2 Unicode and ASCII string primitives.
4 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #include "BaseLibInternals.h"
11 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
14 [ATTENTION] This function will be deprecated for security reason.
16 Copies one Null-terminated Unicode string to another Null-terminated Unicode
17 string and returns the new Unicode string.
19 This function copies the contents of the Unicode string Source to the Unicode
20 string Destination, and returns Destination. If Source and Destination
21 overlap, then the results are undefined.
23 If Destination is NULL, then ASSERT().
24 If Destination is not aligned on a 16-bit boundary, then ASSERT().
25 If Source is NULL, then ASSERT().
26 If Source is not aligned on a 16-bit boundary, then ASSERT().
27 If Source and Destination overlap, then ASSERT().
28 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
29 PcdMaximumUnicodeStringLength Unicode characters, not including the
30 Null-terminator, then ASSERT().
32 @param Destination A pointer to a Null-terminated Unicode string.
33 @param Source A pointer to a Null-terminated Unicode string.
41 OUT CHAR16
*Destination
,
42 IN CONST CHAR16
*Source
48 // Destination cannot be NULL
50 ASSERT (Destination
!= NULL
);
51 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
54 // Destination and source cannot overlap
56 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
57 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
59 ReturnValue
= Destination
;
60 while (*Source
!= 0) {
61 *(Destination
++) = *(Source
++);
68 [ATTENTION] This function will be deprecated for security reason.
70 Copies up to a specified length from one Null-terminated Unicode string to
71 another Null-terminated Unicode string and returns the new Unicode string.
73 This function copies the contents of the Unicode string Source to the Unicode
74 string Destination, and returns Destination. At most, Length Unicode
75 characters are copied from Source to Destination. If Length is 0, then
76 Destination is returned unmodified. If Length is greater that the number of
77 Unicode characters in Source, then Destination is padded with Null Unicode
78 characters. If Source and Destination overlap, then the results are
81 If Length > 0 and Destination is NULL, then ASSERT().
82 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
83 If Length > 0 and Source is NULL, then ASSERT().
84 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
85 If Source and Destination overlap, then ASSERT().
86 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
87 PcdMaximumUnicodeStringLength, then ASSERT().
88 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
89 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
92 @param Destination A pointer to a Null-terminated Unicode string.
93 @param Source A pointer to a Null-terminated Unicode string.
94 @param Length The maximum number of Unicode characters to copy.
102 OUT CHAR16
*Destination
,
103 IN CONST CHAR16
*Source
,
114 // Destination cannot be NULL if Length is not zero
116 ASSERT (Destination
!= NULL
);
117 ASSERT (((UINTN
) Destination
& BIT0
) == 0);
120 // Destination and source cannot overlap
122 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
123 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
125 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
126 ASSERT (Length
<= PcdGet32 (PcdMaximumUnicodeStringLength
));
129 ReturnValue
= Destination
;
131 while ((*Source
!= L
'\0') && (Length
> 0)) {
132 *(Destination
++) = *(Source
++);
136 ZeroMem (Destination
, Length
* sizeof (*Destination
));
142 Returns the length of a Null-terminated Unicode string.
144 This function returns the number of Unicode characters in the Null-terminated
145 Unicode string specified by String.
147 If String is NULL, then ASSERT().
148 If String is not aligned on a 16-bit boundary, then ASSERT().
149 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
150 PcdMaximumUnicodeStringLength Unicode characters, not including the
151 Null-terminator, then ASSERT().
153 @param String A pointer to a Null-terminated Unicode string.
155 @return The length of String.
161 IN CONST CHAR16
*String
166 ASSERT (String
!= NULL
);
167 ASSERT (((UINTN
) String
& BIT0
) == 0);
169 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
171 // If PcdMaximumUnicodeStringLength is not zero,
172 // length should not more than PcdMaximumUnicodeStringLength
174 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
175 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
182 Returns the size of a Null-terminated Unicode string in bytes, including the
185 This function returns the size, in bytes, of the Null-terminated Unicode string
188 If String is NULL, then ASSERT().
189 If String is not aligned on a 16-bit boundary, then ASSERT().
190 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
191 PcdMaximumUnicodeStringLength Unicode characters, not including the
192 Null-terminator, then ASSERT().
194 @param String A pointer to a Null-terminated Unicode string.
196 @return The size of String.
202 IN CONST CHAR16
*String
205 return (StrLen (String
) + 1) * sizeof (*String
);
209 Compares two Null-terminated Unicode strings, and returns the difference
210 between the first mismatched Unicode characters.
212 This function compares the Null-terminated Unicode string FirstString to the
213 Null-terminated Unicode string SecondString. If FirstString is identical to
214 SecondString, then 0 is returned. Otherwise, the value returned is the first
215 mismatched Unicode character in SecondString subtracted from the first
216 mismatched Unicode character in FirstString.
218 If FirstString is NULL, then ASSERT().
219 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
220 If SecondString is NULL, then ASSERT().
221 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
222 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
223 than PcdMaximumUnicodeStringLength Unicode characters, not including the
224 Null-terminator, then ASSERT().
225 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
226 than PcdMaximumUnicodeStringLength Unicode characters, not including the
227 Null-terminator, then ASSERT().
229 @param FirstString A pointer to a Null-terminated Unicode string.
230 @param SecondString A pointer to a Null-terminated Unicode string.
232 @retval 0 FirstString is identical to SecondString.
233 @return others FirstString is not identical to SecondString.
239 IN CONST CHAR16
*FirstString
,
240 IN CONST CHAR16
*SecondString
244 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
246 ASSERT (StrSize (FirstString
) != 0);
247 ASSERT (StrSize (SecondString
) != 0);
249 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
253 return *FirstString
- *SecondString
;
257 Compares up to a specified length the contents of two Null-terminated Unicode strings,
258 and returns the difference between the first mismatched Unicode characters.
260 This function compares the Null-terminated Unicode string FirstString to the
261 Null-terminated Unicode string SecondString. At most, Length Unicode
262 characters will be compared. If Length is 0, then 0 is returned. If
263 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
264 value returned is the first mismatched Unicode character in SecondString
265 subtracted from the first mismatched Unicode character in FirstString.
267 If Length > 0 and FirstString is NULL, then ASSERT().
268 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
269 If Length > 0 and SecondString is NULL, then ASSERT().
270 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
271 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
272 PcdMaximumUnicodeStringLength, then ASSERT().
273 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
274 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
276 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
277 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
280 @param FirstString A pointer to a Null-terminated Unicode string.
281 @param SecondString A pointer to a Null-terminated Unicode string.
282 @param Length The maximum number of Unicode characters to compare.
284 @retval 0 FirstString is identical to SecondString.
285 @return others FirstString is not identical to SecondString.
291 IN CONST CHAR16
*FirstString
,
292 IN CONST CHAR16
*SecondString
,
301 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
302 // Length tests are performed inside StrLen().
304 ASSERT (StrSize (FirstString
) != 0);
305 ASSERT (StrSize (SecondString
) != 0);
307 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
308 ASSERT (Length
<= PcdGet32 (PcdMaximumUnicodeStringLength
));
311 while ((*FirstString
!= L
'\0') &&
312 (*SecondString
!= L
'\0') &&
313 (*FirstString
== *SecondString
) &&
320 return *FirstString
- *SecondString
;
323 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
326 [ATTENTION] This function will be deprecated for security reason.
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 Destination is not aligned on a 16-bit boundary, then ASSERT().
339 If Source is NULL, then ASSERT().
340 If Source is not aligned on a 16-bit boundary, then ASSERT().
341 If Source and Destination overlap, then ASSERT().
342 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
343 than PcdMaximumUnicodeStringLength Unicode characters, not including the
344 Null-terminator, then ASSERT().
345 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
346 PcdMaximumUnicodeStringLength Unicode characters, not including the
347 Null-terminator, then ASSERT().
348 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
349 and Source results in a Unicode string with more than
350 PcdMaximumUnicodeStringLength Unicode characters, not including the
351 Null-terminator, then ASSERT().
353 @param Destination A pointer to a Null-terminated Unicode string.
354 @param Source A pointer to a Null-terminated Unicode string.
362 IN OUT CHAR16
*Destination
,
363 IN CONST CHAR16
*Source
366 StrCpy (Destination
+ StrLen (Destination
), Source
);
369 // Size of the resulting string should never be zero.
370 // PcdMaximumUnicodeStringLength is tested inside StrLen().
372 ASSERT (StrSize (Destination
) != 0);
377 [ATTENTION] This function will be deprecated for security reason.
379 Concatenates up to a specified length one Null-terminated Unicode to the end
380 of another Null-terminated Unicode string, and returns the concatenated
383 This function concatenates two Null-terminated Unicode strings. The contents
384 of Null-terminated Unicode string Source are concatenated to the end of
385 Null-terminated Unicode string Destination, and Destination is returned. At
386 most, Length Unicode characters are concatenated from Source to the end of
387 Destination, and Destination is always Null-terminated. If Length is 0, then
388 Destination is returned unmodified. If Source and Destination overlap, then
389 the results are undefined.
391 If Destination is NULL, then ASSERT().
392 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
393 If Length > 0 and Source is NULL, then ASSERT().
394 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
395 If Source and Destination overlap, then ASSERT().
396 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
397 PcdMaximumUnicodeStringLength, then ASSERT().
398 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
399 than PcdMaximumUnicodeStringLength Unicode characters, not including the
400 Null-terminator, then ASSERT().
401 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
402 PcdMaximumUnicodeStringLength Unicode characters, not including the
403 Null-terminator, then ASSERT().
404 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
405 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
406 Unicode characters, not including the Null-terminator, then ASSERT().
408 @param Destination A pointer to a Null-terminated Unicode string.
409 @param Source A pointer to a Null-terminated Unicode string.
410 @param Length The maximum number of Unicode characters to concatenate from
419 IN OUT CHAR16
*Destination
,
420 IN CONST CHAR16
*Source
,
424 UINTN DestinationLen
;
426 DestinationLen
= StrLen (Destination
);
427 StrnCpy (Destination
+ DestinationLen
, Source
, Length
);
428 Destination
[DestinationLen
+ Length
] = L
'\0';
431 // Size of the resulting string should never be zero.
432 // PcdMaximumUnicodeStringLength is tested inside StrLen().
434 ASSERT (StrSize (Destination
) != 0);
440 Returns the first occurrence of a Null-terminated Unicode sub-string
441 in a Null-terminated Unicode string.
443 This function scans the contents of the Null-terminated Unicode string
444 specified by String and returns the first occurrence of SearchString.
445 If SearchString is not found in String, then NULL is returned. If
446 the length of SearchString is zero, then String is
449 If String is NULL, then ASSERT().
450 If String is not aligned on a 16-bit boundary, then ASSERT().
451 If SearchString is NULL, then ASSERT().
452 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
454 If PcdMaximumUnicodeStringLength is not zero, and SearchString
455 or String contains more than PcdMaximumUnicodeStringLength Unicode
456 characters, not including the Null-terminator, then ASSERT().
458 @param String A pointer to a Null-terminated Unicode string.
459 @param SearchString A pointer to a Null-terminated Unicode string to search for.
461 @retval NULL If the SearchString does not appear in String.
462 @return others If there is a match.
468 IN CONST CHAR16
*String
,
469 IN CONST CHAR16
*SearchString
472 CONST CHAR16
*FirstMatch
;
473 CONST CHAR16
*SearchStringTmp
;
476 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
477 // Length tests are performed inside StrLen().
479 ASSERT (StrSize (String
) != 0);
480 ASSERT (StrSize (SearchString
) != 0);
482 if (*SearchString
== L
'\0') {
483 return (CHAR16
*) String
;
486 while (*String
!= L
'\0') {
487 SearchStringTmp
= SearchString
;
490 while ((*String
== *SearchStringTmp
)
491 && (*String
!= L
'\0')) {
496 if (*SearchStringTmp
== L
'\0') {
497 return (CHAR16
*) FirstMatch
;
500 if (*String
== L
'\0') {
504 String
= FirstMatch
+ 1;
511 Check if a Unicode character is a decimal character.
513 This internal function checks if a Unicode character is a
514 decimal character. The valid decimal character is from
517 @param Char The character to check against.
519 @retval TRUE If the Char is a decmial character.
520 @retval FALSE If the Char is not a decmial character.
525 InternalIsDecimalDigitCharacter (
529 return (BOOLEAN
) (Char
>= L
'0' && Char
<= L
'9');
533 Convert a Unicode character to upper case only if
534 it maps to a valid small-case ASCII character.
536 This internal function only deal with Unicode character
537 which maps to a valid small-case ASCII character, i.e.
538 L'a' to L'z'. For other Unicode character, the input character
539 is returned directly.
541 @param Char The character to convert.
543 @retval LowerCharacter If the Char is with range L'a' to L'z'.
544 @retval Unchanged Otherwise.
553 if (Char
>= L
'a' && Char
<= L
'z') {
554 return (CHAR16
) (Char
- (L
'a' - L
'A'));
561 Convert a Unicode character to numerical value.
563 This internal function only deal with Unicode character
564 which maps to a valid hexadecimal ASII character, i.e.
565 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
566 Unicode character, the value returned does not make sense.
568 @param Char The character to convert.
570 @return The numerical value converted.
575 InternalHexCharToUintn (
579 if (InternalIsDecimalDigitCharacter (Char
)) {
583 return (10 + CharToUpper (Char
) - L
'A');
587 Check if a Unicode character is a hexadecimal character.
589 This internal function checks if a Unicode character is a
590 decimal character. The valid hexadecimal character is
591 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
594 @param Char The character to check against.
596 @retval TRUE If the Char is a hexadecmial character.
597 @retval FALSE If the Char is not a hexadecmial character.
602 InternalIsHexaDecimalDigitCharacter (
607 return (BOOLEAN
) (InternalIsDecimalDigitCharacter (Char
) ||
608 (Char
>= L
'A' && Char
<= L
'F') ||
609 (Char
>= L
'a' && Char
<= L
'f'));
613 Convert a Null-terminated Unicode decimal string to a value of
616 This function returns a value of type UINTN by interpreting the contents
617 of the Unicode string specified by String as a decimal number. The format
618 of the input Unicode string String is:
620 [spaces] [decimal digits].
622 The valid decimal digit character is in the range [0-9]. The
623 function will ignore the pad space, which includes spaces or
624 tab characters, before [decimal digits]. The running zero in the
625 beginning of [decimal digits] will be ignored. Then, the function
626 stops at the first character that is a not a valid decimal character
627 or a Null-terminator, whichever one comes first.
629 If String is NULL, then ASSERT().
630 If String is not aligned in a 16-bit boundary, then ASSERT().
631 If String has only pad spaces, then 0 is returned.
632 If String has no pad spaces or valid decimal digits,
634 If the number represented by String overflows according
635 to the range defined by UINTN, then MAX_UINTN is returned.
637 If PcdMaximumUnicodeStringLength is not zero, and String contains
638 more than PcdMaximumUnicodeStringLength Unicode characters, not including
639 the Null-terminator, then ASSERT().
641 @param String A pointer to a Null-terminated Unicode string.
643 @retval Value translated from String.
649 IN CONST CHAR16
*String
654 StrDecimalToUintnS (String
, (CHAR16
**) NULL
, &Result
);
660 Convert a Null-terminated Unicode decimal string to a value of
663 This function returns a value of type UINT64 by interpreting the contents
664 of the Unicode string specified by String as a decimal number. The format
665 of the input Unicode string String is:
667 [spaces] [decimal digits].
669 The valid decimal digit character is in the range [0-9]. The
670 function will ignore the pad space, which includes spaces or
671 tab characters, before [decimal digits]. The running zero in the
672 beginning of [decimal digits] will be ignored. Then, the function
673 stops at the first character that is a not a valid decimal character
674 or a Null-terminator, whichever one comes first.
676 If String is NULL, then ASSERT().
677 If String is not aligned in a 16-bit boundary, then ASSERT().
678 If String has only pad spaces, then 0 is returned.
679 If String has no pad spaces or valid decimal digits,
681 If the number represented by String overflows according
682 to the range defined by UINT64, then MAX_UINT64 is returned.
684 If PcdMaximumUnicodeStringLength is not zero, and String contains
685 more than PcdMaximumUnicodeStringLength Unicode characters, not including
686 the Null-terminator, then ASSERT().
688 @param String A pointer to a Null-terminated Unicode string.
690 @retval Value translated from String.
696 IN CONST CHAR16
*String
701 StrDecimalToUint64S (String
, (CHAR16
**) NULL
, &Result
);
706 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
708 This function returns a value of type UINTN by interpreting the contents
709 of the Unicode string specified by String as a hexadecimal number.
710 The format of the input Unicode string String is:
712 [spaces][zeros][x][hexadecimal digits].
714 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
715 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
716 If "x" appears in the input string, it must be prefixed with at least one 0.
717 The function will ignore the pad space, which includes spaces or tab characters,
718 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
719 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
720 first valid hexadecimal digit. Then, the function stops at the first character that is
721 a not a valid hexadecimal character or NULL, whichever one comes first.
723 If String is NULL, then ASSERT().
724 If String is not aligned in a 16-bit boundary, then ASSERT().
725 If String has only pad spaces, then zero is returned.
726 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
727 then zero is returned.
728 If the number represented by String overflows according to the range defined by
729 UINTN, then MAX_UINTN is returned.
731 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
732 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
735 @param String A pointer to a Null-terminated Unicode string.
737 @retval Value translated from String.
743 IN CONST CHAR16
*String
748 StrHexToUintnS (String
, (CHAR16
**) NULL
, &Result
);
754 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
756 This function returns a value of type UINT64 by interpreting the contents
757 of the Unicode string specified by String as a hexadecimal number.
758 The format of the input Unicode string String is
760 [spaces][zeros][x][hexadecimal digits].
762 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
763 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
764 If "x" appears in the input string, it must be prefixed with at least one 0.
765 The function will ignore the pad space, which includes spaces or tab characters,
766 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
767 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
768 first valid hexadecimal digit. Then, the function stops at the first character that is
769 a not a valid hexadecimal character or NULL, whichever one comes first.
771 If String is NULL, then ASSERT().
772 If String is not aligned in a 16-bit boundary, then ASSERT().
773 If String has only pad spaces, then zero is returned.
774 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
775 then zero is returned.
776 If the number represented by String overflows according to the range defined by
777 UINT64, then MAX_UINT64 is returned.
779 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
780 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
783 @param String A pointer to a Null-terminated Unicode string.
785 @retval Value translated from String.
791 IN CONST CHAR16
*String
796 StrHexToUint64S (String
, (CHAR16
**) NULL
, &Result
);
801 Check if a ASCII character is a decimal character.
803 This internal function checks if a Unicode character is a
804 decimal character. The valid decimal character is from
807 @param Char The character to check against.
809 @retval TRUE If the Char is a decmial character.
810 @retval FALSE If the Char is not a decmial character.
815 InternalAsciiIsDecimalDigitCharacter (
819 return (BOOLEAN
) (Char
>= '0' && Char
<= '9');
823 Check if a ASCII character is a hexadecimal character.
825 This internal function checks if a ASCII character is a
826 decimal character. The valid hexadecimal character is
827 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
830 @param Char The character to check against.
832 @retval TRUE If the Char is a hexadecmial character.
833 @retval FALSE If the Char is not a hexadecmial character.
838 InternalAsciiIsHexaDecimalDigitCharacter (
843 return (BOOLEAN
) (InternalAsciiIsDecimalDigitCharacter (Char
) ||
844 (Char
>= 'A' && Char
<= 'F') ||
845 (Char
>= 'a' && Char
<= 'f'));
848 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
851 [ATTENTION] This function is deprecated for security reason.
853 Convert a Null-terminated Unicode string to a Null-terminated
854 ASCII string and returns the ASCII string.
856 This function converts the content of the Unicode string Source
857 to the ASCII string Destination by copying the lower 8 bits of
858 each Unicode character. It returns Destination.
860 The caller is responsible to make sure Destination points to a buffer with size
861 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
863 If any Unicode characters in Source contain non-zero value in
864 the upper 8 bits, then ASSERT().
866 If Destination is NULL, then ASSERT().
867 If Source is NULL, then ASSERT().
868 If Source is not aligned on a 16-bit boundary, then ASSERT().
869 If Source and Destination overlap, then ASSERT().
871 If PcdMaximumUnicodeStringLength is not zero, and Source contains
872 more than PcdMaximumUnicodeStringLength Unicode characters, not including
873 the Null-terminator, then ASSERT().
875 If PcdMaximumAsciiStringLength is not zero, and Source contains more
876 than PcdMaximumAsciiStringLength Unicode characters, not including the
877 Null-terminator, then ASSERT().
879 @param Source A pointer to a Null-terminated Unicode string.
880 @param Destination A pointer to a Null-terminated ASCII string.
887 UnicodeStrToAsciiStr (
888 IN CONST CHAR16
*Source
,
889 OUT CHAR8
*Destination
894 ASSERT (Destination
!= NULL
);
897 // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
898 // Length tests are performed inside StrLen().
900 ASSERT (StrSize (Source
) != 0);
903 // Source and Destination should not overlap
905 ASSERT ((UINTN
) (Destination
- (CHAR8
*) Source
) >= StrSize (Source
));
906 ASSERT ((UINTN
) ((CHAR8
*) Source
- Destination
) > StrLen (Source
));
909 ReturnValue
= Destination
;
910 while (*Source
!= '\0') {
912 // If any Unicode characters in Source contain
913 // non-zero value in the upper 8 bits, then ASSERT().
915 ASSERT (*Source
< 0x100);
916 *(Destination
++) = (CHAR8
) *(Source
++);
922 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
923 // Length tests are performed inside AsciiStrLen().
925 ASSERT (AsciiStrSize (ReturnValue
) != 0);
931 [ATTENTION] This function will be deprecated for security reason.
933 Copies one Null-terminated ASCII string to another Null-terminated ASCII
934 string and returns the new ASCII string.
936 This function copies the contents of the ASCII string Source to the ASCII
937 string Destination, and returns Destination. If Source and Destination
938 overlap, then the results are undefined.
940 If Destination is NULL, then ASSERT().
941 If Source is NULL, then ASSERT().
942 If Source and Destination overlap, then ASSERT().
943 If PcdMaximumAsciiStringLength is not zero and Source contains more than
944 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
947 @param Destination A pointer to a Null-terminated ASCII string.
948 @param Source A pointer to a Null-terminated ASCII string.
956 OUT CHAR8
*Destination
,
957 IN CONST CHAR8
*Source
963 // Destination cannot be NULL
965 ASSERT (Destination
!= NULL
);
968 // Destination and source cannot overlap
970 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
971 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
973 ReturnValue
= Destination
;
974 while (*Source
!= 0) {
975 *(Destination
++) = *(Source
++);
982 [ATTENTION] This function will be deprecated for security reason.
984 Copies up to a specified length one Null-terminated ASCII string to another
985 Null-terminated ASCII string and returns the new ASCII string.
987 This function copies the contents of the ASCII string Source to the ASCII
988 string Destination, and returns Destination. At most, Length ASCII characters
989 are copied from Source to Destination. If Length is 0, then Destination is
990 returned unmodified. If Length is greater that the number of ASCII characters
991 in Source, then Destination is padded with Null ASCII characters. If Source
992 and Destination overlap, then the results are undefined.
994 If Destination is NULL, then ASSERT().
995 If Source is NULL, then ASSERT().
996 If Source and Destination overlap, then ASSERT().
997 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
998 PcdMaximumAsciiStringLength, then ASSERT().
999 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1000 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1003 @param Destination A pointer to a Null-terminated ASCII string.
1004 @param Source A pointer to a Null-terminated ASCII string.
1005 @param Length The maximum number of ASCII characters to copy.
1013 OUT CHAR8
*Destination
,
1014 IN CONST CHAR8
*Source
,
1025 // Destination cannot be NULL
1027 ASSERT (Destination
!= NULL
);
1030 // Destination and source cannot overlap
1032 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
1033 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
1035 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1036 ASSERT (Length
<= PcdGet32 (PcdMaximumAsciiStringLength
));
1039 ReturnValue
= Destination
;
1041 while (*Source
!= 0 && Length
> 0) {
1042 *(Destination
++) = *(Source
++);
1046 ZeroMem (Destination
, Length
* sizeof (*Destination
));
1052 Returns the length of a Null-terminated ASCII string.
1054 This function returns the number of ASCII characters in the Null-terminated
1055 ASCII string specified by String.
1057 If Length > 0 and Destination is NULL, then ASSERT().
1058 If Length > 0 and Source is NULL, then ASSERT().
1059 If PcdMaximumAsciiStringLength is not zero and String contains more than
1060 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1063 @param String A pointer to a Null-terminated ASCII string.
1065 @return The length of String.
1071 IN CONST CHAR8
*String
1076 ASSERT (String
!= NULL
);
1078 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
1080 // If PcdMaximumUnicodeStringLength is not zero,
1081 // length should not more than PcdMaximumUnicodeStringLength
1083 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1084 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
1091 Returns the size of a Null-terminated ASCII string in bytes, including the
1094 This function returns the size, in bytes, of the Null-terminated ASCII string
1095 specified by String.
1097 If String is NULL, then ASSERT().
1098 If PcdMaximumAsciiStringLength is not zero and String contains more than
1099 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1102 @param String A pointer to a Null-terminated ASCII string.
1104 @return The size of String.
1110 IN CONST CHAR8
*String
1113 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
1117 Compares two Null-terminated ASCII strings, and returns the difference
1118 between the first mismatched ASCII characters.
1120 This function compares the Null-terminated ASCII string FirstString to the
1121 Null-terminated ASCII string SecondString. If FirstString is identical to
1122 SecondString, then 0 is returned. Otherwise, the value returned is the first
1123 mismatched ASCII character in SecondString subtracted from the first
1124 mismatched ASCII character in FirstString.
1126 If FirstString is NULL, then ASSERT().
1127 If SecondString is NULL, then ASSERT().
1128 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1129 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1131 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1132 than PcdMaximumAsciiStringLength ASCII characters, not including the
1133 Null-terminator, then ASSERT().
1135 @param FirstString A pointer to a Null-terminated ASCII string.
1136 @param SecondString A pointer to a Null-terminated ASCII string.
1138 @retval ==0 FirstString is identical to SecondString.
1139 @retval !=0 FirstString is not identical to SecondString.
1145 IN CONST CHAR8
*FirstString
,
1146 IN CONST CHAR8
*SecondString
1150 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1152 ASSERT (AsciiStrSize (FirstString
));
1153 ASSERT (AsciiStrSize (SecondString
));
1155 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
1160 return *FirstString
- *SecondString
;
1164 Converts a lowercase Ascii character to upper one.
1166 If Chr is lowercase Ascii character, then converts it to upper one.
1168 If Value >= 0xA0, then ASSERT().
1169 If (Value & 0x0F) >= 0x0A, then ASSERT().
1171 @param Chr one Ascii character
1173 @return The uppercase value of Ascii character
1182 return (UINT8
) ((Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
);
1186 Convert a ASCII character to numerical value.
1188 This internal function only deal with Unicode character
1189 which maps to a valid hexadecimal ASII character, i.e.
1190 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1191 ASCII character, the value returned does not make sense.
1193 @param Char The character to convert.
1195 @return The numerical value converted.
1200 InternalAsciiHexCharToUintn (
1204 if (InternalIsDecimalDigitCharacter (Char
)) {
1208 return (10 + AsciiCharToUpper (Char
) - 'A');
1213 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1214 and returns the difference between the first mismatched ASCII characters.
1216 This function performs a case insensitive comparison of the Null-terminated
1217 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1218 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1219 value returned is the first mismatched lower case ASCII character in
1220 SecondString subtracted from the first mismatched lower case ASCII character
1223 If FirstString is NULL, then ASSERT().
1224 If SecondString is NULL, then ASSERT().
1225 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1226 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1228 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1229 than PcdMaximumAsciiStringLength ASCII characters, not including the
1230 Null-terminator, then ASSERT().
1232 @param FirstString A pointer to a Null-terminated ASCII string.
1233 @param SecondString A pointer to a Null-terminated ASCII string.
1235 @retval ==0 FirstString is identical to SecondString using case insensitive
1237 @retval !=0 FirstString is not identical to SecondString using case
1238 insensitive comparisons.
1244 IN CONST CHAR8
*FirstString
,
1245 IN CONST CHAR8
*SecondString
1248 CHAR8 UpperFirstString
;
1249 CHAR8 UpperSecondString
;
1252 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1254 ASSERT (AsciiStrSize (FirstString
));
1255 ASSERT (AsciiStrSize (SecondString
));
1257 UpperFirstString
= AsciiCharToUpper (*FirstString
);
1258 UpperSecondString
= AsciiCharToUpper (*SecondString
);
1259 while ((*FirstString
!= '\0') && (*SecondString
!= '\0') && (UpperFirstString
== UpperSecondString
)) {
1262 UpperFirstString
= AsciiCharToUpper (*FirstString
);
1263 UpperSecondString
= AsciiCharToUpper (*SecondString
);
1266 return UpperFirstString
- UpperSecondString
;
1270 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1271 the difference between the first mismatched ASCII characters.
1273 This function compares the Null-terminated ASCII string FirstString to the
1274 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1275 will be compared. If Length is 0, then 0 is returned. If FirstString is
1276 identical to SecondString, then 0 is returned. Otherwise, the value returned
1277 is the first mismatched ASCII character in SecondString subtracted from the
1278 first mismatched ASCII character in FirstString.
1280 If Length > 0 and FirstString is NULL, then ASSERT().
1281 If Length > 0 and SecondString is NULL, then ASSERT().
1282 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1283 PcdMaximumAsciiStringLength, then ASSERT().
1284 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1285 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1287 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1288 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1291 @param FirstString A pointer to a Null-terminated ASCII string.
1292 @param SecondString A pointer to a Null-terminated ASCII string.
1293 @param Length The maximum number of ASCII characters for compare.
1295 @retval ==0 FirstString is identical to SecondString.
1296 @retval !=0 FirstString is not identical to SecondString.
1302 IN CONST CHAR8
*FirstString
,
1303 IN CONST CHAR8
*SecondString
,
1312 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1314 ASSERT (AsciiStrSize (FirstString
));
1315 ASSERT (AsciiStrSize (SecondString
));
1317 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
1318 ASSERT (Length
<= PcdGet32 (PcdMaximumAsciiStringLength
));
1321 while ((*FirstString
!= '\0') &&
1322 (*SecondString
!= '\0') &&
1323 (*FirstString
== *SecondString
) &&
1329 return *FirstString
- *SecondString
;
1332 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1335 [ATTENTION] This function will be deprecated for security reason.
1337 Concatenates one Null-terminated ASCII string to another Null-terminated
1338 ASCII string, and returns the concatenated ASCII string.
1340 This function concatenates two Null-terminated ASCII strings. The contents of
1341 Null-terminated ASCII string Source are concatenated to the end of Null-
1342 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1345 If Destination is NULL, then ASSERT().
1346 If Source is NULL, then ASSERT().
1347 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1348 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1350 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1351 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1353 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1354 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1355 ASCII characters, then ASSERT().
1357 @param Destination A pointer to a Null-terminated ASCII string.
1358 @param Source A pointer to a Null-terminated ASCII string.
1366 IN OUT CHAR8
*Destination
,
1367 IN CONST CHAR8
*Source
1370 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
1373 // Size of the resulting string should never be zero.
1374 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1376 ASSERT (AsciiStrSize (Destination
) != 0);
1381 [ATTENTION] This function will be deprecated for security reason.
1383 Concatenates up to a specified length one Null-terminated ASCII string to
1384 the end of another Null-terminated ASCII string, and returns the
1385 concatenated ASCII string.
1387 This function concatenates two Null-terminated ASCII strings. The contents
1388 of Null-terminated ASCII string Source are concatenated to the end of Null-
1389 terminated ASCII string Destination, and Destination is returned. At most,
1390 Length ASCII characters are concatenated from Source to the end of
1391 Destination, and Destination is always Null-terminated. If Length is 0, then
1392 Destination is returned unmodified. If Source and Destination overlap, then
1393 the results are undefined.
1395 If Length > 0 and Destination is NULL, then ASSERT().
1396 If Length > 0 and Source is NULL, then ASSERT().
1397 If Source and Destination overlap, then ASSERT().
1398 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1399 PcdMaximumAsciiStringLength, then ASSERT().
1400 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1401 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1403 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1404 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1406 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1407 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1408 ASCII characters, not including the Null-terminator, then ASSERT().
1410 @param Destination A pointer to a Null-terminated ASCII string.
1411 @param Source A pointer to a Null-terminated ASCII string.
1412 @param Length The maximum number of ASCII characters to concatenate from
1421 IN OUT CHAR8
*Destination
,
1422 IN CONST CHAR8
*Source
,
1426 UINTN DestinationLen
;
1428 DestinationLen
= AsciiStrLen (Destination
);
1429 AsciiStrnCpy (Destination
+ DestinationLen
, Source
, Length
);
1430 Destination
[DestinationLen
+ Length
] = '\0';
1433 // Size of the resulting string should never be zero.
1434 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1436 ASSERT (AsciiStrSize (Destination
) != 0);
1442 Returns the first occurrence of a Null-terminated ASCII sub-string
1443 in a Null-terminated ASCII string.
1445 This function scans the contents of the ASCII string specified by String
1446 and returns the first occurrence of SearchString. If SearchString is not
1447 found in String, then NULL is returned. If the length of SearchString is zero,
1448 then String is returned.
1450 If String is NULL, then ASSERT().
1451 If SearchString is NULL, then ASSERT().
1453 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1454 String contains more than PcdMaximumAsciiStringLength Unicode characters
1455 not including the Null-terminator, then ASSERT().
1457 @param String A pointer to a Null-terminated ASCII string.
1458 @param SearchString A pointer to a Null-terminated ASCII string to search for.
1460 @retval NULL If the SearchString does not appear in String.
1461 @retval others If there is a match return the first occurrence of SearchingString.
1462 If the length of SearchString is zero,return String.
1468 IN CONST CHAR8
*String
,
1469 IN CONST CHAR8
*SearchString
1472 CONST CHAR8
*FirstMatch
;
1473 CONST CHAR8
*SearchStringTmp
;
1476 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1478 ASSERT (AsciiStrSize (String
) != 0);
1479 ASSERT (AsciiStrSize (SearchString
) != 0);
1481 if (*SearchString
== '\0') {
1482 return (CHAR8
*) String
;
1485 while (*String
!= '\0') {
1486 SearchStringTmp
= SearchString
;
1487 FirstMatch
= String
;
1489 while ((*String
== *SearchStringTmp
)
1490 && (*String
!= '\0')) {
1495 if (*SearchStringTmp
== '\0') {
1496 return (CHAR8
*) FirstMatch
;
1499 if (*String
== '\0') {
1503 String
= FirstMatch
+ 1;
1510 Convert a Null-terminated ASCII decimal string to a value of type
1513 This function returns a value of type UINTN by interpreting the contents
1514 of the ASCII string String as a decimal number. The format of the input
1515 ASCII string String is:
1517 [spaces] [decimal digits].
1519 The valid decimal digit character is in the range [0-9]. The function will
1520 ignore the pad space, which includes spaces or tab characters, before the digits.
1521 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1522 function stops at the first character that is a not a valid decimal character or
1523 Null-terminator, whichever on comes first.
1525 If String has only pad spaces, then 0 is returned.
1526 If String has no pad spaces or valid decimal digits, then 0 is returned.
1527 If the number represented by String overflows according to the range defined by
1528 UINTN, then MAX_UINTN is returned.
1529 If String is NULL, then ASSERT().
1530 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1531 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1534 @param String A pointer to a Null-terminated ASCII string.
1536 @retval Value translated from String.
1541 AsciiStrDecimalToUintn (
1542 IN CONST CHAR8
*String
1547 AsciiStrDecimalToUintnS (String
, (CHAR8
**) NULL
, &Result
);
1553 Convert a Null-terminated ASCII decimal string to a value of type
1556 This function returns a value of type UINT64 by interpreting the contents
1557 of the ASCII string String as a decimal number. The format of the input
1558 ASCII string String is:
1560 [spaces] [decimal digits].
1562 The valid decimal digit character is in the range [0-9]. The function will
1563 ignore the pad space, which includes spaces or tab characters, before the digits.
1564 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1565 function stops at the first character that is a not a valid decimal character or
1566 Null-terminator, whichever on comes first.
1568 If String has only pad spaces, then 0 is returned.
1569 If String has no pad spaces or valid decimal digits, then 0 is returned.
1570 If the number represented by String overflows according to the range defined by
1571 UINT64, then MAX_UINT64 is returned.
1572 If String is NULL, then ASSERT().
1573 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1574 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1577 @param String A pointer to a Null-terminated ASCII string.
1579 @retval Value translated from String.
1584 AsciiStrDecimalToUint64 (
1585 IN CONST CHAR8
*String
1590 AsciiStrDecimalToUint64S (String
, (CHAR8
**) NULL
, &Result
);
1595 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1597 This function returns a value of type UINTN by interpreting the contents of
1598 the ASCII string String as a hexadecimal number. The format of the input ASCII
1601 [spaces][zeros][x][hexadecimal digits].
1603 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1604 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1605 appears in the input string, it must be prefixed with at least one 0. The function
1606 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1607 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1608 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1609 digit. Then, the function stops at the first character that is a not a valid
1610 hexadecimal character or Null-terminator, whichever on comes first.
1612 If String has only pad spaces, then 0 is returned.
1613 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1616 If the number represented by String overflows according to the range defined by UINTN,
1617 then MAX_UINTN is returned.
1618 If String is NULL, then ASSERT().
1619 If PcdMaximumAsciiStringLength is not zero,
1620 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1621 the Null-terminator, then ASSERT().
1623 @param String A pointer to a Null-terminated ASCII string.
1625 @retval Value translated from String.
1630 AsciiStrHexToUintn (
1631 IN CONST CHAR8
*String
1636 AsciiStrHexToUintnS (String
, (CHAR8
**) NULL
, &Result
);
1642 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1644 This function returns a value of type UINT64 by interpreting the contents of
1645 the ASCII string String as a hexadecimal number. The format of the input ASCII
1648 [spaces][zeros][x][hexadecimal digits].
1650 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1651 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1652 appears in the input string, it must be prefixed with at least one 0. The function
1653 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1654 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1655 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1656 digit. Then, the function stops at the first character that is a not a valid
1657 hexadecimal character or Null-terminator, whichever on comes first.
1659 If String has only pad spaces, then 0 is returned.
1660 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1663 If the number represented by String overflows according to the range defined by UINT64,
1664 then MAX_UINT64 is returned.
1665 If String is NULL, then ASSERT().
1666 If PcdMaximumAsciiStringLength is not zero,
1667 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1668 the Null-terminator, then ASSERT().
1670 @param String A pointer to a Null-terminated ASCII string.
1672 @retval Value translated from String.
1677 AsciiStrHexToUint64 (
1678 IN CONST CHAR8
*String
1683 AsciiStrHexToUint64S (String
, (CHAR8
**) NULL
, &Result
);
1687 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1690 [ATTENTION] This function is deprecated for security reason.
1692 Convert one Null-terminated ASCII string to a Null-terminated
1693 Unicode string and returns the Unicode string.
1695 This function converts the contents of the ASCII string Source to the Unicode
1696 string Destination, and returns Destination. The function terminates the
1697 Unicode string Destination by appending a Null-terminator character at the end.
1698 The caller is responsible to make sure Destination points to a buffer with size
1699 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1701 If Destination is NULL, then ASSERT().
1702 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1703 If Source is NULL, then ASSERT().
1704 If Source and Destination overlap, then ASSERT().
1705 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1706 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1708 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1709 PcdMaximumUnicodeStringLength ASCII characters not including the
1710 Null-terminator, then ASSERT().
1712 @param Source A pointer to a Null-terminated ASCII string.
1713 @param Destination A pointer to a Null-terminated Unicode string.
1715 @return Destination.
1720 AsciiStrToUnicodeStr (
1721 IN CONST CHAR8
*Source
,
1722 OUT CHAR16
*Destination
1725 CHAR16
*ReturnValue
;
1727 ASSERT (Destination
!= NULL
);
1730 // ASSERT Source is less long than PcdMaximumAsciiStringLength
1732 ASSERT (AsciiStrSize (Source
) != 0);
1735 // Source and Destination should not overlap
1737 ASSERT ((UINTN
) ((CHAR8
*) Destination
- Source
) > AsciiStrLen (Source
));
1738 ASSERT ((UINTN
) (Source
- (CHAR8
*) Destination
) >= (AsciiStrSize (Source
) * sizeof (CHAR16
)));
1741 ReturnValue
= Destination
;
1742 while (*Source
!= '\0') {
1743 *(Destination
++) = (CHAR16
)(UINT8
) *(Source
++);
1746 // End the Destination with a NULL.
1748 *Destination
= '\0';
1751 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
1753 ASSERT (StrSize (ReturnValue
) != 0);
1761 // The basis for Base64 encoding is RFC 4686 https://tools.ietf.org/html/rfc4648
1763 // RFC 4686 has a number of MAY and SHOULD cases. This implementation chooses
1764 // the more restrictive versions for security concerns (see RFC 4686 section 3.3).
1766 // A invalid character, if encountered during the decode operation, causes the data
1767 // to be rejected. In addition, the '=' padding character is only allowed at the end
1768 // of the Base64 encoded string.
1772 STATIC CHAR8 EncodingTable
[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
1773 "abcdefghijklmnopqrstuvwxyz"
1776 STATIC UINT8 DecodingTable
[] = {
1778 // Valid characters ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
1779 // Also, set '=' as a zero for decoding
1780 // 0 , 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e, f
1781 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 0
1782 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 10
1783 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, 62, BAD_V
, BAD_V
, BAD_V
, 63, // 20
1784 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, BAD_V
, BAD_V
, BAD_V
, 0, BAD_V
, BAD_V
, // 30
1785 BAD_V
, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, // 40
1786 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 50
1787 BAD_V
, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, // 60
1788 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 70
1789 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 80
1790 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // 90
1791 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // a0
1792 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // b0
1793 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // c0
1794 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // d0
1795 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, // d0
1796 BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
, BAD_V
// f0
1800 Convert binary data to a Base64 encoded ascii string based on RFC4648.
1802 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
1803 The Ascii string is produced by converting the data string specified by Source and SourceLength.
1805 @param Source Input UINT8 data
1806 @param SourceLength Number of UINT8 bytes of data
1807 @param Destination Pointer to output string buffer
1808 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
1809 Caller is responsible for passing in buffer of DestinationSize
1811 @retval RETURN_SUCCESS When ascii buffer is filled in.
1812 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
1813 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
1814 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
1815 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
1821 IN CONST UINT8
*Source
,
1822 IN UINTN SourceLength
,
1823 OUT CHAR8
*Destination OPTIONAL
,
1824 IN OUT UINTN
*DestinationSize
1832 // Check pointers, and SourceLength is valid
1834 if ((Source
== NULL
) || (DestinationSize
== NULL
)) {
1835 return RETURN_INVALID_PARAMETER
;
1839 // Allow for RFC 4648 test vector 1
1841 if (SourceLength
== 0) {
1842 if (*DestinationSize
< 1) {
1843 *DestinationSize
= 1;
1844 return RETURN_BUFFER_TOO_SMALL
;
1846 *DestinationSize
= 1;
1847 *Destination
= '\0';
1848 return RETURN_SUCCESS
;
1852 // Check if SourceLength or DestinationSize is valid
1854 if ((SourceLength
>= (MAX_ADDRESS
- (UINTN
)Source
)) || (*DestinationSize
>= (MAX_ADDRESS
- (UINTN
)Destination
))){
1855 return RETURN_INVALID_PARAMETER
;
1859 // 4 ascii per 3 bytes + NULL
1861 RequiredSize
= ((SourceLength
+ 2) / 3) * 4 + 1;
1862 if ((Destination
== NULL
) || *DestinationSize
< RequiredSize
) {
1863 *DestinationSize
= RequiredSize
;
1864 return RETURN_BUFFER_TOO_SMALL
;
1867 Left
= SourceLength
;
1870 // Encode 24 bits (three bytes) into 4 ascii characters
1874 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2 ];
1875 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4) + ((Source
[1] & 0xf0) >> 4)];
1876 *Destination
++ = EncodingTable
[((Source
[1] & 0x0f) << 2) + ((Source
[2] & 0xc0) >> 6)];
1877 *Destination
++ = EncodingTable
[( Source
[2] & 0x3f)];
1883 // Handle the remainder, and add padding '=' characters as necessary.
1889 // No bytes Left, done.
1895 // One more data byte, two pad characters
1897 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2];
1898 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4)];
1899 *Destination
++ = '=';
1900 *Destination
++ = '=';
1905 // Two more data bytes, and one pad character
1907 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2];
1908 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4) + ((Source
[1] & 0xf0) >> 4)];
1909 *Destination
++ = EncodingTable
[((Source
[1] & 0x0f) << 2)];
1910 *Destination
++ = '=';
1914 // Add terminating NULL
1916 *Destination
= '\0';
1917 return RETURN_SUCCESS
;
1921 Convert Base64 ascii string to binary data based on RFC4648.
1923 Produce Null-terminated binary data in the output buffer specified by Destination and DestinationSize.
1924 The binary data is produced by converting the Base64 ascii string specified by Source and SourceLength.
1926 @param Source Input ASCII characters
1927 @param SourceLength Number of ASCII characters
1928 @param Destination Pointer to output buffer
1929 @param DestinationSize Caller is responsible for passing in buffer of at least DestinationSize.
1930 Set 0 to get the size needed. Set to bytes stored on return.
1932 @retval RETURN_SUCCESS When binary buffer is filled in.
1933 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
1934 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS -(UINTN)Destination ).
1935 @retval RETURN_INVALID_PARAMETER If there is any invalid character in input stream.
1936 @retval RETURN_BUFFER_TOO_SMALL If buffer length is smaller than required buffer size.
1941 IN CONST CHAR8
*Source
,
1942 IN UINTN SourceLength
,
1943 OUT UINT8
*Destination OPTIONAL
,
1944 IN OUT UINTN
*DestinationSize
1952 UINTN DestinationIndex
;
1954 UINTN ActualSourceLength
;
1957 // Check pointers are not NULL
1959 if ((Source
== NULL
) || (DestinationSize
== NULL
)) {
1960 return RETURN_INVALID_PARAMETER
;
1964 // Check if SourceLength or DestinationSize is valid
1966 if ((SourceLength
>= (MAX_ADDRESS
- (UINTN
)Source
)) || (*DestinationSize
>= (MAX_ADDRESS
- (UINTN
)Destination
))){
1967 return RETURN_INVALID_PARAMETER
;
1970 ActualSourceLength
= 0;
1974 // Determine the actual number of valid characters in the string.
1975 // All invalid characters except selected white space characters,
1976 // will cause the Base64 string to be rejected. White space to allow
1977 // properly formatted XML will be ignored.
1979 // See section 3.3 of RFC 4648.
1981 for (SourceIndex
= 0; SourceIndex
< SourceLength
; SourceIndex
++) {
1984 // '=' is part of the quantum
1986 if (Source
[SourceIndex
] == '=') {
1987 ActualSourceLength
++;
1991 // Only two '=' characters can be valid.
1993 if (BufferSize
< -2) {
1994 return RETURN_INVALID_PARAMETER
;
1998 Chr
= Source
[SourceIndex
];
1999 if (BAD_V
!= DecodingTable
[(UINT8
) Chr
]) {
2002 // The '=' characters are only valid at the end, so any
2003 // valid character after an '=', will be flagged as an error.
2005 if (BufferSize
< 0) {
2006 return RETURN_INVALID_PARAMETER
;
2008 ActualSourceLength
++;
2013 // The reset of the decoder will ignore all invalid characters allowed here.
2014 // Ignoring selected white space is useful. In this case, the decoder will
2015 // ignore ' ', '\t', '\n', and '\r'.
2017 if ((Chr
!= ' ') &&(Chr
!= '\t') &&(Chr
!= '\n') &&(Chr
!= '\r')) {
2018 return RETURN_INVALID_PARAMETER
;
2025 // The Base64 character string must be a multiple of 4 character quantums.
2027 if (ActualSourceLength
% 4 != 0) {
2028 return RETURN_INVALID_PARAMETER
;
2031 BufferSize
+= ActualSourceLength
/ 4 * 3;
2032 if (BufferSize
< 0) {
2033 return RETURN_INVALID_PARAMETER
;
2037 // BufferSize is >= 0
2039 if ((Destination
== NULL
) || (*DestinationSize
< (UINTN
) BufferSize
)) {
2040 *DestinationSize
= BufferSize
;
2041 return RETURN_BUFFER_TOO_SMALL
;
2045 // If no decodable characters, return a size of zero. RFC 4686 test vector 1.
2047 if (ActualSourceLength
== 0) {
2048 *DestinationSize
= 0;
2049 return RETURN_SUCCESS
;
2053 // Input data is verified to be a multiple of 4 valid charcters. Process four
2054 // characters at a time. Uncounted (ie. invalid) characters will be ignored.
2056 for (SourceIndex
= 0, DestinationIndex
= 0; (SourceIndex
< SourceLength
) && (DestinationIndex
< *DestinationSize
); ) {
2060 // Get 24 bits of data from 4 input characters, each character representing 6 bits
2062 for (Index
= 0; Index
< 4; Index
++) {
2064 Chr
= DecodingTable
[(UINT8
) Source
[SourceIndex
++]];
2065 } while (Chr
== BAD_V
);
2067 Value
|= (UINT32
)Chr
;
2071 // Store 3 bytes of binary data (24 bits)
2073 *Destination
++ = (UINT8
) (Value
>> 16);
2077 // Due to the '=' special cases for the two bytes at the end,
2078 // we have to check the length and not store the padding data
2080 if (DestinationIndex
++ < *DestinationSize
) {
2081 *Destination
++ = (UINT8
) (Value
>> 8);
2083 if (DestinationIndex
++ < *DestinationSize
) {
2084 *Destination
++ = (UINT8
) Value
;
2088 return RETURN_SUCCESS
;
2092 Converts an 8-bit value to an 8-bit BCD value.
2094 Converts the 8-bit value specified by Value to BCD. The BCD value is
2097 If Value >= 100, then ASSERT().
2099 @param Value The 8-bit value to convert to BCD. Range 0..99.
2101 @return The BCD value.
2110 ASSERT (Value
< 100);
2111 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2115 Converts an 8-bit BCD value to an 8-bit value.
2117 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2120 If Value >= 0xA0, then ASSERT().
2121 If (Value & 0x0F) >= 0x0A, then ASSERT().
2123 @param Value The 8-bit BCD value to convert to an 8-bit value.
2125 @return The 8-bit value is returned.
2134 ASSERT (Value
< 0xa0);
2135 ASSERT ((Value
& 0xf) < 0xa);
2136 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));