org.eclipse.cdt.core.dom.ast

## Interface IASTTranslationUnit

All Superinterfaces:
  IASTDeclarationListOwner, IASTNode, IFileNomination

All Known Subinterfaces:
  ICPPASTTranslationUnit

    public interface IASTTranslationUnit
    extends IASTDeclarationListOwner, IFileNomination

The translation unit represents a compilable unit of source. All existing implementations of IASTTranslationUnit are not thread safe. Even 'get' methods may cause changes to the underlying object.

### Nested Class Summary

Nested Classes
`static interface` `IASTTranslationUnit.IDependencyTree`

### Nested classes/interfaces inherited from interface org.eclipse.cdt.core.dom.ast.IASTNode

`IASTNode.CopyStyle`

### Field Summary

Fields
`static ASTNodeProperty` `EXPANSION_NAME` Deprecated. names for macro expansions are nested inside of `IASTPreprocessorMacroExpansion`.
`static ASTNodeProperty` `MACRO_EXPANSION`
`static ASTNodeProperty` `OWNED_DECLARATION` `OWNED_DECLARATION` represents the relationship between an `IASTTranslationUnit` and its nested `IASTDeclaration`'s.
`static ASTNodeProperty` `PREPROCESSOR_STATEMENT` `PREPROCESSOR_STATEMENT` represents the relationship between an `IASTTranslationUnit` and its nested `IASTPreprocessorStatement`.
`static ASTNodeProperty` `SCANNER_PROBLEM` `SCANNER_PROBLEM` represents the relationship between an `IASTTranslationUnit` and its nested `IASTProblem`.

### Fields inherited from interface org.eclipse.cdt.core.dom.ast.IASTNode

`EMPTY_NODE_ARRAY`

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`void` `addDeclaration(IASTDeclaration declaration)` Adds declaration to translation unit.
`IASTTranslationUnit` `copy()` Returns a copy of the AST, however the ILocationResolver and the preprocessor nodes are not copied.
`IASTTranslationUnit` `copy(IASTNode.CopyStyle style)` Returns a copy of the AST, however the ILocationResolver and the preprocessor nodes are not copied.
`IASTFileLocation` `flattenLocationsToFile(IASTNodeLocation[] nodeLocations)` Flattens the node locations provided into a single file location.
`void` `freeze()` Causes this node and all the nodes rooted at this node to become immutable.
`IASTPreprocessorStatement[]` `getAllPreprocessorStatements()` Returns all preprocessor statements.
`org.eclipse.cdt.core.index.IIndexFileSet` `getASTFileSet()` Returns the set of files in the index that are superseded by this AST, or `null` if not available.
`INodeFactory` `getASTNodeFactory()` Returns the node factory that was used to build the AST.
`IASTPreprocessorMacroDefinition[]` `getBuiltinMacroDefinitions()` Returns built-in macro definitions used when parsing this translation unit.
`IASTComment[]` `getComments()` In case the AST was created in a way that supports comment parsing, all comments of the translation unit are returned.
`java.lang.String` `getContainingFilename(int offset)`
`IASTDeclaration[]` `getDeclarations()` A translation unit contains an ordered sequence of declarations.
`org.eclipse.cdt.core.dom.IName[]` `getDeclarations(IBinding binding)` Returns the list of declarations in this translation unit for the given binding.
`IASTName[]` `getDeclarationsInAST(IBinding binding)` Returns the list of declarations in this translation unit for the given binding.
`org.eclipse.cdt.core.dom.IName[]` `getDefinitions(IBinding binding)` Returns the array of definitions in this translation unit for the given binding.
`IASTName[]` `getDefinitionsInAST(IBinding binding)` Equivalent to getDefinitionsInAst(binding, false).
`IASTName[]` `getDefinitionsInAST(IBinding binding, boolean permissive)` Returns the array of definitions in this translation unit for the given binding.
`IASTTranslationUnit.IDependencyTree` `getDependencyTree()` Returns the dependency tree for the translation unit.
`java.lang.String` `getFilePath()` Returns the location of the root file of this translation unit.
`IASTPreprocessorIncludeStatement[]` `getIncludeDirectives()` Returns the include directives encountered in parsing this translation unit.
`org.eclipse.cdt.core.index.IIndex` `getIndex()` Returns the Index associated with this translation unit.
`org.eclipse.cdt.core.index.IIndexFileSet` `getIndexFileSet()` Returns the set of files that have been skipped because they have been part of the index prior to creating this AST, or `null` if not available.
`org.eclipse.cdt.core.dom.ILinkage` `getLinkage()` Returns the linkage this AST was parsed in.
`IASTPreprocessorMacroDefinition[]` `getMacroDefinitions()` Returns the macro definitions encountered in parsing this translation unit.
`IASTPreprocessorMacroExpansion[]` `getMacroExpansions()` Returns an array with all macro expansions of this translation unit.
`IASTNodeSelector` `getNodeSelector(java.lang.String filePath)` Returns an IASTNodeSelector object for finding nodes by file offsets.
`ITranslationUnit` `getOriginatingTranslationUnit()` Returns the ITranslationUnit this AST originated from, or `null` if the AST does not correspond to an ITranslationUnit.
`org.eclipse.cdt.core.parser.ParserLanguage` `getParserLanguage()` Deprecated. Use `getLinkage()` instead
`IASTProblem[]` `getPreprocessorProblems()` Returns all preprocessor and scanner problems.
`int` `getPreprocessorProblemsCount()` Fast access to the count of preprocessor problems to support statistics.
`IASTName[]` `getReferences(IBinding binding)` Returns the list of references in this translation unit to the given binding.
`IScope` `getScope()` This returns the global scope for the translation unit.
`boolean` `hasNodesOmitted()` Returns `true` if the parser has skipped any nodes while creating the AST.
`boolean` `isBasedOnIncompleteIndex()` Returns `true` if the index was not fully initialized when the code of the translation unit was parsed.
`boolean` `isHeaderUnit()` Returns whether this AST represents a header file.
`IASTNode` `selectNodeForLocation(java.lang.String path, int offset, int length)` Deprecated. use `getNodeSelector(String)`, instead.
`void` `setHasNodesOmitted(boolean nodesOmitted)` Sets whether the parser has skipped any nodes while creating the AST for the translation unit.
`void` `setIndex(org.eclipse.cdt.core.index.IIndex index)` Sets the Index to be used for this translation unit.
`void` `setIsHeaderUnit(boolean headerUnit)` Sets whether this AST represents a header file.
`void` `setPragmaOnceSemantics(boolean value)`
`void` `setSignificantMacros(org.eclipse.cdt.core.parser.ISignificantMacros sigMacros)`

