2 Unicode string primatives.
4 Copyright (c) 2006, 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
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.
18 Copies one Null-terminated Unicode string to another Null-terminated Unicode
19 string and returns the new Unicode string.
21 This function copies the contents of the Unicode string Source to the Unicode
22 string Destination, and returns Destination. If Source and Destination
23 overlap, then the results are undefined.
25 If Destination is NULL, then ASSERT().
26 If Source is NULL, then ASSERT().
27 If Source and Destination overlap, then ASSERT().
28 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
29 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
31 @param Destination Pointer to a Null-terminated Unicode string.
32 @param Source Pointer to a Null-terminated Unicode string.
40 OUT CHAR16
*Destination
,
41 IN CONST CHAR16
*Source
47 // Destination cannot be NULL
49 ASSERT (Destination
!= NULL
);
52 // Destination and source cannot overlap
54 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
55 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
57 ReturnValue
= Destination
;
59 *(Destination
++) = *(Source
++);
66 Copies one Null-terminated Unicode string with a maximum length to another
67 Null-terminated Unicode string with a maximum length and returns the new
70 This function copies the contents of the Unicode string Source to the Unicode
71 string Destination, and returns Destination. At most, Length Unicode
72 characters are copied from Source to Destination. If Length is 0, then
73 Destination is returned unmodified. If Length is greater that the number of
74 Unicode characters in Source, then Destination is padded with Null Unicode
75 characters. If Source and Destination overlap, then the results are
78 If Destination is NULL, then ASSERT().
79 If Source is NULL, then ASSERT().
80 If Source and Destination overlap, then ASSERT().
81 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
82 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
84 @param Destination Pointer to a Null-terminated Unicode string.
85 @param Source Pointer to a Null-terminated Unicode string.
86 @param Length Maximum number of Unicode characters to copy.
94 OUT CHAR16
*Destination
,
95 IN CONST CHAR16
*Source
,
106 // Destination cannot be NULL if Length is not zero
108 ASSERT (Destination
!= NULL
);
111 // Destination and source cannot overlap
112 // Q: Does Source have to be NULL-terminated?
114 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
115 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
117 ReturnValue
= Destination
;
119 while ((*Source
!= L
'\0') && (Length
> 0)) {
120 *(Destination
++) = *(Source
++);
124 ZeroMem (Destination
, Length
* sizeof (*Destination
));
129 Returns the length of a Null-terminated Unicode string.
131 This function returns the number of Unicode characters in the Null-terminated
132 Unicode string specified by String.
134 If String is NULL, then ASSERT().
135 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
136 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
138 @param String Pointer to a Null-terminated Unicode string.
140 @return The length of String.
146 IN CONST CHAR16
*String
151 ASSERT (String
!= NULL
);
153 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
155 // If PcdMaximumUnicodeStringLength is not zero,
156 // length should not more than PcdMaximumUnicodeStringLength
158 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
159 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
166 Returns the size of a Null-terminated Unicode string in bytes, including the
169 This function returns the size, in bytes, of the Null-terminated Unicode
170 string specified by String.
172 If String is NULL, then ASSERT().
173 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
174 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
176 @param String Pointer to a Null-terminated Unicode string.
178 @return The size of String.
184 IN CONST CHAR16
*String
187 return (StrLen (String
) + 1) * sizeof (*String
);
191 Compares two Null-terminated Unicode strings, and returns the difference
192 between the first mismatched Unicode characters.
194 This function compares the Null-terminated Unicode string FirstString to the
195 Null-terminated Unicode string SecondString. If FirstString is identical to
196 SecondString, then 0 is returned. Otherwise, the value returned is the first
197 mismatched Unicode character in SecondString subtracted from the first
198 mismatched Unicode character in FirstString.
200 If FirstString is NULL, then ASSERT().
201 If SecondString is NULL, then ASSERT().
202 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
203 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
204 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
205 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
207 @param FirstString Pointer to a Null-terminated Unicode string.
208 @param SecondString Pointer to a Null-terminated Unicode string.
210 @retval 0 FirstString is identical to SecondString.
211 @retval !=0 FirstString is not identical to SecondString.
217 IN CONST CHAR16
*FirstString
,
218 IN CONST CHAR16
*SecondString
222 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
224 ASSERT (StrSize (FirstString
) != 0);
225 ASSERT (StrSize (SecondString
) != 0);
227 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
231 return *FirstString
- *SecondString
;
235 Compares two Null-terminated Unicode strings with maximum lengths, and
236 returns the difference between the first mismatched Unicode characters.
238 This function compares the Null-terminated Unicode string FirstString to the
239 Null-terminated Unicode string SecondString. At most, Length Unicode
240 characters will be compared. If Length is 0, then 0 is returned. If
241 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
242 value returned is the first mismatched Unicode character in SecondString
243 subtracted from the first mismatched Unicode character in FirstString.
245 If FirstString is NULL, then ASSERT().
246 If SecondString is NULL, then ASSERT().
247 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
248 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
249 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
250 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
252 @param FirstString Pointer to a Null-terminated Unicode string.
253 @param SecondString Pointer to a Null-terminated Unicode string.
254 @param Length Maximum number of Unicode characters to compare.
256 @retval 0 FirstString is identical to SecondString.
257 @retval !=0 FirstString is not identical to SecondString.
263 IN CONST CHAR16
*FirstString
,
264 IN CONST CHAR16
*SecondString
,
273 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
274 // Length tests are performed inside StrLen().
276 ASSERT (StrSize (FirstString
) != 0);
277 ASSERT (StrSize (SecondString
) != 0);
279 while ((*FirstString
!= L
'\0') &&
280 (*FirstString
== *SecondString
) &&
287 return *FirstString
- *SecondString
;
291 Concatenates one Null-terminated Unicode string to another Null-terminated
292 Unicode string, and returns the concatenated Unicode string.
294 This function concatenates two Null-terminated Unicode strings. The contents
295 of Null-terminated Unicode string Source are concatenated to the end of
296 Null-terminated Unicode string Destination. The Null-terminated concatenated
297 Unicode String is returned. If Source and Destination overlap, then the
298 results are undefined.
300 If Destination is NULL, then ASSERT().
301 If Source is NULL, then ASSERT().
302 If Source and Destination overlap, then ASSERT().
303 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
304 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
305 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
306 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
307 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
308 and Source results in a Unicode string with more than
309 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
311 @param Destination Pointer to a Null-terminated Unicode string.
312 @param Source Pointer to a Null-terminated Unicode string.
320 IN OUT CHAR16
*Destination
,
321 IN CONST CHAR16
*Source
324 StrCpy (Destination
+ StrLen (Destination
), Source
);
327 // Size of the resulting string should never be zero.
328 // PcdMaximumUnicodeStringLength is tested inside StrLen().
330 ASSERT (StrSize (Destination
) != 0);
335 Concatenates one Null-terminated Unicode string with a maximum length to the
336 end of another Null-terminated Unicode string, and returns the concatenated
339 This function concatenates two Null-terminated Unicode strings. The contents
340 of Null-terminated Unicode string Source are concatenated to the end of
341 Null-terminated Unicode string Destination, and Destination is returned. At
342 most, Length Unicode characters are concatenated from Source to the end of
343 Destination, and Destination is always Null-terminated. If Length is 0, then
344 Destination is returned unmodified. If Source and Destination overlap, then
345 the results are undefined.
347 If Destination is NULL, then ASSERT().
348 If Source is NULL, then ASSERT().
349 If Source and Destination overlap, then ASSERT().
350 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
351 than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
352 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
353 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
354 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
355 and Source results in a Unicode string with more than
356 PcdMaximumUnicodeStringLength Unicode characters, then ASSERT().
358 @param Destination Pointer to a Null-terminated Unicode string.
359 @param Source Pointer to a Null-terminated Unicode string.
360 @param Length Maximum number of Unicode characters to concatenate from
369 IN OUT CHAR16
*Destination
,
370 IN CONST CHAR16
*Source
,
374 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
377 // Size of the resulting string should never be zero.
378 // PcdMaximumUnicodeStringLength is tested inside StrLen().
380 ASSERT (StrSize (Destination
) != 0);
385 Copies one Null-terminated ASCII string to another Null-terminated ASCII
386 string and returns the new ASCII string.
388 This function copies the contents of the ASCII string Source to the ASCII
389 string Destination, and returns Destination. If Source and Destination
390 overlap, then the results are undefined.
392 If Destination is NULL, then ASSERT().
393 If Source is NULL, then ASSERT().
394 If Source and Destination overlap, then ASSERT().
395 If PcdMaximumAsciiStringLength is not zero and Source contains more than
396 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
398 @param Destination Pointer to a Null-terminated ASCII string.
399 @param Source Pointer to a Null-terminated ASCII string.
407 OUT CHAR8
*Destination
,
408 IN CONST CHAR8
*Source
414 // Destination cannot be NULL
416 ASSERT (Destination
!= NULL
);
419 // Destination and source cannot overlap
421 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
422 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
424 ReturnValue
= Destination
;
426 *(Destination
++) = *(Source
++);
433 Copies one Null-terminated ASCII string with a maximum length to another
434 Null-terminated ASCII string with a maximum length and returns the new ASCII
437 This function copies the contents of the ASCII string Source to the ASCII
438 string Destination, and returns Destination. At most, Length ASCII characters
439 are copied from Source to Destination. If Length is 0, then Destination is
440 returned unmodified. If Length is greater that the number of ASCII characters
441 in Source, then Destination is padded with Null ASCII characters. If Source
442 and Destination overlap, then the results are undefined.
444 If Destination is NULL, then ASSERT().
445 If Source is NULL, then ASSERT().
446 If Source and Destination overlap, then ASSERT().
447 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
448 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
450 @param Destination Pointer to a Null-terminated ASCII string.
451 @param Source Pointer to a Null-terminated ASCII string.
452 @param Length Maximum number of ASCII characters to copy.
460 OUT CHAR8
*Destination
,
461 IN CONST CHAR8
*Source
,
472 // Destination cannot be NULL
474 ASSERT (Destination
!= NULL
);
477 // Destination and source cannot overlap
479 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
480 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
482 ReturnValue
= Destination
;
484 while (*Source
&& Length
> 0) {
485 *(Destination
++) = *(Source
++);
489 ZeroMem (Destination
, Length
* sizeof (*Destination
));
494 Returns the length of a Null-terminated ASCII string.
496 This function returns the number of ASCII characters in the Null-terminated
497 ASCII string specified by String.
499 If String is NULL, then ASSERT().
500 If PcdMaximumAsciiStringLength is not zero and String contains more than
501 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
503 @param String Pointer to a Null-terminated ASCII string.
505 @return The length of String.
511 IN CONST CHAR8
*String
516 ASSERT (String
!= NULL
);
518 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
520 // If PcdMaximumUnicodeStringLength is not zero,
521 // length should not more than PcdMaximumUnicodeStringLength
523 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
524 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
531 Returns the size of a Null-terminated ASCII string in bytes, including the
534 This function returns the size, in bytes, of the Null-terminated ASCII string
537 If String is NULL, then ASSERT().
538 If PcdMaximumAsciiStringLength is not zero and String contains more than
539 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
541 @param String Pointer to a Null-terminated ASCII string.
543 @return The size of String.
549 IN CONST CHAR8
*String
552 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
556 Compares two Null-terminated ASCII strings, and returns the difference
557 between the first mismatched ASCII characters.
559 This function compares the Null-terminated ASCII string FirstString to the
560 Null-terminated ASCII string SecondString. If FirstString is identical to
561 SecondString, then 0 is returned. Otherwise, the value returned is the first
562 mismatched ASCII character in SecondString subtracted from the first
563 mismatched ASCII character in FirstString.
565 If FirstString is NULL, then ASSERT().
566 If SecondString is NULL, then ASSERT().
567 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
568 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
569 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
570 than PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
572 @param FirstString Pointer to a Null-terminated ASCII string.
573 @param SecondString Pointer to a Null-terminated ASCII string.
575 @retval 0 FirstString is identical to SecondString.
576 @retval !=0 FirstString is not identical to SecondString.
582 IN CONST CHAR8
*FirstString
,
583 IN CONST CHAR8
*SecondString
587 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
589 ASSERT (AsciiStrSize (FirstString
));
590 ASSERT (AsciiStrSize (SecondString
));
592 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
597 return *FirstString
- *SecondString
;
607 return (Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
;
611 Performs a case insensitive comparison of two Null-terminated ASCII strings,
612 and returns the difference between the first mismatched ASCII characters.
614 This function performs a case insensitive comparison of the Null-terminated
615 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
616 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
617 value returned is the first mismatched lower case ASCII character in
618 SecondString subtracted from the first mismatched lower case ASCII character
621 If FirstString is NULL, then ASSERT().
622 If SecondString is NULL, then ASSERT().
623 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
624 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
625 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
626 than PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
628 @param FirstString Pointer to a Null-terminated ASCII string.
629 @param SecondString Pointer to a Null-terminated ASCII string.
631 @retval 0 FirstString is identical to SecondString using case insensitive
633 @retval !=0 FirstString is not identical to SecondString using case
634 insensitive comparisons.
640 IN CONST CHAR8
*FirstString
,
641 IN CONST CHAR8
*SecondString
645 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
647 ASSERT (AsciiStrSize (FirstString
));
648 ASSERT (AsciiStrSize (SecondString
));
650 while ((*FirstString
!= '\0') &&
651 (AsciiToUpper (*FirstString
) == AsciiToUpper (*SecondString
))) {
656 return AsciiToUpper (*FirstString
) - AsciiToUpper (*SecondString
);
660 Compares two Null-terminated ASCII strings with maximum lengths, and returns
661 the difference between the first mismatched ASCII characters.
663 This function compares the Null-terminated ASCII string FirstString to the
664 Null-terminated ASCII string SecondString. At most, Length ASCII characters
665 will be compared. If Length is 0, then 0 is returned. If FirstString is
666 identical to SecondString, then 0 is returned. Otherwise, the value returned
667 is the first mismatched ASCII character in SecondString subtracted from the
668 first mismatched ASCII character in FirstString.
670 If FirstString is NULL, then ASSERT().
671 If SecondString is NULL, then ASSERT().
672 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
673 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
674 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
675 than PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
677 @param FirstString Pointer to a Null-terminated ASCII string.
678 @param SecondString Pointer to a Null-terminated ASCII string.
680 @retval 0 FirstString is identical to SecondString.
681 @retval !=0 FirstString is not identical to SecondString.
687 IN CONST CHAR8
*FirstString
,
688 IN CONST CHAR8
*SecondString
,
693 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
695 ASSERT (AsciiStrSize (FirstString
));
696 ASSERT (AsciiStrSize (SecondString
));
698 while ((*FirstString
!= '\0') &&
699 (*FirstString
== *SecondString
) &&
705 return *FirstString
- *SecondString
;
709 Concatenates one Null-terminated ASCII string to another Null-terminated
710 ASCII string, and returns the concatenated ASCII string.
712 This function concatenates two Null-terminated ASCII strings. The contents of
713 Null-terminated ASCII string Source are concatenated to the end of Null-
714 terminated ASCII string Destination. The Null-terminated concatenated ASCII
717 If Destination is NULL, then ASSERT().
718 If Source is NULL, then ASSERT().
719 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
720 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
721 If PcdMaximumAsciiStringLength is not zero and Source contains more than
722 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
723 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
724 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
725 ASCII characters, then ASSERT().
727 @param Destination Pointer to a Null-terminated ASCII string.
728 @param Source Pointer to a Null-terminated ASCII string.
736 IN OUT CHAR8
*Destination
,
737 IN CONST CHAR8
*Source
740 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
743 // Size of the resulting string should never be zero.
744 // PcdMaximumUnicodeStringLength is tested inside StrLen().
746 ASSERT (AsciiStrSize (Destination
) != 0);
751 Concatenates one Null-terminated ASCII string with a maximum length to the
752 end of another Null-terminated ASCII string, and returns the concatenated
755 This function concatenates two Null-terminated ASCII strings. The contents
756 of Null-terminated ASCII string Source are concatenated to the end of Null-
757 terminated ASCII string Destination, and Destination is returned. At most,
758 Length ASCII characters are concatenated from Source to the end of
759 Destination, and Destination is always Null-terminated. If Length is 0, then
760 Destination is returned unmodified. If Source and Destination overlap, then
761 the results are undefined.
763 If Destination is NULL, then ASSERT().
764 If Source is NULL, then ASSERT().
765 If Source and Destination overlap, then ASSERT().
766 If PcdMaximumAsciiStringLength is not zero, and Destination contains more
767 than PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
768 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
769 PcdMaximumAsciiStringLength ASCII characters, then ASSERT().
770 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
771 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
772 ASCII characters, then ASSERT().
774 @param Destination Pointer to a Null-terminated ASCII string.
775 @param Source Pointer to a Null-terminated ASCII string.
776 @param Length Maximum number of ASCII characters to concatenate from
785 IN OUT CHAR8
*Destination
,
786 IN CONST CHAR8
*Source
,
790 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
793 // Size of the resulting string should never be zero.
794 // PcdMaximumUnicodeStringLength is tested inside StrLen().
796 ASSERT (AsciiStrSize (Destination
) != 0);
801 Converts an 8-bit value to an 8-bit BCD value.
803 Converts the 8-bit value specified by Value to BCD. The BCD value is
806 If Value >= 100, then ASSERT().
808 @param Value The 8-bit value to convert to BCD. Range 0..99.
810 @return The BCD value
819 ASSERT (Value
< 100);
820 return ((Value
/ 10) << 4) | (Value
% 10);
824 Converts an 8-bit BCD value to an 8-bit value.
826 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
829 If Value >= 0xA0, then ASSERT().
830 If (Value & 0x0F) >= 0x0A, then ASSERT().
832 @param Value The 8-bit BCD value to convert to an 8-bit value.
834 @return The 8-bit value is returned.
843 ASSERT (Value
< 0xa0);
844 ASSERT ((Value
& 0xf) < 0xa);
845 return (Value
>> 4) * 10 + (Value
& 0xf);