clang 8.0.0

Classes | Functions
Physical source locations
libclang: C Interface to Clang

Clang represents physical source locations in its abstract syntax tree in great detail, with file, line, and column information for the majority of the tokens parsed in the source code. More...

Collaboration diagram for Physical source locations:

## Classes
struct | CXSourceLocation
| Identifies a specific source location within a translation unit. More...
struct | CXSourceRange
| Identifies a half-open character range in the source code. More...
struct | CXSourceRangeList
| Identifies an array of ranges. More...

## Functions
CINDEX_LINKAGE CXSourceLocation | clang_getNullLocation (void)
| Retrieve a NULL (invalid) source location. More...
CINDEX_LINKAGE unsigned | clang_equalLocations (CXSourceLocation loc1, CXSourceLocation loc2)
| Determine whether two source locations, which must refer into the same translation unit, refer to exactly the same point in the source code. More...
CINDEX_LINKAGE CXSourceLocation | clang_getLocation (CXTranslationUnit tu, CXFile file, unsigned line, unsigned column)
| Retrieves the source location associated with a given file/line/column in a particular translation unit. More...
CINDEX_LINKAGE CXSourceLocation | clang_getLocationForOffset (CXTranslationUnit tu, CXFile file, unsigned offset)
| Retrieves the source location associated with a given character offset in a particular translation unit. More...
CINDEX_LINKAGE int | clang_Location_isInSystemHeader (CXSourceLocation location)
| Returns non-zero if the given source location is in a system header. More...
CINDEX_LINKAGE int | clang_Location_isFromMainFile (CXSourceLocation location)
| Returns non-zero if the given source location is in the main file of the corresponding translation unit. More...
CINDEX_LINKAGE CXSourceRange | clang_getNullRange (void)
| Retrieve a NULL (invalid) source range. More...
CINDEX_LINKAGE CXSourceRange | clang_getRange (CXSourceLocation begin, CXSourceLocation end)
| Retrieve a source range given the beginning and ending source locations. More...
CINDEX_LINKAGE unsigned | clang_equalRanges (CXSourceRange range1, CXSourceRange range2)
| Determine whether two ranges are equivalent. More...
CINDEX_LINKAGE int | clang_Range_isNull (CXSourceRange range)
| Returns non-zero if `range` is null. More...
CINDEX_LINKAGE void | clang_getExpansionLocation (CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset)
| Retrieve the file, line, column, and offset represented by the given source location. More...
CINDEX_LINKAGE void | clang_getPresumedLocation (CXSourceLocation location, CXString *filename, unsigned *line, unsigned *column)
| Retrieve the file, line and column represented by the given source location, as specified in a # line directive. More...
CINDEX_LINKAGE void | clang_getInstantiationLocation (CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset)
| Legacy API to retrieve the file, line, column, and offset represented by the given source location. More...
CINDEX_LINKAGE void | clang_getSpellingLocation (CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset)
| Retrieve the file, line, column, and offset represented by the given source location. More...
CINDEX_LINKAGE void | clang_getFileLocation (CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset)
| Retrieve the file, line, column, and offset represented by the given source location. More...
CINDEX_LINKAGE CXSourceLocation | clang_getRangeStart (CXSourceRange range)
| Retrieve a source location representing the first character within a source range. More...
CINDEX_LINKAGE CXSourceLocation | clang_getRangeEnd (CXSourceRange range)
| Retrieve a source location representing the last character within a source range. More...
CINDEX_LINKAGE CXSourceRangeList * | clang_getSkippedRanges (CXTranslationUnit tu, CXFile file)
| Retrieve all ranges that were skipped by the preprocessor. More...
CINDEX_LINKAGE CXSourceRangeList * | clang_getAllSkippedRanges (CXTranslationUnit tu)
| Retrieve all ranges from all files that were skipped by the preprocessor. More...
CINDEX_LINKAGE void | clang_disposeSourceRangeList (CXSourceRangeList *ranges)
| Destroy the given `CXSourceRangeList`. More...

## Detailed Description