### Methods inherited from interface org.eclipse.cdt.core.dom.ast.IASTDeclarationListOwner

`getDeclarations`

### Methods inherited from interface org.eclipse.cdt.core.dom.ast.IASTNode

`accept, contains, getChildren, getContainingFilename, getFileLocation, getLeadingSyntax, getNodeLocations, getOriginalNode, getParent, getPropertyInParent, getRawSignature, getSyntax, getTrailingSyntax, getTranslationUnit, isActive, isFrozen, isPartOfTranslationUnitFile, setParent, setPropertyInParent`

### Methods inherited from interface org.eclipse.cdt.core.dom.ast.IFileNomination

`getSignificantMacros, hasPragmaOnceSemantics`

### Field Detail

#### OWNED_DECLARATION

    static final ASTNodeProperty OWNED_DECLARATION

`OWNED_DECLARATION` represents the relationship between an `IASTTranslationUnit` and its nested `IASTDeclaration`'s.

#### SCANNER_PROBLEM

    static final ASTNodeProperty SCANNER_PROBLEM

`SCANNER_PROBLEM` represents the relationship between an `IASTTranslationUnit` and its nested `IASTProblem`.

#### PREPROCESSOR_STATEMENT

    static final ASTNodeProperty PREPROCESSOR_STATEMENT

`PREPROCESSOR_STATEMENT` represents the relationship between an `IASTTranslationUnit` and its nested `IASTPreprocessorStatement`.

#### MACRO_EXPANSION

    static final ASTNodeProperty MACRO_EXPANSION

#### EXPANSION_NAME

    @Deprecated
    static final ASTNodeProperty EXPANSION_NAME

Deprecated. names for macro expansions are nested inside of `IASTPreprocessorMacroExpansion`.

### Method Detail

#### getDeclarations

    IASTDeclaration[] getDeclarations()

A translation unit contains an ordered sequence of declarations.

Returns:
  List of IASTDeclaration

#### addDeclaration

    void addDeclaration(IASTDeclaration declaration)

Adds declaration to translation unit.

Specified by:
  `addDeclaration` in interface `IASTDeclarationListOwner`
Parameters:
  `declaration` - `IASTDeclaration`

