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   Returns the length of a Null-terminated Unicode string.
  25
  26   This function returns the number of Unicode characters in the Null-terminated
  27   Unicode string specified by String.
  28
  29   If String is NULL, then ASSERT().
  30
  31   @param  String  Pointer to a Null-terminated Unicode string.
  32
  33   @return The length of String.
  34
  35 **/
  36 UINTN
  37 EFIAPI
  38 StrLen (
  39   IN      CONST CHAR16              *String
  40   )
  41 {
  42   UINTN                             Length;
  43
  44   ASSERT (String != NULL);
  45
  46   for (Length = 0; *String != L'\0'; String++, Length++) {
  47     ;
  48   }
  49   return Length;
  50 }
  51
  52 /**
  53   Returns the length of a Null-terminated ASCII string.
  54
  55   This function returns the number of ASCII characters in the Null-terminated
  56   ASCII string specified by String.
  57
  58   If String is NULL, then ASSERT().
  59
  60   @param  String  Pointer to a Null-terminated ASCII string.
  61
  62   @return The length of String.
  63
  64 **/
  65 UINTN
  66 EFIAPI
  67 AsciiStrLen (
  68   IN      CONST CHAR8               *String
  69   )
  70 {
  71   UINTN                             Length;
  72
  73   ASSERT (String != NULL);
  74
  75   for (Length = 0; *String != '\0'; String++, Length++) {
  76     ;
  77   }
  78   return Length;
  79 }
  80
  81 /**
  82   Copies one Null-terminated Unicode string to another Null-terminated Unicode
  83   string and returns the new Unicode string.
  84
  85   This function copies the contents of the Unicode string Source to the Unicode
  86   string Destination, and returns Destination. If Source and Destination
  87   overlap, then the results are undefined.
  88
  89   If Destination is NULL, then ASSERT().
  90   If Source is NULL, then ASSERT().
  91   If Source and Destination overlap, then ASSERT().
  92
  93   @param  Destination Pointer to a Null-terminated Unicode string.
  94   @param  Source      Pointer to a Null-terminated Unicode string.
  95
  96   @return Destiantion
  97
  98 **/
  99 CHAR16 *
 100 EFIAPI
 101 StrCpy (
 102   OUT     CHAR16                    *Destination,
 103   IN      CONST CHAR16              *Source
 104   )
 105 {
 106   CHAR16                            *ReturnValue;
 107
 108   //
 109   // Destination cannot be NULL
 110   //
 111   ASSERT (Destination != NULL);
 112
 113   //
 114   // Destination and source cannot overlap
 115   //
 116   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
 117   ASSERT ((UINTN)(Source - Destination) > StrLen (Source));
 118
 119   ReturnValue = Destination;
 120   while (*Source) {
 121     *(Destination++) = *(Source++);
 122   }
 123   *Destination = 0;
 124   return ReturnValue;
 125 }
 126
 127 /**
 128   Copies one Null-terminated Unicode string with a maximum length to another
 129   Null-terminated Unicode string with a maximum length and returns the new
 130   Unicode string.
 131
 132   This function copies the contents of the Unicode string Source to the Unicode
 133   string Destination, and returns Destination. At most, Length Unicode
 134   characters are copied from Source to Destination. If Length is 0, then
 135   Destination is returned unmodified. If Length is greater that the number of
 136   Unicode characters in Source, then Destination is padded with Null Unicode
 137   characters. If Source and Destination overlap, then the results are
 138   undefined.
 139
 140   If Destination is NULL, then ASSERT().
 141   If Source is NULL, then ASSERT().
 142   If Source and Destination overlap, then ASSERT().
 143
 144   @param  Destination Pointer to a Null-terminated Unicode string.
 145   @param  Source      Pointer to a Null-terminated Unicode string.
 146   @param  Length      Maximum number of Unicode characters to copy.
 147
 148   @return Destination
 149
 150 **/
 151 CHAR16 *
 152 EFIAPI
 153 StrnCpy (
 154   OUT     CHAR16                    *Destination,
 155   IN      CONST CHAR16              *Source,
 156   IN      UINTN                     Length
 157   )
 158 {
 159   CHAR16                            *ReturnValue;
 160
 161   if (Length == 0) {
 162     return Destination;
 163   }
 164
 165   //
 166   // Destination cannot be NULL if Length is not zero
 167   //
 168   ASSERT (Destination != NULL);
 169
 170   //
 171   // Destination and source cannot overlap
 172   // Q: Does Source have to be NULL-terminated?
 173   //
 174   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
 175   ASSERT ((UINTN)(Source - Destination) >= Length);
 176
 177   ReturnValue = Destination;
 178
 179   while ((*Source != L'\0') && (Length > 0)) {
 180     *(Destination++) = *(Source++);
 181     Length--;
 182   }
 183
 184   memset (Destination, 0, Length * sizeof (*Destination));
 185   return ReturnValue;
 186 }
 187
 188 /**
 189   Returns the size of a Null-terminated Unicode string in bytes, including the
 190   Null terminator.
 191
 192   This function returns the size, in bytes, of the Null-terminated Unicode
 193   string specified by String.
 194
 195   If String is NULL, then ASSERT().
 196
 197   @param  String  Pointer to a Null-terminated Unicode string.
 198
 199   @return The size of String.
 200
 201 **/
 202 UINTN
 203 EFIAPI
 204 StrSize (
 205   IN      CONST CHAR16              *String
 206   )
 207 {
 208   return (StrLen (String) + 1) * sizeof (*String);
 209 }
 210
 211 /**
 212   Compares two Null-terminated Unicode strings, and returns the difference
 213   between the first mismatched Unicode characters.
 214
 215   This function compares the Null-terminated Unicode string FirstString to the
 216   Null-terminated Unicode string SecondString. If FirstString is identical to
 217   SecondString, then 0 is returned. Otherwise, the value returned is the first
 218   mismatched Unicode character in SecondString subtracted from the first
 219   mismatched Unicode character in FirstString.
 220
 221   If FirstString is NULL, then ASSERT().
 222   If SecondString is NULL, then ASSERT().
 223
 224   @param  FirstString   Pointer to a Null-terminated Unicode string.
 225   @param  SecondString  Pointer to a Null-terminated Unicode string.
 226
 227   @retval 0   FirstString is identical to SecondString.
 228   @retval !=0 FirstString is not identical to SecondString.
 229
 230 **/
 231 INTN
 232 EFIAPI
 233 StrCmp (
 234   IN      CONST CHAR16              *FirstString,
 235   IN      CONST CHAR16              *SecondString
 236   )
 237 {
 238   //
 239   // ASSERT both strings should never be zero
 240   //
 241   ASSERT (StrSize (FirstString) != 0);
 242   ASSERT (StrSize (SecondString) != 0);
 243
 244   while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {
 245     FirstString++;
 246     SecondString++;
 247   }
 248   return *FirstString - *SecondString;
 249 }
 250
 251 /**
 252   Compares two Null-terminated Unicode strings with maximum lengths, and
 253   returns the difference between the first mismatched Unicode characters.
 254
 255   This function compares the Null-terminated Unicode string FirstString to the
 256   Null-terminated Unicode string SecondString. At most, Length Unicode
 257   characters will be compared. If Length is 0, then 0 is returned. If
 258   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
 259   value returned is the first mismatched Unicode character in SecondString
 260   subtracted from the first mismatched Unicode character in FirstString.
 261
 262   If FirstString is NULL, then ASSERT().
 263   If SecondString is NULL, then ASSERT().
 264
 265   @param  FirstString   Pointer to a Null-terminated Unicode string.
 266   @param  SecondString  Pointer to a Null-terminated Unicode string.
 267   @param  Length        Maximum number of Unicode characters to compare.
 268
 269   @retval 0   FirstString is identical to SecondString.
 270   @retval !=0 FirstString is not identical to SecondString.
 271
 272 **/
 273 INTN
 274 EFIAPI
 275 StrnCmp (
 276   IN      CONST CHAR16              *FirstString,
 277   IN      CONST CHAR16              *SecondString,
 278   IN      UINTN                     Length
 279   )
 280 {
 281   if (Length == 0) {
 282     return 0;
 283   }
 284
 285   //
 286   // ASSERT both strings should never be zero
 287   //
 288   ASSERT (StrSize (FirstString) != 0);
 289   ASSERT (StrSize (SecondString) != 0);
 290
 291   while ((*FirstString != L'\0') &&
 292          (*FirstString == *SecondString) &&
 293          (Length > 1)) {
 294     FirstString++;
 295     SecondString++;
 296     Length--;
 297   }
 298
 299   return *FirstString - *SecondString;
 300 }
 301
 302 /**
 303   Concatenates one Null-terminated Unicode string to another Null-terminated
 304   Unicode string, and returns the concatenated Unicode string.
 305
 306   This function concatenates two Null-terminated Unicode strings. The contents
 307   of Null-terminated Unicode string Source are concatenated to the end of
 308   Null-terminated Unicode string Destination. The Null-terminated concatenated
 309   Unicode String is returned. If Source and Destination overlap, then the
 310   results are undefined.
 311
 312   If Destination is NULL, then ASSERT().
 313   If Source is NULL, then ASSERT().
 314   If Source and Destination overlap, then ASSERT().
 315
 316   @param  Destination Pointer to a Null-terminated Unicode string.
 317   @param  Source      Pointer to a Null-terminated Unicode string.
 318
 319   @return Destination
 320
 321 **/
 322 CHAR16 *
 323 EFIAPI
 324 StrCat (
 325   IN OUT  CHAR16                    *Destination,
 326   IN      CONST CHAR16              *Source
 327   )
 328 {
 329   StrCpy (Destination + StrLen (Destination), Source);
 330
 331   //
 332   // Size of the resulting string should never be zero.
 333   //
 334   ASSERT (StrSize (Destination) != 0);
 335   return Destination;
 336 }
 337
 338 /**
 339   Concatenates one Null-terminated Unicode string with a maximum length to the
 340   end of another Null-terminated Unicode string, and returns the concatenated
 341   Unicode string.
 342
 343   This function concatenates two Null-terminated Unicode strings. The contents
 344   of Null-terminated Unicode string Source are concatenated to the end of
 345   Null-terminated Unicode string Destination, and Destination is returned. At
 346   most, Length Unicode characters are concatenated from Source to the end of
 347   Destination, and Destination is always Null-terminated. If Length is 0, then
 348   Destination is returned unmodified. If Source and Destination overlap, then
 349   the results are undefined.
 350
 351   If Destination is NULL, then ASSERT().
 352   If Source is NULL, then ASSERT().
 353   If Source and Destination overlap, then ASSERT().
 354
 355   @param  Destination Pointer to a Null-terminated Unicode string.
 356   @param  Source      Pointer to a Null-terminated Unicode string.
 357   @param  Length      Maximum number of Unicode characters to concatenate from
 358                       Source.
 359
 360   @return Destination
 361
 362 **/
 363 CHAR16 *
 364 EFIAPI
 365 StrnCat (
 366   IN OUT  CHAR16                    *Destination,
 367   IN      CONST CHAR16              *Source,
 368   IN      UINTN                     Length
 369   )
 370 {
 371   StrnCpy (Destination + StrLen (Destination), Source, Length);
 372
 373   //
 374   // Size of the resulting string should never be zero.
 375   //
 376   ASSERT (StrSize (Destination) != 0);
 377   return Destination;
 378 }
 379
 380 /**
 381   Copies one Null-terminated ASCII string to another Null-terminated ASCII
 382   string and returns the new ASCII string.
 383
 384   This function copies the contents of the ASCII string Source to the ASCII
 385   string Destination, and returns Destination. If Source and Destination
 386   overlap, then the results are undefined.
 387
 388   If Destination is NULL, then ASSERT().
 389   If Source is NULL, then ASSERT().
 390   If Source and Destination overlap, then ASSERT().
 391
 392   @param  Destination Pointer to a Null-terminated ASCII string.
 393   @param  Source      Pointer to a Null-terminated ASCII string.
 394
 395   @return Destination
 396
 397 **/
 398 CHAR8 *
 399 EFIAPI
 400 AsciiStrCpy (
 401   OUT     CHAR8                     *Destination,
 402   IN      CONST CHAR8               *Source
 403   )
 404 {
 405   CHAR8                             *ReturnValue;
 406
 407   //
 408   // Destination cannot be NULL
 409   //
 410   ASSERT (Destination != NULL);
 411
 412   //
 413   // Destination and source cannot overlap
 414   //
 415   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
 416   ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source));
 417
 418   ReturnValue = Destination;
 419   while (*Source) {
 420     *(Destination++) = *(Source++);
 421   }
 422   *Destination = 0;
 423   return ReturnValue;
 424 }
 425
 426 /**
 427   Copies one Null-terminated ASCII string with a maximum length to another
 428   Null-terminated ASCII string with a maximum length and returns the new ASCII
 429   string.
 430
 431   This function copies the contents of the ASCII string Source to the ASCII
 432   string Destination, and returns Destination. At most, Length ASCII characters
 433   are copied from Source to Destination. If Length is 0, then Destination is
 434   returned unmodified. If Length is greater that the number of ASCII characters
 435   in Source, then Destination is padded with Null ASCII characters. If Source
 436   and Destination overlap, then the results are undefined.
 437
 438   If Destination is NULL, then ASSERT().
 439   If Source is NULL, then ASSERT().
 440   If Source and Destination overlap, then ASSERT().
 441
 442   @param  Destination Pointer to a Null-terminated ASCII string.
 443   @param  Source      Pointer to a Null-terminated ASCII string.
 444   @param  Length      Maximum number of ASCII characters to copy.
 445
 446   @return Destination
 447
 448 **/
 449 CHAR8 *
 450 EFIAPI
 451 AsciiStrnCpy (
 452   OUT     CHAR8                     *Destination,
 453   IN      CONST CHAR8               *Source,
 454   IN      UINTN                     Length
 455   )
 456 {
 457   CHAR8                             *ReturnValue;
 458
 459   if (Length == 0) {
 460     return Destination;
 461   }
 462
 463   //
 464   // Destination cannot be NULL
 465   //
 466   ASSERT (Destination != NULL);
 467
 468   //
 469   // Destination and source cannot overlap
 470   //
 471   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
 472   ASSERT ((UINTN)(Source - Destination) >= Length);
 473
 474   ReturnValue = Destination;
 475
 476   while (*Source && Length > 0) {
 477     *(Destination++) = *(Source++);
 478     Length--;
 479   }
 480
 481   // ZeroMem (Destination, Length * sizeof (*Destination));
 482   memset (Destination, 0, Length * sizeof (*Destination));
 483   return ReturnValue;
 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 }