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