#### getScope

    IScope getScope()

This returns the global scope for the translation unit.

Returns:
  the global scope

#### getDeclarations

    org.eclipse.cdt.core.dom.IName[] getDeclarations(IBinding binding)

Returns the list of declarations in this translation unit for the given binding. The list contains the IName nodes that declare the binding. These may be part of the AST or are pulled in from the index.

Parameters:
  `binding` -
Returns:
  Array of IName nodes for the binding's declaration

#### getDeclarationsInAST

    IASTName[] getDeclarationsInAST(IBinding binding)

Returns the list of declarations in this translation unit for the given binding. The list contains the IASTName nodes that declare the binding. These are part of the AST no declarations are pulled in from the index.

Parameters:
  `binding` -
Returns:
  Array of IASTName nodes for the binding's declaration

#### getDefinitions

    org.eclipse.cdt.core.dom.IName[] getDefinitions(IBinding binding)

Returns the array of definitions in this translation unit for the given binding. The array contains the IName nodes that define the binding. These may be part of the AST or are pulled in from the index.

Parameters:
  `binding` -
Returns:
  the definition of the IBinding

#### getDefinitionsInAST

    IASTName[] getDefinitionsInAST(IBinding binding)

Equivalent to getDefinitionsInAst(binding, false).

#### getDefinitionsInAST

    IASTName[] getDefinitionsInAST(IBinding binding,
                                   boolean permissive)

Returns the array of definitions in this translation unit for the given binding. The array contains the IASTName nodes that define the binding. These are part of the AST, no definitions are pulled in from the index. If 'permissive' is true, definitions that are not exact matches (for example, a method definition with a non-matching signature) are also returned.

Parameters:
  `binding` -
  `permissive` -
Returns:
  Array of IASTName nodes for the binding's declaration
Since:
  6.5

#### getReferences

    IASTName[] getReferences(IBinding binding)

Returns the list of references in this translation unit to the given binding. This list contains the IASTName nodes that represent a use of the binding. These are part of the AST, no definitions are pulled in from the index.

Parameters:
  `binding` -
Returns:
  List of IASTName nodes representing uses of the binding

#### getNodeSelector

    IASTNodeSelector getNodeSelector(java.lang.String filePath)

Returns an IASTNodeSelector object for finding nodes by file offsets. The object is suitable for working in one of the files that is part of the translation unit.

Parameters:
  `filePath` - file of interest, as returned by `IASTFileLocation.getFileName()`, or `null` to specify the root source of the translation-unit.
Returns:
  an IASTNodeSelector.
Since:
  5.0

#### selectNodeForLocation

    @Deprecated
    IASTNode selectNodeForLocation(java.lang.String path,
                                               int offset,
                                               int length)

Deprecated. use `getNodeSelector(String)`, instead.

#### getMacroDefinitions

    IASTPreprocessorMacroDefinition[] getMacroDefinitions()

Returns the macro definitions encountered in parsing this translation unit. The result will not contain definitions for built-in macros.

In case the information for a header-file is pulled in from the index, macro definitions contained therein are not returned.

#### getBuiltinMacroDefinitions

    IASTPreprocessorMacroDefinition[] getBuiltinMacroDefinitions()

Returns built-in macro definitions used when parsing this translation unit. This includes macros obtained from the index.

#### getIncludeDirectives

    IASTPreprocessorIncludeStatement[] getIncludeDirectives()

Returns the include directives encountered in parsing this translation unit. This will also contain directives used for handling the gcc-options -imacros and -include.

In case the information for a header-file is pulled in from the index, include directives contained therein are not returned.

#### getAllPreprocessorStatements

    IASTPreprocessorStatement[] getAllPreprocessorStatements()

Returns all preprocessor statements. In case the information for a header-file is pulled in from the index, preprocessing statements contained therein are not returned.

#### getMacroExpansions

    IASTPreprocessorMacroExpansion[] getMacroExpansions()

Returns an array with all macro expansions of this translation unit.

#### getPreprocessorProblems

    IASTProblem[] getPreprocessorProblems()

Returns all preprocessor and scanner problems.

Returns:
  `IASTProblem[]`

#### getPreprocessorProblemsCount

    int getPreprocessorProblemsCount()

Fast access to the count of preprocessor problems to support statistics.

#### getFilePath

    java.lang.String getFilePath()

Returns the location of the root file of this translation unit. This will be the same value as returned by `getFileLocation().getFileName()`

