]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/PrintLib.h
2 Provides services to print a formatted string to a buffer. All combinations of
3 Unicode and ASCII strings are supported.
5 Copyright (c) 2006 - 2008, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __PRINT_LIB_H__
17 #define __PRINT_LIB_H__
20 /// Define the maximum number of characters that are required to
21 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
24 /// Maximum Length Decimal String = 28
25 /// "-9,223,372,036,854,775,808"
26 /// Maximum Length Hexidecimal String = 17
27 /// "FFFFFFFFFFFFFFFF"
28 /// Maximum Length GUID = 37
29 /// "00000000-0000-0000-0000-000000000000"
30 /// Maximum Length TIME = 18
31 /// "12/12/2006 12:12"
33 #define MAXIMUM_VALUE_CHARACTERS 38
36 /// Flags bitmask values use in UnicodeValueToString() and
37 /// AsciiValueToString()
39 #define LEFT_JUSTIFY 0x01
40 #define COMMA_TYPE 0x08
41 #define PREFIX_ZERO 0x20
42 #define RADIX_HEX 0x80
45 Produces a Null-terminated Unicode string in an output buffer based on
46 a Null-terminated Unicode format string and a VA_LIST argument list
48 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
50 The Unicode string is produced by parsing the format string specified by FormatString.
51 Arguments are pulled from the variable argument list specified by Marker based on the
52 contents of the format string.
53 The number of Unicode characters in the produced output buffer is returned not including
55 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
57 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
58 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
59 If BufferSize > 1 and FormatString is NULL, then ASSERT().
60 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
61 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
62 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
64 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
65 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
66 Null-terminator, then ASSERT().
68 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
70 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
71 @param FormatString Null-terminated Unicode format string.
72 @param Marker VA_LIST marker for the variable argument list.
74 @return The number of Unicode characters in the produced output buffer not including the
81 OUT CHAR16
*StartOfBuffer
,
83 IN CONST CHAR16
*FormatString
,
88 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
89 Unicode format string and variable argument list.
91 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
93 The Unicode string is produced by parsing the format string specified by FormatString.
94 Arguments are pulled from the variable argument list based on the contents of the format string.
95 The number of Unicode characters in the produced output buffer is returned not including
97 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
99 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
100 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
101 If BufferSize > 1 and FormatString is NULL, then ASSERT().
102 If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
103 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
104 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
106 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
107 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
108 Null-terminator, then ASSERT().
110 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
112 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
113 @param FormatString Null-terminated Unicode format string.
114 @param ... Variable argument list whose contents are accessed based on the
115 format string specified by FormatString.
117 @return The number of Unicode characters in the produced output buffer not including the
124 OUT CHAR16
*StartOfBuffer
,
126 IN CONST CHAR16
*FormatString
,
131 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
132 ASCII format string and a VA_LIST argument list
134 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
136 The Unicode string is produced by parsing the format string specified by FormatString.
137 Arguments are pulled from the variable argument list specified by Marker based on the
138 contents of the format string.
139 The number of Unicode characters in the produced output buffer is returned not including
141 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
143 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
144 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
145 If BufferSize > 1 and FormatString is NULL, then ASSERT().
146 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
147 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
149 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
150 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
151 Null-terminator, then ASSERT().
153 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
155 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
156 @param FormatString Null-terminated ASCII format string.
157 @param Marker VA_LIST marker for the variable argument list.
159 @return The number of Unicode characters in the produced output buffer not including the
165 UnicodeVSPrintAsciiFormat (
166 OUT CHAR16
*StartOfBuffer
,
168 IN CONST CHAR8
*FormatString
,
173 Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
174 ASCII format string and variable argument list.
176 Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
178 The Unicode string is produced by parsing the format string specified by FormatString.
179 Arguments are pulled from the variable argument list based on the contents of the
181 The number of Unicode characters in the produced output buffer is returned not including
183 If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
185 If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
186 If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
187 If BufferSize > 1 and FormatString is NULL, then ASSERT().
188 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
189 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
191 If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
192 contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
193 Null-terminator, then ASSERT().
195 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
197 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
198 @param FormatString Null-terminated ASCII format string.
199 @param ... Variable argument list whose contents are accessed based on the
200 format string specified by FormatString.
202 @return The number of Unicode characters in the produced output buffer not including the
208 UnicodeSPrintAsciiFormat (
209 OUT CHAR16
*StartOfBuffer
,
211 IN CONST CHAR8
*FormatString
,
216 Converts a decimal value to a Null-terminated Unicode string.
218 Converts the decimal number specified by Value to a Null-terminated Unicode
219 string specified by Buffer containing at most Width characters. No padding of spaces
220 is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
221 The number of Unicode characters in Buffer is returned not including the Null-terminator.
222 If the conversion contains more than Width characters, then only the first
223 Width characters are returned, and the total number of characters
224 required to perform the conversion is returned.
225 Additional conversion parameters are specified in Flags.
227 The Flags bit LEFT_JUSTIFY is always ignored.
228 All conversions are left justified in Buffer.
229 If Width is 0, PREFIX_ZERO is ignored in Flags.
230 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
231 are inserted every 3rd digit starting from the right.
232 If HEX_RADIX is set in Flags, then the output buffer will be
233 formatted in hexadecimal format.
234 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
235 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
236 then Buffer is padded with '0' characters so the combination of the optional '-'
237 sign character, '0' characters, digit characters for Value, and the Null-terminator
238 add up to Width characters.
239 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
240 If Buffer is NULL, then ASSERT().
241 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
242 If unsupported bits are set in Flags, then ASSERT().
243 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
244 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
246 @param Buffer Pointer to the output buffer for the produced Null-terminated
248 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
249 @param Value The 64-bit signed value to convert to a string.
250 @param Width The maximum number of Unicode characters to place in Buffer, not including
253 @return The number of Unicode characters in Buffer not including the Null-terminator.
258 UnicodeValueToString (
259 IN OUT CHAR16
*Buffer
,
266 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
267 ASCII format string and a VA_LIST argument list.
269 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
271 The ASCII string is produced by parsing the format string specified by FormatString.
272 Arguments are pulled from the variable argument list specified by Marker based on
273 the contents of the format string.
274 The number of ASCII characters in the produced output buffer is returned not including
276 If BufferSize is 0, then no output buffer is produced and 0 is returned.
278 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
279 If BufferSize > 0 and FormatString is NULL, then ASSERT().
280 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
281 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
283 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
284 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
285 Null-terminator, then ASSERT().
287 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
289 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
290 @param FormatString Null-terminated ASCII format string.
291 @param Marker VA_LIST marker for the variable argument list.
293 @return The number of ASCII characters in the produced output buffer not including the
300 OUT CHAR8
*StartOfBuffer
,
302 IN CONST CHAR8
*FormatString
,
307 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
308 ASCII format string and variable argument list.
310 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
312 The ASCII string is produced by parsing the format string specified by FormatString.
313 Arguments are pulled from the variable argument list based on the contents of the
315 The number of ASCII characters in the produced output buffer is returned not including
317 If BufferSize is 0, then no output buffer is produced and 0 is returned.
319 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
320 If BufferSize > 0 and FormatString is NULL, then ASSERT().
321 If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
322 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
324 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
325 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
326 Null-terminator, then ASSERT().
328 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
330 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
331 @param FormatString Null-terminated ASCII format string.
332 @param ... Variable argument list whose contents are accessed based on the
333 format string specified by FormatString.
335 @return The number of ASCII characters in the produced output buffer not including the
342 OUT CHAR8
*StartOfBuffer
,
344 IN CONST CHAR8
*FormatString
,
349 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
350 Unicode format string and a VA_LIST argument list.
352 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
354 The ASCII string is produced by parsing the format string specified by FormatString.
355 Arguments are pulled from the variable argument list specified by Marker based on
356 the contents of the format string.
357 The number of ASCII characters in the produced output buffer is returned not including
359 If BufferSize is 0, then no output buffer is produced and 0 is returned.
361 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
362 If BufferSize > 0 and FormatString is NULL, then ASSERT().
363 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
364 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
365 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
367 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
368 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
369 Null-terminator, then ASSERT().
371 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
373 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
374 @param FormatString Null-terminated Unicode format string.
375 @param Marker VA_LIST marker for the variable argument list.
377 @return The number of ASCII characters in the produced output buffer not including the
383 AsciiVSPrintUnicodeFormat (
384 OUT CHAR8
*StartOfBuffer
,
386 IN CONST CHAR16
*FormatString
,
391 Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
392 Unicode format string and variable argument list.
394 Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
396 The ASCII string is produced by parsing the format string specified by FormatString.
397 Arguments are pulled from the variable argument list based on the contents of the
399 The number of ASCII characters in the produced output buffer is returned not including
401 If BufferSize is 0, then no output buffer is produced and 0 is returned.
403 If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
404 If BufferSize > 0 and FormatString is NULL, then ASSERT().
405 If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
406 If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
407 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
409 If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
410 contains more than PcdMaximumAsciiStringLength ASCII characters not including the
411 Null-terminator, then ASSERT().
413 @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated
415 @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer.
416 @param FormatString Null-terminated Unicode format string.
417 @param ... Variable argument list whose contents are accessed based on the
418 format string specified by FormatString.
420 @return The number of ASCII characters in the produced output buffer not including the
426 AsciiSPrintUnicodeFormat (
427 OUT CHAR8
*StartOfBuffer
,
429 IN CONST CHAR16
*FormatString
,
434 Converts a decimal value to a Null-terminated ASCII string.
436 Converts the decimal number specified by Value to a Null-terminated ASCII string
437 specified by Buffer containing at most Width characters. No padding of spaces
439 If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
440 The number of ASCII characters in Buffer is returned not including the Null-terminator.
441 If the conversion contains more than Width characters, then only the first Width
442 characters are returned, and the total number of characters required to perform
443 the conversion is returned.
444 Additional conversion parameters are specified in Flags.
445 The Flags bit LEFT_JUSTIFY is always ignored.
446 All conversions are left justified in Buffer.
447 If Width is 0, PREFIX_ZERO is ignored in Flags.
448 If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
449 are inserted every 3rd digit starting from the right.
450 If HEX_RADIX is set in Flags, then the output buffer will be
451 formatted in hexadecimal format.
452 If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
453 If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
454 then Buffer is padded with '0' characters so the combination of the optional '-'
455 sign character, '0' characters, digit characters for Value, and the Null-terminator
456 add up to Width characters.
458 If Buffer is NULL, then ASSERT().
459 If unsupported bits are set in Flags, then ASSERT().
460 If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
461 If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
463 @param Buffer Pointer to the output buffer for the produced Null-terminated
465 @param Flags The bitmask of flags that specify left justification, zero pad, and commas.
466 @param Value The 64-bit signed value to convert to a string.
467 @param Width The maximum number of ASCII characters to place in Buffer, not including
470 @return The number of ASCII characters in Buffer not including the Null-terminator.
476 IN OUT CHAR8
*Buffer
,