File : g-forstr.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- G N A T . F O R M A T T E D _ S T R I N G --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2014-2016, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This package add support for formatted string as supported by C printf()
33
34 -- A simple usage is:
35 --
36 -- Put_Line (-(+"%s" & "a string"));
37 --
38 -- or with a constant for the format:
39 --
40 -- declare
41 -- Format : constant Formatted_String := +"%s";
42 -- begin
43 -- Put_Line (-(Format & "a string"));
44 -- end;
45 --
46 -- Finally a more complex example:
47 --
48 -- declare
49 -- F : Formatted_String := +"['%c' ; %10d]";
50 -- C : Character := 'v';
51 -- I : Integer := 98;
52 -- begin
53 -- F := F & C & I;
54 -- Put_Line (-F);
55 -- end;
56
57 -- Which will display:
58
59 -- ['v' ; 98]
60
61 -- Each format specifier is: %[flags][width][.precision][length]specifier
62
63 -- Specifiers:
64 -- d or i Signed decimal integer
65 -- u Unsigned decimal integer
66 -- o Unsigned octal
67 -- x Unsigned hexadecimal integer
68 -- X Unsigned hexadecimal integer (uppercase)
69 -- f Decimal floating point, lowercase
70 -- F Decimal floating point, uppercase
71 -- e Scientific notation (mantissa/exponent), lowercase
72 -- E Scientific notation (mantissa/exponent), uppercase
73 -- g Use the shortest representation: %e or %f
74 -- G Use the shortest representation: %E or %F
75 -- c Character
76 -- s String of characters
77 -- p Pointer address
78 -- % A % followed by another % character will write a single %
79
80 -- Flags:
81
82 -- - Left-justify within the given field width;
83 -- Right justification is the default.
84
85 -- + Forces to preceed the result with a plus or minus sign (+ or -)
86 -- even for positive numbers. By default, only negative numbers
87 -- are preceded with a - sign.
88
89 -- (space) If no sign is going to be written, a blank space is inserted
90 -- before the value.
91
92 -- # Used with o, x or X specifiers the value is preceeded with
93 -- 0, 0x or 0X respectively for values different than zero.
94 -- Used with a, A, e, E, f, F, g or G it forces the written
95 -- output to contain a decimal point even if no more digits
96 -- follow. By default, if no digits follow, no decimal point is
97 -- written.
98
99 -- ~ As above, but using Ada style based <base>#<number>#
100
101 -- 0 Left-pads the number with zeroes (0) instead of spaces when
102 -- padding is specified.
103
104 -- Width:
105 -- number Minimum number of characters to be printed. If the value to
106 -- be printed is shorter than this number, the result is padded
107 -- with blank spaces. The value is not truncated even if the
108 -- result is larger.
109
110 -- * The width is not specified in the format string, but as an
111 -- additional integer value argument preceding the argument that
112 -- has to be formatted.
113 -- Precision:
114 -- number For integer specifiers (d, i, o, u, x, X): precision specifies
115 -- the minimum number of digits to be written. If the value to be
116 -- written is shorter than this number, the result is padded with
117 -- leading zeros. The value is not truncated even if the result
118 -- is longer. A precision of 0 means that no character is written
119 -- for the value 0.
120
121 -- For e, E, f and F specifiers: this is the number of digits to
122 -- be printed after the decimal point (by default, this is 6).
123 -- For g and G specifiers: This is the maximum number of
124 -- significant digits to be printed.
125
126 -- For s: this is the maximum number of characters to be printed.
127 -- By default all characters are printed until the ending null
128 -- character is encountered.
129
130 -- If the period is specified without an explicit value for
131 -- precision, 0 is assumed.
132
133 -- .* The precision is not specified in the format string, but as an
134 -- additional integer value argument preceding the argument that
135 -- has to be formatted.
136
137 with Ada.Text_IO;
138 with System;
139
140 private with Ada.Finalization;
141 private with Ada.Strings.Unbounded;
142
143 package GNAT.Formatted_String is
144 use Ada;
145
146 type Formatted_String (<>) is private;
147 -- A format string as defined for printf routine. This string is the
148 -- actual format for all the parameters added with the "&" routines below.
149 -- Note that a Formatted_String object can't be reused as it serves as
150 -- recipient for the final result. That is, each use of "&" will build
151 -- incrementally the final result string which can be retrieved with
152 -- the "-" routine below.
153
154 Format_Error : exception;
155 -- Raised for every mismatch between the parameter and the expected format
156 -- and for malformed format.
157
158 function "+" (Format : String) return Formatted_String;
159 -- Create the format string
160
161 function "-" (Format : Formatted_String) return String;
162 -- Get the result of the formatted string corresponding to the current
163 -- rendering (up to the last parameter formated).
164
165 function "&"
166 (Format : Formatted_String;
167 Var : Character) return Formatted_String;
168 -- A character, expect a %c
169
170 function "&"
171 (Format : Formatted_String;
172 Var : String) return Formatted_String;
173 -- A string, expect a %s
174
175 function "&"
176 (Format : Formatted_String;
177 Var : Boolean) return Formatted_String;
178 -- A boolean image, expect a %s
179
180 function "&"
181 (Format : Formatted_String;
182 Var : Integer) return Formatted_String;
183 -- An integer, expect a %d, %o, %x, %X
184
185 function "&"
186 (Format : Formatted_String;
187 Var : Long_Integer) return Formatted_String;
188 -- As above
189
190 function "&"
191 (Format : Formatted_String;
192 Var : System.Address) return Formatted_String;
193 -- An address, expect a %p
194
195 function "&"
196 (Format : Formatted_String;
197 Var : Float) return Formatted_String;
198 -- A float, expect %f, %e, %F, %E, %g, %G
199
200 function "&"
201 (Format : Formatted_String;
202 Var : Long_Float) return Formatted_String;
203 -- As above
204
205 function "&"
206 (Format : Formatted_String;
207 Var : Duration) return Formatted_String;
208 -- As above
209
210 -- Some generics
211
212 generic
213 type Int is range <>;
214
215 with procedure Put
216 (To : out String;
217 Item : Int;
218 Base : Text_IO.Number_Base);
219 function Int_Format
220 (Format : Formatted_String;
221 Var : Int) return Formatted_String;
222 -- As for Integer above
223
224 generic
225 type Int is mod <>;
226
227 with procedure Put
228 (To : out String;
229 Item : Int;
230 Base : Text_IO.Number_Base);
231 function Mod_Format
232 (Format : Formatted_String;
233 Var : Int) return Formatted_String;
234 -- As for Integer above
235
236 generic
237 type Flt is digits <>;
238
239 with procedure Put
240 (To : out String;
241 Item : Flt;
242 Aft : Text_IO.Field;
243 Exp : Text_IO.Field);
244 function Flt_Format
245 (Format : Formatted_String;
246 Var : Flt) return Formatted_String;
247 -- As for Float above
248
249 generic
250 type Flt is delta <>;
251
252 with procedure Put
253 (To : out String;
254 Item : Flt;
255 Aft : Text_IO.Field;
256 Exp : Text_IO.Field);
257 function Fixed_Format
258 (Format : Formatted_String;
259 Var : Flt) return Formatted_String;
260 -- As for Float above
261
262 generic
263 type Flt is delta <> digits <>;
264
265 with procedure Put
266 (To : out String;
267 Item : Flt;
268 Aft : Text_IO.Field;
269 Exp : Text_IO.Field);
270 function Decimal_Format
271 (Format : Formatted_String;
272 Var : Flt) return Formatted_String;
273 -- As for Float above
274
275 generic
276 type Enum is (<>);
277 function Enum_Format
278 (Format : Formatted_String;
279 Var : Enum) return Formatted_String;
280 -- As for String above, output the string representation of the enumeration
281
282 private
283 use Ada.Strings.Unbounded;
284
285 type I_Vars is array (Positive range 1 .. 2) of Integer;
286 -- Used to keep 2 numbers for the possible * for the width and precision
287
288 type Data (Size : Natural) is record
289 Ref_Count : Natural := 1;
290 Format : String (1 .. Size); -- the format string
291 Index : Positive := 1; -- format index for next value
292 Result : Unbounded_String; -- current value
293 Current : Natural; -- the current format number
294 Stored_Value : Natural := 0; -- number of stored values in Stack
295 Stack : I_Vars;
296 end record;
297
298 type Data_Access is access Data;
299
300 -- The formatted string record is controlled and do not need an initialize
301 -- as it requires an explit initial value. This is given with "+" and
302 -- properly initialize the record at this point.
303
304 type Formatted_String is new Finalization.Controlled with record
305 D : Data_Access;
306 end record;
307
308 overriding procedure Adjust (F : in out Formatted_String);
309 overriding procedure Finalize (F : in out Formatted_String);
310
311 end GNAT.Formatted_String;