2 Unicode and ASCII string primatives.
4 Copyright (c) 2006 - 2008, 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.
15 #include "BaseLibInternals.h"
17 #define QUOTIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
18 #define REMAINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
20 #define QUOTIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
21 #define REMAINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
23 #define QUOTIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
24 #define REMAINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
26 #define QUOTIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
27 #define REMAINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
30 Copies one Null-terminated Unicode string to another Null-terminated Unicode
31 string and returns the new Unicode string.
33 This function copies the contents of the Unicode string Source to the Unicode
34 string Destination, and returns Destination. If Source and Destination
35 overlap, then the results are undefined.
37 If Destination is NULL, then ASSERT().
38 If Destination is not aligned on a 16-bit boundary, then ASSERT().
39 If Source is NULL, then ASSERT().
40 If Source is not aligned on a 16-bit boundary, then ASSERT().
41 If Source and Destination overlap, then ASSERT().
42 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
43 PcdMaximumUnicodeStringLength Unicode characters not including the
44 Null-terminator, then ASSERT().
46 @param Destination Pointer to a Null-terminated Unicode string.
47 @param Source Pointer to a Null-terminated Unicode string.
49 @return Destination pointing to the copied string.
55 OUT CHAR16
*Destination
,
56 IN CONST CHAR16
*Source
62 // Destination cannot be NULL
64 ASSERT (Destination
!= NULL
);
65 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
68 // Destination and source cannot overlap
70 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
71 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
73 ReturnValue
= Destination
;
74 while (*Source
!= 0) {
75 *(Destination
++) = *(Source
++);
82 Copies one Null-terminated Unicode string with a maximum length to another
83 Null-terminated Unicode string with a maximum length and returns the new
86 This function copies the contents of the Unicode string Source to the Unicode
87 string Destination, and returns Destination. At most, Length Unicode
88 characters are copied from Source to Destination. If Length is 0, then
89 Destination is returned unmodified. If Length is greater that the number of
90 Unicode characters in Source, then Destination is padded with Null Unicode
91 characters. If Source and Destination overlap, then the results are
94 If Length > 0 and Destination is NULL, then ASSERT().
95 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
96 If Length > 0 and Source is NULL, then ASSERT().
97 If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
98 If Source and Destination overlap, then ASSERT().
99 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
100 PcdMaximumUnicodeStringLength Unicode characters not including the
101 Null-terminator, then ASSERT().
103 @param Destination Pointer to a Null-terminated Unicode string.
104 @param Source Pointer to a Null-terminated Unicode string.
105 @param Length Maximum number of Unicode characters to copy.
107 @return Destination pointing to the copied string.
113 OUT CHAR16
*Destination
,
114 IN CONST CHAR16
*Source
,
125 // Destination cannot be NULL if Length is not zero
127 ASSERT (Destination
!= NULL
);
128 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
131 // Destination and source cannot overlap
133 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
134 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
136 ReturnValue
= Destination
;
138 while ((*Source
!= L
'\0') && (Length
> 0)) {
139 *(Destination
++) = *(Source
++);
143 ZeroMem (Destination
, Length
* sizeof (*Destination
));
148 Returns the length of a Null-terminated Unicode string.
150 This function returns the number of Unicode characters in the Null-terminated
151 Unicode string specified by String.
153 If String is NULL, then ASSERT().
154 If String is not aligned on a 16-bit boundary, then ASSERT().
155 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
156 PcdMaximumUnicodeStringLength Unicode characters not including the
157 Null-terminator, then ASSERT().
159 @param String Pointer to a Null-terminated Unicode string.
161 @return The length of String.
167 IN CONST CHAR16
*String
172 ASSERT (String
!= NULL
);
173 ASSERT (((UINTN
) String
& BIT0
) == 0);
175 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
177 // If PcdMaximumUnicodeStringLength is not zero,
178 // length should not more than PcdMaximumUnicodeStringLength
180 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
181 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
188 Returns the size of a Null-terminated Unicode string in bytes, including the
191 This function returns the size, in bytes, of the Null-terminated Unicode
192 string specified by String.
194 If String is NULL, then ASSERT().
195 If String is not aligned on a 16-bit boundary, then ASSERT().
196 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
197 PcdMaximumUnicodeStringLength Unicode characters not including the
198 Null-terminator, then ASSERT().
200 @param String Pointer to a Null-terminated Unicode string.
202 @return The size in bytes of String.
208 IN CONST CHAR16
*String
211 return (StrLen (String
) + 1) * sizeof (*String
);
215 Compares two Null-terminated Unicode strings, and returns the difference
216 between the first mismatched Unicode characters.
218 This function compares the Null-terminated Unicode string FirstString to the
219 Null-terminated Unicode string SecondString. If FirstString is identical to
220 SecondString, then 0 is returned. Otherwise, the value returned is the first
221 mismatched Unicode character in SecondString subtracted from the first
222 mismatched Unicode character in FirstString.
224 If FirstString is NULL, then ASSERT().
225 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
226 If SecondString is NULL, then ASSERT().
227 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
228 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
229 than PcdMaximumUnicodeStringLength Unicode characters not including the
230 Null-terminator, then ASSERT().
231 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
232 than PcdMaximumUnicodeStringLength Unicode characters not including the
233 Null-terminator, then ASSERT().
235 @param FirstString Pointer to a Null-terminated Unicode string.
236 @param SecondString Pointer to a Null-terminated Unicode string.
238 @retval 0 FirstString is identical to SecondString.
239 @return The first mismatched Unicode character in SecondString subtracted
240 from the first mismatched Unicode character in FirstString.
246 IN CONST CHAR16
*FirstString
,
247 IN CONST CHAR16
*SecondString
251 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
253 ASSERT (StrSize (FirstString
) != 0);
254 ASSERT (StrSize (SecondString
) != 0);
256 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
260 return *FirstString
- *SecondString
;
264 Compares two Null-terminated Unicode strings with maximum lengths, and
265 returns the difference between the first mismatched Unicode characters.
267 This function compares the Null-terminated Unicode string FirstString to the
268 Null-terminated Unicode string SecondString. At most, Length Unicode
269 characters will be compared. If Length is 0, then 0 is returned. If
270 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
271 value returned is the first mismatched Unicode character in SecondString
272 subtracted from the first mismatched Unicode character in FirstString.
274 If Length > 0 and FirstString is NULL, then ASSERT().
275 If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
276 If Length > 0 and SecondString is NULL, then ASSERT().
277 If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
278 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
279 than PcdMaximumUnicodeStringLength Unicode characters not including the
280 Null-terminator, then ASSERT().
281 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
282 than PcdMaximumUnicodeStringLength Unicode characters not including the
283 Null-terminator, then ASSERT().
285 @param FirstString Pointer to a Null-terminated Unicode string.
286 @param SecondString Pointer to a Null-terminated Unicode string.
287 @param Length Maximum number of Unicode characters to compare.
289 @retval 0 FirstString is identical to SecondString.
290 @return The value returned is the first mismatched Unicode character in SecondString
291 subtracted from the first mismatched Unicode character in FirstString.
297 IN CONST CHAR16
*FirstString
,
298 IN CONST CHAR16
*SecondString
,
307 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
308 // Length tests are performed inside StrLen().
310 ASSERT (StrSize (FirstString
) != 0);
311 ASSERT (StrSize (SecondString
) != 0);
313 while ((*FirstString
!= L
'\0') &&
314 (*FirstString
== *SecondString
) &&
321 return *FirstString
- *SecondString
;
325 Concatenates one Null-terminated Unicode string to another Null-terminated
326 Unicode string, and returns the concatenated Unicode string.
328 This function concatenates two Null-terminated Unicode strings. The contents
329 of Null-terminated Unicode string Source are concatenated to the end of
330 Null-terminated Unicode string Destination. The Null-terminated concatenated
331 Unicode String is returned. If Source and Destination overlap, then the
332 results are undefined.
334 If Destination is NULL, then ASSERT().
335 If Source is NULL, then ASSERT().
336 If Source and Destination overlap, then ASSERT().
337 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
338 than PcdMaximumUnicodeStringLength Unicode characters not including the
339 Null-terminator, then ASSERT().
340 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
341 PcdMaximumUnicodeStringLength Unicode characters not including the
342 Null-terminator, then ASSERT().
343 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
344 and Source results in a Unicode string with more than
345 PcdMaximumUnicodeStringLength Unicode characters not including the
346 Null-terminator, then ASSERT().
348 @param Destination Pointer to a Null-terminated Unicode string.
349 @param Source Pointer to a Null-terminated Unicode string.
351 @return Destination pointing to the concatenated Unicode string.
357 IN OUT CHAR16
*Destination
,
358 IN CONST CHAR16
*Source
361 StrCpy (Destination
+ StrLen (Destination
), Source
);
364 // Size of the resulting string should never be zero.
365 // PcdMaximumUnicodeStringLength is tested inside StrLen().
367 ASSERT (StrSize (Destination
) != 0);
372 Concatenates one Null-terminated Unicode string with a maximum length to the
373 end of another Null-terminated Unicode string, and returns the concatenated
376 This function concatenates two Null-terminated Unicode strings. The contents
377 of Null-terminated Unicode string Source are concatenated to the end of
378 Null-terminated Unicode string Destination, and Destination is returned. At
379 most, Length Unicode characters are concatenated from Source to the end of
380 Destination, and Destination is always Null-terminated. If Length is 0, then
381 Destination is returned unmodified. If Source and Destination overlap, then
382 the results are undefined.
384 If Destination is NULL, then ASSERT().
385 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
386 If Length > 0 and Source is NULL, then ASSERT().
387 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
388 If Source and Destination overlap, then ASSERT().
389 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
390 than PcdMaximumUnicodeStringLength Unicode characters not including the
391 Null-terminator, then ASSERT().
392 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
393 PcdMaximumUnicodeStringLength Unicode characters not including the
394 Null-terminator, then ASSERT().
395 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
396 and Source results in a Unicode string with more than
397 PcdMaximumUnicodeStringLength Unicode characters not including the
398 Null-terminator, then ASSERT().
400 @param Destination Pointer to a Null-terminated Unicode string.
401 @param Source Pointer to a Null-terminated Unicode string.
402 @param Length Maximum number of Unicode characters to concatenate from
405 @return Destination pointing to the concatenated Unicode string.
411 IN OUT CHAR16
*Destination
,
412 IN CONST CHAR16
*Source
,
416 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
419 // Size of the resulting string should never be zero.
420 // PcdMaximumUnicodeStringLength is tested inside StrLen().
422 ASSERT (StrSize (Destination
) != 0);
427 Returns the first occurance of a Null-terminated Unicode sub-string
428 in a Null-terminated Unicode string.
430 This function scans the contents of the Null-terminated Unicode string
431 specified by String and returns the first occurrence of SearchString.
432 If SearchString is not found in String, then NULL is returned. If
433 the length of SearchString is zero, then String is
436 If String is NULL, then ASSERT().
437 If String is not aligned on a 16-bit boundary, then ASSERT().
438 If SearchString is NULL, then ASSERT().
439 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
441 If PcdMaximumUnicodeStringLength is not zero, and SearchString
442 or String contains more than PcdMaximumUnicodeStringLength Unicode
443 characters not including the Null-terminator, then ASSERT().
445 @param String Pointer to a Null-terminated Unicode string.
446 @param SearchString Pointer to a Null-terminated Unicode string to search for.
448 @retval NULL If the SearchString does not appear in String.
449 @return Pointer to the matching sub-string.
455 IN CONST CHAR16
*String
,
456 IN CONST CHAR16
*SearchString
459 CONST CHAR16
*FirstMatch
;
460 CONST CHAR16
*SearchStringTmp
;
463 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
464 // Length tests are performed inside StrLen().
466 ASSERT (StrSize (String
) != 0);
467 ASSERT (StrSize (SearchString
) != 0);
469 while (*String
!= '\0') {
470 SearchStringTmp
= SearchString
;
473 while ((*String
== *SearchStringTmp
)
474 && (*SearchStringTmp
!= '\0')
475 && (*String
!= '\0')) {
480 if ('\0' == *SearchStringTmp
) {
481 return (CHAR16
*) FirstMatch
;
484 if (SearchStringTmp
== SearchString
) {
486 // If no character from SearchString match,
487 // move the pointer to the String under search
498 Check if a Unicode character is a decimal character.
500 This internal function checks if a Unicode character is a
501 decimal character. The valid decimal character is from
504 @param Char The character to check against.
506 @retval TRUE If the Char is a decmial character.
507 @retval FALSE If the Char is not a decmial character.
512 InternalIsDecimalDigitCharacter (
516 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
520 Convert a Unicode character to upper case only if
521 it maps to a valid small-case ASCII character.
523 This internal function only deal with Unicode character
524 which maps to a valid small-case ASCII character, i.e.
525 L'a' to L'z'. For other Unicode character, the input character
526 is returned directly.
528 @param Char The character to convert.
530 @retval LowerCharacter If the Char is with range L'a' to L'z'.
531 @retval Unchanged Otherwise.
536 InternalCharToUpper (
540 if (Char
>= L
'a' && Char
<= L
'z') {
541 return (CHAR16
) (Char
- (L
'a' - L
'A'));
548 Convert a Unicode character to numerical value.
550 This internal function only deal with Unicode character
551 which maps to a valid hexadecimal ASII character, i.e.
552 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
553 Unicode character, the value returned does not make sense.
555 @param Char The character to convert.
557 @return The numerical value converted.
562 InternalHexCharToUintn (
566 if (InternalIsDecimalDigitCharacter (Char
)) {
570 return (UINTN
) (10 + InternalCharToUpper (Char
) - L
'A');
574 Check if a Unicode character is a hexadecimal character.
576 This internal function checks if a Unicode character is a
577 decimal character. The valid hexadecimal character is
578 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
581 @param Char The character to check against.
583 @retval TRUE If the Char is a hexadecmial character.
584 @retval FALSE If the Char is not a hexadecmial character.
589 InternalIsHexaDecimalDigitCharacter (
594 return (BOOLEAN
) (InternalIsDecimalDigitCharacter (Char
) ||
595 (Char
>= L
'A' && Char
<= L
'F') ||
596 (Char
>= L
'a' && Char
<= L
'f'));
600 Convert a Null-terminated Unicode decimal string to a value of
603 This function returns a value of type UINTN by interpreting the contents
604 of the Unicode string specified by String as a decimal number. The format
605 of the input Unicode string String is:
607 [spaces] [decimal digits].
609 The valid decimal digit character is in the range [0-9]. The
610 function will ignore the pad space, which includes spaces or
611 tab characters, before [decimal digits]. The running zero in the
612 beginning of [decimal digits] will be ignored. Then, the function
613 stops at the first character that is a not a valid decimal character
614 or a Null-terminator, whichever one comes first.
616 If String is NULL, then ASSERT().
617 If String is not aligned in a 16-bit boundary, then ASSERT().
618 If String has only pad spaces, then 0 is returned.
619 If String has no pad spaces or valid decimal digits,
621 If the number represented by String overflows according
622 to the range defined by UINTN, then ASSERT().
624 If PcdMaximumUnicodeStringLength is not zero, and String contains
625 more than PcdMaximumUnicodeStringLength Unicode characters not including
626 the Null-terminator, then ASSERT().
628 @param String Pointer to a Null-terminated Unicode string.
630 @return The value of type UINTN converted.
636 IN CONST CHAR16
*String
642 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
643 // Length tests are performed inside StrLen().
645 ASSERT (StrSize (String
) != 0);
648 // Ignore the pad spaces (space or tab)
650 while ((L
' ' ==*String
) || (L
'\t' == *String
)) {
655 // Ignore leading Zeros after the spaces
657 while (L
'0' == *String
) {
663 while (InternalIsDecimalDigitCharacter (*String
)) {
665 // If the number represented by String overflows according
666 // to the range defined by UINTN, then ASSERT().
668 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_10
) ||
669 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
670 (*String
- L
'0') <= REMAINDER_MAX_UINTN_DIVIDED_BY_10
)
673 Result
= Result
* 10 + (*String
- L
'0');
682 Convert a Null-terminated Unicode decimal string to a value of
685 This function returns a value of type UINT64 by interpreting the contents
686 of the Unicode string specified by String as a decimal number. The format
687 of the input Unicode string String is:
689 [spaces] [decimal digits].
691 The valid decimal digit character is in the range [0-9]. The
692 function will ignore the pad space, which includes spaces or
693 tab characters, before [decimal digits]. The running zero in the
694 beginning of [decimal digits] will be ignored. Then, the function
695 stops at the first character that is a not a valid decimal character
696 or a Null-terminator, whichever one comes first.
698 If String is NULL, then ASSERT().
699 If String is not aligned in a 16-bit boundary, then ASSERT().
700 If String has only pad spaces, then 0 is returned.
701 If String has no pad spaces or valid decimal digits,
703 If the number represented by String overflows according
704 to the range defined by UINT64, then ASSERT().
706 If PcdMaximumUnicodeStringLength is not zero, and String contains
707 more than PcdMaximumUnicodeStringLength Unicode characters not including
708 the Null-terminator, then ASSERT().
710 @param String Pointer to a Null-terminated Unicode string.
712 @return The value of type UINT64 converted.
718 IN CONST CHAR16
*String
724 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
725 // Length tests are performed inside StrLen().
727 ASSERT (StrSize (String
) != 0);
730 // Ignore the pad spaces (space or tab)
732 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
737 // Ignore leading Zeros after the spaces
739 while (L
'0' == *String
) {
745 while (InternalIsDecimalDigitCharacter (*String
)) {
747 // If the number represented by String overflows according
748 // to the range defined by UINTN, then ASSERT().
750 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_10
) ||
751 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
752 (*String
- L
'0') <= REMAINDER_MAX_UINT64_DIVIDED_BY_10
)
755 Result
= MultU64x32 (Result
, 10) + (*String
- L
'0');
763 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
765 This function returns a value of type UINTN by interpreting the contents
766 of the Unicode string specified by String as a hexadecimal number.
767 The format of the input Unicode string String is:
769 [spaces][zeros][x][hexadecimal digits].
771 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
772 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
773 If "x" appears in the input string, it must be prefixed with at least one 0.
774 The function will ignore the pad space, which includes spaces or tab characters,
775 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
776 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
777 first valid hexadecimal digit. Then, the function stops at the first character that is
778 a not a valid hexadecimal character or NULL, whichever one comes first.
780 If String is NULL, then ASSERT().
781 If String is not aligned in a 16-bit boundary, then ASSERT().
782 If String has only pad spaces, then zero is returned.
783 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
784 then zero is returned.
785 If the number represented by String overflows according to the range defined by
786 UINTN, then ASSERT().
788 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
789 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
792 @param String Pointer to a Null-terminated Unicode string.
794 @return The value of type UINTN converted.
800 IN CONST CHAR16
*String
806 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
807 // Length tests are performed inside StrLen().
809 ASSERT (StrSize (String
) != 0);
812 // Ignore the pad spaces (space or tab)
814 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
819 // Ignore leading Zeros after the spaces
821 while (L
'0' == *String
) {
825 if (InternalCharToUpper (*String
) == L
'X') {
826 ASSERT (L
'0' == *(String
- 1));
827 if (*(String
- 1) != L
'0') {
838 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
840 // If the Hex Number represented by String overflows according
841 // to the range defined by UINTN, then ASSERT().
843 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_16
) ||
844 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
845 (InternalHexCharToUintn (*String
) <= REMAINDER_MAX_UINTN_DIVIDED_BY_16
))
848 Result
= (Result
<< 4) + InternalHexCharToUintn (*String
);
857 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
859 This function returns a value of type UINT64 by interpreting the contents
860 of the Unicode string specified by String as a hexadecimal number.
861 The format of the input Unicode string String is
863 [spaces][zeros][x][hexadecimal digits].
865 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
866 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
867 If "x" appears in the input string, it must be prefixed with at least one 0.
868 The function will ignore the pad space, which includes spaces or tab characters,
869 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
870 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
871 first valid hexadecimal digit. Then, the function stops at the first character that is
872 a not a valid hexadecimal character or NULL, whichever one comes first.
874 If String is NULL, then ASSERT().
875 If String is not aligned in a 16-bit boundary, then ASSERT().
876 If String has only pad spaces, then zero is returned.
877 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
878 then zero is returned.
879 If the number represented by String overflows according to the range defined by
880 UINT64, then ASSERT().
882 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
883 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
886 @param String Pointer to a Null-terminated Unicode string.
888 @return The value of type UINT64 converted.
894 IN CONST CHAR16
*String
900 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
901 // Length tests are performed inside StrLen().
903 ASSERT (StrSize (String
) != 0);
906 // Ignore the pad spaces (space or tab)
908 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
913 // Ignore leading Zeros after the spaces
915 while (L
'0' == *String
) {
919 if (InternalCharToUpper (*String
) == L
'X') {
920 ASSERT (L
'0' == *(String
- 1));
921 if (*(String
- 1) != L
'0') {
932 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
934 // If the Hex Number represented by String overflows according
935 // to the range defined by UINTN, then ASSERT().
937 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_16
)||
938 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
939 (InternalHexCharToUintn (*String
) <= REMAINDER_MAX_UINT64_DIVIDED_BY_16
))
942 Result
= LShiftU64 (Result
, 4);
943 Result
= Result
+ InternalHexCharToUintn (*String
);
951 Check if a ASCII character is a decimal character.
953 This internal function checks if a Unicode character is a
954 decimal character. The valid decimal character is from
957 @param Char The character to check against.
959 @retval TRUE If the Char is a decmial character.
960 @retval FALSE If the Char is not a decmial character.
965 InternalAsciiIsDecimalDigitCharacter (
969 return (BOOLEAN
) (Char
>= '0' && Char
<= '9');
973 Check if a ASCII character is a hexadecimal character.
975 This internal function checks if a ASCII character is a
976 decimal character. The valid hexadecimal character is
977 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
980 @param Char The character to check against.
982 @retval TRUE If the Char is a hexadecmial character.
983 @retval FALSE If the Char is not a hexadecmial character.
988 InternalAsciiIsHexaDecimalDigitCharacter (
993 return (BOOLEAN
) (InternalAsciiIsDecimalDigitCharacter (Char
) ||
994 (Char
>= 'A' && Char
<= 'F') ||
995 (Char
>= 'a' && Char
<= 'f'));
999 Convert a Null-terminated Unicode string to a Null-terminated
1000 ASCII string and returns the ASCII string.
1002 This function converts the content of the Unicode string Source
1003 to the ASCII string Destination by copying the lower 8 bits of
1004 each Unicode character. It returns Destination. The function terminates
1005 the ASCII string Destination by appending a Null-terminator character
1006 at the end. The caller is responsible to make sure Destination points
1007 to a buffer with size equal or greater than (StrLen (Source) + 1) in bytes.
1009 If Destination is NULL, then ASSERT().
1010 If Source is NULL, then ASSERT().
1011 If Source is not aligned on a 16-bit boundary, then ASSERT().
1012 If Source and Destination overlap, then ASSERT().
1014 If any Unicode characters in Source contain non-zero value in
1015 the upper 8 bits, then ASSERT().
1017 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1018 more than PcdMaximumUnicodeStringLength Unicode characters not including
1019 the Null-terminator, then ASSERT().
1021 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1022 than PcdMaximumAsciiStringLength Unicode characters not including the
1023 Null-terminator, then ASSERT().
1025 @param Source Pointer to a Null-terminated Unicode string.
1026 @param Destination Pointer to a Null-terminated ASCII string.
1028 @return Destination pointing to the converted ASCII string.
1033 UnicodeStrToAsciiStr (
1034 IN CONST CHAR16
*Source
,
1035 OUT CHAR8
*Destination
1040 ASSERT (Destination
!= NULL
);
1043 // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
1044 // Length tests are performed inside StrLen().
1046 ASSERT (StrSize (Source
) != 0);
1049 // Source and Destination should not overlap
1051 ASSERT ((UINTN
) ((CHAR16
*) Destination
- Source
) > StrLen (Source
));
1052 ASSERT ((UINTN
) ((CHAR8
*) Source
- Destination
) > StrLen (Source
));
1055 ReturnValue
= Destination
;
1056 while (*Source
!= '\0') {
1058 // If any Unicode characters in Source contain
1059 // non-zero value in the upper 8 bits, then ASSERT().
1061 ASSERT (*Source
< 0x100);
1062 *(Destination
++) = (CHAR8
) *(Source
++);
1065 *Destination
= '\0';
1068 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
1069 // Length tests are performed inside AsciiStrLen().
1071 ASSERT (AsciiStrSize (ReturnValue
) != 0);
1078 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1079 string and returns the new ASCII string.
1081 This function copies the contents of the ASCII string Source to the ASCII
1082 string Destination, and returns Destination. If Source and Destination
1083 overlap, then the results are undefined.
1085 If Destination is NULL, then ASSERT().
1086 If Source is NULL, then ASSERT().
1087 If Source and Destination overlap, then ASSERT().
1088 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1089 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1092 @param Destination Pointer to a Null-terminated ASCII string.
1093 @param Source Pointer to a Null-terminated ASCII string.
1095 @return Destination pointing to the copied string.
1101 OUT CHAR8
*Destination
,
1102 IN CONST CHAR8
*Source
1108 // Destination cannot be NULL
1110 ASSERT (Destination
!= NULL
);
1113 // Destination and source cannot overlap
1115 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1116 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
1118 ReturnValue
= Destination
;
1119 while (*Source
!= 0) {
1120 *(Destination
++) = *(Source
++);
1127 Copies one Null-terminated ASCII string with a maximum length to another
1128 Null-terminated ASCII string with a maximum length and returns the new ASCII
1131 This function copies the contents of the ASCII string Source to the ASCII
1132 string Destination, and returns Destination. At most, Length ASCII characters
1133 are copied from Source to Destination. If Length is 0, then Destination is
1134 returned unmodified. If Length is greater that the number of ASCII characters
1135 in Source, then Destination is padded with Null ASCII characters. If Source
1136 and Destination overlap, then the results are undefined.
1138 If Destination is NULL, then ASSERT().
1139 If Source is NULL, then ASSERT().
1140 If Source and Destination overlap, then ASSERT().
1141 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1142 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1145 @param Destination Pointer to a Null-terminated ASCII string.
1146 @param Source Pointer to a Null-terminated ASCII string.
1147 @param Length Maximum number of ASCII characters to copy.
1149 @return Destination pointing to the copied string.
1155 OUT CHAR8
*Destination
,
1156 IN CONST CHAR8
*Source
,
1167 // Destination cannot be NULL
1169 ASSERT (Destination
!= NULL
);
1172 // Destination and source cannot overlap
1174 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1175 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
1177 ReturnValue
= Destination
;
1179 while (*Source
!= 0 && Length
> 0) {
1180 *(Destination
++) = *(Source
++);
1184 ZeroMem (Destination
, Length
* sizeof (*Destination
));
1189 Returns the length of a Null-terminated ASCII string.
1191 This function returns the number of ASCII characters in the Null-terminated
1192 ASCII string specified by String.
1194 If String is NULL, then ASSERT().
1195 If PcdMaximumAsciiStringLength is not zero and String contains more than
1196 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1199 @param String Pointer to a Null-terminated ASCII string.
1201 @return The length of String.
1207 IN CONST CHAR8
*String
1212 ASSERT (String
!= NULL
);
1214 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
1216 // If PcdMaximumUnicodeStringLength is not zero,
1217 // length should not more than PcdMaximumUnicodeStringLength
1219 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1220 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
1227 Returns the size of a Null-terminated ASCII string in bytes, including the
1230 This function returns the size, in bytes, of the Null-terminated ASCII string
1231 specified by String.
1233 If String is NULL, then ASSERT().
1234 If PcdMaximumAsciiStringLength is not zero and String contains more than
1235 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1238 @param String Pointer to a Null-terminated ASCII string.
1240 @return The size of String.
1246 IN CONST CHAR8
*String
1249 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
1253 Compares two Null-terminated ASCII strings, and returns the difference
1254 between the first mismatched ASCII characters.
1256 This function compares the Null-terminated ASCII string FirstString to the
1257 Null-terminated ASCII string SecondString. If FirstString is identical to
1258 SecondString, then 0 is returned. Otherwise, the value returned is the first
1259 mismatched ASCII character in SecondString subtracted from the first
1260 mismatched ASCII character in FirstString.
1262 If FirstString is NULL, then ASSERT().
1263 If SecondString is NULL, then ASSERT().
1264 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1265 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1267 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1268 than PcdMaximumAsciiStringLength ASCII characters not including the
1269 Null-terminator, then ASSERT().
1271 @param FirstString Pointer to a Null-terminated ASCII string.
1272 @param SecondString Pointer to a Null-terminated ASCII string.
1274 @retval 0 FirstString is identical to SecondString.
1275 @return The first mismatched ASCII character in SecondString subtracted
1276 from the first mismatched ASCII character in FirstString.
1282 IN CONST CHAR8
*FirstString
,
1283 IN CONST CHAR8
*SecondString
1287 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1289 ASSERT (AsciiStrSize (FirstString
));
1290 ASSERT (AsciiStrSize (SecondString
));
1292 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
1297 return *FirstString
- *SecondString
;
1301 Converts a lowercase Ascii character to upper one.
1303 If Chr is lowercase Ascii character, then converts it to upper one.
1305 If Value >= 0xA0, then ASSERT().
1306 If (Value & 0x0F) >= 0x0A, then ASSERT().
1308 @param Chr one Ascii character
1310 @return The uppercase value of Ascii character
1319 return (UINT8
) ((Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
);
1323 Convert a ASCII character to numerical value.
1325 This internal function only deal with Unicode character
1326 which maps to a valid hexadecimal ASII character, i.e.
1327 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1328 ASCII character, the value returned does not make sense.
1330 @param Char The character to convert.
1332 @return The numerical value converted.
1337 InternalAsciiHexCharToUintn (
1341 if (InternalIsDecimalDigitCharacter (Char
)) {
1345 return (UINTN
) (10 + AsciiToUpper (Char
) - 'A');
1350 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1351 and returns the difference between the first mismatched ASCII characters.
1353 This function performs a case insensitive comparison of the Null-terminated
1354 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1355 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1356 value returned is the first mismatched lower case ASCII character in
1357 SecondString subtracted from the first mismatched lower case ASCII character
1360 If FirstString is NULL, then ASSERT().
1361 If SecondString is NULL, then ASSERT().
1362 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1363 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1365 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1366 than PcdMaximumAsciiStringLength ASCII characters not including the
1367 Null-terminator, then ASSERT().
1369 @param FirstString Pointer to a Null-terminated ASCII string.
1370 @param SecondString Pointer to a Null-terminated ASCII string.
1372 @retval 0 FirstString is identical to SecondString using case insensitive
1374 @return The first mismatched lower case ASCII character in SecondString subtracted
1375 from the first mismatched lower case ASCII character in FirstString.
1381 IN CONST CHAR8
*FirstString
,
1382 IN CONST CHAR8
*SecondString
1385 CHAR8 UpperFirstString
;
1386 CHAR8 UpperSecondString
;
1389 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1391 ASSERT (AsciiStrSize (FirstString
));
1392 ASSERT (AsciiStrSize (SecondString
));
1394 UpperFirstString
= AsciiToUpper (*FirstString
);
1395 UpperSecondString
= AsciiToUpper (*SecondString
);
1396 while ((*FirstString
!= '\0') && (UpperFirstString
== UpperSecondString
)) {
1399 UpperFirstString
= AsciiToUpper (*FirstString
);
1400 UpperSecondString
= AsciiToUpper (*SecondString
);
1403 return UpperFirstString
- UpperSecondString
;
1407 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1408 the difference between the first mismatched ASCII characters.
1410 This function compares the Null-terminated ASCII string FirstString to the
1411 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1412 will be compared. If Length is 0, then 0 is returned. If FirstString is
1413 identical to SecondString, then 0 is returned. Otherwise, the value returned
1414 is the first mismatched ASCII character in SecondString subtracted from the
1415 first mismatched ASCII character in FirstString.
1417 If FirstString is NULL, then ASSERT().
1418 If SecondString is NULL, then ASSERT().
1419 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1420 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1422 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
1423 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1426 @param FirstString Pointer to a Null-terminated ASCII string.
1427 @param SecondString Pointer to a Null-terminated ASCII string.
1428 @param Length Maximum number of ASCII characters to compare.
1430 @retval 0 FirstString is identical to SecondString.
1431 @return The first mismatched ASCII character in SecondString subtracted from the
1432 first mismatched ASCII character in FirstString.
1438 IN CONST CHAR8
*FirstString
,
1439 IN CONST CHAR8
*SecondString
,
1448 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1450 ASSERT (AsciiStrSize (FirstString
));
1451 ASSERT (AsciiStrSize (SecondString
));
1453 while ((*FirstString
!= '\0') &&
1454 (*FirstString
== *SecondString
) &&
1460 return *FirstString
- *SecondString
;
1464 Concatenates one Null-terminated ASCII string to another Null-terminated
1465 ASCII string, and returns the concatenated ASCII string.
1467 This function concatenates two Null-terminated ASCII strings. The contents of
1468 Null-terminated ASCII string Source are concatenated to the end of Null-
1469 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1472 If Destination is NULL, then ASSERT().
1473 If Source is NULL, then ASSERT().
1474 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1475 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1477 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1478 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1480 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1481 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1482 ASCII characters, then ASSERT().
1484 @param Destination Pointer to a Null-terminated ASCII string.
1485 @param Source Pointer to a Null-terminated ASCII string.
1487 @return Destination pointing to the concatenated ASCII string.
1493 IN OUT CHAR8
*Destination
,
1494 IN CONST CHAR8
*Source
1497 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
1500 // Size of the resulting string should never be zero.
1501 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1503 ASSERT (AsciiStrSize (Destination
) != 0);
1508 Concatenates one Null-terminated ASCII string with a maximum length to the
1509 end of another Null-terminated ASCII string, and returns the concatenated
1512 This function concatenates two Null-terminated ASCII strings. The contents
1513 of Null-terminated ASCII string Source are concatenated to the end of Null-
1514 terminated ASCII string Destination, and Destination is returned. At most,
1515 Length ASCII characters are concatenated from Source to the end of
1516 Destination, and Destination is always Null-terminated. If Length is 0, then
1517 Destination is returned unmodified. If Source and Destination overlap, then
1518 the results are undefined.
1520 If Destination is NULL, then ASSERT().
1521 If Source is NULL, then ASSERT().
1522 If Source and Destination overlap, then ASSERT().
1523 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1524 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1526 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1527 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1529 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1530 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1531 ASCII characters not including the Null-terminator, then ASSERT().
1533 @param Destination Pointer to a Null-terminated ASCII string.
1534 @param Source Pointer to a Null-terminated ASCII string.
1535 @param Length Maximum number of ASCII characters to concatenate from
1538 @return Destination pointing to the concatenated ASCII string.
1544 IN OUT CHAR8
*Destination
,
1545 IN CONST CHAR8
*Source
,
1549 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
1552 // Size of the resulting string should never be zero.
1553 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1555 ASSERT (AsciiStrSize (Destination
) != 0);
1560 Returns the first occurance of a Null-terminated ASCII sub-string
1561 in a Null-terminated ASCII string.
1563 This function scans the contents of the ASCII string specified by String
1564 and returns the first occurrence of SearchString. If SearchString is not
1565 found in String, then NULL is returned. If the length of SearchString is zero,
1566 then String is returned.
1568 If String is NULL, then ASSERT().
1569 If SearchString is NULL, then ASSERT().
1571 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1572 String contains more than PcdMaximumAsciiStringLength Unicode characters
1573 not including the Null-terminator, then ASSERT().
1575 @param String Pointer to a Null-terminated ASCII string.
1576 @param SearchString Pointer to a Null-terminated ASCII string to search for.
1578 @retval NULL If the SearchString does not appear in String.
1579 @return Pointer to the matching sub-string.
1585 IN CONST CHAR8
*String
,
1586 IN CONST CHAR8
*SearchString
1589 CONST CHAR8
*FirstMatch
;
1590 CONST CHAR8
*SearchStringTmp
;
1593 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1595 ASSERT (AsciiStrSize (String
) != 0);
1596 ASSERT (AsciiStrSize (SearchString
) != 0);
1598 while (*String
!= '\0') {
1599 SearchStringTmp
= SearchString
;
1600 FirstMatch
= String
;
1602 while ((*String
== *SearchStringTmp
)
1603 && (*SearchStringTmp
!= '\0')
1604 && (*String
!= '\0')) {
1609 if (*SearchStringTmp
== '\0') {
1610 return (CHAR8
*) FirstMatch
;
1613 if (SearchStringTmp
== SearchString
) {
1615 // If no character from SearchString match,
1616 // move the pointer to the String under search
1617 // by one character.
1628 Convert a Null-terminated ASCII decimal string to a value of type
1631 This function returns a value of type UINTN by interpreting the contents
1632 of the ASCII string String as a decimal number. The format of the input
1633 ASCII string String is:
1635 [spaces] [decimal digits].
1637 The valid decimal digit character is in the range [0-9]. The function will
1638 ignore the pad space, which includes spaces or tab characters, before the digits.
1639 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1640 function stops at the first character that is a not a valid decimal character or
1641 Null-terminator, whichever on comes first.
1643 If String has only pad spaces, then 0 is returned.
1644 If String has no pad spaces or valid decimal digits, then 0 is returned.
1645 If the number represented by String overflows according to the range defined by
1646 UINTN, then ASSERT().
1647 If String is NULL, then ASSERT().
1648 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1649 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1652 @param String Pointer to a Null-terminated ASCII string.
1654 @return The value of type UINTN converted.
1659 AsciiStrDecimalToUintn (
1660 IN CONST CHAR8
*String
1666 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1668 ASSERT (AsciiStrSize (String
) != 0);
1671 // Ignore the pad spaces (space or tab)
1673 while ((' ' == *String
) || ('\t' == *String
)) {
1678 // Ignore leading Zeros after the spaces
1680 while ('0' == *String
) {
1686 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1688 // If the number represented by String overflows according
1689 // to the range defined by UINTN, then ASSERT().
1691 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_10
) ||
1692 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
1693 (*String
- '0') <= REMAINDER_MAX_UINTN_DIVIDED_BY_10
)
1696 Result
= Result
* 10 + (*String
- '0');
1705 Convert a Null-terminated ASCII decimal string to a value of type
1708 This function returns a value of type UINT64 by interpreting the contents
1709 of the ASCII string String as a decimal number. The format of the input
1710 ASCII string String is:
1712 [spaces] [decimal digits].
1714 The valid decimal digit character is in the range [0-9]. The function will
1715 ignore the pad space, which includes spaces or tab characters, before the digits.
1716 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1717 function stops at the first character that is a not a valid decimal character or
1718 Null-terminator, whichever on comes first.
1720 If String has only pad spaces, then 0 is returned.
1721 If String has no pad spaces or valid decimal digits, then 0 is returned.
1722 If the number represented by String overflows according to the range defined by
1723 UINT64, then ASSERT().
1724 If String is NULL, then ASSERT().
1725 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1726 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1729 @param String Pointer to a Null-terminated ASCII string.
1731 @return The value of type UINT64 converted.
1736 AsciiStrDecimalToUint64 (
1737 IN CONST CHAR8
*String
1743 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1745 ASSERT (AsciiStrSize (String
) != 0);
1748 // Ignore the pad spaces (space or tab)
1750 while ((' ' == *String
) || ('\t' == *String
)) {
1755 // Ignore leading Zeros after the spaces
1757 while ('0' == *String
) {
1763 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1765 // If the number represented by String overflows according
1766 // to the range defined by UINTN, then ASSERT().
1768 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_10
) ||
1769 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
1770 (*String
- '0') <= REMAINDER_MAX_UINT64_DIVIDED_BY_10
)
1773 Result
= MultU64x32 (Result
, 10) + (*String
- '0');
1781 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1783 This function returns a value of type UINTN by interpreting the contents of
1784 the ASCII string String as a hexadecimal number. The format of the input ASCII
1787 [spaces][zeros][x][hexadecimal digits].
1789 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1790 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1791 appears in the input string, it must be prefixed with at least one 0. The function
1792 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1793 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1794 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1795 digit. Then, the function stops at the first character that is a not a valid
1796 hexadecimal character or Null-terminator, whichever on comes first.
1798 If String has only pad spaces, then 0 is returned.
1799 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1802 If the number represented by String overflows according to the range defined by UINTN,
1804 If String is NULL, then ASSERT().
1805 If PcdMaximumAsciiStringLength is not zero,
1806 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1807 the Null-terminator, then ASSERT().
1809 @param String Pointer to a Null-terminated ASCII string.
1811 @return The value of type UINTN converted.
1816 AsciiStrHexToUintn (
1817 IN CONST CHAR8
*String
1823 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1825 ASSERT (AsciiStrSize (String
) != 0);
1828 // Ignore the pad spaces (space or tab)
1830 while ((' ' == *String
) || ('\t' == *String
)) {
1835 // Ignore leading Zeros after the spaces
1837 while ('0' == *String
) {
1841 if (AsciiToUpper (*String
) == 'X') {
1842 ASSERT ('0' == *(String
- 1));
1843 if (*(String
- 1) != '0') {
1854 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1856 // If the Hex Number represented by String overflows according
1857 // to the range defined by UINTN, then ASSERT().
1859 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_16
) ||
1860 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
1861 (InternalAsciiHexCharToUintn (*String
) <= REMAINDER_MAX_UINTN_DIVIDED_BY_16
))
1864 Result
= (Result
<< 4) + InternalAsciiHexCharToUintn (*String
);
1873 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1875 This function returns a value of type UINT64 by interpreting the contents of
1876 the ASCII string String as a hexadecimal number. The format of the input ASCII
1879 [spaces][zeros][x][hexadecimal digits].
1881 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1882 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1883 appears in the input string, it must be prefixed with at least one 0. The function
1884 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1885 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1886 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1887 digit. Then, the function stops at the first character that is a not a valid
1888 hexadecimal character or Null-terminator, whichever on comes first.
1890 If String has only pad spaces, then 0 is returned.
1891 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1894 If the number represented by String overflows according to the range defined by UINT64,
1896 If String is NULL, then ASSERT().
1897 If PcdMaximumAsciiStringLength is not zero,
1898 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1899 the Null-terminator, then ASSERT().
1901 @param String Pointer to a Null-terminated ASCII string.
1903 @return The value of type UINT64 converted.
1908 AsciiStrHexToUint64 (
1909 IN CONST CHAR8
*String
1915 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1917 ASSERT (AsciiStrSize (String
) != 0);
1920 // Ignore the pad spaces (space or tab) and leading Zeros
1923 // Ignore the pad spaces (space or tab)
1925 while ((' ' == *String
) || ('\t' == *String
)) {
1930 // Ignore leading Zeros after the spaces
1932 while ('0' == *String
) {
1936 if (AsciiToUpper (*String
) == 'X') {
1937 ASSERT ('0' == *(String
- 1));
1938 if (*(String
- 1) != '0') {
1949 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1951 // If the Hex Number represented by String overflows according
1952 // to the range defined by UINTN, then ASSERT().
1954 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_16
) ||
1955 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
1956 (InternalAsciiHexCharToUintn (*String
) <= REMAINDER_MAX_UINT64_DIVIDED_BY_16
))
1959 Result
= LShiftU64 (Result
, 4);
1960 Result
= Result
+ InternalAsciiHexCharToUintn (*String
);
1969 Convert one Null-terminated ASCII string to a Null-terminated
1970 Unicode string and returns the Unicode string.
1972 This function converts the contents of the ASCII string Source to the Unicode
1973 string Destination, and returns Destination. The function terminates the
1974 Unicode string Destination by appending a Null-terminator character at the end.
1975 The caller is responsible to make sure Destination points to a buffer with size
1976 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1978 If Destination is NULL, then ASSERT().
1979 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1980 If Source is NULL, then ASSERT().
1981 If Source and Destination overlap, then ASSERT().
1982 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1983 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1985 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1986 PcdMaximumUnicodeStringLength ASCII characters not including the
1987 Null-terminator, then ASSERT().
1989 @param Source Pointer to a Null-terminated ASCII string.
1990 @param Destination Pointer to a Null-terminated Unicode string.
1992 @return Destination pointing to the converted Unicode string.
1997 AsciiStrToUnicodeStr (
1998 IN CONST CHAR8
*Source
,
1999 OUT CHAR16
*Destination
2002 CHAR16
*ReturnValue
;
2004 ASSERT (Destination
!= NULL
);
2007 // ASSERT Source is less long than PcdMaximumAsciiStringLength
2009 ASSERT (AsciiStrSize (Source
) != 0);
2012 // Source and Destination should not overlap
2014 ASSERT ((UINTN
) ((CHAR8
*) Destination
- Source
) > AsciiStrLen (Source
));
2015 ASSERT ((UINTN
) (Source
- (CHAR8
*) Destination
) > (AsciiStrLen (Source
) * sizeof (CHAR16
)));
2018 ReturnValue
= Destination
;
2019 while (*Source
!= '\0') {
2020 *(Destination
++) = (CHAR16
) *(Source
++);
2023 // End the Destination with a NULL.
2025 *Destination
= '\0';
2028 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
2030 ASSERT (StrSize (ReturnValue
) != 0);
2036 Converts an 8-bit value to an 8-bit BCD value.
2038 Converts the 8-bit value specified by Value to BCD. The BCD value is
2041 If Value >= 100, then ASSERT().
2043 @param Value The 8-bit value to convert to BCD. Range 0..99.
2045 @return The BCD value converted.
2054 ASSERT (Value
< 100);
2055 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2059 Converts an 8-bit BCD value to an 8-bit value.
2061 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2064 If Value >= 0xA0, then ASSERT().
2065 If (Value & 0x0F) >= 0x0A, then ASSERT().
2067 @param Value The 8-bit BCD value to convert to an 8-bit value.
2069 @return The 8-bit decimal value converted.
2078 ASSERT (Value
< 0xa0);
2079 ASSERT ((Value
& 0xf) < 0xa);
2080 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));
2085 Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character.
2087 This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal
2088 character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A'
2091 The upper nibble in the input byte will be masked off.
2093 @param Nibble The nibble which is in the low 4 bits of the input byte.
2095 @return The Unicode hexadecimal character.
2104 if (Nibble
<= 0x9) {
2105 return (CHAR16
)(Nibble
+ L
'0');
2108 return (CHAR16
)(Nibble
- 0xA + L
'A');
2112 Convert binary buffer to a Unicode String in a specified sequence.
2114 This function converts bytes in the memory block pointed by Buffer to a Unicode String Str.
2115 Each byte will be represented by two Unicode characters. For example, byte 0xA1 will
2116 be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character
2117 for the Most Significant Nibble will be put before the Unicode Character for the Least Significant
2118 Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1".
2119 For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the
2120 the last character in the output string. The one next to first byte will be put into the
2121 character before the last character. This rules applies to the rest of the bytes. The Unicode
2122 character by the last byte will be put into the first character in the output string. For example,
2123 the input buffer for a 64-bits unsigned integrer 0x12345678abcdef1234 will be converted to
2124 a Unicode string equal to L"12345678abcdef1234".
2126 @param String Pointer to the buffer allocated for the convertion.
2127 @param StringLen On input: Pointer to length in bytes of buffer to hold the Unicode string.
2128 On output:If return EFI_SUCCESS, pointer to length of Unicode string converted.
2129 If return EFI_BUFFER_TOO_SMALL, pointer to length of string buffer desired.
2130 @param Buffer The pointer to a input buffer.
2131 @param BufferSizeInBytes Lenth in bytes of the input buffer.
2133 @retval EFI_SUCCESS The convertion is successfull. All bytes in Buffer has been convert to the corresponding
2134 Unicode character and placed into the right place in String.
2135 @retval EFI_BUFFER_TOO_SMALL StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to
2136 complete the convertion.
2141 IN OUT CHAR16
*String
,
2142 IN OUT UINTN
*StringLen
,
2143 IN CONST UINT8
*Buffer
,
2144 IN UINTN BufferSizeInBytes
2152 // Make sure string is either passed or allocate enough.
2153 // It takes 2 Unicode characters (4 bytes) to represent 1 byte of the binary buffer.
2154 // Plus the Unicode termination character.
2156 StrLen
= BufferSizeInBytes
* 2;
2157 if (StrLen
> ((*StringLen
) - 1)) {
2158 *StringLen
= StrLen
+ 1;
2159 return RETURN_BUFFER_TOO_SMALL
;
2162 *StringLen
= StrLen
+ 1;
2166 String
[StrLen
] = L
'\0';
2168 for (Idx
= 0; Idx
< BufferSizeInBytes
; Idx
++) {
2171 String
[StrLen
- 1 - Idx
* 2] = NibbleToHexChar (Byte
);
2172 String
[StrLen
- 2 - Idx
* 2] = NibbleToHexChar ((UINT8
)(Byte
>> 4));
2175 return RETURN_SUCCESS
;
2180 Convert a Unicode string consisting of hexadecimal characters to a output byte buffer.
2182 This function converts a Unicode string consisting of characters in the range of Hexadecimal
2183 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
2184 at the first non-hexadecimal character or the NULL character. The convertion process can be
2185 simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be
2186 converted into one byte. The first Unicode character represents the Most Significant Nibble and the
2187 second Unicode character represents the Least Significant Nibble in the output byte.
2188 The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode
2189 characters represent the the byte preceding the last byte. This rule applies to the rest pairs of bytes.
2190 The last pair represent the first byte in the output buffer.
2192 For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes
2193 (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12".
2195 If String has N valid hexadecimal characters for conversion, the caller must make sure Buffer is at least
2196 N/2 (if N is even) or (N+1)/2 (if N if odd) bytes.
2198 @param Buffer The output buffer allocated by the caller.
2199 @param BufferSizeInBytes On input, the size in bytes of Buffer. On output, it is updated to
2200 contain the size of the Buffer which is actually used for the converstion.
2201 For Unicode string with 2*N hexadecimal characters (not including the
2202 tailing NULL character), N bytes of Buffer will be used for the output.
2203 @param String The input hexadecimal string.
2204 @param ConvertedStrLen The number of hexadecimal characters used to produce content in output
2207 @retval RETURN_BUFFER_TOO_SMALL The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes
2208 will be updated to the size required for the converstion.
2209 @retval RETURN_SUCCESS The convertion is successful or the first Unicode character from String
2210 is hexadecimal. If ConvertedStrLen is not NULL, it is updated
2211 to the number of hexadecimal character used for the converstion.
2217 IN OUT UINTN
*BufferSizeInBytes
,
2218 IN CONST CHAR16
*String
,
2219 OUT UINTN
*ConvertedStrLen OPTIONAL
2229 // Find out how many hex characters the string has.
2231 for (Idx
= 0, HexCnt
= 0; IsHexDigit (&Digit
, String
[Idx
]); Idx
++, HexCnt
++);
2234 *ConvertedStrLen
= 0;
2235 return RETURN_SUCCESS
;
2238 // Two Unicode characters make up 1 buffer byte. Round up.
2240 BufferLength
= (HexCnt
+ 1) / 2;
2243 // Test if buffer is passed enough.
2245 if (BufferLength
> (*BufferSizeInBytes
)) {
2246 *BufferSizeInBytes
= BufferLength
;
2247 return RETURN_BUFFER_TOO_SMALL
;
2250 *BufferSizeInBytes
= BufferLength
;
2252 for (Idx
= 0; Idx
< HexCnt
; Idx
++) {
2254 IsHexDigit (&Digit
, String
[HexCnt
- 1 - Idx
]);
2257 // For odd charaters, write the lower nibble for each buffer byte,
2258 // and for even characters, the upper nibble.
2260 if ((Idx
& 1) == 0) {
2263 Byte
= Buffer
[Idx
/ 2];
2265 Byte
= (UINT8
) (Byte
| Digit
<< 4);
2268 Buffer
[Idx
/ 2] = Byte
;
2271 if (ConvertedStrLen
!= NULL
) {
2272 *ConvertedStrLen
= HexCnt
;
2275 return RETURN_SUCCESS
;
2280 Test if a Unicode character is a hexadecimal digit. If true, the input
2281 Unicode character is converted to a byte.
2283 This function tests if a Unicode character is a hexadecimal digit. If true, the input
2284 Unicode character is converted to a byte. For example, Unicode character
2285 L'A' will be converted to 0x0A.
2287 If Digit is NULL, then ASSERT().
2289 @param Digit The output hexadecimal digit.
2290 @param Char The input Unicode character.
2292 @retval TRUE Char is in the range of Hexadecimal number. Digit is updated
2293 to the byte value of the number.
2294 @retval FALSE Char is not in the range of Hexadecimal number. Digit is keep
2304 ASSERT (Digit
!= NULL
);
2306 if ((Char
>= L
'0') && (Char
<= L
'9')) {
2307 *Digit
= (UINT8
) (Char
- L
'0');
2311 if ((Char
>= L
'A') && (Char
<= L
'F')) {
2312 *Digit
= (UINT8
) (Char
- L
'A' + 0x0A);
2316 if ((Char
>= L
'a') && (Char
<= L
'f')) {
2317 *Digit
= (UINT8
) (Char
- L
'a' + 0x0A);