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