Tools/Source/TianoTools/String/String.c

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