1) Added BIT0, BIT1, …, BIT63 to the Base Defines
[mirror_edk2.git] / MdePkg / Include / Library / PrintLib.h
1 /** @file
2 Library that provides print services
3
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: PrintLib.h
14
15 **/
16
17 #ifndef __PRINT_LIB_H__
18 #define __PRINT_LIB_H__
19
20 ///
21 /// Define the maximum number of characters that are required to
22 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
23 /// terminator.
24 ///
25 /// Maximum Length Decimal String = 28
26 /// "-9,223,372,036,854,775,808"
27 /// Maximum Length Hexidecimal String = 17
28 /// "FFFFFFFFFFFFFFFF"
29 /// Maximum Length GUID = 37
30 /// "00000000-0000-0000-0000-000000000000"
31 /// Maximum Length TIME = 18
32 /// "12/12/2006 12:12"
33 ///
34 #define MAXIMUM_VALUE_CHARACTERS 38
35
36 ///
37 /// Flags bitmask values use in UnicodeValueToString() and
38 /// AcsiiValueToString()
39 ///
40 #define LEFT_JUSTIFY 0x01
41 #define COMMA_TYPE 0x08
42 #define PREFIX_ZERO 0x20
43 #define RADIX_HEX 0x80
44
45 /**
46 Produces a Null-terminated Unicode string in an output buffer based on
47 a Null-terminated Unicode format string and a VA_LIST argument list
48
49 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
50 and BufferSize.
51 The Unicode string is produced by parsing the format string specified by FormatString.
52 Arguments are pulled from the variable argument list specified by Marker based on the
53 contents of the format string.
54 The number of Unicode characters in the produced output buffer is returned not including
55 the Null-terminator.
56 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
57
58 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
59 If BufferSize > 1 and FormatString is NULL, then ASSERT().
60 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
61 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
62 ASSERT().
63 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
64 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
65 Null-terminator, then ASSERT().
66
67 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
68 Unicode string.
69 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
70 @param FormatString Null-terminated Unicode format string.
71 @param Marker VA_LIST marker for the variable argument list.
72
73 @return The number of Unicode characters in the produced output buffer not including the
74 Null-terminator.
75
76 **/
77 UINTN
78 EFIAPI
79 UnicodeVSPrint (
80 OUT CHAR16 *StartOfBuffer,
81 IN UINTN BufferSize,
82 IN CONST CHAR16 *FormatString,
83 IN VA_LIST Marker
84 );
85
86 /**
87 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
88 Unicode format string and variable argument list.
89
90 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
91 and BufferSize.
92 The Unicode string is produced by parsing the format string specified by FormatString.
93 Arguments are pulled from the variable argument list based on the contents of the format string.
94 The number of Unicode characters in the produced output buffer is returned not including
95 the Null-terminator.
96 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
97
98 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
99 If BufferSize > 1 and FormatString is NULL, then ASSERT().
100 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
101 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
102 ASSERT().
103 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
104 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
105 Null-terminator, then ASSERT().
106
107 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
108 Unicode string.
109 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
110 @param FormatString Null-terminated Unicode format string.
111
112 @return The number of Unicode characters in the produced output buffer not including the
113 Null-terminator.
114
115 **/
116 UINTN
117 EFIAPI
118 UnicodeSPrint (
119 OUT CHAR16 *StartOfBuffer,
120 IN UINTN BufferSize,
121 IN CONST CHAR16 *FormatString,
122 ...
123 );
124
125 /**
126 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
127 ASCII format string and a VA_LIST argument list
128
129 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
130 and BufferSize.
131 The Unicode string is produced by parsing the format string specified by FormatString.
132 Arguments are pulled from the variable argument list specified by Marker based on the
133 contents of the format string.
134 The number of Unicode characters in the produced output buffer is returned not including
135 the Null-terminator.
136 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
137
138 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
139 If BufferSize > 1 and FormatString is NULL, then ASSERT().
140 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
141 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
142 ASSERT().
143 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
144 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
145 Null-terminator, then ASSERT().
146
147 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
148 Unicode string.
149 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
150 @param FormatString Null-terminated Unicode format string.
151 @param Marker VA_LIST marker for the variable argument list.
152
153 @return The number of Unicode characters in the produced output buffer not including the
154 Null-terminator.
155
156 **/
157 UINTN
158 EFIAPI
159 UnicodeVSPrintAsciiFormat (
160 OUT CHAR16 *StartOfBuffer,
161 IN UINTN BufferSize,
162 IN CONST CHAR8 *FormatString,
163 IN VA_LIST Marker
164 );
165
166 /**
167 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
168 ASCII format string and variable argument list.
169
170 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
171 and BufferSize.
172 The Unicode string is produced by parsing the format string specified by FormatString.
173 Arguments are pulled from the variable argument list based on the contents of the
174 format string.
175 The number of Unicode characters in the produced output buffer is returned not including
176 the Null-terminator.
177 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
178
179 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
180 If BufferSize > 1 and FormatString is NULL, then ASSERT().
181 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
182 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
183 ASSERT().
184 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
185 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
186 Null-terminator, then ASSERT().
187
188 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
189 Unicode string.
190 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
191 @param FormatString Null-terminated Unicode format string.
192
193 @return The number of Unicode characters in the produced output buffer not including the
194 Null-terminator.
195
196 **/
197 UINTN
198 EFIAPI
199 UnicodeSPrintAsciiFormat (
200 OUT CHAR16 *StartOfBuffer,
201 IN UINTN BufferSize,
202 IN CONST CHAR8 *FormatString,
203 ...
204 );
205
206 /**
207 Converts a decimal value to a Null-terminated Unicode string.
208
209 Converts the decimal number specified by Value to a Null-terminated Unicode
210 string specified by Buffer containing at most Width characters. No padding of spaces
211 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
212 The number of Unicode characters in Buffer is returned not including the Null-terminator.
213 If the conversion contains more than Width characters, then only the first
214 Width characters are returned, and the total number of characters
215 required to perform the conversion is returned.
216 Additional conversion parameters are specified in Flags.
217
218 The Flags bit LEFT_JUSTIFY is always ignored.
219 All conversions are left justified in Buffer.
220 If Width is 0, PREFIX_ZERO is ignored in Flags.
221 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
222 are inserted every 3rd digit starting from the right.
223 If HEX_RADIX is set in Flags, then the output buffer will be
224 formatted in hexadecimal format.
225 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
226 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
227 then Buffer is padded with '0' characters so the combination of the optional '-'
228 sign character, '0' characters, digit characters for Value, and the Null-terminator
229 add up to Width characters.
230 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
231 If Buffer is NULL, then ASSERT().
232 If unsupported bits are set in Flags, then ASSERT().
233 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
234 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
235
236 @param Buffer Pointer to the output buffer for the produced Null-terminated
237 Unicode string.
238 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
239 @param Value The 64-bit signed value to convert to a string.
240 @param Width The maximum number of Unicode characters to place in Buffer, not including
241 the Null-terminator.
242
243 @return The number of Unicode characters in Buffer not including the Null-terminator.
244
245 **/
246 UINTN
247 EFIAPI
248 UnicodeValueToString (
249 IN OUT CHAR16 *Buffer,
250 IN UINTN Flags,
251 IN INT64 Value,
252 IN UINTN Width
253 );
254
255 /**
256 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
257 ASCII format string and a VA_LIST argument list.
258
259 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
260 and BufferSize.
261 The ASCII string is produced by parsing the format string specified by FormatString.
262 Arguments are pulled from the variable argument list specified by Marker based on
263 the contents of the format string.
264 The number of ASCII characters in the produced output buffer is returned not including
265 the Null-terminator.
266 If BufferSize is 0, then no output buffer is produced and 0 is returned.
267
268 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
269 If BufferSize > 0 and FormatString is NULL, then ASSERT().
270 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
271 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
272 ASSERT().
273 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
274 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
275 Null-terminator, then ASSERT().
276
277 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
278 ASCII string.
279 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
280 @param FormatString Null-terminated Unicode format string.
281 @param Marker VA_LIST marker for the variable argument list.
282
283 @return The number of ASCII characters in the produced output buffer not including the
284 Null-terminator.
285
286 **/
287 UINTN
288 EFIAPI
289 AsciiVSPrint (
290 OUT CHAR8 *StartOfBuffer,
291 IN UINTN BufferSize,
292 IN CONST CHAR8 *FormatString,
293 IN VA_LIST Marker
294 );
295
296 /**
297 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
298 ASCII format string and variable argument list.
299
300 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
301 and BufferSize.
302 The ASCII string is produced by parsing the format string specified by FormatString.
303 Arguments are pulled from the variable argument list based on the contents of the
304 format string.
305 The number of ASCII characters in the produced output buffer is returned not including
306 the Null-terminator.
307 If BufferSize is 0, then no output buffer is produced and 0 is returned.
308
309 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
310 If BufferSize > 0 and FormatString is NULL, then ASSERT().
311 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
312 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
313 ASSERT().
314 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
315 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
316 Null-terminator, then ASSERT().
317
318 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
319 ASCII string.
320 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
321 @param FormatString Null-terminated Unicode format string.
322
323 @return The number of ASCII characters in the produced output buffer not including the
324 Null-terminator.
325
326 **/
327 UINTN
328 EFIAPI
329 AsciiSPrint (
330 OUT CHAR8 *StartOfBuffer,
331 IN UINTN BufferSize,
332 IN CONST CHAR8 *FormatString,
333 ...
334 );
335
336 /**
337 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
338 ASCII format string and a VA_LIST argument list.
339
340 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
341 and BufferSize.
342 The ASCII string is produced by parsing the format string specified by FormatString.
343 Arguments are pulled from the variable argument list specified by Marker based on
344 the contents of the format string.
345 The number of ASCII characters in the produced output buffer is returned not including
346 the Null-terminator.
347 If BufferSize is 0, then no output buffer is produced and 0 is returned.
348
349 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
350 If BufferSize > 0 and FormatString is NULL, then ASSERT().
351 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
352 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
353 ASSERT().
354 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
355 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
356 Null-terminator, then ASSERT().
357
358 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
359 ASCII string.
360 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
361 @param FormatString Null-terminated Unicode format string.
362 @param Marker VA_LIST marker for the variable argument list.
363
364 @return The number of ASCII characters in the produced output buffer not including the
365 Null-terminator.
366
367 **/
368 UINTN
369 EFIAPI
370 AsciiVSPrintUnicodeFormat (
371 OUT CHAR8 *StartOfBuffer,
372 IN UINTN BufferSize,
373 IN CONST CHAR16 *FormatString,
374 IN VA_LIST Marker
375 );
376
377 /**
378 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
379 ASCII format string and variable argument list.
380
381 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
382 and BufferSize.
383 The ASCII string is produced by parsing the format string specified by FormatString.
384 Arguments are pulled from the variable argument list based on the contents of the
385 format string.
386 The number of ASCII characters in the produced output buffer is returned not including
387 the Null-terminator.
388 If BufferSize is 0, then no output buffer is produced and 0 is returned.
389
390 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
391 If BufferSize > 0 and FormatString is NULL, then ASSERT().
392 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
393 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
394 ASSERT().
395 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
396 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
397 Null-terminator, then ASSERT().
398
399 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
400 ASCII string.
401 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
402 @param FormatString Null-terminated Unicode format string.
403
404 @return The number of ASCII characters in the produced output buffer not including the
405 Null-terminator.
406
407 **/
408 UINTN
409 EFIAPI
410 AsciiSPrintUnicodeFormat (
411 OUT CHAR8 *StartOfBuffer,
412 IN UINTN BufferSize,
413 IN CONST CHAR16 *FormatString,
414 ...
415 );
416
417 /**
418 Converts a decimal value to a Null-terminated ASCII string.
419
420 Converts the decimal number specified by Value to a Null-terminated ASCII string
421 specified by Buffer containing at most Width characters. No padding of spaces
422 is ever performed.
423 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
424 The number of ASCII characters in Buffer is returned not including the Null-terminator.
425 If the conversion contains more than Width characters, then only the first Width
426 characters are returned, and the total number of characters required to perform
427 the conversion is returned.
428 Additional conversion parameters are specified in Flags.
429 The Flags bit LEFT_JUSTIFY is always ignored.
430 All conversions are left justified in Buffer.
431 If Width is 0, PREFIX_ZERO is ignored in Flags.
432 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
433 are inserted every 3rd digit starting from the right.
434 If HEX_RADIX is set in Flags, then the output buffer will be
435 formatted in hexadecimal format.
436 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
437 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
438 then Buffer is padded with '0' characters so the combination of the optional '-'
439 sign character, '0' characters, digit characters for Value, and the Null-terminator
440 add up to Width characters.
441
442 If Buffer is NULL, then ASSERT().
443 If unsupported bits are set in Flags, then ASSERT().
444 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
445 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
446
447 @param Buffer Pointer to the output buffer for the produced Null-terminated
448 ASCII string.
449 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
450 @param Value The 64-bit signed value to convert to a string.
451 @param Width The maximum number of ASCII characters to place in Buffer, not including
452 the Null-terminator.
453
454 @return The number of ASCII characters in Buffer not including the Null-terminator.
455
456 **/
457 UINTN
458 EFIAPI
459 AsciiValueToString (
460 IN OUT CHAR8 *Buffer,
461 IN UINTN Flags,
462 IN INT64 Value,
463 IN UINTN Width
464 );
465
466 #endif