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