Clang represents physical source locations in its abstract syntax tree in great detail, with file, line, and column information for the majority of the tokens parsed in the source code.

These data types and functions are used to represent source location information, either for a particular point in the program or for a range of points in the program, and extract specific location information from those data types.

## Function Documentation

## ◆ clang_disposeSourceRangeList()

CINDEX_LINKAGE void clang_disposeSourceRangeList | ( | CXSourceRangeList * | ranges | ) |

Destroy the given `CXSourceRangeList`.

## ◆ clang_equalLocations()

CINDEX_LINKAGE unsigned clang_equalLocations | ( | CXSourceLocation | loc1,
|  | CXSourceLocation | loc2
| ) |  |

Determine whether two source locations, which must refer into the same translation unit, refer to exactly the same point in the source code.

Returns
  non-zero if the source locations refer to the same location, zero if they refer to different locations.

## ◆ clang_equalRanges()

CINDEX_LINKAGE unsigned clang_equalRanges | ( | CXSourceRange | range1,
|  | CXSourceRange | range2
| ) |  |

Determine whether two ranges are equivalent.

Returns
  non-zero if the ranges are the same, zero if they differ.

## ◆ clang_getAllSkippedRanges()

CINDEX_LINKAGE CXSourceRangeList* clang_getAllSkippedRanges | ( | CXTranslationUnit | tu | ) |

Retrieve all ranges from all files that were skipped by the preprocessor.

The preprocessor will skip lines when they are surrounded by an if/ifdef/ifndef directive whose condition does not evaluate to true.

## ◆ clang_getExpansionLocation()

CINDEX_LINKAGE void clang_getExpansionLocation | ( | CXSourceLocation | location,
|  | CXFile * | file,
|  | unsigned * | line,
|  | unsigned * | column,
|  | unsigned * | offset
| ) |  |

Retrieve the file, line, column, and offset represented by the given source location.

If the location refers into a macro expansion, retrieves the location of the macro expansion.

Parameters

  location | the location within a source file that will be decomposed into its parts.
  file | [out] if non-NULL, will be set to the file to which the given source location points.
  line | [out] if non-NULL, will be set to the line to which the given source location points.
  column | [out] if non-NULL, will be set to the column to which the given source location points.
  offset | [out] if non-NULL, will be set to the offset into the buffer to which the given source location points.

## ◆ clang_getFileLocation()

CINDEX_LINKAGE void clang_getFileLocation | ( | CXSourceLocation | location,
|  | CXFile * | file,
|  | unsigned * | line,
|  | unsigned * | column,
|  | unsigned * | offset
| ) |  |

Retrieve the file, line, column, and offset represented by the given source location.

If the location refers into a macro expansion, return where the macro was expanded or where the macro argument was written, if the location points at a macro argument.

Parameters

  location | the location within a source file that will be decomposed into its parts.
  file | [out] if non-NULL, will be set to the file to which the given source location points.
  line | [out] if non-NULL, will be set to the line to which the given source location points.
  column | [out] if non-NULL, will be set to the column to which the given source location points.
  offset | [out] if non-NULL, will be set to the offset into the buffer to which the given source location points.

## ◆ clang_getInstantiationLocation()

CINDEX_LINKAGE void clang_getInstantiationLocation | ( | CXSourceLocation | location,
|  | CXFile * | file,
|  | unsigned * | line,
|  | unsigned * | column,
|  | unsigned * | offset
| ) |  |

Legacy API to retrieve the file, line, column, and offset represented by the given source location.

This interface has been replaced by the newer interface clang_getExpansionLocation(). See that interface's documentation for details.

## ◆ clang_getLocation()

CINDEX_LINKAGE CXSourceLocation clang_getLocation | ( | CXTranslationUnit | tu,
|  | CXFile | file,
|  | unsigned | line,
|  | unsigned | column
| ) |  |

Retrieves the source location associated with a given file/line/column in a particular translation unit.

## ◆ clang_getLocationForOffset()

CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset | ( | CXTranslationUnit | tu,
|  | CXFile | file,
|  | unsigned | offset
| ) |  |

