1	/* Map (unsigned int) keys to (source file, line, column) triples.
2	Copyright (C) 2001-2022 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	};
761
762	struct htab;
763
764	/* The following data structure encodes a location with some adhoc data
765	and maps it to a new unsigned integer (called an adhoc location)
766	that replaces the original location to represent the mapping.
767
768	The new adhoc_loc uses the highest bit as the enabling bit, i.e. if the
769	highest bit is 1, then the number is adhoc_loc. Otherwise, it serves as
770	the original location. Once identified as the adhoc_loc, the lower 31
771	bits of the integer is used to index the location_adhoc_data array,
772	in which the locus and associated data is stored. */
773
774	struct GTY(()) location_adhoc_data_map {
775	struct htab * GTY((skip)) htab;
776	location_t curr_loc;
777	unsigned int allocated;
778	struct location_adhoc_data GTY((length ("%h.allocated"))) *data;
779	};
780
781	/* A set of chronological line_map structures. */
782	class GTY(()) line_maps {
783	public:
784
785	~line_maps ();
786
787	maps_info_ordinary info_ordinary;
788
789	maps_info_macro info_macro;
790
791	/* Depth of the include stack, including the current file. */
792	unsigned int depth;
793
794	/* If true, prints an include trace a la -H. */
795	bool trace_includes;
796
797	/* True if we've seen a #line or # 44 "file" directive. */
798	bool seen_line_directive;
799
800	/* Highest location_t "given out". */
801	location_t highest_location;
802
803	/* Start of line of highest location_t "given out". */
804	location_t highest_line;
805
806	/* The maximum column number we can quickly allocate. Higher numbers
807	may require allocating a new line_map. */
808	unsigned int max_column_hint;
809
810	/* The allocator to use when resizing 'maps', defaults to xrealloc. */
811	line_map_realloc GTY((callback)) reallocator;
812
813	/* The allocators' function used to know the actual size it
814	allocated, for a certain allocation size requested. */
815	line_map_round_alloc_size_func GTY((callback)) round_alloc_size;
816
817	struct location_adhoc_data_map location_adhoc_data_map;
818
819	/* The special location value that is used as spelling location for
820	built-in tokens. */
821	location_t builtin_location;
822
823	/* The default value of range_bits in ordinary line maps. */
824	unsigned int default_range_bits;
825
826	unsigned int num_optimized_ranges;
827	unsigned int num_unoptimized_ranges;
828	};
829
830	/* Returns the number of allocated maps so far. MAP_KIND shall be TRUE
831	if we are interested in macro maps, FALSE otherwise. */
832	inline unsigned int
833	LINEMAPS_ALLOCATED (const line_maps *set, bool map_kind)
834	{
835	if (map_kind)
836	return set->info_macro.allocated;
837	else
838	return set->info_ordinary.allocated;
839	}
840
841	/* As above, but by reference (e.g. as an lvalue). */
842
843	inline unsigned int &
844	LINEMAPS_ALLOCATED (line_maps *set, bool map_kind)
845	{
846	if (map_kind)
847	return set->info_macro.allocated;
848	else
849	return set->info_ordinary.allocated;
850	}
851
852	/* Returns the number of used maps so far. MAP_KIND shall be TRUE if
853	we are interested in macro maps, FALSE otherwise.*/
854	inline unsigned int
855	LINEMAPS_USED (const line_maps *set, bool map_kind)
856	{
857	if (map_kind)
858	return set->info_macro.used;
859	else
860	return set->info_ordinary.used;
861	}
862
863	/* As above, but by reference (e.g. as an lvalue). */
864
865	inline unsigned int &
866	LINEMAPS_USED (line_maps *set, bool map_kind)
867	{
868	if (map_kind)
869	return set->info_macro.used;
870	else
871	return set->info_ordinary.used;
872	}
873
874	/* Returns the index of the last map that was looked up with
875	linemap_lookup. MAP_KIND shall be TRUE if we are interested in
876	macro maps, FALSE otherwise. */
877	inline unsigned int &
878	LINEMAPS_CACHE (const line_maps *set, bool map_kind)
879	{
880	if (map_kind)
881	return set->info_macro.cache;
882	else
883	return set->info_ordinary.cache;
884	}
885
886	/* Return the map at a given index. */
887	inline line_map *
888	LINEMAPS_MAP_AT (const line_maps *set, bool map_kind, int index)
889	{
890	if (map_kind)
891	return &set->info_macro.maps[index];
892	else
893	return &set->info_ordinary.maps[index];
894	}
895
896	/* Returns the last map used in the line table SET. MAP_KIND
897	shall be TRUE if we are interested in macro maps, FALSE
898	otherwise.*/
899	inline line_map *
900	LINEMAPS_LAST_MAP (const line_maps *set, bool map_kind)
901	{
902	return LINEMAPS_MAP_AT (set, map_kind,
903	LINEMAPS_USED (set, map_kind) - 1);
904	}
905
906	/* Returns the last map that was allocated in the line table SET.
907	MAP_KIND shall be TRUE if we are interested in macro maps, FALSE
908	otherwise.*/
909	inline line_map *
910	LINEMAPS_LAST_ALLOCATED_MAP (const line_maps *set, bool map_kind)
911	{
912	return LINEMAPS_MAP_AT (set, map_kind,
913	LINEMAPS_ALLOCATED (set, map_kind) - 1);
914	}
915
916	/* Returns a pointer to the memory region where ordinary maps are
917	allocated in the line table SET. */
918	inline line_map_ordinary *
919	LINEMAPS_ORDINARY_MAPS (const line_maps *set)
920	{
921	return set->info_ordinary.maps;
922	}
923
924	/* Returns the INDEXth ordinary map. */
925	inline line_map_ordinary *
926	LINEMAPS_ORDINARY_MAP_AT (const line_maps *set, int index)
927	{
928	linemap_assert (index >= 0
929	&& (unsigned int)index < LINEMAPS_USED (set, false));
930	return (line_map_ordinary *)LINEMAPS_MAP_AT (set, false, index);
931	}
932
933	/* Return the number of ordinary maps allocated in the line table
934	SET. */
935	inline unsigned int
936	LINEMAPS_ORDINARY_ALLOCATED (const line_maps *set)
937	{
938	return LINEMAPS_ALLOCATED (set, false);
939	}
940
941	/* Return the number of ordinary maps used in the line table SET. */
942	inline unsigned int
943	LINEMAPS_ORDINARY_USED (const line_maps *set)
944	{
945	return LINEMAPS_USED (set, false);
946	}
947
948	/* Return the index of the last ordinary map that was looked up with
949	linemap_lookup. */
950	inline unsigned int &
951	LINEMAPS_ORDINARY_CACHE (const line_maps *set)
952	{
953	return LINEMAPS_CACHE (set, false);
954	}
955
956	/* Returns a pointer to the last ordinary map used in the line table
957	SET. */
958	inline line_map_ordinary *
959	LINEMAPS_LAST_ORDINARY_MAP (const line_maps *set)
960	{
961	return (line_map_ordinary *)LINEMAPS_LAST_MAP (set, false);
962	}
963
964	/* Returns a pointer to the last ordinary map allocated the line table
965	SET. */
966	inline line_map_ordinary *
967	LINEMAPS_LAST_ALLOCATED_ORDINARY_MAP (const line_maps *set)
968	{
969	return (line_map_ordinary *)LINEMAPS_LAST_ALLOCATED_MAP (set, false);
970	}
971
972	/* Returns a pointer to the beginning of the region where macro maps
973	are allocated. */
974	inline line_map_macro *
975	LINEMAPS_MACRO_MAPS (const line_maps *set)
976	{
977	return set->info_macro.maps;
978	}
979
980	/* Returns the INDEXth macro map. */
981	inline line_map_macro *
982	LINEMAPS_MACRO_MAP_AT (const line_maps *set, int index)
983	{
984	linemap_assert (index >= 0
985	&& (unsigned int)index < LINEMAPS_USED (set, true));
986	return (line_map_macro *)LINEMAPS_MAP_AT (set, true, index);
987	}
988
989	/* Returns the number of macro maps that were allocated in the line
990	table SET. */
991	inline unsigned int
992	LINEMAPS_MACRO_ALLOCATED (const line_maps *set)
993	{
994	return LINEMAPS_ALLOCATED (set, true);
995	}
996
997	/* Returns the number of macro maps used in the line table SET. */
998	inline unsigned int
999	LINEMAPS_MACRO_USED (const line_maps *set)
1000	{
1001	return LINEMAPS_USED (set, true);
1002	}
1003
1004	/* Return the index of the last macro map that was looked up with
1005	linemap_lookup. */
1006	inline unsigned int &
1007	LINEMAPS_MACRO_CACHE (const line_maps *set)
1008	{
1009	return LINEMAPS_CACHE (set, true);
1010	}
1011
1012	/* Returns the last macro map used in the line table SET. */
1013	inline line_map_macro *
1014	LINEMAPS_LAST_MACRO_MAP (const line_maps *set)
1015	{
1016	return (line_map_macro *)LINEMAPS_LAST_MAP (set, true);
1017	}
1018
1019	/* Returns the lowest location [of a token resulting from macro
1020	expansion] encoded in this line table. */
1021	inline location_t
1022	LINEMAPS_MACRO_LOWEST_LOCATION (const line_maps *set)
1023	{
1024	return LINEMAPS_MACRO_USED (set)
1025	? MAP_START_LOCATION (LINEMAPS_LAST_MACRO_MAP (set))
1026	: MAX_LOCATION_T + 1;
1027	}
1028
1029	/* Returns the last macro map allocated in the line table SET. */
1030	inline line_map_macro *
1031	LINEMAPS_LAST_ALLOCATED_MACRO_MAP (const line_maps *set)
1032	{
1033	return (line_map_macro *)LINEMAPS_LAST_ALLOCATED_MAP (set, true);
1034	}
1035
1036	extern location_t get_combined_adhoc_loc (line_maps *, location_t,
1037	source_range, void *);
1038	extern void *get_data_from_adhoc_loc (const line_maps *, location_t);
1039	extern location_t get_location_from_adhoc_loc (const line_maps *,
1040	location_t);
1041
1042	extern source_range get_range_from_loc (line_maps *set, location_t loc);
1043
1044	/* Get whether location LOC is a "pure" location, or
1045	whether it is an ad-hoc location, or embeds range information. */
1046
1047	bool
1048	pure_location_p (line_maps *set, location_t loc);
1049
1050	/* Given location LOC within SET, strip away any packed range information
1051	or ad-hoc information. */
1052
1053	extern location_t get_pure_location (line_maps *set, location_t loc);
1054
1055	/* Combine LOC and BLOCK, giving a combined adhoc location. */
1056
1057	inline location_t
1058	COMBINE_LOCATION_DATA (class line_maps *set,
1059	location_t loc,
1060	source_range src_range,
1061	void *block)
1062	{
1063	return get_combined_adhoc_loc (set, loc, src_range, block);
1064	}
1065
1066	extern void rebuild_location_adhoc_htab (class line_maps *);
1067
1068	/* Initialize a line map set. SET is the line map set to initialize
1069	and BUILTIN_LOCATION is the special location value to be used as
1070	spelling location for built-in tokens. This BUILTIN_LOCATION has
1071	to be strictly less than RESERVED_LOCATION_COUNT. */
1072	extern void linemap_init (class line_maps *set,
1073	location_t builtin_location);
1074
1075	/* Check for and warn about line_maps entered but not exited. */
1076
1077	extern void linemap_check_files_exited (class line_maps *);
1078
1079	/* Return a location_t for the start (i.e. column==0) of
1080	(physical) line TO_LINE in the current source file (as in the
1081	most recent linemap_add). MAX_COLUMN_HINT is the highest column
1082	number we expect to use in this line (but it does not change
1083	the highest_location). */
1084
1085	extern location_t linemap_line_start
1086	(class line_maps *set, linenum_type to_line, unsigned int max_column_hint);
1087
1088	/* Allocate a raw block of line maps, zero initialized. */
1089	extern line_map *line_map_new_raw (line_maps *, bool, unsigned);
1090
1091	/* Add a mapping of logical source line to physical source file and
1092	line number. This function creates an "ordinary map", which is a
1093	map that records locations of tokens that are not part of macro
1094	replacement-lists present at a macro expansion point.
1095
1096	The text pointed to by TO_FILE must have a lifetime
1097	at least as long as the lifetime of SET. An empty
1098	TO_FILE means standard input. If reason is LC_LEAVE, and
1099	TO_FILE is NULL, then TO_FILE, TO_LINE and SYSP are given their
1100	natural values considering the file we are returning to.
1101
1102	A call to this function can relocate the previous set of
1103	maps, so any stored line_map pointers should not be used. */
1104	extern const line_map *linemap_add
1105	(class line_maps *, enum lc_reason, unsigned int sysp,
1106	const char *to_file, linenum_type to_line);
1107
1108	/* Create a macro map. A macro map encodes source locations of tokens
1109	that are part of a macro replacement-list, at a macro expansion
1110	point. See the extensive comments of struct line_map and struct
1111	line_map_macro, in line-map.h.
1112
1113	This map shall be created when the macro is expanded. The map
1114	encodes the source location of the expansion point of the macro as
1115	well as the "original" source location of each token that is part
1116	of the macro replacement-list. If a macro is defined but never
1117	expanded, it has no macro map. SET is the set of maps the macro
1118	map should be part of. MACRO_NODE is the macro which the new macro
1119	map should encode source locations for. EXPANSION is the location
1120	of the expansion point of MACRO. For function-like macros
1121	invocations, it's best to make it point to the closing parenthesis
1122	of the macro, rather than the the location of the first character
1123	of the macro. NUM_TOKENS is the number of tokens that are part of
1124	the replacement-list of MACRO. */
1125	const line_map_macro *linemap_enter_macro (line_maps *, cpp_hashnode *,
1126	location_t, unsigned int);
1127
1128	/* Create a source location for a module. The creator must either do
1129	this after the TU is tokenized, or deal with saving and restoring
1130	map state. */
1131
1132	extern location_t linemap_module_loc
1133	(line_maps *, location_t from, const char *name);
1134	extern void linemap_module_reparent
1135	(line_maps *, location_t loc, location_t new_parent);
1136
1137	/* Restore the linemap state such that the map at LWM-1 continues.
1138	Return start location of the new map. */
1139	extern unsigned linemap_module_restore
1140	(line_maps *, unsigned lwm);
1141
1142	/* Given a logical source location, returns the map which the
1143	corresponding (source file, line, column) triplet can be deduced
1144	from. Since the set is built chronologically, the logical lines are
1145	monotonic increasing, and so the list is sorted and we can use a
1146	binary search. If no line map have been allocated yet, this
1147	function returns NULL. */
1148	extern const line_map *linemap_lookup
1149	(const line_maps *, location_t);
1150
1151	unsigned linemap_lookup_macro_index (const line_maps *, location_t);
1152
1153	/* Returns TRUE if the line table set tracks token locations across
1154	macro expansion, FALSE otherwise. */
1155	bool linemap_tracks_macro_expansion_locs_p (class line_maps *);
1156
1157	/* Return the name of the macro associated to MACRO_MAP. */
1158	const char* linemap_map_get_macro_name (const line_map_macro *);
1159
1160	/* Return a positive value if LOCATION is the locus of a token that is
1161	located in a system header, O otherwise. It returns 1 if LOCATION
1162	is the locus of a token that is located in a system header, and 2
1163	if LOCATION is the locus of a token located in a C system header
1164	that therefore needs to be extern "C" protected in C++.
1165
1166	Note that this function returns 1 if LOCATION belongs to a token
1167	that is part of a macro replacement-list defined in a system
1168	header, but expanded in a non-system file. */
1169	int linemap_location_in_system_header_p (class line_maps *,
1170	location_t);
1171
1172	/* Return TRUE if LOCATION is a source code location of a token that is part of
1173	a macro expansion, FALSE otherwise. */
1174	bool linemap_location_from_macro_expansion_p (const line_maps *,
1175	location_t);
1176
1177	/* TRUE if LOCATION is a source code location of a token that is part of the
1178	definition of a macro, FALSE otherwise. */
1179	bool linemap_location_from_macro_definition_p (class line_maps *,
1180	location_t);
1181
1182	/* With the precondition that LOCATION is the locus of a token that is
1183	an argument of a function-like macro MACRO_MAP and appears in the
1184	expansion of MACRO_MAP, return the locus of that argument in the
1185	context of the caller of MACRO_MAP. */
1186
1187	extern location_t linemap_macro_map_loc_unwind_toward_spelling
1188	(line_maps *set, const line_map_macro *macro_map, location_t location);
1189
1190	/* location_t values from 0 to RESERVED_LOCATION_COUNT-1 will
1191	be reserved for libcpp user as special values, no token from libcpp
1192	will contain any of those locations. */
1193	const location_t RESERVED_LOCATION_COUNT = 2;
1194
1195	/* Converts a map and a location_t to source line. */
1196	inline linenum_type
1197	SOURCE_LINE (const line_map_ordinary *ord_map, location_t loc)
1198	{
1199	return ((loc - ord_map->start_location)
1200	>> ord_map->m_column_and_range_bits) + ord_map->to_line;
1201	}
1202
1203	/* Convert a map and location_t to source column number. */
1204	inline linenum_type
1205	SOURCE_COLUMN (const line_map_ordinary *ord_map, location_t loc)
1206	{
1207	return ((loc - ord_map->start_location)
1208	& ((1 << ord_map->m_column_and_range_bits) - 1)) >> ord_map->m_range_bits;
1209	}
1210
1211
1212	inline location_t
1213	linemap_included_from (const line_map_ordinary *ord_map)
1214	{
1215	return ord_map->included_from;
1216	}
1217
1218	/* The linemap containing the included-from location of MAP. */
1219	const line_map_ordinary *linemap_included_from_linemap
1220	(line_maps *set, const line_map_ordinary *map);
1221
1222	/* True if the map is at the bottom of the include stack. */
1223
1224	inline bool
1225	MAIN_FILE_P (const line_map_ordinary *ord_map)
1226	{
1227	return ord_map->included_from == 0;
1228	}
1229
1230	/* Encode and return a location_t from a column number. The
1231	source line considered is the last source line used to call
1232	linemap_line_start, i.e, the last source line which a location was
1233	encoded from. */
1234	extern location_t
1235	linemap_position_for_column (class line_maps *, unsigned int);
1236
1237	/* Encode and return a source location from a given line and
1238	column. */
1239	location_t
1240	linemap_position_for_line_and_column (line_maps *set,
1241	const line_map_ordinary *,
1242	linenum_type, unsigned int);
1243
1244	/* Encode and return a location_t starting from location LOC and
1245	shifting it by OFFSET columns. This function does not support
1246	virtual locations. */
1247	location_t
1248	linemap_position_for_loc_and_offset (class line_maps *set,
1249	location_t loc,
1250	unsigned int offset);
1251
1252	/* Return the file this map is for. */
1253	inline const char *
1254	LINEMAP_FILE (const line_map_ordinary *ord_map)
1255	{
1256	return ord_map->to_file;
1257	}
1258
1259	/* Return the line number this map started encoding location from. */
1260	inline linenum_type
1261	LINEMAP_LINE (const line_map_ordinary *ord_map)
1262	{
1263	return ord_map->to_line;
1264	}
1265
1266	/* Return a positive value if map encodes locations from a system
1267	header, 0 otherwise. Returns 1 if MAP encodes locations in a
1268	system header and 2 if it encodes locations in a C system header
1269	that therefore needs to be extern "C" protected in C++. */
1270	inline unsigned char
1271	LINEMAP_SYSP (const line_map_ordinary *ord_map)
1272	{
1273	return ord_map->sysp;
1274	}
1275
1276	const struct line_map *first_map_in_common (line_maps *set,
1277	location_t loc0,
1278	location_t loc1,
1279	location_t *res_loc0,
1280	location_t *res_loc1);
1281
1282	/* Return a positive value if PRE denotes the location of a token that
1283	comes before the token of POST, 0 if PRE denotes the location of
1284	the same token as the token for POST, and a negative value
1285	otherwise. */
1286	int linemap_compare_locations (class line_maps *set,
1287	location_t pre,
1288	location_t post);
1289
1290	/* Return TRUE if LOC_A denotes the location a token that comes
1291	topogically before the token denoted by location LOC_B, or if they
1292	are equal. */
1293	inline bool
1294	linemap_location_before_p (class line_maps *set,
1295	location_t loc_a,
1296	location_t loc_b)
1297	{
1298	return linemap_compare_locations (set, loc_a, loc_b) >= 0;
1299	}
1300
1301	typedef struct
1302	{
1303	/* The name of the source file involved. */
1304	const char *file;
1305
1306	/* The line-location in the source file. */
1307	int line;
1308
1309	int column;
1310
1311	void *data;
1312
1313	/* In a system header?. */
1314	bool sysp;
1315	} expanded_location;
1316
1317	class range_label;
1318
1319	/* A hint to diagnostic_show_locus on how to print a source range within a
1320	rich_location.
1321
1322	Typically this is SHOW_RANGE_WITH_CARET for the 0th range, and
1323	SHOW_RANGE_WITHOUT_CARET for subsequent ranges,
1324	but the Fortran frontend uses SHOW_RANGE_WITH_CARET repeatedly for
1325	printing things like:
1326
1327	x = x + y
1328	1 2
1329	Error: Shapes for operands at (1) and (2) are not conformable
1330
1331	where "1" and "2" are notionally carets. */
1332
1333	enum range_display_kind
1334	{
1335	/* Show the pertinent source line(s), the caret, and underline(s). */
1336	SHOW_RANGE_WITH_CARET,
1337
1338	/* Show the pertinent source line(s) and underline(s), but don't
1339	show the caret (just an underline). */
1340	SHOW_RANGE_WITHOUT_CARET,
1341
1342	/* Just show the source lines; don't show the range itself.
1343	This is for use when displaying some line-insertion fix-it hints (for
1344	showing the user context on the change, for when it doesn't make sense
1345	to highlight the first column on the next line). */
1346	SHOW_LINES_WITHOUT_RANGE
1347	};
1348
1349	/* A location within a rich_location: a caret&range, with
1350	the caret potentially flagged for display, and an optional
1351	label. */
1352
1353	struct location_range
1354	{
1355	location_t m_loc;
1356
1357	enum range_display_kind m_range_display_kind;
1358
1359	/* If non-NULL, the label for this range. */
1360	const range_label *m_label;
1361	};
1362
1363	/* A partially-embedded vec for use within rich_location for storing
1364	ranges and fix-it hints.
1365
1366	Elements [0..NUM_EMBEDDED) are allocated within m_embed, after
1367	that they are within the dynamically-allocated m_extra.
1368
1369	This allows for static allocation in the common case, whilst
1370	supporting the rarer case of an arbitrary number of elements.
1371
1372	Dynamic allocation is not performed unless it's needed. */
1373
1374	template <typename T, int NUM_EMBEDDED>
1375	class semi_embedded_vec
1376	{
1377	public:
1378	semi_embedded_vec ();
1379	~semi_embedded_vec ();
1380
1381	unsigned int count () const { return m_num; }
1382	T& operator[] (int idx);
1383	const T& operator[] (int idx) const;
1384
1385	void push (const T&);
1386	void truncate (int len);
1387
1388	private:
1389	int m_num;
1390	T m_embedded[NUM_EMBEDDED];
1391	int m_alloc;
1392	T *m_extra;
1393	};
1394
1395	/* Constructor for semi_embedded_vec. In particular, no dynamic allocation
1396	is done. */
1397
1398	template <typename T, int NUM_EMBEDDED>
1399	semi_embedded_vec<T, NUM_EMBEDDED>::semi_embedded_vec ()
1400	: m_num (0), m_alloc (0), m_extra (NULL)
1401	{
1402	}
1403
1404	/* semi_embedded_vec's dtor. Release any dynamically-allocated memory. */
1405
1406	template <typename T, int NUM_EMBEDDED>
1407	semi_embedded_vec<T, NUM_EMBEDDED>::~semi_embedded_vec ()
1408	{
1409	XDELETEVEC (m_extra);
1410	}
1411
1412	/* Look up element IDX, mutably. */
1413
1414	template <typename T, int NUM_EMBEDDED>
1415	T&
1416	semi_embedded_vec<T, NUM_EMBEDDED>::operator[] (int idx)
1417	{
1418	linemap_assert (idx < m_num);
1419	if (idx < NUM_EMBEDDED)
1420	return m_embedded[idx];
1421	else
1422	{
1423	linemap_assert (m_extra != NULL);
1424	return m_extra[idx - NUM_EMBEDDED];
1425	}
1426	}
1427
1428	/* Look up element IDX (const). */
1429
1430	template <typename T, int NUM_EMBEDDED>
1431	const T&
1432	semi_embedded_vec<T, NUM_EMBEDDED>::operator[] (int idx) const
1433	{
1434	linemap_assert (idx < m_num);
1435	if (idx < NUM_EMBEDDED)
1436	return m_embedded[idx];
1437	else
1438	{
1439	linemap_assert (m_extra != NULL);
1440	return m_extra[idx - NUM_EMBEDDED];
1441	}
1442	}
1443
1444	/* Append VALUE to the end of the semi_embedded_vec. */
1445
1446	template <typename T, int NUM_EMBEDDED>
1447	void
1448	semi_embedded_vec<T, NUM_EMBEDDED>::push (const T& value)
1449	{
1450	int idx = m_num++;
1451	if (idx < NUM_EMBEDDED)
1452	m_embedded[idx] = value;
1453	else
1454	{
1455	/* Offset "idx" to be an index within m_extra. */
1456	idx -= NUM_EMBEDDED;
1457	if (NULL == m_extra)
1458	{
1459	linemap_assert (m_alloc == 0);
1460	m_alloc = 16;
1461	m_extra = XNEWVEC (T, m_alloc);
1462	}
1463	else if (idx >= m_alloc)
1464	{
1465	linemap_assert (m_alloc > 0);
1466	m_alloc *= 2;
1467	m_extra = XRESIZEVEC (T, m_extra, m_alloc);
1468	}
1469	linemap_assert (m_extra);
1470	linemap_assert (idx < m_alloc);
1471	m_extra[idx] = value;
1472	}
1473	}
1474
1475	/* Truncate to length LEN. No deallocation is performed. */
1476
1477	template <typename T, int NUM_EMBEDDED>
1478	void
1479	semi_embedded_vec<T, NUM_EMBEDDED>::truncate (int len)
1480	{
1481	linemap_assert (len <= m_num);
1482	m_num = len;
1483	}
1484
1485	class fixit_hint;
1486	class diagnostic_path;
1487
1488	/* A "rich" source code location, for use when printing diagnostics.
1489	A rich_location has one or more carets&ranges, where the carets
1490	are optional. These are referred to as "ranges" from here.
1491	Typically the zeroth range has a caret; other ranges sometimes
1492	have carets.
1493
1494	The "primary" location of a rich_location is the caret of range 0,
1495	used for determining the line/column when printing diagnostic
1496	text, such as:
1497
1498	some-file.c:3:1: error: ...etc...
1499
1500	Additional ranges may be added to help the user identify other
1501	pertinent clauses in a diagnostic.
1502
1503	Ranges can (optionally) be given labels via class range_label.
1504
1505	rich_location instances are intended to be allocated on the stack
1506	when generating diagnostics, and to be short-lived.
1507
1508	Examples of rich locations
1509	--------------------------
1510
1511	Example A
1512	*********
1513	int i = "foo";
1514	^
1515	This "rich" location is simply a single range (range 0), with
1516	caret = start = finish at the given point.
1517
1518	Example B
1519	*********
1520	a = (foo && bar)
1521	~~~~~^~~~~~~
1522	This rich location has a single range (range 0), with the caret
1523	at the first "&", and the start/finish at the parentheses.
1524	Compare with example C below.
1525
1526	Example C
1527	*********
1528	a = (foo && bar)
1529	~~~ ^~ ~~~
1530	This rich location has three ranges:
1531	- Range 0 has its caret and start location at the first "&" and
1532	end at the second "&.
1533	- Range 1 has its start and finish at the "f" and "o" of "foo";
1534	the caret is not flagged for display, but is perhaps at the "f"
1535	of "foo".
1536	- Similarly, range 2 has its start and finish at the "b" and "r" of
1537	"bar"; the caret is not flagged for display, but is perhaps at the
1538	"b" of "bar".
1539	Compare with example B above.
1540
1541	Example D (Fortran frontend)
1542	****************************
1543	x = x + y
1544	1 2
1545	This rich location has range 0 at "1", and range 1 at "2".
1546	Both are flagged for caret display. Both ranges have start/finish
1547	equal to their caret point. The frontend overrides the diagnostic
1548	context's default caret character for these ranges.
1549
1550	Example E (range labels)
1551	************************
1552	printf ("arg0: %i arg1: %s arg2: %i",
1553	^~
1554	|
1555	const char *
1556	100, 101, 102);
1557	~~~
1558	|
1559	int
1560	This rich location has two ranges:
1561	- range 0 is at the "%s" with start = caret = "%" and finish at
1562	the "s". It has a range_label ("const char *").
1563	- range 1 has start/finish covering the "101" and is not flagged for
1564	caret printing. The caret is at the start of "101", where its
1565	range_label is printed ("int").
1566
1567	Fix-it hints
1568	------------
1569
1570	Rich locations can also contain "fix-it hints", giving suggestions
1571	for the user on how to edit their code to fix a problem. These
1572	can be expressed as insertions, replacements, and removals of text.
1573	The edits by default are relative to the zeroth range within the
1574	rich_location, but optionally they can be expressed relative to
1575	other locations (using various overloaded methods of the form
1576	rich_location::add_fixit_*).
1577
1578	For example:
1579
1580	Example F: fix-it hint: insert_before
1581	*************************************
1582	ptr = arr[0];
1583	^~~~~~
1584	&
1585	This rich location has a single range (range 0) covering "arr[0]",
1586	with the caret at the start. The rich location has a single
1587	insertion fix-it hint, inserted before range 0, added via
1588	richloc.add_fixit_insert_before ("&");
1589
1590	Example G: multiple fix-it hints: insert_before and insert_after
1591	****************************************************************
1592	#define FN(ARG0, ARG1, ARG2) fn(ARG0, ARG1, ARG2)
1593	^~~~ ^~~~ ^~~~
1594	( ) ( ) ( )
1595	This rich location has three ranges, covering "arg0", "arg1",
1596	and "arg2", all with caret-printing enabled.
1597	The rich location has 6 insertion fix-it hints: each arg
1598	has a pair of insertion fix-it hints, suggesting wrapping
1599	them with parentheses: one a '(' inserted before,
1600	the other a ')' inserted after, added via
1601	richloc.add_fixit_insert_before (LOC, "(");
1602	and
1603	richloc.add_fixit_insert_after (LOC, ")");
1604
1605	Example H: fix-it hint: removal
1606	*******************************
1607	struct s {int i};;
1608	^
1609	-
1610	This rich location has a single range at the stray trailing
1611	semicolon, along with a single removal fix-it hint, covering
1612	the same range, added via:
1613	richloc.add_fixit_remove ();
1614
1615	Example I: fix-it hint: replace
1616	*******************************
1617	c = s.colour;
1618	^~~~~~
1619	color
1620	This rich location has a single range (range 0) covering "colour",
1621	and a single "replace" fix-it hint, covering the same range,
1622	added via
1623	richloc.add_fixit_replace ("color");
1624
1625	Example J: fix-it hint: line insertion
1626	**************************************
1627
1628	3 | #include <stddef.h>
1629	+ |+#include <stdio.h>
1630	4 | int the_next_line;
1631
1632	This rich location has a single range at line 4 column 1, marked
1633	with SHOW_LINES_WITHOUT_RANGE (to avoid printing a meaningless caret
1634	on the "i" of int). It has a insertion fix-it hint of the string
1635	"#include <stdio.h>\n".
1636
1637	Adding a fix-it hint can fail: for example, attempts to insert content
1638	at the transition between two line maps may fail due to there being no
1639	location_t value to express the new location.
1640
1641	Attempts to add a fix-it hint within a macro expansion will fail.
1642
1643	There is only limited support for newline characters in fix-it hints:
1644	only hints with newlines which insert an entire new line are permitted,
1645	inserting at the start of a line, and finishing with a newline
1646	(with no interior newline characters). Other attempts to add
1647	fix-it hints containing newline characters will fail.
1648	Similarly, attempts to delete or replace a range *affecting* multiple
1649	lines will fail.
1650
1651	The rich_location API handles these failures gracefully, so that
1652	diagnostics can attempt to add fix-it hints without each needing
1653	extensive checking.
1654
1655	Fix-it hints within a rich_location are "atomic": if any hints can't
1656	be applied, none of them will be (tracked by the m_seen_impossible_fixit
1657	flag), and no fix-its hints will be displayed for that rich_location.
1658	This implies that diagnostic messages need to be worded in such a way
1659	that they make sense whether or not the fix-it hints are displayed,
1660	or that richloc.seen_impossible_fixit_p () should be checked before
1661	issuing the diagnostics. */
1662
1663	class rich_location
1664	{
1665	public:
1666	/* Constructors. */
1667
1668	/* Constructing from a location. */
1669	rich_location (line_maps *set, location_t loc,
1670	const range_label *label = NULL);
1671
1672	/* Destructor. */
1673	~rich_location ();
1674
1675	/* The class manages the memory pointed to by the elements of
1676	the M_FIXIT_HINTS vector and is not meant to be copied or
1677	assigned. */
1678	rich_location (const rich_location &) = delete;
1679	void operator= (const rich_location &) = delete;
1680
1681	/* Accessors. */
1682	location_t get_loc () const { return get_loc (0); }
1683	location_t get_loc (unsigned int idx) const;
1684
1685	void
1686	add_range (location_t loc,
1687	enum range_display_kind range_display_kind
1688	= SHOW_RANGE_WITHOUT_CARET,
1689	const range_label *label = NULL);
1690
1691	void
1692	set_range (unsigned int idx, location_t loc,
1693	enum range_display_kind range_display_kind);
1694
1695	unsigned int get_num_locations () const { return m_ranges.count (); }
1696
1697	const location_range *get_range (unsigned int idx) const;
1698	location_range *get_range (unsigned int idx);
1699
1700	expanded_location get_expanded_location (unsigned int idx);
1701
1702	void
1703	override_column (int column);
1704
1705	/* Fix-it hints. */
1706
1707	/* Methods for adding insertion fix-it hints. */
1708
1709	/* Suggest inserting NEW_CONTENT immediately before the primary
1710	range's start. */
1711	void
1712	add_fixit_insert_before (const char *new_content);
1713
1714	/* Suggest inserting NEW_CONTENT immediately before the start of WHERE. */
1715	void
1716	add_fixit_insert_before (location_t where,
1717	const char *new_content);
1718
1719	/* Suggest inserting NEW_CONTENT immediately after the end of the primary
1720	range. */
1721	void
1722	add_fixit_insert_after (const char *new_content);
1723
1724	/* Suggest inserting NEW_CONTENT immediately after the end of WHERE. */
1725	void
1726	add_fixit_insert_after (location_t where,
1727	const char *new_content);
1728
1729	/* Methods for adding removal fix-it hints. */
1730
1731	/* Suggest removing the content covered by range 0. */
1732	void
1733	add_fixit_remove ();
1734
1735	/* Suggest removing the content covered between the start and finish
1736	of WHERE. */
1737	void
1738	add_fixit_remove (location_t where);
1739
1740	/* Suggest removing the content covered by SRC_RANGE. */
1741	void
1742	add_fixit_remove (source_range src_range);
1743
1744	/* Methods for adding "replace" fix-it hints. */
1745
1746	/* Suggest replacing the content covered by range 0 with NEW_CONTENT. */
1747	void
1748	add_fixit_replace (const char *new_content);
1749
1750	/* Suggest replacing the content between the start and finish of
1751	WHERE with NEW_CONTENT. */
1752	void
1753	add_fixit_replace (location_t where,
1754	const char *new_content);
1755
1756	/* Suggest replacing the content covered by SRC_RANGE with
1757	NEW_CONTENT. */
1758	void
1759	add_fixit_replace (source_range src_range,
1760	const char *new_content);
1761
1762	unsigned int get_num_fixit_hints () const { return m_fixit_hints.count (); }
1763	fixit_hint *get_fixit_hint (int idx) const { return m_fixit_hints[idx]; }
1764	fixit_hint *get_last_fixit_hint () const;
1765	bool seen_impossible_fixit_p () const { return m_seen_impossible_fixit; }
1766
1767	/* Set this if the fix-it hints are not suitable to be
1768	automatically applied.
1769
1770	For example, if you are suggesting more than one
1771	mutually exclusive solution to a problem, then
1772	it doesn't make sense to apply all of the solutions;
1773	manual intervention is required.
1774
1775	If set, then the fix-it hints in the rich_location will
1776	be printed, but will not be added to generated patches,
1777	or affect the modified version of the file. */
1778	void fixits_cannot_be_auto_applied ()
1779	{
1780	m_fixits_cannot_be_auto_applied = true;
1781	}
1782
1783	bool fixits_can_be_auto_applied_p () const
1784	{
1785	return !m_fixits_cannot_be_auto_applied;
1786	}
1787
1788	/* An optional path through the code. */
1789	const diagnostic_path *get_path () const { return m_path; }
1790	void set_path (const diagnostic_path *path) { m_path = path; }
1791
1792	/* A flag for hinting that the diagnostic involves character encoding
1793	issues, and thus that it will be helpful to the user if we show some
1794	representation of how the characters in the pertinent source lines
1795	are encoded.
1796	The default is false (i.e. do not escape).
1797	When set to true, non-ASCII bytes in the pertinent source lines will
1798	be escaped in a manner controlled by the user-supplied option
1799	-fdiagnostics-escape-format=, so that the user can better understand
1800	what's going on with the encoding in their source file. */
1801	bool escape_on_output_p () const { return m_escape_on_output; }
1802	void set_escape_on_output (bool flag) { m_escape_on_output = flag; }
1803
1804	private:
1805	bool reject_impossible_fixit (location_t where);
1806	void stop_supporting_fixits ();
1807	void maybe_add_fixit (location_t start,
1808	location_t next_loc,
1809	const char *new_content);
1810
1811	public:
1812	static const int STATICALLY_ALLOCATED_RANGES = 3;
1813
1814	protected:
1815	line_maps *m_line_table;
1816	semi_embedded_vec <location_range, STATICALLY_ALLOCATED_RANGES> m_ranges;
1817
1818	int m_column_override;
1819
1820	bool m_have_expanded_location;
1821	bool m_seen_impossible_fixit;
1822	bool m_fixits_cannot_be_auto_applied;
1823	bool m_escape_on_output;
1824
1825	expanded_location m_expanded_location;
1826
1827	static const int MAX_STATIC_FIXIT_HINTS = 2;
1828	semi_embedded_vec <fixit_hint *, MAX_STATIC_FIXIT_HINTS> m_fixit_hints;
1829
1830	const diagnostic_path *m_path;
1831	};
1832
1833	/* A struct for the result of range_label::get_text: a NUL-terminated buffer
1834	of localized text, and a flag to determine if the caller should "free" the
1835	buffer. */
1836
1837	class label_text
1838	{
1839	public:
1840	label_text ()
1841	: m_buffer (NULL), m_owned (false)
1842	{}
1843
1844	~label_text ()
1845	{
1846	if (m_owned)
1847	free (m_buffer);
1848	}
1849
1850	/* Move ctor. */
1851	label_text (label_text &&other)
1852	: m_buffer (other.m_buffer), m_owned (other.m_owned)
1853	{
1854	other.release ();
1855	}
1856
1857	/* Move assignment. */
1858	label_text & operator= (label_text &&other)
1859	{
1860	if (m_owned)
1861	free (m_buffer);
1862	m_buffer = other.m_buffer;
1863	m_owned = other.m_owned;
1864	other.release ();
1865	return *this;
1866	}
1867
1868	/* Delete the copy ctor and copy-assignment operator. */
1869	label_text (const label_text &) = delete;
1870	label_text & operator= (const label_text &) = delete;
1871
1872	/* Create a label_text instance that borrows BUFFER from a
1873	longer-lived owner. */
1874	static label_text borrow (const char *buffer)
1875	{
1876	return label_text (const_cast <char *> (buffer), false);
1877	}
1878
1879	/* Create a label_text instance that takes ownership of BUFFER. */
1880	static label_text take (char *buffer)
1881	{
1882	return label_text (buffer, true);
1883	}
1884
1885	void release ()
1886	{
1887	m_buffer = NULL;
1888	m_owned = false;
1889	}
1890
1891	const char *get () const
1892	{
1893	return m_buffer;
1894	}
1895
1896	bool is_owner () const
1897	{
1898	return m_owned;
1899	}
1900
1901	private:
1902	char *m_buffer;
1903	bool m_owned;
1904
1905	label_text (char *buffer, bool owned)
1906	: m_buffer (buffer), m_owned (owned)
1907	{}
1908	};
1909
1910	/* Abstract base class for labelling a range within a rich_location
1911	(e.g. for labelling expressions with their type).
1912
1913	Generating the text could require non-trivial work, so this work
1914	is delayed (via the "get_text" virtual function) until the diagnostic
1915	printing code "knows" it needs it, thus avoiding doing it e.g. for
1916	warnings that are filtered by command-line flags. This virtual
1917	function also isolates libcpp and the diagnostics subsystem from
1918	the front-end and middle-end-specific code for generating the text
1919	for the labels.
1920
1921	Like the rich_location instances they annotate, range_label instances
1922	are intended to be allocated on the stack when generating diagnostics,
1923	and to be short-lived. */
1924
1925	class range_label
1926	{
1927	public:
1928	virtual ~range_label () {}
1929
1930	/* Get localized text for the label.
1931	The RANGE_IDX is provided, allowing for range_label instances to be
1932	shared by multiple ranges if need be (the "flyweight" design pattern). */
1933	virtual label_text get_text (unsigned range_idx) const = 0;
1934	};
1935
1936	/* A fix-it hint: a suggested insertion, replacement, or deletion of text.
1937	We handle these three types of edit with one class, by representing
1938	them as replacement of a half-open range:
1939	[start, next_loc)
1940	Insertions have start == next_loc: "replace" the empty string at the
1941	start location with the new string.
1942	Deletions are replacement with the empty string.
1943
1944	There is only limited support for newline characters in fix-it hints
1945	as noted above in the comment for class rich_location.
1946	A fixit_hint instance can have at most one newline character; if
1947	present, the newline character must be the final character of
1948	the content (preventing e.g. fix-its that split a pre-existing line). */
1949
1950	class fixit_hint
1951	{
1952	public:
1953	fixit_hint (location_t start,
1954	location_t next_loc,
1955	const char *new_content);
1956	~fixit_hint () { free (m_bytes); }
1957
1958	bool affects_line_p (const char *file, int line) const;
1959	location_t get_start_loc () const { return m_start; }
1960	location_t get_next_loc () const { return m_next_loc; }
1961	bool maybe_append (location_t start,
1962	location_t next_loc,
1963	const char *new_content);
1964
1965	const char *get_string () const { return m_bytes; }
1966	size_t get_length () const { return m_len; }
1967
1968	bool insertion_p () const { return m_start == m_next_loc; }
1969
1970	bool ends_with_newline_p () const;
1971
1972	private:
1973	/* We don't use source_range here since, unlike most places,
1974	this is a half-open/half-closed range:
1975	[start, next_loc)
1976	so that we can support insertion via start == next_loc. */
1977	location_t m_start;
1978	location_t m_next_loc;
1979	char *m_bytes;
1980	size_t m_len;
1981	};
1982
1983
1984	/* This is enum is used by the function linemap_resolve_location
1985	below. The meaning of the values is explained in the comment of
1986	that function. */
1987	enum location_resolution_kind
1988	{
1989	LRK_MACRO_EXPANSION_POINT,
1990	LRK_SPELLING_LOCATION,
1991	LRK_MACRO_DEFINITION_LOCATION
1992	};
1993
1994	/* Resolve a virtual location into either a spelling location, an
1995	expansion point location or a token argument replacement point
1996	location. Return the map that encodes the virtual location as well
1997	as the resolved location.
1998
1999	If LOC is *NOT* the location of a token resulting from the
2000	expansion of a macro, then the parameter LRK (which stands for
2001	Location Resolution Kind) is ignored and the resulting location
2002	just equals the one given in argument.
2003
2004	Now if LOC *IS* the location of a token resulting from the
2005	expansion of a macro, this is what happens.
2006
2007	* If LRK is set to LRK_MACRO_EXPANSION_POINT
2008	-------------------------------
2009
2010	The virtual location is resolved to the first macro expansion point
2011	that led to this macro expansion.
2012
2013	* If LRK is set to LRK_SPELLING_LOCATION
2014	-------------------------------------
2015
2016	The virtual location is resolved to the locus where the token has
2017	been spelled in the source. This can follow through all the macro
2018	expansions that led to the token.
2019
2020	* If LRK is set to LRK_MACRO_DEFINITION_LOCATION
2021	--------------------------------------
2022
2023	The virtual location is resolved to the locus of the token in the
2024	context of the macro definition.
2025
2026	If LOC is the locus of a token that is an argument of a
2027	function-like macro [replacing a parameter in the replacement list
2028	of the macro] the virtual location is resolved to the locus of the
2029	parameter that is replaced, in the context of the definition of the
2030	macro.
2031
2032	If LOC is the locus of a token that is not an argument of a
2033	function-like macro, then the function behaves as if LRK was set to
2034	LRK_SPELLING_LOCATION.
2035
2036	If LOC_MAP is not NULL, *LOC_MAP is set to the map encoding the
2037	returned location. Note that if the returned location wasn't originally
2038	encoded by a map, the *MAP is set to NULL. This can happen if LOC
2039	resolves to a location reserved for the client code, like
2040	UNKNOWN_LOCATION or BUILTINS_LOCATION in GCC. */
2041
2042	location_t linemap_resolve_location (class line_maps *,
2043	location_t loc,
2044	enum location_resolution_kind lrk,
2045	const line_map_ordinary **loc_map);
2046
2047	/* Suppose that LOC is the virtual location of a token coming from the
2048	expansion of a macro M. This function then steps up to get the
2049	location L of the point where M got expanded. If L is a spelling
2050	location inside a macro expansion M', then this function returns
2051	the point where M' was expanded. LOC_MAP is an output parameter.
2052	When non-NULL, *LOC_MAP is set to the map of the returned
2053	location. */
2054	location_t linemap_unwind_toward_expansion (class line_maps *,
2055	location_t loc,
2056	const line_map **loc_map);
2057
2058	/* If LOC is the virtual location of a token coming from the expansion
2059	of a macro M and if its spelling location is reserved (e.g, a
2060	location for a built-in token), then this function unwinds (using
2061	linemap_unwind_toward_expansion) the location until a location that
2062	is not reserved and is not in a system header is reached. In other
2063	words, this unwinds the reserved location until a location that is
2064	in real source code is reached.
2065
2066	Otherwise, if the spelling location for LOC is not reserved or if
2067	LOC doesn't come from the expansion of a macro, the function
2068	returns LOC as is and *MAP is not touched.
2069
2070	*MAP is set to the map of the returned location if the later is
2071	different from LOC. */
2072	location_t linemap_unwind_to_first_non_reserved_loc (class line_maps *,
2073	location_t loc,
2074	const line_map **map);
2075
2076	/* Expand source code location LOC and return a user readable source
2077	code location. LOC must be a spelling (non-virtual) location. If
2078	it's a location < RESERVED_LOCATION_COUNT a zeroed expanded source
2079	location is returned. */
2080	expanded_location linemap_expand_location (class line_maps *,
2081	const line_map *,
2082	location_t loc);
2083
2084	/* Statistics about maps allocation and usage as returned by
2085	linemap_get_statistics. */
2086	struct linemap_stats
2087	{
2088	long num_ordinary_maps_allocated;
2089	long num_ordinary_maps_used;
2090	long ordinary_maps_allocated_size;
2091	long ordinary_maps_used_size;
2092	long num_expanded_macros;
2093	long num_macro_tokens;
2094	long num_macro_maps_used;
2095	long macro_maps_allocated_size;
2096	long macro_maps_used_size;
2097	long macro_maps_locations_size;
2098	long duplicated_macro_maps_locations_size;
2099	long adhoc_table_size;
2100	long adhoc_table_entries_used;
2101	};
2102
2103	/* Return the highest location emitted for a given file for which
2104	there is a line map in SET. FILE_NAME is the file name to
2105	consider. If the function returns TRUE, *LOC is set to the highest
2106	location emitted for that file. */
2107	bool linemap_get_file_highest_location (class line_maps * set,
2108	const char *file_name,
2109	location_t *loc);
2110
2111	/* Compute and return statistics about the memory consumption of some
2112	parts of the line table SET. */
2113	void linemap_get_statistics (line_maps *, struct linemap_stats *);
2114
2115	/* Dump debugging information about source location LOC into the file
2116	stream STREAM. SET is the line map set LOC comes from. */
2117	void linemap_dump_location (line_maps *, location_t, FILE *);
2118
2119	/* Dump line map at index IX in line table SET to STREAM. If STREAM
2120	is NULL, use stderr. IS_MACRO is true if the caller wants to
2121	dump a macro map, false otherwise. */
2122	void linemap_dump (FILE *, line_maps *, unsigned, bool);
2123
2124	/* Dump line table SET to STREAM. If STREAM is NULL, stderr is used.
2125	NUM_ORDINARY specifies how many ordinary maps to dump. NUM_MACRO
2126	specifies how many macro maps to dump. */
2127	void line_table_dump (FILE *, line_maps *, unsigned int, unsigned int);
2128
2129	/* An enum for distinguishing the various parts within a location_t. */
2130
2131	enum location_aspect
2132	{
2133	LOCATION_ASPECT_CARET,
2134	LOCATION_ASPECT_START,
2135	LOCATION_ASPECT_FINISH
2136	};
2137
2138	/* The rich_location class requires a way to expand location_t instances.
2139	We would directly use expand_location_to_spelling_point, which is
2140	implemented in gcc/input.cc, but we also need to use it for rich_location
2141	within genmatch.cc.
2142	Hence we require client code of libcpp to implement the following
2143	symbol. */
2144	extern expanded_location
2145	linemap_client_expand_location_to_spelling_point (location_t,
2146	enum location_aspect);
2147
2148	#endif /* !LIBCPP_LINE_MAP_H */
2149