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