Retrieves the source location associated with a given character offset in a particular translation unit.

## ◆ clang_getNullLocation()

CINDEX_LINKAGE CXSourceLocation clang_getNullLocation | ( | void |  | ) |

Retrieve a NULL (invalid) source location.

## ◆ clang_getNullRange()

CINDEX_LINKAGE CXSourceRange clang_getNullRange | ( | void |  | ) |

Retrieve a NULL (invalid) source range.

## ◆ clang_getPresumedLocation()

CINDEX_LINKAGE void clang_getPresumedLocation | ( | CXSourceLocation | location,
|  | CXString * | filename,
|  | unsigned * | line,
|  | unsigned * | column
| ) |  |

Retrieve the file, line and column represented by the given source location, as specified in a # line directive.

Example: given the following source code in a file somefile.c

#123 "dummy.c" 1
static int func(void)
{
return 0;
}

the location information returned by this function would be

File: dummy.c Line: 124 Column: 12

whereas clang_getExpansionLocation would have returned

File: somefile.c Line: 3 Column: 12

Parameters

  location | the location within a source file that will be decomposed into its parts.
  filename | [out] if non-NULL, will be set to the filename of the source location. Note that filenames returned will be for "virtual" files, which don't necessarily exist on the machine running clang - e.g. when parsing preprocessed output obtained from a different environment. If a non-NULL value is passed in, remember to dispose of the returned value using `clang_disposeString()` once you've finished with it. For an invalid source location, an empty string is returned.
  line | [out] if non-NULL, will be set to the line number of the source location. For an invalid source location, zero is returned.
  column | [out] if non-NULL, will be set to the column number of the source location. For an invalid source location, zero is returned.

## ◆ clang_getRange()

CINDEX_LINKAGE CXSourceRange clang_getRange | ( | CXSourceLocation | begin,
|  | CXSourceLocation | end
| ) |  |

Retrieve a source range given the beginning and ending source locations.

## ◆ clang_getRangeEnd()

CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd | ( | CXSourceRange | range | ) |

Retrieve a source location representing the last character within a source range.

## ◆ clang_getRangeStart()

CINDEX_LINKAGE CXSourceLocation clang_getRangeStart | ( | CXSourceRange | range | ) |

Retrieve a source location representing the first character within a source range.

## ◆ clang_getSkippedRanges()

CINDEX_LINKAGE CXSourceRangeList* clang_getSkippedRanges | ( | CXTranslationUnit | tu,
|  | CXFile | file
| ) |  |

Retrieve all ranges that were skipped by the preprocessor.

The preprocessor will skip lines when they are surrounded by an if/ifdef/ifndef directive whose condition does not evaluate to true.

## ◆ clang_getSpellingLocation()

CINDEX_LINKAGE void clang_getSpellingLocation | ( | CXSourceLocation | location,
|  | CXFile * | file,
|  | unsigned * | line,
|  | unsigned * | column,
|  | unsigned * | offset
| ) |  |

Retrieve the file, line, column, and offset represented by the given source location.

If the location refers into a macro instantiation, return where the location was originally spelled in the source file.

Parameters

  location | the location within a source file that will be decomposed into its parts.
  file | [out] if non-NULL, will be set to the file to which the given source location points.
  line | [out] if non-NULL, will be set to the line to which the given source location points.
  column | [out] if non-NULL, will be set to the column to which the given source location points.
  offset | [out] if non-NULL, will be set to the offset into the buffer to which the given source location points.

## ◆ clang_Location_isFromMainFile()

CINDEX_LINKAGE int clang_Location_isFromMainFile | ( | CXSourceLocation | location | ) |

Returns non-zero if the given source location is in the main file of the corresponding translation unit.

## ◆ clang_Location_isInSystemHeader()

CINDEX_LINKAGE int clang_Location_isInSystemHeader | ( | CXSourceLocation | location | ) |

Returns non-zero if the given source location is in a system header.

## ◆ clang_Range_isNull()

CINDEX_LINKAGE int clang_Range_isNull | ( | CXSourceRange | range | ) |

Returns non-zero if `range` is null.