Add new OSS License
[mirror_edk2.git] / Tools / Source / TianoTools / String / String.c
1 /** @file
2 Unicode string primatives.
3
4 Copyright (c) 2004-2006 Intel Corporation. All rights reserved
5 This software and associated documentation (if any) is furnished
6 under a license and may only be used or copied in accordance
7 with the terms of the license. Except as permitted by such
8 license, no part of this software or documentation may be
9 reproduced, stored in a retrieval system, or transmitted in any
10 form or by any means without the express written consent of
11 Intel Corporation.
12
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16 Module Name: String.c
17
18 **/
19
20 #include <assert.h>
21
22 #include <Common/UefiBaseTypes.h>
23
24 #include "CommonLib.h"
25
26 /**
27 Returns the length of a Null-terminated Unicode string.
28
29 This function returns the number of Unicode characters in the Null-terminated
30 Unicode string specified by String.
31
32 If String is NULL, then ASSERT().
33
34 @param String Pointer to a Null-terminated Unicode string.
35
36 @return The length of String.
37
38 **/
39 UINTN
40 EFIAPI
41 StrLen (
42 IN CONST CHAR16 *String
43 )
44 {
45 UINTN Length;
46
47 ASSERT (String != NULL);
48
49 for (Length = 0; *String != L'\0'; String++, Length++) {
50 ;
51 }
52 return Length;
53 }
54
55 /**
56 Returns the length of a Null-terminated ASCII string.
57
58 This function returns the number of ASCII characters in the Null-terminated
59 ASCII string specified by String.
60
61 If String is NULL, then ASSERT().
62
63 @param String Pointer to a Null-terminated ASCII string.
64
65 @return The length of String.
66
67 **/
68 UINTN
69 EFIAPI
70 AsciiStrLen (
71 IN CONST CHAR8 *String
72 )
73 {
74 UINTN Length;
75
76 ASSERT (String != NULL);
77
78 for (Length = 0; *String != '\0'; String++, Length++) {
79 ;
80 }
81 return Length;
82 }
83
84 /**
85 Copies one Null-terminated Unicode string to another Null-terminated Unicode
86 string and returns the new Unicode string.
87
88 This function copies the contents of the Unicode string Source to the Unicode
89 string Destination, and returns Destination. If Source and Destination
90 overlap, then the results are undefined.
91
92 If Destination is NULL, then ASSERT().
93 If Source is NULL, then ASSERT().
94 If Source and Destination overlap, then ASSERT().
95
96 @param Destination Pointer to a Null-terminated Unicode string.
97 @param Source Pointer to a Null-terminated Unicode string.
98
99 @return Destiantion
100
101 **/
102 CHAR16 *
103 EFIAPI
104 StrCpy (
105 OUT CHAR16 *Destination,
106 IN CONST CHAR16 *Source
107 )
108 {
109 CHAR16 *ReturnValue;
110
111 //
112 // Destination cannot be NULL
113 //
114 ASSERT (Destination != NULL);
115
116 //
117 // Destination and source cannot overlap
118 //
119 ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
120 ASSERT ((UINTN)(Source - Destination) > StrLen (Source));
121
122 ReturnValue = Destination;
123 while (*Source) {
124 *(Destination++) = *(Source++);
125 }
126 *Destination = 0;
127 return ReturnValue;
128 }
129
130 /**
131 Copies one Null-terminated Unicode string with a maximum length to another
132 Null-terminated Unicode string with a maximum length and returns the new
133 Unicode string.
134
135 This function copies the contents of the Unicode string Source to the Unicode
136 string Destination, and returns Destination. At most, Length Unicode
137 characters are copied from Source to Destination. If Length is 0, then
138 Destination is returned unmodified. If Length is greater that the number of
139 Unicode characters in Source, then Destination is padded with Null Unicode
140 characters. If Source and Destination overlap, then the results are
141 undefined.
142
143 If Destination is NULL, then ASSERT().
144 If Source is NULL, then ASSERT().
145 If Source and Destination overlap, then ASSERT().
146
147 @param Destination Pointer to a Null-terminated Unicode string.
148 @param Source Pointer to a Null-terminated Unicode string.
149 @param Length Maximum number of Unicode characters to copy.
150
151 @return Destination
152
153 **/
154 CHAR16 *
155 EFIAPI
156 StrnCpy (
157 OUT CHAR16 *Destination,
158 IN CONST CHAR16 *Source,
159 IN UINTN Length
160 )
161 {
162 CHAR16 *ReturnValue;
163
164 if (Length == 0) {
165 return Destination;
166 }
167
168 //
169 // Destination cannot be NULL if Length is not zero
170 //
171 ASSERT (Destination != NULL);
172
173 //
174 // Destination and source cannot overlap
175 // Q: Does Source have to be NULL-terminated?
176 //
177 ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
178 ASSERT ((UINTN)(Source - Destination) >= Length);
179
180 ReturnValue = Destination;
181
182 while ((*Source != L'\0') && (Length > 0)) {
183 *(Destination++) = *(Source++);
184 Length--;
185 }
186
187 memset (Destination, 0, Length * sizeof (*Destination));
188 return ReturnValue;
189 }
190
191 /**
192 Returns the size of a Null-terminated Unicode string in bytes, including the
193 Null terminator.
194
195 This function returns the size, in bytes, of the Null-terminated Unicode
196 string specified by String.
197
198 If String is NULL, then ASSERT().
199
200 @param String Pointer to a Null-terminated Unicode string.
201
202 @return The size of String.
203
204 **/
205 UINTN
206 EFIAPI
207 StrSize (
208 IN CONST CHAR16 *String
209 )
210 {
211 return (StrLen (String) + 1) * sizeof (*String);
212 }
213
214 /**
215 Compares two Null-terminated Unicode strings, and returns the difference
216 between the first mismatched Unicode characters.
217
218 This function compares the Null-terminated Unicode string FirstString to the
219 Null-terminated Unicode string SecondString. If FirstString is identical to
220 SecondString, then 0 is returned. Otherwise, the value returned is the first
221 mismatched Unicode character in SecondString subtracted from the first
222 mismatched Unicode character in FirstString.
223
224 If FirstString is NULL, then ASSERT().
225 If SecondString is NULL, then ASSERT().
226
227 @param FirstString Pointer to a Null-terminated Unicode string.
228 @param SecondString Pointer to a Null-terminated Unicode string.
229
230 @retval 0 FirstString is identical to SecondString.
231 @retval !=0 FirstString is not identical to SecondString.
232
233 **/
234 INTN
235 EFIAPI
236 StrCmp (
237 IN CONST CHAR16 *FirstString,
238 IN CONST CHAR16 *SecondString
239 )
240 {
241 //
242 // ASSERT both strings should never be zero
243 //
244 ASSERT (StrSize (FirstString) != 0);
245 ASSERT (StrSize (SecondString) != 0);
246
247 while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {
248 FirstString++;
249 SecondString++;
250 }
251 return *FirstString - *SecondString;
252 }
253
254 /**
255 Compares two Null-terminated Unicode strings with maximum lengths, and
256 returns the difference between the first mismatched Unicode characters.
257
258 This function compares the Null-terminated Unicode string FirstString to the
259 Null-terminated Unicode string SecondString. At most, Length Unicode
260 characters will be compared. If Length is 0, then 0 is returned. If
261 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
262 value returned is the first mismatched Unicode character in SecondString
263 subtracted from the first mismatched Unicode character in FirstString.
264
265 If FirstString is NULL, then ASSERT().
266 If SecondString is NULL, then ASSERT().
267
268 @param FirstString Pointer to a Null-terminated Unicode string.
269 @param SecondString Pointer to a Null-terminated Unicode string.
270 @param Length Maximum number of Unicode characters to compare.
271
272 @retval 0 FirstString is identical to SecondString.
273 @retval !=0 FirstString is not identical to SecondString.
274
275 **/
276 INTN
277 EFIAPI
278 StrnCmp (
279 IN CONST CHAR16 *FirstString,
280 IN CONST CHAR16 *SecondString,
281 IN UINTN Length
282 )
283 {
284 if (Length == 0) {
285 return 0;
286 }
287
288 //
289 // ASSERT both strings should never be zero
290 //
291 ASSERT (StrSize (FirstString) != 0);
292 ASSERT (StrSize (SecondString) != 0);
293
294 while ((*FirstString != L'\0') &&
295 (*FirstString == *SecondString) &&
296 (Length > 1)) {
297 FirstString++;
298 SecondString++;
299 Length--;
300 }
301
302 return *FirstString - *SecondString;
303 }
304
305 /**
306 Concatenates one Null-terminated Unicode string to another Null-terminated
307 Unicode string, and returns the concatenated Unicode string.
308
309 This function concatenates two Null-terminated Unicode strings. The contents
310 of Null-terminated Unicode string Source are concatenated to the end of
311 Null-terminated Unicode string Destination. The Null-terminated concatenated
312 Unicode String is returned. If Source and Destination overlap, then the
313 results are undefined.
314
315 If Destination is NULL, then ASSERT().
316 If Source is NULL, then ASSERT().
317 If Source and Destination overlap, then ASSERT().
318
319 @param Destination Pointer to a Null-terminated Unicode string.
320 @param Source Pointer to a Null-terminated Unicode string.
321
322 @return Destination
323
324 **/
325 CHAR16 *
326 EFIAPI
327 StrCat (
328 IN OUT CHAR16 *Destination,
329 IN CONST CHAR16 *Source
330 )
331 {
332 StrCpy (Destination + StrLen (Destination), Source);
333
334 //
335 // Size of the resulting string should never be zero.
336 //
337 ASSERT (StrSize (Destination) != 0);
338 return Destination;
339 }
340
341 /**
342 Concatenates one Null-terminated Unicode string with a maximum length to the
343 end of another Null-terminated Unicode string, and returns the concatenated
344 Unicode string.
345
346 This function concatenates two Null-terminated Unicode strings. The contents
347 of Null-terminated Unicode string Source are concatenated to the end of
348 Null-terminated Unicode string Destination, and Destination is returned. At
349 most, Length Unicode characters are concatenated from Source to the end of
350 Destination, and Destination is always Null-terminated. If Length is 0, then
351 Destination is returned unmodified. If Source and Destination overlap, then
352 the results are undefined.
353
354 If Destination is NULL, then ASSERT().
355 If Source is NULL, then ASSERT().
356 If Source and Destination overlap, then ASSERT().
357
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
361 Source.
362
363 @return Destination
364
365 **/
366 CHAR16 *
367 EFIAPI
368 StrnCat (
369 IN OUT CHAR16 *Destination,
370 IN CONST CHAR16 *Source,
371 IN UINTN Length
372 )
373 {
374 StrnCpy (Destination + StrLen (Destination), Source, Length);
375
376 //
377 // Size of the resulting string should never be zero.
378 //
379 ASSERT (StrSize (Destination) != 0);
380 return Destination;
381 }
382
383 /**
384 Copies one Null-terminated ASCII string to another Null-terminated ASCII
385 string and returns the new ASCII string.
386
387 This function copies the contents of the ASCII string Source to the ASCII
388 string Destination, and returns Destination. If Source and Destination
389 overlap, then the results are undefined.
390
391 If Destination is NULL, then ASSERT().
392 If Source is NULL, then ASSERT().
393 If Source and Destination overlap, then ASSERT().
394
395 @param Destination Pointer to a Null-terminated ASCII string.
396 @param Source Pointer to a Null-terminated ASCII string.
397
398 @return Destination
399
400 **/
401 CHAR8 *
402 EFIAPI
403 AsciiStrCpy (
404 OUT CHAR8 *Destination,
405 IN CONST CHAR8 *Source
406 )
407 {
408 CHAR8 *ReturnValue;
409
410 //
411 // Destination cannot be NULL
412 //
413 ASSERT (Destination != NULL);
414
415 //
416 // Destination and source cannot overlap
417 //
418 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
419 ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source));
420
421 ReturnValue = Destination;
422 while (*Source) {
423 *(Destination++) = *(Source++);
424 }
425 *Destination = 0;
426 return ReturnValue;
427 }
428
429 /**
430 Copies one Null-terminated ASCII string with a maximum length to another
431 Null-terminated ASCII string with a maximum length and returns the new ASCII
432 string.
433
434 This function copies the contents of the ASCII string Source to the ASCII
435 string Destination, and returns Destination. At most, Length ASCII characters
436 are copied from Source to Destination. If Length is 0, then Destination is
437 returned unmodified. If Length is greater that the number of ASCII characters
438 in Source, then Destination is padded with Null ASCII characters. If Source
439 and Destination overlap, then the results are undefined.
440
441 If Destination is NULL, then ASSERT().
442 If Source is NULL, then ASSERT().
443 If Source and Destination overlap, then ASSERT().
444
445 @param Destination Pointer to a Null-terminated ASCII string.
446 @param Source Pointer to a Null-terminated ASCII string.
447 @param Length Maximum number of ASCII characters to copy.
448
449 @return Destination
450
451 **/
452 CHAR8 *
453 EFIAPI
454 AsciiStrnCpy (
455 OUT CHAR8 *Destination,
456 IN CONST CHAR8 *Source,
457 IN UINTN Length
458 )
459 {
460 CHAR8 *ReturnValue;
461
462 if (Length == 0) {
463 return Destination;
464 }
465
466 //
467 // Destination cannot be NULL
468 //
469 ASSERT (Destination != NULL);
470
471 //
472 // Destination and source cannot overlap
473 //
474 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
475 ASSERT ((UINTN)(Source - Destination) >= Length);
476
477 ReturnValue = Destination;
478
479 while (*Source && Length > 0) {
480 *(Destination++) = *(Source++);
481 Length--;
482 }
483
484 // ZeroMem (Destination, Length * sizeof (*Destination));
485 memset (Destination, 0, Length * sizeof (*Destination));
486 return ReturnValue;
487 }
488
489 /**
490 Returns the size of a Null-terminated ASCII string in bytes, including the
491 Null terminator.
492
493 This function returns the size, in bytes, of the Null-terminated ASCII string
494 specified by String.
495
496 If String is NULL, then ASSERT().
497
498 @param String Pointer to a Null-terminated ASCII string.
499
500 @return The size of String.
501
502 **/
503 UINTN
504 EFIAPI
505 AsciiStrSize (
506 IN CONST CHAR8 *String
507 )
508 {
509 return (AsciiStrLen (String) + 1) * sizeof (*String);
510 }
511
512 /**
513 Compares two Null-terminated ASCII strings, and returns the difference
514 between the first mismatched ASCII characters.
515
516 This function compares the Null-terminated ASCII string FirstString to the
517 Null-terminated ASCII string SecondString. If FirstString is identical to
518 SecondString, then 0 is returned. Otherwise, the value returned is the first
519 mismatched ASCII character in SecondString subtracted from the first
520 mismatched ASCII character in FirstString.
521
522 If FirstString is NULL, then ASSERT().
523 If SecondString is NULL, then ASSERT().
524
525 @param FirstString Pointer to a Null-terminated ASCII string.
526 @param SecondString Pointer to a Null-terminated ASCII string.
527
528 @retval 0 FirstString is identical to SecondString.
529 @retval !=0 FirstString is not identical to SecondString.
530
531 **/
532 INTN
533 EFIAPI
534 AsciiStrCmp (
535 IN CONST CHAR8 *FirstString,
536 IN CONST CHAR8 *SecondString
537 )
538 {
539 //
540 // ASSERT both strings should never be zero
541 //
542 ASSERT (AsciiStrSize (FirstString));
543 ASSERT (AsciiStrSize (SecondString));
544
545 while ((*FirstString != '\0') && (*FirstString == *SecondString)) {
546 FirstString++;
547 SecondString++;
548 }
549
550 return *FirstString - *SecondString;
551 }
552
553 STATIC
554 CHAR8
555 EFIAPI
556 AsciiToUpper (
557 IN CHAR8 Chr
558 )
559 {
560 return (Chr >= 'a' && Chr <= 'z') ? Chr - ('a' - 'A') : Chr;
561 }
562
563 /**
564 Performs a case insensitive comparison of two Null-terminated ASCII strings,
565 and returns the difference between the first mismatched ASCII characters.
566
567 This function performs a case insensitive comparison of the Null-terminated
568 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
569 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
570 value returned is the first mismatched lower case ASCII character in
571 SecondString subtracted from the first mismatched lower case ASCII character
572 in FirstString.
573
574 If FirstString is NULL, then ASSERT().
575 If SecondString is NULL, then ASSERT().
576
577 @param FirstString Pointer to a Null-terminated ASCII string.
578 @param SecondString Pointer to a Null-terminated ASCII string.
579
580 @retval 0 FirstString is identical to SecondString using case insensitive
581 comparisons.
582 @retval !=0 FirstString is not identical to SecondString using case
583 insensitive comparisons.
584
585 **/
586 INTN
587 EFIAPI
588 AsciiStriCmp (
589 IN CONST CHAR8 *FirstString,
590 IN CONST CHAR8 *SecondString
591 )
592 {
593 //
594 // ASSERT both strings should never be zero
595 //
596 ASSERT (AsciiStrSize (FirstString));
597 ASSERT (AsciiStrSize (SecondString));
598
599 while ((*FirstString != '\0') &&
600 (AsciiToUpper (*FirstString) == AsciiToUpper (*SecondString))) {
601 FirstString++;
602 SecondString++;
603 }
604
605 return AsciiToUpper (*FirstString) - AsciiToUpper (*SecondString);
606 }
607
608 /**
609 Compares two Null-terminated ASCII strings with maximum lengths, and returns
610 the difference between the first mismatched ASCII characters.
611
612 This function compares the Null-terminated ASCII string FirstString to the
613 Null-terminated ASCII string SecondString. At most, Length ASCII characters
614 will be compared. If Length is 0, then 0 is returned. If FirstString is
615 identical to SecondString, then 0 is returned. Otherwise, the value returned
616 is the first mismatched ASCII character in SecondString subtracted from the
617 first mismatched ASCII character in FirstString.
618
619 If FirstString is NULL, then ASSERT().
620 If SecondString is NULL, then ASSERT().
621
622 @param FirstString Pointer to a Null-terminated ASCII string.
623 @param SecondString Pointer to a Null-terminated ASCII string.
624
625 @retval 0 FirstString is identical to SecondString.
626 @retval !=0 FirstString is not identical to SecondString.
627
628 **/
629 INTN
630 EFIAPI
631 AsciiStrnCmp (
632 IN CONST CHAR8 *FirstString,
633 IN CONST CHAR8 *SecondString,
634 IN UINTN Length
635 )
636 {
637 //
638 // ASSERT both strings should never be zero
639 //
640 ASSERT (AsciiStrSize (FirstString));
641 ASSERT (AsciiStrSize (SecondString));
642
643 while ((*FirstString != '\0') &&
644 (*FirstString == *SecondString) &&
645 (Length > 1)) {
646 FirstString++;
647 SecondString++;
648 Length--;
649 }
650 return *FirstString - *SecondString;
651 }
652
653 /**
654 Concatenates one Null-terminated ASCII string to another Null-terminated
655 ASCII string, and returns the concatenated ASCII string.
656
657 This function concatenates two Null-terminated ASCII strings. The contents of
658 Null-terminated ASCII string Source are concatenated to the end of Null-
659 terminated ASCII string Destination. The Null-terminated concatenated ASCII
660 String is returned.
661
662 If Destination is NULL, then ASSERT().
663 If Source is NULL, then ASSERT().
664
665 @param Destination Pointer to a Null-terminated ASCII string.
666 @param Source Pointer to a Null-terminated ASCII string.
667
668 @return Destination
669
670 **/
671 CHAR8 *
672 EFIAPI
673 AsciiStrCat (
674 IN OUT CHAR8 *Destination,
675 IN CONST CHAR8 *Source
676 )
677 {
678 AsciiStrCpy (Destination + AsciiStrLen (Destination), Source);
679
680 //
681 // Size of the resulting string should never be zero.
682 //
683 ASSERT (AsciiStrSize (Destination) != 0);
684 return Destination;
685 }
686
687 /**
688 Concatenates one Null-terminated ASCII string with a maximum length to the
689 end of another Null-terminated ASCII string, and returns the concatenated
690 ASCII string.
691
692 This function concatenates two Null-terminated ASCII strings. The contents
693 of Null-terminated ASCII string Source are concatenated to the end of Null-
694 terminated ASCII string Destination, and Destination is returned. At most,
695 Length ASCII characters are concatenated from Source to the end of
696 Destination, and Destination is always Null-terminated. If Length is 0, then
697 Destination is returned unmodified. If Source and Destination overlap, then
698 the results are undefined.
699
700 If Destination is NULL, then ASSERT().
701 If Source is NULL, then ASSERT().
702 If Source and Destination overlap, then ASSERT().
703
704 @param Destination Pointer to a Null-terminated ASCII string.
705 @param Source Pointer to a Null-terminated ASCII string.
706 @param Length Maximum number of ASCII characters to concatenate from
707 Source.
708
709 @return Destination
710
711 **/
712 CHAR8 *
713 EFIAPI
714 AsciiStrnCat (
715 IN OUT CHAR8 *Destination,
716 IN CONST CHAR8 *Source,
717 IN UINTN Length
718 )
719 {
720 AsciiStrnCpy (Destination + AsciiStrLen (Destination), Source, Length);
721
722 //
723 // Size of the resulting string should never be zero.
724 //
725 ASSERT (AsciiStrSize (Destination) != 0);
726 return Destination;
727 }