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