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


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