/*===-- clang-c/CXSourceLocation.h - C Index Source Location ------*- C -*-===*\ |* *| |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| |* Exceptions. *| |* See https://llvm.org/LICENSE.txt for license information. *| |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| |* *| |*===----------------------------------------------------------------------===*| |* *| |* This header provides the interface to C Index source locations. *| |* *| \*===----------------------------------------------------------------------===*/ #ifndef LLVM_CLANG_C_CXSOURCE_LOCATION_H #define LLVM_CLANG_C_CXSOURCE_LOCATION_H #include "clang-c/CXFile.h" #include "clang-c/CXString.h" #include "clang-c/ExternC.h" #include "clang-c/Platform.h" LLVM_CLANG_C_EXTERN_C_BEGIN /** * \defgroup CINDEX_LOCATIONS Physical source locations * * 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. * * @{ */ /** * Identifies a specific source location within a translation * unit. * * Use clang_getExpansionLocation() or clang_getSpellingLocation() * to map a source location to a particular file, line, and column. */ CXSourceLocation; /** * Identifies a half-open character range in the source code. * * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the * starting and end locations from a source range, respectively. */ CXSourceRange; /** * Retrieve a NULL (invalid) source location. */ CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); /** * 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. */ CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, CXSourceLocation loc2); /** * Determine for two source locations if the first comes * strictly before the second one in the source code. * * \returns non-zero if the first source location comes * strictly before the second one, zero otherwise. */ CINDEX_LINKAGE unsigned clang_isBeforeInTranslationUnit(CXSourceLocation loc1, CXSourceLocation loc2); /** * Returns non-zero if the given source location is in a system header. */ CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); /** * Returns non-zero if the given source location is in the main file of * the corresponding translation unit. */ CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); /** * Retrieve a NULL (invalid) source range. */ CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); /** * Retrieve a source range given the beginning and ending source * locations. */ CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, CXSourceLocation end); /** * Determine whether two ranges are equivalent. * * \returns non-zero if the ranges are the same, zero if they differ. */ CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, CXSourceRange range2); /** * Returns non-zero if \p range is null. */ CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); /** * 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. * * \param location the location within a source file that will be decomposed * into its parts. * * \param file [out] if non-NULL, will be set to the file to which the given * source location points. * * \param line [out] if non-NULL, will be set to the line to which the given * source location points. * * \param column [out] if non-NULL, will be set to the column to which the given * source location points. * * \param offset [out] if non-NULL, will be set to the offset into the * buffer to which the given source location points. */ CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset); /** * 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 * * \code * #123 "dummy.c" 1 * * static int func(void) * { * return 0; * } * \endcode * * 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 * * \param location the location within a source file that will be decomposed * into its parts. * * \param 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 \c clang_disposeString() once you've finished with it. For an invalid * source location, an empty string is returned. * * \param line [out] if non-NULL, will be set to the line number of the * source location. For an invalid source location, zero is returned. * * \param column [out] if non-NULL, will be set to the column number of the * source location. For an invalid source location, zero is returned. */ CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, CXString *filename, unsigned *line, unsigned *column); /** * 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. */ CINDEX_LINKAGE void clang_getInstantiationLocation(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. * * \param location the location within a source file that will be decomposed * into its parts. * * \param file [out] if non-NULL, will be set to the file to which the given * source location points. * * \param line [out] if non-NULL, will be set to the line to which the given * source location points. * * \param column [out] if non-NULL, will be set to the column to which the given * source location points. * * \param offset [out] if non-NULL, will be set to the offset into the * buffer to which the given source location points. */ 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 expansion, return where the macro was * expanded or where the macro argument was written, if the location points at * a macro argument. * * \param location the location within a source file that will be decomposed * into its parts. * * \param file [out] if non-NULL, will be set to the file to which the given * source location points. * * \param line [out] if non-NULL, will be set to the line to which the given * source location points. * * \param column [out] if non-NULL, will be set to the column to which the given * source location points. * * \param offset [out] if non-NULL, will be set to the offset into the * buffer to which the given source location points. */ CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, CXFile *file, unsigned *line, unsigned *column, unsigned *offset); /** * Retrieve a source location representing the first character within a * source range. */ CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); /** * Retrieve a source location representing the last character within a * source range. */ CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); /** * Identifies an array of ranges. */ CXSourceRangeList; /** * Destroy the given \c CXSourceRangeList. */ CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); /** * @} */ LLVM_CLANG_C_EXTERN_C_END #endif
Codebase Browser
llvm