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 }