2 Unicode and ASCII string primatives.
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 // Include common header file for this module.
20 #include "BaseLibInternals.h"
23 Copies one Null-terminated Unicode string to another Null-terminated Unicode
24 string and returns the new Unicode string.
26 This function copies the contents of the Unicode string Source to the Unicode
27 string Destination, and returns Destination. If Source and Destination
28 overlap, then the results are undefined.
30 If Destination is NULL, then ASSERT().
31 If Destination is not aligned on a 16-bit boundary, then ASSERT().
32 If Source is NULL, then ASSERT().
33 If Source is not aligned on a 16-bit boundary, then ASSERT().
34 If Source and Destination overlap, then ASSERT().
35 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
36 PcdMaximumUnicodeStringLength Unicode characters not including the
37 Null-terminator, then ASSERT().
39 @param Destination Pointer to a Null-terminated Unicode string.
40 @param Source Pointer to a Null-terminated Unicode string.
48 OUT CHAR16
*Destination
,
49 IN CONST CHAR16
*Source
55 // Destination cannot be NULL
57 ASSERT (Destination
!= NULL
);
58 ASSERT (((UINTN
) Destination
& 0x01) == 0);
61 // Destination and source cannot overlap
63 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
64 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
66 ReturnValue
= Destination
;
67 while (*Source
!= 0) {
68 *(Destination
++) = *(Source
++);
75 Copies one Null-terminated Unicode string with a maximum length to another
76 Null-terminated Unicode string with a maximum length and returns the new
79 This function copies the contents of the Unicode string Source to the Unicode
80 string Destination, and returns Destination. At most, Length Unicode
81 characters are copied from Source to Destination. If Length is 0, then
82 Destination is returned unmodified. If Length is greater that the number of
83 Unicode characters in Source, then Destination is padded with Null Unicode
84 characters. If Source and Destination overlap, then the results are
87 If Length > 0 and Destination is NULL, then ASSERT().
88 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
89 If Length > 0 and Source is NULL, then ASSERT().
90 If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
91 If Source and Destination overlap, then ASSERT().
92 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
93 PcdMaximumUnicodeStringLength Unicode characters not including the
94 Null-terminator, then ASSERT().
96 @param Destination Pointer to a Null-terminated Unicode string.
97 @param Source Pointer to a Null-terminated Unicode string.
98 @param Length Maximum number of Unicode characters to copy.
106 OUT CHAR16
*Destination
,
107 IN CONST CHAR16
*Source
,
118 // Destination cannot be NULL if Length is not zero
120 ASSERT (Destination
!= NULL
);
121 ASSERT (((UINTN
) Destination
& 0x01) == 0);
124 // Destination and source cannot overlap
125 // Q: Does Source have to be NULL-terminated?
127 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
128 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
130 ReturnValue
= Destination
;
132 while ((*Source
!= L
'\0') && (Length
> 0)) {
133 *(Destination
++) = *(Source
++);
137 ZeroMem (Destination
, Length
* sizeof (*Destination
));
142 Returns the length of a Null-terminated Unicode string.
144 This function returns the number of Unicode characters in the Null-terminated
145 Unicode string specified by String.
147 If String is NULL, then ASSERT().
148 If String is not aligned on a 16-bit boundary, then ASSERT().
149 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
150 PcdMaximumUnicodeStringLength Unicode characters not including the
151 Null-terminator, then ASSERT().
153 @param String Pointer to a Null-terminated Unicode string.
155 @return The length of String.
161 IN CONST CHAR16
*String
166 ASSERT (String
!= NULL
);
167 ASSERT (((UINTN
) String
& 0x01) == 0);
169 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
171 // If PcdMaximumUnicodeStringLength is not zero,
172 // length should not more than PcdMaximumUnicodeStringLength
174 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
175 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
182 Returns the size of a Null-terminated Unicode string in bytes, including the
185 This function returns the size, in bytes, of the Null-terminated Unicode
186 string specified by String.
188 If String is NULL, then ASSERT().
189 If String is not aligned on a 16-bit boundary, then ASSERT().
190 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
191 PcdMaximumUnicodeStringLength Unicode characters not including the
192 Null-terminator, then ASSERT().
194 @param String Pointer to a Null-terminated Unicode string.
196 @return The size in bytes of String.
202 IN CONST CHAR16
*String
205 return (StrLen (String
) + 1) * sizeof (*String
);
209 Compares two Null-terminated Unicode strings, and returns the difference
210 between the first mismatched Unicode characters.
212 This function compares the Null-terminated Unicode string FirstString to the
213 Null-terminated Unicode string SecondString. If FirstString is identical to
214 SecondString, then 0 is returned. Otherwise, the value returned is the first
215 mismatched Unicode character in SecondString subtracted from the first
216 mismatched Unicode character in FirstString.
218 If FirstString is NULL, then ASSERT().
219 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
220 If SecondString is NULL, then ASSERT().
221 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
222 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
223 than PcdMaximumUnicodeStringLength Unicode characters not including the
224 Null-terminator, then ASSERT().
225 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
226 than PcdMaximumUnicodeStringLength Unicode characters not including the
227 Null-terminator, then ASSERT().
229 @param FirstString Pointer to a Null-terminated Unicode string.
230 @param SecondString Pointer to a Null-terminated Unicode string.
232 @retval 0 FirstString is identical to SecondString.
233 @retval !=0 FirstString is not identical to SecondString.
239 IN CONST CHAR16
*FirstString
,
240 IN CONST CHAR16
*SecondString
244 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
246 ASSERT (StrSize (FirstString
) != 0);
247 ASSERT (StrSize (SecondString
) != 0);
249 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
253 return *FirstString
- *SecondString
;
257 Compares two Null-terminated Unicode strings with maximum lengths, and
258 returns the difference between the first mismatched Unicode characters.
260 This function compares the Null-terminated Unicode string FirstString to the
261 Null-terminated Unicode string SecondString. At most, Length Unicode
262 characters will be compared. If Length is 0, then 0 is returned. If
263 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
264 value returned is the first mismatched Unicode character in SecondString
265 subtracted from the first mismatched Unicode character in FirstString.
267 If Length > 0 and FirstString is NULL, then ASSERT().
268 If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
269 If Length > 0 and SecondString is NULL, then ASSERT().
270 If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
271 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
272 than PcdMaximumUnicodeStringLength Unicode characters not including the
273 Null-terminator, then ASSERT().
274 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
275 than PcdMaximumUnicodeStringLength Unicode characters not including the
276 Null-terminator, then ASSERT().
278 @param FirstString Pointer to a Null-terminated Unicode string.
279 @param SecondString Pointer to a Null-terminated Unicode string.
280 @param Length Maximum number of Unicode characters to compare.
282 @retval 0 FirstString is identical to SecondString.
283 @retval !=0 FirstString is not identical to SecondString.
289 IN CONST CHAR16
*FirstString
,
290 IN CONST CHAR16
*SecondString
,
299 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
300 // Length tests are performed inside StrLen().
302 ASSERT (StrSize (FirstString
) != 0);
303 ASSERT (StrSize (SecondString
) != 0);
305 while ((*FirstString
!= L
'\0') &&
306 (*FirstString
== *SecondString
) &&
313 return *FirstString
- *SecondString
;
317 Concatenates one Null-terminated Unicode string to another Null-terminated
318 Unicode string, and returns the concatenated Unicode string.
320 This function concatenates two Null-terminated Unicode strings. The contents
321 of Null-terminated Unicode string Source are concatenated to the end of
322 Null-terminated Unicode string Destination. The Null-terminated concatenated
323 Unicode String is returned. If Source and Destination overlap, then the
324 results are undefined.
326 If Destination is NULL, then ASSERT().
327 If Source is NULL, then ASSERT().
328 If Source and Destination overlap, then ASSERT().
329 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
330 than PcdMaximumUnicodeStringLength Unicode characters not including the
331 Null-terminator, then ASSERT().
332 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
333 PcdMaximumUnicodeStringLength Unicode characters not including the
334 Null-terminator, then ASSERT().
335 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
336 and Source results in a Unicode string with more than
337 PcdMaximumUnicodeStringLength Unicode characters not including the
338 Null-terminator, then ASSERT().
340 @param Destination Pointer to a Null-terminated Unicode string.
341 @param Source Pointer to a Null-terminated Unicode string.
349 IN OUT CHAR16
*Destination
,
350 IN CONST CHAR16
*Source
353 StrCpy (Destination
+ StrLen (Destination
), Source
);
356 // Size of the resulting string should never be zero.
357 // PcdMaximumUnicodeStringLength is tested inside StrLen().
359 ASSERT (StrSize (Destination
) != 0);
364 Concatenates one Null-terminated Unicode string with a maximum length to the
365 end of another Null-terminated Unicode string, and returns the concatenated
368 This function concatenates two Null-terminated Unicode strings. The contents
369 of Null-terminated Unicode string Source are concatenated to the end of
370 Null-terminated Unicode string Destination, and Destination is returned. At
371 most, Length Unicode characters are concatenated from Source to the end of
372 Destination, and Destination is always Null-terminated. If Length is 0, then
373 Destination is returned unmodified. If Source and Destination overlap, then
374 the results are undefined.
376 If Destination is NULL, then ASSERT().
377 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
378 If Length > 0 and Source is NULL, then ASSERT().
379 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
380 If Source and Destination overlap, then ASSERT().
381 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
382 than PcdMaximumUnicodeStringLength Unicode characters not including the
383 Null-terminator, then ASSERT().
384 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
385 PcdMaximumUnicodeStringLength Unicode characters not including the
386 Null-terminator, then ASSERT().
387 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
388 and Source results in a Unicode string with more than
389 PcdMaximumUnicodeStringLength Unicode characters not including the
390 Null-terminator, then ASSERT().
392 @param Destination Pointer to a Null-terminated Unicode string.
393 @param Source Pointer to a Null-terminated Unicode string.
394 @param Length Maximum number of Unicode characters to concatenate from
403 IN OUT CHAR16
*Destination
,
404 IN CONST CHAR16
*Source
,
408 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
411 // Size of the resulting string should never be zero.
412 // PcdMaximumUnicodeStringLength is tested inside StrLen().
414 ASSERT (StrSize (Destination
) != 0);
419 Returns the first occurance of a Null-terminated Unicode sub-string
420 in a Null-terminated Unicode string.
422 This function scans the contents of the Null-terminated Unicode string
423 specified by String and returns the first occurrence of SearchString.
424 If SearchString is not found in String, then NULL is returned. If
425 the length of SearchString is zero, then String is
428 If String is NULL, then ASSERT().
429 If String is not aligned on a 16-bit boundary, then ASSERT().
430 If SearchString is NULL, then ASSERT().
431 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
433 If PcdMaximumUnicodeStringLength is not zero, and SearchString
434 or String contains more than PcdMaximumUnicodeStringLength Unicode
435 characters not including the Null-terminator, then ASSERT().
437 @param String Pointer to a Null-terminated Unicode string.
438 @param SearchString Pointer to a Null-terminated Unicode string to search for.
440 @retval NULL If the SearchString does not appear in String.
441 @retval !NULL If there is a match.
447 IN CONST CHAR16
*String
,
448 IN CONST CHAR16
*SearchString
451 CONST CHAR16
*FirstMatch
;
452 CONST CHAR16
*SearchStringTmp
;
455 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
456 // Length tests are performed inside StrLen().
458 ASSERT (StrSize (String
) != 0);
459 ASSERT (StrSize (SearchString
) != 0);
461 while (*String
!= '\0') {
462 SearchStringTmp
= SearchString
;
465 while ((*String
== *SearchStringTmp
)
466 && (*SearchStringTmp
!= '\0')
467 && (*String
!= '\0')) {
472 if ('\0' == *SearchStringTmp
) {
473 return (CHAR16
*) FirstMatch
;
476 if (SearchStringTmp
== SearchString
) {
478 // If no character from SearchString match,
479 // move the pointer to the String under search
490 Check if a Unicode character is a decimal character.
492 This internal function checks if a Unicode character is a
493 decimal character. The valid decimal character is from
497 @param Char The character to check against.
499 @retval TRUE If the Char is a decmial character.
500 @retval FALSE Otherwise.
505 InternalIsDecimalDigitCharacter (
509 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
513 Convert a Unicode character to upper case only if
514 it maps to a valid small-case ASCII character.
516 This internal function only deal with Unicode character
517 which maps to a valid small-case ASII character, i.e.
518 L'a' to L'z'. For other Unicode character, the input character
519 is returned directly.
522 @param Char The character to convert.
524 @retval LowerCharacter If the Char is with range L'a' to L'z'.
525 @retval Unchanged Otherwise.
530 InternalCharToUpper (
534 if (Char
>= L
'a' && Char
<= L
'z') {
535 return (CHAR16
) (Char
- (L
'a' - L
'A'));
542 Convert a Unicode character to numerical value.
544 This internal function only deal with Unicode character
545 which maps to a valid hexadecimal ASII character, i.e.
546 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
547 Unicode character, the value returned does not make sense.
549 @param Char The character to convert.
551 @retval UINTN The numerical value converted.
556 InternalHexCharToUintn (
560 if (InternalIsDecimalDigitCharacter (Char
)) {
564 return (UINTN
) (10 + InternalCharToUpper (Char
) - L
'A');
568 Check if a Unicode character is a hexadecimal character.
570 This internal function checks if a Unicode character is a
571 decimal character. The valid hexadecimal character is
572 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
575 @param Char The character to check against.
577 @retval TRUE If the Char is a hexadecmial character.
578 @retval FALSE Otherwise.
583 InternalIsHexaDecimalDigitCharacter (
588 return (BOOLEAN
) (InternalIsDecimalDigitCharacter (Char
) ||
589 (Char
>= L
'A' && Char
<= L
'F') ||
590 (Char
>= L
'a' && Char
<= L
'f'));
594 Convert a Null-terminated Unicode decimal string to a value of
597 This function returns a value of type UINTN by interpreting the contents
598 of the Unicode string specified by String as a decimal number. The format
599 of the input Unicode string String is:
601 [spaces] [decimal digits].
603 The valid decimal digit character is in the range [0-9]. The
604 function will ignore the pad space, which includes spaces or
605 tab characters, before [decimal digits]. The running zero in the
606 beginning of [decimal digits] will be ignored. Then, the function
607 stops at the first character that is a not a valid decimal character
608 or a Null-terminator, whichever one comes first.
610 If String is NULL, then ASSERT().
611 If String is not aligned in a 16-bit boundary, then ASSERT().
612 If String has only pad spaces, then 0 is returned.
613 If String has no pad spaces or valid decimal digits,
615 If the number represented by String overflows according
616 to the range defined by UINTN, then ASSERT().
618 If PcdMaximumUnicodeStringLength is not zero, and String contains
619 more than PcdMaximumUnicodeStringLength Unicode characters not including
620 the Null-terminator, then ASSERT().
622 @param String Pointer to a Null-terminated Unicode string.
630 IN CONST CHAR16
*String
636 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
637 // Length tests are performed inside StrLen().
639 ASSERT (StrSize (String
) != 0);
642 // Ignore the pad spaces (space or tab)
644 while ((L
' ' ==*String
) || (L
'\t' == *String
)) {
649 // Ignore leading Zeros after the spaces
651 while (L
'0' == *String
) {
657 while (InternalIsDecimalDigitCharacter (*String
)) {
659 // If the number represented by String overflows according
660 // to the range defined by UINTN, then ASSERT().
662 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_10
) ||
663 ((QUIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
664 (*String
- L
'0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10
)
667 Result
= Result
* 10 + (*String
- L
'0');
676 Convert a Null-terminated Unicode decimal string to a value of
679 This function returns a value of type UINT64 by interpreting the contents
680 of the Unicode string specified by String as a decimal number. The format
681 of the input Unicode string String is:
683 [spaces] [decimal digits].
685 The valid decimal digit character is in the range [0-9]. The
686 function will ignore the pad space, which includes spaces or
687 tab characters, before [decimal digits]. The running zero in the
688 beginning of [decimal digits] will be ignored. Then, the function
689 stops at the first character that is a not a valid decimal character
690 or a Null-terminator, whichever one comes first.
692 If String is NULL, then ASSERT().
693 If String is not aligned in a 16-bit boundary, then ASSERT().
694 If String has only pad spaces, then 0 is returned.
695 If String has no pad spaces or valid decimal digits,
697 If the number represented by String overflows according
698 to the range defined by UINT64, then ASSERT().
700 If PcdMaximumUnicodeStringLength is not zero, and String contains
701 more than PcdMaximumUnicodeStringLength Unicode characters not including
702 the Null-terminator, then ASSERT().
704 @param String Pointer to a Null-terminated Unicode string.
712 IN CONST CHAR16
*String
718 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
719 // Length tests are performed inside StrLen().
721 ASSERT (StrSize (String
) != 0);
724 // Ignore the pad spaces (space or tab)
726 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
731 // Ignore leading Zeros after the spaces
733 while (L
'0' == *String
) {
739 while (InternalIsDecimalDigitCharacter (*String
)) {
741 // If the number represented by String overflows according
742 // to the range defined by UINTN, then ASSERT().
744 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_10
) ||
745 ((QUIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
746 (*String
- L
'0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10
)
749 Result
= MultU64x32 (Result
, 10) + (*String
- L
'0');
757 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
759 This function returns a value of type UINTN by interpreting the contents
760 of the Unicode string specified by String as a hexadecimal number.
761 The format of the input Unicode string String is:
763 [spaces][zeros][x][hexadecimal digits].
765 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
766 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
767 If "x" appears in the input string, it must be prefixed with at least one 0.
768 The function will ignore the pad space, which includes spaces or tab characters,
769 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
770 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
771 first valid hexadecimal digit. Then, the function stops at the first character that is
772 a not a valid hexadecimal character or NULL, whichever one comes first.
774 If String is NULL, then ASSERT().
775 If String is not aligned in a 16-bit boundary, then ASSERT().
776 If String has only pad spaces, then zero is returned.
777 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
778 then zero is returned.
779 If the number represented by String overflows according to the range defined by
780 UINTN, then ASSERT().
782 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
783 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
786 @param String Pointer to a Null-terminated Unicode string.
794 IN CONST CHAR16
*String
800 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
801 // Length tests are performed inside StrLen().
803 ASSERT (StrSize (String
) != 0);
806 // Ignore the pad spaces (space or tab)
808 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
813 // Ignore leading Zeros after the spaces
815 while (L
'0' == *String
) {
819 if (InternalCharToUpper (*String
) == L
'X') {
820 ASSERT (L
'0' == *(String
- 1));
821 if (*(String
- 1) != L
'0') {
832 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
834 // If the Hex Number represented by String overflows according
835 // to the range defined by UINTN, then ASSERT().
837 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_16
) ||
838 ((QUIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
839 (InternalHexCharToUintn (*String
) <= REMINDER_MAX_UINTN_DIVIDED_BY_16
))
842 Result
= (Result
<< 4) + InternalHexCharToUintn (*String
);
851 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
853 This function returns a value of type UINT64 by interpreting the contents
854 of the Unicode string specified by String as a hexadecimal number.
855 The format of the input Unicode string String is
857 [spaces][zeros][x][hexadecimal digits].
859 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
860 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
861 If "x" appears in the input string, it must be prefixed with at least one 0.
862 The function will ignore the pad space, which includes spaces or tab characters,
863 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
864 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
865 first valid hexadecimal digit. Then, the function stops at the first character that is
866 a not a valid hexadecimal character or NULL, whichever one comes first.
868 If String is NULL, then ASSERT().
869 If String is not aligned in a 16-bit boundary, then ASSERT().
870 If String has only pad spaces, then zero is returned.
871 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
872 then zero is returned.
873 If the number represented by String overflows according to the range defined by
874 UINT64, then ASSERT().
876 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
877 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
880 @param String Pointer to a Null-terminated Unicode string.
888 IN CONST CHAR16
*String
894 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
895 // Length tests are performed inside StrLen().
897 ASSERT (StrSize (String
) != 0);
900 // Ignore the pad spaces (space or tab)
902 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
907 // Ignore leading Zeros after the spaces
909 while (L
'0' == *String
) {
913 if (InternalCharToUpper (*String
) == L
'X') {
914 ASSERT (L
'0' == *(String
- 1));
915 if (*(String
- 1) != L
'0') {
926 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
928 // If the Hex Number represented by String overflows according
929 // to the range defined by UINTN, then ASSERT().
931 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_16
)||
932 ((QUIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
933 (InternalHexCharToUintn (*String
) <= REMINDER_MAX_UINT64_DIVIDED_BY_16
))
936 Result
= LShiftU64 (Result
, 4);
937 Result
= Result
+ InternalHexCharToUintn (*String
);
945 Check if a ASCII character is a decimal character.
947 This internal function checks if a Unicode character is a
948 decimal character. The valid decimal character is from
951 @param Char The character to check against.
953 @retval TRUE If the Char is a decmial character.
954 @retval FALSE Otherwise.
959 InternalAsciiIsDecimalDigitCharacter (
963 return (BOOLEAN
) (Char
>= '0' && Char
<= '9');
967 Check if a ASCII character is a hexadecimal character.
969 This internal function checks if a ASCII character is a
970 decimal character. The valid hexadecimal character is
971 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
974 @param Char The character to check against.
976 @retval TRUE If the Char is a hexadecmial character.
977 @retval FALSE Otherwise.
982 InternalAsciiIsHexaDecimalDigitCharacter (
987 return (BOOLEAN
) (InternalAsciiIsDecimalDigitCharacter (Char
) ||
988 (Char
>= 'A' && Char
<= 'F') ||
989 (Char
>= 'a' && Char
<= 'f'));
993 Convert a Null-terminated Unicode string to a Null-terminated
994 ASCII string and returns the ASCII string.
996 This function converts the content of the Unicode string Source
997 to the ASCII string Destination by copying the lower 8 bits of
998 each Unicode character. It returns Destination. The function terminates
999 the ASCII string Destination by appending a Null-terminator character
1000 at the end. The caller is responsible to make sure Destination points
1001 to a buffer with size equal or greater than (StrLen (Source) + 1) in bytes.
1003 If Destination is NULL, then ASSERT().
1004 If Source is NULL, then ASSERT().
1005 If Source is not aligned on a 16-bit boundary, then ASSERT().
1006 If Source and Destination overlap, then ASSERT().
1008 If any Unicode characters in Source contain non-zero value in
1009 the upper 8 bits, then ASSERT().
1011 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1012 more than PcdMaximumUnicodeStringLength Unicode characters not including
1013 the Null-terminator, then ASSERT().
1015 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1016 than PcdMaximumAsciiStringLength Unicode characters not including the
1017 Null-terminator, then ASSERT().
1019 @param Source Pointer to a Null-terminated Unicode string.
1020 @param Destination Pointer to a Null-terminated ASCII string.
1027 UnicodeStrToAsciiStr (
1028 IN CONST CHAR16
*Source
,
1029 OUT CHAR8
*Destination
1034 ASSERT (Destination
!= NULL
);
1037 // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
1038 // Length tests are performed inside StrLen().
1040 ASSERT (StrSize (Source
) != 0);
1043 // Source and Destination should not overlap
1045 ASSERT ((UINTN
) ((CHAR16
*) Destination
- Source
) > StrLen (Source
));
1046 ASSERT ((UINTN
) ((CHAR8
*) Source
- Destination
) > StrLen (Source
));
1049 ReturnValue
= Destination
;
1050 while (*Source
!= '\0') {
1052 // If any Unicode characters in Source contain
1053 // non-zero value in the upper 8 bits, then ASSERT().
1055 ASSERT (*Source
< 0x100);
1056 *(Destination
++) = (CHAR8
) *(Source
++);
1059 *Destination
= '\0';
1062 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
1063 // Length tests are performed inside AsciiStrLen().
1065 ASSERT (AsciiStrSize (ReturnValue
) != 0);
1072 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1073 string and returns the new ASCII string.
1075 This function copies the contents of the ASCII string Source to the ASCII
1076 string Destination, and returns Destination. If Source and Destination
1077 overlap, then the results are undefined.
1079 If Destination is NULL, then ASSERT().
1080 If Source is NULL, then ASSERT().
1081 If Source and Destination overlap, then ASSERT().
1082 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1083 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1086 @param Destination Pointer to a Null-terminated ASCII string.
1087 @param Source Pointer to a Null-terminated ASCII string.
1095 OUT CHAR8
*Destination
,
1096 IN CONST CHAR8
*Source
1102 // Destination cannot be NULL
1104 ASSERT (Destination
!= NULL
);
1107 // Destination and source cannot overlap
1109 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1110 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
1112 ReturnValue
= Destination
;
1113 while (*Source
!= 0) {
1114 *(Destination
++) = *(Source
++);
1121 Copies one Null-terminated ASCII string with a maximum length to another
1122 Null-terminated ASCII string with a maximum length and returns the new ASCII
1125 This function copies the contents of the ASCII string Source to the ASCII
1126 string Destination, and returns Destination. At most, Length ASCII characters
1127 are copied from Source to Destination. If Length is 0, then Destination is
1128 returned unmodified. If Length is greater that the number of ASCII characters
1129 in Source, then Destination is padded with Null ASCII characters. If Source
1130 and Destination overlap, then the results are undefined.
1132 If Destination is NULL, then ASSERT().
1133 If Source is NULL, then ASSERT().
1134 If Source and Destination overlap, then ASSERT().
1135 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1136 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1139 @param Destination Pointer to a Null-terminated ASCII string.
1140 @param Source Pointer to a Null-terminated ASCII string.
1141 @param Length Maximum number of ASCII characters to copy.
1149 OUT CHAR8
*Destination
,
1150 IN CONST CHAR8
*Source
,
1161 // Destination cannot be NULL
1163 ASSERT (Destination
!= NULL
);
1166 // Destination and source cannot overlap
1168 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1169 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
1171 ReturnValue
= Destination
;
1173 while (*Source
!= 0 && Length
> 0) {
1174 *(Destination
++) = *(Source
++);
1178 ZeroMem (Destination
, Length
* sizeof (*Destination
));
1183 Returns the length of a Null-terminated ASCII string.
1185 This function returns the number of ASCII characters in the Null-terminated
1186 ASCII string specified by String.
1188 If String is NULL, then ASSERT().
1189 If PcdMaximumAsciiStringLength is not zero and String contains more than
1190 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1193 @param String Pointer to a Null-terminated ASCII string.
1195 @return The length of String.
1201 IN CONST CHAR8
*String
1206 ASSERT (String
!= NULL
);
1208 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
1210 // If PcdMaximumUnicodeStringLength is not zero,
1211 // length should not more than PcdMaximumUnicodeStringLength
1213 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1214 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
1221 Returns the size of a Null-terminated ASCII string in bytes, including the
1224 This function returns the size, in bytes, of the Null-terminated ASCII string
1225 specified by String.
1227 If String is NULL, then ASSERT().
1228 If PcdMaximumAsciiStringLength is not zero and String contains more than
1229 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1232 @param String Pointer to a Null-terminated ASCII string.
1234 @return The size of String.
1240 IN CONST CHAR8
*String
1243 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
1247 Compares two Null-terminated ASCII strings, and returns the difference
1248 between the first mismatched ASCII characters.
1250 This function compares the Null-terminated ASCII string FirstString to the
1251 Null-terminated ASCII string SecondString. If FirstString is identical to
1252 SecondString, then 0 is returned. Otherwise, the value returned is the first
1253 mismatched ASCII character in SecondString subtracted from the first
1254 mismatched ASCII character in FirstString.
1256 If FirstString is NULL, then ASSERT().
1257 If SecondString is NULL, then ASSERT().
1258 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1259 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1261 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1262 than PcdMaximumAsciiStringLength ASCII characters not including the
1263 Null-terminator, then ASSERT().
1265 @param FirstString Pointer to a Null-terminated ASCII string.
1266 @param SecondString Pointer to a Null-terminated ASCII string.
1268 @retval 0 FirstString is identical to SecondString.
1269 @retval !=0 FirstString is not identical to SecondString.
1275 IN CONST CHAR8
*FirstString
,
1276 IN CONST CHAR8
*SecondString
1280 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1282 ASSERT (AsciiStrSize (FirstString
));
1283 ASSERT (AsciiStrSize (SecondString
));
1285 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
1290 return *FirstString
- *SecondString
;
1294 Converts a lowercase Ascii character to upper one
1296 If Chr is lowercase Ascii character, then converts it to upper one.
1298 If Value >= 0xA0, then ASSERT().
1299 If (Value & 0x0F) >= 0x0A, then ASSERT().
1301 @param Chr one Ascii character
1303 @return The uppercase value of Ascii character
1312 return (UINT8
) ((Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
);
1316 Convert a ASCII character to numerical value.
1318 This internal function only deal with Unicode character
1319 which maps to a valid hexadecimal ASII character, i.e.
1320 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1321 ASCII character, the value returned does not make sense.
1323 @param Char The character to convert.
1325 @retval UINTN The numerical value converted.
1330 InternalAsciiHexCharToUintn (
1334 if (InternalIsDecimalDigitCharacter (Char
)) {
1338 return (UINTN
) (10 + AsciiToUpper (Char
) - 'A');
1343 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1344 and returns the difference between the first mismatched ASCII characters.
1346 This function performs a case insensitive comparison of the Null-terminated
1347 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1348 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1349 value returned is the first mismatched lower case ASCII character in
1350 SecondString subtracted from the first mismatched lower case ASCII character
1353 If FirstString is NULL, then ASSERT().
1354 If SecondString is NULL, then ASSERT().
1355 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1356 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1358 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1359 than PcdMaximumAsciiStringLength ASCII characters not including the
1360 Null-terminator, then ASSERT().
1362 @param FirstString Pointer to a Null-terminated ASCII string.
1363 @param SecondString Pointer to a Null-terminated ASCII string.
1365 @retval 0 FirstString is identical to SecondString using case insensitive
1367 @retval !=0 FirstString is not identical to SecondString using case
1368 insensitive comparisons.
1374 IN CONST CHAR8
*FirstString
,
1375 IN CONST CHAR8
*SecondString
1378 CHAR8 UpperFirstString
;
1379 CHAR8 UpperSecondString
;
1382 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1384 ASSERT (AsciiStrSize (FirstString
));
1385 ASSERT (AsciiStrSize (SecondString
));
1387 UpperFirstString
= AsciiToUpper (*FirstString
);
1388 UpperSecondString
= AsciiToUpper (*SecondString
);
1389 while ((*FirstString
!= '\0') && (UpperFirstString
== UpperSecondString
)) {
1392 UpperFirstString
= AsciiToUpper (*FirstString
);
1393 UpperSecondString
= AsciiToUpper (*SecondString
);
1396 return UpperFirstString
- UpperSecondString
;
1400 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1401 the difference between the first mismatched ASCII characters.
1403 This function compares the Null-terminated ASCII string FirstString to the
1404 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1405 will be compared. If Length is 0, then 0 is returned. If FirstString is
1406 identical to SecondString, then 0 is returned. Otherwise, the value returned
1407 is the first mismatched ASCII character in SecondString subtracted from the
1408 first mismatched ASCII character in FirstString.
1410 If FirstString is NULL, then ASSERT().
1411 If SecondString is NULL, then ASSERT().
1412 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1413 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1415 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
1416 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1419 @param FirstString Pointer to a Null-terminated ASCII string.
1420 @param SecondString Pointer to a Null-terminated ASCII string.
1421 @param Length Maximum number of ASCII characters to compare.
1423 @retval 0 FirstString is identical to SecondString.
1424 @retval !=0 FirstString is not identical to SecondString.
1430 IN CONST CHAR8
*FirstString
,
1431 IN CONST CHAR8
*SecondString
,
1440 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1442 ASSERT (AsciiStrSize (FirstString
));
1443 ASSERT (AsciiStrSize (SecondString
));
1445 while ((*FirstString
!= '\0') &&
1446 (*FirstString
== *SecondString
) &&
1452 return *FirstString
- *SecondString
;
1456 Concatenates one Null-terminated ASCII string to another Null-terminated
1457 ASCII string, and returns the concatenated ASCII string.
1459 This function concatenates two Null-terminated ASCII strings. The contents of
1460 Null-terminated ASCII string Source are concatenated to the end of Null-
1461 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1464 If Destination is NULL, then ASSERT().
1465 If Source is NULL, then ASSERT().
1466 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1467 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1469 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1470 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1472 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1473 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1474 ASCII characters, then ASSERT().
1476 @param Destination Pointer to a Null-terminated ASCII string.
1477 @param Source Pointer to a Null-terminated ASCII string.
1485 IN OUT CHAR8
*Destination
,
1486 IN CONST CHAR8
*Source
1489 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
1492 // Size of the resulting string should never be zero.
1493 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1495 ASSERT (AsciiStrSize (Destination
) != 0);
1500 Concatenates one Null-terminated ASCII string with a maximum length to the
1501 end of another Null-terminated ASCII string, and returns the concatenated
1504 This function concatenates two Null-terminated ASCII strings. The contents
1505 of Null-terminated ASCII string Source are concatenated to the end of Null-
1506 terminated ASCII string Destination, and Destination is returned. At most,
1507 Length ASCII characters are concatenated from Source to the end of
1508 Destination, and Destination is always Null-terminated. If Length is 0, then
1509 Destination is returned unmodified. If Source and Destination overlap, then
1510 the results are undefined.
1512 If Destination is NULL, then ASSERT().
1513 If Source is NULL, then ASSERT().
1514 If Source and Destination overlap, then ASSERT().
1515 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1516 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1518 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1519 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1521 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1522 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1523 ASCII characters not including the Null-terminator, then ASSERT().
1525 @param Destination Pointer to a Null-terminated ASCII string.
1526 @param Source Pointer to a Null-terminated ASCII string.
1527 @param Length Maximum number of ASCII characters to concatenate from
1536 IN OUT CHAR8
*Destination
,
1537 IN CONST CHAR8
*Source
,
1541 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
1544 // Size of the resulting string should never be zero.
1545 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1547 ASSERT (AsciiStrSize (Destination
) != 0);
1552 Returns the first occurance of a Null-terminated ASCII sub-string
1553 in a Null-terminated ASCII string.
1555 This function scans the contents of the ASCII string specified by String
1556 and returns the first occurrence of SearchString. If SearchString is not
1557 found in String, then NULL is returned. If the length of SearchString is zero,
1558 then String is returned.
1560 If String is NULL, then ASSERT().
1561 If SearchString is NULL, then ASSERT().
1563 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1564 String contains more than PcdMaximumAsciiStringLength Unicode characters
1565 not including the Null-terminator, then ASSERT().
1567 @param String Pointer to a Null-terminated ASCII string.
1568 @param SearchString Pointer to a Null-terminated ASCII string to search for.
1570 @retval NULL If the SearchString does not appear in String.
1571 @retval !NULL If there is a match.
1577 IN CONST CHAR8
*String
,
1578 IN CONST CHAR8
*SearchString
1581 CONST CHAR8
*FirstMatch
;
1582 CONST CHAR8
*SearchStringTmp
;
1585 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1587 ASSERT (AsciiStrSize (String
) != 0);
1588 ASSERT (AsciiStrSize (SearchString
) != 0);
1590 while (*String
!= '\0') {
1591 SearchStringTmp
= SearchString
;
1592 FirstMatch
= String
;
1594 while ((*String
== *SearchStringTmp
)
1595 && (*SearchStringTmp
!= '\0')
1596 && (*String
!= '\0')) {
1601 if (*SearchStringTmp
== '\0') {
1602 return (CHAR8
*) FirstMatch
;
1605 if (SearchStringTmp
== SearchString
) {
1607 // If no character from SearchString match,
1608 // move the pointer to the String under search
1609 // by one character.
1620 Convert a Null-terminated ASCII decimal string to a value of type
1623 This function returns a value of type UINTN by interpreting the contents
1624 of the ASCII string String as a decimal number. The format of the input
1625 ASCII string String is:
1627 [spaces] [decimal digits].
1629 The valid decimal digit character is in the range [0-9]. The function will
1630 ignore the pad space, which includes spaces or tab characters, before the digits.
1631 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1632 function stops at the first character that is a not a valid decimal character or
1633 Null-terminator, whichever on comes first.
1635 If String has only pad spaces, then 0 is returned.
1636 If String has no pad spaces or valid decimal digits, then 0 is returned.
1637 If the number represented by String overflows according to the range defined by
1638 UINTN, then ASSERT().
1639 If String is NULL, then ASSERT().
1640 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1641 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1644 @param String Pointer to a Null-terminated ASCII string.
1651 AsciiStrDecimalToUintn (
1652 IN CONST CHAR8
*String
1658 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1660 ASSERT (AsciiStrSize (String
) != 0);
1663 // Ignore the pad spaces (space or tab)
1665 while ((' ' == *String
) || ('\t' == *String
)) {
1670 // Ignore leading Zeros after the spaces
1672 while ('0' == *String
) {
1678 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1680 // If the number represented by String overflows according
1681 // to the range defined by UINTN, then ASSERT().
1683 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_10
) ||
1684 ((QUIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
1685 (*String
- '0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10
)
1688 Result
= Result
* 10 + (*String
- '0');
1697 Convert a Null-terminated ASCII decimal string to a value of type
1700 This function returns a value of type UINT64 by interpreting the contents
1701 of the ASCII string String as a decimal number. The format of the input
1702 ASCII string String is:
1704 [spaces] [decimal digits].
1706 The valid decimal digit character is in the range [0-9]. The function will
1707 ignore the pad space, which includes spaces or tab characters, before the digits.
1708 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1709 function stops at the first character that is a not a valid decimal character or
1710 Null-terminator, whichever on comes first.
1712 If String has only pad spaces, then 0 is returned.
1713 If String has no pad spaces or valid decimal digits, then 0 is returned.
1714 If the number represented by String overflows according to the range defined by
1715 UINT64, then ASSERT().
1716 If String is NULL, then ASSERT().
1717 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1718 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1721 @param String Pointer to a Null-terminated ASCII string.
1728 AsciiStrDecimalToUint64 (
1729 IN CONST CHAR8
*String
1735 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1737 ASSERT (AsciiStrSize (String
) != 0);
1740 // Ignore the pad spaces (space or tab)
1742 while ((' ' == *String
) || ('\t' == *String
)) {
1747 // Ignore leading Zeros after the spaces
1749 while ('0' == *String
) {
1755 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1757 // If the number represented by String overflows according
1758 // to the range defined by UINTN, then ASSERT().
1760 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_10
) ||
1761 ((QUIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
1762 (*String
- '0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10
)
1765 Result
= MultU64x32 (Result
, 10) + (*String
- '0');
1773 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1775 This function returns a value of type UINTN by interpreting the contents of
1776 the ASCII string String as a hexadecimal number. The format of the input ASCII
1779 [spaces][zeros][x][hexadecimal digits].
1781 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1782 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1783 appears in the input string, it must be prefixed with at least one 0. The function
1784 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1785 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1786 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1787 digit. Then, the function stops at the first character that is a not a valid
1788 hexadecimal character or Null-terminator, whichever on comes first.
1790 If String has only pad spaces, then 0 is returned.
1791 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1794 If the number represented by String overflows according to the range defined by UINTN,
1796 If String is NULL, then ASSERT().
1797 If PcdMaximumAsciiStringLength is not zero,
1798 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1799 the Null-terminator, then ASSERT().
1801 @param String Pointer to a Null-terminated ASCII string.
1808 AsciiStrHexToUintn (
1809 IN CONST CHAR8
*String
1815 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1817 ASSERT (AsciiStrSize (String
) != 0);
1820 // Ignore the pad spaces (space or tab)
1822 while ((' ' == *String
) || ('\t' == *String
)) {
1827 // Ignore leading Zeros after the spaces
1829 while ('0' == *String
) {
1833 if (AsciiToUpper (*String
) == 'X') {
1834 ASSERT ('0' == *(String
- 1));
1835 if (*(String
- 1) != '0') {
1846 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1848 // If the Hex Number represented by String overflows according
1849 // to the range defined by UINTN, then ASSERT().
1851 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_16
) ||
1852 ((QUIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
1853 (InternalAsciiHexCharToUintn (*String
) <= REMINDER_MAX_UINTN_DIVIDED_BY_16
))
1856 Result
= (Result
<< 4) + InternalAsciiHexCharToUintn (*String
);
1865 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1867 This function returns a value of type UINT64 by interpreting the contents of
1868 the ASCII string String as a hexadecimal number. The format of the input ASCII
1871 [spaces][zeros][x][hexadecimal digits].
1873 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1874 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1875 appears in the input string, it must be prefixed with at least one 0. The function
1876 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1877 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1878 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1879 digit. Then, the function stops at the first character that is a not a valid
1880 hexadecimal character or Null-terminator, whichever on comes first.
1882 If String has only pad spaces, then 0 is returned.
1883 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1886 If the number represented by String overflows according to the range defined by UINT64,
1888 If String is NULL, then ASSERT().
1889 If PcdMaximumAsciiStringLength is not zero,
1890 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1891 the Null-terminator, then ASSERT().
1893 @param String Pointer to a Null-terminated ASCII string.
1900 AsciiStrHexToUint64 (
1901 IN CONST CHAR8
*String
1907 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1909 ASSERT (AsciiStrSize (String
) != 0);
1912 // Ignore the pad spaces (space or tab) and leading Zeros
1915 // Ignore the pad spaces (space or tab)
1917 while ((' ' == *String
) || ('\t' == *String
)) {
1922 // Ignore leading Zeros after the spaces
1924 while ('0' == *String
) {
1928 if (AsciiToUpper (*String
) == 'X') {
1929 ASSERT ('0' == *(String
- 1));
1930 if (*(String
- 1) != '0') {
1941 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1943 // If the Hex Number represented by String overflows according
1944 // to the range defined by UINTN, then ASSERT().
1946 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_16
) ||
1947 ((QUIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
1948 (InternalAsciiHexCharToUintn (*String
) <= REMINDER_MAX_UINT64_DIVIDED_BY_16
))
1951 Result
= LShiftU64 (Result
, 4);
1952 Result
= Result
+ InternalAsciiHexCharToUintn (*String
);
1961 Convert one Null-terminated ASCII string to a Null-terminated
1962 Unicode string and returns the Unicode string.
1964 This function converts the contents of the ASCII string Source to the Unicode
1965 string Destination, and returns Destination. The function terminates the
1966 Unicode string Destination by appending a Null-terminator character at the end.
1967 The caller is responsible to make sure Destination points to a buffer with size
1968 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1970 If Destination is NULL, then ASSERT().
1971 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1972 If Source is NULL, then ASSERT().
1973 If Source and Destination overlap, then ASSERT().
1974 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1975 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1977 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1978 PcdMaximumUnicodeStringLength ASCII characters not including the
1979 Null-terminator, then ASSERT().
1981 @param Source Pointer to a Null-terminated ASCII string.
1982 @param Destination Pointer to a Null-terminated Unicode string.
1989 AsciiStrToUnicodeStr (
1990 IN CONST CHAR8
*Source
,
1991 OUT CHAR16
*Destination
1994 CHAR16
*ReturnValue
;
1996 ASSERT (Destination
!= NULL
);
1999 // ASSERT Source is less long than PcdMaximumAsciiStringLength
2001 ASSERT (AsciiStrSize (Source
) != 0);
2004 // Source and Destination should not overlap
2006 ASSERT ((UINTN
) ((CHAR8
*) Destination
- Source
) > AsciiStrLen (Source
));
2007 ASSERT ((UINTN
) (Source
- (CHAR8
*) Destination
) > (AsciiStrLen (Source
) * sizeof (CHAR16
)));
2010 ReturnValue
= Destination
;
2011 while (*Source
!= '\0') {
2012 *(Destination
++) = (CHAR16
) *(Source
++);
2015 // End the Destination with a NULL.
2017 *Destination
= '\0';
2020 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
2022 ASSERT (StrSize (ReturnValue
) != 0);
2028 Converts an 8-bit value to an 8-bit BCD value.
2030 Converts the 8-bit value specified by Value to BCD. The BCD value is
2033 If Value >= 100, then ASSERT().
2035 @param Value The 8-bit value to convert to BCD. Range 0..99.
2037 @return The BCD value
2046 ASSERT (Value
< 100);
2047 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2051 Converts an 8-bit BCD value to an 8-bit value.
2053 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2056 If Value >= 0xA0, then ASSERT().
2057 If (Value & 0x0F) >= 0x0A, then ASSERT().
2059 @param Value The 8-bit BCD value to convert to an 8-bit value.
2061 @return The 8-bit value is returned.
2070 ASSERT (Value
< 0xa0);
2071 ASSERT ((Value
& 0xf) < 0xa);
2072 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));
2077 Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character.
2079 This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal
2080 character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A'
2083 The upper nibble in the input byte will be masked off.
2085 @param Nibble The nibble which is in the low 4 bits of the input byte.
2087 @retval CHAR16 The Unicode hexadecimal character.
2096 if (Nibble
<= 0x9) {
2097 return (CHAR16
)(Nibble
+ L
'0');
2100 return (CHAR16
)(Nibble
- 0xA + L
'A');
2104 Convert binary buffer to a Unicode String in a specified sequence.
2106 This function converts bytes in the binary Buffer Buf to a Unicode String Str.
2107 Each byte will be represented by two Unicode characters. For example, byte 0xA1 will
2108 be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character
2109 for the Most Significant Nibble will be put before the Unicode Character for the Least Significant
2110 Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1".
2111 For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the
2112 the last character in the output string. The one next to first byte will be put into the
2113 character before the last character. This rules applies to the rest of the bytes. The Unicode
2114 character by the last byte will be put into the first character in the output string. For example,
2115 the input buffer for a 64-bits unsigned integrer 0x12345678abcdef1234 will be converted to
2116 a Unicode string equal to L"12345678abcdef1234".
2118 @param String On input, String is pointed to the buffer allocated for the convertion.
2119 @param StringLen The Length of String buffer to hold the output String. The length must include the tailing '\0' character.
2120 The StringLen required to convert a N bytes Buffer will be a least equal to or greater
2122 @param Buffer The pointer to a input buffer.
2123 @param BufferSizeInBytes Lenth in bytes of the input buffer.
2126 @retval EFI_SUCCESS The convertion is successfull. All bytes in Buffer has been convert to the corresponding
2127 Unicode character and placed into the right place in String.
2128 @retval EFI_BUFFER_TOO_SMALL StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to
2129 complete the convertion.
2134 IN OUT CHAR16
*String
,
2135 IN OUT UINTN
*StringLen
,
2136 IN CONST UINT8
*Buffer
,
2137 IN UINTN BufferSizeInBytes
2145 // Make sure string is either passed or allocate enough.
2146 // It takes 2 Unicode characters (4 bytes) to represent 1 byte of the binary buffer.
2147 // Plus the Unicode termination character.
2149 StrLen
= BufferSizeInBytes
* 2;
2150 if (StrLen
> ((*StringLen
) - 1)) {
2151 *StringLen
= StrLen
+ 1;
2152 return RETURN_BUFFER_TOO_SMALL
;
2155 *StringLen
= StrLen
+ 1;
2159 String
[StrLen
] = L
'\0';
2161 for (Idx
= 0; Idx
< BufferSizeInBytes
; Idx
++) {
2164 String
[StrLen
- 1 - Idx
* 2] = NibbleToHexChar (Byte
);
2165 String
[StrLen
- 2 - Idx
* 2] = NibbleToHexChar ((UINT8
)(Byte
>> 4));
2168 return RETURN_SUCCESS
;
2173 Convert a Unicode string consisting of hexadecimal characters to a output byte buffer.
2175 This function converts a Unicode string consisting of characters in the range of Hexadecimal
2176 character (L'0' to L'9', L'A' to L'F' and L'a' to L'f') to a output byte buffer. The function will stop
2177 at the first non-hexadecimal character or the NULL character. The convertion process can be
2178 simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be
2179 converted into one byte. The first Unicode character represents the Most Significant Nibble and the
2180 second Unicode character represents the Least Significant Nibble in the output byte.
2181 The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode
2182 characters represent the the byte preceding the last byte. This rule applies to the rest pairs of bytes.
2183 The last pair represent the first byte in the output buffer.
2185 For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes
2186 (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12".
2188 If String has N valid hexadecimal characters for conversion, the caller must make sure Buffer is at least
2189 N/2 (if N is even) or (N+1)/2 (if N if odd) bytes.
2191 @param Buffer The output buffer allocated by the caller.
2192 @param BufferSizeInBytes On input, the size in bytes of Buffer. On output, it is updated to
2193 contain the size of the Buffer which is actually used for the converstion.
2194 For Unicode string with 2*N hexadecimal characters (not including the
2195 tailing NULL character), N bytes of Buffer will be used for the output.
2196 @param String The input hexadecimal string.
2197 @param ConvertedStrLen The number of hexadecimal characters used to produce content in output
2200 @retval RETURN_BUFFER_TOO_SMALL The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes
2201 will be updated to the size required for the converstion.
2202 @retval RETURN_SUCCESS The convertion is successful or the first Unicode character from String
2203 is hexadecimal. If ConvertedStrLen is not NULL, it is updated
2204 to the number of hexadecimal character used for the converstion.
2210 IN OUT UINTN
*BufferSizeInBytes
,
2211 IN CONST CHAR16
*String
,
2212 OUT UINTN
*ConvertedStrLen OPTIONAL
2222 // Find out how many hex characters the string has.
2224 for (Idx
= 0, HexCnt
= 0; IsHexDigit (&Digit
, String
[Idx
]); Idx
++, HexCnt
++);
2227 *ConvertedStrLen
= 0;
2228 return RETURN_SUCCESS
;
2231 // Two Unicode characters make up 1 buffer byte. Round up.
2233 BufferLength
= (HexCnt
+ 1) / 2;
2236 // Test if buffer is passed enough.
2238 if (BufferLength
> (*BufferSizeInBytes
)) {
2239 *BufferSizeInBytes
= BufferLength
;
2240 return RETURN_BUFFER_TOO_SMALL
;
2243 *BufferSizeInBytes
= BufferLength
;
2245 for (Idx
= 0; Idx
< HexCnt
; Idx
++) {
2247 IsHexDigit (&Digit
, String
[HexCnt
- 1 - Idx
]);
2250 // For odd charaters, write the lower nibble for each buffer byte,
2251 // and for even characters, the upper nibble.
2253 if ((Idx
& 1) == 0) {
2256 Byte
= Buffer
[Idx
/ 2];
2258 Byte
= (UINT8
) (Byte
| Digit
<< 4);
2261 Buffer
[Idx
/ 2] = Byte
;
2264 if (ConvertedStrLen
!= NULL
) {
2265 *ConvertedStrLen
= HexCnt
;
2268 return RETURN_SUCCESS
;
2273 Test if a Unicode character is a hexadecimal digit. If true, the input
2274 Unicode character is converted to a byte.
2276 This function tests if a Unicode character is a hexadecimal digit. If true, the input
2277 Unicode character is converted to a byte. For example, Unicode character
2278 L'A' will be converted to 0x0A.
2280 If Digit is NULL, then ASSERT.
2282 @retval TRUE Char is in the range of Hexadecimal number. Digit is updated
2283 to the byte value of the number.
2284 @retval FALSE Char is not in the range of Hexadecimal number. Digit is keep
2294 ASSERT (Digit
!= NULL
);
2296 if ((Char
>= L
'0') && (Char
<= L
'9')) {
2297 *Digit
= (UINT8
) (Char
- L
'0');
2301 if ((Char
>= L
'A') && (Char
<= L
'F')) {
2302 *Digit
= (UINT8
) (Char
- L
'A' + 0x0A);
2306 if ((Char
>= L
'a') && (Char
<= L
'f')) {
2307 *Digit
= (UINT8
) (Char
- L
'a' + 0x0A);