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