1 /* Map (unsigned int) keys to (source file, line, column) triples.
2 Copyright (C) 2001-2023 Free Software Foundation, Inc.
3
4 This program is free software; you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation; either version 3, or (at your option) any
7 later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; see the file COPYING3. If not see
16 <http://www.gnu.org/licenses/>.
17
18 In other words, you are welcome to use, share and improve this program.
19 You are forbidden to forbid anyone else to use, share and improve
20 what you give them. Help stamp out software-hoarding! */
21
22 #ifndef LIBCPP_LINE_MAP_H
23 #define LIBCPP_LINE_MAP_H
24
25 #include <utility>
26
27 #ifndef GTY
28 #define GTY(x) /* nothing */
29 #endif
30
31 /* Both gcc and emacs number source *lines* starting at 1, but
32 they have differing conventions for *columns*.
33
34 GCC uses a 1-based convention for source columns,
35 whereas Emacs's M-x column-number-mode uses a 0-based convention.
36
37 For example, an error in the initial, left-hand
38 column of source line 3 is reported by GCC as:
39
40 some-file.c:3:1: error: ...etc...
41
42 On navigating to the location of that error in Emacs
43 (e.g. via "next-error"),
44 the locus is reported in the Mode Line
45 (assuming M-x column-number-mode) as:
46
47 some-file.c 10% (3, 0)
48
49 i.e. "3:1:" in GCC corresponds to "(3, 0)" in Emacs. */
50
51 /* The type of line numbers. */
52 typedef unsigned int linenum_type;
53
54 /* A type for doing arithmetic on line numbers. */
55 typedef long long linenum_arith_t;
56
57 /* A function for for use by qsort for comparing line numbers. */
58
59 inline int compare (linenum_type lhs, linenum_type rhs)
60 {
61 /* Avoid truncation issues by using linenum_arith_t for the comparison,
62 and only consider the sign of the result. */
63 linenum_arith_t diff = (linenum_arith_t)lhs - (linenum_arith_t)rhs;
64 if (diff)
65 return diff > 0 ? 1 : -1;
66 return 0;
67 }
68
69 /* Reason for creating a new line map with linemap_add. */
70 enum lc_reason
71 {
72 LC_ENTER = 0, /* Begin #include. */
73 LC_LEAVE, /* Return to including file. */
74 LC_RENAME, /* Other reason for name change. */
75 LC_RENAME_VERBATIM, /* Likewise, but "" != stdin. */
76 LC_ENTER_MACRO, /* Begin macro expansion. */
77 LC_MODULE, /* A (C++) Module. */
78 /* FIXME: add support for stringize and paste. */
79 LC_HWM /* High Water Mark. */
80 };
81
82 /* The typedef "location_t" is a key within the location database,
83 identifying a source location or macro expansion, along with range
84 information, and (optionally) a pointer for use by gcc.
85
86 This key only has meaning in relation to a line_maps instance. Within
87 gcc there is a single line_maps instance: "line_table", declared in
88 gcc/input.h and defined in gcc/input.cc.
89
90 The values of the keys are intended to be internal to libcpp,
91 but for ease-of-understanding the implementation, they are currently
92 assigned as follows:
93
94 Actual | Value | Meaning
95 -----------+-------------------------------+-------------------------------
96 0x00000000 | UNKNOWN_LOCATION (gcc/input.h)| Unknown/invalid location.
97 -----------+-------------------------------+-------------------------------
98 0x00000001 | BUILTINS_LOCATION | The location for declarations
99 | (gcc/input.h) | in "<built-in>"
100 -----------+-------------------------------+-------------------------------
101 0x00000002 | RESERVED_LOCATION_COUNT | The first location to be
102 | (also | handed out, and the
103 | ordmap[0]->start_location) | first line in ordmap 0
104 -----------+-------------------------------+-------------------------------
105 | ordmap[1]->start_location | First line in ordmap 1
106 | ordmap[1]->start_location+32 | First column in that line
107 | (assuming range_bits == 5) |
108 | ordmap[1]->start_location+64 | 2nd column in that line
109 | ordmap[1]->start_location+4096| Second line in ordmap 1
110 | (assuming column_bits == 12)
111 |
112 | Subsequent lines are offset by (1 << column_bits),
113 | e.g. 4096 for 12 bits, with a column value of 0 representing
114 | "the whole line".
115 |
116 | Within a line, the low "range_bits" (typically 5) are used for
117 | storing short ranges, so that there's an offset of
118 | (1 << range_bits) between individual columns within a line,
119 | typically 32.
120 | The low range_bits store the offset of the end point from the
121 | start point, and the start point is found by masking away
122 | the range bits.
123 |
124 | For example:
125 | ordmap[1]->start_location+64 "2nd column in that line"
126 | above means a caret at that location, with a range
127 | starting and finishing at the same place (the range bits
128 | are 0), a range of length 1.
129 |
130 | By contrast:
131 | ordmap[1]->start_location+68
132 | has range bits 0x4, meaning a caret with a range starting at
133 | that location, but with endpoint 4 columns further on: a range
134 | of length 5.
135 |
136 | Ranges that have caret != start, or have an endpoint too
137 | far away to fit in range_bits are instead stored as ad-hoc
138 | locations. Hence for range_bits == 5 we can compactly store
139 | tokens of length <= 32 without needing to use the ad-hoc
140 | table.
141 |
142 | This packing scheme means we effectively have
143 | (column_bits - range_bits)
144 | of bits for the columns, typically (12 - 5) = 7, for 128
145 | columns; longer line widths are accomodated by starting a
146 | new ordmap with a higher column_bits.
147 |
148 | ordmap[2]->start_location-1 | Final location in ordmap 1
149 -----------+-------------------------------+-------------------------------
150 | ordmap[2]->start_location | First line in ordmap 2
151 | ordmap[3]->start_location-1 | Final location in ordmap 2
152 -----------+-------------------------------+-------------------------------
153 | | (etc)
154 -----------+-------------------------------+-------------------------------
155 | ordmap[n-1]->start_location | First line in final ord map
156 | | (etc)
157 | set->highest_location - 1 | Final location in that ordmap
158 -----------+-------------------------------+-------------------------------
159 | set->highest_location | Location of the where the next
160 | | ordinary linemap would start
161 -----------+-------------------------------+-------------------------------
162 | |
163 | VVVVVVVVVVVVVVVVVVVVVVVVVVV
164 | Ordinary maps grow this way
165 |
166 | (unallocated integers)
167 |
168 0x60000000 | LINE_MAP_MAX_LOCATION_WITH_COLS
169 | Beyond this point, ordinary linemaps have 0 bits per column:
170 | each increment of the value corresponds to a new source line.
171 |
172 0x70000000 | LINE_MAP_MAX_LOCATION
173 | Beyond the point, we give up on ordinary maps; attempts to
174 | create locations in them lead to UNKNOWN_LOCATION (0).
175 |
176 | (unallocated integers)
177 |
178 | Macro maps grow this way
179 | ^^^^^^^^^^^^^^^^^^^^^^^^
180 | |
181 -----------+-------------------------------+-------------------------------
182 | LINEMAPS_MACRO_LOWEST_LOCATION| Locations within macro maps
183 | macromap[m-1]->start_location | Start of last macro map
184 | |
185 -----------+-------------------------------+-------------------------------
186 | macromap[m-2]->start_location | Start of penultimate macro map
187 -----------+-------------------------------+-------------------------------
188 | macromap[1]->start_location | Start of macro map 1
189 -----------+-------------------------------+-------------------------------
190 | macromap[0]->start_location | Start of macro map 0
191 0x7fffffff | MAX_LOCATION_T | Also used as a mask for
192 | | accessing the ad-hoc data table
193 -----------+-------------------------------+-------------------------------
194 0x80000000 | Start of ad-hoc values; the lower 31 bits are used as an index
195 ... | into the line_table->location_adhoc_data_map.data array.
196 0xffffffff | UINT_MAX |
197 -----------+-------------------------------+-------------------------------
198
199 Examples of location encoding.
200
201 Packed ranges
202 =============
203
204 Consider encoding the location of a token "foo", seen underlined here
205 on line 523, within an ordinary line_map that starts at line 500:
206
207 11111111112
208 12345678901234567890
209 522
210 523 return foo + bar;
211 ^~~
212 524
213
214 The location's caret and start are both at line 523, column 11; the
215 location's finish is on the same line, at column 13 (an offset of 2
216 columns, for length 3).
217
218 Line 523 is offset 23 from the starting line of the ordinary line_map.
219
220 caret == start, and the offset of the finish fits within 5 bits, so
221 this can be stored as a packed range.
222
223 This is encoded as:
224 ordmap->start
225 + (line_offset << ordmap->m_column_and_range_bits)
226 + (column << ordmap->m_range_bits)
227 + (range_offset);
228 i.e. (for line offset 23, column 11, range offset 2):
229 ordmap->start
230 + (23 << 12)
231 + (11 << 5)
232 + 2;
233 i.e.:
234 ordmap->start + 0x17162
235 assuming that the line_map uses the default of 7 bits for columns and
236 5 bits for packed range (giving 12 bits for m_column_and_range_bits).
237
238
239 "Pure" locations
240 ================
241
242 These are a special case of the above, where
243 caret == start == finish
244 They are stored as packed ranges with offset == 0.
245 For example, the location of the "f" of "foo" could be stored
246 as above, but with range offset 0, giving:
247 ordmap->start
248 + (23 << 12)
249 + (11 << 5)
250 + 0;
251 i.e.:
252 ordmap->start + 0x17160
253
254
255 Unoptimized ranges
256 ==================
257
258 Consider encoding the location of the binary expression
259 below:
260
261 11111111112
262 12345678901234567890
263 522
264 523 return foo + bar;
265 ~~~~^~~~~
266 524
267
268 The location's caret is at the "+", line 523 column 15, but starts
269 earlier, at the "f" of "foo" at column 11. The finish is at the "r"
270 of "bar" at column 19.
271
272 This can't be stored as a packed range since start != caret.
273 Hence it is stored as an ad-hoc location e.g. 0x80000003.
274
275 Stripping off the top bit gives us an index into the ad-hoc
276 lookaside table:
277
278 line_table->location_adhoc_data_map.data[0x3]
279
280 from which the caret, start and finish can be looked up,
281 encoded as "pure" locations:
282
283 start == ordmap->start + (23 << 12) + (11 << 5)
284 == ordmap->start + 0x17160 (as above; the "f" of "foo")
285
286 caret == ordmap->start + (23 << 12) + (15 << 5)
287 == ordmap->start + 0x171e0
288
289 finish == ordmap->start + (23 << 12) + (19 << 5)
290 == ordmap->start + 0x17260
291
292 To further see how location_t works in practice, see the
293 worked example in libcpp/location-example.txt. */
294 typedef unsigned int location_t;
295
296 /* Do not track column numbers higher than this one. As a result, the
297 range of column_bits is [12, 18] (or 0 if column numbers are
298 disabled). */
299 const unsigned int LINE_MAP_MAX_COLUMN_NUMBER = (1U << 12);
300
301 /* Do not pack ranges if locations get higher than this.
302 If you change this, update:
303 gcc.dg/plugin/location-overflow-test-*.c. */
304 const location_t LINE_MAP_MAX_LOCATION_WITH_PACKED_RANGES = 0x50000000;
305
306 /* Do not track column numbers if locations get higher than this.
307 If you change this, update:
308 gcc.dg/plugin/location-overflow-test-*.c. */
309 const location_t LINE_MAP_MAX_LOCATION_WITH_COLS = 0x60000000;
310
311 /* Highest possible source location encoded within an ordinary map. */
312 const location_t LINE_MAP_MAX_LOCATION = 0x70000000;
313
314 /* A range of source locations.
315
316 Ranges are closed:
317 m_start is the first location within the range,
318 m_finish is the last location within the range.
319
320 We may need a more compact way to store these, but for now,
321 let's do it the simple way, as a pair. */
322 struct GTY(()) source_range
323 {
324 location_t m_start;
325 location_t m_finish;
326
327 /* We avoid using constructors, since various structs that
328 don't yet have constructors will embed instances of
329 source_range. */
330
331 /* Make a source_range from a location_t. */
332 static source_range from_location (location_t loc)
333 {
334 source_range result;
335 result.m_start = loc;
336 result.m_finish = loc;
337 return result;
338 }
339
340 /* Make a source_range from a pair of location_t. */
341 static source_range from_locations (location_t start,
342 location_t finish)
343 {
344 source_range result;
345 result.m_start = start;
346 result.m_finish = finish;
347 return result;
348 }
349 };
350
351 /* Memory allocation function typedef. Works like xrealloc. */
352 typedef void *(*line_map_realloc) (void *, size_t);
353
354 /* Memory allocator function that returns the actual allocated size,
355 for a given requested allocation. */
356 typedef size_t (*line_map_round_alloc_size_func) (size_t);
357
358 /* A line_map encodes a sequence of locations.
359 There are two kinds of maps. Ordinary maps and macro expansion
360 maps, a.k.a macro maps.
361
362 A macro map encodes source locations of tokens that are part of a
363 macro replacement-list, at a macro expansion point. E.g, in:
364
365 #define PLUS(A,B) A + B
366
367 No macro map is going to be created there, because we are not at a
368 macro expansion point. We are at a macro /definition/ point. So the
369 locations of the tokens of the macro replacement-list (i.e, A + B)
370 will be locations in an ordinary map, not a macro map.
371
372 On the other hand, if we later do:
373
374 int a = PLUS (1,2);
375
376 The invocation of PLUS here is a macro expansion. So we are at a
377 macro expansion point. The preprocessor expands PLUS (1,2) and
378 replaces it with the tokens of its replacement-list: 1 + 2. A macro
379 map is going to be created to hold (or rather to map, haha ...) the
380 locations of the tokens 1, + and 2. The macro map also records the
381 location of the expansion point of PLUS. That location is mapped in
382 the map that is active right before the location of the invocation
383 of PLUS. */
384
385 /* This contains GTY mark-up to support precompiled headers.
386 line_map is an abstract class, only derived objects exist. */
387 struct GTY((tag ("0"), desc ("MAP_ORDINARY_P (&%h) ? 1 : 2"))) line_map {
388 location_t start_location;
389
390 /* Size and alignment is (usually) 4 bytes. */
391 };
392
393 /* An ordinary line map encodes physical source locations. Those
394 physical source locations are called "spelling locations".
395
396 Physical source file TO_FILE at line TO_LINE at column 0 is represented
397 by the logical START_LOCATION. TO_LINE+L at column C is represented by
398 START_LOCATION+(L*(1<<m_column_and_range_bits))+(C*1<<m_range_bits), as
399 long as C<(1<<effective range bits), and the result_location is less than
400 the next line_map's start_location.
401 (The top line is line 1 and the leftmost column is column 1; line/column 0
402 means "entire file/line" or "unknown line/column" or "not applicable".)
403
404 The highest possible source location is MAX_LOCATION_T. */
405 struct GTY((tag ("1"))) line_map_ordinary : public line_map {
406 /* Base class is 4 bytes. */
407
408 /* 4 bytes of integers, each 1 byte for easy extraction/insertion. */
409
410 /* The reason for creation of this line map. */
411 ENUM_BITFIELD (lc_reason) reason : 8;
412
413 /* SYSP is one for a system header, two for a C system header file
414 that therefore needs to be extern "C" protected in C++, and zero
415 otherwise. This field isn't really needed now that it's in
416 cpp_buffer. */
417 unsigned char sysp;
418
419 /* Number of the low-order location_t bits used for column numbers
420 and ranges. */
421 unsigned int m_column_and_range_bits : 8;
422
423 /* Number of the low-order "column" bits used for storing short ranges
424 inline, rather than in the ad-hoc table.
425 MSB LSB
426 31 0
427 +-------------------------+-------------------------------------------+
428 | |<---map->column_and_range_bits (e.g. 12)-->|
429 +-------------------------+-----------------------+-------------------+
430 | | column_and_range_bits | map->range_bits |
431 | | - range_bits | |
432 +-------------------------+-----------------------+-------------------+
433 | row bits | effective column bits | short range bits |
434 | | (e.g. 7) | (e.g. 5) |
435 +-------------------------+-----------------------+-------------------+ */
436 unsigned int m_range_bits : 8;
437
438 /* Pointer alignment boundary on both 32 and 64-bit systems. */
439
440 const char *to_file;
441 linenum_type to_line;
442
443 /* Location from whence this line map was included. For regular
444 #includes, this location will be the last location of a map. For
445 outermost file, this is 0. For modules it could be anywhere
446 within a map. */
447 location_t included_from;
448
449 /* Size is 20 or 24 bytes, no padding */
450 };
451
452 /* This is the highest possible source location encoded within an
453 ordinary or macro map. */
454 const location_t MAX_LOCATION_T = 0x7FFFFFFF;
455
456 struct cpp_hashnode;
457
458 /* A macro line map encodes location of tokens coming from a macro
459 expansion.
460
461 The offset from START_LOCATION is used to index into
462 MACRO_LOCATIONS; this holds the original location of the token. */
463 struct GTY((tag ("2"))) line_map_macro : public line_map {
464 /* Base is 4 bytes. */
465
466 /* The number of tokens inside the replacement-list of MACRO. */
467 unsigned int n_tokens;
468
469 /* Pointer alignment boundary. */
470
471 /* The cpp macro whose expansion gave birth to this macro map. */
472 struct cpp_hashnode *
473 GTY ((nested_ptr (union tree_node,
474 "%h ? CPP_HASHNODE (GCC_IDENT_TO_HT_IDENT (%h)) : NULL",
475 "%h ? HT_IDENT_TO_GCC_IDENT (HT_NODE (%h)) : NULL")))
476 macro;
477
478 /* This array of location is actually an array of pairs of
479 locations. The elements inside it thus look like:
480
481 x0,y0, x1,y1, x2,y2, ...., xn,yn.
482
483 where n == n_tokens;
484
485 Remember that these xI,yI are collected when libcpp is about to
486 expand a given macro.
487
488 yI is the location in the macro definition, either of the token
489 itself or of a macro parameter that it replaces.
490
491 Imagine this:
492
493 #define PLUS(A, B) A + B <--- #1
494
495 int a = PLUS (1,2); <--- #2
496
497 There is a macro map for the expansion of PLUS in #2. PLUS is
498 expanded into its expansion-list. The expansion-list is the
499 replacement-list of PLUS where the macro parameters are replaced
500 with their arguments. So the replacement-list of PLUS is made of
501 the tokens:
502
503 A, +, B
504
505 and the expansion-list is made of the tokens:
506
507 1, +, 2
508
509 Let's consider the case of token "+". Its y1 [yI for I == 1] is
510 its spelling location in #1.
511
512 y0 (thus for token "1") is the spelling location of A in #1.
513
514 And y2 (of token "2") is the spelling location of B in #1.
515
516 When the token is /not/ an argument for a macro, xI is the same
517 location as yI. Otherwise, xI is the location of the token
518 outside this macro expansion. If this macro was expanded from
519 another macro expansion, xI is a virtual location representing
520 the token in that macro expansion; otherwise, it is the spelling
521 location of the token.
522
523 Note that a virtual location is a location returned by
524 linemap_add_macro_token. It encodes the relevant locations (x,y
525 pairs) of that token across the macro expansions from which it
526 (the token) might come from.
527
528 In the example above x1 (for token "+") is going to be the same
529 as y1. x0 is the spelling location for the argument token "1",
530 and x2 is the spelling location for the argument token "2". */
531 location_t * GTY((atomic)) macro_locations;
532
533 /* This is the location of the expansion point of the current macro
534 map. It's the location of the macro name. That location is held
535 by the map that was current right before the current one. It
536 could have been either a macro or an ordinary map, depending on
537 if we are in a nested expansion context not. */
538 location_t expansion;
539
540 /* Size is 20 or 32 (4 bytes padding on 64-bit). */
541 };
542
543 #if CHECKING_P && (GCC_VERSION >= 2007)
544
545 /* Assertion macro to be used in line-map code. */
546 #define linemap_assert(EXPR) \
547 do { \
548 if (! (EXPR)) \
549 abort (); \
550 } while (0)
551
552 /* Assert that becomes a conditional expression when checking is disabled at
553 compilation time. Use this for conditions that should not happen but if
554 they happen, it is better to handle them gracefully rather than crash
555 randomly later.
556 Usage:
557
558 if (linemap_assert_fails(EXPR)) handle_error(); */
559 #define linemap_assert_fails(EXPR) __extension__ \
560 ({linemap_assert (EXPR); false;})
561
562 #else
563 /* Include EXPR, so that unused variable warnings do not occur. */
564 #define linemap_assert(EXPR) ((void)(0 && (EXPR)))
565 #define linemap_assert_fails(EXPR) (! (EXPR))
566 #endif
567
568 /* Get whether location LOC is an ordinary location. */
569
570 inline bool
571 IS_ORDINARY_LOC (location_t loc)
572 {
573 return loc < LINE_MAP_MAX_LOCATION;
574 }
575
576 /* Get whether location LOC is an ad-hoc location. */
577
578 inline bool
579 IS_ADHOC_LOC (location_t loc)
580 {
581 return loc > MAX_LOCATION_T;
582 }
583
584 /* Categorize line map kinds. */
585
586 inline bool
587 MAP_ORDINARY_P (const line_map *map)
588 {
589 return IS_ORDINARY_LOC (map->start_location);
590 }
591
592 /* Return TRUE if MAP encodes locations coming from a macro
593 replacement-list at macro expansion point. */
594 bool
595 linemap_macro_expansion_map_p (const line_map *);
596
597 /* Assert that MAP encodes locations of tokens that are not part of
598 the replacement-list of a macro expansion, downcasting from
599 line_map * to line_map_ordinary *. */
600
601 inline line_map_ordinary *
602 linemap_check_ordinary (line_map *map)
603 {
604 linemap_assert (MAP_ORDINARY_P (map));
605 return (line_map_ordinary *)map;
606 }
607
608 /* Assert that MAP encodes locations of tokens that are not part of
609 the replacement-list of a macro expansion, downcasting from
610 const line_map * to const line_map_ordinary *. */
611
612 inline const line_map_ordinary *
613 linemap_check_ordinary (const line_map *map)
614 {
615 linemap_assert (MAP_ORDINARY_P (map));
616 return (const line_map_ordinary *)map;
617 }
618
619 /* Assert that MAP is a macro expansion and downcast to the appropriate
620 subclass. */
621
622 inline line_map_macro *linemap_check_macro (line_map *map)
623 {
624 linemap_assert (!MAP_ORDINARY_P (map));
625 return (line_map_macro *)map;
626 }
627
628 /* Assert that MAP is a macro expansion and downcast to the appropriate
629 subclass. */
630
631 inline const line_map_macro *
632 linemap_check_macro (const line_map *map)
633 {
634 linemap_assert (!MAP_ORDINARY_P (map));
635 return (const line_map_macro *)map;
636 }
637
638 /* Read the start location of MAP. */
639
640 inline location_t
641 MAP_START_LOCATION (const line_map *map)
642 {
643 return map->start_location;
644 }
645
646 /* Get the starting line number of ordinary map MAP. */
647
648 inline linenum_type
649 ORDINARY_MAP_STARTING_LINE_NUMBER (const line_map_ordinary *ord_map)
650 {
651 return ord_map->to_line;
652 }
653
654 /* Return a positive value if map encodes locations from a system
655 header, 0 otherwise. Returns 1 if ordinary map MAP encodes locations
656 in a system header and 2 if it encodes locations in a C system header
657 that therefore needs to be extern "C" protected in C++. */
658
659 inline unsigned char
660 ORDINARY_MAP_IN_SYSTEM_HEADER_P (const line_map_ordinary *ord_map)
661 {
662 return ord_map->sysp;
663 }
664
665 /* TRUE if this line map is for a module (not a source file). */
666
667 inline bool
668 MAP_MODULE_P (const line_map *map)
669 {
670 return (MAP_ORDINARY_P (map)
671 && linemap_check_ordinary (map)->reason == LC_MODULE);
672 }
673
674 /* Get the filename of ordinary map MAP. */
675
676 inline const char *
677 ORDINARY_MAP_FILE_NAME (const line_map_ordinary *ord_map)
678 {
679 return ord_map->to_file;
680 }
681
682 /* Get the cpp macro whose expansion gave birth to macro map MAP. */
683
684 inline cpp_hashnode *
685 MACRO_MAP_MACRO (const line_map_macro *macro_map)
686 {
687 return macro_map->macro;
688 }
689
690 /* Get the number of tokens inside the replacement-list of the macro
691 that led to macro map MAP. */
692
693 inline unsigned int
694 MACRO_MAP_NUM_MACRO_TOKENS (const line_map_macro *macro_map)
695 {
696 return macro_map->n_tokens;
697 }
698
699 /* Get the array of pairs of locations within macro map MAP.
700 See the declaration of line_map_macro for more information. */
701
702 inline location_t *
703 MACRO_MAP_LOCATIONS (const line_map_macro *macro_map)
704 {
705 return macro_map->macro_locations;
706 }
707
708 /* Get the location of the expansion point of the macro map MAP. */
709
710 inline location_t
711 MACRO_MAP_EXPANSION_POINT_LOCATION (const line_map_macro *macro_map)
712 {
713 return macro_map->expansion;
714 }
715
716 /* The abstraction of a set of location maps. There can be several
717 types of location maps. This abstraction contains the attributes
718 that are independent from the type of the map.
719
720 Essentially this is just a vector of T_linemap_subclass,
721 which can only ever grow in size. */
722
723 struct GTY(()) maps_info_ordinary {
724 /* This array contains the "ordinary" line maps, for all
725 events other than macro expansion
726 (e.g. when a new preprocessing unit starts or ends). */
727 line_map_ordinary * GTY ((length ("%h.used"))) maps;
728
729 /* The total number of allocated maps. */
730 unsigned int allocated;
731
732 /* The number of elements used in maps. This number is smaller
733 or equal to ALLOCATED. */
734 unsigned int used;
735
736 mutable unsigned int cache;
737 };
738
739 struct GTY(()) maps_info_macro {
740 /* This array contains the macro line maps.
741 A macro line map is created whenever a macro expansion occurs. */
742 line_map_macro * GTY ((length ("%h.used"))) maps;
743
744 /* The total number of allocated maps. */
745 unsigned int allocated;
746
747 /* The number of elements used in maps. This number is smaller
748 or equal to ALLOCATED. */
749 unsigned int used;
750
751 mutable unsigned int cache;
752 };
753
754 /* Data structure to associate a source_range together with an arbitrary
755 data pointer with a source location. */
756 struct GTY(()) location_adhoc_data {
757 location_t locus;
758 source_range src_range;
759 void * GTY((skip)) data;
760 unsigned discriminator;
761 };
762
763 struct htab;
764
765 /* The following data structure encodes a location with some adhoc data
766 and maps it to a new unsigned integer (called an adhoc location)
767 that replaces the original location to represent the mapping.
768
769 The new adhoc_loc uses the highest bit as the enabling bit, i.e. if the
770 highest bit is 1, then the number is adhoc_loc. Otherwise, it serves as
771 the original location. Once identified as the adhoc_loc, the lower 31
772 bits of the integer is used to index the location_adhoc_data array,
773 in which the locus and associated data is stored. */
774
775 struct GTY(()) location_adhoc_data_map {
776 struct htab * GTY((skip)) htab;
777 location_t curr_loc;
778 unsigned int allocated;
779 struct location_adhoc_data GTY((length ("%h.allocated"))) *data;
780 };
781
782 /* A set of chronological line_map structures. */
783 class GTY(()) line_maps {
784 public:
785
786 ~line_maps ();
787
788 maps_info_ordinary info_ordinary;
789
790 maps_info_macro info_macro;
791
792 /* Depth of the include stack, including the current file. */
793 unsigned int depth;
794
795 /* If true, prints an include trace a la -H. */
796 bool trace_includes;
797
798 /* True if we've seen a #line or # 44 "file" directive. */
799 bool seen_line_directive;
800
801 /* Highest location_t "given out". */
802 location_t highest_location;
803
804 /* Start of line of highest location_t "given out". */
805 location_t highest_line;
806
807 /* The maximum column number we can quickly allocate. Higher numbers
808 may require allocating a new line_map. */
809 unsigned int max_column_hint;
810
811 /* The allocator to use when resizing 'maps', defaults to xrealloc. */
812 line_map_realloc GTY((callback)) reallocator;
813
814 /* The allocators' function used to know the actual size it
815 allocated, for a certain allocation size requested. */
816 line_map_round_alloc_size_func GTY((callback)) round_alloc_size;
817
818 struct location_adhoc_data_map location_adhoc_data_map;
819
820 /* The special location value that is used as spelling location for
821 built-in tokens. */
822 location_t builtin_location;
823
824 /* The default value of range_bits in ordinary line maps. */
825 unsigned int default_range_bits;
826
827 unsigned int num_optimized_ranges;
828 unsigned int num_unoptimized_ranges;
829 };
830
831 /* Returns the number of allocated maps so far. MAP_KIND shall be TRUE
832 if we are interested in macro maps, FALSE otherwise. */
833 inline unsigned int
834 LINEMAPS_ALLOCATED (const line_maps *set, bool map_kind)
835 {
836 if (map_kind)
837 return set->info_macro.allocated;
838 else
839 return set->info_ordinary.allocated;
840 }
841
842 /* As above, but by reference (e.g. as an lvalue). */
843
844 inline unsigned int &
845 LINEMAPS_ALLOCATED (line_maps *set, bool map_kind)
846 {
847 if (map_kind)
848 return set->info_macro.allocated;
849 else
850 return set->info_ordinary.allocated;
851 }
852
853 /* Returns the number of used maps so far. MAP_KIND shall be TRUE if
854 we are interested in macro maps, FALSE otherwise.*/
855 inline unsigned int
856 LINEMAPS_USED (const line_maps *set, bool map_kind)
857 {
858 if (map_kind)
859 return set->info_macro.used;
860 else
861 return set->info_ordinary.used;
862 }
863
864 /* As above, but by reference (e.g. as an lvalue). */
865
866 inline unsigned int &
867 LINEMAPS_USED (line_maps *set, bool map_kind)
868 {
869 if (map_kind)
870 return set->info_macro.used;
871 else
872 return set->info_ordinary.used;
873 }
874
875 /* Returns the index of the last map that was looked up with
876 linemap_lookup. MAP_KIND shall be TRUE if we are interested in
877 macro maps, FALSE otherwise. */
878 inline unsigned int &
879 LINEMAPS_CACHE (const line_maps *set, bool map_kind)
880 {
881 if (map_kind)
882 return set->info_macro.cache;
883 else
884 return set->info_ordinary.cache;
885 }
886
887 /* Return the map at a given index. */
888 inline line_map *
889 LINEMAPS_MAP_AT (const line_maps *set, bool map_kind, int index)
890 {
891 if (map_kind)
892 return &set->info_macro.maps[index];
893 else
894 return &set->info_ordinary.maps[index];
895 }
896
897 /* Returns the last map used in the line table SET. MAP_KIND
898 shall be TRUE if we are interested in macro maps, FALSE
899 otherwise.*/
900 inline line_map *
901 LINEMAPS_LAST_MAP (const line_maps *set, bool map_kind)
902 {
903 return LINEMAPS_MAP_AT (set, map_kind,
904 LINEMAPS_USED (set, map_kind) - 1);
905 }
906
907 /* Returns the last map that was allocated in the line table SET.
908 MAP_KIND shall be TRUE if we are interested in macro maps, FALSE
909 otherwise.*/
910 inline line_map *
911 LINEMAPS_LAST_ALLOCATED_MAP (const line_maps *set, bool map_kind)
912 {
913 return LINEMAPS_MAP_AT (set, map_kind,
914 LINEMAPS_ALLOCATED (set, map_kind) - 1);
915 }
916
917 /* Returns a pointer to the memory region where ordinary maps are
918 allocated in the line table SET. */
919 inline line_map_ordinary *
920 LINEMAPS_ORDINARY_MAPS (const line_maps *set)
921 {
922 return set->info_ordinary.maps;
923 }
924
925 /* Returns the INDEXth ordinary map. */
926 inline line_map_ordinary *
927 LINEMAPS_ORDINARY_MAP_AT (const line_maps *set, int index)
928 {
929 linemap_assert (index >= 0
930 && (unsigned int)index < LINEMAPS_USED (set, false));
931 return (line_map_ordinary *)LINEMAPS_MAP_AT (set, false, index);
932 }
933
934 /* Return the number of ordinary maps allocated in the line table
935 SET. */
936 inline unsigned int
937 LINEMAPS_ORDINARY_ALLOCATED (const line_maps *set)
938 {
939 return LINEMAPS_ALLOCATED (set, false);
940 }
941
942 /* Return the number of ordinary maps used in the line table SET. */
943 inline unsigned int
944 LINEMAPS_ORDINARY_USED (const line_maps *set)
945 {
946 return LINEMAPS_USED (set, false);
947 }
948
949 /* Return the index of the last ordinary map that was looked up with
950 linemap_lookup. */
951 inline unsigned int &
952 LINEMAPS_ORDINARY_CACHE (const line_maps *set)
953 {
954 return LINEMAPS_CACHE (set, false);
955 }
956
957 /* Returns a pointer to the last ordinary map used in the line table
958 SET. */
959 inline line_map_ordinary *
960 LINEMAPS_LAST_ORDINARY_MAP (const line_maps *set)
961 {
962 return (line_map_ordinary *)LINEMAPS_LAST_MAP (set, false);
963 }
964
965 /* Returns a pointer to the last ordinary map allocated the line table
966 SET. */
967 inline line_map_ordinary *
968 LINEMAPS_LAST_ALLOCATED_ORDINARY_MAP (const line_maps *set)
969 {
970 return (line_map_ordinary *)LINEMAPS_LAST_ALLOCATED_MAP (set, false);
971 }
972
973 /* Returns a pointer to the beginning of the region where macro maps
974 are allocated. */
975 inline line_map_macro *
976 LINEMAPS_MACRO_MAPS (const line_maps *set)
977 {
978 return set->info_macro.maps;
979 }
980
981 /* Returns the INDEXth macro map. */
982 inline line_map_macro *
983 LINEMAPS_MACRO_MAP_AT (const line_maps *set, int index)
984 {
985 linemap_assert (index >= 0
986 && (unsigned int)index < LINEMAPS_USED (set, true));
987 return (line_map_macro *)LINEMAPS_MAP_AT (set, true, index);
988 }
989
990 /* Returns the number of macro maps that were allocated in the line
991 table SET. */
992 inline unsigned int
993 LINEMAPS_MACRO_ALLOCATED (const line_maps *set)
994 {
995 return LINEMAPS_ALLOCATED (set, true);
996 }
997
998 /* Returns the number of macro maps used in the line table SET. */
999 inline unsigned int
1000 LINEMAPS_MACRO_USED (const line_maps *set)
1001 {
1002 return LINEMAPS_USED (set, true);
1003 }
1004
1005 /* Return the index of the last macro map that was looked up with
1006 linemap_lookup. */
1007 inline unsigned int &
1008 LINEMAPS_MACRO_CACHE (const line_maps *set)
1009 {
1010 return LINEMAPS_CACHE (set, true);
1011 }
1012
1013 /* Returns the last macro map used in the line table SET. */
1014 inline line_map_macro *
1015 LINEMAPS_LAST_MACRO_MAP (const line_maps *set)
1016 {
1017 return (line_map_macro *)LINEMAPS_LAST_MAP (set, true);
1018 }
1019
1020 /* Returns the lowest location [of a token resulting from macro
1021 expansion] encoded in this line table. */
1022 inline location_t
1023 LINEMAPS_MACRO_LOWEST_LOCATION (const line_maps *set)
1024 {
1025 return LINEMAPS_MACRO_USED (set)
1026 ? MAP_START_LOCATION (LINEMAPS_LAST_MACRO_MAP (set))
1027 : MAX_LOCATION_T + 1;
1028 }
1029
1030 /* Returns the last macro map allocated in the line table SET. */
1031 inline line_map_macro *
1032 LINEMAPS_LAST_ALLOCATED_MACRO_MAP (const line_maps *set)
1033 {
1034 return (line_map_macro *)LINEMAPS_LAST_ALLOCATED_MAP (set, true);
1035 }
1036
1037 extern location_t get_combined_adhoc_loc (line_maps *, location_t,
1038 source_range, void *, unsigned);
1039 extern void *get_data_from_adhoc_loc (const line_maps *, location_t);
1040 extern unsigned get_discriminator_from_adhoc_loc (const line_maps *, location_t);
1041 extern location_t get_location_from_adhoc_loc (const line_maps *,
1042 location_t);
1043
1044 extern source_range get_range_from_loc (line_maps *set, location_t loc);
1045 extern unsigned get_discriminator_from_loc (line_maps *set, location_t loc);
1046
1047 /* Get whether location LOC is a "pure" location, or
1048 whether it is an ad-hoc location, or embeds range information. */
1049
1050 bool
1051 pure_location_p (line_maps *set, location_t loc);
1052
1053 /* Given location LOC within SET, strip away any packed range information
1054 or ad-hoc information. */
1055
1056 extern location_t get_pure_location (line_maps *set, location_t loc);
1057
1058 /* Combine LOC and BLOCK, giving a combined adhoc location. */
1059
1060 inline location_t
1061 COMBINE_LOCATION_DATA (class line_maps *set,
1062 location_t loc,
1063 source_range src_range,
1064 void *block,
1065 unsigned discriminator)
1066 {
1067 return get_combined_adhoc_loc (set, loc, src_range, block, discriminator);
1068 }
1069
1070 extern void rebuild_location_adhoc_htab (class line_maps *);
1071
1072 /* Initialize a line map set. SET is the line map set to initialize
1073 and BUILTIN_LOCATION is the special location value to be used as
1074 spelling location for built-in tokens. This BUILTIN_LOCATION has
1075 to be strictly less than RESERVED_LOCATION_COUNT. */
1076 extern void linemap_init (class line_maps *set,
1077 location_t builtin_location);
1078
1079 /* Check for and warn about line_maps entered but not exited. */
1080
1081 extern void linemap_check_files_exited (class line_maps *);
1082
1083 /* Return a location_t for the start (i.e. column==0) of
1084 (physical) line TO_LINE in the current source file (as in the
1085 most recent linemap_add). MAX_COLUMN_HINT is the highest column
1086 number we expect to use in this line (but it does not change
1087 the highest_location). */
1088
1089 extern location_t linemap_line_start
1090 (class line_maps *set, linenum_type to_line, unsigned int max_column_hint);
1091
1092 /* Allocate a raw block of line maps, zero initialized. */
1093 extern line_map *line_map_new_raw (line_maps *, bool, unsigned);
1094
1095 /* Add a mapping of logical source line to physical source file and
1096 line number. This function creates an "ordinary map", which is a
1097 map that records locations of tokens that are not part of macro
1098 replacement-lists present at a macro expansion point.
1099
1100 The text pointed to by TO_FILE must have a lifetime
1101 at least as long as the lifetime of SET. An empty
1102 TO_FILE means standard input. If reason is LC_LEAVE, and
1103 TO_FILE is NULL, then TO_FILE, TO_LINE and SYSP are given their
1104 natural values considering the file we are returning to.
1105
1106 A call to this function can relocate the previous set of
1107 maps, so any stored line_map pointers should not be used. */
1108 extern const line_map *linemap_add
1109 (class line_maps *, enum lc_reason, unsigned int sysp,
1110 const char *to_file, linenum_type to_line);
1111
1112 /* Create a macro map. A macro map encodes source locations of tokens
1113 that are part of a macro replacement-list, at a macro expansion
1114 point. See the extensive comments of struct line_map and struct
1115 line_map_macro, in line-map.h.
1116
1117 This map shall be created when the macro is expanded. The map
1118 encodes the source location of the expansion point of the macro as
1119 well as the "original" source location of each token that is part
1120 of the macro replacement-list. If a macro is defined but never
1121 expanded, it has no macro map. SET is the set of maps the macro
1122 map should be part of. MACRO_NODE is the macro which the new macro
1123 map should encode source locations for. EXPANSION is the location
1124 of the expansion point of MACRO. For function-like macros
1125 invocations, it's best to make it point to the closing parenthesis
1126 of the macro, rather than the the location of the first character
1127 of the macro. NUM_TOKENS is the number of tokens that are part of
1128 the replacement-list of MACRO. */
1129 const line_map_macro *linemap_enter_macro (line_maps *, cpp_hashnode *,
1130 location_t, unsigned int);
1131
1132 /* Create a source location for a module. The creator must either do
1133 this after the TU is tokenized, or deal with saving and restoring
1134 map state. */
1135
1136 extern location_t linemap_module_loc
1137 (line_maps *, location_t from, const char *name);
1138 extern void linemap_module_reparent
1139 (line_maps *, location_t loc, location_t new_parent);
1140
1141 /* Restore the linemap state such that the map at LWM-1 continues.
1142 Return start location of the new map. */
1143 extern unsigned linemap_module_restore
1144 (line_maps *, unsigned lwm);
1145
1146 /* Given a logical source location, returns the map which the
1147 corresponding (source file, line, column) triplet can be deduced
1148 from. Since the set is built chronologically, the logical lines are
1149 monotonic increasing, and so the list is sorted and we can use a
1150 binary search. If no line map have been allocated yet, this
1151 function returns NULL. */
1152 extern const line_map *linemap_lookup
1153 (const line_maps *, location_t);
1154
1155 unsigned linemap_lookup_macro_index (const line_maps *, location_t);
1156
1157 /* Returns TRUE if the line table set tracks token locations across
1158 macro expansion, FALSE otherwise. */
1159 bool linemap_tracks_macro_expansion_locs_p (class line_maps *);
1160
1161 /* Return the name of the macro associated to MACRO_MAP. */
1162 const char* linemap_map_get_macro_name (const line_map_macro *);
1163
1164 /* Return a positive value if LOCATION is the locus of a token that is
1165 located in a system header, O otherwise. It returns 1 if LOCATION
1166 is the locus of a token that is located in a system header, and 2
1167 if LOCATION is the locus of a token located in a C system header
1168 that therefore needs to be extern "C" protected in C++.
1169
1170 Note that this function returns 1 if LOCATION belongs to a token
1171 that is part of a macro replacement-list defined in a system
1172 header, but expanded in a non-system file. */
1173 int linemap_location_in_system_header_p (class line_maps *,
1174 location_t);
1175
1176 /* Return TRUE if LOCATION is a source code location of a token that is part of
1177 a macro expansion, FALSE otherwise. */
1178 bool linemap_location_from_macro_expansion_p (const line_maps *,
1179 location_t);
1180
1181 /* TRUE if LOCATION is a source code location of a token that is part of the
1182 definition of a macro, FALSE otherwise. */
1183 bool linemap_location_from_macro_definition_p (class line_maps *,
1184 location_t);
1185
1186 /* With the precondition that LOCATION is the locus of a token that is
1187 an argument of a function-like macro MACRO_MAP and appears in the
1188 expansion of MACRO_MAP, return the locus of that argument in the
1189 context of the caller of MACRO_MAP. */
1190
1191 extern location_t linemap_macro_map_loc_unwind_toward_spelling
1192 (line_maps *set, const line_map_macro *macro_map, location_t location);
1193
1194 /* location_t values from 0 to RESERVED_LOCATION_COUNT-1 will
1195 be reserved for libcpp user as special values, no token from libcpp
1196 will contain any of those locations. */
1197 const location_t RESERVED_LOCATION_COUNT = 2;
1198
1199 /* Converts a map and a location_t to source line. */
1200 inline linenum_type
1201 SOURCE_LINE (const line_map_ordinary *ord_map, location_t loc)
1202 {
1203 return ((loc - ord_map->start_location)
1204 >> ord_map->m_column_and_range_bits) + ord_map->to_line;
1205 }
1206
1207 /* Convert a map and location_t to source column number. */
1208 inline linenum_type
1209 SOURCE_COLUMN (const line_map_ordinary *ord_map, location_t loc)
1210 {
1211 return ((loc - ord_map->start_location)
1212 & ((1 << ord_map->m_column_and_range_bits) - 1)) >> ord_map->m_range_bits;
1213 }
1214
1215
1216 inline location_t
1217 linemap_included_from (const line_map_ordinary *ord_map)
1218 {
1219 return ord_map->included_from;
1220 }
1221
1222 /* The linemap containing the included-from location of MAP. */
1223 const line_map_ordinary *linemap_included_from_linemap
1224 (line_maps *set, const line_map_ordinary *map);
1225
1226 /* True if the map is at the bottom of the include stack. */
1227
1228 inline bool
1229 MAIN_FILE_P (const line_map_ordinary *ord_map)
1230 {
1231 return ord_map->included_from == 0;
1232 }
1233
1234 /* Encode and return a location_t from a column number. The
1235 source line considered is the last source line used to call
1236 linemap_line_start, i.e, the last source line which a location was
1237 encoded from. */
1238 extern location_t
1239 linemap_position_for_column (class line_maps *, unsigned int);
1240
1241 /* Encode and return a source location from a given line and
1242 column. */
1243 location_t
1244 linemap_position_for_line_and_column (line_maps *set,
1245 const line_map_ordinary *,
1246 linenum_type, unsigned int);
1247
1248 /* Encode and return a location_t starting from location LOC and
1249 shifting it by OFFSET columns. This function does not support
1250 virtual locations. */
1251 location_t
1252 linemap_position_for_loc_and_offset (class line_maps *set,
1253 location_t loc,
1254 unsigned int offset);
1255
1256 /* Return the file this map is for. */
1257 inline const char *
1258 LINEMAP_FILE (const line_map_ordinary *ord_map)
1259 {
1260 return ord_map->to_file;
1261 }
1262
1263 /* Return the line number this map started encoding location from. */
1264 inline linenum_type
1265 LINEMAP_LINE (const line_map_ordinary *ord_map)
1266 {
1267 return ord_map->to_line;
1268 }
1269
1270 /* Return a positive value if map encodes locations from a system
1271 header, 0 otherwise. Returns 1 if MAP encodes locations in a
1272 system header and 2 if it encodes locations in a C system header
1273 that therefore needs to be extern "C" protected in C++. */
1274 inline unsigned char
1275 LINEMAP_SYSP (const line_map_ordinary *ord_map)
1276 {
1277 return ord_map->sysp;
1278 }
1279
1280 const struct line_map *first_map_in_common (line_maps *set,
1281 location_t loc0,
1282 location_t loc1,
1283 location_t *res_loc0,
1284 location_t *res_loc1);
1285
1286 /* Return a positive value if PRE denotes the location of a token that
1287 comes before the token of POST, 0 if PRE denotes the location of
1288 the same token as the token for POST, and a negative value
1289 otherwise. */
1290 int linemap_compare_locations (class line_maps *set,
1291 location_t pre,
1292 location_t post);
1293
1294 /* Return TRUE if LOC_A denotes the location a token that comes
1295 topogically before the token denoted by location LOC_B, or if they
1296 are equal. */
1297 inline bool
1298 linemap_location_before_p (class line_maps *set,
1299 location_t loc_a,
1300 location_t loc_b)
1301 {
1302 return linemap_compare_locations (set, loc_a, loc_b) >= 0;
1303 }
1304
1305 typedef struct
1306 {
1307 /* The name of the source file involved. */
1308 const char *file;
1309
1310 /* The line-location in the source file. */
1311 int line;
1312
1313 int column;
1314
1315 void *data;
1316
1317 /* In a system header?. */
1318 bool sysp;
1319 } expanded_location;
1320
1321 class range_label;
1322
1323 /* A hint to diagnostic_show_locus on how to print a source range within a
1324 rich_location.
1325
1326 Typically this is SHOW_RANGE_WITH_CARET for the 0th range, and
1327 SHOW_RANGE_WITHOUT_CARET for subsequent ranges,
1328 but the Fortran frontend uses SHOW_RANGE_WITH_CARET repeatedly for
1329 printing things like:
1330
1331 x = x + y
1332 1 2
1333 Error: Shapes for operands at (1) and (2) are not conformable
1334
1335 where "1" and "2" are notionally carets. */
1336
1337 enum range_display_kind
1338 {
1339 /* Show the pertinent source line(s), the caret, and underline(s). */
1340 SHOW_RANGE_WITH_CARET,
1341
1342 /* Show the pertinent source line(s) and underline(s), but don't
1343 show the caret (just an underline). */
1344 SHOW_RANGE_WITHOUT_CARET,
1345
1346 /* Just show the source lines; don't show the range itself.
1347 This is for use when displaying some line-insertion fix-it hints (for
1348 showing the user context on the change, for when it doesn't make sense
1349 to highlight the first column on the next line). */
1350 SHOW_LINES_WITHOUT_RANGE
1351 };
1352
1353 /* A location within a rich_location: a caret&range, with
1354 the caret potentially flagged for display, and an optional
1355 label. */
1356
1357 struct location_range
1358 {
1359 location_t m_loc;
1360
1361 enum range_display_kind m_range_display_kind;
1362
1363 /* If non-NULL, the label for this range. */
1364 const range_label *m_label;
1365 };
1366
1367 /* A partially-embedded vec for use within rich_location for storing
1368 ranges and fix-it hints.
1369
1370 Elements [0..NUM_EMBEDDED) are allocated within m_embed, after
1371 that they are within the dynamically-allocated m_extra.
1372
1373 This allows for static allocation in the common case, whilst
1374 supporting the rarer case of an arbitrary number of elements.
1375
1376 Dynamic allocation is not performed unless it's needed. */
1377
1378 template <typename T, int NUM_EMBEDDED>
1379 class semi_embedded_vec
1380 {
1381 public:
1382 semi_embedded_vec ();
1383 ~semi_embedded_vec ();
1384
1385 unsigned int count () const { return m_num; }
1386 T& operator[] (int idx);
1387 const T& operator[] (int idx) const;
1388
1389 void push (const T&);
1390 void truncate (int len);
1391
1392 private:
1393 int m_num;
1394 T m_embedded[NUM_EMBEDDED];
1395 int m_alloc;
1396 T *m_extra;
1397 };
1398
1399 /* Constructor for semi_embedded_vec. In particular, no dynamic allocation
1400 is done. */
1401
1402 template <typename T, int NUM_EMBEDDED>
1403 semi_embedded_vec<T, NUM_EMBEDDED>::semi_embedded_vec ()
1404 : m_num (0), m_alloc (0), m_extra (NULL)
1405 {
1406 }
1407
1408 /* semi_embedded_vec's dtor. Release any dynamically-allocated memory. */
1409
1410 template <typename T, int NUM_EMBEDDED>
1411 semi_embedded_vec<T, NUM_EMBEDDED>::~semi_embedded_vec ()
1412 {
1413 XDELETEVEC (m_extra);
1414 }
1415
1416 /* Look up element IDX, mutably. */
1417
1418 template <typename T, int NUM_EMBEDDED>
1419 T&
1420 semi_embedded_vec<T, NUM_EMBEDDED>::operator[] (int idx)
1421 {
1422 linemap_assert (idx < m_num);
1423 if (idx < NUM_EMBEDDED)
1424 return m_embedded[idx];
1425 else
1426 {
1427 linemap_assert (m_extra != NULL);
1428 return m_extra[idx - NUM_EMBEDDED];
1429 }
1430 }
1431
1432 /* Look up element IDX (const). */
1433
1434 template <typename T, int NUM_EMBEDDED>
1435 const T&
1436 semi_embedded_vec<T, NUM_EMBEDDED>::operator[] (int idx) const
1437 {
1438 linemap_assert (idx < m_num);
1439 if (idx < NUM_EMBEDDED)
1440 return m_embedded[idx];
1441 else
1442 {
1443 linemap_assert (m_extra != NULL);
1444 return m_extra[idx - NUM_EMBEDDED];
1445 }
1446 }
1447
1448 /* Append VALUE to the end of the semi_embedded_vec. */
1449
1450 template <typename T, int NUM_EMBEDDED>
1451 void
1452 semi_embedded_vec<T, NUM_EMBEDDED>::push (const T& value)
1453 {
1454 int idx = m_num++;
1455 if (idx < NUM_EMBEDDED)
1456 m_embedded[idx] = value;
1457 else
1458 {
1459 /* Offset "idx" to be an index within m_extra. */
1460 idx -= NUM_EMBEDDED;
1461 if (NULL == m_extra)
1462 {
1463 linemap_assert (m_alloc == 0);
1464 m_alloc = 16;
1465 m_extra = XNEWVEC (T, m_alloc);
1466 }
1467 else if (idx >= m_alloc)
1468 {
1469 linemap_assert (m_alloc > 0);
1470 m_alloc *= 2;
1471 m_extra = XRESIZEVEC (T, m_extra, m_alloc);
1472 }
1473 linemap_assert (m_extra);
1474 linemap_assert (idx < m_alloc);
1475 m_extra[idx] = value;
1476 }
1477 }
1478
1479 /* Truncate to length LEN. No deallocation is performed. */
1480
1481 template <typename T, int NUM_EMBEDDED>
1482 void
1483 semi_embedded_vec<T, NUM_EMBEDDED>::truncate (int len)
1484 {
1485 linemap_assert (len <= m_num);
1486 m_num = len;
1487 }
1488
1489 class fixit_hint;
1490 class diagnostic_path;
1491
1492 /* A "rich" source code location, for use when printing diagnostics.
1493 A rich_location has one or more carets&ranges, where the carets
1494 are optional. These are referred to as "ranges" from here.
1495 Typically the zeroth range has a caret; other ranges sometimes
1496 have carets.
1497
1498 The "primary" location of a rich_location is the caret of range 0,
1499 used for determining the line/column when printing diagnostic
1500 text, such as:
1501
1502 some-file.c:3:1: error: ...etc...
1503
1504 Additional ranges may be added to help the user identify other
1505 pertinent clauses in a diagnostic.
1506
1507 Ranges can (optionally) be given labels via class range_label.
1508
1509 rich_location instances are intended to be allocated on the stack
1510 when generating diagnostics, and to be short-lived.
1511
1512 Examples of rich locations
1513 --------------------------
1514
1515 Example A
1516 *********
1517 int i = "foo";
1518 ^
1519 This "rich" location is simply a single range (range 0), with
1520 caret = start = finish at the given point.
1521
1522 Example B
1523 *********
1524 a = (foo && bar)
1525 ~~~~~^~~~~~~
1526 This rich location has a single range (range 0), with the caret
1527 at the first "&", and the start/finish at the parentheses.
1528 Compare with example C below.
1529
1530 Example C
1531 *********
1532 a = (foo && bar)
1533 ~~~ ^~ ~~~
1534 This rich location has three ranges:
1535 - Range 0 has its caret and start location at the first "&" and
1536 end at the second "&.
1537 - Range 1 has its start and finish at the "f" and "o" of "foo";
1538 the caret is not flagged for display, but is perhaps at the "f"
1539 of "foo".
1540 - Similarly, range 2 has its start and finish at the "b" and "r" of
1541 "bar"; the caret is not flagged for display, but is perhaps at the
1542 "b" of "bar".
1543 Compare with example B above.
1544
1545 Example D (Fortran frontend)
1546 ****************************
1547 x = x + y
1548 1 2
1549 This rich location has range 0 at "1", and range 1 at "2".
1550 Both are flagged for caret display. Both ranges have start/finish
1551 equal to their caret point. The frontend overrides the diagnostic
1552 context's default caret character for these ranges.
1553
1554 Example E (range labels)
1555 ************************
1556 printf ("arg0: %i arg1: %s arg2: %i",
1557 ^~
1558 |
1559 const char *
1560 100, 101, 102);
1561 ~~~
1562 |
1563 int
1564 This rich location has two ranges:
1565 - range 0 is at the "%s" with start = caret = "%" and finish at
1566 the "s". It has a range_label ("const char *").
1567 - range 1 has start/finish covering the "101" and is not flagged for
1568 caret printing. The caret is at the start of "101", where its
1569 range_label is printed ("int").
1570
1571 Fix-it hints
1572 ------------
1573
1574 Rich locations can also contain "fix-it hints", giving suggestions
1575 for the user on how to edit their code to fix a problem. These
1576 can be expressed as insertions, replacements, and removals of text.
1577 The edits by default are relative to the zeroth range within the
1578 rich_location, but optionally they can be expressed relative to
1579 other locations (using various overloaded methods of the form
1580 rich_location::add_fixit_*).
1581
1582 For example:
1583
1584 Example F: fix-it hint: insert_before
1585 *************************************
1586 ptr = arr[0];
1587 ^~~~~~
1588 &
1589 This rich location has a single range (range 0) covering "arr[0]",
1590 with the caret at the start. The rich location has a single
1591 insertion fix-it hint, inserted before range 0, added via
1592 richloc.add_fixit_insert_before ("&");
1593
1594 Example G: multiple fix-it hints: insert_before and insert_after
1595 ****************************************************************
1596 #define FN(ARG0, ARG1, ARG2) fn(ARG0, ARG1, ARG2)
1597 ^~~~ ^~~~ ^~~~
1598 ( ) ( ) ( )
1599 This rich location has three ranges, covering "arg0", "arg1",
1600 and "arg2", all with caret-printing enabled.
1601 The rich location has 6 insertion fix-it hints: each arg
1602 has a pair of insertion fix-it hints, suggesting wrapping
1603 them with parentheses: one a '(' inserted before,
1604 the other a ')' inserted after, added via
1605 richloc.add_fixit_insert_before (LOC, "(");
1606 and
1607 richloc.add_fixit_insert_after (LOC, ")");
1608
1609 Example H: fix-it hint: removal
1610 *******************************
1611 struct s {int i};;
1612 ^
1613 -
1614 This rich location has a single range at the stray trailing
1615 semicolon, along with a single removal fix-it hint, covering
1616 the same range, added via:
1617 richloc.add_fixit_remove ();
1618
1619 Example I: fix-it hint: replace
1620 *******************************
1621 c = s.colour;
1622 ^~~~~~
1623 color
1624 This rich location has a single range (range 0) covering "colour",
1625 and a single "replace" fix-it hint, covering the same range,
1626 added via
1627 richloc.add_fixit_replace ("color");
1628
1629 Example J: fix-it hint: line insertion
1630 **************************************
1631
1632 3 | #include <stddef.h>
1633 + |+#include <stdio.h>
1634 4 | int the_next_line;
1635
1636 This rich location has a single range at line 4 column 1, marked
1637 with SHOW_LINES_WITHOUT_RANGE (to avoid printing a meaningless caret
1638 on the "i" of int). It has a insertion fix-it hint of the string
1639 "#include <stdio.h>\n".
1640
1641 Adding a fix-it hint can fail: for example, attempts to insert content
1642 at the transition between two line maps may fail due to there being no
1643 location_t value to express the new location.
1644
1645 Attempts to add a fix-it hint within a macro expansion will fail.
1646
1647 There is only limited support for newline characters in fix-it hints:
1648 only hints with newlines which insert an entire new line are permitted,
1649 inserting at the start of a line, and finishing with a newline
1650 (with no interior newline characters). Other attempts to add
1651 fix-it hints containing newline characters will fail.
1652 Similarly, attempts to delete or replace a range *affecting* multiple
1653 lines will fail.
1654
1655 The rich_location API handles these failures gracefully, so that
1656 diagnostics can attempt to add fix-it hints without each needing
1657 extensive checking.
1658
1659 Fix-it hints within a rich_location are "atomic": if any hints can't
1660 be applied, none of them will be (tracked by the m_seen_impossible_fixit
1661 flag), and no fix-its hints will be displayed for that rich_location.
1662 This implies that diagnostic messages need to be worded in such a way
1663 that they make sense whether or not the fix-it hints are displayed,
1664 or that richloc.seen_impossible_fixit_p () should be checked before
1665 issuing the diagnostics. */
1666
1667 class rich_location
1668 {
1669 public:
1670 /* Constructors. */
1671
1672 /* Constructing from a location. */
1673 rich_location (line_maps *set, location_t loc,
1674 const range_label *label = NULL);
1675
1676 /* Destructor. */
1677 ~rich_location ();
1678
1679 /* The class manages the memory pointed to by the elements of
1680 the M_FIXIT_HINTS vector and is not meant to be copied or
1681 assigned. */
1682 rich_location (const rich_location &) = delete;
1683 void operator= (const rich_location &) = delete;
1684
1685 /* Accessors. */
1686 location_t get_loc () const { return get_loc (0); }
1687 location_t get_loc (unsigned int idx) const;
1688
1689 void
1690 add_range (location_t loc,
1691 enum range_display_kind range_display_kind
1692 = SHOW_RANGE_WITHOUT_CARET,
1693 const range_label *label = NULL);
1694
1695 void
1696 set_range (unsigned int idx, location_t loc,
1697 enum range_display_kind range_display_kind);
1698
1699 unsigned int get_num_locations () const { return m_ranges.count (); }
1700
1701 const location_range *get_range (unsigned int idx) const;
1702 location_range *get_range (unsigned int idx);
1703
1704 expanded_location get_expanded_location (unsigned int idx);
1705
1706 void
1707 override_column (int column);
1708
1709 /* Fix-it hints. */
1710
1711 /* Methods for adding insertion fix-it hints. */
1712
1713 /* Suggest inserting NEW_CONTENT immediately before the primary
1714 range's start. */
1715 void
1716 add_fixit_insert_before (const char *new_content);
1717
1718 /* Suggest inserting NEW_CONTENT immediately before the start of WHERE. */
1719 void
1720 add_fixit_insert_before (location_t where,
1721 const char *new_content);
1722
1723 /* Suggest inserting NEW_CONTENT immediately after the end of the primary
1724 range. */
1725 void
1726 add_fixit_insert_after (const char *new_content);
1727
1728 /* Suggest inserting NEW_CONTENT immediately after the end of WHERE. */
1729 void
1730 add_fixit_insert_after (location_t where,
1731 const char *new_content);
1732
1733 /* Methods for adding removal fix-it hints. */
1734
1735 /* Suggest removing the content covered by range 0. */
1736 void
1737 add_fixit_remove ();
1738
1739 /* Suggest removing the content covered between the start and finish
1740 of WHERE. */
1741 void
1742 add_fixit_remove (location_t where);
1743
1744 /* Suggest removing the content covered by SRC_RANGE. */
1745 void
1746 add_fixit_remove (source_range src_range);
1747
1748 /* Methods for adding "replace" fix-it hints. */
1749
1750 /* Suggest replacing the content covered by range 0 with NEW_CONTENT. */
1751 void
1752 add_fixit_replace (const char *new_content);
1753
1754 /* Suggest replacing the content between the start and finish of
1755 WHERE with NEW_CONTENT. */
1756 void
1757 add_fixit_replace (location_t where,
1758 const char *new_content);
1759
1760 /* Suggest replacing the content covered by SRC_RANGE with
1761 NEW_CONTENT. */
1762 void
1763 add_fixit_replace (source_range src_range,
1764 const char *new_content);
1765
1766 unsigned int get_num_fixit_hints () const { return m_fixit_hints.count (); }
1767 fixit_hint *get_fixit_hint (int idx) const { return m_fixit_hints[idx]; }
1768 fixit_hint *get_last_fixit_hint () const;
1769 bool seen_impossible_fixit_p () const { return m_seen_impossible_fixit; }
1770
1771 /* Set this if the fix-it hints are not suitable to be
1772 automatically applied.
1773
1774 For example, if you are suggesting more than one
1775 mutually exclusive solution to a problem, then
1776 it doesn't make sense to apply all of the solutions;
1777 manual intervention is required.
1778
1779 If set, then the fix-it hints in the rich_location will
1780 be printed, but will not be added to generated patches,
1781 or affect the modified version of the file. */
1782 void fixits_cannot_be_auto_applied ()
1783 {
1784 m_fixits_cannot_be_auto_applied = true;
1785 }
1786
1787 bool fixits_can_be_auto_applied_p () const
1788 {
1789 return !m_fixits_cannot_be_auto_applied;
1790 }
1791
1792 /* An optional path through the code. */
1793 const diagnostic_path *get_path () const { return m_path; }
1794 void set_path (const diagnostic_path *path) { m_path = path; }
1795
1796 /* A flag for hinting that the diagnostic involves character encoding
1797 issues, and thus that it will be helpful to the user if we show some
1798 representation of how the characters in the pertinent source lines
1799 are encoded.
1800 The default is false (i.e. do not escape).
1801 When set to true, non-ASCII bytes in the pertinent source lines will
1802 be escaped in a manner controlled by the user-supplied option
1803 -fdiagnostics-escape-format=, so that the user can better understand
1804 what's going on with the encoding in their source file. */
1805 bool escape_on_output_p () const { return m_escape_on_output; }
1806 void set_escape_on_output (bool flag) { m_escape_on_output = flag; }
1807
1808 private:
1809 bool reject_impossible_fixit (location_t where);
1810 void stop_supporting_fixits ();
1811 void maybe_add_fixit (location_t start,
1812 location_t next_loc,
1813 const char *new_content);
1814
1815 public:
1816 static const int STATICALLY_ALLOCATED_RANGES = 3;
1817
1818 protected:
1819 line_maps *m_line_table;
1820 semi_embedded_vec <location_range, STATICALLY_ALLOCATED_RANGES> m_ranges;
1821
1822 int m_column_override;
1823
1824 bool m_have_expanded_location;
1825 bool m_seen_impossible_fixit;
1826 bool m_fixits_cannot_be_auto_applied;
1827 bool m_escape_on_output;
1828
1829 expanded_location m_expanded_location;
1830
1831 static const int MAX_STATIC_FIXIT_HINTS = 2;
1832 semi_embedded_vec <fixit_hint *, MAX_STATIC_FIXIT_HINTS> m_fixit_hints;
1833
1834 const diagnostic_path *m_path;
1835 };
1836
1837 /* A struct for the result of range_label::get_text: a NUL-terminated buffer
1838 of localized text, and a flag to determine if the caller should "free" the
1839 buffer. */
1840
1841 class label_text
1842 {
1843 public:
1844 label_text ()
1845 : m_buffer (NULL), m_owned (false)
1846 {}
1847
1848 ~label_text ()
1849 {
1850 if (m_owned)
1851 free (m_buffer);
1852 }
1853
1854 /* Move ctor. */
1855 label_text (label_text &&other)
1856 : m_buffer (other.m_buffer), m_owned (other.m_owned)
1857 {
1858 other.release ();
1859 }
1860
1861 /* Move assignment. */
1862 label_text & operator= (label_text &&other)
1863 {
1864 if (m_owned)
1865 free (m_buffer);
1866 m_buffer = other.m_buffer;
1867 m_owned = other.m_owned;
1868 other.release ();
1869 return *this;
1870 }
1871
1872 /* Delete the copy ctor and copy-assignment operator. */
1873 label_text (const label_text &) = delete;
1874 label_text & operator= (const label_text &) = delete;
1875
1876 /* Create a label_text instance that borrows BUFFER from a
1877 longer-lived owner. */
1878 static label_text borrow (const char *buffer)
1879 {
1880 return label_text (const_cast <char *> (buffer), false);
1881 }
1882
1883 /* Create a label_text instance that takes ownership of BUFFER. */
1884 static label_text take (char *buffer)
1885 {
1886 return label_text (buffer, true);
1887 }
1888
1889 void release ()
1890 {
1891 m_buffer = NULL;
1892 m_owned = false;
1893 }
1894
1895 const char *get () const
1896 {
1897 return m_buffer;
1898 }
1899
1900 bool is_owner () const
1901 {
1902 return m_owned;
1903 }
1904
1905 private:
1906 char *m_buffer;
1907 bool m_owned;
1908
1909 label_text (char *buffer, bool owned)
1910 : m_buffer (buffer), m_owned (owned)
1911 {}
1912 };
1913
1914 /* Abstract base class for labelling a range within a rich_location
1915 (e.g. for labelling expressions with their type).
1916
1917 Generating the text could require non-trivial work, so this work
1918 is delayed (via the "get_text" virtual function) until the diagnostic
1919 printing code "knows" it needs it, thus avoiding doing it e.g. for
1920 warnings that are filtered by command-line flags. This virtual
1921 function also isolates libcpp and the diagnostics subsystem from
1922 the front-end and middle-end-specific code for generating the text
1923 for the labels.
1924
1925 Like the rich_location instances they annotate, range_label instances
1926 are intended to be allocated on the stack when generating diagnostics,
1927 and to be short-lived. */
1928
1929 class range_label
1930 {
1931 public:
1932 virtual ~range_label () {}
1933
1934 /* Get localized text for the label.
1935 The RANGE_IDX is provided, allowing for range_label instances to be
1936 shared by multiple ranges if need be (the "flyweight" design pattern). */
1937 virtual label_text get_text (unsigned range_idx) const = 0;
1938 };
1939
1940 /* A fix-it hint: a suggested insertion, replacement, or deletion of text.
1941 We handle these three types of edit with one class, by representing
1942 them as replacement of a half-open range:
1943 [start, next_loc)
1944 Insertions have start == next_loc: "replace" the empty string at the
1945 start location with the new string.
1946 Deletions are replacement with the empty string.
1947
1948 There is only limited support for newline characters in fix-it hints
1949 as noted above in the comment for class rich_location.
1950 A fixit_hint instance can have at most one newline character; if
1951 present, the newline character must be the final character of
1952 the content (preventing e.g. fix-its that split a pre-existing line). */
1953
1954 class fixit_hint
1955 {
1956 public:
1957 fixit_hint (location_t start,
1958 location_t next_loc,
1959 const char *new_content);
1960 ~fixit_hint () { free (m_bytes); }
1961
1962 bool affects_line_p (const char *file, int line) const;
1963 location_t get_start_loc () const { return m_start; }
1964 location_t get_next_loc () const { return m_next_loc; }
1965 bool maybe_append (location_t start,
1966 location_t next_loc,
1967 const char *new_content);
1968
1969 const char *get_string () const { return m_bytes; }
1970 size_t get_length () const { return m_len; }
1971
1972 bool insertion_p () const { return m_start == m_next_loc; }
1973
1974 bool ends_with_newline_p () const;
1975
1976 private:
1977 /* We don't use source_range here since, unlike most places,
1978 this is a half-open/half-closed range:
1979 [start, next_loc)
1980 so that we can support insertion via start == next_loc. */
1981 location_t m_start;
1982 location_t m_next_loc;
1983 char *m_bytes;
1984 size_t m_len;
1985 };
1986
1987
1988 /* This is enum is used by the function linemap_resolve_location
1989 below. The meaning of the values is explained in the comment of
1990 that function. */
1991 enum location_resolution_kind
1992 {
1993 LRK_MACRO_EXPANSION_POINT,
1994 LRK_SPELLING_LOCATION,
1995 LRK_MACRO_DEFINITION_LOCATION
1996 };
1997
1998 /* Resolve a virtual location into either a spelling location, an
1999 expansion point location or a token argument replacement point
2000 location. Return the map that encodes the virtual location as well
2001 as the resolved location.
2002
2003 If LOC is *NOT* the location of a token resulting from the
2004 expansion of a macro, then the parameter LRK (which stands for
2005 Location Resolution Kind) is ignored and the resulting location
2006 just equals the one given in argument.
2007
2008 Now if LOC *IS* the location of a token resulting from the
2009 expansion of a macro, this is what happens.
2010
2011 * If LRK is set to LRK_MACRO_EXPANSION_POINT
2012 -------------------------------
2013
2014 The virtual location is resolved to the first macro expansion point
2015 that led to this macro expansion.
2016
2017 * If LRK is set to LRK_SPELLING_LOCATION
2018 -------------------------------------
2019
2020 The virtual location is resolved to the locus where the token has
2021 been spelled in the source. This can follow through all the macro
2022 expansions that led to the token.
2023
2024 * If LRK is set to LRK_MACRO_DEFINITION_LOCATION
2025 --------------------------------------
2026
2027 The virtual location is resolved to the locus of the token in the
2028 context of the macro definition.
2029
2030 If LOC is the locus of a token that is an argument of a
2031 function-like macro [replacing a parameter in the replacement list
2032 of the macro] the virtual location is resolved to the locus of the
2033 parameter that is replaced, in the context of the definition of the
2034 macro.
2035
2036 If LOC is the locus of a token that is not an argument of a
2037 function-like macro, then the function behaves as if LRK was set to
2038 LRK_SPELLING_LOCATION.
2039
2040 If LOC_MAP is not NULL, *LOC_MAP is set to the map encoding the
2041 returned location. Note that if the returned location wasn't originally
2042 encoded by a map, the *MAP is set to NULL. This can happen if LOC
2043 resolves to a location reserved for the client code, like
2044 UNKNOWN_LOCATION or BUILTINS_LOCATION in GCC. */
2045
2046 location_t linemap_resolve_location (class line_maps *,
2047 location_t loc,
2048 enum location_resolution_kind lrk,
2049 const line_map_ordinary **loc_map);
2050
2051 /* Suppose that LOC is the virtual location of a token coming from the
2052 expansion of a macro M. This function then steps up to get the
2053 location L of the point where M got expanded. If L is a spelling
2054 location inside a macro expansion M', then this function returns
2055 the point where M' was expanded. LOC_MAP is an output parameter.
2056 When non-NULL, *LOC_MAP is set to the map of the returned
2057 location. */
2058 location_t linemap_unwind_toward_expansion (class line_maps *,
2059 location_t loc,
2060 const line_map **loc_map);
2061
2062 /* If LOC is the virtual location of a token coming from the expansion
2063 of a macro M and if its spelling location is reserved (e.g, a
2064 location for a built-in token), then this function unwinds (using
2065 linemap_unwind_toward_expansion) the location until a location that
2066 is not reserved and is not in a system header is reached. In other
2067 words, this unwinds the reserved location until a location that is
2068 in real source code is reached.
2069
2070 Otherwise, if the spelling location for LOC is not reserved or if
2071 LOC doesn't come from the expansion of a macro, the function
2072 returns LOC as is and *MAP is not touched.
2073
2074 *MAP is set to the map of the returned location if the later is
2075 different from LOC. */
2076 location_t linemap_unwind_to_first_non_reserved_loc (class line_maps *,
2077 location_t loc,
2078 const line_map **map);
2079
2080 /* Expand source code location LOC and return a user readable source
2081 code location. LOC must be a spelling (non-virtual) location. If
2082 it's a location < RESERVED_LOCATION_COUNT a zeroed expanded source
2083 location is returned. */
2084 expanded_location linemap_expand_location (class line_maps *,
2085 const line_map *,
2086 location_t loc);
2087
2088 /* Statistics about maps allocation and usage as returned by
2089 linemap_get_statistics. */
2090 struct linemap_stats
2091 {
2092 long num_ordinary_maps_allocated;
2093 long num_ordinary_maps_used;
2094 long ordinary_maps_allocated_size;
2095 long ordinary_maps_used_size;
2096 long num_expanded_macros;
2097 long num_macro_tokens;
2098 long num_macro_maps_used;
2099 long macro_maps_allocated_size;
2100 long macro_maps_used_size;
2101 long macro_maps_locations_size;
2102 long duplicated_macro_maps_locations_size;
2103 long adhoc_table_size;
2104 long adhoc_table_entries_used;
2105 };
2106
2107 /* Return the highest location emitted for a given file for which
2108 there is a line map in SET. FILE_NAME is the file name to
2109 consider. If the function returns TRUE, *LOC is set to the highest
2110 location emitted for that file. */
2111 bool linemap_get_file_highest_location (class line_maps * set,
2112 const char *file_name,
2113 location_t *loc);
2114
2115 /* Compute and return statistics about the memory consumption of some
2116 parts of the line table SET. */
2117 void linemap_get_statistics (line_maps *, struct linemap_stats *);
2118
2119 /* Dump debugging information about source location LOC into the file
2120 stream STREAM. SET is the line map set LOC comes from. */
2121 void linemap_dump_location (line_maps *, location_t, FILE *);
2122
2123 /* Dump line map at index IX in line table SET to STREAM. If STREAM
2124 is NULL, use stderr. IS_MACRO is true if the caller wants to
2125 dump a macro map, false otherwise. */
2126 void linemap_dump (FILE *, line_maps *, unsigned, bool);
2127
2128 /* Dump line table SET to STREAM. If STREAM is NULL, stderr is used.
2129 NUM_ORDINARY specifies how many ordinary maps to dump. NUM_MACRO
2130 specifies how many macro maps to dump. */
2131 void line_table_dump (FILE *, line_maps *, unsigned int, unsigned int);
2132
2133 /* An enum for distinguishing the various parts within a location_t. */
2134
2135 enum location_aspect
2136 {
2137 LOCATION_ASPECT_CARET,
2138 LOCATION_ASPECT_START,
2139 LOCATION_ASPECT_FINISH
2140 };
2141
2142 /* The rich_location class requires a way to expand location_t instances.
2143 We would directly use expand_location_to_spelling_point, which is
2144 implemented in gcc/input.cc, but we also need to use it for rich_location
2145 within genmatch.cc.
2146 Hence we require client code of libcpp to implement the following
2147 symbol. */
2148 extern expanded_location
2149 linemap_client_expand_location_to_spelling_point (location_t,
2150 enum location_aspect);
2151
2152 #endif /* !LIBCPP_LINE_MAP_H */