Tools/Source/TianoTools/String/String.c

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