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