80223c6732ebedcb0df7fe0747d2d1678f90b244
[people/mcb30/edk2.git] / edk2 / MdePkg / Library / BaseLib / String.c
1 /** @file\r
2   Unicode string primatives.\r
3 \r
4   Copyright (c) 2006, Intel Corporation<BR>\r
5   All rights reserved. This program and the accompanying materials\r
6   are licensed and made available under the terms and conditions of the BSD License\r
7   which accompanies this distribution.  The full text of the license may be found at\r
8   http://opensource.org/licenses/bsd-license.php\r
9 \r
10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
12 \r
13   Module Name:  String.c\r
14 \r
15 **/\r
16 \r
17 /**\r
18   Copies one Null-terminated Unicode string to another Null-terminated Unicode\r
19   string and returns the new Unicode string.\r
20 \r
21   This function copies the contents of the Unicode string Source to the Unicode\r
22   string Destination, and returns Destination. If Source and Destination\r
23   overlap, then the results are undefined.\r
24 \r
25   If Destination is NULL, then ASSERT().\r
26   If Source is NULL, then ASSERT().\r
27   If Source and Destination overlap, then ASSERT().\r
28   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
29   PcdMaximumUnicodeStringLength Unicode characters not including the \r
30   Null-terminator, then ASSERT().\r
31 \r
32   @param  Destination Pointer to a Null-terminated Unicode string.\r
33   @param  Source      Pointer to a Null-terminated Unicode string.\r
34 \r
35   @return Destiantion\r
36 \r
37 **/\r
38 CHAR16 *\r
39 EFIAPI\r
40 StrCpy (\r
41   OUT     CHAR16                    *Destination,\r
42   IN      CONST CHAR16              *Source\r
43   )\r
44 {\r
45   CHAR16                            *ReturnValue;\r
46 \r
47   //\r
48   // Destination cannot be NULL\r
49   //\r
50   ASSERT (Destination != NULL);\r
51 \r
52   //\r
53   // Destination and source cannot overlap\r
54   //\r
55   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));\r
56   ASSERT ((UINTN)(Source - Destination) > StrLen (Source));\r
57 \r
58   ReturnValue = Destination;\r
59   while (*Source) {\r
60     *(Destination++) = *(Source++);\r
61   }\r
62   *Destination = 0;\r
63   return ReturnValue;\r
64 }\r
65 \r
66 /**\r
67   Copies one Null-terminated Unicode string with a maximum length to another\r
68   Null-terminated Unicode string with a maximum length and returns the new\r
69   Unicode string.\r
70 \r
71   This function copies the contents of the Unicode string Source to the Unicode\r
72   string Destination, and returns Destination. At most, Length Unicode\r
73   characters are copied from Source to Destination. If Length is 0, then\r
74   Destination is returned unmodified. If Length is greater that the number of\r
75   Unicode characters in Source, then Destination is padded with Null Unicode\r
76   characters. If Source and Destination overlap, then the results are\r
77   undefined.\r
78 \r
79   If Destination is NULL, then ASSERT().\r
80   If Source is NULL, then ASSERT().\r
81   If Source and Destination overlap, then ASSERT().\r
82   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
83   PcdMaximumUnicodeStringLength Unicode characters not including the \r
84   Null-terminator, then ASSERT().\r
85 \r
86   @param  Destination Pointer to a Null-terminated Unicode string.\r
87   @param  Source      Pointer to a Null-terminated Unicode string.\r
88   @param  Length      Maximum number of Unicode characters to copy.\r
89 \r
90   @return Destination\r
91 \r
92 **/\r
93 CHAR16 *\r
94 EFIAPI\r
95 StrnCpy (\r
96   OUT     CHAR16                    *Destination,\r
97   IN      CONST CHAR16              *Source,\r
98   IN      UINTN                     Length\r
99   )\r
100 {\r
101   CHAR16                            *ReturnValue;\r
102 \r
103   if (Length == 0) {\r
104     return Destination;\r
105   }\r
106 \r
107   //\r
108   // Destination cannot be NULL if Length is not zero\r
109   //\r
110   ASSERT (Destination != NULL);\r
111 \r
112   //\r
113   // Destination and source cannot overlap\r
114   // Q: Does Source have to be NULL-terminated?\r
115   //\r
116   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));\r
117   ASSERT ((UINTN)(Source - Destination) >= Length);\r
118 \r
119   ReturnValue = Destination;\r
120 \r
121   while ((*Source != L'\0') && (Length > 0)) {\r
122     *(Destination++) = *(Source++);\r
123     Length--;\r
124   }\r
125 \r
126   ZeroMem (Destination, Length * sizeof (*Destination));\r
127   return ReturnValue;\r
128 }\r
129 \r
130 /**\r
131   Returns the length of a Null-terminated Unicode string.\r
132 \r
133   This function returns the number of Unicode characters in the Null-terminated\r
134   Unicode string specified by String.\r
135 \r
136   If String is NULL, then ASSERT().\r
137   If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
138   PcdMaximumUnicodeStringLength Unicode characters not including the \r
139   Null-terminator, then ASSERT().\r
140 \r
141   @param  String  Pointer to a Null-terminated Unicode string.\r
142 \r
143   @return The length of String.\r
144 \r
145 **/\r
146 UINTN\r
147 EFIAPI\r
148 StrLen (\r
149   IN      CONST CHAR16              *String\r
150   )\r
151 {\r
152   UINTN                             Length;\r
153 \r
154   ASSERT (String != NULL);\r
155 \r
156   for (Length = 0; *String != L'\0'; String++, Length++) {\r
157     //\r
158     // If PcdMaximumUnicodeStringLength is not zero,\r
159     // length should not more than PcdMaximumUnicodeStringLength\r
160     //\r
161     if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {\r
162       ASSERT (Length < PcdGet32 (PcdMaximumUnicodeStringLength));\r
163     }\r
164   }\r
165   return Length;\r
166 }\r
167 \r
168 /**\r
169   Returns the size of a Null-terminated Unicode string in bytes, including the\r
170   Null terminator.\r
171 \r
172   This function returns the size, in bytes, of the Null-terminated Unicode\r
173   string specified by String.\r
174 \r
175   If String is NULL, then ASSERT().\r
176   If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
177   PcdMaximumUnicodeStringLength Unicode characters not including the \r
178   Null-terminator, then ASSERT().\r
179 \r
180   @param  String  Pointer to a Null-terminated Unicode string.\r
181 \r
182   @return The size of String.\r
183 \r
184 **/\r
185 UINTN\r
186 EFIAPI\r
187 StrSize (\r
188   IN      CONST CHAR16              *String\r
189   )\r
190 {\r
191   return (StrLen (String) + 1) * sizeof (*String);\r
192 }\r
193 \r
194 /**\r
195   Compares two Null-terminated Unicode strings, and returns the difference\r
196   between the first mismatched Unicode characters.\r
197 \r
198   This function compares the Null-terminated Unicode string FirstString to the\r
199   Null-terminated Unicode string SecondString. If FirstString is identical to\r
200   SecondString, then 0 is returned. Otherwise, the value returned is the first\r
201   mismatched Unicode character in SecondString subtracted from the first\r
202   mismatched Unicode character in FirstString.\r
203 \r
204   If FirstString is NULL, then ASSERT().\r
205   If SecondString is NULL, then ASSERT().\r
206   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
207   than PcdMaximumUnicodeStringLength Unicode characters not including the \r
208   Null-terminator, then ASSERT().\r
209   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
210   than PcdMaximumUnicodeStringLength Unicode characters not including the \r
211   Null-terminator, then ASSERT().\r
212 \r
213   @param  FirstString   Pointer to a Null-terminated Unicode string.\r
214   @param  SecondString  Pointer to a Null-terminated Unicode string.\r
215 \r
216   @retval 0   FirstString is identical to SecondString.\r
217   @retval !=0 FirstString is not identical to SecondString.\r
218 \r
219 **/\r
220 INTN\r
221 EFIAPI\r
222 StrCmp (\r
223   IN      CONST CHAR16              *FirstString,\r
224   IN      CONST CHAR16              *SecondString\r
225   )\r
226 {\r
227   //\r
228   // ASSERT both strings are less long than PcdMaximumUnicodeStringLength\r
229   //\r
230   ASSERT (StrSize (FirstString) != 0);\r
231   ASSERT (StrSize (SecondString) != 0);\r
232 \r
233   while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {\r
234     FirstString++;\r
235     SecondString++;\r
236   }\r
237   return *FirstString - *SecondString;\r
238 }\r
239 \r
240 /**\r
241   Compares two Null-terminated Unicode strings with maximum lengths, and\r
242   returns the difference between the first mismatched Unicode characters.\r
243 \r
244   This function compares the Null-terminated Unicode string FirstString to the\r
245   Null-terminated Unicode string SecondString. At most, Length Unicode\r
246   characters will be compared. If Length is 0, then 0 is returned. If\r
247   FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
248   value returned is the first mismatched Unicode character in SecondString\r
249   subtracted from the first mismatched Unicode character in FirstString.\r
250 \r
251   If FirstString is NULL, then ASSERT().\r
252   If SecondString is NULL, then ASSERT().\r
253   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
254   than PcdMaximumUnicodeStringLength Unicode characters not including the\r
255   Null-terminator, then ASSERT().\r
256   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
257   than PcdMaximumUnicodeStringLength Unicode characters not including the\r
258   Null-terminator, then ASSERT().\r
259 \r
260   @param  FirstString   Pointer to a Null-terminated Unicode string.\r
261   @param  SecondString  Pointer to a Null-terminated Unicode string.\r
262   @param  Length        Maximum number of Unicode characters to compare.\r
263 \r
264   @retval 0   FirstString is identical to SecondString.\r
265   @retval !=0 FirstString is not identical to SecondString.\r
266 \r
267 **/\r
268 INTN\r
269 EFIAPI\r
270 StrnCmp (\r
271   IN      CONST CHAR16              *FirstString,\r
272   IN      CONST CHAR16              *SecondString,\r
273   IN      UINTN                     Length\r
274   )\r
275 {\r
276   if (Length == 0) {\r
277     return 0;\r
278   }\r
279 \r
280   //\r
281   // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.\r
282   // Length tests are performed inside StrLen().\r
283   //\r
284   ASSERT (StrSize (FirstString) != 0);\r
285   ASSERT (StrSize (SecondString) != 0);\r
286 \r
287   while ((*FirstString != L'\0') &&\r
288          (*FirstString == *SecondString) &&\r
289          (Length > 1)) {\r
290     FirstString++;\r
291     SecondString++;\r
292     Length--;\r
293   }\r
294 \r
295   return *FirstString - *SecondString;\r
296 }\r
297 \r
298 /**\r
299   Concatenates one Null-terminated Unicode string to another Null-terminated\r
300   Unicode string, and returns the concatenated Unicode string.\r
301 \r
302   This function concatenates two Null-terminated Unicode strings. The contents\r
303   of Null-terminated Unicode string Source are concatenated to the end of\r
304   Null-terminated Unicode string Destination. The Null-terminated concatenated\r
305   Unicode String is returned. If Source and Destination overlap, then the\r
306   results are undefined.\r
307 \r
308   If Destination is NULL, then ASSERT().\r
309   If Source is NULL, then ASSERT().\r
310   If Source and Destination overlap, then ASSERT().\r
311   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
312   than PcdMaximumUnicodeStringLength Unicode characters not including the\r
313   Null-terminator, then ASSERT().\r
314   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
315   PcdMaximumUnicodeStringLength Unicode characters not including the\r
316   Null-terminator, then ASSERT().\r
317   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
318   and Source results in a Unicode string with more than\r
319   PcdMaximumUnicodeStringLength Unicode characters not including the\r
320   Null-terminator, then ASSERT().\r
321 \r
322   @param  Destination Pointer to a Null-terminated Unicode string.\r
323   @param  Source      Pointer to a Null-terminated Unicode string.\r
324 \r
325   @return Destination\r
326 \r
327 **/\r
328 CHAR16 *\r
329 EFIAPI\r
330 StrCat (\r
331   IN OUT  CHAR16                    *Destination,\r
332   IN      CONST CHAR16              *Source\r
333   )\r
334 {\r
335   StrCpy (Destination + StrLen (Destination), Source);\r
336 \r
337   //\r
338   // Size of the resulting string should never be zero.\r
339   // PcdMaximumUnicodeStringLength is tested inside StrLen().\r
340   //\r
341   ASSERT (StrSize (Destination) != 0);\r
342   return Destination;\r
343 }\r
344 \r
345 /**\r
346   Concatenates one Null-terminated Unicode string with a maximum length to the\r
347   end of another Null-terminated Unicode string, and returns the concatenated\r
348   Unicode string.\r
349 \r
350   This function concatenates two Null-terminated Unicode strings. The contents\r
351   of Null-terminated Unicode string Source are concatenated to the end of\r
352   Null-terminated Unicode string Destination, and Destination is returned. At\r
353   most, Length Unicode characters are concatenated from Source to the end of\r
354   Destination, and Destination is always Null-terminated. If Length is 0, then\r
355   Destination is returned unmodified. If Source and Destination overlap, then\r
356   the results are undefined.\r
357 \r
358   If Destination is NULL, then ASSERT().\r
359   If Source is NULL, then ASSERT().\r
360   If Source and Destination overlap, then ASSERT().\r
361   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
362   than PcdMaximumUnicodeStringLength Unicode characters not including the\r
363   Null-terminator, then ASSERT().\r
364   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
365   PcdMaximumUnicodeStringLength Unicode characters not including the\r
366   Null-terminator, then ASSERT().\r
367   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
368   and Source results in a Unicode string with more than\r
369   PcdMaximumUnicodeStringLength Unicode characters not including the\r
370   Null-terminator, then ASSERT().\r
371 \r
372   @param  Destination Pointer to a Null-terminated Unicode string.\r
373   @param  Source      Pointer to a Null-terminated Unicode string.\r
374   @param  Length      Maximum number of Unicode characters to concatenate from\r
375                       Source.\r
376 \r
377   @return Destination\r
378 \r
379 **/\r
380 CHAR16 *\r
381 EFIAPI\r
382 StrnCat (\r
383   IN OUT  CHAR16                    *Destination,\r
384   IN      CONST CHAR16              *Source,\r
385   IN      UINTN                     Length\r
386   )\r
387 {\r
388   StrnCpy (Destination + StrLen (Destination), Source, Length);\r
389 \r
390   //\r
391   // Size of the resulting string should never be zero.\r
392   // PcdMaximumUnicodeStringLength is tested inside StrLen().\r
393   //\r
394   ASSERT (StrSize (Destination) != 0);\r
395   return Destination;\r
396 }\r
397 \r
398 /**\r
399   Copies one Null-terminated ASCII string to another Null-terminated ASCII\r
400   string and returns the new ASCII string.\r
401 \r
402   This function copies the contents of the ASCII string Source to the ASCII\r
403   string Destination, and returns Destination. If Source and Destination\r
404   overlap, then the results are undefined.\r
405 \r
406   If Destination is NULL, then ASSERT().\r
407   If Source is NULL, then ASSERT().\r
408   If Source and Destination overlap, then ASSERT().\r
409   If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
410   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
411   then ASSERT().\r
412 \r
413   @param  Destination Pointer to a Null-terminated ASCII string.\r
414   @param  Source      Pointer to a Null-terminated ASCII string.\r
415 \r
416   @return Destination\r
417 \r
418 **/\r
419 CHAR8 *\r
420 EFIAPI\r
421 AsciiStrCpy (\r
422   OUT     CHAR8                     *Destination,\r
423   IN      CONST CHAR8               *Source\r
424   )\r
425 {\r
426   CHAR8                             *ReturnValue;\r
427 \r
428   //\r
429   // Destination cannot be NULL\r
430   //\r
431   ASSERT (Destination != NULL);\r
432 \r
433   //\r
434   // Destination and source cannot overlap\r
435   //\r
436   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));\r
437   ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source));\r
438 \r
439   ReturnValue = Destination;\r
440   while (*Source) {\r
441     *(Destination++) = *(Source++);\r
442   }\r
443   *Destination = 0;\r
444   return ReturnValue;\r
445 }\r
446 \r
447 /**\r
448   Copies one Null-terminated ASCII string with a maximum length to another\r
449   Null-terminated ASCII string with a maximum length and returns the new ASCII\r
450   string.\r
451 \r
452   This function copies the contents of the ASCII string Source to the ASCII\r
453   string Destination, and returns Destination. At most, Length ASCII characters\r
454   are copied from Source to Destination. If Length is 0, then Destination is\r
455   returned unmodified. If Length is greater that the number of ASCII characters\r
456   in Source, then Destination is padded with Null ASCII characters. If Source\r
457   and Destination overlap, then the results are undefined.\r
458 \r
459   If Destination is NULL, then ASSERT().\r
460   If Source is NULL, then ASSERT().\r
461   If Source and Destination overlap, then ASSERT().\r
462   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
463   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
464   then ASSERT().\r
465 \r
466   @param  Destination Pointer to a Null-terminated ASCII string.\r
467   @param  Source      Pointer to a Null-terminated ASCII string.\r
468   @param  Length      Maximum number of ASCII characters to copy.\r
469 \r
470   @return Destination\r
471 \r
472 **/\r
473 CHAR8 *\r
474 EFIAPI\r
475 AsciiStrnCpy (\r
476   OUT     CHAR8                     *Destination,\r
477   IN      CONST CHAR8               *Source,\r
478   IN      UINTN                     Length\r
479   )\r
480 {\r
481   CHAR8                             *ReturnValue;\r
482 \r
483   if (Length == 0) {\r
484     return Destination;\r
485   }\r
486 \r
487   //\r
488   // Destination cannot be NULL\r
489   //\r
490   ASSERT (Destination != NULL);\r
491 \r
492   //\r
493   // Destination and source cannot overlap\r
494   //\r
495   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));\r
496   ASSERT ((UINTN)(Source - Destination) >= Length);\r
497 \r
498   ReturnValue = Destination;\r
499 \r
500   while (*Source && Length > 0) {\r
501     *(Destination++) = *(Source++);\r
502     Length--;\r
503   }\r
504 \r
505   ZeroMem (Destination, Length * sizeof (*Destination));\r
506   return ReturnValue;\r
507 }\r
508 \r
509 /**\r
510   Returns the length of a Null-terminated ASCII string.\r
511 \r
512   This function returns the number of ASCII characters in the Null-terminated\r
513   ASCII string specified by String.\r
514 \r
515   If String is NULL, then ASSERT().\r
516   If PcdMaximumAsciiStringLength is not zero and String contains more than\r
517   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
518   then ASSERT().\r
519 \r
520   @param  String  Pointer to a Null-terminated ASCII string.\r
521 \r
522   @return The length of String.\r
523 \r
524 **/\r
525 UINTN\r
526 EFIAPI\r
527 AsciiStrLen (\r
528   IN      CONST CHAR8               *String\r
529   )\r
530 {\r
531   UINTN                             Length;\r
532 \r
533   ASSERT (String != NULL);\r
534 \r
535   for (Length = 0; *String != '\0'; String++, Length++) {\r
536     //\r
537     // If PcdMaximumUnicodeStringLength is not zero,\r
538     // length should not more than PcdMaximumUnicodeStringLength\r
539     //\r
540     if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {\r
541       ASSERT (Length < PcdGet32 (PcdMaximumAsciiStringLength));\r
542     }\r
543   }\r
544   return Length;\r
545 }\r
546 \r
547 /**\r
548   Returns the size of a Null-terminated ASCII string in bytes, including the\r
549   Null terminator.\r
550 \r
551   This function returns the size, in bytes, of the Null-terminated ASCII string\r
552   specified by String.\r
553 \r
554   If String is NULL, then ASSERT().\r
555   If PcdMaximumAsciiStringLength is not zero and String contains more than\r
556   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
557   then ASSERT().\r
558 \r
559   @param  String  Pointer to a Null-terminated ASCII string.\r
560 \r
561   @return The size of String.\r
562 \r
563 **/\r
564 UINTN\r
565 EFIAPI\r
566 AsciiStrSize (\r
567   IN      CONST CHAR8               *String\r
568   )\r
569 {\r
570   return (AsciiStrLen (String) + 1) * sizeof (*String);\r
571 }\r
572 \r
573 /**\r
574   Compares two Null-terminated ASCII strings, and returns the difference\r
575   between the first mismatched ASCII characters.\r
576 \r
577   This function compares the Null-terminated ASCII string FirstString to the\r
578   Null-terminated ASCII string SecondString. If FirstString is identical to\r
579   SecondString, then 0 is returned. Otherwise, the value returned is the first\r
580   mismatched ASCII character in SecondString subtracted from the first\r
581   mismatched ASCII character in FirstString.\r
582 \r
583   If FirstString is NULL, then ASSERT().\r
584   If SecondString is NULL, then ASSERT().\r
585   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
586   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
587   then ASSERT().\r
588   If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
589   than PcdMaximumAsciiStringLength ASCII characters not including the\r
590   Null-terminator, then ASSERT().\r
591 \r
592   @param  FirstString   Pointer to a Null-terminated ASCII string.\r
593   @param  SecondString  Pointer to a Null-terminated ASCII string.\r
594 \r
595   @retval 0   FirstString is identical to SecondString.\r
596   @retval !=0 FirstString is not identical to SecondString.\r
597 \r
598 **/\r
599 INTN\r
600 EFIAPI\r
601 AsciiStrCmp (\r
602   IN      CONST CHAR8               *FirstString,\r
603   IN      CONST CHAR8               *SecondString\r
604   )\r
605 {\r
606   //\r
607   // ASSERT both strings are less long than PcdMaximumAsciiStringLength\r
608   //\r
609   ASSERT (AsciiStrSize (FirstString));\r
610   ASSERT (AsciiStrSize (SecondString));\r
611 \r
612   while ((*FirstString != '\0') && (*FirstString == *SecondString)) {\r
613     FirstString++;\r
614     SecondString++;\r
615   }\r
616 \r
617   return *FirstString - *SecondString;\r
618 }\r
619 \r
620 STATIC\r
621 CHAR8\r
622 EFIAPI\r
623 AsciiToUpper (\r
624   IN      CHAR8                     Chr\r
625   )\r
626 {\r
627   return (Chr >= 'a' && Chr <= 'z') ? Chr - ('a' - 'A') : Chr;\r
628 }\r
629 \r
630 /**\r
631   Performs a case insensitive comparison of two Null-terminated ASCII strings,\r
632   and returns the difference between the first mismatched ASCII characters.\r
633 \r
634   This function performs a case insensitive comparison of the Null-terminated\r
635   ASCII string FirstString to the Null-terminated ASCII string SecondString. If\r
636   FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
637   value returned is the first mismatched lower case ASCII character in\r
638   SecondString subtracted from the first mismatched lower case ASCII character\r
639   in FirstString.\r
640 \r
641   If FirstString is NULL, then ASSERT().\r
642   If SecondString is NULL, then ASSERT().\r
643   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
644   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
645   then ASSERT().\r
646   If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
647   than PcdMaximumAsciiStringLength ASCII characters not including the\r
648   Null-terminator, then ASSERT().\r
649 \r
650   @param  FirstString   Pointer to a Null-terminated ASCII string.\r
651   @param  SecondString  Pointer to a Null-terminated ASCII string.\r
652 \r
653   @retval 0   FirstString is identical to SecondString using case insensitive\r
654               comparisons.\r
655   @retval !=0 FirstString is not identical to SecondString using case\r
656               insensitive comparisons.\r
657 \r
658 **/\r
659 INTN\r
660 EFIAPI\r
661 AsciiStriCmp (\r
662   IN      CONST CHAR8               *FirstString,\r
663   IN      CONST CHAR8               *SecondString\r
664   )\r
665 {\r
666   //\r
667   // ASSERT both strings are less long than PcdMaximumAsciiStringLength\r
668   //\r
669   ASSERT (AsciiStrSize (FirstString));\r
670   ASSERT (AsciiStrSize (SecondString));\r
671 \r
672   while ((*FirstString != '\0') &&\r
673          (AsciiToUpper (*FirstString) == AsciiToUpper (*SecondString))) {\r
674     FirstString++;\r
675     SecondString++;\r
676   }\r
677 \r
678   return AsciiToUpper (*FirstString) - AsciiToUpper (*SecondString);\r
679 }\r
680 \r
681 /**\r
682   Compares two Null-terminated ASCII strings with maximum lengths, and returns\r
683   the difference between the first mismatched ASCII characters.\r
684 \r
685   This function compares the Null-terminated ASCII string FirstString to the\r
686   Null-terminated ASCII  string SecondString. At most, Length ASCII characters\r
687   will be compared. If Length is 0, then 0 is returned. If FirstString is\r
688   identical to SecondString, then 0 is returned. Otherwise, the value returned\r
689   is the first mismatched ASCII character in SecondString subtracted from the\r
690   first mismatched ASCII character in FirstString.\r
691 \r
692   If FirstString is NULL, then ASSERT().\r
693   If SecondString is NULL, then ASSERT().\r
694   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
695   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
696   then ASSERT().\r
697   If PcdMaximumAsciiStringLength is not zero and SecondString contains more than\r
698   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
699   then ASSERT().\r
700 \r
701   @param  FirstString   Pointer to a Null-terminated ASCII string.\r
702   @param  SecondString  Pointer to a Null-terminated ASCII string.\r
703 \r
704   @retval 0   FirstString is identical to SecondString.\r
705   @retval !=0 FirstString is not identical to SecondString.\r
706 \r
707 **/\r
708 INTN\r
709 EFIAPI\r
710 AsciiStrnCmp (\r
711   IN      CONST CHAR8               *FirstString,\r
712   IN      CONST CHAR8               *SecondString,\r
713   IN      UINTN                     Length\r
714   )\r
715 {\r
716   //\r
717   // ASSERT both strings are less long than PcdMaximumAsciiStringLength\r
718   //\r
719   ASSERT (AsciiStrSize (FirstString));\r
720   ASSERT (AsciiStrSize (SecondString));\r
721 \r
722   while ((*FirstString != '\0') &&\r
723          (*FirstString == *SecondString) &&\r
724          (Length > 1)) {\r
725     FirstString++;\r
726     SecondString++;\r
727     Length--;\r
728   }\r
729   return *FirstString - *SecondString;\r
730 }\r
731 \r
732 /**\r
733   Concatenates one Null-terminated ASCII string to another Null-terminated\r
734   ASCII string, and returns the concatenated ASCII string.\r
735 \r
736   This function concatenates two Null-terminated ASCII strings. The contents of\r
737   Null-terminated ASCII string Source are concatenated to the end of Null-\r
738   terminated ASCII string Destination. The Null-terminated concatenated ASCII\r
739   String is returned.\r
740 \r
741   If Destination is NULL, then ASSERT().\r
742   If Source is NULL, then ASSERT().\r
743   If PcdMaximumAsciiStringLength is not zero and Destination contains more than\r
744   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
745   then ASSERT().\r
746   If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
747   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
748   then ASSERT().\r
749   If PcdMaximumAsciiStringLength is not zero and concatenating Destination and\r
750   Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
751   ASCII characters, then ASSERT().\r
752 \r
753   @param  Destination Pointer to a Null-terminated ASCII string.\r
754   @param  Source      Pointer to a Null-terminated ASCII string.\r
755 \r
756   @return Destination\r
757 \r
758 **/\r
759 CHAR8 *\r
760 EFIAPI\r
761 AsciiStrCat (\r
762   IN OUT CHAR8    *Destination,\r
763   IN CONST CHAR8  *Source\r
764   )\r
765 {\r
766   AsciiStrCpy (Destination + AsciiStrLen (Destination), Source);\r
767 \r
768   //\r
769   // Size of the resulting string should never be zero.\r
770   // PcdMaximumUnicodeStringLength is tested inside StrLen().\r
771   //\r
772   ASSERT (AsciiStrSize (Destination) != 0);\r
773   return Destination;\r
774 }\r
775 \r
776 /**\r
777   Concatenates one Null-terminated ASCII string with a maximum length to the\r
778   end of another Null-terminated ASCII string, and returns the concatenated\r
779   ASCII string.\r
780 \r
781   This function concatenates two Null-terminated ASCII strings. The contents\r
782   of Null-terminated ASCII string Source are concatenated to the end of Null-\r
783   terminated ASCII string Destination, and Destination is returned. At most,\r
784   Length ASCII characters are concatenated from Source to the end of\r
785   Destination, and Destination is always Null-terminated. If Length is 0, then\r
786   Destination is returned unmodified. If Source and Destination overlap, then\r
787   the results are undefined.\r
788 \r
789   If Destination is NULL, then ASSERT().\r
790   If Source is NULL, then ASSERT().\r
791   If Source and Destination overlap, then ASSERT().\r
792   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than\r
793   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
794   then ASSERT().\r
795   If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
796   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
797   then ASSERT().\r
798   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and\r
799   Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
800   ASCII characters not including the Null-terminator, then ASSERT().\r
801 \r
802   @param  Destination Pointer to a Null-terminated ASCII string.\r
803   @param  Source      Pointer to a Null-terminated ASCII string.\r
804   @param  Length      Maximum number of ASCII characters to concatenate from\r
805                       Source.\r
806 \r
807   @return Destination\r
808 \r
809 **/\r
810 CHAR8 *\r
811 EFIAPI\r
812 AsciiStrnCat (\r
813   IN OUT  CHAR8                     *Destination,\r
814   IN      CONST CHAR8               *Source,\r
815   IN      UINTN                     Length\r
816   )\r
817 {\r
818   AsciiStrnCpy (Destination + AsciiStrLen (Destination), Source, Length);\r
819 \r
820   //\r
821   // Size of the resulting string should never be zero.\r
822   // PcdMaximumUnicodeStringLength is tested inside StrLen().\r
823   //\r
824   ASSERT (AsciiStrSize (Destination) != 0);\r
825   return Destination;\r
826 }\r
827 \r
828 /**\r
829   Converts an 8-bit value to an 8-bit BCD value.\r
830 \r
831   Converts the 8-bit value specified by Value to BCD. The BCD value is\r
832   returned.\r
833 \r
834   If Value >= 100, then ASSERT().\r
835 \r
836   @param  Value The 8-bit value to convert to BCD. Range 0..99.\r
837 \r
838   @return The BCD value\r
839 \r
840 **/\r
841 UINT8\r
842 EFIAPI\r
843 DecimalToBcd8 (\r
844   IN      UINT8                     Value\r
845   )\r
846 {\r
847   ASSERT (Value < 100);\r
848   return ((Value / 10) << 4) | (Value % 10);\r
849 }\r
850 \r
851 /**\r
852   Converts an 8-bit BCD value to an 8-bit value.\r
853 \r
854   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit\r
855   value is returned.\r
856 \r
857   If Value >= 0xA0, then ASSERT().\r
858   If (Value & 0x0F) >= 0x0A, then ASSERT().\r
859 \r
860   @param  Value The 8-bit BCD value to convert to an 8-bit value.\r
861 \r
862   @return The 8-bit value is returned.\r
863 \r
864 **/\r
865 UINT8\r
866 EFIAPI\r
867 BcdToDecimal8 (\r
868   IN      UINT8                     Value\r
869   )\r
870 {\r
871   ASSERT (Value < 0xa0);\r
872   ASSERT ((Value & 0xf) < 0xa);\r
873   return (Value >> 4) * 10 + (Value & 0xf);\r
874 }\r