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 not including the
30 Null-terminator, then ASSERT().
32 @param Destination Pointer to a Null-terminated Unicode string.
33 @param Source Pointer to a Null-terminated Unicode string.
41 OUT CHAR16
*Destination
,
42 IN CONST CHAR16
*Source
48 // Destination cannot be NULL
50 ASSERT (Destination
!= NULL
);
53 // Destination and source cannot overlap
55 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
56 ASSERT ((UINTN
)(Source
- Destination
) > StrLen (Source
));
58 ReturnValue
= Destination
;
60 *(Destination
++) = *(Source
++);
67 Copies one Null-terminated Unicode string with a maximum length to another
68 Null-terminated Unicode string with a maximum length and returns the new
71 This function copies the contents of the Unicode string Source to the Unicode
72 string Destination, and returns Destination. At most, Length Unicode
73 characters are copied from Source to Destination. If Length is 0, then
74 Destination is returned unmodified. If Length is greater that the number of
75 Unicode characters in Source, then Destination is padded with Null Unicode
76 characters. If Source and Destination overlap, then the results are
79 If Destination is NULL, then ASSERT().
80 If Source is NULL, then ASSERT().
81 If Source and Destination overlap, then ASSERT().
82 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
83 PcdMaximumUnicodeStringLength Unicode characters not including the
84 Null-terminator, then ASSERT().
86 @param Destination Pointer to a Null-terminated Unicode string.
87 @param Source Pointer to a Null-terminated Unicode string.
88 @param Length Maximum number of Unicode characters to copy.
96 OUT CHAR16
*Destination
,
97 IN CONST CHAR16
*Source
,
108 // Destination cannot be NULL if Length is not zero
110 ASSERT (Destination
!= NULL
);
113 // Destination and source cannot overlap
114 // Q: Does Source have to be NULL-terminated?
116 ASSERT ((UINTN
)(Destination
- Source
) > StrLen (Source
));
117 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
119 ReturnValue
= Destination
;
121 while ((*Source
!= L
'\0') && (Length
> 0)) {
122 *(Destination
++) = *(Source
++);
126 ZeroMem (Destination
, Length
* sizeof (*Destination
));
131 Returns the length of a Null-terminated Unicode string.
133 This function returns the number of Unicode characters in the Null-terminated
134 Unicode string specified by String.
136 If String is NULL, then ASSERT().
137 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
138 PcdMaximumUnicodeStringLength Unicode characters not including the
139 Null-terminator, then ASSERT().
141 @param String Pointer to a Null-terminated Unicode string.
143 @return The length of String.
149 IN CONST CHAR16
*String
154 ASSERT (String
!= NULL
);
156 for (Length
= 0; *String
!= L
'\0'; String
++, Length
++) {
158 // If PcdMaximumUnicodeStringLength is not zero,
159 // length should not more than PcdMaximumUnicodeStringLength
161 if (PcdGet32 (PcdMaximumUnicodeStringLength
) != 0) {
162 ASSERT (Length
< PcdGet32 (PcdMaximumUnicodeStringLength
));
169 Returns the size of a Null-terminated Unicode string in bytes, including the
172 This function returns the size, in bytes, of the Null-terminated Unicode
173 string specified by String.
175 If String is NULL, then ASSERT().
176 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
177 PcdMaximumUnicodeStringLength Unicode characters not including the
178 Null-terminator, then ASSERT().
180 @param String Pointer to a Null-terminated Unicode string.
182 @return The size of String.
188 IN CONST CHAR16
*String
191 return (StrLen (String
) + 1) * sizeof (*String
);
195 Compares two Null-terminated Unicode strings, and returns the difference
196 between the first mismatched Unicode characters.
198 This function compares the Null-terminated Unicode string FirstString to the
199 Null-terminated Unicode string SecondString. If FirstString is identical to
200 SecondString, then 0 is returned. Otherwise, the value returned is the first
201 mismatched Unicode character in SecondString subtracted from the first
202 mismatched Unicode character in FirstString.
204 If FirstString is NULL, then ASSERT().
205 If SecondString is NULL, then ASSERT().
206 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
207 than PcdMaximumUnicodeStringLength Unicode characters not including the
208 Null-terminator, then ASSERT().
209 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
210 than PcdMaximumUnicodeStringLength Unicode characters not including the
211 Null-terminator, then ASSERT().
213 @param FirstString Pointer to a Null-terminated Unicode string.
214 @param SecondString Pointer to a Null-terminated Unicode string.
216 @retval 0 FirstString is identical to SecondString.
217 @retval !=0 FirstString is not identical to SecondString.
223 IN CONST CHAR16
*FirstString
,
224 IN CONST CHAR16
*SecondString
228 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
230 ASSERT (StrSize (FirstString
) != 0);
231 ASSERT (StrSize (SecondString
) != 0);
233 while ((*FirstString
!= L
'\0') && (*FirstString
== *SecondString
)) {
237 return *FirstString
- *SecondString
;
241 Compares two Null-terminated Unicode strings with maximum lengths, and
242 returns the difference between the first mismatched Unicode characters.
244 This function compares the Null-terminated Unicode string FirstString to the
245 Null-terminated Unicode string SecondString. At most, Length Unicode
246 characters will be compared. If Length is 0, then 0 is returned. If
247 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
248 value returned is the first mismatched Unicode character in SecondString
249 subtracted from the first mismatched Unicode character in FirstString.
251 If FirstString is NULL, then ASSERT().
252 If SecondString is NULL, then ASSERT().
253 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
254 than PcdMaximumUnicodeStringLength Unicode characters not including the
255 Null-terminator, then ASSERT().
256 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
257 than PcdMaximumUnicodeStringLength Unicode characters not including the
258 Null-terminator, then ASSERT().
260 @param FirstString Pointer to a Null-terminated Unicode string.
261 @param SecondString Pointer to a Null-terminated Unicode string.
262 @param Length Maximum number of Unicode characters to compare.
264 @retval 0 FirstString is identical to SecondString.
265 @retval !=0 FirstString is not identical to SecondString.
271 IN CONST CHAR16
*FirstString
,
272 IN CONST CHAR16
*SecondString
,
281 // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
282 // Length tests are performed inside StrLen().
284 ASSERT (StrSize (FirstString
) != 0);
285 ASSERT (StrSize (SecondString
) != 0);
287 while ((*FirstString
!= L
'\0') &&
288 (*FirstString
== *SecondString
) &&
295 return *FirstString
- *SecondString
;
299 Concatenates one Null-terminated Unicode string to another Null-terminated
300 Unicode string, and returns the concatenated Unicode string.
302 This function concatenates two Null-terminated Unicode strings. The contents
303 of Null-terminated Unicode string Source are concatenated to the end of
304 Null-terminated Unicode string Destination. The Null-terminated concatenated
305 Unicode String is returned. If Source and Destination overlap, then the
306 results are undefined.
308 If Destination is NULL, then ASSERT().
309 If Source is NULL, then ASSERT().
310 If Source and Destination overlap, then ASSERT().
311 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
312 than PcdMaximumUnicodeStringLength Unicode characters not including the
313 Null-terminator, then ASSERT().
314 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
315 PcdMaximumUnicodeStringLength Unicode characters not including the
316 Null-terminator, then ASSERT().
317 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
318 and Source results in a Unicode string with more than
319 PcdMaximumUnicodeStringLength Unicode characters not including the
320 Null-terminator, then ASSERT().
322 @param Destination Pointer to a Null-terminated Unicode string.
323 @param Source Pointer to a Null-terminated Unicode string.
331 IN OUT CHAR16
*Destination
,
332 IN CONST CHAR16
*Source
335 StrCpy (Destination
+ StrLen (Destination
), Source
);
338 // Size of the resulting string should never be zero.
339 // PcdMaximumUnicodeStringLength is tested inside StrLen().
341 ASSERT (StrSize (Destination
) != 0);
346 Concatenates one Null-terminated Unicode string with a maximum length to the
347 end of another Null-terminated Unicode string, and returns the concatenated
350 This function concatenates two Null-terminated Unicode strings. The contents
351 of Null-terminated Unicode string Source are concatenated to the end of
352 Null-terminated Unicode string Destination, and Destination is returned. At
353 most, Length Unicode characters are concatenated from Source to the end of
354 Destination, and Destination is always Null-terminated. If Length is 0, then
355 Destination is returned unmodified. If Source and Destination overlap, then
356 the results are undefined.
358 If Destination is NULL, then ASSERT().
359 If Source is NULL, then ASSERT().
360 If Source and Destination overlap, then ASSERT().
361 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
362 than PcdMaximumUnicodeStringLength Unicode characters not including the
363 Null-terminator, then ASSERT().
364 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
365 PcdMaximumUnicodeStringLength Unicode characters not including the
366 Null-terminator, then ASSERT().
367 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
368 and Source results in a Unicode string with more than
369 PcdMaximumUnicodeStringLength Unicode characters not including the
370 Null-terminator, then ASSERT().
372 @param Destination Pointer to a Null-terminated Unicode string.
373 @param Source Pointer to a Null-terminated Unicode string.
374 @param Length Maximum number of Unicode characters to concatenate from
383 IN OUT CHAR16
*Destination
,
384 IN CONST CHAR16
*Source
,
388 StrnCpy (Destination
+ StrLen (Destination
), Source
, Length
);
391 // Size of the resulting string should never be zero.
392 // PcdMaximumUnicodeStringLength is tested inside StrLen().
394 ASSERT (StrSize (Destination
) != 0);
399 Copies one Null-terminated ASCII string to another Null-terminated ASCII
400 string and returns the new ASCII string.
402 This function copies the contents of the ASCII string Source to the ASCII
403 string Destination, and returns Destination. If Source and Destination
404 overlap, then the results are undefined.
406 If Destination is NULL, then ASSERT().
407 If Source is NULL, then ASSERT().
408 If Source and Destination overlap, then ASSERT().
409 If PcdMaximumAsciiStringLength is not zero and Source contains more than
410 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
413 @param Destination Pointer to a Null-terminated ASCII string.
414 @param Source Pointer to a Null-terminated ASCII string.
422 OUT CHAR8
*Destination
,
423 IN CONST CHAR8
*Source
429 // Destination cannot be NULL
431 ASSERT (Destination
!= NULL
);
434 // Destination and source cannot overlap
436 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
437 ASSERT ((UINTN
)(Source
- Destination
) > AsciiStrLen (Source
));
439 ReturnValue
= Destination
;
441 *(Destination
++) = *(Source
++);
448 Copies one Null-terminated ASCII string with a maximum length to another
449 Null-terminated ASCII string with a maximum length and returns the new ASCII
452 This function copies the contents of the ASCII string Source to the ASCII
453 string Destination, and returns Destination. At most, Length ASCII characters
454 are copied from Source to Destination. If Length is 0, then Destination is
455 returned unmodified. If Length is greater that the number of ASCII characters
456 in Source, then Destination is padded with Null ASCII characters. If Source
457 and Destination overlap, then the results are undefined.
459 If Destination is NULL, then ASSERT().
460 If Source is NULL, then ASSERT().
461 If Source and Destination overlap, then ASSERT().
462 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
463 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
466 @param Destination Pointer to a Null-terminated ASCII string.
467 @param Source Pointer to a Null-terminated ASCII string.
468 @param Length Maximum number of ASCII characters to copy.
476 OUT CHAR8
*Destination
,
477 IN CONST CHAR8
*Source
,
488 // Destination cannot be NULL
490 ASSERT (Destination
!= NULL
);
493 // Destination and source cannot overlap
495 ASSERT ((UINTN
)(Destination
- Source
) > AsciiStrLen (Source
));
496 ASSERT ((UINTN
)(Source
- Destination
) >= Length
);
498 ReturnValue
= Destination
;
500 while (*Source
&& Length
> 0) {
501 *(Destination
++) = *(Source
++);
505 ZeroMem (Destination
, Length
* sizeof (*Destination
));
510 Returns the length of a Null-terminated ASCII string.
512 This function returns the number of ASCII characters in the Null-terminated
513 ASCII string specified by String.
515 If String is NULL, then ASSERT().
516 If PcdMaximumAsciiStringLength is not zero and String contains more than
517 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
520 @param String Pointer to a Null-terminated ASCII string.
522 @return The length of String.
528 IN CONST CHAR8
*String
533 ASSERT (String
!= NULL
);
535 for (Length
= 0; *String
!= '\0'; String
++, Length
++) {
537 // If PcdMaximumUnicodeStringLength is not zero,
538 // length should not more than PcdMaximumUnicodeStringLength
540 if (PcdGet32 (PcdMaximumAsciiStringLength
) != 0) {
541 ASSERT (Length
< PcdGet32 (PcdMaximumAsciiStringLength
));
548 Returns the size of a Null-terminated ASCII string in bytes, including the
551 This function returns the size, in bytes, of the Null-terminated ASCII string
554 If String is NULL, then ASSERT().
555 If PcdMaximumAsciiStringLength is not zero and String contains more than
556 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
559 @param String Pointer to a Null-terminated ASCII string.
561 @return The size of String.
567 IN CONST CHAR8
*String
570 return (AsciiStrLen (String
) + 1) * sizeof (*String
);
574 Compares two Null-terminated ASCII strings, and returns the difference
575 between the first mismatched ASCII characters.
577 This function compares the Null-terminated ASCII string FirstString to the
578 Null-terminated ASCII string SecondString. If FirstString is identical to
579 SecondString, then 0 is returned. Otherwise, the value returned is the first
580 mismatched ASCII character in SecondString subtracted from the first
581 mismatched ASCII character in FirstString.
583 If FirstString is NULL, then ASSERT().
584 If SecondString is NULL, then ASSERT().
585 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
586 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
588 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
589 than PcdMaximumAsciiStringLength ASCII characters not including the
590 Null-terminator, then ASSERT().
592 @param FirstString Pointer to a Null-terminated ASCII string.
593 @param SecondString Pointer to a Null-terminated ASCII string.
595 @retval 0 FirstString is identical to SecondString.
596 @retval !=0 FirstString is not identical to SecondString.
602 IN CONST CHAR8
*FirstString
,
603 IN CONST CHAR8
*SecondString
607 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
609 ASSERT (AsciiStrSize (FirstString
));
610 ASSERT (AsciiStrSize (SecondString
));
612 while ((*FirstString
!= '\0') && (*FirstString
== *SecondString
)) {
617 return *FirstString
- *SecondString
;
627 return (Chr
>= 'a' && Chr
<= 'z') ? Chr
- ('a' - 'A') : Chr
;
631 Performs a case insensitive comparison of two Null-terminated ASCII strings,
632 and returns the difference between the first mismatched ASCII characters.
634 This function performs a case insensitive comparison of the Null-terminated
635 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
636 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
637 value returned is the first mismatched lower case ASCII character in
638 SecondString subtracted from the first mismatched lower case ASCII character
641 If FirstString is NULL, then ASSERT().
642 If SecondString is NULL, then ASSERT().
643 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
644 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
646 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
647 than PcdMaximumAsciiStringLength ASCII characters not including the
648 Null-terminator, then ASSERT().
650 @param FirstString Pointer to a Null-terminated ASCII string.
651 @param SecondString Pointer to a Null-terminated ASCII string.
653 @retval 0 FirstString is identical to SecondString using case insensitive
655 @retval !=0 FirstString is not identical to SecondString using case
656 insensitive comparisons.
662 IN CONST CHAR8
*FirstString
,
663 IN CONST CHAR8
*SecondString
667 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
669 ASSERT (AsciiStrSize (FirstString
));
670 ASSERT (AsciiStrSize (SecondString
));
672 while ((*FirstString
!= '\0') &&
673 (AsciiToUpper (*FirstString
) == AsciiToUpper (*SecondString
))) {
678 return AsciiToUpper (*FirstString
) - AsciiToUpper (*SecondString
);
682 Compares two Null-terminated ASCII strings with maximum lengths, and returns
683 the difference between the first mismatched ASCII characters.
685 This function compares the Null-terminated ASCII string FirstString to the
686 Null-terminated ASCII string SecondString. At most, Length ASCII characters
687 will be compared. If Length is 0, then 0 is returned. If FirstString is
688 identical to SecondString, then 0 is returned. Otherwise, the value returned
689 is the first mismatched ASCII character in SecondString subtracted from the
690 first mismatched ASCII character in FirstString.
692 If FirstString is NULL, then ASSERT().
693 If SecondString is NULL, then ASSERT().
694 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
695 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
697 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than
698 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
701 @param FirstString Pointer to a Null-terminated ASCII string.
702 @param SecondString Pointer to a Null-terminated ASCII string.
704 @retval 0 FirstString is identical to SecondString.
705 @retval !=0 FirstString is not identical to SecondString.
711 IN CONST CHAR8
*FirstString
,
712 IN CONST CHAR8
*SecondString
,
721 // ASSERT both strings are less long than PcdMaximumAsciiStringLength
723 ASSERT (AsciiStrSize (FirstString
));
724 ASSERT (AsciiStrSize (SecondString
));
726 while ((*FirstString
!= '\0') &&
727 (*FirstString
== *SecondString
) &&
733 return *FirstString
- *SecondString
;
737 Concatenates one Null-terminated ASCII string to another Null-terminated
738 ASCII string, and returns the concatenated ASCII string.
740 This function concatenates two Null-terminated ASCII strings. The contents of
741 Null-terminated ASCII string Source are concatenated to the end of Null-
742 terminated ASCII string Destination. The Null-terminated concatenated ASCII
745 If Destination is NULL, then ASSERT().
746 If Source is NULL, then ASSERT().
747 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
748 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
750 If PcdMaximumAsciiStringLength is not zero and Source contains more than
751 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
753 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
754 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
755 ASCII characters, then ASSERT().
757 @param Destination Pointer to a Null-terminated ASCII string.
758 @param Source Pointer to a Null-terminated ASCII string.
766 IN OUT CHAR8
*Destination
,
767 IN CONST CHAR8
*Source
770 AsciiStrCpy (Destination
+ AsciiStrLen (Destination
), Source
);
773 // Size of the resulting string should never be zero.
774 // PcdMaximumUnicodeStringLength is tested inside StrLen().
776 ASSERT (AsciiStrSize (Destination
) != 0);
781 Concatenates one Null-terminated ASCII string with a maximum length to the
782 end of another Null-terminated ASCII string, and returns the concatenated
785 This function concatenates two Null-terminated ASCII strings. The contents
786 of Null-terminated ASCII string Source are concatenated to the end of Null-
787 terminated ASCII string Destination, and Destination is returned. At most,
788 Length ASCII characters are concatenated from Source to the end of
789 Destination, and Destination is always Null-terminated. If Length is 0, then
790 Destination is returned unmodified. If Source and Destination overlap, then
791 the results are undefined.
793 If Destination is NULL, then ASSERT().
794 If Source is NULL, then ASSERT().
795 If Source and Destination overlap, then ASSERT().
796 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
797 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
799 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
800 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
802 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
803 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
804 ASCII characters not including the Null-terminator, then ASSERT().
806 @param Destination Pointer to a Null-terminated ASCII string.
807 @param Source Pointer to a Null-terminated ASCII string.
808 @param Length Maximum number of ASCII characters to concatenate from
817 IN OUT CHAR8
*Destination
,
818 IN CONST CHAR8
*Source
,
822 AsciiStrnCpy (Destination
+ AsciiStrLen (Destination
), Source
, Length
);
825 // Size of the resulting string should never be zero.
826 // PcdMaximumUnicodeStringLength is tested inside StrLen().
828 ASSERT (AsciiStrSize (Destination
) != 0);
833 Converts an 8-bit value to an 8-bit BCD value.
835 Converts the 8-bit value specified by Value to BCD. The BCD value is
838 If Value >= 100, then ASSERT().
840 @param Value The 8-bit value to convert to BCD. Range 0..99.
842 @return The BCD value
851 ASSERT (Value
< 100);
852 return ((Value
/ 10) << 4) | (Value
% 10);
856 Converts an 8-bit BCD value to an 8-bit value.
858 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
861 If Value >= 0xA0, then ASSERT().
862 If (Value & 0x0F) >= 0x0A, then ASSERT().
864 @param Value The 8-bit BCD value to convert to an 8-bit value.
866 @return The 8-bit value is returned.
875 ASSERT (Value
< 0xa0);
876 ASSERT ((Value
& 0xf) < 0xa);
877 return (Value
>> 4) * 10 + (Value
& 0xf);