]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Library/BaseLib/String.c
projects / mirror_edk2.git / blob
? search:


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