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


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