1/*===-- clang-c/CXSourceLocation.h - C Index Source Location ------*- C -*-===*\
2|* *|
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4|* Exceptions. *|
5|* See https://llvm.org/LICENSE.txt for license information. *|
6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7|* *|
8|*===----------------------------------------------------------------------===*|
9|* *|
10|* This header provides the interface to C Index source locations. *|
11|* *|
12\*===----------------------------------------------------------------------===*/
13
14#ifndef LLVM_CLANG_C_CXSOURCE_LOCATION_H
15#define LLVM_CLANG_C_CXSOURCE_LOCATION_H
16
17#include "clang-c/CXFile.h"
18#include "clang-c/CXString.h"
19#include "clang-c/ExternC.h"
20#include "clang-c/Platform.h"
21
22LLVM_CLANG_C_EXTERN_C_BEGIN
23
24/**
25 * \defgroup CINDEX_LOCATIONS Physical source locations
26 *
27 * Clang represents physical source locations in its abstract syntax tree in
28 * great detail, with file, line, and column information for the majority of
29 * the tokens parsed in the source code. These data types and functions are
30 * used to represent source location information, either for a particular
31 * point in the program or for a range of points in the program, and extract
32 * specific location information from those data types.
33 *
34 * @{
35 */
36
37/**
38 * Identifies a specific source location within a translation
39 * unit.
40 *
41 * Use clang_getExpansionLocation() or clang_getSpellingLocation()
42 * to map a source location to a particular file, line, and column.
43 */
44typedef struct {
45 const void *ptr_data[2];
46 unsigned int_data;
47} CXSourceLocation;
48
49/**
50 * Identifies a half-open character range in the source code.
51 *
52 * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
53 * starting and end locations from a source range, respectively.
54 */
55typedef struct {
56 const void *ptr_data[2];
57 unsigned begin_int_data;
58 unsigned end_int_data;
59} CXSourceRange;
60
61/**
62 * Retrieve a NULL (invalid) source location.
63 */
64CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void);
65
66/**
67 * Determine whether two source locations, which must refer into
68 * the same translation unit, refer to exactly the same point in the source
69 * code.
70 *
71 * \returns non-zero if the source locations refer to the same location, zero
72 * if they refer to different locations.
73 */
74CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
75 CXSourceLocation loc2);
76
77/**
78 * Returns non-zero if the given source location is in a system header.
79 */
80CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location);
81
82/**
83 * Returns non-zero if the given source location is in the main file of
84 * the corresponding translation unit.
85 */
86CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location);
87
88/**
89 * Retrieve a NULL (invalid) source range.
90 */
91CINDEX_LINKAGE CXSourceRange clang_getNullRange(void);
92
93/**
94 * Retrieve a source range given the beginning and ending source
95 * locations.
96 */
97CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
98 CXSourceLocation end);
99
100/**
101 * Determine whether two ranges are equivalent.
102 *
103 * \returns non-zero if the ranges are the same, zero if they differ.
104 */
105CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1,
106 CXSourceRange range2);
107
108/**
109 * Returns non-zero if \p range is null.
110 */
111CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range);
112
113/**
114 * Retrieve the file, line, column, and offset represented by
115 * the given source location.
116 *
117 * If the location refers into a macro expansion, retrieves the
118 * location of the macro expansion.
119 *
120 * \param location the location within a source file that will be decomposed
121 * into its parts.
122 *
123 * \param file [out] if non-NULL, will be set to the file to which the given
124 * source location points.
125 *
126 * \param line [out] if non-NULL, will be set to the line to which the given
127 * source location points.
128 *
129 * \param column [out] if non-NULL, will be set to the column to which the given
130 * source location points.
131 *
132 * \param offset [out] if non-NULL, will be set to the offset into the
133 * buffer to which the given source location points.
134 */
135CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location,
136 CXFile *file, unsigned *line,
137 unsigned *column,
138 unsigned *offset);
139
140/**
141 * Retrieve the file, line and column represented by the given source
142 * location, as specified in a # line directive.
143 *
144 * Example: given the following source code in a file somefile.c
145 *
146 * \code
147 * #123 "dummy.c" 1
148 *
149 * static int func(void)
150 * {
151 * return 0;
152 * }
153 * \endcode
154 *
155 * the location information returned by this function would be
156 *
157 * File: dummy.c Line: 124 Column: 12
158 *
159 * whereas clang_getExpansionLocation would have returned
160 *
161 * File: somefile.c Line: 3 Column: 12
162 *
163 * \param location the location within a source file that will be decomposed
164 * into its parts.
165 *
166 * \param filename [out] if non-NULL, will be set to the filename of the
167 * source location. Note that filenames returned will be for "virtual" files,
168 * which don't necessarily exist on the machine running clang - e.g. when
169 * parsing preprocessed output obtained from a different environment. If
170 * a non-NULL value is passed in, remember to dispose of the returned value
171 * using \c clang_disposeString() once you've finished with it. For an invalid
172 * source location, an empty string is returned.
173 *
174 * \param line [out] if non-NULL, will be set to the line number of the
175 * source location. For an invalid source location, zero is returned.
176 *
177 * \param column [out] if non-NULL, will be set to the column number of the
178 * source location. For an invalid source location, zero is returned.
179 */
180CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location,
181 CXString *filename,
182 unsigned *line, unsigned *column);
183
184/**
185 * Legacy API to retrieve the file, line, column, and offset represented
186 * by the given source location.
187 *
188 * This interface has been replaced by the newer interface
189 * #clang_getExpansionLocation(). See that interface's documentation for
190 * details.
191 */
192CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
193 CXFile *file, unsigned *line,
194 unsigned *column,
195 unsigned *offset);
196
197/**
198 * Retrieve the file, line, column, and offset represented by
199 * the given source location.
200 *
201 * If the location refers into a macro instantiation, return where the
202 * location was originally spelled in the source file.
203 *
204 * \param location the location within a source file that will be decomposed
205 * into its parts.
206 *
207 * \param file [out] if non-NULL, will be set to the file to which the given
208 * source location points.
209 *
210 * \param line [out] if non-NULL, will be set to the line to which the given
211 * source location points.
212 *
213 * \param column [out] if non-NULL, will be set to the column to which the given
214 * source location points.
215 *
216 * \param offset [out] if non-NULL, will be set to the offset into the
217 * buffer to which the given source location points.
218 */
219CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location,
220 CXFile *file, unsigned *line,
221 unsigned *column,
222 unsigned *offset);
223
224/**
225 * Retrieve the file, line, column, and offset represented by
226 * the given source location.
227 *
228 * If the location refers into a macro expansion, return where the macro was
229 * expanded or where the macro argument was written, if the location points at
230 * a macro argument.
231 *
232 * \param location the location within a source file that will be decomposed
233 * into its parts.
234 *
235 * \param file [out] if non-NULL, will be set to the file to which the given
236 * source location points.
237 *
238 * \param line [out] if non-NULL, will be set to the line to which the given
239 * source location points.
240 *
241 * \param column [out] if non-NULL, will be set to the column to which the given
242 * source location points.
243 *
244 * \param offset [out] if non-NULL, will be set to the offset into the
245 * buffer to which the given source location points.
246 */
247CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location,
248 CXFile *file, unsigned *line,
249 unsigned *column, unsigned *offset);
250
251/**
252 * Retrieve a source location representing the first character within a
253 * source range.
254 */
255CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
256
257/**
258 * Retrieve a source location representing the last character within a
259 * source range.
260 */
261CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
262
263/**
264 * Identifies an array of ranges.
265 */
266typedef struct {
267 /** The number of ranges in the \c ranges array. */
268 unsigned count;
269 /**
270 * An array of \c CXSourceRanges.
271 */
272 CXSourceRange *ranges;
273} CXSourceRangeList;
274
275/**
276 * Destroy the given \c CXSourceRangeList.
277 */
278CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);
279
280/**
281 * @}
282 */
283
284LLVM_CLANG_C_EXTERN_C_END
285
286#endif
287

source code of clang/include/clang-c/CXSourceLocation.h