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.
18 #include "BaseLibInternals.h"
21 Copies one Null-terminated Unicode string to another Null-terminated Unicode
22 string and returns the new Unicode string.
24 This function copies the contents of the Unicode string Source to the Unicode
25 string Destination, and returns Destination. If Source and Destination
26 overlap, then the results are undefined.
28 If Destination is NULL, then ASSERT().
29 If Destination is not aligned on a 16-bit boundary, then ASSERT().
30 If Source is NULL, then ASSERT().
31 If Source is not aligned on a 16-bit boundary, then ASSERT().
32 If Source and Destination overlap, then ASSERT().
33 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
34 PcdMaximumUnicodeStringLength Unicode characters not including the
35 Null-terminator, then ASSERT().
37 @param Destination Pointer to a Null-terminated Unicode string.
38 @param Source Pointer to a Null-terminated Unicode string.
46 OUT CHAR16
*Destination
,
47 IN CONST CHAR16
*Source
53 // Destination cannot be NULL
55 ASSERT (Destination
!= NULL
);
56 ASSERT (((UINTN
) Destination
& 0x01) == 0);
59 // Destination and source cannot overlap
61 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
62 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
64 ReturnValue
= Destination
;
65 while (*Source
!= 0) {
66 *(Destination
++) = *(Source
++);
73 Copies one Null-terminated Unicode string with a maximum length to another
74 Null-terminated Unicode string with a maximum length and returns the new
77 This function copies the contents of the Unicode string Source to the Unicode
78 string Destination, and returns Destination. At most, Length Unicode
79 characters are copied from Source to Destination. If Length is 0, then
80 Destination is returned unmodified. If Length is greater that the number of
81 Unicode characters in Source, then Destination is padded with Null Unicode
82 characters. If Source and Destination overlap, then the results are
85 If Length > 0 and Destination is NULL, then ASSERT().
86 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
87 If Length > 0 and Source is NULL, then ASSERT().
88 If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
89 If Source and Destination overlap, then ASSERT().
90 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
91 PcdMaximumUnicodeStringLength Unicode characters not including the
92 Null-terminator, then ASSERT().
94 @param Destination Pointer to a Null-terminated Unicode string.
95 @param Source Pointer to a Null-terminated Unicode string.
96 @param Length Maximum number of Unicode characters to copy.
104 OUT CHAR16
*Destination
,
105 IN CONST CHAR16
*Source
,
116 // Destination cannot be NULL if Length is not zero
118 ASSERT (Destination
!= NULL
);
119 ASSERT (((UINTN
) Destination
& 0x01) == 0);
122 // Destination and source cannot overlap
123 // Q: Does Source have to be NULL-terminated?
125 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
126 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
128 ReturnValue
= Destination
;
130 while ((*Source
!= L
'\0') && (Length
> 0)) {
131 *(Destination
++) = *(Source
++);
135 ZeroMem (Destination
, Length
* sizeof (*Destination
));
140 Returns the length of a Null-terminated Unicode string.
142 This function returns the number of Unicode characters in the Null-terminated
143 Unicode string specified by String.
145 If String is NULL, then ASSERT().
146 If String is not aligned on a 16-bit boundary, then ASSERT().
147 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
148 PcdMaximumUnicodeStringLength Unicode characters not including the
149 Null-terminator, then ASSERT().
151 @param String Pointer to a Null-terminated Unicode string.
153 @return The length of String.
159 IN CONST CHAR16
*String
164 ASSERT (String
!= NULL
);
165 ASSERT (((UINTN
) String
& 0x01) == 0);
167 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
169 // If PcdMaximumUnicodeStringLength is not zero,
170 // length should not more than PcdMaximumUnicodeStringLength
172 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
173 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
180 Returns the size of a Null-terminated Unicode string in bytes, including the
183 This function returns the size, in bytes, of the Null-terminated Unicode
184 string specified by String.
186 If String is NULL, then ASSERT().
187 If String is not aligned on a 16-bit boundary, then ASSERT().
188 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
189 PcdMaximumUnicodeStringLength Unicode characters not including the
190 Null-terminator, then ASSERT().
192 @param String Pointer to a Null-terminated Unicode string.
194 @return The size in bytes of String.
200 IN CONST CHAR16
*String
203 return (StrLen (String
) + 1) * sizeof (*String
);
207 Compares two Null-terminated Unicode strings, and returns the difference
208 between the first mismatched Unicode characters.
210 This function compares the Null-terminated Unicode string FirstString to the
211 Null-terminated Unicode string SecondString. If FirstString is identical to
212 SecondString, then 0 is returned. Otherwise, the value returned is the first
213 mismatched Unicode character in SecondString subtracted from the first
214 mismatched Unicode character in FirstString.
216 If FirstString is NULL, then ASSERT().
217 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
218 If SecondString is NULL, then ASSERT().
219 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
220 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
221 than PcdMaximumUnicodeStringLength Unicode characters not including the
222 Null-terminator, then ASSERT().
223 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
224 than PcdMaximumUnicodeStringLength Unicode characters not including the
225 Null-terminator, then ASSERT().
227 @param FirstString Pointer to a Null-terminated Unicode string.
228 @param SecondString Pointer to a Null-terminated Unicode string.
230 @retval 0 FirstString is identical to SecondString.
231 @return others FirstString is not identical to SecondString.
237 IN CONST CHAR16
*FirstString
,
238 IN CONST CHAR16
*SecondString
242 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
244 ASSERT (StrSize (FirstString
) != 0);
245 ASSERT (StrSize (SecondString
) != 0);
247 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
251 return *FirstString
- *SecondString
;
255 Compares two Null-terminated Unicode strings with maximum lengths, and
256 returns the difference between the first mismatched Unicode characters.
258 This function compares the Null-terminated Unicode string FirstString to the
259 Null-terminated Unicode string SecondString. At most, Length Unicode
260 characters will be compared. If Length is 0, then 0 is returned. If
261 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
262 value returned is the first mismatched Unicode character in SecondString
263 subtracted from the first mismatched Unicode character in FirstString.
265 If Length > 0 and FirstString is NULL, then ASSERT().
266 If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
267 If Length > 0 and SecondString is NULL, then ASSERT().
268 If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
269 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
270 than PcdMaximumUnicodeStringLength Unicode characters not including the
271 Null-terminator, then ASSERT().
272 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
273 than PcdMaximumUnicodeStringLength Unicode characters not including the
274 Null-terminator, then ASSERT().
276 @param FirstString Pointer to a Null-terminated Unicode string.
277 @param SecondString Pointer to a Null-terminated Unicode string.
278 @param Length Maximum number of Unicode characters to compare.
280 @retval 0 FirstString is identical to SecondString.
281 @return others FirstString is not identical to SecondString.
287 IN CONST CHAR16
*FirstString
,
288 IN CONST CHAR16
*SecondString
,
297 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
298 // Length tests are performed inside StrLen().
300 ASSERT (StrSize (FirstString
) != 0);
301 ASSERT (StrSize (SecondString
) != 0);
303 while ((*FirstString
!= L
'\0') &&
304 (*FirstString
== *SecondString
) &&
311 return *FirstString
- *SecondString
;
315 Concatenates one Null-terminated Unicode string to another Null-terminated
316 Unicode string, and returns the concatenated Unicode string.
318 This function concatenates two Null-terminated Unicode strings. The contents
319 of Null-terminated Unicode string Source are concatenated to the end of
320 Null-terminated Unicode string Destination. The Null-terminated concatenated
321 Unicode String is returned. If Source and Destination overlap, then the
322 results are undefined.
324 If Destination is NULL, then ASSERT().
325 If Source is NULL, then ASSERT().
326 If Source and Destination overlap, then ASSERT().
327 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
328 than PcdMaximumUnicodeStringLength Unicode characters not including the
329 Null-terminator, then ASSERT().
330 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
331 PcdMaximumUnicodeStringLength Unicode characters not including the
332 Null-terminator, then ASSERT().
333 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
334 and Source results in a Unicode string with more than
335 PcdMaximumUnicodeStringLength Unicode characters not including the
336 Null-terminator, then ASSERT().
338 @param Destination Pointer to a Null-terminated Unicode string.
339 @param Source Pointer to a Null-terminated Unicode string.
347 IN OUT CHAR16
*Destination
,
348 IN CONST CHAR16
*Source
351 StrCpy (Destination
+ StrLen (Destination
), Source
);
354 // Size of the resulting string should never be zero.
355 // PcdMaximumUnicodeStringLength is tested inside StrLen().
357 ASSERT (StrSize (Destination
) != 0);
362 Concatenates one Null-terminated Unicode string with a maximum length to the
363 end of another Null-terminated Unicode string, and returns the concatenated
366 This function concatenates two Null-terminated Unicode strings. The contents
367 of Null-terminated Unicode string Source are concatenated to the end of
368 Null-terminated Unicode string Destination, and Destination is returned. At
369 most, Length Unicode characters are concatenated from Source to the end of
370 Destination, and Destination is always Null-terminated. If Length is 0, then
371 Destination is returned unmodified. If Source and Destination overlap, then
372 the results are undefined.
374 If Destination is NULL, then ASSERT().
375 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
376 If Length > 0 and Source is NULL, then ASSERT().
377 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
378 If Source and Destination overlap, then ASSERT().
379 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
380 than PcdMaximumUnicodeStringLength Unicode characters not including the
381 Null-terminator, then ASSERT().
382 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
383 PcdMaximumUnicodeStringLength Unicode characters not including the
384 Null-terminator, then ASSERT().
385 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
386 and Source results in a Unicode string with more than
387 PcdMaximumUnicodeStringLength Unicode characters not including the
388 Null-terminator, then ASSERT().
390 @param Destination Pointer to a Null-terminated Unicode string.
391 @param Source Pointer to a Null-terminated Unicode string.
392 @param Length Maximum number of Unicode characters to concatenate from
401 IN OUT CHAR16
*Destination
,
402 IN CONST CHAR16
*Source
,
406 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
409 // Size of the resulting string should never be zero.
410 // PcdMaximumUnicodeStringLength is tested inside StrLen().
412 ASSERT (StrSize (Destination
) != 0);
417 Returns the first occurance of a Null-terminated Unicode sub-string
418 in a Null-terminated Unicode string.
420 This function scans the contents of the Null-terminated Unicode string
421 specified by String and returns the first occurrence of SearchString.
422 If SearchString is not found in String, then NULL is returned. If
423 the length of SearchString is zero, then String is
426 If String is NULL, then ASSERT().
427 If String is not aligned on a 16-bit boundary, then ASSERT().
428 If SearchString is NULL, then ASSERT().
429 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
431 If PcdMaximumUnicodeStringLength is not zero, and SearchString
432 or String contains more than PcdMaximumUnicodeStringLength Unicode
433 characters not including the Null-terminator, then ASSERT().
435 @param String Pointer to a Null-terminated Unicode string.
436 @param SearchString Pointer to a Null-terminated Unicode string to search for.
438 @retval NULL If the SearchString does not appear in String.
439 @return others If there is a match.
445 IN CONST CHAR16
*String
,
446 IN CONST CHAR16
*SearchString
449 CONST CHAR16
*FirstMatch
;
450 CONST CHAR16
*SearchStringTmp
;
453 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
454 // Length tests are performed inside StrLen().
456 ASSERT (StrSize (String
) != 0);
457 ASSERT (StrSize (SearchString
) != 0);
459 while (*String
!= '\0') {
460 SearchStringTmp
= SearchString
;
463 while ((*String
== *SearchStringTmp
)
464 && (*SearchStringTmp
!= '\0')
465 && (*String
!= '\0')) {
470 if ('\0' == *SearchStringTmp
) {
471 return (CHAR16
*) FirstMatch
;
474 if (SearchStringTmp
== SearchString
) {
476 // If no character from SearchString match,
477 // move the pointer to the String under search
488 Check if a Unicode character is a decimal character.
490 This internal function checks if a Unicode character is a
491 decimal character. The valid decimal character is from
495 @param Char The character to check against.
497 @retval TRUE If the Char is a decmial character.
498 @retval FALSE Otherwise.
503 InternalIsDecimalDigitCharacter (
507 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
511 Convert a Unicode character to upper case only if
512 it maps to a valid small-case ASCII character.
514 This internal function only deal with Unicode character
515 which maps to a valid small-case ASII character, i.e.
516 L'a' to L'z'. For other Unicode character, the input character
517 is returned directly.
520 @param Char The character to convert.
522 @retval LowerCharacter If the Char is with range L'a' to L'z'.
523 @retval Unchanged Otherwise.
528 InternalCharToUpper (
532 if (Char
>= L
'a' && Char
<= L
'z') {
533 return (CHAR16
) (Char
- (L
'a' - L
'A'));
540 Convert a Unicode character to numerical value.
542 This internal function only deal with Unicode character
543 which maps to a valid hexadecimal ASII character, i.e.
544 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
545 Unicode character, the value returned does not make sense.
547 @param Char The character to convert.
549 @retval UINTN The numerical value converted.
554 InternalHexCharToUintn (
558 if (InternalIsDecimalDigitCharacter (Char
)) {
562 return (UINTN
) (10 + InternalCharToUpper (Char
) - L
'A');
566 Check if a Unicode character is a hexadecimal character.
568 This internal function checks if a Unicode character is a
569 decimal character. The valid hexadecimal character is
570 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
573 @param Char The character to check against.
575 @retval TRUE If the Char is a hexadecmial character.
576 @retval FALSE Otherwise.
581 InternalIsHexaDecimalDigitCharacter (
586 return (BOOLEAN
) (InternalIsDecimalDigitCharacter (Char
) ||
587 (Char
>= L
'A' && Char
<= L
'F') ||
588 (Char
>= L
'a' && Char
<= L
'f'));
592 Convert a Null-terminated Unicode decimal string to a value of
595 This function returns a value of type UINTN by interpreting the contents
596 of the Unicode string specified by String as a decimal number. The format
597 of the input Unicode string String is:
599 [spaces] [decimal digits].
601 The valid decimal digit character is in the range [0-9]. The
602 function will ignore the pad space, which includes spaces or
603 tab characters, before [decimal digits]. The running zero in the
604 beginning of [decimal digits] will be ignored. Then, the function
605 stops at the first character that is a not a valid decimal character
606 or a Null-terminator, whichever one comes first.
608 If String is NULL, then ASSERT().
609 If String is not aligned in a 16-bit boundary, then ASSERT().
610 If String has only pad spaces, then 0 is returned.
611 If String has no pad spaces or valid decimal digits,
613 If the number represented by String overflows according
614 to the range defined by UINTN, then ASSERT().
616 If PcdMaximumUnicodeStringLength is not zero, and String contains
617 more than PcdMaximumUnicodeStringLength Unicode characters not including
618 the Null-terminator, then ASSERT().
620 @param String Pointer to a Null-terminated Unicode string.
628 IN CONST CHAR16
*String
634 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
635 // Length tests are performed inside StrLen().
637 ASSERT (StrSize (String
) != 0);
640 // Ignore the pad spaces (space or tab)
642 while ((L
' ' ==*String
) || (L
'\t' == *String
)) {
647 // Ignore leading Zeros after the spaces
649 while (L
'0' == *String
) {
655 while (InternalIsDecimalDigitCharacter (*String
)) {
657 // If the number represented by String overflows according
658 // to the range defined by UINTN, then ASSERT().
660 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_10
) ||
661 ((QUIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
662 (*String
- L
'0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10
)
665 Result
= Result
* 10 + (*String
- L
'0');
674 Convert a Null-terminated Unicode decimal string to a value of
677 This function returns a value of type UINT64 by interpreting the contents
678 of the Unicode string specified by String as a decimal number. The format
679 of the input Unicode string String is:
681 [spaces] [decimal digits].
683 The valid decimal digit character is in the range [0-9]. The
684 function will ignore the pad space, which includes spaces or
685 tab characters, before [decimal digits]. The running zero in the
686 beginning of [decimal digits] will be ignored. Then, the function
687 stops at the first character that is a not a valid decimal character
688 or a Null-terminator, whichever one comes first.
690 If String is NULL, then ASSERT().
691 If String is not aligned in a 16-bit boundary, then ASSERT().
692 If String has only pad spaces, then 0 is returned.
693 If String has no pad spaces or valid decimal digits,
695 If the number represented by String overflows according
696 to the range defined by UINT64, then ASSERT().
698 If PcdMaximumUnicodeStringLength is not zero, and String contains
699 more than PcdMaximumUnicodeStringLength Unicode characters not including
700 the Null-terminator, then ASSERT().
702 @param String Pointer to a Null-terminated Unicode string.
710 IN CONST CHAR16
*String
716 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
717 // Length tests are performed inside StrLen().
719 ASSERT (StrSize (String
) != 0);
722 // Ignore the pad spaces (space or tab)
724 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
729 // Ignore leading Zeros after the spaces
731 while (L
'0' == *String
) {
737 while (InternalIsDecimalDigitCharacter (*String
)) {
739 // If the number represented by String overflows according
740 // to the range defined by UINTN, then ASSERT().
742 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_10
) ||
743 ((QUIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
744 (*String
- L
'0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10
)
747 Result
= MultU64x32 (Result
, 10) + (*String
- L
'0');
755 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
757 This function returns a value of type UINTN by interpreting the contents
758 of the Unicode string specified by String as a hexadecimal number.
759 The format of the input Unicode string String is:
761 [spaces][zeros][x][hexadecimal digits].
763 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
764 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
765 If "x" appears in the input string, it must be prefixed with at least one 0.
766 The function will ignore the pad space, which includes spaces or tab characters,
767 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
768 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
769 first valid hexadecimal digit. Then, the function stops at the first character that is
770 a not a valid hexadecimal character or NULL, whichever one comes first.
772 If String is NULL, then ASSERT().
773 If String is not aligned in a 16-bit boundary, then ASSERT().
774 If String has only pad spaces, then zero is returned.
775 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
776 then zero is returned.
777 If the number represented by String overflows according to the range defined by
778 UINTN, then ASSERT().
780 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
781 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
784 @param String Pointer to a Null-terminated Unicode string.
792 IN CONST CHAR16
*String
798 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
799 // Length tests are performed inside StrLen().
801 ASSERT (StrSize (String
) != 0);
804 // Ignore the pad spaces (space or tab)
806 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
811 // Ignore leading Zeros after the spaces
813 while (L
'0' == *String
) {
817 if (InternalCharToUpper (*String
) == L
'X') {
818 ASSERT (L
'0' == *(String
- 1));
819 if (*(String
- 1) != L
'0') {
830 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
832 // If the Hex Number represented by String overflows according
833 // to the range defined by UINTN, then ASSERT().
835 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_16
) ||
836 ((QUIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
837 (InternalHexCharToUintn (*String
) <= REMINDER_MAX_UINTN_DIVIDED_BY_16
))
840 Result
= (Result
<< 4) + InternalHexCharToUintn (*String
);
849 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
851 This function returns a value of type UINT64 by interpreting the contents
852 of the Unicode string specified by String as a hexadecimal number.
853 The format of the input Unicode string String is
855 [spaces][zeros][x][hexadecimal digits].
857 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
858 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
859 If "x" appears in the input string, it must be prefixed with at least one 0.
860 The function will ignore the pad space, which includes spaces or tab characters,
861 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
862 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
863 first valid hexadecimal digit. Then, the function stops at the first character that is
864 a not a valid hexadecimal character or NULL, whichever one comes first.
866 If String is NULL, then ASSERT().
867 If String is not aligned in a 16-bit boundary, then ASSERT().
868 If String has only pad spaces, then zero is returned.
869 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
870 then zero is returned.
871 If the number represented by String overflows according to the range defined by
872 UINT64, then ASSERT().
874 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
875 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
878 @param String Pointer to a Null-terminated Unicode string.
886 IN CONST CHAR16
*String
892 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
893 // Length tests are performed inside StrLen().
895 ASSERT (StrSize (String
) != 0);
898 // Ignore the pad spaces (space or tab)
900 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
905 // Ignore leading Zeros after the spaces
907 while (L
'0' == *String
) {
911 if (InternalCharToUpper (*String
) == L
'X') {
912 ASSERT (L
'0' == *(String
- 1));
913 if (*(String
- 1) != L
'0') {
924 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
926 // If the Hex Number represented by String overflows according
927 // to the range defined by UINTN, then ASSERT().
929 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_16
)||
930 ((QUIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
931 (InternalHexCharToUintn (*String
) <= REMINDER_MAX_UINT64_DIVIDED_BY_16
))
934 Result
= LShiftU64 (Result
, 4);
935 Result
= Result
+ InternalHexCharToUintn (*String
);
943 Check if a ASCII character is a decimal character.
945 This internal function checks if a Unicode character is a
946 decimal character. The valid decimal character is from
949 @param Char The character to check against.
951 @retval TRUE If the Char is a decmial character.
952 @retval FALSE Otherwise.
957 InternalAsciiIsDecimalDigitCharacter (
961 return (BOOLEAN
) (Char
>= '0' && Char
<= '9');
965 Check if a ASCII character is a hexadecimal character.
967 This internal function checks if a ASCII character is a
968 decimal character. The valid hexadecimal character is
969 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
972 @param Char The character to check against.
974 @retval TRUE If the Char is a hexadecmial character.
975 @retval FALSE Otherwise.
980 InternalAsciiIsHexaDecimalDigitCharacter (
985 return (BOOLEAN
) (InternalAsciiIsDecimalDigitCharacter (Char
) ||
986 (Char
>= 'A' && Char
<= 'F') ||
987 (Char
>= 'a' && Char
<= 'f'));
991 Convert a Null-terminated Unicode string to a Null-terminated
992 ASCII string and returns the ASCII string.
994 This function converts the content of the Unicode string Source
995 to the ASCII string Destination by copying the lower 8 bits of
996 each Unicode character. It returns Destination. The function terminates
997 the ASCII string Destination by appending a Null-terminator character
998 at the end. The caller is responsible to make sure Destination points
999 to a buffer with size equal or greater than (StrLen (Source) + 1) in bytes.
1001 If Destination is NULL, then ASSERT().
1002 If Source is NULL, then ASSERT().
1003 If Source is not aligned on a 16-bit boundary, then ASSERT().
1004 If Source and Destination overlap, then ASSERT().
1006 If any Unicode characters in Source contain non-zero value in
1007 the upper 8 bits, then ASSERT().
1009 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1010 more than PcdMaximumUnicodeStringLength Unicode characters not including
1011 the Null-terminator, then ASSERT().
1013 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1014 than PcdMaximumAsciiStringLength Unicode characters not including the
1015 Null-terminator, then ASSERT().
1017 @param Source Pointer to a Null-terminated Unicode string.
1018 @param Destination Pointer to a Null-terminated ASCII string.
1025 UnicodeStrToAsciiStr (
1026 IN CONST CHAR16
*Source
,
1027 OUT CHAR8
*Destination
1032 ASSERT (Destination
!= NULL
);
1035 // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
1036 // Length tests are performed inside StrLen().
1038 ASSERT (StrSize (Source
) != 0);
1041 // Source and Destination should not overlap
1043 ASSERT ((UINTN
) ((CHAR16
*) Destination
- Source
) > StrLen (Source
));
1044 ASSERT ((UINTN
) ((CHAR8
*) Source
- Destination
) > StrLen (Source
));
1047 ReturnValue
= Destination
;
1048 while (*Source
!= '\0') {
1050 // If any Unicode characters in Source contain
1051 // non-zero value in the upper 8 bits, then ASSERT().
1053 ASSERT (*Source
< 0x100);
1054 *(Destination
++) = (CHAR8
) *(Source
++);
1057 *Destination
= '\0';
1060 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
1061 // Length tests are performed inside AsciiStrLen().
1063 ASSERT (AsciiStrSize (ReturnValue
) != 0);
1070 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1071 string and returns the new ASCII string.
1073 This function copies the contents of the ASCII string Source to the ASCII
1074 string Destination, and returns Destination. If Source and Destination
1075 overlap, then the results are undefined.
1077 If Destination is NULL, then ASSERT().
1078 If Source is NULL, then ASSERT().
1079 If Source and Destination overlap, then ASSERT().
1080 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1081 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1084 @param Destination Pointer to a Null-terminated ASCII string.
1085 @param Source Pointer to a Null-terminated ASCII string.
1093 OUT CHAR8
*Destination
,
1094 IN CONST CHAR8
*Source
1100 // Destination cannot be NULL
1102 ASSERT (Destination
!= NULL
);
1105 // Destination and source cannot overlap
1107 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1108 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
1110 ReturnValue
= Destination
;
1111 while (*Source
!= 0) {
1112 *(Destination
++) = *(Source
++);
1119 Copies one Null-terminated ASCII string with a maximum length to another
1120 Null-terminated ASCII string with a maximum length and returns the new ASCII
1123 This function copies the contents of the ASCII string Source to the ASCII
1124 string Destination, and returns Destination. At most, Length ASCII characters
1125 are copied from Source to Destination. If Length is 0, then Destination is
1126 returned unmodified. If Length is greater that the number of ASCII characters
1127 in Source, then Destination is padded with Null ASCII characters. If Source
1128 and Destination overlap, then the results are undefined.
1130 If Destination is NULL, then ASSERT().
1131 If Source is NULL, then ASSERT().
1132 If Source and Destination overlap, then ASSERT().
1133 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1134 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1137 @param Destination Pointer to a Null-terminated ASCII string.
1138 @param Source Pointer to a Null-terminated ASCII string.
1139 @param Length Maximum number of ASCII characters to copy.
1147 OUT CHAR8
*Destination
,
1148 IN CONST CHAR8
*Source
,
1159 // Destination cannot be NULL
1161 ASSERT (Destination
!= NULL
);
1164 // Destination and source cannot overlap
1166 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1167 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
1169 ReturnValue
= Destination
;
1171 while (*Source
!= 0 && Length
> 0) {
1172 *(Destination
++) = *(Source
++);
1176 ZeroMem (Destination
, Length
* sizeof (*Destination
));
1181 Returns the length of a Null-terminated ASCII string.
1183 This function returns the number of ASCII characters in the Null-terminated
1184 ASCII string specified by String.
1186 If String is NULL, then ASSERT().
1187 If PcdMaximumAsciiStringLength is not zero and String contains more than
1188 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1191 @param String Pointer to a Null-terminated ASCII string.
1193 @return The length of String.
1199 IN CONST CHAR8
*String
1204 ASSERT (String
!= NULL
);
1206 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
1208 // If PcdMaximumUnicodeStringLength is not zero,
1209 // length should not more than PcdMaximumUnicodeStringLength
1211 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1212 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
1219 Returns the size of a Null-terminated ASCII string in bytes, including the
1222 This function returns the size, in bytes, of the Null-terminated ASCII string
1223 specified by String.
1225 If String is NULL, then ASSERT().
1226 If PcdMaximumAsciiStringLength is not zero and String contains more than
1227 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1230 @param String Pointer to a Null-terminated ASCII string.
1232 @return The size of String.
1238 IN CONST CHAR8
*String
1241 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
1245 Compares two Null-terminated ASCII strings, and returns the difference
1246 between the first mismatched ASCII characters.
1248 This function compares the Null-terminated ASCII string FirstString to the
1249 Null-terminated ASCII string SecondString. If FirstString is identical to
1250 SecondString, then 0 is returned. Otherwise, the value returned is the first
1251 mismatched ASCII character in SecondString subtracted from the first
1252 mismatched ASCII character in FirstString.
1254 If FirstString is NULL, then ASSERT().
1255 If SecondString is NULL, then ASSERT().
1256 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1257 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1259 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1260 than PcdMaximumAsciiStringLength ASCII characters not including the
1261 Null-terminator, then ASSERT().
1263 @param FirstString Pointer to a Null-terminated ASCII string.
1264 @param SecondString Pointer to a Null-terminated ASCII string.
1266 @retval 0 FirstString is identical to SecondString.
1267 @return others FirstString is not identical to SecondString.
1273 IN CONST CHAR8
*FirstString
,
1274 IN CONST CHAR8
*SecondString
1278 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1280 ASSERT (AsciiStrSize (FirstString
));
1281 ASSERT (AsciiStrSize (SecondString
));
1283 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
1288 return *FirstString
- *SecondString
;
1292 Converts a lowercase Ascii character to upper one
1294 If Chr is lowercase Ascii character, then converts it to upper one.
1296 If Value >= 0xA0, then ASSERT().
1297 If (Value & 0x0F) >= 0x0A, then ASSERT().
1299 @param Chr one Ascii character
1301 @return The uppercase value of Ascii character
1310 return (UINT8
) ((Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
);
1314 Convert a ASCII character to numerical value.
1316 This internal function only deal with Unicode character
1317 which maps to a valid hexadecimal ASII character, i.e.
1318 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1319 ASCII character, the value returned does not make sense.
1321 @param Char The character to convert.
1323 @retval UINTN The numerical value converted.
1328 InternalAsciiHexCharToUintn (
1332 if (InternalIsDecimalDigitCharacter (Char
)) {
1336 return (UINTN
) (10 + AsciiToUpper (Char
) - 'A');
1341 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1342 and returns the difference between the first mismatched ASCII characters.
1344 This function performs a case insensitive comparison of the Null-terminated
1345 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1346 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1347 value returned is the first mismatched lower case ASCII character in
1348 SecondString subtracted from the first mismatched lower case ASCII character
1351 If FirstString is NULL, then ASSERT().
1352 If SecondString is NULL, then ASSERT().
1353 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1354 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1356 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1357 than PcdMaximumAsciiStringLength ASCII characters not including the
1358 Null-terminator, then ASSERT().
1360 @param FirstString Pointer to a Null-terminated ASCII string.
1361 @param SecondString Pointer to a Null-terminated ASCII string.
1363 @retval 0 FirstString is identical to SecondString using case insensitive
1365 @return others FirstString is not identical to SecondString using case
1366 insensitive comparisons.
1372 IN CONST CHAR8
*FirstString
,
1373 IN CONST CHAR8
*SecondString
1376 CHAR8 UpperFirstString
;
1377 CHAR8 UpperSecondString
;
1380 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1382 ASSERT (AsciiStrSize (FirstString
));
1383 ASSERT (AsciiStrSize (SecondString
));
1385 UpperFirstString
= AsciiToUpper (*FirstString
);
1386 UpperSecondString
= AsciiToUpper (*SecondString
);
1387 while ((*FirstString
!= '\0') && (UpperFirstString
== UpperSecondString
)) {
1390 UpperFirstString
= AsciiToUpper (*FirstString
);
1391 UpperSecondString
= AsciiToUpper (*SecondString
);
1394 return UpperFirstString
- UpperSecondString
;
1398 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1399 the difference between the first mismatched ASCII characters.
1401 This function compares the Null-terminated ASCII string FirstString to the
1402 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1403 will be compared. If Length is 0, then 0 is returned. If FirstString is
1404 identical to SecondString, then 0 is returned. Otherwise, the value returned
1405 is the first mismatched ASCII character in SecondString subtracted from the
1406 first mismatched ASCII character in FirstString.
1408 If FirstString is NULL, then ASSERT().
1409 If SecondString is NULL, then ASSERT().
1410 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1411 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1413 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
1414 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1417 @param FirstString Pointer to a Null-terminated ASCII string.
1418 @param SecondString Pointer to a Null-terminated ASCII string.
1419 @param Length Maximum number of ASCII characters to compare.
1421 @retval 0 FirstString is identical to SecondString.
1422 @return others FirstString is not identical to SecondString.
1428 IN CONST CHAR8
*FirstString
,
1429 IN CONST CHAR8
*SecondString
,
1438 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1440 ASSERT (AsciiStrSize (FirstString
));
1441 ASSERT (AsciiStrSize (SecondString
));
1443 while ((*FirstString
!= '\0') &&
1444 (*FirstString
== *SecondString
) &&
1450 return *FirstString
- *SecondString
;
1454 Concatenates one Null-terminated ASCII string to another Null-terminated
1455 ASCII string, and returns the concatenated ASCII string.
1457 This function concatenates two Null-terminated ASCII strings. The contents of
1458 Null-terminated ASCII string Source are concatenated to the end of Null-
1459 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1462 If Destination is NULL, then ASSERT().
1463 If Source is NULL, then ASSERT().
1464 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1465 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1467 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1468 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1470 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1471 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1472 ASCII characters, then ASSERT().
1474 @param Destination Pointer to a Null-terminated ASCII string.
1475 @param Source Pointer to a Null-terminated ASCII string.
1483 IN OUT CHAR8
*Destination
,
1484 IN CONST CHAR8
*Source
1487 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
1490 // Size of the resulting string should never be zero.
1491 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1493 ASSERT (AsciiStrSize (Destination
) != 0);
1498 Concatenates one Null-terminated ASCII string with a maximum length to the
1499 end of another Null-terminated ASCII string, and returns the concatenated
1502 This function concatenates two Null-terminated ASCII strings. The contents
1503 of Null-terminated ASCII string Source are concatenated to the end of Null-
1504 terminated ASCII string Destination, and Destination is returned. At most,
1505 Length ASCII characters are concatenated from Source to the end of
1506 Destination, and Destination is always Null-terminated. If Length is 0, then
1507 Destination is returned unmodified. If Source and Destination overlap, then
1508 the results are undefined.
1510 If Destination is NULL, then ASSERT().
1511 If Source is NULL, then ASSERT().
1512 If Source and Destination overlap, then ASSERT().
1513 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1514 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1516 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1517 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1519 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1520 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1521 ASCII characters not including the Null-terminator, then ASSERT().
1523 @param Destination Pointer to a Null-terminated ASCII string.
1524 @param Source Pointer to a Null-terminated ASCII string.
1525 @param Length Maximum number of ASCII characters to concatenate from
1534 IN OUT CHAR8
*Destination
,
1535 IN CONST CHAR8
*Source
,
1539 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
1542 // Size of the resulting string should never be zero.
1543 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1545 ASSERT (AsciiStrSize (Destination
) != 0);
1550 Returns the first occurance of a Null-terminated ASCII sub-string
1551 in a Null-terminated ASCII string.
1553 This function scans the contents of the ASCII string specified by String
1554 and returns the first occurrence of SearchString. If SearchString is not
1555 found in String, then NULL is returned. If the length of SearchString is zero,
1556 then String is returned.
1558 If String is NULL, then ASSERT().
1559 If SearchString is NULL, then ASSERT().
1561 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1562 String contains more than PcdMaximumAsciiStringLength Unicode characters
1563 not including the Null-terminator, then ASSERT().
1565 @param String Pointer to a Null-terminated ASCII string.
1566 @param SearchString Pointer to a Null-terminated ASCII string to search for.
1568 @retval NULL If the SearchString does not appear in String.
1569 @return others If there is a match.
1575 IN CONST CHAR8
*String
,
1576 IN CONST CHAR8
*SearchString
1579 CONST CHAR8
*FirstMatch
;
1580 CONST CHAR8
*SearchStringTmp
;
1583 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1585 ASSERT (AsciiStrSize (String
) != 0);
1586 ASSERT (AsciiStrSize (SearchString
) != 0);
1588 while (*String
!= '\0') {
1589 SearchStringTmp
= SearchString
;
1590 FirstMatch
= String
;
1592 while ((*String
== *SearchStringTmp
)
1593 && (*SearchStringTmp
!= '\0')
1594 && (*String
!= '\0')) {
1599 if (*SearchStringTmp
== '\0') {
1600 return (CHAR8
*) FirstMatch
;
1603 if (SearchStringTmp
== SearchString
) {
1605 // If no character from SearchString match,
1606 // move the pointer to the String under search
1607 // by one character.
1618 Convert a Null-terminated ASCII decimal string to a value of type
1621 This function returns a value of type UINTN by interpreting the contents
1622 of the ASCII string String as a decimal number. The format of the input
1623 ASCII string String is:
1625 [spaces] [decimal digits].
1627 The valid decimal digit character is in the range [0-9]. The function will
1628 ignore the pad space, which includes spaces or tab characters, before the digits.
1629 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1630 function stops at the first character that is a not a valid decimal character or
1631 Null-terminator, whichever on comes first.
1633 If String has only pad spaces, then 0 is returned.
1634 If String has no pad spaces or valid decimal digits, then 0 is returned.
1635 If the number represented by String overflows according to the range defined by
1636 UINTN, then ASSERT().
1637 If String is NULL, then ASSERT().
1638 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1639 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1642 @param String Pointer to a Null-terminated ASCII string.
1649 AsciiStrDecimalToUintn (
1650 IN CONST CHAR8
*String
1656 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1658 ASSERT (AsciiStrSize (String
) != 0);
1661 // Ignore the pad spaces (space or tab)
1663 while ((' ' == *String
) || ('\t' == *String
)) {
1668 // Ignore leading Zeros after the spaces
1670 while ('0' == *String
) {
1676 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1678 // If the number represented by String overflows according
1679 // to the range defined by UINTN, then ASSERT().
1681 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_10
) ||
1682 ((QUIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
1683 (*String
- '0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10
)
1686 Result
= Result
* 10 + (*String
- '0');
1695 Convert a Null-terminated ASCII decimal string to a value of type
1698 This function returns a value of type UINT64 by interpreting the contents
1699 of the ASCII string String as a decimal number. The format of the input
1700 ASCII string String is:
1702 [spaces] [decimal digits].
1704 The valid decimal digit character is in the range [0-9]. The function will
1705 ignore the pad space, which includes spaces or tab characters, before the digits.
1706 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1707 function stops at the first character that is a not a valid decimal character or
1708 Null-terminator, whichever on comes first.
1710 If String has only pad spaces, then 0 is returned.
1711 If String has no pad spaces or valid decimal digits, then 0 is returned.
1712 If the number represented by String overflows according to the range defined by
1713 UINT64, then ASSERT().
1714 If String is NULL, then ASSERT().
1715 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1716 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1719 @param String Pointer to a Null-terminated ASCII string.
1726 AsciiStrDecimalToUint64 (
1727 IN CONST CHAR8
*String
1733 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1735 ASSERT (AsciiStrSize (String
) != 0);
1738 // Ignore the pad spaces (space or tab)
1740 while ((' ' == *String
) || ('\t' == *String
)) {
1745 // Ignore leading Zeros after the spaces
1747 while ('0' == *String
) {
1753 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1755 // If the number represented by String overflows according
1756 // to the range defined by UINTN, then ASSERT().
1758 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_10
) ||
1759 ((QUIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
1760 (*String
- '0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10
)
1763 Result
= MultU64x32 (Result
, 10) + (*String
- '0');
1771 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1773 This function returns a value of type UINTN by interpreting the contents of
1774 the ASCII string String as a hexadecimal number. The format of the input ASCII
1777 [spaces][zeros][x][hexadecimal digits].
1779 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1780 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1781 appears in the input string, it must be prefixed with at least one 0. The function
1782 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1783 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1784 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1785 digit. Then, the function stops at the first character that is a not a valid
1786 hexadecimal character or Null-terminator, whichever on comes first.
1788 If String has only pad spaces, then 0 is returned.
1789 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1792 If the number represented by String overflows according to the range defined by UINTN,
1794 If String is NULL, then ASSERT().
1795 If PcdMaximumAsciiStringLength is not zero,
1796 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1797 the Null-terminator, then ASSERT().
1799 @param String Pointer to a Null-terminated ASCII string.
1806 AsciiStrHexToUintn (
1807 IN CONST CHAR8
*String
1813 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1815 ASSERT (AsciiStrSize (String
) != 0);
1818 // Ignore the pad spaces (space or tab)
1820 while ((' ' == *String
) || ('\t' == *String
)) {
1825 // Ignore leading Zeros after the spaces
1827 while ('0' == *String
) {
1831 if (AsciiToUpper (*String
) == 'X') {
1832 ASSERT ('0' == *(String
- 1));
1833 if (*(String
- 1) != '0') {
1844 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1846 // If the Hex Number represented by String overflows according
1847 // to the range defined by UINTN, then ASSERT().
1849 ASSERT ((Result
< QUIENT_MAX_UINTN_DIVIDED_BY_16
) ||
1850 ((QUIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
1851 (InternalAsciiHexCharToUintn (*String
) <= REMINDER_MAX_UINTN_DIVIDED_BY_16
))
1854 Result
= (Result
<< 4) + InternalAsciiHexCharToUintn (*String
);
1863 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1865 This function returns a value of type UINT64 by interpreting the contents of
1866 the ASCII string String as a hexadecimal number. The format of the input ASCII
1869 [spaces][zeros][x][hexadecimal digits].
1871 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1872 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1873 appears in the input string, it must be prefixed with at least one 0. The function
1874 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1875 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1876 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1877 digit. Then, the function stops at the first character that is a not a valid
1878 hexadecimal character or Null-terminator, whichever on comes first.
1880 If String has only pad spaces, then 0 is returned.
1881 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1884 If the number represented by String overflows according to the range defined by UINT64,
1886 If String is NULL, then ASSERT().
1887 If PcdMaximumAsciiStringLength is not zero,
1888 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1889 the Null-terminator, then ASSERT().
1891 @param String Pointer to a Null-terminated ASCII string.
1898 AsciiStrHexToUint64 (
1899 IN CONST CHAR8
*String
1905 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1907 ASSERT (AsciiStrSize (String
) != 0);
1910 // Ignore the pad spaces (space or tab) and leading Zeros
1913 // Ignore the pad spaces (space or tab)
1915 while ((' ' == *String
) || ('\t' == *String
)) {
1920 // Ignore leading Zeros after the spaces
1922 while ('0' == *String
) {
1926 if (AsciiToUpper (*String
) == 'X') {
1927 ASSERT ('0' == *(String
- 1));
1928 if (*(String
- 1) != '0') {
1939 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1941 // If the Hex Number represented by String overflows according
1942 // to the range defined by UINTN, then ASSERT().
1944 ASSERT ((Result
< QUIENT_MAX_UINT64_DIVIDED_BY_16
) ||
1945 ((QUIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
1946 (InternalAsciiHexCharToUintn (*String
) <= REMINDER_MAX_UINT64_DIVIDED_BY_16
))
1949 Result
= LShiftU64 (Result
, 4);
1950 Result
= Result
+ InternalAsciiHexCharToUintn (*String
);
1959 Convert one Null-terminated ASCII string to a Null-terminated
1960 Unicode string and returns the Unicode string.
1962 This function converts the contents of the ASCII string Source to the Unicode
1963 string Destination, and returns Destination. The function terminates the
1964 Unicode string Destination by appending a Null-terminator character at the end.
1965 The caller is responsible to make sure Destination points to a buffer with size
1966 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1968 If Destination is NULL, then ASSERT().
1969 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1970 If Source is NULL, then ASSERT().
1971 If Source and Destination overlap, then ASSERT().
1972 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1973 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1975 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1976 PcdMaximumUnicodeStringLength ASCII characters not including the
1977 Null-terminator, then ASSERT().
1979 @param Source Pointer to a Null-terminated ASCII string.
1980 @param Destination Pointer to a Null-terminated Unicode string.
1987 AsciiStrToUnicodeStr (
1988 IN CONST CHAR8
*Source
,
1989 OUT CHAR16
*Destination
1992 CHAR16
*ReturnValue
;
1994 ASSERT (Destination
!= NULL
);
1997 // ASSERT Source is less long than PcdMaximumAsciiStringLength
1999 ASSERT (AsciiStrSize (Source
) != 0);
2002 // Source and Destination should not overlap
2004 ASSERT ((UINTN
) ((CHAR8
*) Destination
- Source
) > AsciiStrLen (Source
));
2005 ASSERT ((UINTN
) (Source
- (CHAR8
*) Destination
) > (AsciiStrLen (Source
) * sizeof (CHAR16
)));
2008 ReturnValue
= Destination
;
2009 while (*Source
!= '\0') {
2010 *(Destination
++) = (CHAR16
) *(Source
++);
2013 // End the Destination with a NULL.
2015 *Destination
= '\0';
2018 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
2020 ASSERT (StrSize (ReturnValue
) != 0);
2026 Converts an 8-bit value to an 8-bit BCD value.
2028 Converts the 8-bit value specified by Value to BCD. The BCD value is
2031 If Value >= 100, then ASSERT().
2033 @param Value The 8-bit value to convert to BCD. Range 0..99.
2035 @return The BCD value
2044 ASSERT (Value
< 100);
2045 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2049 Converts an 8-bit BCD value to an 8-bit value.
2051 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2054 If Value >= 0xA0, then ASSERT().
2055 If (Value & 0x0F) >= 0x0A, then ASSERT().
2057 @param Value The 8-bit BCD value to convert to an 8-bit value.
2059 @return The 8-bit value is returned.
2068 ASSERT (Value
< 0xa0);
2069 ASSERT ((Value
& 0xf) < 0xa);
2070 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));
2075 Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character.
2077 This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal
2078 character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A'
2081 The upper nibble in the input byte will be masked off.
2083 @param Nibble The nibble which is in the low 4 bits of the input byte.
2085 @retval CHAR16 The Unicode hexadecimal character.
2094 if (Nibble
<= 0x9) {
2095 return (CHAR16
)(Nibble
+ L
'0');
2098 return (CHAR16
)(Nibble
- 0xA + L
'A');
2102 Convert binary buffer to a Unicode String in a specified sequence.
2104 This function converts bytes in the memory block pointed by Buffer to a Unicode String Str.
2105 Each byte will be represented by two Unicode characters. For example, byte 0xA1 will
2106 be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character
2107 for the Most Significant Nibble will be put before the Unicode Character for the Least Significant
2108 Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1".
2109 For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the
2110 the last character in the output string. The one next to first byte will be put into the
2111 character before the last character. This rules applies to the rest of the bytes. The Unicode
2112 character by the last byte will be put into the first character in the output string. For example,
2113 the input buffer for a 64-bits unsigned integrer 0x12345678abcdef1234 will be converted to
2114 a Unicode string equal to L"12345678abcdef1234".
2116 @param String On input, String is pointed to the buffer allocated for the convertion.
2117 @param StringLen The Length of String buffer to hold the output String. The length must include the tailing '\0' character.
2118 The StringLen required to convert a N bytes Buffer will be a least equal to or greater
2120 @param Buffer The pointer to a input buffer.
2121 @param BufferSizeInBytes Lenth in bytes of the input buffer.
2124 @retval EFI_SUCCESS The convertion is successfull. All bytes in Buffer has been convert to the corresponding
2125 Unicode character and placed into the right place in String.
2126 @retval EFI_BUFFER_TOO_SMALL StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to
2127 complete the convertion.
2132 IN OUT CHAR16
*String
,
2133 IN OUT UINTN
*StringLen
,
2134 IN CONST UINT8
*Buffer
,
2135 IN UINTN BufferSizeInBytes
2143 // Make sure string is either passed or allocate enough.
2144 // It takes 2 Unicode characters (4 bytes) to represent 1 byte of the binary buffer.
2145 // Plus the Unicode termination character.
2147 StrLen
= BufferSizeInBytes
* 2;
2148 if (StrLen
> ((*StringLen
) - 1)) {
2149 *StringLen
= StrLen
+ 1;
2150 return RETURN_BUFFER_TOO_SMALL
;
2153 *StringLen
= StrLen
+ 1;
2157 String
[StrLen
] = L
'\0';
2159 for (Idx
= 0; Idx
< BufferSizeInBytes
; Idx
++) {
2162 String
[StrLen
- 1 - Idx
* 2] = NibbleToHexChar (Byte
);
2163 String
[StrLen
- 2 - Idx
* 2] = NibbleToHexChar ((UINT8
)(Byte
>> 4));
2166 return RETURN_SUCCESS
;
2171 Convert a Unicode string consisting of hexadecimal characters to a output byte buffer.
2173 This function converts a Unicode string consisting of characters in the range of Hexadecimal
2174 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
2175 at the first non-hexadecimal character or the NULL character. The convertion process can be
2176 simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be
2177 converted into one byte. The first Unicode character represents the Most Significant Nibble and the
2178 second Unicode character represents the Least Significant Nibble in the output byte.
2179 The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode
2180 characters represent the the byte preceding the last byte. This rule applies to the rest pairs of bytes.
2181 The last pair represent the first byte in the output buffer.
2183 For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes
2184 (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12".
2186 If String has N valid hexadecimal characters for conversion, the caller must make sure Buffer is at least
2187 N/2 (if N is even) or (N+1)/2 (if N if odd) bytes.
2189 @param Buffer The output buffer allocated by the caller.
2190 @param BufferSizeInBytes On input, the size in bytes of Buffer. On output, it is updated to
2191 contain the size of the Buffer which is actually used for the converstion.
2192 For Unicode string with 2*N hexadecimal characters (not including the
2193 tailing NULL character), N bytes of Buffer will be used for the output.
2194 @param String The input hexadecimal string.
2195 @param ConvertedStrLen The number of hexadecimal characters used to produce content in output
2198 @retval RETURN_BUFFER_TOO_SMALL The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes
2199 will be updated to the size required for the converstion.
2200 @retval RETURN_SUCCESS The convertion is successful or the first Unicode character from String
2201 is hexadecimal. If ConvertedStrLen is not NULL, it is updated
2202 to the number of hexadecimal character used for the converstion.
2208 IN OUT UINTN
*BufferSizeInBytes
,
2209 IN CONST CHAR16
*String
,
2210 OUT UINTN
*ConvertedStrLen OPTIONAL
2220 // Find out how many hex characters the string has.
2222 for (Idx
= 0, HexCnt
= 0; IsHexDigit (&Digit
, String
[Idx
]); Idx
++, HexCnt
++);
2225 *ConvertedStrLen
= 0;
2226 return RETURN_SUCCESS
;
2229 // Two Unicode characters make up 1 buffer byte. Round up.
2231 BufferLength
= (HexCnt
+ 1) / 2;
2234 // Test if buffer is passed enough.
2236 if (BufferLength
> (*BufferSizeInBytes
)) {
2237 *BufferSizeInBytes
= BufferLength
;
2238 return RETURN_BUFFER_TOO_SMALL
;
2241 *BufferSizeInBytes
= BufferLength
;
2243 for (Idx
= 0; Idx
< HexCnt
; Idx
++) {
2245 IsHexDigit (&Digit
, String
[HexCnt
- 1 - Idx
]);
2248 // For odd charaters, write the lower nibble for each buffer byte,
2249 // and for even characters, the upper nibble.
2251 if ((Idx
& 1) == 0) {
2254 Byte
= Buffer
[Idx
/ 2];
2256 Byte
= (UINT8
) (Byte
| Digit
<< 4);
2259 Buffer
[Idx
/ 2] = Byte
;
2262 if (ConvertedStrLen
!= NULL
) {
2263 *ConvertedStrLen
= HexCnt
;
2266 return RETURN_SUCCESS
;
2271 Test if a Unicode character is a hexadecimal digit. If true, the input
2272 Unicode character is converted to a byte.
2274 This function tests if a Unicode character is a hexadecimal digit. If true, the input
2275 Unicode character is converted to a byte. For example, Unicode character
2276 L'A' will be converted to 0x0A.
2278 If Digit is NULL, then ASSERT.
2280 @param Digit The output hexadecimal digit.
2282 @param Char The input Unicode character.
2284 @retval TRUE Char is in the range of Hexadecimal number. Digit is updated
2285 to the byte value of the number.
2286 @retval FALSE Char is not in the range of Hexadecimal number. Digit is keep
2296 ASSERT (Digit
!= NULL
);
2298 if ((Char
>= L
'0') && (Char
<= L
'9')) {
2299 *Digit
= (UINT8
) (Char
- L
'0');
2303 if ((Char
>= L
'A') && (Char
<= L
'F')) {
2304 *Digit
= (UINT8
) (Char
- L
'A' + 0x0A);
2308 if ((Char
>= L
'a') && (Char
<= L
'f')) {
2309 *Digit
= (UINT8
) (Char
- L
'a' + 0x0A);