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);
1760 STATIC CHAR8 EncodingTable
[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
1761 "abcdefghijklmnopqrstuvwxyz"
1765 Convert binary data to a Base64 encoded ascii string based on RFC4648.
1767 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
1768 The Ascii string is produced by converting the data string specified by Source and SourceLength.
1770 @param Source Input UINT8 data
1771 @param SourceLength Number of UINT8 bytes of data
1772 @param Destination Pointer to output string buffer
1773 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
1774 Caller is responsible for passing in buffer of DestinationSize
1776 @retval RETURN_SUCCESS When ascii buffer is filled in.
1777 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
1778 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
1779 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
1780 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
1786 IN CONST UINT8
*Source
,
1787 IN UINTN SourceLength
,
1788 OUT CHAR8
*Destination OPTIONAL
,
1789 IN OUT UINTN
*DestinationSize
1797 // Check pointers, and SourceLength is valid
1799 if ((Source
== NULL
) || (DestinationSize
== NULL
)) {
1800 return RETURN_INVALID_PARAMETER
;
1804 // Allow for RFC 4648 test vector 1
1806 if (SourceLength
== 0) {
1807 if (*DestinationSize
< 1) {
1808 *DestinationSize
= 1;
1809 return RETURN_BUFFER_TOO_SMALL
;
1811 *DestinationSize
= 1;
1812 *Destination
= '\0';
1813 return RETURN_SUCCESS
;
1817 // Check if SourceLength or DestinationSize is valid
1819 if ((SourceLength
>= (MAX_ADDRESS
- (UINTN
)Source
)) || (*DestinationSize
>= (MAX_ADDRESS
- (UINTN
)Destination
))){
1820 return RETURN_INVALID_PARAMETER
;
1824 // 4 ascii per 3 bytes + NULL
1826 RequiredSize
= ((SourceLength
+ 2) / 3) * 4 + 1;
1827 if ((Destination
== NULL
) || *DestinationSize
< RequiredSize
) {
1828 *DestinationSize
= RequiredSize
;
1829 return RETURN_BUFFER_TOO_SMALL
;
1832 Left
= SourceLength
;
1835 // Encode 24 bits (three bytes) into 4 ascii characters
1839 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2 ];
1840 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4) + ((Source
[1] & 0xf0) >> 4)];
1841 *Destination
++ = EncodingTable
[((Source
[1] & 0x0f) << 2) + ((Source
[2] & 0xc0) >> 6)];
1842 *Destination
++ = EncodingTable
[( Source
[2] & 0x3f)];
1848 // Handle the remainder, and add padding '=' characters as necessary.
1854 // No bytes Left, done.
1860 // One more data byte, two pad characters
1862 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2];
1863 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4)];
1864 *Destination
++ = '=';
1865 *Destination
++ = '=';
1870 // Two more data bytes, and one pad character
1872 *Destination
++ = EncodingTable
[( Source
[0] & 0xfc) >> 2];
1873 *Destination
++ = EncodingTable
[((Source
[0] & 0x03) << 4) + ((Source
[1] & 0xf0) >> 4)];
1874 *Destination
++ = EncodingTable
[((Source
[1] & 0x0f) << 2)];
1875 *Destination
++ = '=';
1879 // Add terminating NULL
1881 *Destination
= '\0';
1882 return RETURN_SUCCESS
;
1886 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
1889 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
1891 Whitespace is ignored at all positions:
1892 - 0x09 ('\t') horizontal tab
1893 - 0x0A ('\n') new line
1894 - 0x0B ('\v') vertical tab
1895 - 0x0C ('\f') form feed
1896 - 0x0D ('\r') carriage return
1899 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
1900 and enforced at the end of the Base64 ASCII encoded data, and only there.
1902 Other characters outside of the encoding alphabet cause the function to
1903 reject the Base64 ASCII encoded data.
1905 @param[in] Source Array of CHAR8 elements containing the Base64
1906 ASCII encoding. May be NULL if SourceSize is
1909 @param[in] SourceSize Number of CHAR8 elements in Source.
1911 @param[out] Destination Array of UINT8 elements receiving the decoded
1912 8-bit binary representation. Allocated by the
1913 caller. May be NULL if DestinationSize is
1914 zero on input. If NULL, decoding is
1915 performed, but the 8-bit binary
1916 representation is not stored. If non-NULL and
1917 the function returns an error, the contents
1918 of Destination are indeterminate.
1920 @param[in,out] DestinationSize On input, the number of UINT8 elements that
1921 the caller allocated for Destination. On
1922 output, if the function returns
1923 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
1924 the number of UINT8 elements that are
1925 required for decoding the Base64 ASCII
1926 representation. If the function returns a
1927 value different from both RETURN_SUCCESS and
1928 RETURN_BUFFER_TOO_SMALL, then DestinationSize
1929 is indeterminate on output.
1931 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
1932 been decoded to on-output DestinationSize
1933 UINT8 elements at Destination. Note that
1934 RETURN_SUCCESS covers the case when
1935 DestinationSize is zero on input, and
1936 Source decodes to zero bytes (due to
1937 containing at most ignored whitespace).
1939 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
1940 large enough for decoding SourceSize CHAR8
1941 elements at Source. The required number of
1942 UINT8 elements has been stored to
1945 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
1947 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
1949 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
1952 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
1953 SourceSize) would wrap around MAX_ADDRESS.
1955 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
1956 DestinationSize) would wrap around
1957 MAX_ADDRESS, as specified on input.
1959 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
1960 and CHAR8[SourceSize] at Source overlaps
1961 UINT8[DestinationSize] at Destination, as
1964 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
1970 IN CONST CHAR8
*Source OPTIONAL
,
1971 IN UINTN SourceSize
,
1972 OUT UINT8
*Destination OPTIONAL
,
1973 IN OUT UINTN
*DestinationSize
1977 return RETURN_INVALID_PARAMETER
;
1981 Converts an 8-bit value to an 8-bit BCD value.
1983 Converts the 8-bit value specified by Value to BCD. The BCD value is
1986 If Value >= 100, then ASSERT().
1988 @param Value The 8-bit value to convert to BCD. Range 0..99.
1990 @return The BCD value.
1999 ASSERT (Value
< 100);
2000 return (UINT8
) (((Value
/ 10) << 4) | (Value
% 10));
2004 Converts an 8-bit BCD value to an 8-bit value.
2006 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2009 If Value >= 0xA0, then ASSERT().
2010 If (Value & 0x0F) >= 0x0A, then ASSERT().
2012 @param Value The 8-bit BCD value to convert to an 8-bit value.
2014 @return The 8-bit value is returned.
2023 ASSERT (Value
< 0xa0);
2024 ASSERT ((Value
& 0xf) < 0xa);
2025 return (UINT8
) ((Value
>> 4) * 10 + (Value
& 0xf));