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  ...             The variable argument list.
 115
 116   @return The number of Unicode characters in the produced output buffer not including the
 117           Null-terminator.
 118
 119 **/
 120 UINTN
 121 EFIAPI
 122 UnicodeSPrint (
 123   OUT CHAR16        *StartOfBuffer,
 124   IN  UINTN         BufferSize,
 125   IN  CONST CHAR16  *FormatString,
 126   ...
 127   );
 128
 129 /**
 130   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 131   ASCII format string and a VA_LIST argument list
 132
 133   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 134   and BufferSize.
 135   The Unicode string is produced by parsing the format string specified by FormatString.
 136   Arguments are pulled from the variable argument list specified by Marker based on the
 137   contents of the format string.
 138   The number of Unicode characters in the produced output buffer is returned not including
 139   the Null-terminator.
 140   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 141
 142   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 143   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 144   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 145   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 146   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 147   ASSERT().
 148   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 149   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 150   Null-terminator, then ASSERT().
 151
 152   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 153                           Unicode string.
 154   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 155   @param  FormatString    Null-terminated ASCII format string.
 156   @param  Marker          VA_LIST marker for the variable argument list.
 157
 158   @return The number of Unicode characters in the produced output buffer not including the
 159           Null-terminator.
 160
 161 **/
 162 UINTN
 163 EFIAPI
 164 UnicodeVSPrintAsciiFormat (
 165   OUT CHAR16       *StartOfBuffer,
 166   IN  UINTN        BufferSize,
 167   IN  CONST CHAR8  *FormatString,
 168   IN  VA_LIST      Marker
 169   );
 170
 171 /**
 172   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 173   ASCII format string and  variable argument list.
 174
 175   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 176   and BufferSize.
 177   The Unicode string is produced by parsing the format string specified by FormatString.
 178   Arguments are pulled from the variable argument list based on the contents of the
 179   format string.
 180   The number of Unicode characters in the produced output buffer is returned not including
 181   the Null-terminator.
 182   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 183
 184   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 185   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 186   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 187   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 188   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 189   ASSERT().
 190   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 191   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 192   Null-terminator, then ASSERT().
 193
 194   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 195                           Unicode string.
 196   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 197   @param  FormatString    Null-terminated ASCII format string.
 198   @param  ...             The variable argument list.
 199
 200   @return The number of Unicode characters in the produced output buffer not including the
 201           Null-terminator.
 202
 203 **/
 204 UINTN
 205 EFIAPI
 206 UnicodeSPrintAsciiFormat (
 207   OUT CHAR16       *StartOfBuffer,
 208   IN  UINTN        BufferSize,
 209   IN  CONST CHAR8  *FormatString,
 210   ...
 211   );
 212
 213 /**
 214   Converts a decimal value to a Null-terminated Unicode string.
 215
 216   Converts the decimal number specified by Value to a Null-terminated Unicode
 217   string specified by Buffer containing at most Width characters. No padding of spaces
 218   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 219   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 220   If the conversion contains more than Width characters, then only the first
 221   Width characters are returned, and the total number of characters
 222   required to perform the conversion is returned.
 223   Additional conversion parameters are specified in Flags.
 224
 225   The Flags bit LEFT_JUSTIFY is always ignored.
 226   All conversions are left justified in Buffer.
 227   If Width is 0, PREFIX_ZERO is ignored in Flags.
 228   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 229   are inserted every 3rd digit starting from the right.
 230   If HEX_RADIX is set in Flags, then the output buffer will be
 231   formatted in hexadecimal format.
 232   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 233   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 234   then Buffer is padded with '0' characters so the combination of the optional '-'
 235   sign character, '0' characters, digit characters for Value, and the Null-terminator
 236   add up to Width characters.
 237   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 238   If Buffer is NULL, then ASSERT().
 239   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 240   If unsupported bits are set in Flags, then ASSERT().
 241   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 242   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 243
 244   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 245                   Unicode string.
 246   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 247   @param  Value   The 64-bit signed value to convert to a string.
 248   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 249                   the Null-terminator.
 250
 251   @return The number of Unicode characters in Buffer not including the Null-terminator.
 252
 253 **/
 254 UINTN
 255 EFIAPI
 256 UnicodeValueToString (
 257   IN OUT CHAR16  *Buffer,
 258   IN UINTN       Flags,
 259   IN INT64       Value,
 260   IN UINTN       Width
 261   );
 262
 263 /**
 264   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 265   ASCII format string and a VA_LIST argument list.
 266
 267   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 268   and BufferSize.
 269   The ASCII string is produced by parsing the format string specified by FormatString.
 270   Arguments are pulled from the variable argument list specified by Marker based on
 271   the contents of the format string.
 272   The number of ASCII characters in the produced output buffer is returned not including
 273   the Null-terminator.
 274   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 275
 276   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 277   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 278   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 279   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 280   ASSERT().
 281   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 282   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 283   Null-terminator, then ASSERT().
 284
 285   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 286                           ASCII string.
 287   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 288   @param  FormatString    Null-terminated ASCII format string.
 289   @param  Marker          VA_LIST marker for the variable argument list.
 290
 291   @return The number of ASCII characters in the produced output buffer not including the
 292           Null-terminator.
 293
 294 **/
 295 UINTN
 296 EFIAPI
 297 AsciiVSPrint (
 298   OUT CHAR8         *StartOfBuffer,
 299   IN  UINTN         BufferSize,
 300   IN  CONST CHAR8   *FormatString,
 301   IN  VA_LIST       Marker
 302   );
 303
 304 /**
 305   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 306   ASCII format string and  variable argument list.
 307
 308   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 309   and BufferSize.
 310   The ASCII string is produced by parsing the format string specified by FormatString.
 311   Arguments are pulled from the variable argument list based on the contents of the
 312   format string.
 313   The number of ASCII characters in the produced output buffer is returned not including
 314   the Null-terminator.
 315   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 316
 317   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 318   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 319   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 320   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 321   ASSERT().
 322   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 323   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 324   Null-terminator, then ASSERT().
 325
 326   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 327                           ASCII string.
 328   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 329   @param  FormatString    Null-terminated ASCII format string.
 330   @param  ...             The variable argument list.
 331
 332   @return The number of ASCII characters in the produced output buffer not including the
 333           Null-terminator.
 334
 335 **/
 336 UINTN
 337 EFIAPI
 338 AsciiSPrint (
 339   OUT CHAR8        *StartOfBuffer,
 340   IN  UINTN        BufferSize,
 341   IN  CONST CHAR8  *FormatString,
 342   ...
 343   );
 344
 345 /**
 346   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 347   Unicode format string and a VA_LIST argument list.
 348
 349   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 350   and BufferSize.
 351   The ASCII string is produced by parsing the format string specified by FormatString.
 352   Arguments are pulled from the variable argument list specified by Marker based on
 353   the contents of the format string.
 354   The number of ASCII characters in the produced output buffer is returned not including
 355   the Null-terminator.
 356   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 357
 358   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 359   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 360   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 361   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 362   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 363   ASSERT().
 364   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 365   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 366   Null-terminator, then ASSERT().
 367
 368   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 369                           ASCII string.
 370   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 371   @param  FormatString    Null-terminated Unicode format string.
 372   @param  Marker          VA_LIST marker for the variable argument list.
 373
 374   @return The number of ASCII characters in the produced output buffer not including the
 375           Null-terminator.
 376
 377 **/
 378 UINTN
 379 EFIAPI
 380 AsciiVSPrintUnicodeFormat (
 381   OUT CHAR8         *StartOfBuffer,
 382   IN  UINTN         BufferSize,
 383   IN  CONST CHAR16  *FormatString,
 384   IN  VA_LIST       Marker
 385   );
 386
 387 /**
 388   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 389   Unicode format string and  variable argument list.
 390
 391   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 392   and BufferSize.
 393   The ASCII string is produced by parsing the format string specified by FormatString.
 394   Arguments are pulled from the variable argument list based on the contents of the
 395   format string.
 396   The number of ASCII characters in the produced output buffer is returned not including
 397   the Null-terminator.
 398   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 399
 400   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 401   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 402   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 403   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 404   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 405   ASSERT().
 406   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 407   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 408   Null-terminator, then ASSERT().
 409
 410   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 411                           ASCII string.
 412   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 413   @param  FormatString    Null-terminated Unicode format string.
 414   @param  ...             The variable argument list.
 415
 416   @return The number of ASCII characters in the produced output buffer not including the
 417           Null-terminator.
 418
 419 **/
 420 UINTN
 421 EFIAPI
 422 AsciiSPrintUnicodeFormat (
 423   OUT CHAR8         *StartOfBuffer,
 424   IN  UINTN         BufferSize,
 425   IN  CONST CHAR16  *FormatString,
 426   ...
 427   );
 428
 429 /**
 430   Converts a decimal value to a Null-terminated ASCII string.
 431
 432   Converts the decimal number specified by Value to a Null-terminated ASCII string
 433   specified by Buffer containing at most Width characters. No padding of spaces
 434   is ever performed.
 435   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 436   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 437   If the conversion contains more than Width characters, then only the first Width
 438   characters are returned, and the total number of characters required to perform
 439   the conversion is returned.
 440   Additional conversion parameters are specified in Flags.
 441   The Flags bit LEFT_JUSTIFY is always ignored.
 442   All conversions are left justified in Buffer.
 443   If Width is 0, PREFIX_ZERO is ignored in Flags.
 444   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 445   are inserted every 3rd digit starting from the right.
 446   If HEX_RADIX is set in Flags, then the output buffer will be
 447   formatted in hexadecimal format.
 448   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 449   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 450   then Buffer is padded with '0' characters so the combination of the optional '-'
 451   sign character, '0' characters, digit characters for Value, and the Null-terminator
 452   add up to Width characters.
 453
 454   If Buffer is NULL, then ASSERT().
 455   If unsupported bits are set in Flags, then ASSERT().
 456   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 457   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 458
 459   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 460                   ASCII string.
 461   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 462   @param  Value   The 64-bit signed value to convert to a string.
 463   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 464                   the Null-terminator.
 465
 466   @return The number of ASCII characters in Buffer not including the Null-terminator.
 467
 468 **/
 469 UINTN
 470 EFIAPI
 471 AsciiValueToString (
 472   IN OUT CHAR8  *Buffer,
 473   IN UINTN      Flags,
 474   IN INT64      Value,
 475   IN UINTN      Width
 476   );
 477
 478 #endif