X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;ds=sidebyside;f=MdePkg%2FInclude%2FLibrary%2FPrintLib.h;h=1158a47b156efbc987e39bb6ff19357e5210c338;hb=58125b7a64b7378d78bdeb6da639ff51eb74e38f;hp=004bc9f926bf0cef882f48b2a377fbbdaf2da390;hpb=4f7f1f5fa8bdd3f4446ba8e8eb6fb662c4eb99d9;p=mirror_edk2.git diff --git a/MdePkg/Include/Library/PrintLib.h b/MdePkg/Include/Library/PrintLib.h index 004bc9f926..1158a47b15 100644 --- a/MdePkg/Include/Library/PrintLib.h +++ b/MdePkg/Include/Library/PrintLib.h @@ -1,16 +1,15 @@ /** @file - Library that provides print services + Provides services to print a formatted string to a buffer. All combinations of + Unicode and ASCII strings are supported. - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2006 - 2008, Intel Corporation +All rights reserved. This program and the accompanying materials +are licensed and made available under the terms and conditions of the BSD License +which accompanies this distribution. The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - Module Name: PrintLib.h +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ @@ -35,11 +34,12 @@ /// /// Flags bitmask values use in UnicodeValueToString() and -/// AcsiiValueToString() +/// AsciiValueToString() /// #define LEFT_JUSTIFY 0x01 #define COMMA_TYPE 0x08 #define PREFIX_ZERO 0x20 +#define RADIX_HEX 0x80 /** Produces a Null-terminated Unicode string in an output buffer based on @@ -55,7 +55,9 @@ If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). + If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). If BufferSize > 1 and FormatString is NULL, then ASSERT(). + If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT(). @@ -95,7 +97,9 @@ UnicodeVSPrint ( If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). + If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). If BufferSize > 1 and FormatString is NULL, then ASSERT(). + If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT(). @@ -107,6 +111,8 @@ UnicodeVSPrint ( Unicode string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. @param FormatString Null-terminated Unicode format string. + @param ... Variable argument list whose contents are accessed based on the + format string specified by FormatString. @return The number of Unicode characters in the produced output buffer not including the Null-terminator. @@ -135,6 +141,7 @@ UnicodeSPrint ( If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). + If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). If BufferSize > 1 and FormatString is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then @@ -146,7 +153,7 @@ UnicodeSPrint ( @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. + @param FormatString Null-terminated ASCII format string. @param Marker VA_LIST marker for the variable argument list. @return The number of Unicode characters in the produced output buffer not including the @@ -176,6 +183,7 @@ UnicodeVSPrintAsciiFormat ( If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned. If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). + If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT(). If BufferSize > 1 and FormatString is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then @@ -187,7 +195,9 @@ UnicodeVSPrintAsciiFormat ( @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated Unicode string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. + @param FormatString Null-terminated ASCII format string. + @param ... Variable argument list whose contents are accessed based on the + format string specified by FormatString. @return The number of Unicode characters in the produced output buffer not including the Null-terminator. @@ -202,6 +212,56 @@ UnicodeSPrintAsciiFormat ( ... ); +/** + Converts a decimal value to a Null-terminated Unicode string. + + Converts the decimal number specified by Value to a Null-terminated Unicode + string specified by Buffer containing at most Width characters. No padding of spaces + is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. + The number of Unicode characters in Buffer is returned not including the Null-terminator. + If the conversion contains more than Width characters, then only the first + Width characters are returned, and the total number of characters + required to perform the conversion is returned. + Additional conversion parameters are specified in Flags. + + The Flags bit LEFT_JUSTIFY is always ignored. + All conversions are left justified in Buffer. + If Width is 0, PREFIX_ZERO is ignored in Flags. + If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas + are inserted every 3rd digit starting from the right. + If HEX_RADIX is set in Flags, then the output buffer will be + formatted in hexadecimal format. + If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'. + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' + sign character, '0' characters, digit characters for Value, and the Null-terminator + add up to Width characters. + If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT(). + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 16-bit boundary, then ASSERT(). + If unsupported bits are set in Flags, then ASSERT(). + If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT(). + If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() + + @param Buffer Pointer to the output buffer for the produced Null-terminated + Unicode string. + @param Flags The bitmask of flags that specify left justification, zero pad, and commas. + @param Value The 64-bit signed value to convert to a string. + @param Width The maximum number of Unicode characters to place in Buffer, not including + the Null-terminator. + + @return The number of Unicode characters in Buffer not including the Null-terminator. + +**/ +UINTN +EFIAPI +UnicodeValueToString ( + IN OUT CHAR16 *Buffer, + IN UINTN Flags, + IN INT64 Value, + IN UINTN Width + ); + /** Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated ASCII format string and a VA_LIST argument list. @@ -227,7 +287,7 @@ UnicodeSPrintAsciiFormat ( @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. + @param FormatString Null-terminated ASCII format string. @param Marker VA_LIST marker for the variable argument list. @return The number of ASCII characters in the produced output buffer not including the @@ -268,8 +328,10 @@ AsciiVSPrint ( @param StartOfBuffer A pointer to the output buffer for the produced Null-terminated ASCII string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. - @param FormatString Null-terminated Unicode format string. - + @param FormatString Null-terminated ASCII format string. + @param ... Variable argument list whose contents are accessed based on the + format string specified by FormatString. + @return The number of ASCII characters in the produced output buffer not including the Null-terminator. @@ -285,7 +347,7 @@ AsciiSPrint ( /** Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated - ASCII format string and a VA_LIST argument list. + Unicode format string and a VA_LIST argument list. Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer and BufferSize. @@ -298,6 +360,7 @@ AsciiSPrint ( If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). If BufferSize > 0 and FormatString is NULL, then ASSERT(). + If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT(). @@ -326,7 +389,7 @@ AsciiVSPrintUnicodeFormat ( /** Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated - ASCII format string and variable argument list. + Unicode format string and variable argument list. Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer and BufferSize. @@ -339,6 +402,7 @@ AsciiVSPrintUnicodeFormat ( If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). If BufferSize > 0 and FormatString is NULL, then ASSERT(). + If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then ASSERT(). @@ -350,6 +414,8 @@ AsciiVSPrintUnicodeFormat ( ASCII string. @param BufferSize The size, in bytes, of the output buffer specified by StartOfBuffer. @param FormatString Null-terminated Unicode format string. + @param ... Variable argument list whose contents are accessed based on the + format string specified by FormatString. @return The number of ASCII characters in the produced output buffer not including the Null-terminator. @@ -364,56 +430,12 @@ AsciiSPrintUnicodeFormat ( ... ); -/** - Converts a decimal value to a Null-terminated Unicode string. - - Converts the decimal number specified by Value to a Null-terminated Unicode - string specified by Buffer containing at most Width characters. - If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. - The number of Unicode characters in Buffer is returned not including the Null-terminator. - If the conversion contains more than Width characters, then only the first - Width characters are returned, and the total number of characters - required to perform the conversion is returned. - Additional conversion parameters are specified in Flags. - The Flags bit LEFT_JUSTIFY is always ignored. - All conversions are left justified in Buffer. - If Width is 0, PREFIX_ZERO is ignored in Flags. - If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas - are inserted every 3rd digit starting from the right. - If Value is < 0, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, - then Buffer is padded with '0' characters so the combination of the optional '-' - sign character, '0' characters, digit characters for Value, and the Null-terminator - add up to Width characters. - - If Buffer is NULL, then ASSERT(). - If unsupported bits are set in Flags, then ASSERT(). - If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() - - @param Buffer Pointer to the output buffer for the produced Null-terminated - Unicode string. - @param Flags The bitmask of flags that specify left justification, zero pad, and commas. - @param Value The 64-bit signed value to convert to a string. - @param Width The maximum number of Unicode characters to place in Buffer, not including - the Null-terminator. - - @return The number of Unicode characters in Buffer not including the Null-terminator. - -**/ -UINTN -EFIAPI -UnicodeValueToString ( - IN OUT CHAR16 *Buffer, - IN UINTN Flags, - IN INT64 Value, - IN UINTN Width - ); - /** Converts a decimal value to a Null-terminated ASCII string. Converts the decimal number specified by Value to a Null-terminated ASCII string - specified by Buffer containing at most Width characters. + specified by Buffer containing at most Width characters. No padding of spaces + is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. The number of ASCII characters in Buffer is returned not including the Null-terminator. If the conversion contains more than Width characters, then only the first Width @@ -423,16 +445,19 @@ UnicodeValueToString ( The Flags bit LEFT_JUSTIFY is always ignored. All conversions are left justified in Buffer. If Width is 0, PREFIX_ZERO is ignored in Flags. - If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas + If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas are inserted every 3rd digit starting from the right. - If Value is < 0, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then Buffer - is padded with '0' characters so the combination of the optional '-' - sign character, '0' characters, digit characters for Value, and the - Null-terminator add up to Width characters. - + If HEX_RADIX is set in Flags, then the output buffer will be + formatted in hexadecimal format. + If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'. + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' + sign character, '0' characters, digit characters for Value, and the Null-terminator + add up to Width characters. + If Buffer is NULL, then ASSERT(). If unsupported bits are set in Flags, then ASSERT(). + If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT(). If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT() @param Buffer Pointer to the output buffer for the produced Null-terminated @@ -448,10 +473,10 @@ UnicodeValueToString ( UINTN EFIAPI AsciiValueToString ( - IN OUT CHAR8 *Buffer, - IN UINTN Flags, - IN INT64 Value, - IN UINTN Width + OUT CHAR8 *Buffer, + IN UINTN Flags, + IN INT64 Value, + IN UINTN Width ); #endif