1) Added BIT0, BIT1, …, BIT63 to the Base Defines
[mirror_edk2.git] / MdePkg / Library / BaseLib / String.c
CommitLineData
d958721a 1/** @file
2 Unicode and ASCII string primatives.
3
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: String.c
14
15**/
16
17#include "BaseLibInternals.h"
18
19/**
20 Copies one Null-terminated Unicode string to another Null-terminated Unicode
21 string and returns the new Unicode string.
22
23 This function copies the contents of the Unicode string Source to the Unicode
24 string Destination, and returns Destination. If Source and Destination
25 overlap, then the results are undefined.
26
27 If Destination is NULL, then ASSERT().
28 If Source is NULL, then ASSERT().
29 If Source and Destination overlap, then ASSERT().
30 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
31 PcdMaximumUnicodeStringLength Unicode characters not including the
32 Null-terminator, then ASSERT().
33
34 @param Destination Pointer to a Null-terminated Unicode string.
35 @param Source Pointer to a Null-terminated Unicode string.
36
37 @return Destiantion
38
39**/
40CHAR16 *
41EFIAPI
42StrCpy (
43 OUT CHAR16 *Destination,
44 IN CONST CHAR16 *Source
45 )
46{
47 CHAR16 *ReturnValue;
48
49 //
50 // Destination cannot be NULL
51 //
52 ASSERT (Destination != NULL);
53
54 //
55 // Destination and source cannot overlap
56 //
57 ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
58 ASSERT ((UINTN)(Source - Destination) > StrLen (Source));
59
60 ReturnValue = Destination;
61 while (*Source) {
62 *(Destination++) = *(Source++);
63 }
64 *Destination = 0;
65 return ReturnValue;
66}
67
68/**
69 Copies one Null-terminated Unicode string with a maximum length to another
70 Null-terminated Unicode string with a maximum length and returns the new
71 Unicode string.
72
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
79 undefined.
80
81 If Destination is NULL, then ASSERT().
82 If Source is NULL, then ASSERT().
83 If Source and Destination overlap, then ASSERT().
84 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
85 PcdMaximumUnicodeStringLength Unicode characters not including the
86 Null-terminator, then ASSERT().
87
88 @param Destination Pointer to a Null-terminated Unicode string.
89 @param Source Pointer to a Null-terminated Unicode string.
90 @param Length Maximum number of Unicode characters to copy.
91
92 @return Destination
93
94**/
95CHAR16 *
96EFIAPI
97StrnCpy (
98 OUT CHAR16 *Destination,
99 IN CONST CHAR16 *Source,
100 IN UINTN Length
101 )
102{
103 CHAR16 *ReturnValue;
104
105 if (Length == 0) {
106 return Destination;
107 }
108
109 //
110 // Destination cannot be NULL if Length is not zero
111 //
112 ASSERT (Destination != NULL);
113
114 //
115 // Destination and source cannot overlap
116 // Q: Does Source have to be NULL-terminated?
117 //
118 ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
119 ASSERT ((UINTN)(Source - Destination) >= Length);
120
121 ReturnValue = Destination;
122
123 while ((*Source != L'\0') && (Length > 0)) {
124 *(Destination++) = *(Source++);
125 Length--;
126 }
127
128 ZeroMem (Destination, Length * sizeof (*Destination));
129 return ReturnValue;
130}
131
132/**
133 Returns the length of a Null-terminated Unicode string.
134
135 This function returns the number of Unicode characters in the Null-terminated
136 Unicode string specified by String.
137
138 If String is NULL, then ASSERT().
139 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
140 PcdMaximumUnicodeStringLength Unicode characters not including the
141 Null-terminator, then ASSERT().
142
143 @param String Pointer to a Null-terminated Unicode string.
144
145 @return The length of String.
146
147**/
148UINTN
149EFIAPI
150StrLen (
151 IN CONST CHAR16 *String
152 )
153{
154 UINTN Length;
155
156 ASSERT (String != NULL);
157
158 for (Length = 0; *String != L'\0'; String++, Length++) {
159 //
160 // If PcdMaximumUnicodeStringLength is not zero,
161 // length should not more than PcdMaximumUnicodeStringLength
162 //
163 if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
164 ASSERT (Length < PcdGet32 (PcdMaximumUnicodeStringLength));
165 }
166 }
167 return Length;
168}
169
170/**
171 Returns the size of a Null-terminated Unicode string in bytes, including the
172 Null terminator.
173
174 This function returns the size, in bytes, of the Null-terminated Unicode
175 string specified by String.
176
177 If String is NULL, then ASSERT().
178 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
179 PcdMaximumUnicodeStringLength Unicode characters not including the
180 Null-terminator, then ASSERT().
181
182 @param String Pointer to a Null-terminated Unicode string.
183
184 @return The size of String.
185
186**/
187UINTN
188EFIAPI
189StrSize (
190 IN CONST CHAR16 *String
191 )
192{
193 return (StrLen (String) + 1) * sizeof (*String);
194}
195
196/**
197 Compares two Null-terminated Unicode strings, and returns the difference
198 between the first mismatched Unicode characters.
199
200 This function compares the Null-terminated Unicode string FirstString to the
201 Null-terminated Unicode string SecondString. If FirstString is identical to
202 SecondString, then 0 is returned. Otherwise, the value returned is the first
203 mismatched Unicode character in SecondString subtracted from the first
204 mismatched Unicode character in FirstString.
205
206 If FirstString is NULL, then ASSERT().
207 If SecondString is NULL, then ASSERT().
208 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
209 than PcdMaximumUnicodeStringLength Unicode characters not including the
210 Null-terminator, then ASSERT().
211 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
212 than PcdMaximumUnicodeStringLength Unicode characters not including the
213 Null-terminator, then ASSERT().
214
215 @param FirstString Pointer to a Null-terminated Unicode string.
216 @param SecondString Pointer to a Null-terminated Unicode string.
217
218 @retval 0 FirstString is identical to SecondString.
219 @retval !=0 FirstString is not identical to SecondString.
220
221**/
222INTN
223EFIAPI
224StrCmp (
225 IN CONST CHAR16 *FirstString,
226 IN CONST CHAR16 *SecondString
227 )
228{
229 //
230 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
231 //
232 ASSERT (StrSize (FirstString) != 0);
233 ASSERT (StrSize (SecondString) != 0);
234
235 while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {
236 FirstString++;
237 SecondString++;
238 }
239 return *FirstString - *SecondString;
240}
241
242/**
243 Compares two Null-terminated Unicode strings with maximum lengths, and
244 returns the difference between the first mismatched Unicode characters.
245
246 This function compares the Null-terminated Unicode string FirstString to the
247 Null-terminated Unicode string SecondString. At most, Length Unicode
248 characters will be compared. If Length is 0, then 0 is returned. If
249 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
250 value returned is the first mismatched Unicode character in SecondString
251 subtracted from the first mismatched Unicode character in FirstString.
252
253 If FirstString is NULL, then ASSERT().
254 If SecondString is NULL, then ASSERT().
255 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
256 than PcdMaximumUnicodeStringLength Unicode characters not including the
257 Null-terminator, then ASSERT().
258 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
259 than PcdMaximumUnicodeStringLength Unicode characters not including the
260 Null-terminator, then ASSERT().
261
262 @param FirstString Pointer to a Null-terminated Unicode string.
263 @param SecondString Pointer to a Null-terminated Unicode string.
264 @param Length Maximum number of Unicode characters to compare.
265
266 @retval 0 FirstString is identical to SecondString.
267 @retval !=0 FirstString is not identical to SecondString.
268
269**/
270INTN
271EFIAPI
272StrnCmp (
273 IN CONST CHAR16 *FirstString,
274 IN CONST CHAR16 *SecondString,
275 IN UINTN Length
276 )
277{
278 if (Length == 0) {
279 return 0;
280 }
281
282 //
283 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
284 // Length tests are performed inside StrLen().
285 //
286 ASSERT (StrSize (FirstString) != 0);
287 ASSERT (StrSize (SecondString) != 0);
288
289 while ((*FirstString != L'\0') &&
290 (*FirstString == *SecondString) &&
291 (Length > 1)) {
292 FirstString++;
293 SecondString++;
294 Length--;
295 }
296
297 return *FirstString - *SecondString;
298}
299
300/**
301 Concatenates one Null-terminated Unicode string to another Null-terminated
302 Unicode string, and returns the concatenated Unicode string.
303
304 This function concatenates two Null-terminated Unicode strings. The contents
305 of Null-terminated Unicode string Source are concatenated to the end of
306 Null-terminated Unicode string Destination. The Null-terminated concatenated
307 Unicode String is returned. If Source and Destination overlap, then the
308 results are undefined.
309
310 If Destination is NULL, then ASSERT().
311 If Source is NULL, then ASSERT().
312 If Source and Destination overlap, then ASSERT().
313 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
314 than PcdMaximumUnicodeStringLength Unicode characters not including the
315 Null-terminator, then ASSERT().
316 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
317 PcdMaximumUnicodeStringLength Unicode characters not including the
318 Null-terminator, then ASSERT().
319 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
320 and Source results in a Unicode string with more than
321 PcdMaximumUnicodeStringLength Unicode characters not including the
322 Null-terminator, then ASSERT().
323
324 @param Destination Pointer to a Null-terminated Unicode string.
325 @param Source Pointer to a Null-terminated Unicode string.
326
327 @return Destination
328
329**/
330CHAR16 *
331EFIAPI
332StrCat (
333 IN OUT CHAR16 *Destination,
334 IN CONST CHAR16 *Source
335 )
336{
337 StrCpy (Destination + StrLen (Destination), Source);
338
339 //
340 // Size of the resulting string should never be zero.
341 // PcdMaximumUnicodeStringLength is tested inside StrLen().
342 //
343 ASSERT (StrSize (Destination) != 0);
344 return Destination;
345}
346
347/**
348 Concatenates one Null-terminated Unicode string with a maximum length to the
349 end of another Null-terminated Unicode string, and returns the concatenated
350 Unicode string.
351
352 This function concatenates two Null-terminated Unicode strings. The contents
353 of Null-terminated Unicode string Source are concatenated to the end of
354 Null-terminated Unicode string Destination, and Destination is returned. At
355 most, Length Unicode characters are concatenated from Source to the end of
356 Destination, and Destination is always Null-terminated. If Length is 0, then
357 Destination is returned unmodified. If Source and Destination overlap, then
358 the results are undefined.
359
360 If Destination is NULL, then ASSERT().
361 If Source is NULL, then ASSERT().
362 If Source and Destination overlap, then ASSERT().
363 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
364 than PcdMaximumUnicodeStringLength Unicode characters not including the
365 Null-terminator, then ASSERT().
366 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
367 PcdMaximumUnicodeStringLength Unicode characters not including the
368 Null-terminator, then ASSERT().
369 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
370 and Source results in a Unicode string with more than
371 PcdMaximumUnicodeStringLength Unicode characters not including the
372 Null-terminator, then ASSERT().
373
374 @param Destination Pointer to a Null-terminated Unicode string.
375 @param Source Pointer to a Null-terminated Unicode string.
376 @param Length Maximum number of Unicode characters to concatenate from
377 Source.
378
379 @return Destination
380
381**/
382CHAR16 *
383EFIAPI
384StrnCat (
385 IN OUT CHAR16 *Destination,
386 IN CONST CHAR16 *Source,
387 IN UINTN Length
388 )
389{
390 StrnCpy (Destination + StrLen (Destination), Source, Length);
391
392 //
393 // Size of the resulting string should never be zero.
394 // PcdMaximumUnicodeStringLength is tested inside StrLen().
395 //
396 ASSERT (StrSize (Destination) != 0);
397 return Destination;
398}
399
400/**
401 Returns the first occurance of a Null-terminated Unicode sub-string
402 in a Null-terminated Unicode string.
403
404 This function scans the contents of the Null-terminated Unicode string
405 specified by String and returns the first occurrence of SearchString.
406 If SearchString is not found in String, then NULL is returned. If
407 the length of SearchString is zero, then String is
408 returned.
409
410 If String is NULL, then ASSERT().
411 If String is not aligned on a 16-bit boundary, then ASSERT().
412 If SearchString is NULL, then ASSERT().
413 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
414
415 If PcdMaximumUnicodeStringLength is not zero, and SearchString
416 or String contains more than PcdMaximumUnicodeStringLength Unicode
417 characters not including the Null-terminator, then ASSERT().
418
419 @param String Pointer to a Null-terminated Unicode string.
420 @param SearchString Pointer to a Null-terminated Unicode string to search for.
421
422 @retval NULL If the SearchString does not appear in String.
423 @retval !NULL If there is a match.
424
425**/
426CHAR16 *
427EFIAPI
428StrStr (
429 IN CONST CHAR16 *String,
430 IN CONST CHAR16 *SearchString
431 )
432{
433 CONST CHAR16 *FirstMatch;
434 CONST CHAR16 *SearchStringTmp;
435
436 ASSERT (String != NULL);
437 ASSERT (((UINTN) String & 0x01) == 0);
438 ASSERT (SearchString != NULL);
439 ASSERT (((UINTN) SearchString & 0x01) == 0);
440
441 //
442 // If PcdMaximumUnicodeStringLength is not zero,
443 // length of String should not more than PcdMaximumUnicodeStringLength
444 //
445 if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
446 ASSERT (StrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
447 }
448
449 //
450 // If PcdMaximumUnicodeStringLength is not zero,
451 // length of SearchString should not more than PcdMaximumUnicodeStringLength
452 //
453 if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
454 ASSERT (StrLen (SearchString) < PcdGet32 (PcdMaximumAsciiStringLength));
455 }
456
457 while (*String != '\0') {
458 SearchStringTmp = SearchString;
459 FirstMatch = String;
460
461 while ((*String == *SearchStringTmp)
462 && (*SearchStringTmp != '\0')
463 && (*String != '\0')) {
464 String++;
465 SearchStringTmp++;
466 }
467
468 if (*SearchStringTmp == '\0') {
469 return (CHAR16 *) FirstMatch;
470 }
471
472 if (SearchStringTmp == SearchString) {
473 //
474 // If no character from SearchString match,
475 // move the pointer to the String under search
476 // by one character.
477 //
478 String++;
479 }
480 }
481
482 return NULL;
483}
484
485/**
486 Check if a Unicode character is a decimal character.
487
488 This internal function checks if a Unicode character is a
489 decimal character. The valid decimal character is from
490 L'0' to L'9'.
491
492
493 @param Char The character to check against.
494
495 @retval TRUE If the Char is a decmial character.
496 @retval FALSE Otherwise.
497
498**/
499STATIC
500BOOLEAN
501InternalIsDecimalDigitCharacter (
502 IN CHAR16 Char
503 )
504{
505 return (BOOLEAN) (Char >= L'0' && Char <= L'9');
506}
507
508/**
509 Convert a Unicode character to upper case only if
510 it maps to a valid small-case ASCII character.
511
512 This internal function only deal with Unicode character
513 which maps to a valid small-case ASII character, i.e.
514 L'a' to L'z'. For other Unicode character, the input character
515 is returned directly.
516
517
518 @param Char The character to convert.
519
520 @retval LowerCharacter If the Char is with range L'a' to L'z'.
521 @retval Unchanged Otherwise.
522
523**/
524STATIC
525CHAR16
526InternalCharToUpper (
527 IN CHAR16 Char
528 )
529{
530 if (Char >= L'a' && Char <= L'z') {
531 return Char - (L'a' - L'A');
532 }
533
534 return Char;
535}
536
537/**
538 Convert a Unicode character to numerical value.
539
540 This internal function only deal with Unicode character
541 which maps to a valid hexadecimal ASII character, i.e.
542 L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
543 Unicode character, the value returned does not make sense.
544
545 @param Char The character to convert.
546
547 @retval UINTN The numerical value converted.
548
549**/
550STATIC
551UINTN
552InternalHexCharToUintn (
553 IN CHAR16 Char
554 )
555{
556 if (InternalIsDecimalDigitCharacter (Char)) {
557 return Char - L'0';
558 }
559
560 return (UINTN) (10 + InternalCharToUpper (Char) - L'A');
561}
562
563/**
564 Check if a Unicode character is a hexadecimal character.
565
566 This internal function checks if a Unicode character is a
567 decimal character. The valid hexadecimal character is
568 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
569
570
571 @param Char The character to check against.
572
573 @retval TRUE If the Char is a hexadecmial character.
574 @retval FALSE Otherwise.
575
576**/
577STATIC
578BOOLEAN
579InternalIsHexaDecimalDigitCharacter (
580 IN CHAR16 Char
581 )
582{
583
584 return (BOOLEAN) (InternalIsDecimalDigitCharacter (Char) ||
585 (Char >= L'A' && Char <= L'F') ||
586 (Char >= L'a' && Char <= L'f'));
587}
588
589/**
590 Convert a Null-terminated Unicode decimal string to a value of
591 type UINTN.
592
593 This function returns a value of type UINTN by interpreting the contents
594 of the Unicode string specified by String as a decimal number. The format
595 of the input Unicode string String is:
596
597 [spaces] [decimal digits].
598
599 The valid decimal digit character is in the range [0-9]. The
600 function will ignore the pad space, which includes spaces or
601 tab characters, before [decimal digits]. The running zero in the
602 beginning of [decimal digits] will be ignored. Then, the function
603 stops at the first character that is a not a valid decimal character
604 or a Null-terminator, whichever one comes first.
605
606 If String is NULL, then ASSERT().
607 If String is not aligned in a 16-bit boundary, then ASSERT().
608 If String has only pad spaces, then 0 is returned.
609 If String has no pad spaces or valid decimal digits,
610 then 0 is returned.
611 If the number represented by String overflows according
612 to the range defined by UINTN, then ASSERT().
613
614 If PcdMaximumUnicodeStringLength is not zero, and String contains
615 more than PcdMaximumUnicodeStringLength Unicode characters not including
616 the Null-terminator, then ASSERT().
617
618 @param String Pointer to a Null-terminated Unicode string.
619
620 @retval UINTN
621
622**/
623UINTN
624EFIAPI
625StrDecimalToUintn (
626 IN CONST CHAR16 *String
627 )
628{
629 UINTN Result;
630
631 ASSERT (String != NULL);
632 ASSERT (((UINTN) String & 0x01) == 0);
633 ASSERT (StrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
634
635 //
636 // Ignore the pad spaces (space or tab)
637 //
638 while ((*String == L' ') || (*String == L'\t')) {
639 String++;
640 }
641
642 //
643 // Ignore leading Zeros after the spaces
644 //
645 while (*String == L'0') {
646 String++;
647 }
648
649 Result = 0;
650
651 while (InternalIsDecimalDigitCharacter (*String)) {
652 //
653 // If the number represented by String overflows according
654 // to the range defined by UINTN, then ASSERT().
655 //
656 ASSERT ((Result < QUIENT_MAX_UINTN_DIVIDED_BY_10) ||
657 ((Result == QUIENT_MAX_UINTN_DIVIDED_BY_10) &&
658 (*String - L'0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10)
659 );
660
661 Result = Result * 10 + (*String - L'0');
662 String++;
663 }
664
665 return Result;
666}
667
668
669/**
670 Convert a Null-terminated Unicode decimal string to a value of
671 type UINT64.
672
673 This function returns a value of type UINT64 by interpreting the contents
674 of the Unicode string specified by String as a decimal number. The format
675 of the input Unicode string String is:
676
677 [spaces] [decimal digits].
678
679 The valid decimal digit character is in the range [0-9]. The
680 function will ignore the pad space, which includes spaces or
681 tab characters, before [decimal digits]. The running zero in the
682 beginning of [decimal digits] will be ignored. Then, the function
683 stops at the first character that is a not a valid decimal character
684 or a Null-terminator, whichever one comes first.
685
686 If String is NULL, then ASSERT().
687 If String is not aligned in a 16-bit boundary, then ASSERT().
688 If String has only pad spaces, then 0 is returned.
689 If String has no pad spaces or valid decimal digits,
690 then 0 is returned.
691 If the number represented by String overflows according
692 to the range defined by UINT64, then ASSERT().
693
694 If PcdMaximumUnicodeStringLength is not zero, and String contains
695 more than PcdMaximumUnicodeStringLength Unicode characters not including
696 the Null-terminator, then ASSERT().
697
698 @param String Pointer to a Null-terminated Unicode string.
699
700 @retval UINT64
701
702**/
703UINT64
704EFIAPI
705StrDecimalToUint64 (
706 IN CONST CHAR16 *String
707 )
708{
709 UINT64 Result;
710
711 ASSERT (String != NULL);
712 ASSERT (((UINTN) String & 0x01) == 0);
713 ASSERT (StrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
714
715 //
716 // Ignore the pad spaces (space or tab)
717 //
718 while ((*String == L' ') || (*String == L'\t')) {
719 String++;
720 }
721
722 //
723 // Ignore leading Zeros after the spaces
724 //
725 while (*String == L'0') {
726 String++;
727 }
728
729 Result = 0;
730
731 while (InternalIsDecimalDigitCharacter (*String)) {
732 //
733 // If the number represented by String overflows according
734 // to the range defined by UINTN, then ASSERT().
735 //
736 ASSERT ((Result < QUIENT_MAX_UINT64_DIVIDED_BY_10) ||
737 ((Result == QUIENT_MAX_UINT64_DIVIDED_BY_10) &&
738 (*String - L'0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10)
739 );
740
741 Result = MultU64x32 (Result, 10) + (*String - L'0');
742 String++;
743 }
744
745 return Result;
746}
747
748/**
749 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
750
751 This function returns a value of type UINTN by interpreting the contents
752 of the Unicode string specified by String as a hexadecimal number.
753 The format of the input Unicode string String is:
754
755 [spaces][zeros][x][hexadecimal digits].
756
757 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
758 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
759 If "x" appears in the input string, it must be prefixed with at least one 0.
760 The function will ignore the pad space, which includes spaces or tab characters,
761 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
762 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
763 first valid hexadecimal digit. Then, the function stops at the first character that is
764 a not a valid hexadecimal character or NULL, whichever one comes first.
765
766 If String is NULL, then ASSERT().
767 If String is not aligned in a 16-bit boundary, then ASSERT().
768 If String has only pad spaces, then zero is returned.
769 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
770 then zero is returned.
771 If the number represented by String overflows according to the range defined by
772 UINTN, then ASSERT().
773
774 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
775 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
776 then ASSERT().
777
778 @param String Pointer to a Null-terminated Unicode string.
779
780 @retval UINTN
781
782**/
783UINTN
784EFIAPI
785StrHexToUintn (
786 IN CONST CHAR16 *String
787 )
788{
789 UINTN Result;
790
791 ASSERT (String != NULL);
792 ASSERT (StrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
793
794 //
795 // Ignore the pad spaces (space or tab)
796 //
797 while ((*String == L' ') || (*String == L'\t')) {
798 String++;
799 }
800
801 //
802 // Ignore leading Zeros after the spaces
803 //
804 while (*String == L'0') {
805 String++;
806 }
807
808 if (InternalCharToUpper (*String) == L'X') {
809 ASSERT (*(String - 1) == L'0');
810 if (*(String - 1) != L'0') {
811 return 0;
812 }
813 //
814 // Skip the 'X'
815 //
816 String++;
817 }
818
819 Result = 0;
820
821 while (InternalIsHexaDecimalDigitCharacter (*String)) {
822 //
823 // If the Hex Number represented by String overflows according
824 // to the range defined by UINTN, then ASSERT().
825 //
826 ASSERT ((Result < QUIENT_MAX_UINTN_DIVIDED_BY_16) ||
827 ((Result == QUIENT_MAX_UINTN_DIVIDED_BY_16) &&
828 (InternalHexCharToUintn (*String) <= REMINDER_MAX_UINTN_DIVIDED_BY_16))
829 );
830
831 Result = (Result << 4) + InternalHexCharToUintn (*String);
832 String++;
833 }
834
835 return Result;
836}
837
838
839/**
840 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
841
842 This function returns a value of type UINT64 by interpreting the contents
843 of the Unicode string specified by String as a hexadecimal number.
844 The format of the input Unicode string String is
845
846 [spaces][zeros][x][hexadecimal digits].
847
848 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
849 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
850 If "x" appears in the input string, it must be prefixed with at least one 0.
851 The function will ignore the pad space, which includes spaces or tab characters,
852 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
853 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
854 first valid hexadecimal digit. Then, the function stops at the first character that is
855 a not a valid hexadecimal character or NULL, whichever one comes first.
856
857 If String is NULL, then ASSERT().
858 If String is not aligned in a 16-bit boundary, then ASSERT().
859 If String has only pad spaces, then zero is returned.
860 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
861 then zero is returned.
862 If the number represented by String overflows according to the range defined by
863 UINT64, then ASSERT().
864
865 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
866 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
867 then ASSERT().
868
869 @param String Pointer to a Null-terminated Unicode string.
870
871 @retval UINT64
872
873**/
874UINT64
875EFIAPI
876StrHexToUint64 (
877 IN CONST CHAR16 *String
878 )
879{
880 UINT64 Result;
881
882 ASSERT (String != NULL);
883 ASSERT (StrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
884
885 //
886 // Ignore the pad spaces (space or tab)
887 //
888 while ((*String == L' ') || (*String == L'\t')) {
889 String++;
890 }
891
892 //
893 // Ignore leading Zeros after the spaces
894 //
895 while (*String == L'0') {
896 String++;
897 }
898
899 if (InternalCharToUpper (*String) == L'X') {
900 ASSERT (*(String - 1) == L'0');
901 if (*(String - 1) != L'0') {
902 return 0;
903 }
904 //
905 // Skip the 'X'
906 //
907 String++;
908 }
909
910 Result = 0;
911
912 while (InternalIsHexaDecimalDigitCharacter (*String)) {
913 //
914 // If the Hex Number represented by String overflows according
915 // to the range defined by UINTN, then ASSERT().
916 //
917 ASSERT ((Result < QUIENT_MAX_UINT64_DIVIDED_BY_16)||
918 ((Result == QUIENT_MAX_UINT64_DIVIDED_BY_16) &&
919 (InternalHexCharToUintn (*String) <= REMINDER_MAX_UINT64_DIVIDED_BY_16))
920 );
921
922 Result = LShiftU64 (Result, 4) + InternalHexCharToUintn (*String);
923 String++;
924 }
925
926 return Result;
927}
928
929/**
930 Check if a ASCII character is a decimal character.
931
932 This internal function checks if a Unicode character is a
933 decimal character. The valid decimal character is from
934 '0' to '9'.
935
936 @param Char The character to check against.
937
938 @retval TRUE If the Char is a decmial character.
939 @retval FALSE Otherwise.
940
941**/
942STATIC
943BOOLEAN
944InternalAsciiIsDecimalDigitCharacter (
945 IN CHAR8 Char
946 )
947{
948 return (BOOLEAN) (Char >= '0' && Char <= '9');
949}
950
951/**
952 Check if a ASCII character is a hexadecimal character.
953
954 This internal function checks if a ASCII character is a
955 decimal character. The valid hexadecimal character is
956 L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
957
958
959 @param Char The character to check against.
960
961 @retval TRUE If the Char is a hexadecmial character.
962 @retval FALSE Otherwise.
963
964**/
965STATIC
966BOOLEAN
967InternalAsciiIsHexaDecimalDigitCharacter (
968 IN CHAR8 Char
969 )
970{
971
972 return (BOOLEAN) (InternalAsciiIsDecimalDigitCharacter (Char) ||
973 (Char >= 'A' && Char <= 'F') ||
974 (Char >= 'a' && Char <= 'f'));
975}
976
977/**
978 Convert a Null-terminated Unicode string to a Null-terminated
979 ASCII string and returns the ASCII string.
980
981 This function converts the content of the Unicode string Source
982 to the ASCII string Destination by copying the lower 8 bits of
983 each Unicode character. It returns Destination. The function terminates
984 the ASCII string Destination by appending a Null-terminator character
985 at the end. The caller is responsible to make sure Destination points
986 to a buffer with size equal or greater than (StrLen (Source) + 1) in bytes.
987
988 If Destination is NULL, then ASSERT().
989 If Source is NULL, then ASSERT().
990 If Source is not aligned on a 16-bit boundary, then ASSERT().
991 If Source and Destination overlap, then ASSERT().
992
993 If any Unicode characters in Source contain non-zero value in
994 the upper 8 bits, then ASSERT().
995
996 If PcdMaximumUnicodeStringLength is not zero, and Source contains
997 more than PcdMaximumUnicodeStringLength Unicode characters not including
998 the Null-terminator, then ASSERT().
999
1000 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1001 than PcdMaximumAsciiStringLength Unicode characters not including the
1002 Null-terminator, then ASSERT().
1003
1004 @param Source Pointer to a Null-terminated Unicode string.
1005 @param Destination Pointer to a Null-terminated ASCII string.
1006
1007 @reture Destination
1008
1009**/
1010CHAR8 *
1011EFIAPI
1012UnicodeStrToAsciiStr (
1013 IN CONST CHAR16 *Source,
1014 OUT CHAR8 *Destination
1015 )
1016{
1017 ASSERT (Destination != NULL);
1018 ASSERT (Source != NULL);
1019
1020 //
1021 // Source and Destination should not overlap
1022 //
1023 ASSERT ((UINTN) ((CHAR16 *) Destination - Source) > StrLen (Source));
1024 ASSERT ((UINTN) ((CHAR8 *) Source - Destination) > StrLen (Source));
1025
1026 //
1027 // If PcdMaximumUnicodeStringLength is not zero,
1028 // length of Source should not more than PcdMaximumUnicodeStringLength
1029 //
1030 if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
1031 ASSERT (StrLen (Source) < PcdGet32 (PcdMaximumUnicodeStringLength));
1032 }
1033
1034 while (*Source != '\0') {
1035 //
1036 // If any Unicode characters in Source contain
1037 // non-zero value in the upper 8 bits, then ASSERT().
1038 //
1039 ASSERT (*Source < 0x100);
1040 *(Destination++) = (CHAR8) *(Source++);
1041 }
1042
1043 *Destination = '\0';
1044
1045 return Destination;
1046}
1047
1048
1049/**
1050 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1051 string and returns the new ASCII string.
1052
1053 This function copies the contents of the ASCII string Source to the ASCII
1054 string Destination, and returns Destination. If Source and Destination
1055 overlap, then the results are undefined.
1056
1057 If Destination is NULL, then ASSERT().
1058 If Source is NULL, then ASSERT().
1059 If Source and Destination overlap, then ASSERT().
1060 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1061 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1062 then ASSERT().
1063
1064 @param Destination Pointer to a Null-terminated ASCII string.
1065 @param Source Pointer to a Null-terminated ASCII string.
1066
1067 @return Destination
1068
1069**/
1070CHAR8 *
1071EFIAPI
1072AsciiStrCpy (
1073 OUT CHAR8 *Destination,
1074 IN CONST CHAR8 *Source
1075 )
1076{
1077 CHAR8 *ReturnValue;
1078
1079 //
1080 // Destination cannot be NULL
1081 //
1082 ASSERT (Destination != NULL);
1083
1084 //
1085 // Destination and source cannot overlap
1086 //
1087 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
1088 ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source));
1089
1090 ReturnValue = Destination;
1091 while (*Source) {
1092 *(Destination++) = *(Source++);
1093 }
1094 *Destination = 0;
1095 return ReturnValue;
1096}
1097
1098/**
1099 Copies one Null-terminated ASCII string with a maximum length to another
1100 Null-terminated ASCII string with a maximum length and returns the new ASCII
1101 string.
1102
1103 This function copies the contents of the ASCII string Source to the ASCII
1104 string Destination, and returns Destination. At most, Length ASCII characters
1105 are copied from Source to Destination. If Length is 0, then Destination is
1106 returned unmodified. If Length is greater that the number of ASCII characters
1107 in Source, then Destination is padded with Null ASCII characters. If Source
1108 and Destination overlap, then the results are undefined.
1109
1110 If Destination is NULL, then ASSERT().
1111 If Source is NULL, then ASSERT().
1112 If Source and Destination overlap, then ASSERT().
1113 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1114 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1115 then ASSERT().
1116
1117 @param Destination Pointer to a Null-terminated ASCII string.
1118 @param Source Pointer to a Null-terminated ASCII string.
1119 @param Length Maximum number of ASCII characters to copy.
1120
1121 @return Destination
1122
1123**/
1124CHAR8 *
1125EFIAPI
1126AsciiStrnCpy (
1127 OUT CHAR8 *Destination,
1128 IN CONST CHAR8 *Source,
1129 IN UINTN Length
1130 )
1131{
1132 CHAR8 *ReturnValue;
1133
1134 if (Length == 0) {
1135 return Destination;
1136 }
1137
1138 //
1139 // Destination cannot be NULL
1140 //
1141 ASSERT (Destination != NULL);
1142
1143 //
1144 // Destination and source cannot overlap
1145 //
1146 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
1147 ASSERT ((UINTN)(Source - Destination) >= Length);
1148
1149 ReturnValue = Destination;
1150
1151 while (*Source && Length > 0) {
1152 *(Destination++) = *(Source++);
1153 Length--;
1154 }
1155
1156 ZeroMem (Destination, Length * sizeof (*Destination));
1157 return ReturnValue;
1158}
1159
1160/**
1161 Returns the length of a Null-terminated ASCII string.
1162
1163 This function returns the number of ASCII characters in the Null-terminated
1164 ASCII string specified by String.
1165
1166 If String is NULL, then ASSERT().
1167 If PcdMaximumAsciiStringLength is not zero and String contains more than
1168 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1169 then ASSERT().
1170
1171 @param String Pointer to a Null-terminated ASCII string.
1172
1173 @return The length of String.
1174
1175**/
1176UINTN
1177EFIAPI
1178AsciiStrLen (
1179 IN CONST CHAR8 *String
1180 )
1181{
1182 UINTN Length;
1183
1184 ASSERT (String != NULL);
1185
1186 for (Length = 0; *String != '\0'; String++, Length++) {
1187 //
1188 // If PcdMaximumUnicodeStringLength is not zero,
1189 // length should not more than PcdMaximumUnicodeStringLength
1190 //
1191 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1192 ASSERT (Length < PcdGet32 (PcdMaximumAsciiStringLength));
1193 }
1194 }
1195 return Length;
1196}
1197
1198/**
1199 Returns the size of a Null-terminated ASCII string in bytes, including the
1200 Null terminator.
1201
1202 This function returns the size, in bytes, of the Null-terminated ASCII string
1203 specified by String.
1204
1205 If String is NULL, then ASSERT().
1206 If PcdMaximumAsciiStringLength is not zero and String contains more than
1207 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1208 then ASSERT().
1209
1210 @param String Pointer to a Null-terminated ASCII string.
1211
1212 @return The size of String.
1213
1214**/
1215UINTN
1216EFIAPI
1217AsciiStrSize (
1218 IN CONST CHAR8 *String
1219 )
1220{
1221 return (AsciiStrLen (String) + 1) * sizeof (*String);
1222}
1223
1224/**
1225 Compares two Null-terminated ASCII strings, and returns the difference
1226 between the first mismatched ASCII characters.
1227
1228 This function compares the Null-terminated ASCII string FirstString to the
1229 Null-terminated ASCII string SecondString. If FirstString is identical to
1230 SecondString, then 0 is returned. Otherwise, the value returned is the first
1231 mismatched ASCII character in SecondString subtracted from the first
1232 mismatched ASCII character in FirstString.
1233
1234 If FirstString is NULL, then ASSERT().
1235 If SecondString is NULL, then ASSERT().
1236 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1237 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1238 then ASSERT().
1239 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1240 than PcdMaximumAsciiStringLength ASCII characters not including the
1241 Null-terminator, then ASSERT().
1242
1243 @param FirstString Pointer to a Null-terminated ASCII string.
1244 @param SecondString Pointer to a Null-terminated ASCII string.
1245
1246 @retval 0 FirstString is identical to SecondString.
1247 @retval !=0 FirstString is not identical to SecondString.
1248
1249**/
1250INTN
1251EFIAPI
1252AsciiStrCmp (
1253 IN CONST CHAR8 *FirstString,
1254 IN CONST CHAR8 *SecondString
1255 )
1256{
1257 //
1258 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1259 //
1260 ASSERT (AsciiStrSize (FirstString));
1261 ASSERT (AsciiStrSize (SecondString));
1262
1263 while ((*FirstString != '\0') && (*FirstString == *SecondString)) {
1264 FirstString++;
1265 SecondString++;
1266 }
1267
1268 return *FirstString - *SecondString;
1269}
1270
1271/**
1272 Converts a lowercase Ascii character to upper one
1273
1274 If Chr is lowercase Ascii character, then converts it to upper one.
1275
1276 If Value >= 0xA0, then ASSERT().
1277 If (Value & 0x0F) >= 0x0A, then ASSERT().
1278
1279 @param chr one Ascii character
1280
1281 @return The uppercase value of Ascii character
1282
1283**/
1284STATIC
1285CHAR8
1286AsciiToUpper (
1287 IN CHAR8 Chr
1288 )
1289{
1290 return (UINT8) ((Chr >= 'a' && Chr <= 'z') ? Chr - ('a' - 'A') : Chr);
1291}
1292
1293/**
1294 Convert a ASCII character to numerical value.
1295
1296 This internal function only deal with Unicode character
1297 which maps to a valid hexadecimal ASII character, i.e.
1298 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1299 ASCII character, the value returned does not make sense.
1300
1301 @param Char The character to convert.
1302
1303 @retval UINTN The numerical value converted.
1304
1305**/
1306STATIC
1307UINTN
1308InternalAsciiHexCharToUintn (
1309 IN CHAR8 Char
1310 )
1311{
1312 if (InternalIsDecimalDigitCharacter (Char)) {
1313 return Char - '0';
1314 }
1315
1316 return (UINTN) (10 + AsciiToUpper (Char) - 'A');
1317}
1318
1319
1320/**
1321 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1322 and returns the difference between the first mismatched ASCII characters.
1323
1324 This function performs a case insensitive comparison of the Null-terminated
1325 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1326 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1327 value returned is the first mismatched lower case ASCII character in
1328 SecondString subtracted from the first mismatched lower case ASCII character
1329 in FirstString.
1330
1331 If FirstString is NULL, then ASSERT().
1332 If SecondString is NULL, then ASSERT().
1333 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1334 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1335 then ASSERT().
1336 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1337 than PcdMaximumAsciiStringLength ASCII characters not including the
1338 Null-terminator, then ASSERT().
1339
1340 @param FirstString Pointer to a Null-terminated ASCII string.
1341 @param SecondString Pointer to a Null-terminated ASCII string.
1342
1343 @retval 0 FirstString is identical to SecondString using case insensitive
1344 comparisons.
1345 @retval !=0 FirstString is not identical to SecondString using case
1346 insensitive comparisons.
1347
1348**/
1349INTN
1350EFIAPI
1351AsciiStriCmp (
1352 IN CONST CHAR8 *FirstString,
1353 IN CONST CHAR8 *SecondString
1354 )
1355{
1356 CHAR8 UpperFirstString;
1357 CHAR8 UpperSecondString;
1358
1359 //
1360 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1361 //
1362 ASSERT (AsciiStrSize (FirstString));
1363 ASSERT (AsciiStrSize (SecondString));
1364
1365 UpperFirstString = AsciiToUpper (*FirstString);
1366 UpperSecondString = AsciiToUpper (*SecondString);
1367 while ((*FirstString != '\0') && (UpperFirstString == UpperSecondString)) {
1368 FirstString++;
1369 SecondString++;
1370 UpperFirstString = AsciiToUpper (*FirstString);
1371 UpperSecondString = AsciiToUpper (*SecondString);
1372 }
1373
1374 return UpperFirstString - UpperSecondString;
1375}
1376
1377/**
1378 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1379 the difference between the first mismatched ASCII characters.
1380
1381 This function compares the Null-terminated ASCII string FirstString to the
1382 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1383 will be compared. If Length is 0, then 0 is returned. If FirstString is
1384 identical to SecondString, then 0 is returned. Otherwise, the value returned
1385 is the first mismatched ASCII character in SecondString subtracted from the
1386 first mismatched ASCII character in FirstString.
1387
1388 If FirstString is NULL, then ASSERT().
1389 If SecondString is NULL, then ASSERT().
1390 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1391 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1392 then ASSERT().
1393 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
1394 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1395 then ASSERT().
1396
1397 @param FirstString Pointer to a Null-terminated ASCII string.
1398 @param SecondString Pointer to a Null-terminated ASCII string.
1399
1400 @retval 0 FirstString is identical to SecondString.
1401 @retval !=0 FirstString is not identical to SecondString.
1402
1403**/
1404INTN
1405EFIAPI
1406AsciiStrnCmp (
1407 IN CONST CHAR8 *FirstString,
1408 IN CONST CHAR8 *SecondString,
1409 IN UINTN Length
1410 )
1411{
1412 if (Length == 0) {
1413 return 0;
1414 }
1415
1416 //
1417 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1418 //
1419 ASSERT (AsciiStrSize (FirstString));
1420 ASSERT (AsciiStrSize (SecondString));
1421
1422 while ((*FirstString != '\0') &&
1423 (*FirstString == *SecondString) &&
1424 (Length > 1)) {
1425 FirstString++;
1426 SecondString++;
1427 Length--;
1428 }
1429 return *FirstString - *SecondString;
1430}
1431
1432/**
1433 Concatenates one Null-terminated ASCII string to another Null-terminated
1434 ASCII string, and returns the concatenated ASCII string.
1435
1436 This function concatenates two Null-terminated ASCII strings. The contents of
1437 Null-terminated ASCII string Source are concatenated to the end of Null-
1438 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1439 String is returned.
1440
1441 If Destination is NULL, then ASSERT().
1442 If Source is NULL, then ASSERT().
1443 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1444 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1445 then ASSERT().
1446 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1447 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1448 then ASSERT().
1449 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1450 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1451 ASCII characters, then ASSERT().
1452
1453 @param Destination Pointer to a Null-terminated ASCII string.
1454 @param Source Pointer to a Null-terminated ASCII string.
1455
1456 @return Destination
1457
1458**/
1459CHAR8 *
1460EFIAPI
1461AsciiStrCat (
1462 IN OUT CHAR8 *Destination,
1463 IN CONST CHAR8 *Source
1464 )
1465{
1466 AsciiStrCpy (Destination + AsciiStrLen (Destination), Source);
1467
1468 //
1469 // Size of the resulting string should never be zero.
1470 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1471 //
1472 ASSERT (AsciiStrSize (Destination) != 0);
1473 return Destination;
1474}
1475
1476/**
1477 Concatenates one Null-terminated ASCII string with a maximum length to the
1478 end of another Null-terminated ASCII string, and returns the concatenated
1479 ASCII string.
1480
1481 This function concatenates two Null-terminated ASCII strings. The contents
1482 of Null-terminated ASCII string Source are concatenated to the end of Null-
1483 terminated ASCII string Destination, and Destination is returned. At most,
1484 Length ASCII characters are concatenated from Source to the end of
1485 Destination, and Destination is always Null-terminated. If Length is 0, then
1486 Destination is returned unmodified. If Source and Destination overlap, then
1487 the results are undefined.
1488
1489 If Destination is NULL, then ASSERT().
1490 If Source is NULL, then ASSERT().
1491 If Source and Destination overlap, then ASSERT().
1492 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1493 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1494 then ASSERT().
1495 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1496 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1497 then ASSERT().
1498 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1499 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1500 ASCII characters not including the Null-terminator, then ASSERT().
1501
1502 @param Destination Pointer to a Null-terminated ASCII string.
1503 @param Source Pointer to a Null-terminated ASCII string.
1504 @param Length Maximum number of ASCII characters to concatenate from
1505 Source.
1506
1507 @return Destination
1508
1509**/
1510CHAR8 *
1511EFIAPI
1512AsciiStrnCat (
1513 IN OUT CHAR8 *Destination,
1514 IN CONST CHAR8 *Source,
1515 IN UINTN Length
1516 )
1517{
1518 AsciiStrnCpy (Destination + AsciiStrLen (Destination), Source, Length);
1519
1520 //
1521 // Size of the resulting string should never be zero.
1522 // PcdMaximumUnicodeStringLength is tested inside StrLen().
1523 //
1524 ASSERT (AsciiStrSize (Destination) != 0);
1525 return Destination;
1526}
1527
1528/**
1529 Returns the first occurance of a Null-terminated ASCII sub-string
1530 in a Null-terminated ASCII string.
1531
1532 This function scans the contents of the ASCII string specified by String
1533 and returns the first occurrence of SearchString. If SearchString is not
1534 found in String, then NULL is returned. If the length of SearchString is zero,
1535 then String is returned.
1536
1537 If String is NULL, then ASSERT().
1538 If SearchString is NULL, then ASSERT().
1539
1540 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1541 String contains more than PcdMaximumAsciiStringLength Unicode characters
1542 not including the Null-terminator, then ASSERT().
1543
1544 @param String Pointer to a Null-terminated ASCII string.
1545 @param SearchString Pointer to a Null-terminated ASCII string to search for.
1546
1547 @retval NULL If the SearchString does not appear in String.
1548 @retval !NULL If there is a match.
1549
1550**/
1551CHAR8 *
1552EFIAPI
1553AsciiStrStr (
1554 IN CONST CHAR8 *String,
1555 IN CONST CHAR8 *SearchString
1556 )
1557{
1558 CONST CHAR8 *FirstMatch;
1559 CONST CHAR8 *SearchStringTmp;
1560
1561 ASSERT (String != NULL);
1562 ASSERT (SearchString != NULL);
1563
1564 //
1565 // If PcdMaximumUnicodeStringLength is not zero,
1566 // length of String should not more than PcdMaximumUnicodeStringLength
1567 //
1568 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1569 ASSERT (AsciiStrLen (String) < PcdGet32 (PcdMaximumAsciiStringLength));
1570 }
1571
1572 //
1573 // If PcdMaximumUnicodeStringLength is not zero,
1574 // length of SearchString should not more than PcdMaximumUnicodeStringLength
1575 //
1576 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1577 ASSERT (AsciiStrLen (SearchString) < PcdGet32 (PcdMaximumAsciiStringLength));
1578 }
1579
1580 while (*String != '\0') {
1581 SearchStringTmp = SearchString;
1582 FirstMatch = String;
1583
1584 while ((*String == *SearchStringTmp)
1585 && (*SearchStringTmp != '\0')
1586 && (*String != '\0')) {
1587 String++;
1588 SearchStringTmp++;
1589 }
1590
1591 if (*SearchStringTmp == '\0') {
1592 return (CHAR8 *) FirstMatch;
1593 }
1594
1595 if (SearchStringTmp == SearchString) {
1596 //
1597 // If no character from SearchString match,
1598 // move the pointer to the String under search
1599 // by one character.
1600 //
1601 String++;
1602 }
1603
1604 }
1605
1606 return NULL;
1607}
1608
1609/**
1610 Convert a Null-terminated ASCII decimal string to a value of type
1611 UINTN.
1612
1613 This function returns a value of type UINTN by interpreting the contents
1614 of the ASCII string String as a decimal number. The format of the input
1615 ASCII string String is:
1616
1617 [spaces] [decimal digits].
1618
1619 The valid decimal digit character is in the range [0-9]. The function will
1620 ignore the pad space, which includes spaces or tab characters, before the digits.
1621 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1622 function stops at the first character that is a not a valid decimal character or
1623 Null-terminator, whichever on comes first.
1624
1625 If String has only pad spaces, then 0 is returned.
1626 If String has no pad spaces or valid decimal digits, then 0 is returned.
1627 If the number represented by String overflows according to the range defined by
1628 UINTN, then ASSERT().
1629 If String is NULL, then ASSERT().
1630 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1631 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1632 then ASSERT().
1633
1634 @param String Pointer to a Null-terminated ASCII string.
1635
1636 @retval UINTN
1637
1638**/
1639UINTN
1640EFIAPI
1641AsciiStrDecimalToUintn (
1642 IN CONST CHAR8 *String
1643 )
1644{
1645 UINTN Result;
1646
1647 ASSERT (String != NULL);
1648 ASSERT (AsciiStrLen (String) < PcdGet32 (PcdMaximumAsciiStringLength));
1649
1650 //
1651 // Ignore the pad spaces (space or tab)
1652 //
1653 while ((*String == ' ') || (*String == '\t')) {
1654 String++;
1655 }
1656
1657 //
1658 // Ignore leading Zeros after the spaces
1659 //
1660 while (*String == '0') {
1661 String++;
1662 }
1663
1664 Result = 0;
1665
1666 while (InternalAsciiIsDecimalDigitCharacter (*String)) {
1667 //
1668 // If the number represented by String overflows according
1669 // to the range defined by UINTN, then ASSERT().
1670 //
1671 ASSERT ((Result < QUIENT_MAX_UINTN_DIVIDED_BY_10) ||
1672 ((Result == QUIENT_MAX_UINTN_DIVIDED_BY_10) &&
1673 (*String - '0') <= REMINDER_MAX_UINTN_DIVIDED_BY_10)
1674 );
1675
1676 Result = Result * 10 + (*String - '0');
1677 String++;
1678 }
1679
1680 return Result;
1681}
1682
1683
1684/**
1685 Convert a Null-terminated ASCII decimal string to a value of type
1686 UINT64.
1687
1688 This function returns a value of type UINT64 by interpreting the contents
1689 of the ASCII string String as a decimal number. The format of the input
1690 ASCII string String is:
1691
1692 [spaces] [decimal digits].
1693
1694 The valid decimal digit character is in the range [0-9]. The function will
1695 ignore the pad space, which includes spaces or tab characters, before the digits.
1696 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1697 function stops at the first character that is a not a valid decimal character or
1698 Null-terminator, whichever on comes first.
1699
1700 If String has only pad spaces, then 0 is returned.
1701 If String has no pad spaces or valid decimal digits, then 0 is returned.
1702 If the number represented by String overflows according to the range defined by
1703 UINT64, then ASSERT().
1704 If String is NULL, then ASSERT().
1705 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1706 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1707 then ASSERT().
1708
1709 @param String Pointer to a Null-terminated ASCII string.
1710
1711 @retval UINT64
1712
1713**/
1714UINT64
1715EFIAPI
1716AsciiStrDecimalToUint64 (
1717 IN CONST CHAR8 *String
1718 )
1719{
1720 UINT64 Result;
1721
1722 ASSERT (String != NULL);
1723 ASSERT (AsciiStrLen (String) < PcdGet32 (PcdMaximumAsciiStringLength));
1724
1725 //
1726 // Ignore the pad spaces (space or tab)
1727 //
1728 while ((*String == ' ') || (*String == '\t')) {
1729 String++;
1730 }
1731
1732 //
1733 // Ignore leading Zeros after the spaces
1734 //
1735 while (*String == '0') {
1736 String++;
1737 }
1738
1739 Result = 0;
1740
1741 while (InternalAsciiIsDecimalDigitCharacter (*String)) {
1742 //
1743 // If the number represented by String overflows according
1744 // to the range defined by UINTN, then ASSERT().
1745 //
1746 ASSERT ((Result < QUIENT_MAX_UINT64_DIVIDED_BY_10) ||
1747 ((Result == QUIENT_MAX_UINT64_DIVIDED_BY_10) &&
1748 (*String - '0') <= REMINDER_MAX_UINT64_DIVIDED_BY_10)
1749 );
1750
1751 Result = MultU64x32 (Result, 10) + (*String - '0');
1752 String++;
1753 }
1754
1755 return Result;
1756}
1757
1758/**
1759 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1760
1761 This function returns a value of type UINTN by interpreting the contents of
1762 the ASCII string String as a hexadecimal number. The format of the input ASCII
1763 string String is:
1764
1765 [spaces][zeros][x][hexadecimal digits].
1766
1767 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1768 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1769 appears in the input string, it must be prefixed with at least one 0. The function
1770 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1771 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1772 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1773 digit. Then, the function stops at the first character that is a not a valid
1774 hexadecimal character or Null-terminator, whichever on comes first.
1775
1776 If String has only pad spaces, then 0 is returned.
1777 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1778 0 is returned.
1779
1780 If the number represented by String overflows according to the range defined by UINTN,
1781 then ASSERT().
1782 If String is NULL, then ASSERT().
1783 If PcdMaximumAsciiStringLength is not zero,
1784 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1785 the Null-terminator, then ASSERT().
1786
1787 @param String Pointer to a Null-terminated ASCII string.
1788
1789 @retval UINTN
1790
1791**/
1792UINTN
1793EFIAPI
1794AsciiStrHexToUintn (
1795 IN CONST CHAR8 *String
1796 )
1797{
1798 UINTN Result;
1799
1800 ASSERT (String != NULL);
1801 ASSERT (AsciiStrLen (String) < PcdGet32 (PcdMaximumAsciiStringLength));
1802
1803 //
1804 // Ignore the pad spaces (space or tab)
1805 //
1806 while ((*String == ' ') || (*String == '\t')) {
1807 String++;
1808 }
1809
1810 //
1811 // Ignore leading Zeros after the spaces
1812 //
1813 while (*String == '0') {
1814 String++;
1815 }
1816
1817 if (AsciiToUpper (*String) == 'X') {
1818 ASSERT (*(String - 1) == '0');
1819 if (*(String - 1) != '0') {
1820 return 0;
1821 }
1822 //
1823 // Skip the 'X'
1824 //
1825 String++;
1826 }
1827
1828 Result = 0;
1829
1830 while (InternalAsciiIsHexaDecimalDigitCharacter (*String)) {
1831 //
1832 // If the Hex Number represented by String overflows according
1833 // to the range defined by UINTN, then ASSERT().
1834 //
1835 ASSERT ((Result < QUIENT_MAX_UINTN_DIVIDED_BY_16) ||
1836 ((Result == QUIENT_MAX_UINTN_DIVIDED_BY_16) &&
1837 (InternalAsciiHexCharToUintn (*String) <= REMINDER_MAX_UINTN_DIVIDED_BY_16))
1838 );
1839
1840 Result = (Result << 4) + InternalAsciiHexCharToUintn (*String);
1841 String++;
1842 }
1843
1844 return Result;
1845}
1846
1847
1848/**
1849 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1850
1851 This function returns a value of type UINT64 by interpreting the contents of
1852 the ASCII string String as a hexadecimal number. The format of the input ASCII
1853 string String is:
1854
1855 [spaces][zeros][x][hexadecimal digits].
1856
1857 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1858 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1859 appears in the input string, it must be prefixed with at least one 0. The function
1860 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1861 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1862 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1863 digit. Then, the function stops at the first character that is a not a valid
1864 hexadecimal character or Null-terminator, whichever on comes first.
1865
1866 If String has only pad spaces, then 0 is returned.
1867 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1868 0 is returned.
1869
1870 If the number represented by String overflows according to the range defined by UINT64,
1871 then ASSERT().
1872 If String is NULL, then ASSERT().
1873 If PcdMaximumAsciiStringLength is not zero,
1874 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1875 the Null-terminator, then ASSERT().
1876
1877 @param String Pointer to a Null-terminated ASCII string.
1878
1879 @retval UINT64
1880
1881**/
1882UINT64
1883EFIAPI
1884AsciiStrHexToUint64 (
1885 IN CONST CHAR8 *String
1886 )
1887{
1888 UINT64 Result;
1889
1890 ASSERT (String != NULL);
1891 ASSERT (AsciiStrLen (String) < PcdGet32 (PcdMaximumUnicodeStringLength));
1892
1893 //
1894 // Ignore the pad spaces (space or tab) and leading Zeros
1895 //
1896 //
1897 // Ignore the pad spaces (space or tab)
1898 //
1899 while ((*String == ' ') || (*String == '\t')) {
1900 String++;
1901 }
1902
1903 //
1904 // Ignore leading Zeros after the spaces
1905 //
1906 while (*String == '0') {
1907 String++;
1908 }
1909
1910 if (AsciiToUpper (*String) == 'X') {
1911 ASSERT (*(String - 1) == '0');
1912 if (*(String - 1) != '0') {
1913 return 0;
1914 }
1915 //
1916 // Skip the 'X'
1917 //
1918 String++;
1919 }
1920
1921 Result = 0;
1922
1923 while (InternalAsciiIsHexaDecimalDigitCharacter (*String)) {
1924 //
1925 // If the Hex Number represented by String overflows according
1926 // to the range defined by UINTN, then ASSERT().
1927 //
1928 ASSERT ((Result < QUIENT_MAX_UINT64_DIVIDED_BY_16) ||
1929 ((Result == QUIENT_MAX_UINT64_DIVIDED_BY_16) &&
1930 (InternalAsciiHexCharToUintn (*String) <= REMINDER_MAX_UINT64_DIVIDED_BY_16))
1931 );
1932
1933 Result = LShiftU64 (Result, 4) + InternalAsciiHexCharToUintn (*String);
1934 String++;
1935 }
1936
1937 return Result;
1938}
1939
1940
1941/**
1942 Convert one Null-terminated ASCII string to a Null-terminated
1943 Unicode string and returns the Unicode string.
1944
1945 This function converts the contents of the ASCII string Source to the Unicode
1946 string Destination, and returns Destination. The function terminates the
1947 Unicode string Destination by appending a Null-terminator character at the end.
1948 The caller is responsible to make sure Destination points to a buffer with size
1949 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1950
1951 If Destination is NULL, then ASSERT().
1952 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1953 If Source is NULL, then ASSERT().
1954 If Source and Destination overlap, then ASSERT().
1955 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1956 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1957 then ASSERT().
1958 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1959 PcdMaximumUnicodeStringLength ASCII characters not including the
1960 Null-terminator, then ASSERT().
1961
1962 @param Source Pointer to a Null-terminated ASCII string.
1963 @param Destination Pointer to a Null-terminated Unicode string.
1964
1965 @reture Destination
1966
1967**/
1968CHAR16 *
1969EFIAPI
1970AsciiStrToUnicodeStr (
1971 IN CONST CHAR8 *Source,
1972 OUT CHAR16 *Destination
1973 )
1974{
1975 ASSERT (Destination != NULL);
1976 ASSERT (Source != NULL);
1977
1978 //
1979 // Source and Destination should not overlap
1980 //
1981 ASSERT ((UINTN) ((CHAR8 *) Destination - Source) > AsciiStrLen (Source));
1982 ASSERT ((UINTN) (Source - (CHAR8 *) Destination) > (AsciiStrLen (Source) * sizeof (CHAR16)));
1983
1984 //
1985 // If PcdMaximumAsciiStringLength is not zero,
1986 // length of Source should not more than PcdMaximumUnicodeStringLength
1987 //
1988 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1989 ASSERT (AsciiStrLen (Source) < PcdGet32 (PcdMaximumAsciiStringLength));
1990 }
1991
1992 while (*Source != '\0') {
1993 *(Destination++) = (CHAR16) *(Source++);
1994 }
1995 //
1996 // End the Destination with a NULL.
1997 //
1998 *Destination = '\0';
1999
2000 return Destination;
2001}
2002
2003/**
2004 Converts an 8-bit value to an 8-bit BCD value.
2005
2006 Converts the 8-bit value specified by Value to BCD. The BCD value is
2007 returned.
2008
2009 If Value >= 100, then ASSERT().
2010
2011 @param Value The 8-bit value to convert to BCD. Range 0..99.
2012
2013 @return The BCD value
2014
2015**/
2016UINT8
2017EFIAPI
2018DecimalToBcd8 (
2019 IN UINT8 Value
2020 )
2021{
2022 ASSERT (Value < 100);
2023 return (UINT8) (((Value / 10) << 4) | (Value % 10));
2024}
2025
2026/**
2027 Converts an 8-bit BCD value to an 8-bit value.
2028
2029 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2030 value is returned.
2031
2032 If Value >= 0xA0, then ASSERT().
2033 If (Value & 0x0F) >= 0x0A, then ASSERT().
2034
2035 @param Value The 8-bit BCD value to convert to an 8-bit value.
2036
2037 @return The 8-bit value is returned.
2038
2039**/
2040UINT8
2041EFIAPI
2042BcdToDecimal8 (
2043 IN UINT8 Value
2044 )
2045{
2046 ASSERT (Value < 0xa0);
2047 ASSERT ((Value & 0xf) < 0xa);
2048 return (UINT8) ((Value >> 4) * 10 + (Value & 0xf));
2049}
2050
2051