See Also:
  `IASTFileLocation.getFileName()`

#### flattenLocationsToFile

    IASTFileLocation flattenLocationsToFile(IASTNodeLocation[] nodeLocations)

Flattens the node locations provided into a single file location.

Parameters:
  `nodeLocations` - `IASTNodeLocation`s to flatten
Returns:
  null if not possible, otherwise, a file location representing where the macros are.

#### getDependencyTree

    IASTTranslationUnit.IDependencyTree getDependencyTree()

Returns the dependency tree for the translation unit.

In case the information for a header-file is pulled in from the index, dependencies contained therein are not part of the dependency tree.

#### getContainingFilename

    java.lang.String getContainingFilename(int offset)

Parameters:
  `offset` -

#### getParserLanguage

    @Deprecated
    org.eclipse.cdt.core.parser.ParserLanguage getParserLanguage()

Deprecated. Use `getLinkage()` instead

#### getIndex

    org.eclipse.cdt.core.index.IIndex getIndex()

Returns the Index associated with this translation unit.

Returns:
  the Index for this translation unit.

#### getIndexFileSet

    org.eclipse.cdt.core.index.IIndexFileSet getIndexFileSet()

Returns the set of files that have been skipped because they have been part of the index prior to creating this AST, or `null` if not available. Applies only, if AST was created with an index and the option to skip headers found in the index.

Since:
  5.1

#### getASTFileSet

    org.eclipse.cdt.core.index.IIndexFileSet getASTFileSet()

Returns the set of files in the index that are superseded by this AST, or `null` if not available. Applies only, if AST was created with an index.

Since:
  5.3

#### getComments

    IASTComment[] getComments()

In case the AST was created in a way that supports comment parsing, all comments of the translation unit are returned. Otherwise an empty array will be supplied.

Returns:
  `IASTComment[]`
Since:
  4.0

#### getLinkage

    org.eclipse.cdt.core.dom.ILinkage getLinkage()

Returns the linkage this AST was parsed in.

#### isHeaderUnit

    boolean isHeaderUnit()

Returns whether this AST represents a header file.

#### getASTNodeFactory

    INodeFactory getASTNodeFactory()

Returns the node factory that was used to build the AST.

Since:
  5.2

#### setIndex

    void setIndex(org.eclipse.cdt.core.index.IIndex index)

Sets the Index to be used for this translation unit.

#### setIsHeaderUnit

    void setIsHeaderUnit(boolean headerUnit)

Sets whether this AST represents a header file.

#### freeze

    void freeze()

Causes this node and all the nodes rooted at this node to become immutable. Once the AST is frozen any calls to set or add methods on any of the nodes in the AST will result in an IllegalStateException.

Since:
  5.1

#### copy

    IASTTranslationUnit copy()

Returns a copy of the AST, however the ILocationResolver and the preprocessor nodes are not copied.

Specified by:
  `copy` in interface `IASTNode`
Since:
  5.1
See Also:
  `IASTNode.copy()`

#### copy

    IASTTranslationUnit copy(IASTNode.CopyStyle style)

Returns a copy of the AST, however the ILocationResolver and the preprocessor nodes are not copied.

Specified by:
  `copy` in interface `IASTNode`
Parameters:
  `style` - `IASTNode.CopyStyle` create a copy with or without locations. Please see `IASTNode.CopyStyle` for restrictions on copies with Locations.
Since:
  5.3
See Also:
  `IASTNode.copy()`

#### getOriginatingTranslationUnit

    ITranslationUnit getOriginatingTranslationUnit()

Returns the ITranslationUnit this AST originated from, or `null` if the AST does not correspond to an ITranslationUnit.

Since:
  5.3

#### isBasedOnIncompleteIndex

    boolean isBasedOnIncompleteIndex()

Returns `true` if the index was not fully initialized when the code of the translation unit was parsed.

Since:
  5.4

#### setSignificantMacros

    void setSignificantMacros(org.eclipse.cdt.core.parser.ISignificantMacros sigMacros)

Since:
  5.4

#### setPragmaOnceSemantics

    void setPragmaOnceSemantics(boolean value)

Since:
  5.4

#### hasNodesOmitted

    boolean hasNodesOmitted()

Returns `true` if the parser has skipped any nodes while creating the AST.

Since:
  5.6

#### setHasNodesOmitted

    void setHasNodesOmitted(boolean nodesOmitted)

Sets whether the parser has skipped any nodes while creating the AST for the translation unit.

Since:
  5.6