MdePkg/Include/Library/PrintLib.h

   1 /** @file
   2   Provides services to print a formatted string to a buffer. All combinations of
   3   Unicode and ASCII strings are supported.
   4
   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
  10
  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.
  13
  14 **/
  15
  16 #ifndef __PRINT_LIB_H__
  17 #define __PRINT_LIB_H__
  18
  19 ///
  20 /// Define the maximum number of characters that are required to
  21 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
  22 /// terminator.
  23 ///
  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"
  32 ///
  33 #define MAXIMUM_VALUE_CHARACTERS  38
  34
  35 ///
  36 /// Flags bitmask values use in UnicodeValueToString() and
  37 /// AsciiValueToString()
  38 ///
  39 #define LEFT_JUSTIFY      0x01
  40 #define COMMA_TYPE        0x08
  41 #define PREFIX_ZERO       0x20
  42 #define RADIX_HEX         0x80
  43
  44 /**
  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
  47
  48   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  49   and BufferSize.
  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
  54   the Null-terminator.
  55   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  56
  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
  63   ASSERT().
  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().
  67
  68   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  69                           Unicode string.
  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.
  73
  74   @return The number of Unicode characters in the produced output buffer not including the
  75           Null-terminator.
  76
  77 **/
  78 UINTN
  79 EFIAPI
  80 UnicodeVSPrint (
  81   OUT CHAR16        *StartOfBuffer,
  82   IN  UINTN         BufferSize,
  83   IN  CONST CHAR16  *FormatString,
  84   IN  VA_LIST       Marker
  85   );
  86
  87 /**
  88   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  89   Unicode format string and variable argument list.
  90
  91   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  92   and BufferSize.
  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
  96   the Null-terminator.
  97   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  98
  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
 105   ASSERT().
 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().
 109
 110   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 111                           Unicode string.
 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.
 116
 117   @return The number of Unicode characters in the produced output buffer not including the
 118           Null-terminator.
 119
 120 **/
 121 UINTN
 122 EFIAPI
 123 UnicodeSPrint (
 124   OUT CHAR16        *StartOfBuffer,
 125   IN  UINTN         BufferSize,
 126   IN  CONST CHAR16  *FormatString,
 127   ...
 128   );
 129
 130 /**
 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
 133
 134   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 135   and BufferSize.
 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
 140   the Null-terminator.
 141   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 142
 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
 148   ASSERT().
 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().
 152
 153   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 154                           Unicode string.
 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.
 158
 159   @return The number of Unicode characters in the produced output buffer not including the
 160           Null-terminator.
 161
 162 **/
 163 UINTN
 164 EFIAPI
 165 UnicodeVSPrintAsciiFormat (
 166   OUT CHAR16       *StartOfBuffer,
 167   IN  UINTN        BufferSize,
 168   IN  CONST CHAR8  *FormatString,
 169   IN  VA_LIST      Marker
 170   );
 171
 172 /**
 173   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 174   ASCII format string and  variable argument list.
 175
 176   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 177   and BufferSize.
 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
 180   format string.
 181   The number of Unicode characters in the produced output buffer is returned not including
 182   the Null-terminator.
 183   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 184
 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
 190   ASSERT().
 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().
 194
 195   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 196                           Unicode string.
 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.
 201
 202   @return The number of Unicode characters in the produced output buffer not including the
 203           Null-terminator.
 204
 205 **/
 206 UINTN
 207 EFIAPI
 208 UnicodeSPrintAsciiFormat (
 209   OUT CHAR16       *StartOfBuffer,
 210   IN  UINTN        BufferSize,
 211   IN  CONST CHAR8  *FormatString,
 212   ...
 213   );
 214
 215 /**
 216   Converts a decimal value to a Null-terminated Unicode string.
 217
 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.
 226
 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()
 245
 246   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 247                   Unicode string.
 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
 251                   the Null-terminator.
 252
 253   @return The number of Unicode characters in Buffer not including the Null-terminator.
 254
 255 **/
 256 UINTN
 257 EFIAPI
 258 UnicodeValueToString (
 259   IN OUT CHAR16  *Buffer,
 260   IN UINTN       Flags,
 261   IN INT64       Value,
 262   IN UINTN       Width
 263   );
 264
 265 /**
 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.
 268
 269   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 270   and BufferSize.
 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
 275   the Null-terminator.
 276   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 277
 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
 282   ASSERT().
 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().
 286
 287   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 288                           ASCII string.
 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.
 292
 293   @return The number of ASCII characters in the produced output buffer not including the
 294           Null-terminator.
 295
 296 **/
 297 UINTN
 298 EFIAPI
 299 AsciiVSPrint (
 300   OUT CHAR8         *StartOfBuffer,
 301   IN  UINTN         BufferSize,
 302   IN  CONST CHAR8   *FormatString,
 303   IN  VA_LIST       Marker
 304   );
 305
 306 /**
 307   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 308   ASCII format string and  variable argument list.
 309
 310   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 311   and BufferSize.
 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
 314   format string.
 315   The number of ASCII characters in the produced output buffer is returned not including
 316   the Null-terminator.
 317   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 318
 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
 323   ASSERT().
 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().
 327
 328   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 329                           ASCII string.
 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.
 334
 335   @return The number of ASCII characters in the produced output buffer not including the
 336           Null-terminator.
 337
 338 **/
 339 UINTN
 340 EFIAPI
 341 AsciiSPrint (
 342   OUT CHAR8        *StartOfBuffer,
 343   IN  UINTN        BufferSize,
 344   IN  CONST CHAR8  *FormatString,
 345   ...
 346   );
 347
 348 /**
 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.
 351
 352   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 353   and BufferSize.
 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
 358   the Null-terminator.
 359   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 360
 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
 366   ASSERT().
 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().
 370
 371   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 372                           ASCII string.
 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.
 376
 377   @return The number of ASCII characters in the produced output buffer not including the
 378           Null-terminator.
 379
 380 **/
 381 UINTN
 382 EFIAPI
 383 AsciiVSPrintUnicodeFormat (
 384   OUT CHAR8         *StartOfBuffer,
 385   IN  UINTN         BufferSize,
 386   IN  CONST CHAR16  *FormatString,
 387   IN  VA_LIST       Marker
 388   );
 389
 390 /**
 391   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 392   Unicode format string and  variable argument list.
 393
 394   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 395   and BufferSize.
 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
 398   format string.
 399   The number of ASCII characters in the produced output buffer is returned not including
 400   the Null-terminator.
 401   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 402
 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
 408   ASSERT().
 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().
 412
 413   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 414                           ASCII string.
 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.
 419
 420   @return The number of ASCII characters in the produced output buffer not including the
 421           Null-terminator.
 422
 423 **/
 424 UINTN
 425 EFIAPI
 426 AsciiSPrintUnicodeFormat (
 427   OUT CHAR8         *StartOfBuffer,
 428   IN  UINTN         BufferSize,
 429   IN  CONST CHAR16  *FormatString,
 430   ...
 431   );
 432
 433 /**
 434   Converts a decimal value to a Null-terminated ASCII string.
 435
 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
 438   is ever performed.
 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.
 457
 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()
 462
 463   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 464                   ASCII string.
 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
 468                   the Null-terminator.
 469
 470   @return The number of ASCII characters in Buffer not including the Null-terminator.
 471
 472 **/
 473 UINTN
 474 EFIAPI
 475 AsciiValueToString (
 476   OUT CHAR8      *Buffer,
 477   IN  UINTN      Flags,
 478   IN  INT64      Value,
 479   IN  UINTN      Width
 480   );
 481
 482 #endif