MdePkg/Library/BaseLib/String.c

   1 /** @file
   2   Unicode and ASCII string primitives.
   3
   4   Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
   5   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 **/
  14
  15 #include "BaseLibInternals.h"
  16
  17 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
  18
  19 /**
  20   [ATTENTION] This function will be deprecated for security reason.
  21
  22   Copies one Null-terminated Unicode string to another Null-terminated Unicode
  23   string and returns the new Unicode string.
  24
  25   This function copies the contents of the Unicode string Source to the Unicode
  26   string Destination, and returns Destination. If Source and Destination
  27   overlap, then the results are undefined.
  28
  29   If Destination is NULL, then ASSERT().
  30   If Destination is not aligned on a 16-bit boundary, then ASSERT().
  31   If Source is NULL, then ASSERT().
  32   If Source is not aligned on a 16-bit boundary, then ASSERT().
  33   If Source and Destination overlap, then ASSERT().
  34   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
  35   PcdMaximumUnicodeStringLength Unicode characters, not including the
  36   Null-terminator, then ASSERT().
  37
  38   @param  Destination A pointer to a Null-terminated Unicode string.
  39   @param  Source      A pointer to a Null-terminated Unicode string.
  40
  41   @return Destination.
  42
  43 **/
  44 CHAR16 *
  45 EFIAPI
  46 StrCpy (
  47   OUT     CHAR16                    *Destination,
  48   IN      CONST CHAR16              *Source
  49   )
  50 {
  51   CHAR16                            *ReturnValue;
  52
  53   //
  54   // Destination cannot be NULL
  55   //
  56   ASSERT (Destination != NULL);
  57   ASSERT (((UINTN) Destination & BIT0) == 0);
  58
  59   //
  60   // Destination and source cannot overlap
  61   //
  62   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
  63   ASSERT ((UINTN)(Source - Destination) > StrLen (Source));
  64
  65   ReturnValue = Destination;
  66   while (*Source != 0) {
  67     *(Destination++) = *(Source++);
  68   }
  69   *Destination = 0;
  70   return ReturnValue;
  71 }
  72
  73 /**
  74   [ATTENTION] This function will be deprecated for security reason.
  75
  76   Copies up to a specified length from one Null-terminated Unicode string  to
  77   another Null-terminated Unicode string and returns the new Unicode string.
  78
  79   This function copies the contents of the Unicode string Source to the Unicode
  80   string Destination, and returns Destination. At most, Length Unicode
  81   characters are copied from Source to Destination. If Length is 0, then
  82   Destination is returned unmodified. If Length is greater that the number of
  83   Unicode characters in Source, then Destination is padded with Null Unicode
  84   characters. If Source and Destination overlap, then the results are
  85   undefined.
  86
  87   If Length > 0 and Destination is NULL, then ASSERT().
  88   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
  89   If Length > 0 and Source is NULL, then ASSERT().
  90   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
  91   If Source and Destination overlap, then ASSERT().
  92   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
  93   PcdMaximumUnicodeStringLength, then ASSERT().
  94   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
  95   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
  96   then ASSERT().
  97
  98   @param  Destination A pointer to a Null-terminated Unicode string.
  99   @param  Source      A pointer to a Null-terminated Unicode string.
 100   @param  Length      The maximum number of Unicode characters to copy.
 101
 102   @return Destination.
 103
 104 **/
 105 CHAR16 *
 106 EFIAPI
 107 StrnCpy (
 108   OUT     CHAR16                    *Destination,
 109   IN      CONST CHAR16              *Source,
 110   IN      UINTN                     Length
 111   )
 112 {
 113   CHAR16                            *ReturnValue;
 114
 115   if (Length == 0) {
 116     return Destination;
 117   }
 118
 119   //
 120   // Destination cannot be NULL if Length is not zero
 121   //
 122   ASSERT (Destination != NULL);
 123   ASSERT (((UINTN) Destination & BIT0) == 0);
 124
 125   //
 126   // Destination and source cannot overlap
 127   //
 128   ASSERT ((UINTN)(Destination - Source) > StrLen (Source));
 129   ASSERT ((UINTN)(Source - Destination) >= Length);
 130
 131   if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
 132     ASSERT (Length <= PcdGet32 (PcdMaximumUnicodeStringLength));
 133   }
 134
 135   ReturnValue = Destination;
 136
 137   while ((*Source != L'\0') && (Length > 0)) {
 138     *(Destination++) = *(Source++);
 139     Length--;
 140   }
 141
 142   ZeroMem (Destination, Length * sizeof (*Destination));
 143   return ReturnValue;
 144 }
 145 #endif
 146
 147 /**
 148   Returns the length of a Null-terminated Unicode string.
 149
 150   This function returns the number of Unicode characters in the Null-terminated
 151   Unicode string specified by String.
 152
 153   If String is NULL, then ASSERT().
 154   If String is not aligned on a 16-bit boundary, then ASSERT().
 155   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 156   PcdMaximumUnicodeStringLength Unicode characters, not including the
 157   Null-terminator, then ASSERT().
 158
 159   @param  String  A pointer to a Null-terminated Unicode string.
 160
 161   @return The length of String.
 162
 163 **/
 164 UINTN
 165 EFIAPI
 166 StrLen (
 167   IN      CONST CHAR16              *String
 168   )
 169 {
 170   UINTN                             Length;
 171
 172   ASSERT (String != NULL);
 173   ASSERT (((UINTN) String & BIT0) == 0);
 174
 175   for (Length = 0; *String != L'\0'; String++, Length++) {
 176     //
 177     // If PcdMaximumUnicodeStringLength is not zero,
 178     // length should not more than PcdMaximumUnicodeStringLength
 179     //
 180     if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
 181       ASSERT (Length < PcdGet32 (PcdMaximumUnicodeStringLength));
 182     }
 183   }
 184   return Length;
 185 }
 186
 187 /**
 188   Returns the size of a Null-terminated Unicode string in bytes, including the
 189   Null terminator.
 190
 191   This function returns the size, in bytes, of the Null-terminated Unicode string
 192   specified by String.
 193
 194   If String is NULL, then ASSERT().
 195   If String is not aligned on a 16-bit boundary, then ASSERT().
 196   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 197   PcdMaximumUnicodeStringLength Unicode characters, not including the
 198   Null-terminator, then ASSERT().
 199
 200   @param  String  A pointer to a Null-terminated Unicode string.
 201
 202   @return The size of String.
 203
 204 **/
 205 UINTN
 206 EFIAPI
 207 StrSize (
 208   IN      CONST CHAR16              *String
 209   )
 210 {
 211   return (StrLen (String) + 1) * sizeof (*String);
 212 }
 213
 214 /**
 215   Compares two Null-terminated Unicode strings, and returns the difference
 216   between the first mismatched Unicode characters.
 217
 218   This function compares the Null-terminated Unicode string FirstString to the
 219   Null-terminated Unicode string SecondString. If FirstString is identical to
 220   SecondString, then 0 is returned. Otherwise, the value returned is the first
 221   mismatched Unicode character in SecondString subtracted from the first
 222   mismatched Unicode character in FirstString.
 223
 224   If FirstString is NULL, then ASSERT().
 225   If FirstString is not aligned on a 16-bit boundary, then ASSERT().
 226   If SecondString is NULL, then ASSERT().
 227   If SecondString is not aligned on a 16-bit boundary, then ASSERT().
 228   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
 229   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 230   Null-terminator, then ASSERT().
 231   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
 232   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 233   Null-terminator, then ASSERT().
 234
 235   @param  FirstString   A pointer to a Null-terminated Unicode string.
 236   @param  SecondString  A pointer to a Null-terminated Unicode string.
 237
 238   @retval 0      FirstString is identical to SecondString.
 239   @return others FirstString is not identical to SecondString.
 240
 241 **/
 242 INTN
 243 EFIAPI
 244 StrCmp (
 245   IN      CONST CHAR16              *FirstString,
 246   IN      CONST CHAR16              *SecondString
 247   )
 248 {
 249   //
 250   // ASSERT both strings are less long than PcdMaximumUnicodeStringLength
 251   //
 252   ASSERT (StrSize (FirstString) != 0);
 253   ASSERT (StrSize (SecondString) != 0);
 254
 255   while ((*FirstString != L'\0') && (*FirstString == *SecondString)) {
 256     FirstString++;
 257     SecondString++;
 258   }
 259   return *FirstString - *SecondString;
 260 }
 261
 262 /**
 263   Compares up to a specified length the contents of two Null-terminated Unicode strings,
 264   and returns the difference between the first mismatched Unicode characters.
 265
 266   This function compares the Null-terminated Unicode string FirstString to the
 267   Null-terminated Unicode string SecondString. At most, Length Unicode
 268   characters will be compared. If Length is 0, then 0 is returned. If
 269   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
 270   value returned is the first mismatched Unicode character in SecondString
 271   subtracted from the first mismatched Unicode character in FirstString.
 272
 273   If Length > 0 and FirstString is NULL, then ASSERT().
 274   If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
 275   If Length > 0 and SecondString is NULL, then ASSERT().
 276   If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
 277   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
 278   PcdMaximumUnicodeStringLength, then ASSERT().
 279   If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
 280   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 281   then ASSERT().
 282   If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
 283   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 284   then ASSERT().
 285
 286   @param  FirstString   A pointer to a Null-terminated Unicode string.
 287   @param  SecondString  A pointer to a Null-terminated Unicode string.
 288   @param  Length        The maximum number of Unicode characters to compare.
 289
 290   @retval 0      FirstString is identical to SecondString.
 291   @return others FirstString is not identical to SecondString.
 292
 293 **/
 294 INTN
 295 EFIAPI
 296 StrnCmp (
 297   IN      CONST CHAR16              *FirstString,
 298   IN      CONST CHAR16              *SecondString,
 299   IN      UINTN                     Length
 300   )
 301 {
 302   if (Length == 0) {
 303     return 0;
 304   }
 305
 306   //
 307   // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
 308   // Length tests are performed inside StrLen().
 309   //
 310   ASSERT (StrSize (FirstString) != 0);
 311   ASSERT (StrSize (SecondString) != 0);
 312
 313   if (PcdGet32 (PcdMaximumUnicodeStringLength) != 0) {
 314     ASSERT (Length <= PcdGet32 (PcdMaximumUnicodeStringLength));
 315   }
 316
 317   while ((*FirstString != L'\0') &&
 318          (*SecondString != L'\0') &&
 319          (*FirstString == *SecondString) &&
 320          (Length > 1)) {
 321     FirstString++;
 322     SecondString++;
 323     Length--;
 324   }
 325
 326   return *FirstString - *SecondString;
 327 }
 328
 329 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 330
 331 /**
 332   [ATTENTION] This function will be deprecated for security reason.
 333
 334   Concatenates one Null-terminated Unicode string to another Null-terminated
 335   Unicode string, and returns the concatenated Unicode string.
 336
 337   This function concatenates two Null-terminated Unicode strings. The contents
 338   of Null-terminated Unicode string Source are concatenated to the end of
 339   Null-terminated Unicode string Destination. The Null-terminated concatenated
 340   Unicode String is returned. If Source and Destination overlap, then the
 341   results are undefined.
 342
 343   If Destination is NULL, then ASSERT().
 344   If Destination is not aligned on a 16-bit boundary, then ASSERT().
 345   If Source is NULL, then ASSERT().
 346   If Source is not aligned on a 16-bit boundary, then ASSERT().
 347   If Source and Destination overlap, then ASSERT().
 348   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
 349   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 350   Null-terminator, then ASSERT().
 351   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 352   PcdMaximumUnicodeStringLength Unicode characters, not including the
 353   Null-terminator, then ASSERT().
 354   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
 355   and Source results in a Unicode string with more than
 356   PcdMaximumUnicodeStringLength Unicode characters, not including the
 357   Null-terminator, then ASSERT().
 358
 359   @param  Destination A pointer to a Null-terminated Unicode string.
 360   @param  Source      A pointer to a Null-terminated Unicode string.
 361
 362   @return Destination.
 363
 364 **/
 365 CHAR16 *
 366 EFIAPI
 367 StrCat (
 368   IN OUT  CHAR16                    *Destination,
 369   IN      CONST CHAR16              *Source
 370   )
 371 {
 372   StrCpy (Destination + StrLen (Destination), Source);
 373
 374   //
 375   // Size of the resulting string should never be zero.
 376   // PcdMaximumUnicodeStringLength is tested inside StrLen().
 377   //
 378   ASSERT (StrSize (Destination) != 0);
 379   return Destination;
 380 }
 381
 382 /**
 383   [ATTENTION] This function will be deprecated for security reason.
 384
 385   Concatenates up to a specified length one Null-terminated Unicode to the end
 386   of another Null-terminated Unicode string, and returns the concatenated
 387   Unicode string.
 388
 389   This function concatenates two Null-terminated Unicode strings. The contents
 390   of Null-terminated Unicode string Source are concatenated to the end of
 391   Null-terminated Unicode string Destination, and Destination is returned. At
 392   most, Length Unicode characters are concatenated from Source to the end of
 393   Destination, and Destination is always Null-terminated. If Length is 0, then
 394   Destination is returned unmodified. If Source and Destination overlap, then
 395   the results are undefined.
 396
 397   If Destination is NULL, then ASSERT().
 398   If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
 399   If Length > 0 and Source is NULL, then ASSERT().
 400   If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
 401   If Source and Destination overlap, then ASSERT().
 402   If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
 403   PcdMaximumUnicodeStringLength, then ASSERT().
 404   If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
 405   than PcdMaximumUnicodeStringLength Unicode characters, not including the
 406   Null-terminator, then ASSERT().
 407   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
 408   PcdMaximumUnicodeStringLength Unicode characters, not including the
 409   Null-terminator, then ASSERT().
 410   If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
 411   and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
 412   Unicode characters, not including the Null-terminator, then ASSERT().
 413
 414   @param  Destination A pointer to a Null-terminated Unicode string.
 415   @param  Source      A pointer to a Null-terminated Unicode string.
 416   @param  Length      The maximum number of Unicode characters to concatenate from
 417                       Source.
 418
 419   @return Destination.
 420
 421 **/
 422 CHAR16 *
 423 EFIAPI
 424 StrnCat (
 425   IN OUT  CHAR16                    *Destination,
 426   IN      CONST CHAR16              *Source,
 427   IN      UINTN                     Length
 428   )
 429 {
 430   UINTN   DestinationLen;
 431
 432   DestinationLen = StrLen (Destination);
 433   StrnCpy (Destination + DestinationLen, Source, Length);
 434   Destination[DestinationLen + Length] = L'\0';
 435
 436   //
 437   // Size of the resulting string should never be zero.
 438   // PcdMaximumUnicodeStringLength is tested inside StrLen().
 439   //
 440   ASSERT (StrSize (Destination) != 0);
 441   return Destination;
 442 }
 443 #endif
 444
 445 /**
 446   Returns the first occurrence of a Null-terminated Unicode sub-string
 447   in a Null-terminated Unicode string.
 448
 449   This function scans the contents of the Null-terminated Unicode string
 450   specified by String and returns the first occurrence of SearchString.
 451   If SearchString is not found in String, then NULL is returned.  If
 452   the length of SearchString is zero, then String is
 453   returned.
 454
 455   If String is NULL, then ASSERT().
 456   If String is not aligned on a 16-bit boundary, then ASSERT().
 457   If SearchString is NULL, then ASSERT().
 458   If SearchString is not aligned on a 16-bit boundary, then ASSERT().
 459
 460   If PcdMaximumUnicodeStringLength is not zero, and SearchString
 461   or String contains more than PcdMaximumUnicodeStringLength Unicode
 462   characters, not including the Null-terminator, then ASSERT().
 463
 464   @param  String          A pointer to a Null-terminated Unicode string.
 465   @param  SearchString    A pointer to a Null-terminated Unicode string to search for.
 466
 467   @retval NULL            If the SearchString does not appear in String.
 468   @return others          If there is a match.
 469
 470 **/
 471 CHAR16 *
 472 EFIAPI
 473 StrStr (
 474   IN      CONST CHAR16              *String,
 475   IN      CONST CHAR16              *SearchString
 476   )
 477 {
 478   CONST CHAR16 *FirstMatch;
 479   CONST CHAR16 *SearchStringTmp;
 480
 481   //
 482   // ASSERT both strings are less long than PcdMaximumUnicodeStringLength.
 483   // Length tests are performed inside StrLen().
 484   //
 485   ASSERT (StrSize (String) != 0);
 486   ASSERT (StrSize (SearchString) != 0);
 487
 488   if (*SearchString == L'\0') {
 489     return (CHAR16 *) String;
 490   }
 491
 492   while (*String != L'\0') {
 493     SearchStringTmp = SearchString;
 494     FirstMatch = String;
 495
 496     while ((*String == *SearchStringTmp)
 497             && (*String != L'\0')) {
 498       String++;
 499       SearchStringTmp++;
 500     }
 501
 502     if (*SearchStringTmp == L'\0') {
 503       return (CHAR16 *) FirstMatch;
 504     }
 505
 506     if (*String == L'\0') {
 507       return NULL;
 508     }
 509
 510     String = FirstMatch + 1;
 511   }
 512
 513   return NULL;
 514 }
 515
 516 /**
 517   Check if a Unicode character is a decimal character.
 518
 519   This internal function checks if a Unicode character is a
 520   decimal character. The valid decimal character is from
 521   L'0' to L'9'.
 522
 523   @param  Char  The character to check against.
 524
 525   @retval TRUE  If the Char is a decmial character.
 526   @retval FALSE If the Char is not a decmial character.
 527
 528 **/
 529 BOOLEAN
 530 EFIAPI
 531 InternalIsDecimalDigitCharacter (
 532   IN      CHAR16                    Char
 533   )
 534 {
 535   return (BOOLEAN) (Char >= L'0' && Char <= L'9');
 536 }
 537
 538 /**
 539   Convert a Unicode character to upper case only if
 540   it maps to a valid small-case ASCII character.
 541
 542   This internal function only deal with Unicode character
 543   which maps to a valid small-case ASCII character, i.e.
 544   L'a' to L'z'. For other Unicode character, the input character
 545   is returned directly.
 546
 547   @param  Char  The character to convert.
 548
 549   @retval LowerCharacter   If the Char is with range L'a' to L'z'.
 550   @retval Unchanged        Otherwise.
 551
 552 **/
 553 CHAR16
 554 EFIAPI
 555 InternalCharToUpper (
 556   IN      CHAR16                    Char
 557   )
 558 {
 559   if (Char >= L'a' && Char <= L'z') {
 560     return (CHAR16) (Char - (L'a' - L'A'));
 561   }
 562
 563   return Char;
 564 }
 565
 566 /**
 567   Convert a Unicode character to numerical value.
 568
 569   This internal function only deal with Unicode character
 570   which maps to a valid hexadecimal ASII character, i.e.
 571   L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other
 572   Unicode character, the value returned does not make sense.
 573
 574   @param  Char  The character to convert.
 575
 576   @return The numerical value converted.
 577
 578 **/
 579 UINTN
 580 EFIAPI
 581 InternalHexCharToUintn (
 582   IN      CHAR16                    Char
 583   )
 584 {
 585   if (InternalIsDecimalDigitCharacter (Char)) {
 586     return Char - L'0';
 587   }
 588
 589   return (10 + InternalCharToUpper (Char) - L'A');
 590 }
 591
 592 /**
 593   Check if a Unicode character is a hexadecimal character.
 594
 595   This internal function checks if a Unicode character is a
 596   decimal character.  The valid hexadecimal character is
 597   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
 598
 599
 600   @param  Char  The character to check against.
 601
 602   @retval TRUE  If the Char is a hexadecmial character.
 603   @retval FALSE If the Char is not a hexadecmial character.
 604
 605 **/
 606 BOOLEAN
 607 EFIAPI
 608 InternalIsHexaDecimalDigitCharacter (
 609   IN      CHAR16                    Char
 610   )
 611 {
 612
 613   return (BOOLEAN) (InternalIsDecimalDigitCharacter (Char) ||
 614     (Char >= L'A' && Char <= L'F') ||
 615     (Char >= L'a' && Char <= L'f'));
 616 }
 617
 618 /**
 619   Convert a Null-terminated Unicode decimal string to a value of
 620   type UINTN.
 621
 622   This function returns a value of type UINTN by interpreting the contents
 623   of the Unicode string specified by String as a decimal number. The format
 624   of the input Unicode string String is:
 625
 626                   [spaces] [decimal digits].
 627
 628   The valid decimal digit character is in the range [0-9]. The
 629   function will ignore the pad space, which includes spaces or
 630   tab characters, before [decimal digits]. The running zero in the
 631   beginning of [decimal digits] will be ignored. Then, the function
 632   stops at the first character that is a not a valid decimal character
 633   or a Null-terminator, whichever one comes first.
 634
 635   If String is NULL, then ASSERT().
 636   If String is not aligned in a 16-bit boundary, then ASSERT().
 637   If String has only pad spaces, then 0 is returned.
 638   If String has no pad spaces or valid decimal digits,
 639   then 0 is returned.
 640   If the number represented by String overflows according
 641   to the range defined by UINTN, then MAX_UINTN is returned.
 642
 643   If PcdMaximumUnicodeStringLength is not zero, and String contains
 644   more than PcdMaximumUnicodeStringLength Unicode characters, not including
 645   the Null-terminator, then ASSERT().
 646
 647   @param  String      A pointer to a Null-terminated Unicode string.
 648
 649   @retval Value translated from String.
 650
 651 **/
 652 UINTN
 653 EFIAPI
 654 StrDecimalToUintn (
 655   IN      CONST CHAR16              *String
 656   )
 657 {
 658   UINTN     Result;
 659
 660   StrDecimalToUintnS (String, (CHAR16 **) NULL, &Result);
 661   return Result;
 662 }
 663
 664
 665 /**
 666   Convert a Null-terminated Unicode decimal string to a value of
 667   type UINT64.
 668
 669   This function returns a value of type UINT64 by interpreting the contents
 670   of the Unicode string specified by String as a decimal number. The format
 671   of the input Unicode string String is:
 672
 673                   [spaces] [decimal digits].
 674
 675   The valid decimal digit character is in the range [0-9]. The
 676   function will ignore the pad space, which includes spaces or
 677   tab characters, before [decimal digits]. The running zero in the
 678   beginning of [decimal digits] will be ignored. Then, the function
 679   stops at the first character that is a not a valid decimal character
 680   or a Null-terminator, whichever one comes first.
 681
 682   If String is NULL, then ASSERT().
 683   If String is not aligned in a 16-bit boundary, then ASSERT().
 684   If String has only pad spaces, then 0 is returned.
 685   If String has no pad spaces or valid decimal digits,
 686   then 0 is returned.
 687   If the number represented by String overflows according
 688   to the range defined by UINT64, then MAX_UINT64 is returned.
 689
 690   If PcdMaximumUnicodeStringLength is not zero, and String contains
 691   more than PcdMaximumUnicodeStringLength Unicode characters, not including
 692   the Null-terminator, then ASSERT().
 693
 694   @param  String          A pointer to a Null-terminated Unicode string.
 695
 696   @retval Value translated from String.
 697
 698 **/
 699 UINT64
 700 EFIAPI
 701 StrDecimalToUint64 (
 702   IN      CONST CHAR16              *String
 703   )
 704 {
 705   UINT64     Result;
 706
 707   StrDecimalToUint64S (String, (CHAR16 **) NULL, &Result);
 708   return Result;
 709 }
 710
 711 /**
 712   Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
 713
 714   This function returns a value of type UINTN by interpreting the contents
 715   of the Unicode string specified by String as a hexadecimal number.
 716   The format of the input Unicode string String is:
 717
 718                   [spaces][zeros][x][hexadecimal digits].
 719
 720   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 721   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 722   If "x" appears in the input string, it must be prefixed with at least one 0.
 723   The function will ignore the pad space, which includes spaces or tab characters,
 724   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
 725   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
 726   first valid hexadecimal digit. Then, the function stops at the first character that is
 727   a not a valid hexadecimal character or NULL, whichever one comes first.
 728
 729   If String is NULL, then ASSERT().
 730   If String is not aligned in a 16-bit boundary, then ASSERT().
 731   If String has only pad spaces, then zero is returned.
 732   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
 733   then zero is returned.
 734   If the number represented by String overflows according to the range defined by
 735   UINTN, then MAX_UINTN is returned.
 736
 737   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 738   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 739   then ASSERT().
 740
 741   @param  String          A pointer to a Null-terminated Unicode string.
 742
 743   @retval Value translated from String.
 744
 745 **/
 746 UINTN
 747 EFIAPI
 748 StrHexToUintn (
 749   IN      CONST CHAR16              *String
 750   )
 751 {
 752   UINTN     Result;
 753
 754   StrHexToUintnS (String, (CHAR16 **) NULL, &Result);
 755   return Result;
 756 }
 757
 758
 759 /**
 760   Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
 761
 762   This function returns a value of type UINT64 by interpreting the contents
 763   of the Unicode string specified by String as a hexadecimal number.
 764   The format of the input Unicode string String is
 765
 766                   [spaces][zeros][x][hexadecimal digits].
 767
 768   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
 769   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
 770   If "x" appears in the input string, it must be prefixed with at least one 0.
 771   The function will ignore the pad space, which includes spaces or tab characters,
 772   before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
 773   [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
 774   first valid hexadecimal digit. Then, the function stops at the first character that is
 775   a not a valid hexadecimal character or NULL, whichever one comes first.
 776
 777   If String is NULL, then ASSERT().
 778   If String is not aligned in a 16-bit boundary, then ASSERT().
 779   If String has only pad spaces, then zero is returned.
 780   If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
 781   then zero is returned.
 782   If the number represented by String overflows according to the range defined by
 783   UINT64, then MAX_UINT64 is returned.
 784
 785   If PcdMaximumUnicodeStringLength is not zero, and String contains more than
 786   PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
 787   then ASSERT().
 788
 789   @param  String          A pointer to a Null-terminated Unicode string.
 790
 791   @retval Value translated from String.
 792
 793 **/
 794 UINT64
 795 EFIAPI
 796 StrHexToUint64 (
 797   IN      CONST CHAR16             *String
 798   )
 799 {
 800   UINT64    Result;
 801
 802   StrHexToUint64S (String, (CHAR16 **) NULL, &Result);
 803   return Result;
 804 }
 805
 806 /**
 807   Check if a ASCII character is a decimal character.
 808
 809   This internal function checks if a Unicode character is a
 810   decimal character. The valid decimal character is from
 811   '0' to '9'.
 812
 813   @param  Char  The character to check against.
 814
 815   @retval TRUE  If the Char is a decmial character.
 816   @retval FALSE If the Char is not a decmial character.
 817
 818 **/
 819 BOOLEAN
 820 EFIAPI
 821 InternalAsciiIsDecimalDigitCharacter (
 822   IN      CHAR8                     Char
 823   )
 824 {
 825   return (BOOLEAN) (Char >= '0' && Char <= '9');
 826 }
 827
 828 /**
 829   Check if a ASCII character is a hexadecimal character.
 830
 831   This internal function checks if a ASCII character is a
 832   decimal character.  The valid hexadecimal character is
 833   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
 834
 835
 836   @param  Char  The character to check against.
 837
 838   @retval TRUE  If the Char is a hexadecmial character.
 839   @retval FALSE If the Char is not a hexadecmial character.
 840
 841 **/
 842 BOOLEAN
 843 EFIAPI
 844 InternalAsciiIsHexaDecimalDigitCharacter (
 845   IN      CHAR8                    Char
 846   )
 847 {
 848
 849   return (BOOLEAN) (InternalAsciiIsDecimalDigitCharacter (Char) ||
 850     (Char >= 'A' && Char <= 'F') ||
 851     (Char >= 'a' && Char <= 'f'));
 852 }
 853
 854 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
 855
 856 /**
 857   [ATTENTION] This function is deprecated for security reason.
 858
 859   Convert a Null-terminated Unicode string to a Null-terminated
 860   ASCII string and returns the ASCII string.
 861
 862   This function converts the content of the Unicode string Source
 863   to the ASCII string Destination by copying the lower 8 bits of
 864   each Unicode character. It returns Destination.
 865
 866   The caller is responsible to make sure Destination points to a buffer with size
 867   equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
 868
 869   If any Unicode characters in Source contain non-zero value in
 870   the upper 8 bits, then ASSERT().
 871
 872   If Destination is NULL, then ASSERT().
 873   If Source is NULL, then ASSERT().
 874   If Source is not aligned on a 16-bit boundary, then ASSERT().
 875   If Source and Destination overlap, then ASSERT().
 876
 877   If PcdMaximumUnicodeStringLength is not zero, and Source contains
 878   more than PcdMaximumUnicodeStringLength Unicode characters, not including
 879   the Null-terminator, then ASSERT().
 880
 881   If PcdMaximumAsciiStringLength is not zero, and Source contains more
 882   than PcdMaximumAsciiStringLength Unicode characters, not including the
 883   Null-terminator, then ASSERT().
 884
 885   @param  Source        A pointer to a Null-terminated Unicode string.
 886   @param  Destination   A pointer to a Null-terminated ASCII string.
 887
 888   @return Destination.
 889
 890 **/
 891 CHAR8 *
 892 EFIAPI
 893 UnicodeStrToAsciiStr (
 894   IN      CONST CHAR16              *Source,
 895   OUT     CHAR8                     *Destination
 896   )
 897 {
 898   CHAR8                               *ReturnValue;
 899
 900   ASSERT (Destination != NULL);
 901
 902   //
 903   // ASSERT if Source is long than PcdMaximumUnicodeStringLength.
 904   // Length tests are performed inside StrLen().
 905   //
 906   ASSERT (StrSize (Source) != 0);
 907
 908   //
 909   // Source and Destination should not overlap
 910   //
 911   ASSERT ((UINTN) (Destination - (CHAR8 *) Source) >= StrSize (Source));
 912   ASSERT ((UINTN) ((CHAR8 *) Source - Destination) > StrLen (Source));
 913
 914
 915   ReturnValue = Destination;
 916   while (*Source != '\0') {
 917     //
 918     // If any Unicode characters in Source contain
 919     // non-zero value in the upper 8 bits, then ASSERT().
 920     //
 921     ASSERT (*Source < 0x100);
 922     *(Destination++) = (CHAR8) *(Source++);
 923   }
 924
 925   *Destination = '\0';
 926
 927   //
 928   // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength.
 929   // Length tests are performed inside AsciiStrLen().
 930   //
 931   ASSERT (AsciiStrSize (ReturnValue) != 0);
 932
 933   return ReturnValue;
 934 }
 935
 936 /**
 937   [ATTENTION] This function will be deprecated for security reason.
 938
 939   Copies one Null-terminated ASCII string to another Null-terminated ASCII
 940   string and returns the new ASCII string.
 941
 942   This function copies the contents of the ASCII string Source to the ASCII
 943   string Destination, and returns Destination. If Source and Destination
 944   overlap, then the results are undefined.
 945
 946   If Destination is NULL, then ASSERT().
 947   If Source is NULL, then ASSERT().
 948   If Source and Destination overlap, then ASSERT().
 949   If PcdMaximumAsciiStringLength is not zero and Source contains more than
 950   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
 951   then ASSERT().
 952
 953   @param  Destination A pointer to a Null-terminated ASCII string.
 954   @param  Source      A pointer to a Null-terminated ASCII string.
 955
 956   @return Destination
 957
 958 **/
 959 CHAR8 *
 960 EFIAPI
 961 AsciiStrCpy (
 962   OUT     CHAR8                     *Destination,
 963   IN      CONST CHAR8               *Source
 964   )
 965 {
 966   CHAR8                             *ReturnValue;
 967
 968   //
 969   // Destination cannot be NULL
 970   //
 971   ASSERT (Destination != NULL);
 972
 973   //
 974   // Destination and source cannot overlap
 975   //
 976   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
 977   ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source));
 978
 979   ReturnValue = Destination;
 980   while (*Source != 0) {
 981     *(Destination++) = *(Source++);
 982   }
 983   *Destination = 0;
 984   return ReturnValue;
 985 }
 986
 987 /**
 988   [ATTENTION] This function will be deprecated for security reason.
 989
 990   Copies up to a specified length one Null-terminated ASCII string to another
 991   Null-terminated ASCII string and returns the new ASCII string.
 992
 993   This function copies the contents of the ASCII string Source to the ASCII
 994   string Destination, and returns Destination. At most, Length ASCII characters
 995   are copied from Source to Destination. If Length is 0, then Destination is
 996   returned unmodified. If Length is greater that the number of ASCII characters
 997   in Source, then Destination is padded with Null ASCII characters. If Source
 998   and Destination overlap, then the results are undefined.
 999
1000   If Destination is NULL, then ASSERT().
1001   If Source is NULL, then ASSERT().
1002   If Source and Destination overlap, then ASSERT().
1003   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1004   PcdMaximumAsciiStringLength, then ASSERT().
1005   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1006   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1007   then ASSERT().
1008
1009   @param  Destination A pointer to a Null-terminated ASCII string.
1010   @param  Source      A pointer to a Null-terminated ASCII string.
1011   @param  Length      The maximum number of ASCII characters to copy.
1012
1013   @return Destination
1014
1015 **/
1016 CHAR8 *
1017 EFIAPI
1018 AsciiStrnCpy (
1019   OUT     CHAR8                     *Destination,
1020   IN      CONST CHAR8               *Source,
1021   IN      UINTN                     Length
1022   )
1023 {
1024   CHAR8                             *ReturnValue;
1025
1026   if (Length == 0) {
1027     return Destination;
1028   }
1029
1030   //
1031   // Destination cannot be NULL
1032   //
1033   ASSERT (Destination != NULL);
1034
1035   //
1036   // Destination and source cannot overlap
1037   //
1038   ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source));
1039   ASSERT ((UINTN)(Source - Destination) >= Length);
1040
1041   if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1042     ASSERT (Length <= PcdGet32 (PcdMaximumAsciiStringLength));
1043   }
1044
1045   ReturnValue = Destination;
1046
1047   while (*Source != 0 && Length > 0) {
1048     *(Destination++) = *(Source++);
1049     Length--;
1050   }
1051
1052   ZeroMem (Destination, Length * sizeof (*Destination));
1053   return ReturnValue;
1054 }
1055 #endif
1056
1057 /**
1058   Returns the length of a Null-terminated ASCII string.
1059
1060   This function returns the number of ASCII characters in the Null-terminated
1061   ASCII string specified by String.
1062
1063   If Length > 0 and Destination is NULL, then ASSERT().
1064   If Length > 0 and Source is NULL, then ASSERT().
1065   If PcdMaximumAsciiStringLength is not zero and String contains more than
1066   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1067   then ASSERT().
1068
1069   @param  String  A pointer to a Null-terminated ASCII string.
1070
1071   @return The length of String.
1072
1073 **/
1074 UINTN
1075 EFIAPI
1076 AsciiStrLen (
1077   IN      CONST CHAR8               *String
1078   )
1079 {
1080   UINTN                             Length;
1081
1082   ASSERT (String != NULL);
1083
1084   for (Length = 0; *String != '\0'; String++, Length++) {
1085     //
1086     // If PcdMaximumUnicodeStringLength is not zero,
1087     // length should not more than PcdMaximumUnicodeStringLength
1088     //
1089     if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1090       ASSERT (Length < PcdGet32 (PcdMaximumAsciiStringLength));
1091     }
1092   }
1093   return Length;
1094 }
1095
1096 /**
1097   Returns the size of a Null-terminated ASCII string in bytes, including the
1098   Null terminator.
1099
1100   This function returns the size, in bytes, of the Null-terminated ASCII string
1101   specified by String.
1102
1103   If String is NULL, then ASSERT().
1104   If PcdMaximumAsciiStringLength is not zero and String contains more than
1105   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1106   then ASSERT().
1107
1108   @param  String  A pointer to a Null-terminated ASCII string.
1109
1110   @return The size of String.
1111
1112 **/
1113 UINTN
1114 EFIAPI
1115 AsciiStrSize (
1116   IN      CONST CHAR8               *String
1117   )
1118 {
1119   return (AsciiStrLen (String) + 1) * sizeof (*String);
1120 }
1121
1122 /**
1123   Compares two Null-terminated ASCII strings, and returns the difference
1124   between the first mismatched ASCII characters.
1125
1126   This function compares the Null-terminated ASCII string FirstString to the
1127   Null-terminated ASCII string SecondString. If FirstString is identical to
1128   SecondString, then 0 is returned. Otherwise, the value returned is the first
1129   mismatched ASCII character in SecondString subtracted from the first
1130   mismatched ASCII character in FirstString.
1131
1132   If FirstString is NULL, then ASSERT().
1133   If SecondString is NULL, then ASSERT().
1134   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1135   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1136   then ASSERT().
1137   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1138   than PcdMaximumAsciiStringLength ASCII characters, not including the
1139   Null-terminator, then ASSERT().
1140
1141   @param  FirstString   A pointer to a Null-terminated ASCII string.
1142   @param  SecondString  A pointer to a Null-terminated ASCII string.
1143
1144   @retval ==0      FirstString is identical to SecondString.
1145   @retval !=0      FirstString is not identical to SecondString.
1146
1147 **/
1148 INTN
1149 EFIAPI
1150 AsciiStrCmp (
1151   IN      CONST CHAR8               *FirstString,
1152   IN      CONST CHAR8               *SecondString
1153   )
1154 {
1155   //
1156   // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1157   //
1158   ASSERT (AsciiStrSize (FirstString));
1159   ASSERT (AsciiStrSize (SecondString));
1160
1161   while ((*FirstString != '\0') && (*FirstString == *SecondString)) {
1162     FirstString++;
1163     SecondString++;
1164   }
1165
1166   return *FirstString - *SecondString;
1167 }
1168
1169 /**
1170   Converts a lowercase Ascii character to upper one.
1171
1172   If Chr is lowercase Ascii character, then converts it to upper one.
1173
1174   If Value >= 0xA0, then ASSERT().
1175   If (Value & 0x0F) >= 0x0A, then ASSERT().
1176
1177   @param  Chr   one Ascii character
1178
1179   @return The uppercase value of Ascii character
1180
1181 **/
1182 CHAR8
1183 EFIAPI
1184 InternalBaseLibAsciiToUpper (
1185   IN      CHAR8                     Chr
1186   )
1187 {
1188   return (UINT8) ((Chr >= 'a' && Chr <= 'z') ? Chr - ('a' - 'A') : Chr);
1189 }
1190
1191 /**
1192   Convert a ASCII character to numerical value.
1193
1194   This internal function only deal with Unicode character
1195   which maps to a valid hexadecimal ASII character, i.e.
1196   '0' to '9', 'a' to 'f' or 'A' to 'F'. For other
1197   ASCII character, the value returned does not make sense.
1198
1199   @param  Char  The character to convert.
1200
1201   @return The numerical value converted.
1202
1203 **/
1204 UINTN
1205 EFIAPI
1206 InternalAsciiHexCharToUintn (
1207   IN      CHAR8                    Char
1208   )
1209 {
1210   if (InternalIsDecimalDigitCharacter (Char)) {
1211     return Char - '0';
1212   }
1213
1214   return (10 + InternalBaseLibAsciiToUpper (Char) - 'A');
1215 }
1216
1217
1218 /**
1219   Performs a case insensitive comparison of two Null-terminated ASCII strings,
1220   and returns the difference between the first mismatched ASCII characters.
1221
1222   This function performs a case insensitive comparison of the Null-terminated
1223   ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1224   FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1225   value returned is the first mismatched lower case ASCII character in
1226   SecondString subtracted from the first mismatched lower case ASCII character
1227   in FirstString.
1228
1229   If FirstString is NULL, then ASSERT().
1230   If SecondString is NULL, then ASSERT().
1231   If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1232   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1233   then ASSERT().
1234   If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1235   than PcdMaximumAsciiStringLength ASCII characters, not including the
1236   Null-terminator, then ASSERT().
1237
1238   @param  FirstString   A pointer to a Null-terminated ASCII string.
1239   @param  SecondString  A pointer to a Null-terminated ASCII string.
1240
1241   @retval ==0    FirstString is identical to SecondString using case insensitive
1242                  comparisons.
1243   @retval !=0    FirstString is not identical to SecondString using case
1244                  insensitive comparisons.
1245
1246 **/
1247 INTN
1248 EFIAPI
1249 AsciiStriCmp (
1250   IN      CONST CHAR8               *FirstString,
1251   IN      CONST CHAR8               *SecondString
1252   )
1253 {
1254   CHAR8  UpperFirstString;
1255   CHAR8  UpperSecondString;
1256
1257   //
1258   // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1259   //
1260   ASSERT (AsciiStrSize (FirstString));
1261   ASSERT (AsciiStrSize (SecondString));
1262
1263   UpperFirstString  = InternalBaseLibAsciiToUpper (*FirstString);
1264   UpperSecondString = InternalBaseLibAsciiToUpper (*SecondString);
1265   while ((*FirstString != '\0') && (UpperFirstString == UpperSecondString)) {
1266     FirstString++;
1267     SecondString++;
1268     UpperFirstString  = InternalBaseLibAsciiToUpper (*FirstString);
1269     UpperSecondString = InternalBaseLibAsciiToUpper (*SecondString);
1270   }
1271
1272   return UpperFirstString - UpperSecondString;
1273 }
1274
1275 /**
1276   Compares two Null-terminated ASCII strings with maximum lengths, and returns
1277   the difference between the first mismatched ASCII characters.
1278
1279   This function compares the Null-terminated ASCII string FirstString to the
1280   Null-terminated ASCII  string SecondString. At most, Length ASCII characters
1281   will be compared. If Length is 0, then 0 is returned. If FirstString is
1282   identical to SecondString, then 0 is returned. Otherwise, the value returned
1283   is the first mismatched ASCII character in SecondString subtracted from the
1284   first mismatched ASCII character in FirstString.
1285
1286   If Length > 0 and FirstString is NULL, then ASSERT().
1287   If Length > 0 and SecondString is NULL, then ASSERT().
1288   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1289   PcdMaximumAsciiStringLength, then ASSERT().
1290   If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1291   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1292   then ASSERT().
1293   If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1294   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1295   then ASSERT().
1296
1297   @param  FirstString   A pointer to a Null-terminated ASCII string.
1298   @param  SecondString  A pointer to a Null-terminated ASCII string.
1299   @param  Length        The maximum number of ASCII characters for compare.
1300
1301   @retval ==0       FirstString is identical to SecondString.
1302   @retval !=0       FirstString is not identical to SecondString.
1303
1304 **/
1305 INTN
1306 EFIAPI
1307 AsciiStrnCmp (
1308   IN      CONST CHAR8               *FirstString,
1309   IN      CONST CHAR8               *SecondString,
1310   IN      UINTN                     Length
1311   )
1312 {
1313   if (Length == 0) {
1314     return 0;
1315   }
1316
1317   //
1318   // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1319   //
1320   ASSERT (AsciiStrSize (FirstString));
1321   ASSERT (AsciiStrSize (SecondString));
1322
1323   if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) {
1324     ASSERT (Length <= PcdGet32 (PcdMaximumAsciiStringLength));
1325   }
1326
1327   while ((*FirstString != '\0') &&
1328          (*SecondString != '\0') &&
1329          (*FirstString == *SecondString) &&
1330          (Length > 1)) {
1331     FirstString++;
1332     SecondString++;
1333     Length--;
1334   }
1335   return *FirstString - *SecondString;
1336 }
1337
1338 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1339
1340 /**
1341   [ATTENTION] This function will be deprecated for security reason.
1342
1343   Concatenates one Null-terminated ASCII string to another Null-terminated
1344   ASCII string, and returns the concatenated ASCII string.
1345
1346   This function concatenates two Null-terminated ASCII strings. The contents of
1347   Null-terminated ASCII string Source are concatenated to the end of Null-
1348   terminated ASCII string Destination. The Null-terminated concatenated ASCII
1349   String is returned.
1350
1351   If Destination is NULL, then ASSERT().
1352   If Source is NULL, then ASSERT().
1353   If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1354   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1355   then ASSERT().
1356   If PcdMaximumAsciiStringLength is not zero and Source contains more than
1357   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1358   then ASSERT().
1359   If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1360   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1361   ASCII characters, then ASSERT().
1362
1363   @param  Destination A pointer to a Null-terminated ASCII string.
1364   @param  Source      A pointer to a Null-terminated ASCII string.
1365
1366   @return Destination
1367
1368 **/
1369 CHAR8 *
1370 EFIAPI
1371 AsciiStrCat (
1372   IN OUT CHAR8    *Destination,
1373   IN CONST CHAR8  *Source
1374   )
1375 {
1376   AsciiStrCpy (Destination + AsciiStrLen (Destination), Source);
1377
1378   //
1379   // Size of the resulting string should never be zero.
1380   // PcdMaximumUnicodeStringLength is tested inside StrLen().
1381   //
1382   ASSERT (AsciiStrSize (Destination) != 0);
1383   return Destination;
1384 }
1385
1386 /**
1387   [ATTENTION] This function will be deprecated for security reason.
1388
1389   Concatenates up to a specified length one Null-terminated ASCII string to
1390   the end of another Null-terminated ASCII string, and returns the
1391   concatenated ASCII string.
1392
1393   This function concatenates two Null-terminated ASCII strings. The contents
1394   of Null-terminated ASCII string Source are concatenated to the end of Null-
1395   terminated ASCII string Destination, and Destination is returned. At most,
1396   Length ASCII characters are concatenated from Source to the end of
1397   Destination, and Destination is always Null-terminated. If Length is 0, then
1398   Destination is returned unmodified. If Source and Destination overlap, then
1399   the results are undefined.
1400
1401   If Length > 0 and Destination is NULL, then ASSERT().
1402   If Length > 0 and Source is NULL, then ASSERT().
1403   If Source and Destination overlap, then ASSERT().
1404   If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1405   PcdMaximumAsciiStringLength, then ASSERT().
1406   If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1407   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1408   then ASSERT().
1409   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1410   PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1411   then ASSERT().
1412   If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1413   Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1414   ASCII characters, not including the Null-terminator, then ASSERT().
1415
1416   @param  Destination A pointer to a Null-terminated ASCII string.
1417   @param  Source      A pointer to a Null-terminated ASCII string.
1418   @param  Length      The maximum number of ASCII characters to concatenate from
1419                       Source.
1420
1421   @return Destination
1422
1423 **/
1424 CHAR8 *
1425 EFIAPI
1426 AsciiStrnCat (
1427   IN OUT  CHAR8                     *Destination,
1428   IN      CONST CHAR8               *Source,
1429   IN      UINTN                     Length
1430   )
1431 {
1432   UINTN   DestinationLen;
1433
1434   DestinationLen = AsciiStrLen (Destination);
1435   AsciiStrnCpy (Destination + DestinationLen, Source, Length);
1436   Destination[DestinationLen + Length] = '\0';
1437
1438   //
1439   // Size of the resulting string should never be zero.
1440   // PcdMaximumUnicodeStringLength is tested inside StrLen().
1441   //
1442   ASSERT (AsciiStrSize (Destination) != 0);
1443   return Destination;
1444 }
1445 #endif
1446
1447 /**
1448   Returns the first occurrence of a Null-terminated ASCII sub-string
1449   in a Null-terminated ASCII string.
1450
1451   This function scans the contents of the ASCII string specified by String
1452   and returns the first occurrence of SearchString. If SearchString is not
1453   found in String, then NULL is returned. If the length of SearchString is zero,
1454   then String is returned.
1455
1456   If String is NULL, then ASSERT().
1457   If SearchString is NULL, then ASSERT().
1458
1459   If PcdMaximumAsciiStringLength is not zero, and SearchString or
1460   String contains more than PcdMaximumAsciiStringLength Unicode characters
1461   not including the Null-terminator, then ASSERT().
1462
1463   @param  String          A pointer to a Null-terminated ASCII string.
1464   @param  SearchString    A pointer to a Null-terminated ASCII string to search for.
1465
1466   @retval NULL            If the SearchString does not appear in String.
1467   @retval others          If there is a match return the first occurrence of SearchingString.
1468                           If the length of SearchString is zero,return String.
1469
1470 **/
1471 CHAR8 *
1472 EFIAPI
1473 AsciiStrStr (
1474   IN      CONST CHAR8               *String,
1475   IN      CONST CHAR8               *SearchString
1476   )
1477 {
1478   CONST CHAR8 *FirstMatch;
1479   CONST CHAR8 *SearchStringTmp;
1480
1481   //
1482   // ASSERT both strings are less long than PcdMaximumAsciiStringLength
1483   //
1484   ASSERT (AsciiStrSize (String) != 0);
1485   ASSERT (AsciiStrSize (SearchString) != 0);
1486
1487   if (*SearchString == '\0') {
1488     return (CHAR8 *) String;
1489   }
1490
1491   while (*String != '\0') {
1492     SearchStringTmp = SearchString;
1493     FirstMatch = String;
1494
1495     while ((*String == *SearchStringTmp)
1496             && (*String != '\0')) {
1497       String++;
1498       SearchStringTmp++;
1499     }
1500
1501     if (*SearchStringTmp == '\0') {
1502       return (CHAR8 *) FirstMatch;
1503     }
1504
1505     if (*String == '\0') {
1506       return NULL;
1507     }
1508
1509     String = FirstMatch + 1;
1510   }
1511
1512   return NULL;
1513 }
1514
1515 /**
1516   Convert a Null-terminated ASCII decimal string to a value of type
1517   UINTN.
1518
1519   This function returns a value of type UINTN by interpreting the contents
1520   of the ASCII string String as a decimal number. The format of the input
1521   ASCII string String is:
1522
1523                     [spaces] [decimal digits].
1524
1525   The valid decimal digit character is in the range [0-9]. The function will
1526   ignore the pad space, which includes spaces or tab characters, before the digits.
1527   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1528   function stops at the first character that is a not a valid decimal character or
1529   Null-terminator, whichever on comes first.
1530
1531   If String has only pad spaces, then 0 is returned.
1532   If String has no pad spaces or valid decimal digits, then 0 is returned.
1533   If the number represented by String overflows according to the range defined by
1534   UINTN, then MAX_UINTN is returned.
1535   If String is NULL, then ASSERT().
1536   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1537   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1538   then ASSERT().
1539
1540   @param  String          A pointer to a Null-terminated ASCII string.
1541
1542   @retval Value translated from String.
1543
1544 **/
1545 UINTN
1546 EFIAPI
1547 AsciiStrDecimalToUintn (
1548   IN      CONST CHAR8               *String
1549   )
1550 {
1551   UINTN     Result;
1552
1553   AsciiStrDecimalToUintnS (String, (CHAR8 **) NULL, &Result);
1554   return Result;
1555 }
1556
1557
1558 /**
1559   Convert a Null-terminated ASCII decimal string to a value of type
1560   UINT64.
1561
1562   This function returns a value of type UINT64 by interpreting the contents
1563   of the ASCII string String as a decimal number. The format of the input
1564   ASCII string String is:
1565
1566                     [spaces] [decimal digits].
1567
1568   The valid decimal digit character is in the range [0-9]. The function will
1569   ignore the pad space, which includes spaces or tab characters, before the digits.
1570   The running zero in the beginning of [decimal digits] will be ignored. Then, the
1571   function stops at the first character that is a not a valid decimal character or
1572   Null-terminator, whichever on comes first.
1573
1574   If String has only pad spaces, then 0 is returned.
1575   If String has no pad spaces or valid decimal digits, then 0 is returned.
1576   If the number represented by String overflows according to the range defined by
1577   UINT64, then MAX_UINT64 is returned.
1578   If String is NULL, then ASSERT().
1579   If PcdMaximumAsciiStringLength is not zero, and String contains more than
1580   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1581   then ASSERT().
1582
1583   @param  String          A pointer to a Null-terminated ASCII string.
1584
1585   @retval Value translated from String.
1586
1587 **/
1588 UINT64
1589 EFIAPI
1590 AsciiStrDecimalToUint64 (
1591   IN      CONST CHAR8               *String
1592   )
1593 {
1594   UINT64     Result;
1595
1596   AsciiStrDecimalToUint64S (String, (CHAR8 **) NULL, &Result);
1597   return Result;
1598 }
1599
1600 /**
1601   Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1602
1603   This function returns a value of type UINTN by interpreting the contents of
1604   the ASCII string String as a hexadecimal number. The format of the input ASCII
1605   string String is:
1606
1607                   [spaces][zeros][x][hexadecimal digits].
1608
1609   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1610   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1611   appears in the input string, it must be prefixed with at least one 0. The function
1612   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1613   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1614   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1615   digit. Then, the function stops at the first character that is a not a valid
1616   hexadecimal character or Null-terminator, whichever on comes first.
1617
1618   If String has only pad spaces, then 0 is returned.
1619   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1620   0 is returned.
1621
1622   If the number represented by String overflows according to the range defined by UINTN,
1623   then MAX_UINTN is returned.
1624   If String is NULL, then ASSERT().
1625   If PcdMaximumAsciiStringLength is not zero,
1626   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1627   the Null-terminator, then ASSERT().
1628
1629   @param  String          A pointer to a Null-terminated ASCII string.
1630
1631   @retval Value translated from String.
1632
1633 **/
1634 UINTN
1635 EFIAPI
1636 AsciiStrHexToUintn (
1637   IN      CONST CHAR8               *String
1638   )
1639 {
1640   UINTN     Result;
1641
1642   AsciiStrHexToUintnS (String, (CHAR8 **) NULL, &Result);
1643   return Result;
1644 }
1645
1646
1647 /**
1648   Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1649
1650   This function returns a value of type UINT64 by interpreting the contents of
1651   the ASCII string String as a hexadecimal number. The format of the input ASCII
1652   string String is:
1653
1654                   [spaces][zeros][x][hexadecimal digits].
1655
1656   The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1657   The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1658   appears in the input string, it must be prefixed with at least one 0. The function
1659   will ignore the pad space, which includes spaces or tab characters, before [zeros],
1660   [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1661   will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1662   digit. Then, the function stops at the first character that is a not a valid
1663   hexadecimal character or Null-terminator, whichever on comes first.
1664
1665   If String has only pad spaces, then 0 is returned.
1666   If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1667   0 is returned.
1668
1669   If the number represented by String overflows according to the range defined by UINT64,
1670   then MAX_UINT64 is returned.
1671   If String is NULL, then ASSERT().
1672   If PcdMaximumAsciiStringLength is not zero,
1673   and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1674   the Null-terminator, then ASSERT().
1675
1676   @param  String          A pointer to a Null-terminated ASCII string.
1677
1678   @retval Value translated from String.
1679
1680 **/
1681 UINT64
1682 EFIAPI
1683 AsciiStrHexToUint64 (
1684   IN      CONST CHAR8                *String
1685   )
1686 {
1687   UINT64    Result;
1688
1689   AsciiStrHexToUint64S (String, (CHAR8 **) NULL, &Result);
1690   return Result;
1691 }
1692
1693 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1694
1695 /**
1696   [ATTENTION] This function is deprecated for security reason.
1697
1698   Convert one Null-terminated ASCII string to a Null-terminated
1699   Unicode string and returns the Unicode string.
1700
1701   This function converts the contents of the ASCII string Source to the Unicode
1702   string Destination, and returns Destination.  The function terminates the
1703   Unicode string Destination by appending a Null-terminator character at the end.
1704   The caller is responsible to make sure Destination points to a buffer with size
1705   equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
1706
1707   If Destination is NULL, then ASSERT().
1708   If Destination is not aligned on a 16-bit boundary, then ASSERT().
1709   If Source is NULL, then ASSERT().
1710   If Source and Destination overlap, then ASSERT().
1711   If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1712   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1713   then ASSERT().
1714   If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1715   PcdMaximumUnicodeStringLength ASCII characters not including the
1716   Null-terminator, then ASSERT().
1717
1718   @param  Source        A pointer to a Null-terminated ASCII string.
1719   @param  Destination   A pointer to a Null-terminated Unicode string.
1720
1721   @return Destination.
1722
1723 **/
1724 CHAR16 *
1725 EFIAPI
1726 AsciiStrToUnicodeStr (
1727   IN      CONST CHAR8               *Source,
1728   OUT     CHAR16                    *Destination
1729   )
1730 {
1731   CHAR16                            *ReturnValue;
1732
1733   ASSERT (Destination != NULL);
1734
1735   //
1736   // ASSERT Source is less long than PcdMaximumAsciiStringLength
1737   //
1738   ASSERT (AsciiStrSize (Source) != 0);
1739
1740   //
1741   // Source and Destination should not overlap
1742   //
1743   ASSERT ((UINTN) ((CHAR8 *) Destination - Source) > AsciiStrLen (Source));
1744   ASSERT ((UINTN) (Source - (CHAR8 *) Destination) >= (AsciiStrSize (Source) * sizeof (CHAR16)));
1745
1746
1747   ReturnValue = Destination;
1748   while (*Source != '\0') {
1749     *(Destination++) = (CHAR16) *(Source++);
1750   }
1751   //
1752   // End the Destination with a NULL.
1753   //
1754   *Destination = '\0';
1755
1756   //
1757   // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength
1758   //
1759   ASSERT (StrSize (ReturnValue) != 0);
1760
1761   return ReturnValue;
1762 }
1763
1764 #endif
1765
1766 /**
1767   Converts an 8-bit value to an 8-bit BCD value.
1768
1769   Converts the 8-bit value specified by Value to BCD. The BCD value is
1770   returned.
1771
1772   If Value >= 100, then ASSERT().
1773
1774   @param  Value The 8-bit value to convert to BCD. Range 0..99.
1775
1776   @return The BCD value.
1777
1778 **/
1779 UINT8
1780 EFIAPI
1781 DecimalToBcd8 (
1782   IN      UINT8                     Value
1783   )
1784 {
1785   ASSERT (Value < 100);
1786   return (UINT8) (((Value / 10) << 4) | (Value % 10));
1787 }
1788
1789 /**
1790   Converts an 8-bit BCD value to an 8-bit value.
1791
1792   Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
1793   value is returned.
1794
1795   If Value >= 0xA0, then ASSERT().
1796   If (Value & 0x0F) >= 0x0A, then ASSERT().
1797
1798   @param  Value The 8-bit BCD value to convert to an 8-bit value.
1799
1800   @return The 8-bit value is returned.
1801
1802 **/
1803 UINT8
1804 EFIAPI
1805 BcdToDecimal8 (
1806   IN      UINT8                     Value
1807   )
1808 {
1809   ASSERT (Value < 0xa0);
1810   ASSERT ((Value & 0xf) < 0xa);
1811   return (UINT8) ((Value >> 4) * 10 + (Value & 0xf));
1812 }