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 * Determine for two source locations if the first comes
79 * strictly before the second one in the source code.
80 *
81 * \returns non-zero if the first source location comes
82 * strictly before the second one, zero otherwise.
83 */
84CINDEX_LINKAGE unsigned clang_isBeforeInTranslationUnit(CXSourceLocation loc1,
85 CXSourceLocation loc2);
86
87/**
88 * Returns non-zero if the given source location is in a system header.
89 */
90CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location);
91
92/**
93 * Returns non-zero if the given source location is in the main file of
94 * the corresponding translation unit.
95 */
96CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location);
97
98/**
99 * Retrieve a NULL (invalid) source range.
100 */
101CINDEX_LINKAGE CXSourceRange clang_getNullRange(void);
102
103/**
104 * Retrieve a source range given the beginning and ending source
105 * locations.
106 */
107CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
108 CXSourceLocation end);
109
110/**
111 * Determine whether two ranges are equivalent.
112 *
113 * \returns non-zero if the ranges are the same, zero if they differ.
114 */
115CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1,
116 CXSourceRange range2);
117
118/**
119 * Returns non-zero if \p range is null.
120 */
121CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range);
122
123/**
124 * Retrieve the file, line, column, and offset represented by
125 * the given source location.
126 *
127 * If the location refers into a macro expansion, retrieves the
128 * location of the macro expansion.
129 *
130 * \param location the location within a source file that will be decomposed
131 * into its parts.
132 *
133 * \param file [out] if non-NULL, will be set to the file to which the given
134 * source location points.
135 *
136 * \param line [out] if non-NULL, will be set to the line to which the given
137 * source location points.
138 *
139 * \param column [out] if non-NULL, will be set to the column to which the given
140 * source location points.
141 *
142 * \param offset [out] if non-NULL, will be set to the offset into the
143 * buffer to which the given source location points.
144 */
145CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location,
146 CXFile *file, unsigned *line,
147 unsigned *column,
148 unsigned *offset);
149
150/**
151 * Retrieve the file, line and column represented by the given source
152 * location, as specified in a # line directive.
153 *
154 * Example: given the following source code in a file somefile.c
155 *
156 * \code
157 * #123 "dummy.c" 1
158 *
159 * static int func(void)
160 * {
161 * return 0;
162 * }
163 * \endcode
164 *
165 * the location information returned by this function would be
166 *
167 * File: dummy.c Line: 124 Column: 12
168 *
169 * whereas clang_getExpansionLocation would have returned
170 *
171 * File: somefile.c Line: 3 Column: 12
172 *
173 * \param location the location within a source file that will be decomposed
174 * into its parts.
175 *
176 * \param filename [out] if non-NULL, will be set to the filename of the
177 * source location. Note that filenames returned will be for "virtual" files,
178 * which don't necessarily exist on the machine running clang - e.g. when
179 * parsing preprocessed output obtained from a different environment. If
180 * a non-NULL value is passed in, remember to dispose of the returned value
181 * using \c clang_disposeString() once you've finished with it. For an invalid
182 * source location, an empty string is returned.
183 *
184 * \param line [out] if non-NULL, will be set to the line number of the
185 * source location. For an invalid source location, zero is returned.
186 *
187 * \param column [out] if non-NULL, will be set to the column number of the
188 * source location. For an invalid source location, zero is returned.
189 */
190CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location,
191 CXString *filename,
192 unsigned *line, unsigned *column);
193
194/**
195 * Legacy API to retrieve the file, line, column, and offset represented
196 * by the given source location.
197 *
198 * This interface has been replaced by the newer interface
199 * #clang_getExpansionLocation(). See that interface's documentation for
200 * details.
201 */
202CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
203 CXFile *file, unsigned *line,
204 unsigned *column,
205 unsigned *offset);
206
207/**
208 * Retrieve the file, line, column, and offset represented by
209 * the given source location.
210 *
211 * If the location refers into a macro instantiation, return where the
212 * location was originally spelled in the source file.
213 *
214 * \param location the location within a source file that will be decomposed
215 * into its parts.
216 *
217 * \param file [out] if non-NULL, will be set to the file to which the given
218 * source location points.
219 *
220 * \param line [out] if non-NULL, will be set to the line to which the given
221 * source location points.
222 *
223 * \param column [out] if non-NULL, will be set to the column to which the given
224 * source location points.
225 *
226 * \param offset [out] if non-NULL, will be set to the offset into the
227 * buffer to which the given source location points.
228 */
229CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location,
230 CXFile *file, unsigned *line,
231 unsigned *column,
232 unsigned *offset);
233
234/**
235 * Retrieve the file, line, column, and offset represented by
236 * the given source location.
237 *
238 * If the location refers into a macro expansion, return where the macro was
239 * expanded or where the macro argument was written, if the location points at
240 * a macro argument.
241 *
242 * \param location the location within a source file that will be decomposed
243 * into its parts.
244 *
245 * \param file [out] if non-NULL, will be set to the file to which the given
246 * source location points.
247 *
248 * \param line [out] if non-NULL, will be set to the line to which the given
249 * source location points.
250 *
251 * \param column [out] if non-NULL, will be set to the column to which the given
252 * source location points.
253 *
254 * \param offset [out] if non-NULL, will be set to the offset into the
255 * buffer to which the given source location points.
256 */
257CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location,
258 CXFile *file, unsigned *line,
259 unsigned *column, unsigned *offset);
260
261/**
262 * Retrieve a source location representing the first character within a
263 * source range.
264 */
265CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
266
267/**
268 * Retrieve a source location representing the last character within a
269 * source range.
270 */
271CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
272
273/**
274 * Identifies an array of ranges.
275 */
276typedef struct {
277 /** The number of ranges in the \c ranges array. */
278 unsigned count;
279 /**
280 * An array of \c CXSourceRanges.
281 */
282 CXSourceRange *ranges;
283} CXSourceRangeList;
284
285/**
286 * Destroy the given \c CXSourceRangeList.
287 */
288CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);
289
290/**
291 * @}
292 */
293
294LLVM_CLANG_C_EXTERN_C_END
295
296#endif
297