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.
18 #include "BaseLibInternals.h"
20 #define QUOTIENT_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 / 10)
21 #define REMAINDER_MAX_UINTN_DIVIDED_BY_10 ((UINTN) -1 % 10)
23 #define QUOTIENT_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 / 16)
24 #define REMAINDER_MAX_UINTN_DIVIDED_BY_16 ((UINTN) -1 % 16)
26 #define QUOTIENT_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 / 10)
27 #define REMAINDER_MAX_UINT64_DIVIDED_BY_10 ((UINT64) -1 % 10)
29 #define QUOTIENT_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 / 16)
30 #define REMAINDER_MAX_UINT64_DIVIDED_BY_16 ((UINT64) -1 % 16)
33 Copies one Null-terminated Unicode string to another Null-terminated Unicode
34 string and returns the new Unicode string.
36 This function copies the contents of the Unicode string Source to the Unicode
37 string Destination, and returns Destination. If Source and Destination
38 overlap, then the results are undefined.
40 If Destination is NULL, then ASSERT().
41 If Destination is not aligned on a 16-bit boundary, then ASSERT().
42 If Source is NULL, then ASSERT().
43 If Source is not aligned on a 16-bit boundary, then ASSERT().
44 If Source and Destination overlap, then ASSERT().
45 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
46 PcdMaximumUnicodeStringLength Unicode characters not including the
47 Null-terminator, then ASSERT().
49 @param Destination Pointer to a Null-terminated Unicode string.
50 @param Source Pointer to a Null-terminated Unicode string.
52 @return Destination pointing to the copied string.
58 OUT CHAR16
*Destination
,
59 IN CONST CHAR16
*Source
65 // Destination cannot be NULL
67 ASSERT (Destination
!= NULL
);
68 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
71 // Destination and source cannot overlap
73 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
74 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
76 ReturnValue
= Destination
;
77 while (*Source
!= 0) {
78 *(Destination
++) = *(Source
++);
85 Copies one Null-terminated Unicode string with a maximum length to another
86 Null-terminated Unicode string with a maximum length and returns the new
89 This function copies the contents of the Unicode string Source to the Unicode
90 string Destination, and returns Destination. At most, Length Unicode
91 characters are copied from Source to Destination. If Length is 0, then
92 Destination is returned unmodified. If Length is greater that the number of
93 Unicode characters in Source, then Destination is padded with Null Unicode
94 characters. If Source and Destination overlap, then the results are
97 If Length > 0 and Destination is NULL, then ASSERT().
98 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
99 If Length > 0 and Source is NULL, then ASSERT().
100 If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT().
101 If Source and Destination overlap, then ASSERT().
102 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
103 PcdMaximumUnicodeStringLength Unicode characters not including the
104 Null-terminator, then ASSERT().
106 @param Destination Pointer to a Null-terminated Unicode string.
107 @param Source Pointer to a Null-terminated Unicode string.
108 @param Length Maximum number of Unicode characters to copy.
110 @return Destination pointing to the copied string.
116 OUT CHAR16
*Destination
,
117 IN CONST CHAR16
*Source
,
128 // Destination cannot be NULL if Length is not zero
130 ASSERT (Destination
!= NULL
);
131 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
134 // Destination and source cannot overlap
136 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
137 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
139 ReturnValue
= Destination
;
141 while ((*Source
!= L
'\0') && (Length
> 0)) {
142 *(Destination
++) = *(Source
++);
146 ZeroMem (Destination
, Length
* sizeof (*Destination
));
151 Returns the length of a Null-terminated Unicode string.
153 This function returns the number of Unicode characters in the Null-terminated
154 Unicode string specified by String.
156 If String is NULL, then ASSERT().
157 If String is not aligned on a 16-bit boundary, then ASSERT().
158 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
159 PcdMaximumUnicodeStringLength Unicode characters not including the
160 Null-terminator, then ASSERT().
162 @param String Pointer to a Null-terminated Unicode string.
164 @return The length of String.
170 IN CONST CHAR16
*String
175 ASSERT (String
!= NULL
);
176 ASSERT (((UINTN
) String
& BIT0
) == 0);
178 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
180 // If PcdMaximumUnicodeStringLength is not zero,
181 // length should not more than PcdMaximumUnicodeStringLength
183 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
184 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
191 Returns the size of a Null-terminated Unicode string in bytes, including the
194 This function returns the size, in bytes, of the Null-terminated Unicode
195 string specified by String.
197 If String is NULL, then ASSERT().
198 If String is not aligned on a 16-bit boundary, then ASSERT().
199 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
200 PcdMaximumUnicodeStringLength Unicode characters not including the
201 Null-terminator, then ASSERT().
203 @param String Pointer to a Null-terminated Unicode string.
205 @return The size in bytes of String.
211 IN CONST CHAR16
*String
214 return (StrLen (String
) + 1) * sizeof (*String
);
218 Compares two Null-terminated Unicode strings, and returns the difference
219 between the first mismatched Unicode characters.
221 This function compares the Null-terminated Unicode string FirstString to the
222 Null-terminated Unicode string SecondString. If FirstString is identical to
223 SecondString, then 0 is returned. Otherwise, the value returned is the first
224 mismatched Unicode character in SecondString subtracted from the first
225 mismatched Unicode character in FirstString.
227 If FirstString is NULL, then ASSERT().
228 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
229 If SecondString is NULL, then ASSERT().
230 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
231 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
232 than PcdMaximumUnicodeStringLength Unicode characters not including the
233 Null-terminator, then ASSERT().
234 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
235 than PcdMaximumUnicodeStringLength Unicode characters not including the
236 Null-terminator, then ASSERT().
238 @param FirstString Pointer to a Null-terminated Unicode string.
239 @param SecondString Pointer to a Null-terminated Unicode string.
241 @retval 0 FirstString is identical to SecondString.
242 @return The first mismatched Unicode character in SecondString subtracted
243 from the first mismatched Unicode character in FirstString.
249 IN CONST CHAR16
*FirstString
,
250 IN CONST CHAR16
*SecondString
254 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
256 ASSERT (StrSize (FirstString
) != 0);
257 ASSERT (StrSize (SecondString
) != 0);
259 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
263 return *FirstString
- *SecondString
;
267 Compares two Null-terminated Unicode strings with maximum lengths, and
268 returns the difference between the first mismatched Unicode characters.
270 This function compares the Null-terminated Unicode string FirstString to the
271 Null-terminated Unicode string SecondString. At most, Length Unicode
272 characters will be compared. If Length is 0, then 0 is returned. If
273 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
274 value returned is the first mismatched Unicode character in SecondString
275 subtracted from the first mismatched Unicode character in FirstString.
277 If Length > 0 and FirstString is NULL, then ASSERT().
278 If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT().
279 If Length > 0 and SecondString is NULL, then ASSERT().
280 If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT().
281 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
282 than PcdMaximumUnicodeStringLength Unicode characters not including the
283 Null-terminator, then ASSERT().
284 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
285 than PcdMaximumUnicodeStringLength Unicode characters not including the
286 Null-terminator, then ASSERT().
288 @param FirstString Pointer to a Null-terminated Unicode string.
289 @param SecondString Pointer to a Null-terminated Unicode string.
290 @param Length Maximum number of Unicode characters to compare.
292 @retval 0 FirstString is identical to SecondString.
293 @return The value returned is the first mismatched Unicode character in SecondString
294 subtracted from the first mismatched Unicode character in FirstString.
300 IN CONST CHAR16
*FirstString
,
301 IN CONST CHAR16
*SecondString
,
310 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
311 // Length tests are performed inside StrLen().
313 ASSERT (StrSize (FirstString
) != 0);
314 ASSERT (StrSize (SecondString
) != 0);
316 while ((*FirstString
!= L
'\0') &&
317 (*FirstString
== *SecondString
) &&
324 return *FirstString
- *SecondString
;
328 Concatenates one Null-terminated Unicode string to another Null-terminated
329 Unicode string, and returns the concatenated Unicode string.
331 This function concatenates two Null-terminated Unicode strings. The contents
332 of Null-terminated Unicode string Source are concatenated to the end of
333 Null-terminated Unicode string Destination. The Null-terminated concatenated
334 Unicode String is returned. If Source and Destination overlap, then the
335 results are undefined.
337 If Destination is NULL, then ASSERT().
338 If Source is NULL, then ASSERT().
339 If Source and Destination overlap, then ASSERT().
340 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
341 than PcdMaximumUnicodeStringLength Unicode characters not including the
342 Null-terminator, then ASSERT().
343 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
344 PcdMaximumUnicodeStringLength Unicode characters not including the
345 Null-terminator, then ASSERT().
346 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
347 and Source results in a Unicode string with more than
348 PcdMaximumUnicodeStringLength Unicode characters not including the
349 Null-terminator, then ASSERT().
351 @param Destination Pointer to a Null-terminated Unicode string.
352 @param Source Pointer to a Null-terminated Unicode string.
354 @return Destination pointing to the concatenated Unicode string.
360 IN OUT CHAR16
*Destination
,
361 IN CONST CHAR16
*Source
364 StrCpy (Destination
+ StrLen (Destination
), Source
);
367 // Size of the resulting string should never be zero.
368 // PcdMaximumUnicodeStringLength is tested inside StrLen().
370 ASSERT (StrSize (Destination
) != 0);
375 Concatenates one Null-terminated Unicode string with a maximum length to the
376 end of another Null-terminated Unicode string, and returns the concatenated
379 This function concatenates two Null-terminated Unicode strings. The contents
380 of Null-terminated Unicode string Source are concatenated to the end of
381 Null-terminated Unicode string Destination, and Destination is returned. At
382 most, Length Unicode characters are concatenated from Source to the end of
383 Destination, and Destination is always Null-terminated. If Length is 0, then
384 Destination is returned unmodified. If Source and Destination overlap, then
385 the results are undefined.
387 If Destination is NULL, then ASSERT().
388 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
389 If Length > 0 and Source is NULL, then ASSERT().
390 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
391 If Source and Destination overlap, then ASSERT().
392 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
393 than PcdMaximumUnicodeStringLength Unicode characters not including the
394 Null-terminator, then ASSERT().
395 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
396 PcdMaximumUnicodeStringLength Unicode characters not including the
397 Null-terminator, then ASSERT().
398 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
399 and Source results in a Unicode string with more than
400 PcdMaximumUnicodeStringLength Unicode characters not including the
401 Null-terminator, then ASSERT().
403 @param Destination Pointer to a Null-terminated Unicode string.
404 @param Source Pointer to a Null-terminated Unicode string.
405 @param Length Maximum number of Unicode characters to concatenate from
408 @return Destination pointing to the concatenated Unicode string.
414 IN OUT CHAR16
*Destination
,
415 IN CONST CHAR16
*Source
,
419 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
422 // Size of the resulting string should never be zero.
423 // PcdMaximumUnicodeStringLength is tested inside StrLen().
425 ASSERT (StrSize (Destination
) != 0);
430 Returns the first occurance of a Null-terminated Unicode sub-string
431 in a Null-terminated Unicode string.
433 This function scans the contents of the Null-terminated Unicode string
434 specified by String and returns the first occurrence of SearchString.
435 If SearchString is not found in String, then NULL is returned. If
436 the length of SearchString is zero, then String is
439 If String is NULL, then ASSERT().
440 If String is not aligned on a 16-bit boundary, then ASSERT().
441 If SearchString is NULL, then ASSERT().
442 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
444 If PcdMaximumUnicodeStringLength is not zero, and SearchString
445 or String contains more than PcdMaximumUnicodeStringLength Unicode
446 characters not including the Null-terminator, then ASSERT().
448 @param String Pointer to a Null-terminated Unicode string.
449 @param SearchString Pointer to a Null-terminated Unicode string to search for.
451 @retval NULL If the SearchString does not appear in String.
452 @return Pointer to the matching sub-string.
458 IN CONST CHAR16
*String
,
459 IN CONST CHAR16
*SearchString
462 CONST CHAR16
*FirstMatch
;
463 CONST CHAR16
*SearchStringTmp
;
466 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
467 // Length tests are performed inside StrLen().
469 ASSERT (StrSize (String
) != 0);
470 ASSERT (StrSize (SearchString
) != 0);
472 while (*String
!= '\0') {
473 SearchStringTmp
= SearchString
;
476 while ((*String
== *SearchStringTmp
)
477 && (*SearchStringTmp
!= '\0')
478 && (*String
!= '\0')) {
483 if ('\0' == *SearchStringTmp
) {
484 return (CHAR16
*) FirstMatch
;
487 if (SearchStringTmp
== SearchString
) {
489 // If no character from SearchString match,
490 // move the pointer to the String under search
501 Check if a Unicode character is a decimal character.
503 This internal function checks if a Unicode character is a
504 decimal character. The valid decimal character is from
508 @param Char The character to check against.
510 @retval TRUE If the Char is a decmial character.
511 @retval FALSE If the Char is not a decmial character.
516 InternalIsDecimalDigitCharacter (
520 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
524 Convert a Unicode character to upper case only if
525 it maps to a valid small-case ASCII character.
527 This internal function only deal with Unicode character
528 which maps to a valid small-case ASCII character, i.e.
529 L'a' to L'z'. For other Unicode character, the input character
530 is returned directly.
533 @param Char The character to convert.
535 @retval LowerCharacter If the Char is with range L'a' to L'z'.
536 @retval Unchanged Otherwise.
541 InternalCharToUpper (
545 if (Char
>= L
'a' && Char
<= L
'z') {
546 return (CHAR16
) (Char
- (L
'a' - L
'A'));
553 Convert a Unicode character to numerical value.
555 This internal function only deal with Unicode character
556 which maps to a valid hexadecimal ASII character, i.e.
557 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
558 Unicode character, the value returned does not make sense.
560 @param Char The character to convert.
562 @return The numerical value converted.
567 InternalHexCharToUintn (
571 if (InternalIsDecimalDigitCharacter (Char
)) {
575 return (UINTN
) (10 + InternalCharToUpper (Char
) - L
'A');
579 Check if a Unicode character is a hexadecimal character.
581 This internal function checks if a Unicode character is a
582 decimal character. The valid hexadecimal character is
583 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
586 @param Char The character to check against.
588 @retval TRUE If the Char is a hexadecmial character.
589 @retval FALSE If the Char is not a hexadecmial character.
594 InternalIsHexaDecimalDigitCharacter (
599 return (BOOLEAN
) (InternalIsDecimalDigitCharacter (Char
) ||
600 (Char
>= L
'A' && Char
<= L
'F') ||
601 (Char
>= L
'a' && Char
<= L
'f'));
605 Convert a Null-terminated Unicode decimal string to a value of
608 This function returns a value of type UINTN by interpreting the contents
609 of the Unicode string specified by String as a decimal number. The format
610 of the input Unicode string String is:
612 [spaces] [decimal digits].
614 The valid decimal digit character is in the range [0-9]. The
615 function will ignore the pad space, which includes spaces or
616 tab characters, before [decimal digits]. The running zero in the
617 beginning of [decimal digits] will be ignored. Then, the function
618 stops at the first character that is a not a valid decimal character
619 or a Null-terminator, whichever one comes first.
621 If String is NULL, then ASSERT().
622 If String is not aligned in a 16-bit boundary, then ASSERT().
623 If String has only pad spaces, then 0 is returned.
624 If String has no pad spaces or valid decimal digits,
626 If the number represented by String overflows according
627 to the range defined by UINTN, then ASSERT().
629 If PcdMaximumUnicodeStringLength is not zero, and String contains
630 more than PcdMaximumUnicodeStringLength Unicode characters not including
631 the Null-terminator, then ASSERT().
633 @param String Pointer to a Null-terminated Unicode string.
635 @return The value of type UINTN converted.
641 IN CONST CHAR16
*String
647 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
648 // Length tests are performed inside StrLen().
650 ASSERT (StrSize (String
) != 0);
653 // Ignore the pad spaces (space or tab)
655 while ((L
' ' ==*String
) || (L
'\t' == *String
)) {
660 // Ignore leading Zeros after the spaces
662 while (L
'0' == *String
) {
668 while (InternalIsDecimalDigitCharacter (*String
)) {
670 // If the number represented by String overflows according
671 // to the range defined by UINTN, then ASSERT().
673 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_10
) ||
674 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
675 (*String
- L
'0') <= REMAINDER_MAX_UINTN_DIVIDED_BY_10
)
678 Result
= Result
* 10 + (*String
- L
'0');
687 Convert a Null-terminated Unicode decimal string to a value of
690 This function returns a value of type UINT64 by interpreting the contents
691 of the Unicode string specified by String as a decimal number. The format
692 of the input Unicode string String is:
694 [spaces] [decimal digits].
696 The valid decimal digit character is in the range [0-9]. The
697 function will ignore the pad space, which includes spaces or
698 tab characters, before [decimal digits]. The running zero in the
699 beginning of [decimal digits] will be ignored. Then, the function
700 stops at the first character that is a not a valid decimal character
701 or a Null-terminator, whichever one comes first.
703 If String is NULL, then ASSERT().
704 If String is not aligned in a 16-bit boundary, then ASSERT().
705 If String has only pad spaces, then 0 is returned.
706 If String has no pad spaces or valid decimal digits,
708 If the number represented by String overflows according
709 to the range defined by UINT64, then ASSERT().
711 If PcdMaximumUnicodeStringLength is not zero, and String contains
712 more than PcdMaximumUnicodeStringLength Unicode characters not including
713 the Null-terminator, then ASSERT().
715 @param String Pointer to a Null-terminated Unicode string.
717 @return The value of type UINT64 converted.
723 IN CONST CHAR16
*String
729 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
730 // Length tests are performed inside StrLen().
732 ASSERT (StrSize (String
) != 0);
735 // Ignore the pad spaces (space or tab)
737 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
742 // Ignore leading Zeros after the spaces
744 while (L
'0' == *String
) {
750 while (InternalIsDecimalDigitCharacter (*String
)) {
752 // If the number represented by String overflows according
753 // to the range defined by UINTN, then ASSERT().
755 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_10
) ||
756 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
757 (*String
- L
'0') <= REMAINDER_MAX_UINT64_DIVIDED_BY_10
)
760 Result
= MultU64x32 (Result
, 10) + (*String
- L
'0');
768 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
770 This function returns a value of type UINTN by interpreting the contents
771 of the Unicode string specified by String as a hexadecimal number.
772 The format of the input Unicode string String is:
774 [spaces][zeros][x][hexadecimal digits].
776 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
777 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
778 If "x" appears in the input string, it must be prefixed with at least one 0.
779 The function will ignore the pad space, which includes spaces or tab characters,
780 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
781 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
782 first valid hexadecimal digit. Then, the function stops at the first character that is
783 a not a valid hexadecimal character or NULL, whichever one comes first.
785 If String is NULL, then ASSERT().
786 If String is not aligned in a 16-bit boundary, then ASSERT().
787 If String has only pad spaces, then zero is returned.
788 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
789 then zero is returned.
790 If the number represented by String overflows according to the range defined by
791 UINTN, then ASSERT().
793 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
794 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
797 @param String Pointer to a Null-terminated Unicode string.
799 @return The value of type UINTN converted.
805 IN CONST CHAR16
*String
811 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
812 // Length tests are performed inside StrLen().
814 ASSERT (StrSize (String
) != 0);
817 // Ignore the pad spaces (space or tab)
819 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
824 // Ignore leading Zeros after the spaces
826 while (L
'0' == *String
) {
830 if (InternalCharToUpper (*String
) == L
'X') {
831 ASSERT (L
'0' == *(String
- 1));
832 if (*(String
- 1) != L
'0') {
843 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
845 // If the Hex Number represented by String overflows according
846 // to the range defined by UINTN, then ASSERT().
848 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_16
) ||
849 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
850 (InternalHexCharToUintn (*String
) <= REMAINDER_MAX_UINTN_DIVIDED_BY_16
))
853 Result
= (Result
<< 4) + InternalHexCharToUintn (*String
);
862 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
864 This function returns a value of type UINT64 by interpreting the contents
865 of the Unicode string specified by String as a hexadecimal number.
866 The format of the input Unicode string String is
868 [spaces][zeros][x][hexadecimal digits].
870 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
871 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
872 If "x" appears in the input string, it must be prefixed with at least one 0.
873 The function will ignore the pad space, which includes spaces or tab characters,
874 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
875 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
876 first valid hexadecimal digit. Then, the function stops at the first character that is
877 a not a valid hexadecimal character or NULL, whichever one comes first.
879 If String is NULL, then ASSERT().
880 If String is not aligned in a 16-bit boundary, then ASSERT().
881 If String has only pad spaces, then zero is returned.
882 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
883 then zero is returned.
884 If the number represented by String overflows according to the range defined by
885 UINT64, then ASSERT().
887 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
888 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
891 @param String Pointer to a Null-terminated Unicode string.
893 @return The value of type UINT64 converted.
899 IN CONST CHAR16
*String
905 // ASSERT String is less long than PcdMaximumUnicodeStringLength.
906 // Length tests are performed inside StrLen().
908 ASSERT (StrSize (String
) != 0);
911 // Ignore the pad spaces (space or tab)
913 while ((L
' ' == *String
) || (L
'\t' == *String
)) {
918 // Ignore leading Zeros after the spaces
920 while (L
'0' == *String
) {
924 if (InternalCharToUpper (*String
) == L
'X') {
925 ASSERT (L
'0' == *(String
- 1));
926 if (*(String
- 1) != L
'0') {
937 while (InternalIsHexaDecimalDigitCharacter (*String
)) {
939 // If the Hex Number represented by String overflows according
940 // to the range defined by UINTN, then ASSERT().
942 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_16
)||
943 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
944 (InternalHexCharToUintn (*String
) <= REMAINDER_MAX_UINT64_DIVIDED_BY_16
))
947 Result
= LShiftU64 (Result
, 4);
948 Result
= Result
+ InternalHexCharToUintn (*String
);
956 Check if a ASCII character is a decimal character.
958 This internal function checks if a Unicode character is a
959 decimal character. The valid decimal character is from
962 @param Char The character to check against.
964 @retval TRUE If the Char is a decmial character.
965 @retval FALSE If the Char is not a decmial character.
970 InternalAsciiIsDecimalDigitCharacter (
974 return (BOOLEAN
) (Char
>= '0' && Char
<= '9');
978 Check if a ASCII character is a hexadecimal character.
980 This internal function checks if a ASCII character is a
981 decimal character. The valid hexadecimal character is
982 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
985 @param Char The character to check against.
987 @retval TRUE If the Char is a hexadecmial character.
988 @retval FALSE If the Char is not a hexadecmial character.
993 InternalAsciiIsHexaDecimalDigitCharacter (
998 return (BOOLEAN
) (InternalAsciiIsDecimalDigitCharacter (Char
) ||
999 (Char
>= 'A' && Char
<= 'F') ||
1000 (Char
>= 'a' && Char
<= 'f'));
1004 Convert a Null-terminated Unicode string to a Null-terminated
1005 ASCII string and returns the ASCII string.
1007 This function converts the content of the Unicode string Source
1008 to the ASCII string Destination by copying the lower 8 bits of
1009 each Unicode character. It returns Destination. The function terminates
1010 the ASCII string Destination by appending a Null-terminator character
1011 at the end. The caller is responsible to make sure Destination points
1012 to a buffer with size equal or greater than (StrLen (Source) + 1) in bytes.
1014 If Destination is NULL, then ASSERT().
1015 If Source is NULL, then ASSERT().
1016 If Source is not aligned on a 16-bit boundary, then ASSERT().
1017 If Source and Destination overlap, then ASSERT().
1019 If any Unicode characters in Source contain non-zero value in
1020 the upper 8 bits, then ASSERT().
1022 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1023 more than PcdMaximumUnicodeStringLength Unicode characters not including
1024 the Null-terminator, then ASSERT().
1026 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1027 than PcdMaximumAsciiStringLength Unicode characters not including the
1028 Null-terminator, then ASSERT().
1030 @param Source Pointer to a Null-terminated Unicode string.
1031 @param Destination Pointer to a Null-terminated ASCII string.
1033 @return Destination pointing to the converted ASCII string.
1038 UnicodeStrToAsciiStr (
1039 IN CONST CHAR16
*Source
,
1040 OUT CHAR8
*Destination
1045 ASSERT (Destination
!= NULL
);
1048 // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
1049 // Length tests are performed inside StrLen().
1051 ASSERT (StrSize (Source
) != 0);
1054 // Source and Destination should not overlap
1056 ASSERT ((UINTN
) ((CHAR16
*) Destination
- Source
) > StrLen (Source
));
1057 ASSERT ((UINTN
) ((CHAR8
*) Source
- Destination
) > StrLen (Source
));
1060 ReturnValue
= Destination
;
1061 while (*Source
!= '\0') {
1063 // If any Unicode characters in Source contain
1064 // non-zero value in the upper 8 bits, then ASSERT().
1066 ASSERT (*Source
< 0x100);
1067 *(Destination
++) = (CHAR8
) *(Source
++);
1070 *Destination
= '\0';
1073 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
1074 // Length tests are performed inside AsciiStrLen().
1076 ASSERT (AsciiStrSize (ReturnValue
) != 0);
1083 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1084 string and returns the new ASCII string.
1086 This function copies the contents of the ASCII string Source to the ASCII
1087 string Destination, and returns Destination. If Source and Destination
1088 overlap, then the results are undefined.
1090 If Destination is NULL, then ASSERT().
1091 If Source is NULL, then ASSERT().
1092 If Source and Destination overlap, then ASSERT().
1093 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1094 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1097 @param Destination Pointer to a Null-terminated ASCII string.
1098 @param Source Pointer to a Null-terminated ASCII string.
1100 @return Destination pointing to the copied string.
1106 OUT CHAR8
*Destination
,
1107 IN CONST CHAR8
*Source
1113 // Destination cannot be NULL
1115 ASSERT (Destination
!= NULL
);
1118 // Destination and source cannot overlap
1120 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1121 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
1123 ReturnValue
= Destination
;
1124 while (*Source
!= 0) {
1125 *(Destination
++) = *(Source
++);
1132 Copies one Null-terminated ASCII string with a maximum length to another
1133 Null-terminated ASCII string with a maximum length and returns the new ASCII
1136 This function copies the contents of the ASCII string Source to the ASCII
1137 string Destination, and returns Destination. At most, Length ASCII characters
1138 are copied from Source to Destination. If Length is 0, then Destination is
1139 returned unmodified. If Length is greater that the number of ASCII characters
1140 in Source, then Destination is padded with Null ASCII characters. If Source
1141 and Destination overlap, then the results are undefined.
1143 If Destination is NULL, then ASSERT().
1144 If Source is NULL, then ASSERT().
1145 If Source and Destination overlap, then ASSERT().
1146 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1147 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1150 @param Destination Pointer to a Null-terminated ASCII string.
1151 @param Source Pointer to a Null-terminated ASCII string.
1152 @param Length Maximum number of ASCII characters to copy.
1154 @return Destination pointing to the copied string.
1160 OUT CHAR8
*Destination
,
1161 IN CONST CHAR8
*Source
,
1172 // Destination cannot be NULL
1174 ASSERT (Destination
!= NULL
);
1177 // Destination and source cannot overlap
1179 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1180 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
1182 ReturnValue
= Destination
;
1184 while (*Source
!= 0 && Length
> 0) {
1185 *(Destination
++) = *(Source
++);
1189 ZeroMem (Destination
, Length
* sizeof (*Destination
));
1194 Returns the length of a Null-terminated ASCII string.
1196 This function returns the number of ASCII characters in the Null-terminated
1197 ASCII string specified by String.
1199 If String is NULL, then ASSERT().
1200 If PcdMaximumAsciiStringLength is not zero and String contains more than
1201 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1204 @param String Pointer to a Null-terminated ASCII string.
1206 @return The length of String.
1212 IN CONST CHAR8
*String
1217 ASSERT (String
!= NULL
);
1219 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
1221 // If PcdMaximumUnicodeStringLength is not zero,
1222 // length should not more than PcdMaximumUnicodeStringLength
1224 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1225 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
1232 Returns the size of a Null-terminated ASCII string in bytes, including the
1235 This function returns the size, in bytes, of the Null-terminated ASCII string
1236 specified by String.
1238 If String is NULL, then ASSERT().
1239 If PcdMaximumAsciiStringLength is not zero and String contains more than
1240 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1243 @param String Pointer to a Null-terminated ASCII string.
1245 @return The size of String.
1251 IN CONST CHAR8
*String
1254 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
1258 Compares two Null-terminated ASCII strings, and returns the difference
1259 between the first mismatched ASCII characters.
1261 This function compares the Null-terminated ASCII string FirstString to the
1262 Null-terminated ASCII string SecondString. If FirstString is identical to
1263 SecondString, then 0 is returned. Otherwise, the value returned is the first
1264 mismatched ASCII character in SecondString subtracted from the first
1265 mismatched ASCII character in FirstString.
1267 If FirstString is NULL, then ASSERT().
1268 If SecondString is NULL, then ASSERT().
1269 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1270 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1272 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1273 than PcdMaximumAsciiStringLength ASCII characters not including the
1274 Null-terminator, then ASSERT().
1276 @param FirstString Pointer to a Null-terminated ASCII string.
1277 @param SecondString Pointer to a Null-terminated ASCII string.
1279 @retval 0 FirstString is identical to SecondString.
1280 @return The first mismatched ASCII character in SecondString subtracted
1281 from the first mismatched ASCII character in FirstString.
1287 IN CONST CHAR8
*FirstString
,
1288 IN CONST CHAR8
*SecondString
1292 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1294 ASSERT (AsciiStrSize (FirstString
));
1295 ASSERT (AsciiStrSize (SecondString
));
1297 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
1302 return *FirstString
- *SecondString
;
1306 Converts a lowercase Ascii character to upper one.
1308 If Chr is lowercase Ascii character, then converts it to upper one.
1310 If Value >= 0xA0, then ASSERT().
1311 If (Value & 0x0F) >= 0x0A, then ASSERT().
1313 @param Chr one Ascii character
1315 @return The uppercase value of Ascii character
1324 return (UINT8
) ((Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
);
1328 Convert a ASCII character to numerical value.
1330 This internal function only deal with Unicode character
1331 which maps to a valid hexadecimal ASII character, i.e.
1332 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1333 ASCII character, the value returned does not make sense.
1335 @param Char The character to convert.
1337 @return The numerical value converted.
1342 InternalAsciiHexCharToUintn (
1346 if (InternalIsDecimalDigitCharacter (Char
)) {
1350 return (UINTN
) (10 + AsciiToUpper (Char
) - 'A');
1355 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1356 and returns the difference between the first mismatched ASCII characters.
1358 This function performs a case insensitive comparison of the Null-terminated
1359 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1360 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1361 value returned is the first mismatched lower case ASCII character in
1362 SecondString subtracted from the first mismatched lower case ASCII character
1365 If FirstString is NULL, then ASSERT().
1366 If SecondString is NULL, then ASSERT().
1367 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1368 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1370 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1371 than PcdMaximumAsciiStringLength ASCII characters not including the
1372 Null-terminator, then ASSERT().
1374 @param FirstString Pointer to a Null-terminated ASCII string.
1375 @param SecondString Pointer to a Null-terminated ASCII string.
1377 @retval 0 FirstString is identical to SecondString using case insensitive
1379 @return The first mismatched lower case ASCII character in SecondString subtracted
1380 from the first mismatched lower case ASCII character in FirstString.
1386 IN CONST CHAR8
*FirstString
,
1387 IN CONST CHAR8
*SecondString
1390 CHAR8 UpperFirstString
;
1391 CHAR8 UpperSecondString
;
1394 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1396 ASSERT (AsciiStrSize (FirstString
));
1397 ASSERT (AsciiStrSize (SecondString
));
1399 UpperFirstString
= AsciiToUpper (*FirstString
);
1400 UpperSecondString
= AsciiToUpper (*SecondString
);
1401 while ((*FirstString
!= '\0') && (UpperFirstString
== UpperSecondString
)) {
1404 UpperFirstString
= AsciiToUpper (*FirstString
);
1405 UpperSecondString
= AsciiToUpper (*SecondString
);
1408 return UpperFirstString
- UpperSecondString
;
1412 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1413 the difference between the first mismatched ASCII characters.
1415 This function compares the Null-terminated ASCII string FirstString to the
1416 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1417 will be compared. If Length is 0, then 0 is returned. If FirstString is
1418 identical to SecondString, then 0 is returned. Otherwise, the value returned
1419 is the first mismatched ASCII character in SecondString subtracted from the
1420 first mismatched ASCII character in FirstString.
1422 If FirstString is NULL, then ASSERT().
1423 If SecondString is NULL, then ASSERT().
1424 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1425 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1427 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
1428 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1431 @param FirstString Pointer to a Null-terminated ASCII string.
1432 @param SecondString Pointer to a Null-terminated ASCII string.
1433 @param Length Maximum number of ASCII characters to compare.
1435 @retval 0 FirstString is identical to SecondString.
1436 @return The first mismatched ASCII character in SecondString subtracted from the
1437 first mismatched ASCII character in FirstString.
1443 IN CONST CHAR8
*FirstString
,
1444 IN CONST CHAR8
*SecondString
,
1453 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1455 ASSERT (AsciiStrSize (FirstString
));
1456 ASSERT (AsciiStrSize (SecondString
));
1458 while ((*FirstString
!= '\0') &&
1459 (*FirstString
== *SecondString
) &&
1465 return *FirstString
- *SecondString
;
1469 Concatenates one Null-terminated ASCII string to another Null-terminated
1470 ASCII string, and returns the concatenated ASCII string.
1472 This function concatenates two Null-terminated ASCII strings. The contents of
1473 Null-terminated ASCII string Source are concatenated to the end of Null-
1474 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1477 If Destination is NULL, then ASSERT().
1478 If Source is NULL, then ASSERT().
1479 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1480 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1482 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1483 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1485 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1486 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1487 ASCII characters, then ASSERT().
1489 @param Destination Pointer to a Null-terminated ASCII string.
1490 @param Source Pointer to a Null-terminated ASCII string.
1492 @return Destination pointing to the concatenated ASCII string.
1498 IN OUT CHAR8
*Destination
,
1499 IN CONST CHAR8
*Source
1502 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
1505 // Size of the resulting string should never be zero.
1506 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1508 ASSERT (AsciiStrSize (Destination
) != 0);
1513 Concatenates one Null-terminated ASCII string with a maximum length to the
1514 end of another Null-terminated ASCII string, and returns the concatenated
1517 This function concatenates two Null-terminated ASCII strings. The contents
1518 of Null-terminated ASCII string Source are concatenated to the end of Null-
1519 terminated ASCII string Destination, and Destination is returned. At most,
1520 Length ASCII characters are concatenated from Source to the end of
1521 Destination, and Destination is always Null-terminated. If Length is 0, then
1522 Destination is returned unmodified. If Source and Destination overlap, then
1523 the results are undefined.
1525 If Destination is NULL, then ASSERT().
1526 If Source is NULL, then ASSERT().
1527 If Source and Destination overlap, then ASSERT().
1528 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1529 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1531 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1532 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1534 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1535 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1536 ASCII characters not including the Null-terminator, then ASSERT().
1538 @param Destination Pointer to a Null-terminated ASCII string.
1539 @param Source Pointer to a Null-terminated ASCII string.
1540 @param Length Maximum number of ASCII characters to concatenate from
1543 @return Destination pointing to the concatenated ASCII string.
1549 IN OUT CHAR8
*Destination
,
1550 IN CONST CHAR8
*Source
,
1554 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
1557 // Size of the resulting string should never be zero.
1558 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1560 ASSERT (AsciiStrSize (Destination
) != 0);
1565 Returns the first occurance of a Null-terminated ASCII sub-string
1566 in a Null-terminated ASCII string.
1568 This function scans the contents of the ASCII string specified by String
1569 and returns the first occurrence of SearchString. If SearchString is not
1570 found in String, then NULL is returned. If the length of SearchString is zero,
1571 then String is returned.
1573 If String is NULL, then ASSERT().
1574 If SearchString is NULL, then ASSERT().
1576 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1577 String contains more than PcdMaximumAsciiStringLength Unicode characters
1578 not including the Null-terminator, then ASSERT().
1580 @param String Pointer to a Null-terminated ASCII string.
1581 @param SearchString Pointer to a Null-terminated ASCII string to search for.
1583 @retval NULL If the SearchString does not appear in String.
1584 @return Pointer to the matching sub-string.
1590 IN CONST CHAR8
*String
,
1591 IN CONST CHAR8
*SearchString
1594 CONST CHAR8
*FirstMatch
;
1595 CONST CHAR8
*SearchStringTmp
;
1598 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1600 ASSERT (AsciiStrSize (String
) != 0);
1601 ASSERT (AsciiStrSize (SearchString
) != 0);
1603 while (*String
!= '\0') {
1604 SearchStringTmp
= SearchString
;
1605 FirstMatch
= String
;
1607 while ((*String
== *SearchStringTmp
)
1608 && (*SearchStringTmp
!= '\0')
1609 && (*String
!= '\0')) {
1614 if (*SearchStringTmp
== '\0') {
1615 return (CHAR8
*) FirstMatch
;
1618 if (SearchStringTmp
== SearchString
) {
1620 // If no character from SearchString match,
1621 // move the pointer to the String under search
1622 // by one character.
1633 Convert a Null-terminated ASCII decimal string to a value of type
1636 This function returns a value of type UINTN by interpreting the contents
1637 of the ASCII string String as a decimal number. The format of the input
1638 ASCII string String is:
1640 [spaces] [decimal digits].
1642 The valid decimal digit character is in the range [0-9]. The function will
1643 ignore the pad space, which includes spaces or tab characters, before the digits.
1644 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1645 function stops at the first character that is a not a valid decimal character or
1646 Null-terminator, whichever on comes first.
1648 If String has only pad spaces, then 0 is returned.
1649 If String has no pad spaces or valid decimal digits, then 0 is returned.
1650 If the number represented by String overflows according to the range defined by
1651 UINTN, then ASSERT().
1652 If String is NULL, then ASSERT().
1653 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1654 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1657 @param String Pointer to a Null-terminated ASCII string.
1659 @return The value of type UINTN converted.
1664 AsciiStrDecimalToUintn (
1665 IN CONST CHAR8
*String
1671 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1673 ASSERT (AsciiStrSize (String
) != 0);
1676 // Ignore the pad spaces (space or tab)
1678 while ((' ' == *String
) || ('\t' == *String
)) {
1683 // Ignore leading Zeros after the spaces
1685 while ('0' == *String
) {
1691 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1693 // If the number represented by String overflows according
1694 // to the range defined by UINTN, then ASSERT().
1696 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_10
) ||
1697 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_10
== Result
) &&
1698 (*String
- '0') <= REMAINDER_MAX_UINTN_DIVIDED_BY_10
)
1701 Result
= Result
* 10 + (*String
- '0');
1710 Convert a Null-terminated ASCII decimal string to a value of type
1713 This function returns a value of type UINT64 by interpreting the contents
1714 of the ASCII string String as a decimal number. The format of the input
1715 ASCII string String is:
1717 [spaces] [decimal digits].
1719 The valid decimal digit character is in the range [0-9]. The function will
1720 ignore the pad space, which includes spaces or tab characters, before the digits.
1721 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1722 function stops at the first character that is a not a valid decimal character or
1723 Null-terminator, whichever on comes first.
1725 If String has only pad spaces, then 0 is returned.
1726 If String has no pad spaces or valid decimal digits, then 0 is returned.
1727 If the number represented by String overflows according to the range defined by
1728 UINT64, then ASSERT().
1729 If String is NULL, then ASSERT().
1730 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1731 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1734 @param String Pointer to a Null-terminated ASCII string.
1736 @return The value of type UINT64 converted.
1741 AsciiStrDecimalToUint64 (
1742 IN CONST CHAR8
*String
1748 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1750 ASSERT (AsciiStrSize (String
) != 0);
1753 // Ignore the pad spaces (space or tab)
1755 while ((' ' == *String
) || ('\t' == *String
)) {
1760 // Ignore leading Zeros after the spaces
1762 while ('0' == *String
) {
1768 while (InternalAsciiIsDecimalDigitCharacter (*String
)) {
1770 // If the number represented by String overflows according
1771 // to the range defined by UINTN, then ASSERT().
1773 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_10
) ||
1774 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_10
== Result
) &&
1775 (*String
- '0') <= REMAINDER_MAX_UINT64_DIVIDED_BY_10
)
1778 Result
= MultU64x32 (Result
, 10) + (*String
- '0');
1786 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1788 This function returns a value of type UINTN by interpreting the contents of
1789 the ASCII string String as a hexadecimal number. The format of the input ASCII
1792 [spaces][zeros][x][hexadecimal digits].
1794 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1795 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1796 appears in the input string, it must be prefixed with at least one 0. The function
1797 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1798 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1799 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1800 digit. Then, the function stops at the first character that is a not a valid
1801 hexadecimal character or Null-terminator, whichever on comes first.
1803 If String has only pad spaces, then 0 is returned.
1804 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1807 If the number represented by String overflows according to the range defined by UINTN,
1809 If String is NULL, then ASSERT().
1810 If PcdMaximumAsciiStringLength is not zero,
1811 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1812 the Null-terminator, then ASSERT().
1814 @param String Pointer to a Null-terminated ASCII string.
1816 @return The value of type UINTN converted.
1821 AsciiStrHexToUintn (
1822 IN CONST CHAR8
*String
1828 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1830 ASSERT (AsciiStrSize (String
) != 0);
1833 // Ignore the pad spaces (space or tab)
1835 while ((' ' == *String
) || ('\t' == *String
)) {
1840 // Ignore leading Zeros after the spaces
1842 while ('0' == *String
) {
1846 if (AsciiToUpper (*String
) == 'X') {
1847 ASSERT ('0' == *(String
- 1));
1848 if (*(String
- 1) != '0') {
1859 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1861 // If the Hex Number represented by String overflows according
1862 // to the range defined by UINTN, then ASSERT().
1864 ASSERT ((Result
< QUOTIENT_MAX_UINTN_DIVIDED_BY_16
) ||
1865 ((QUOTIENT_MAX_UINTN_DIVIDED_BY_16
== Result
) &&
1866 (InternalAsciiHexCharToUintn (*String
) <= REMAINDER_MAX_UINTN_DIVIDED_BY_16
))
1869 Result
= (Result
<< 4) + InternalAsciiHexCharToUintn (*String
);
1878 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1880 This function returns a value of type UINT64 by interpreting the contents of
1881 the ASCII string String as a hexadecimal number. The format of the input ASCII
1884 [spaces][zeros][x][hexadecimal digits].
1886 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1887 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1888 appears in the input string, it must be prefixed with at least one 0. The function
1889 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1890 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1891 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1892 digit. Then, the function stops at the first character that is a not a valid
1893 hexadecimal character or Null-terminator, whichever on comes first.
1895 If String has only pad spaces, then 0 is returned.
1896 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1899 If the number represented by String overflows according to the range defined by UINT64,
1901 If String is NULL, then ASSERT().
1902 If PcdMaximumAsciiStringLength is not zero,
1903 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1904 the Null-terminator, then ASSERT().
1906 @param String Pointer to a Null-terminated ASCII string.
1908 @return The value of type UINT64 converted.
1913 AsciiStrHexToUint64 (
1914 IN CONST CHAR8
*String
1920 // ASSERT Strings is less long than PcdMaximumAsciiStringLength
1922 ASSERT (AsciiStrSize (String
) != 0);
1925 // Ignore the pad spaces (space or tab) and leading Zeros
1928 // Ignore the pad spaces (space or tab)
1930 while ((' ' == *String
) || ('\t' == *String
)) {
1935 // Ignore leading Zeros after the spaces
1937 while ('0' == *String
) {
1941 if (AsciiToUpper (*String
) == 'X') {
1942 ASSERT ('0' == *(String
- 1));
1943 if (*(String
- 1) != '0') {
1954 while (InternalAsciiIsHexaDecimalDigitCharacter (*String
)) {
1956 // If the Hex Number represented by String overflows according
1957 // to the range defined by UINTN, then ASSERT().
1959 ASSERT ((Result
< QUOTIENT_MAX_UINT64_DIVIDED_BY_16
) ||
1960 ((QUOTIENT_MAX_UINT64_DIVIDED_BY_16
== Result
) &&
1961 (InternalAsciiHexCharToUintn (*String
) <= REMAINDER_MAX_UINT64_DIVIDED_BY_16
))
1964 Result
= LShiftU64 (Result
, 4);
1965 Result
= Result
+ InternalAsciiHexCharToUintn (*String
);
1974 Convert one Null-terminated ASCII string to a Null-terminated
1975 Unicode string and returns the Unicode string.
1977 This function converts the contents of the ASCII string Source to the Unicode
1978 string Destination, and returns Destination. The function terminates the
1979 Unicode string Destination by appending a Null-terminator character at the end.
1980 The caller is responsible to make sure Destination points to a buffer with size
1981 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1983 If Destination is NULL, then ASSERT().
1984 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1985 If Source is NULL, then ASSERT().
1986 If Source and Destination overlap, then ASSERT().
1987 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1988 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1990 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1991 PcdMaximumUnicodeStringLength ASCII characters not including the
1992 Null-terminator, then ASSERT().
1994 @param Source Pointer to a Null-terminated ASCII string.
1995 @param Destination Pointer to a Null-terminated Unicode string.
1997 @return Destination pointing to the converted Unicode string.
2002 AsciiStrToUnicodeStr (
2003 IN CONST CHAR8
*Source
,
2004 OUT CHAR16
*Destination
2007 CHAR16
*ReturnValue
;
2009 ASSERT (Destination
!= NULL
);
2012 // ASSERT Source is less long than PcdMaximumAsciiStringLength
2014 ASSERT (AsciiStrSize (Source
) != 0);
2017 // Source and Destination should not overlap
2019 ASSERT ((UINTN
) ((CHAR8
*) Destination
- Source
) > AsciiStrLen (Source
));
2020 ASSERT ((UINTN
) (Source
- (CHAR8
*) Destination
) > (AsciiStrLen (Source
) * sizeof (CHAR16
)));
2023 ReturnValue
= Destination
;
2024 while (*Source
!= '\0') {
2025 *(Destination
++) = (CHAR16
) *(Source
++);
2028 // End the Destination with a NULL.
2030 *Destination
= '\0';
2033 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
2035 ASSERT (StrSize (ReturnValue
) != 0);
2041 Converts an 8-bit value to an 8-bit BCD value.
2043 Converts the 8-bit value specified by Value to BCD. The BCD value is
2046 If Value >= 100, then ASSERT().
2048 @param Value The 8-bit value to convert to BCD. Range 0..99.
2050 @return The BCD value converted.
2059 ASSERT (Value
< 100);
2060 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2064 Converts an 8-bit BCD value to an 8-bit value.
2066 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2069 If Value >= 0xA0, then ASSERT().
2070 If (Value & 0x0F) >= 0x0A, then ASSERT().
2072 @param Value The 8-bit BCD value to convert to an 8-bit value.
2074 @return The 8-bit decimal value converted.
2083 ASSERT (Value
< 0xa0);
2084 ASSERT ((Value
& 0xf) < 0xa);
2085 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));
2090 Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character.
2092 This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal
2093 character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A'
2096 The upper nibble in the input byte will be masked off.
2098 @param Nibble The nibble which is in the low 4 bits of the input byte.
2100 @return The Unicode hexadecimal character.
2109 if (Nibble
<= 0x9) {
2110 return (CHAR16
)(Nibble
+ L
'0');
2113 return (CHAR16
)(Nibble
- 0xA + L
'A');
2117 Convert binary buffer to a Unicode String in a specified sequence.
2119 This function converts bytes in the memory block pointed by Buffer to a Unicode String Str.
2120 Each byte will be represented by two Unicode characters. For example, byte 0xA1 will
2121 be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character
2122 for the Most Significant Nibble will be put before the Unicode Character for the Least Significant
2123 Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1".
2124 For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the
2125 the last character in the output string. The one next to first byte will be put into the
2126 character before the last character. This rules applies to the rest of the bytes. The Unicode
2127 character by the last byte will be put into the first character in the output string. For example,
2128 the input buffer for a 64-bits unsigned integrer 0x12345678abcdef1234 will be converted to
2129 a Unicode string equal to L"12345678abcdef1234".
2131 @param String Pointer to the buffer allocated for the convertion.
2132 @param StringLen On input: Pointer to length in bytes of buffer to hold the Unicode string.
2133 On output:If return EFI_SUCCESS, pointer to length of Unicode string converted.
2134 If return EFI_BUFFER_TOO_SMALL, pointer to length of string buffer desired.
2135 @param Buffer The pointer to a input buffer.
2136 @param BufferSizeInBytes Lenth in bytes of the input buffer.
2138 @retval EFI_SUCCESS The convertion is successfull. All bytes in Buffer has been convert to the corresponding
2139 Unicode character and placed into the right place in String.
2140 @retval EFI_BUFFER_TOO_SMALL StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to
2141 complete the convertion.
2146 IN OUT CHAR16
*String
,
2147 IN OUT UINTN
*StringLen
,
2148 IN CONST UINT8
*Buffer
,
2149 IN UINTN BufferSizeInBytes
2157 // Make sure string is either passed or allocate enough.
2158 // It takes 2 Unicode characters (4 bytes) to represent 1 byte of the binary buffer.
2159 // Plus the Unicode termination character.
2161 StrLen
= BufferSizeInBytes
* 2;
2162 if (StrLen
> ((*StringLen
) - 1)) {
2163 *StringLen
= StrLen
+ 1;
2164 return RETURN_BUFFER_TOO_SMALL
;
2167 *StringLen
= StrLen
+ 1;
2171 String
[StrLen
] = L
'\0';
2173 for (Idx
= 0; Idx
< BufferSizeInBytes
; Idx
++) {
2176 String
[StrLen
- 1 - Idx
* 2] = NibbleToHexChar (Byte
);
2177 String
[StrLen
- 2 - Idx
* 2] = NibbleToHexChar ((UINT8
)(Byte
>> 4));
2180 return RETURN_SUCCESS
;
2185 Convert a Unicode string consisting of hexadecimal characters to a output byte buffer.
2187 This function converts a Unicode string consisting of characters in the range of Hexadecimal
2188 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
2189 at the first non-hexadecimal character or the NULL character. The convertion process can be
2190 simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be
2191 converted into one byte. The first Unicode character represents the Most Significant Nibble and the
2192 second Unicode character represents the Least Significant Nibble in the output byte.
2193 The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode
2194 characters represent the the byte preceding the last byte. This rule applies to the rest pairs of bytes.
2195 The last pair represent the first byte in the output buffer.
2197 For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes
2198 (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12".
2200 If String has N valid hexadecimal characters for conversion, the caller must make sure Buffer is at least
2201 N/2 (if N is even) or (N+1)/2 (if N if odd) bytes.
2203 @param Buffer The output buffer allocated by the caller.
2204 @param BufferSizeInBytes On input, the size in bytes of Buffer. On output, it is updated to
2205 contain the size of the Buffer which is actually used for the converstion.
2206 For Unicode string with 2*N hexadecimal characters (not including the
2207 tailing NULL character), N bytes of Buffer will be used for the output.
2208 @param String The input hexadecimal string.
2209 @param ConvertedStrLen The number of hexadecimal characters used to produce content in output
2212 @retval RETURN_BUFFER_TOO_SMALL The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes
2213 will be updated to the size required for the converstion.
2214 @retval RETURN_SUCCESS The convertion is successful or the first Unicode character from String
2215 is hexadecimal. If ConvertedStrLen is not NULL, it is updated
2216 to the number of hexadecimal character used for the converstion.
2222 IN OUT UINTN
*BufferSizeInBytes
,
2223 IN CONST CHAR16
*String
,
2224 OUT UINTN
*ConvertedStrLen OPTIONAL
2234 // Find out how many hex characters the string has.
2236 for (Idx
= 0, HexCnt
= 0; IsHexDigit (&Digit
, String
[Idx
]); Idx
++, HexCnt
++);
2239 *ConvertedStrLen
= 0;
2240 return RETURN_SUCCESS
;
2243 // Two Unicode characters make up 1 buffer byte. Round up.
2245 BufferLength
= (HexCnt
+ 1) / 2;
2248 // Test if buffer is passed enough.
2250 if (BufferLength
> (*BufferSizeInBytes
)) {
2251 *BufferSizeInBytes
= BufferLength
;
2252 return RETURN_BUFFER_TOO_SMALL
;
2255 *BufferSizeInBytes
= BufferLength
;
2257 for (Idx
= 0; Idx
< HexCnt
; Idx
++) {
2259 IsHexDigit (&Digit
, String
[HexCnt
- 1 - Idx
]);
2262 // For odd charaters, write the lower nibble for each buffer byte,
2263 // and for even characters, the upper nibble.
2265 if ((Idx
& 1) == 0) {
2268 Byte
= Buffer
[Idx
/ 2];
2270 Byte
= (UINT8
) (Byte
| Digit
<< 4);
2273 Buffer
[Idx
/ 2] = Byte
;
2276 if (ConvertedStrLen
!= NULL
) {
2277 *ConvertedStrLen
= HexCnt
;
2280 return RETURN_SUCCESS
;
2285 Test if a Unicode character is a hexadecimal digit. If true, the input
2286 Unicode character is converted to a byte.
2288 This function tests if a Unicode character is a hexadecimal digit. If true, the input
2289 Unicode character is converted to a byte. For example, Unicode character
2290 L'A' will be converted to 0x0A.
2292 If Digit is NULL, then ASSERT().
2294 @param Digit The output hexadecimal digit.
2295 @param Char The input Unicode character.
2297 @retval TRUE Char is in the range of Hexadecimal number. Digit is updated
2298 to the byte value of the number.
2299 @retval FALSE Char is not in the range of Hexadecimal number. Digit is keep
2309 ASSERT (Digit
!= NULL
);
2311 if ((Char
>= L
'0') && (Char
<= L
'9')) {
2312 *Digit
= (UINT8
) (Char
- L
'0');
2316 if ((Char
>= L
'A') && (Char
<= L
'F')) {
2317 *Digit
= (UINT8
) (Char
- L
'A' + 0x0A);
2321 if ((Char
>= L
'a') && (Char
<= L
'f')) {
2322 *Digit
= (UINT8
) (Char
- L
'a' + 0x0A);