add function header
[mirror_edk2.git] / MdePkg / Library / BasePrintLib / PrintLib.c
index bbd0820..f2c7ee5 100644 (file)
@@ -56,20 +56,21 @@ static CONST STATUS_LOOKUP_TABLE_ENTRY  StatusString[] = {
 \r
 \r
 /**\r
+  Worker function that produces a Null-terminated string in an output buffer \r
+  based on a Null-terminated format string and a VA_LIST argument list.\r
+\r
   VSPrint function to process format and place the results in Buffer. Since a \r
   VA_LIST is used this rountine allows the nesting of Vararg routines. Thus \r
   this is the main print working routine\r
 \r
-  @param  StartOfBuffer Unicode buffer to print the results of the parsing of Format into.\r
-  \r
-  @param  BufferSize Maximum number of characters to put into buffer. Zero means\r
-  no limit.\r
-  \r
-  @param  Flags Intial flags value.  Can only have FORMAT_UNICODE and OUTPUT_UNICODE set\r
-  \r
-  @param  FormatString Unicode format string see file header for more details.\r
-  \r
-  @param  Marker Vararg list consumed by processing Format.\r
+  @param  Buffer      Character buffer to print the results of the parsing\r
+                      of Format into.\r
+  @param  BufferSize  Maximum number of characters to put into buffer.\r
+                      Zero means no limit.\r
+  @param  Flags       Intial flags value.\r
+                      Can only have FORMAT_UNICODE and OUTPUT_UNICODE set\r
+  @param  Format      Null-terminated format string.\r
+  @param  Marker      Vararg list consumed by processing Format.\r
 \r
   @return Number of characters printed.\r
 \r
@@ -515,6 +516,25 @@ BasePrintLibVSPrint (
   return ((Buffer - OriginalBuffer) / BytesPerOutputCharacter);\r
 }\r
 \r
+/**\r
+  Worker function that produces a Null-terminated string in an output buffer \r
+  based on a Null-terminated format string and variable argument list.\r
+\r
+  VSPrint function to process format and place the results in Buffer. Since a \r
+  VA_LIST is used this rountine allows the nesting of Vararg routines. Thus \r
+  this is the main print working routine\r
+\r
+  @param  Buffer        Character buffer to print the results of the parsing\r
+                        of Format into.\r
+  @param  BufferSize    Maximum number of characters to put into buffer.\r
+                        Zero means no limit.\r
+  @param  Flags         Intial flags value.\r
+                        Can only have FORMAT_UNICODE and OUTPUT_UNICODE set\r
+  @param  FormatString  Null-terminated format string.\r
+\r
+  @return Number of characters printed.\r
+\r
+**/\r
 UINTN\r
 BasePrintLibSPrint (\r
   OUT CHAR8        *StartOfBuffer,\r
@@ -530,6 +550,34 @@ BasePrintLibSPrint (
   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, Flags, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated Unicode string in an output buffer based on \r
+  a Null-terminated Unicode format string and a VA_LIST argument list\r
+  \r
+  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.  \r
+  The Unicode string is produced by parsing the format string specified by FormatString.  \r
+  Arguments are pulled from the variable argument list specified by Marker based on the \r
+  contents of the format string.  \r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          Unicode string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  Marker          VA_LIST marker for the variable argument list.\r
+  \r
+  @return return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 UnicodeVSPrint (\r
@@ -542,6 +590,32 @@ UnicodeVSPrint (
   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated \r
+  Unicode format string and variable argument list.\r
+  \r
+  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The Unicode string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list based on the contents of the format string.\r
+  The length of the produced output buffer is returned.  \r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          Unicode string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 UnicodeSPrint (\r
@@ -557,6 +631,34 @@ UnicodeSPrint (
   return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated\r
+  ASCII format string and a VA_LIST argument list\r
+  \r
+  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The Unicode string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list specified by Marker based on the \r
+  contents of the format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          Unicode string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  Marker          VA_LIST marker for the variable argument list.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 UnicodeVSPrintAsciiFormat (\r
@@ -569,6 +671,33 @@ UnicodeVSPrintAsciiFormat (
   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE,FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated \r
+  ASCII format string and  variable argument list.\r
+  \r
+  Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The Unicode string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list based on the contents of the \r
+  format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          Unicode string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 UnicodeSPrintAsciiFormat (\r
@@ -584,6 +713,34 @@ UnicodeSPrintAsciiFormat (
   return UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize >> 1, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
+  ASCII format string and a VA_LIST argument list.\r
+  \r
+  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The ASCII string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list specified by Marker based on \r
+  the contents of the format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          ASCII string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  Marker          VA_LIST marker for the variable argument list.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 AsciiVSPrint (\r
@@ -596,6 +753,33 @@ AsciiVSPrint (
   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, 0, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
+  ASCII format string and  variable argument list.\r
+  \r
+  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The ASCII string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list based on the contents of the \r
+  format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          ASCII string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 AsciiSPrint (\r
@@ -611,6 +795,34 @@ AsciiSPrint (
   return AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
+  ASCII format string and a VA_LIST argument list.\r
+  \r
+  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The ASCII string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list specified by Marker based on \r
+  the contents of the format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          ASCII string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  @param  Marker          VA_LIST marker for the variable argument list.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 AsciiVSPrintUnicodeFormat (\r
@@ -623,6 +835,33 @@ AsciiVSPrintUnicodeFormat (
   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated\r
+  ASCII format string and  variable argument list.\r
+  \r
+  Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer\r
+  and BufferSize.\r
+  The ASCII string is produced by parsing the format string specified by FormatString.\r
+  Arguments are pulled from the variable argument list based on the contents of the \r
+  format string.\r
+  The length of the produced output buffer is returned.\r
+  If BufferSize is 0, then no output buffer is produced and 0 is returned.\r
+\r
+  If BufferSize is not 0 and StartOfBuffer is NULL, then ASSERT().\r
+  If BufferSize is not 0 and FormatString is NULL, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than \r
+  PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+  If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string\r
+  contains more than PcdMaximumUnicodeStringLength ASCII characters, then ASSERT().\r
+\r
+  @param  StartOfBuffer   APointer to the output buffer for the produced Null-terminated \r
+                          ASCII string.\r
+  @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.\r
+  @param  FormatString    Null-terminated Unicode format string.\r
+  \r
+  @return Length of the produced output buffer.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 AsciiSPrintUnicodeFormat (\r
@@ -638,6 +877,41 @@ AsciiSPrintUnicodeFormat (
   return AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);\r
 }\r
 \r
+/**\r
+  Converts a decimal value to a Null-terminated Unicode string.\r
+  \r
+  Converts the decimal number specified by Value to a Null-terminated Unicode \r
+  string specified by Buffer containing at most Width characters.\r
+  If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.\r
+  The total number of characters placed in Buffer is returned.\r
+  If the conversion contains more than Width characters, then only the first\r
+  Width characters are returned, and the total number of characters \r
+  required to perform the conversion is returned.\r
+  Additional conversion parameters are specified in Flags.  \r
+  The Flags bit LEFT_JUSTIFY is always ignored.\r
+  All conversions are left justified in Buffer.\r
+  If Width is 0, PREFIX_ZERO is ignored in Flags.\r
+  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas\r
+  are inserted every 3rd digit starting from the right.\r
+  If Value is < 0, then the fist character in Buffer is a '-'.\r
+  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, \r
+  then Buffer is padded with '0' characters so the combination of the optional '-' \r
+  sign character, '0' characters, digit characters for Value, and the Null-terminator\r
+  add up to Width characters.\r
+\r
+  If Buffer is NULL, then ASSERT().\r
+  If unsupported bits are set in Flags, then ASSERT().\r
+  If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
+\r
+  @param  Buffer  Pointer to the output buffer for the produced Null-terminated\r
+                  Unicode string.\r
+  @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.\r
+  @param  Value   The 64-bit signed value to convert to a string.\r
+  @param  Width          The maximum number of Unicode characters to place in Buffer.\r
+  \r
+  @return Total number of characters required to perform the conversion.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 UnicodeValueToString (\r
@@ -650,6 +924,41 @@ UnicodeValueToString (
   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);\r
 }\r
 \r
+/**\r
+  Converts a decimal value to a Null-terminated ASCII string.\r
+  \r
+  Converts the decimal number specified by Value to a Null-terminated ASCII string \r
+  specified by Buffer containing at most Width characters.\r
+  If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.\r
+  The total number of characters placed in Buffer is returned.\r
+  If the conversion contains more than Width characters, then only the first Width\r
+  characters are returned, and the total number of characters required to perform\r
+  the conversion is returned.\r
+  Additional conversion parameters are specified in Flags.  \r
+  The Flags bit LEFT_JUSTIFY is always ignored.\r
+  All conversions are left justified in Buffer.\r
+  If Width is 0, PREFIX_ZERO is ignored in Flags.\r
+  If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas \r
+  are inserted every 3rd digit starting from the right.\r
+  If Value is < 0, then the fist character in Buffer is a '-'.\r
+  If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then Buffer\r
+  is padded with '0' characters so the combination of the optional '-'\r
+  sign character, '0' characters, digit characters for Value, and the \r
+  Null-terminator add up to Width characters.\r
+\r
+  If Buffer is NULL, then ASSERT().\r
+  If unsupported bits are set in Flags, then ASSERT().\r
+  If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()\r
+\r
+  @param  Buffer  Pointer to the output buffer for the produced Null-terminated\r
+                  ASCII string.\r
+  @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.\r
+  @param  Value   The 64-bit signed value to convert to a string.\r
+  @param  Width          The maximum number of ASCII characters to place in Buffer.\r
+  \r
+  @return Total number of characters required to perform the conversion.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 AsciiValueToString (\r