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