org.eclipse.cdt.core.index

## Interface IIndex

    public interface IIndex

Interface for accessing the index for one or more projects.

Since:
  4.0
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

### Field Summary

Fields
`static int` `DEPTH_INFINITE` Constant to specify infinite depth.
`static int` `DEPTH_ZERO` Constant to find direct includes, only.
`static int` `FIND_ALL_OCCURRENCES` Constant to search for all occurrences of a binding.
`static int` `FIND_DECLARATIONS` Constant to search for declarations.
`static int` `FIND_DECLARATIONS_DEFINITIONS` Constant to search for all declarations including definitions.
`static int` `FIND_DEFINITIONS` Constant to search for definitions.
`static int` `FIND_POTENTIAL_MATCHES` Constant to include potential matches in the results of a search.
`static int` `FIND_REFERENCES` Constant to search for references.
`static int` `SEARCH_ACROSS_LANGUAGE_BOUNDARIES` Constant to search for occurrences across language boundaries.

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`void` `acquireReadLock()` Before making calls to an index you have to obtain a lock.
`IIndexBinding` `adaptBinding(IBinding binding)` Returns an `IIndexBinding` for this index that is equivalent to the specified binding, or null if such a binding does not exist in this index.
`IIndexFileSet` `createFileSet()` Creates a file-set that can be used with this index as long as the caller holds a read-lock.
`IIndexBinding` `findBinding(IName name)` Searches for the binding of a name.
`IIndexBinding[]` `findBindings(char[][] names, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all bindings in global scope with a given name.
`IIndexBinding[]` `findBindings(char[] name, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches the global scope and optionally all other scopes for bindings with a given name.
`IIndexBinding[]` `findBindings(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches the global scope for all bindings with a given name.
`IIndexBinding[]` `findBindings(Pattern[] patterns, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all bindings with qualified names that seen as an array of simple names match the given array of patterns.
`IIndexBinding[]` `findBindings(Pattern pattern, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all bindings with simple names that match the given pattern.
`IIndexBinding[]` `findBindingsForContentAssist(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)`
`IIndexBinding[]` `findBindingsForPrefix(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all bindings with names that start with the given prefix.
`IIndexName[]` `findDeclarations(IBinding binding)` Searches for all declarations and definitions that resolve to the given binding.
`IIndexName[]` `findDefinitions(IBinding binding)` Searches for all definitions that resolve to the given binding.
`IIndexInclude[]` `findIncludedBy(IIndexFile file)` Looks for include relations pointing to the given file.
`IIndexInclude[]` `findIncludedBy(IIndexFile file, int depth)` Looks recursively for include relations pointing to the given file.
`IIndexInclude[]` `findIncludes(IIndexFile file)` Looks for include relations originated by the given file.
`IIndexInclude[]` `findIncludes(IIndexFile file, int depth)` Looks recursively for include relations originated by the given file.
`IIndexBinding[]` `findMacroContainers(Pattern pattern, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all macro containers (one for macros with the same name) with names that match the given pattern.
`IIndexMacro[]` `findMacros(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all macros with a given name.
`IIndexMacro[]` `findMacrosForPrefix(char[] prefix, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)` Searches for all macros with names that start with the given prefix.
`IIndexName[]` `findNames(IBinding binding, int flags)` Searches for all names that resolve to the given binding.
`IIndexName[]` `findReferences(IBinding binding)` Searches for all references that resolve to the given binding.
`IIndexFile[]` `getAllFiles()` Returns an array of all files that are part of this index.
`IIndexFile[]` `getDefectiveFiles()` Returns an array of files that were indexed with I/O errors.
`IIndexFile` `getFile(int linkageID, IIndexFileLocation location)` Deprecated. Use `getFile(int, IIndexFileLocation, ISignificantMacros)` or `getFiles(int, IIndexFileLocation)`.
`IIndexFile` `getFile(int linkageID, IIndexFileLocation location, ISignificantMacros significantMacros)` Returns the file for the given location, linkage, and significant macros May return `null`, if no such file exists.
`IIndexFile[]` `getFiles(IIndexFileLocation location)` Returns the file objects for the given location in any linkage.
`IIndexFile[]` `getFiles(int linkageID, IIndexFileLocation location)` Returns the file objects for the given location and linkage.
`IIndexFile[]` `getFilesWithUnresolvedIncludes()` Returns an array of files containing unresolved includes.
`IScope[]` `getInlineNamespaces()` Returns the global inline c++ namespaces.
`long` `getLastWriteAccess()` Returns a timestamp of when the index was last written to.
`boolean` `hasWaitingReaders()`
`boolean` `isFullyInitialized()` Returns `true` if the index is fully initialized.
`void` `releaseReadLock()` Any lock obtained by `acquireReadLock()` must be released.
`IIndexFile` `resolveInclude(IIndexInclude include)` Resolves the file that is included by the given include directive.

### Field Detail

#### DEPTH_INFINITE

    static final int DEPTH_INFINITE

Constant to specify infinite depth.

See Also:
  `findIncludedBy(IIndexFile, int)`, `findIncludes(IIndexFile, int)`, Constant Field Values

#### DEPTH_ZERO

    static final int DEPTH_ZERO

Constant to find direct includes, only.

See Also:
  `findIncludedBy(IIndexFile, int)`, `findIncludes(IIndexFile, int)`, Constant Field Values

#### FIND_DECLARATIONS

    static final int FIND_DECLARATIONS

Constant to search for declarations. This does not include definitions.

See Also:
  Constant Field Values

#### FIND_DEFINITIONS

    static final int FIND_DEFINITIONS

Constant to search for definitions. This does not include declarations.

See Also:
  Constant Field Values

#### FIND_REFERENCES

    static final int FIND_REFERENCES

Constant to search for references. This does not include declarations or definitions.

See Also:
  Constant Field Values

#### SEARCH_ACROSS_LANGUAGE_BOUNDARIES

    static final int SEARCH_ACROSS_LANGUAGE_BOUNDARIES

Constant to search for occurrences across language boundaries. Can be used to find the occurrences of a C++-function declared with 'extern "C"' within the c-linkage.

See Also:
  Constant Field Values

#### FIND_POTENTIAL_MATCHES

    static final int FIND_POTENTIAL_MATCHES

Constant to include potential matches in the results of a search. An example of a potential match might be a function definition that does match a declaration exactly in signature.

Since:
  6.5
See Also:
  Constant Field Values

#### FIND_DECLARATIONS_DEFINITIONS

    static final int FIND_DECLARATIONS_DEFINITIONS

Constant to search for all declarations including definitions.

See Also:
  Constant Field Values

#### FIND_ALL_OCCURRENCES

    static final int FIND_ALL_OCCURRENCES

Constant to search for all occurrences of a binding. This includes declarations, definitions and references.

See Also:
  Constant Field Values

### Method Detail

#### acquireReadLock

    void acquireReadLock()
                  throws InterruptedException

Before making calls to an index you have to obtain a lock. The objects returned by an index become invalid as soon as the indexer writes to the index. You may obtain nested read locks. Make sure you release the lock.

Throws:
  `InterruptedException`
See Also:
  `

       index.acquireReadLock();
       try {
          ....
       } finally {
          index.releaseReadLock();
       }

  `

#### releaseReadLock

    void releaseReadLock()

Any lock obtained by `acquireReadLock()` must be released.

#### hasWaitingReaders

    boolean hasWaitingReaders()

Returns:
  `true` if there are threads waiting for read locks.
Since:
  5.2

#### getLastWriteAccess

    long getLastWriteAccess()

Returns a timestamp of when the index was last written to. This can be used to figure out whether information read from the index is still reliable or not.

     long timestamp;
     IBinding binding= null;
     index.acquireReadLock();
     try {
        timestamp= index.getLastWriteAccess();
        binding= index.findBinding(...);
     } finally {
        index.releaseReadLock();
     }
     ...
     index.acqureReadLock();
     try {
        if (index.getLastWriteAccess() != timestamp) {
           // don't use binding, it's not valid anymore
           binding= index.findBinding(...);
        }
        String name= binding.getName();
        ...
     } finally {
        index.releaseReadLock();
     }

#### getFile

    @Deprecated
    IIndexFile getFile(int linkageID,
                                   IIndexFileLocation location)
                            throws org.eclipse.core.runtime.CoreException

Deprecated. Use `getFile(int, IIndexFileLocation, ISignificantMacros)` or `getFiles(int, IIndexFileLocation)`.

Throws:
  `org.eclipse.core.runtime.CoreException`
Restriction:
  This method is not intended to be referenced by clients.

#### getFile

    IIndexFile getFile(int linkageID,
                       IIndexFileLocation location,
                       ISignificantMacros significantMacros)
                throws org.eclipse.core.runtime.CoreException

Returns the file for the given location, linkage, and significant macros May return `null`, if no such file exists.

Parameters:
  `linkageID` - the id of the linkage in which the file has been parsed.
  `location` - the IIndexFileLocation representing the location of the file
  `significantMacros` - The names and definitions of the macros used to disambiguate between variants of the file contents corresponding to different inclusion points.
Returns:
  the file for the location, or `null` if the file is not present in the index
Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  5.4

#### getFiles

    IIndexFile[] getFiles(int linkageID,
                          IIndexFileLocation location)
                   throws org.eclipse.core.runtime.CoreException

Returns the file objects for the given location and linkage. Multiple files are returned when a header file is stored in the index in multiple variants for different sets of macro definitions. This method may only return files that are actually managed by this fragment. This method returns files without content, also.

Parameters:
  `linkageID` - the id of the linkage in which the file has been parsed.
  `location` - the IIndexFileLocation representing the location of the file
Returns:
  the files for the location and the linkage.
Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  5.4

#### getFiles

    IIndexFile[] getFiles(IIndexFileLocation location)
                   throws org.eclipse.core.runtime.CoreException

Returns the file objects for the given location in any linkage.

Parameters:
  `location` - an IIndexFileLocation representing the location of the file
Returns:
  an array of file-objects.
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findIncludes

    IIndexInclude[] findIncludes(IIndexFile file)
                          throws org.eclipse.core.runtime.CoreException

Looks for include relations originated by the given file. This is the same as

     findIncludes(file, DEPTH_ZERO);

Parameters:
  `file` - the file containing the include directives
Returns:
  an array of include relations
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findIncludedBy

    IIndexInclude[] findIncludedBy(IIndexFile file)
                            throws org.eclipse.core.runtime.CoreException

Looks for include relations pointing to the given file. This is the same as

     findIncludedBy(file, DEPTH_ZERO);

Parameters:
  `file` - the file included by the directives to be found
Returns:
  an array of include relations
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findIncludes

    IIndexInclude[] findIncludes(IIndexFile file,
                                 int depth)
                          throws org.eclipse.core.runtime.CoreException

Looks recursively for include relations originated by the given file.

Parameters:
  `file` - the file containing the include directives
  `depth` - depth to which includes are followed, should be one of `DEPTH_ZERO` or `DEPTH_INFINITE`
Returns:
  an array of include relations
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findIncludedBy

    IIndexInclude[] findIncludedBy(IIndexFile file,
                                   int depth)
                            throws org.eclipse.core.runtime.CoreException

Looks recursively for include relations pointing to the given file.

Parameters:
  `file` - the file the include directives point to
  `depth` - depth to which includes are followed, should be one of `DEPTH_ZERO` or `DEPTH_INFINITE`
Returns:
  an array of include relations
Throws:
  `org.eclipse.core.runtime.CoreException`

#### resolveInclude

    IIndexFile resolveInclude(IIndexInclude include)
                       throws org.eclipse.core.runtime.CoreException

Resolves the file that is included by the given include directive. May return `null` in case the file cannot be found. This is usually more efficient than using:

     getFiles(include.getIncludesLocation())

Parameters:
  `include` -
Returns:
  the file included or `null`.
Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  4.0

#### findMacros

    IIndexMacro[] findMacros(char[] name,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches for all macros with a given name.

Parameters:
  `name` - a name, that has to be matched by the macros.
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of macros matching the name.
Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  4.0.2

#### findMacrosForPrefix

    IIndexMacro[] findMacrosForPrefix(char[] prefix,
                                      IndexFilter filter,
                                      org.eclipse.core.runtime.IProgressMonitor monitor)
                               throws org.eclipse.core.runtime.CoreException

Searches for all macros with names that start with the given prefix.

Parameters:
  `prefix` - the prefix with which all returned macros must start
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor for progress reporting and cancellation, may be `null`
Returns:
  an array of bindings with the prefix
Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  4.0.2

#### findBinding

    IIndexBinding findBinding(IName name)
                       throws org.eclipse.core.runtime.CoreException

Searches for the binding of a name. The name may be originated by an AST or by a search in an index. May return `null`.

Parameters:
  `name` - a name to find the binding for
Returns:
  the binding or `null`
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindings

    IIndexBinding[] findBindings(Pattern pattern,
                                 boolean isFullyQualified,
                                 IndexFilter filter,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

Searches for all bindings with simple names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned. This is fully equivalent to

     findBindings(new Pattern[] {pattern}, isFullyQualified, filter, monitor);

Parameters:
  `pattern` - the pattern the name of the binding has to match.
  `isFullyQualified` - if `true`, binding must be in global scope
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindings

    IIndexBinding[] findBindings(Pattern[] patterns,
                                 boolean isFullyQualified,
                                 IndexFilter filter,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

Searches for all bindings with qualified names that seen as an array of simple names match the given array of patterns. In case a binding exists in multiple projects, no duplicate bindings are returned. You can search with an array of patterns that specifies a partial qualification only.

Parameters:
  `patterns` - an array of patterns the components of the qualified name of the bindings have to match.
  `isFullyQualified` - if `true`, the array of pattern specifies the fully qualified name
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findMacroContainers

    IIndexBinding[] findMacroContainers(Pattern pattern,
                                        IndexFilter filter,
                                        org.eclipse.core.runtime.IProgressMonitor monitor)
                                 throws org.eclipse.core.runtime.CoreException

Searches for all macro containers (one for macros with the same name) with names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned.

Parameters:
  `pattern` - a pattern the name of the bindings have to match.
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindings

    IIndexBinding[] findBindings(char[][] names,
                                 IndexFilter filter,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

Searches for all bindings in global scope with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.

Parameters:
  `names` - an array of names, which has to be matched by the qualified name of the bindings.
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindings

    IIndexBinding[] findBindings(char[] name,
                                 IndexFilter filter,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

Searches the global scope for all bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns. This is fully equivalent to

     findBindings(name, true, filter, monitor);

Parameters:
  `name` - a name, which has to be matched by the qualified name of the bindings.
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindings

    IIndexBinding[] findBindings(char[] name,
                                 boolean fileScopeOnly,
                                 IndexFilter filter,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

Searches the global scope and optionally all other scopes for bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.

Parameters:
  `name` - a name, which has to be matched by the qualified name of the bindings.
  `fileScopeOnly` - if true, only bindings at file scope are returned
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor to report progress, may be `null`.
Returns:
  an array of bindings matching the pattern
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindingsForPrefix

    IIndexBinding[] findBindingsForPrefix(char[] prefix,
                                          boolean fileScopeOnly,
                                          IndexFilter filter,
                                          org.eclipse.core.runtime.IProgressMonitor monitor)
                                   throws org.eclipse.core.runtime.CoreException

Searches for all bindings with names that start with the given prefix.

Parameters:
  `prefix` - the prefix with which all returned bindings must start
  `fileScopeOnly` - if true, only bindings at file scope are returned
  `filter` - a filter that allows for skipping parts of the index
  `monitor` - a monitor for progress reporting and cancellation, may be `null`
Returns:
  an array of bindings with the prefix
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findBindingsForContentAssist

    IIndexBinding[] findBindingsForContentAssist(char[] prefix,
                                                 boolean fileScopeOnly,
                                                 IndexFilter filter,
                                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                                          throws org.eclipse.core.runtime.CoreException

Throws:
  `org.eclipse.core.runtime.CoreException`
Restriction:
  This method is not intended to be referenced by clients.

#### findNames

    IIndexName[] findNames(IBinding binding,
                           int flags)
                    throws org.eclipse.core.runtime.CoreException

Searches for all names that resolve to the given binding. The search can be limited to references, declarations or definitions, or a combination of those.

Parameters:
  `binding` - a binding for which names are searched for
  `flags` - a combination of `FIND_DECLARATIONS`, `FIND_DEFINITIONS`, `FIND_REFERENCES`, `SEARCH_ACROSS_LANGUAGE_BOUNDARIES`, and `FIND_POTENTIAL_MATCHES`.
Returns:
  an array of names
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findReferences

    IIndexName[] findReferences(IBinding binding)
                         throws org.eclipse.core.runtime.CoreException

Searches for all references that resolve to the given binding. This is fully equivalent to

     findNames(binding, IIndex.FIND_REFERENCES);

Parameters:
  `binding` - a binding for which references are searched for
Returns:
  an array of names
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findDeclarations

    IIndexName[] findDeclarations(IBinding binding)
                           throws org.eclipse.core.runtime.CoreException

Searches for all declarations and definitions that resolve to the given binding. This is fully equivalent to

     findNames(binding, IIndex.FIND_DECLARATIONS_DEFINITIONS);

Parameters:
  `binding` - a binding for which declarations are searched for
Returns:
  an array of names
Throws:
  `org.eclipse.core.runtime.CoreException`

#### findDefinitions

    IIndexName[] findDefinitions(IBinding binding)
                          throws org.eclipse.core.runtime.CoreException

Searches for all definitions that resolve to the given binding. This is fully equivalent to

     findNames(binding, IIndex.FIND_DEFINITIONS);

Parameters:
  `binding` - a binding for which declarations are searched for
Returns:
  an array of names
Throws:
  `org.eclipse.core.runtime.CoreException`

#### adaptBinding

    IIndexBinding adaptBinding(IBinding binding)

Returns an `IIndexBinding` for this index that is equivalent to the specified binding, or null if such a binding does not exist in this index. This is useful for adapting bindings obtained from IIndex objects that might have been created for a different scope or for IBinding objects obtained directly from the AST.

Parameters:
  `binding` - an AST or an index binding
Returns:
  an IIndexBinding for this index that is equivalent to the specified binding

#### createFileSet

    IIndexFileSet createFileSet()

Creates a file-set that can be used with this index as long as the caller holds a read-lock.

#### getAllFiles

    IIndexFile[] getAllFiles()
                      throws org.eclipse.core.runtime.CoreException

Returns an array of all files that are part of this index. If a file is parsed in two linkages or in multiple fragments, only one of the files will be returned.

Throws:
  `org.eclipse.core.runtime.CoreException`

#### getDefectiveFiles

    IIndexFile[] getDefectiveFiles()
                            throws org.eclipse.core.runtime.CoreException

Returns an array of files that were indexed with I/O errors.

Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  5.4
Restriction:
  This method is not intended to be referenced by clients.

#### getFilesWithUnresolvedIncludes

    IIndexFile[] getFilesWithUnresolvedIncludes()
                                         throws org.eclipse.core.runtime.CoreException

Returns an array of files containing unresolved includes.

Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  5.4
Restriction:
  This method is not intended to be referenced by clients.

#### getInlineNamespaces

    IScope[] getInlineNamespaces()
                          throws org.eclipse.core.runtime.CoreException

Returns the global inline c++ namespaces.

Throws:
  `org.eclipse.core.runtime.CoreException`
Since:
  5.3

#### isFullyInitialized

    boolean isFullyInitialized()

Returns `true` if the index is fully initialized. An index may not be fully initialized during Eclipse startup, or soon after adding a new project to the workspace.

Since:
  5.4