1 /** @file 2 Unicode and ASCII string primitives. 3 4 Copyright (c) 2006 - 2016, 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 (UINTN) (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 ASSERT(). 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 // 661 // ASSERT String is less long than PcdMaximumUnicodeStringLength. 662 // Length tests are performed inside StrLen(). 663 // 664 ASSERT (StrSize (String) != 0); 665 666 // 667 // Ignore the pad spaces (space or tab) 668 // 669 while ((*String == L' ') || (*String == L'\t')) { 670 String++; 671 } 672 673 // 674 // Ignore leading Zeros after the spaces 675 // 676 while (*String == L'0') { 677 String++; 678 } 679 680 Result = 0; 681 682 while (InternalIsDecimalDigitCharacter (*String)) { 683 // 684 // If the number represented by String overflows according 685 // to the range defined by UINTN, then ASSERT(). 686 // 687 ASSERT (Result <= ((((UINTN) ~0) - (*String - L'0')) / 10)); 688 689 Result = Result * 10 + (*String - L'0'); 690 String++; 691 } 692 693 return Result; 694 } 695 696 697 /** 698 Convert a Null-terminated Unicode decimal string to a value of 699 type UINT64. 700 701 This function returns a value of type UINT64 by interpreting the contents 702 of the Unicode string specified by String as a decimal number. The format 703 of the input Unicode string String is: 704 705 [spaces] [decimal digits]. 706 707 The valid decimal digit character is in the range [0-9]. The 708 function will ignore the pad space, which includes spaces or 709 tab characters, before [decimal digits]. The running zero in the 710 beginning of [decimal digits] will be ignored. Then, the function 711 stops at the first character that is a not a valid decimal character 712 or a Null-terminator, whichever one comes first. 713 714 If String is NULL, then ASSERT(). 715 If String is not aligned in a 16-bit boundary, then ASSERT(). 716 If String has only pad spaces, then 0 is returned. 717 If String has no pad spaces or valid decimal digits, 718 then 0 is returned. 719 If the number represented by String overflows according 720 to the range defined by UINT64, then ASSERT(). 721 722 If PcdMaximumUnicodeStringLength is not zero, and String contains 723 more than PcdMaximumUnicodeStringLength Unicode characters, not including 724 the Null-terminator, then ASSERT(). 725 726 @param String A pointer to a Null-terminated Unicode string. 727 728 @retval Value translated from String. 729 730 **/ 731 UINT64 732 EFIAPI 733 StrDecimalToUint64 ( 734 IN CONST CHAR16 *String 735 ) 736 { 737 UINT64 Result; 738 739 // 740 // ASSERT String is less long than PcdMaximumUnicodeStringLength. 741 // Length tests are performed inside StrLen(). 742 // 743 ASSERT (StrSize (String) != 0); 744 745 // 746 // Ignore the pad spaces (space or tab) 747 // 748 while ((*String == L' ') || (*String == L'\t')) { 749 String++; 750 } 751 752 // 753 // Ignore leading Zeros after the spaces 754 // 755 while (*String == L'0') { 756 String++; 757 } 758 759 Result = 0; 760 761 while (InternalIsDecimalDigitCharacter (*String)) { 762 // 763 // If the number represented by String overflows according 764 // to the range defined by UINTN, then ASSERT(). 765 // 766 ASSERT (Result <= DivU64x32 (((UINT64) ~0) - (*String - L'0') , 10)); 767 768 Result = MultU64x32 (Result, 10) + (*String - L'0'); 769 String++; 770 } 771 772 return Result; 773 } 774 775 /** 776 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN. 777 778 This function returns a value of type UINTN by interpreting the contents 779 of the Unicode string specified by String as a hexadecimal number. 780 The format of the input Unicode string String is: 781 782 [spaces][zeros][x][hexadecimal digits]. 783 784 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 785 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 786 If "x" appears in the input string, it must be prefixed with at least one 0. 787 The function will ignore the pad space, which includes spaces or tab characters, 788 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 789 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 790 first valid hexadecimal digit. Then, the function stops at the first character that is 791 a not a valid hexadecimal character or NULL, whichever one comes first. 792 793 If String is NULL, then ASSERT(). 794 If String is not aligned in a 16-bit boundary, then ASSERT(). 795 If String has only pad spaces, then zero is returned. 796 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 797 then zero is returned. 798 If the number represented by String overflows according to the range defined by 799 UINTN, then ASSERT(). 800 801 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 802 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, 803 then ASSERT(). 804 805 @param String A pointer to a Null-terminated Unicode string. 806 807 @retval Value translated from String. 808 809 **/ 810 UINTN 811 EFIAPI 812 StrHexToUintn ( 813 IN CONST CHAR16 *String 814 ) 815 { 816 UINTN Result; 817 818 // 819 // ASSERT String is less long than PcdMaximumUnicodeStringLength. 820 // Length tests are performed inside StrLen(). 821 // 822 ASSERT (StrSize (String) != 0); 823 824 // 825 // Ignore the pad spaces (space or tab) 826 // 827 while ((*String == L' ') || (*String == L'\t')) { 828 String++; 829 } 830 831 // 832 // Ignore leading Zeros after the spaces 833 // 834 while (*String == L'0') { 835 String++; 836 } 837 838 if (InternalCharToUpper (*String) == L'X') { 839 if (*(String - 1) != L'0') { 840 return 0; 841 } 842 // 843 // Skip the 'X' 844 // 845 String++; 846 } 847 848 Result = 0; 849 850 while (InternalIsHexaDecimalDigitCharacter (*String)) { 851 // 852 // If the Hex Number represented by String overflows according 853 // to the range defined by UINTN, then ASSERT(). 854 // 855 ASSERT (Result <= ((((UINTN) ~0) - InternalHexCharToUintn (*String)) >> 4)); 856 857 Result = (Result << 4) + InternalHexCharToUintn (*String); 858 String++; 859 } 860 861 return Result; 862 } 863 864 865 /** 866 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64. 867 868 This function returns a value of type UINT64 by interpreting the contents 869 of the Unicode string specified by String as a hexadecimal number. 870 The format of the input Unicode string String is 871 872 [spaces][zeros][x][hexadecimal digits]. 873 874 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 875 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. 876 If "x" appears in the input string, it must be prefixed with at least one 0. 877 The function will ignore the pad space, which includes spaces or tab characters, 878 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or 879 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the 880 first valid hexadecimal digit. Then, the function stops at the first character that is 881 a not a valid hexadecimal character or NULL, whichever one comes first. 882 883 If String is NULL, then ASSERT(). 884 If String is not aligned in a 16-bit boundary, then ASSERT(). 885 If String has only pad spaces, then zero is returned. 886 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, 887 then zero is returned. 888 If the number represented by String overflows according to the range defined by 889 UINT64, then ASSERT(). 890 891 If PcdMaximumUnicodeStringLength is not zero, and String contains more than 892 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, 893 then ASSERT(). 894 895 @param String A pointer to a Null-terminated Unicode string. 896 897 @retval Value translated from String. 898 899 **/ 900 UINT64 901 EFIAPI 902 StrHexToUint64 ( 903 IN CONST CHAR16 *String 904 ) 905 { 906 UINT64 Result; 907 908 // 909 // ASSERT String is less long than PcdMaximumUnicodeStringLength. 910 // Length tests are performed inside StrLen(). 911 // 912 ASSERT (StrSize (String) != 0); 913 914 // 915 // Ignore the pad spaces (space or tab) 916 // 917 while ((*String == L' ') || (*String == L'\t')) { 918 String++; 919 } 920 921 // 922 // Ignore leading Zeros after the spaces 923 // 924 while (*String == L'0') { 925 String++; 926 } 927 928 if (InternalCharToUpper (*String) == L'X') { 929 ASSERT (*(String - 1) == L'0'); 930 if (*(String - 1) != L'0') { 931 return 0; 932 } 933 // 934 // Skip the 'X' 935 // 936 String++; 937 } 938 939 Result = 0; 940 941 while (InternalIsHexaDecimalDigitCharacter (*String)) { 942 // 943 // If the Hex Number represented by String overflows according 944 // to the range defined by UINTN, then ASSERT(). 945 // 946 ASSERT (Result <= RShiftU64 (((UINT64) ~0) - InternalHexCharToUintn (*String) , 4)); 947 948 Result = LShiftU64 (Result, 4); 949 Result = Result + InternalHexCharToUintn (*String); 950 String++; 951 } 952 953 return Result; 954 } 955 956 /** 957 Check if a ASCII character is a decimal character. 958 959 This internal function checks if a Unicode character is a 960 decimal character. The valid decimal character is from 961 '0' to '9'. 962 963 @param Char The character to check against. 964 965 @retval TRUE If the Char is a decmial character. 966 @retval FALSE If the Char is not a decmial character. 967 968 **/ 969 BOOLEAN 970 EFIAPI 971 InternalAsciiIsDecimalDigitCharacter ( 972 IN CHAR8 Char 973 ) 974 { 975 return (BOOLEAN) (Char >= '0' && Char <= '9'); 976 } 977 978 /** 979 Check if a ASCII character is a hexadecimal character. 980 981 This internal function checks if a ASCII character is a 982 decimal character. The valid hexadecimal character is 983 L'0' to L'9', L'a' to L'f', or L'A' to L'F'. 984 985 986 @param Char The character to check against. 987 988 @retval TRUE If the Char is a hexadecmial character. 989 @retval FALSE If the Char is not a hexadecmial character. 990 991 **/ 992 BOOLEAN 993 EFIAPI 994 InternalAsciiIsHexaDecimalDigitCharacter ( 995 IN CHAR8 Char 996 ) 997 { 998 999 return (BOOLEAN) (InternalAsciiIsDecimalDigitCharacter (Char) || 1000 (Char >= 'A' && Char <= 'F') || 1001 (Char >= 'a' && Char <= 'f')); 1002 } 1003 1004 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 1005 1006 /** 1007 [ATTENTION] This function is deprecated for security reason. 1008 1009 Convert a Null-terminated Unicode string to a Null-terminated 1010 ASCII string and returns the ASCII string. 1011 1012 This function converts the content of the Unicode string Source 1013 to the ASCII string Destination by copying the lower 8 bits of 1014 each Unicode character. It returns Destination. 1015 1016 The caller is responsible to make sure Destination points to a buffer with size 1017 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes. 1018 1019 If any Unicode characters in Source contain non-zero value in 1020 the upper 8 bits, then ASSERT(). 1021 1022 If Destination is NULL, then ASSERT(). 1023 If Source is NULL, then ASSERT(). 1024 If Source is not aligned on a 16-bit boundary, then ASSERT(). 1025 If Source and Destination overlap, then ASSERT(). 1026 1027 If PcdMaximumUnicodeStringLength is not zero, and Source contains 1028 more than PcdMaximumUnicodeStringLength Unicode characters, not including 1029 the Null-terminator, then ASSERT(). 1030 1031 If PcdMaximumAsciiStringLength is not zero, and Source contains more 1032 than PcdMaximumAsciiStringLength Unicode characters, not including the 1033 Null-terminator, then ASSERT(). 1034 1035 @param Source A pointer to a Null-terminated Unicode string. 1036 @param Destination A pointer to a Null-terminated ASCII string. 1037 1038 @return Destination. 1039 1040 **/ 1041 CHAR8 * 1042 EFIAPI 1043 UnicodeStrToAsciiStr ( 1044 IN CONST CHAR16 *Source, 1045 OUT CHAR8 *Destination 1046 ) 1047 { 1048 CHAR8 *ReturnValue; 1049 1050 ASSERT (Destination != NULL); 1051 1052 // 1053 // ASSERT if Source is long than PcdMaximumUnicodeStringLength. 1054 // Length tests are performed inside StrLen(). 1055 // 1056 ASSERT (StrSize (Source) != 0); 1057 1058 // 1059 // Source and Destination should not overlap 1060 // 1061 ASSERT ((UINTN) (Destination - (CHAR8 *) Source) >= StrSize (Source)); 1062 ASSERT ((UINTN) ((CHAR8 *) Source - Destination) > StrLen (Source)); 1063 1064 1065 ReturnValue = Destination; 1066 while (*Source != '\0') { 1067 // 1068 // If any Unicode characters in Source contain 1069 // non-zero value in the upper 8 bits, then ASSERT(). 1070 // 1071 ASSERT (*Source < 0x100); 1072 *(Destination++) = (CHAR8) *(Source++); 1073 } 1074 1075 *Destination = '\0'; 1076 1077 // 1078 // ASSERT Original Destination is less long than PcdMaximumAsciiStringLength. 1079 // Length tests are performed inside AsciiStrLen(). 1080 // 1081 ASSERT (AsciiStrSize (ReturnValue) != 0); 1082 1083 return ReturnValue; 1084 } 1085 1086 /** 1087 [ATTENTION] This function will be deprecated for security reason. 1088 1089 Copies one Null-terminated ASCII string to another Null-terminated ASCII 1090 string and returns the new ASCII string. 1091 1092 This function copies the contents of the ASCII string Source to the ASCII 1093 string Destination, and returns Destination. If Source and Destination 1094 overlap, then the results are undefined. 1095 1096 If Destination is NULL, then ASSERT(). 1097 If Source is NULL, then ASSERT(). 1098 If Source and Destination overlap, then ASSERT(). 1099 If PcdMaximumAsciiStringLength is not zero and Source contains more than 1100 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1101 then ASSERT(). 1102 1103 @param Destination A pointer to a Null-terminated ASCII string. 1104 @param Source A pointer to a Null-terminated ASCII string. 1105 1106 @return Destination 1107 1108 **/ 1109 CHAR8 * 1110 EFIAPI 1111 AsciiStrCpy ( 1112 OUT CHAR8 *Destination, 1113 IN CONST CHAR8 *Source 1114 ) 1115 { 1116 CHAR8 *ReturnValue; 1117 1118 // 1119 // Destination cannot be NULL 1120 // 1121 ASSERT (Destination != NULL); 1122 1123 // 1124 // Destination and source cannot overlap 1125 // 1126 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source)); 1127 ASSERT ((UINTN)(Source - Destination) > AsciiStrLen (Source)); 1128 1129 ReturnValue = Destination; 1130 while (*Source != 0) { 1131 *(Destination++) = *(Source++); 1132 } 1133 *Destination = 0; 1134 return ReturnValue; 1135 } 1136 1137 /** 1138 [ATTENTION] This function will be deprecated for security reason. 1139 1140 Copies up to a specified length one Null-terminated ASCII string to another 1141 Null-terminated ASCII string and returns the new ASCII string. 1142 1143 This function copies the contents of the ASCII string Source to the ASCII 1144 string Destination, and returns Destination. At most, Length ASCII characters 1145 are copied from Source to Destination. If Length is 0, then Destination is 1146 returned unmodified. If Length is greater that the number of ASCII characters 1147 in Source, then Destination is padded with Null ASCII characters. If Source 1148 and Destination overlap, then the results are undefined. 1149 1150 If Destination is NULL, then ASSERT(). 1151 If Source is NULL, then ASSERT(). 1152 If Source and Destination overlap, then ASSERT(). 1153 If PcdMaximumAsciiStringLength is not zero, and Length is greater than 1154 PcdMaximumAsciiStringLength, then ASSERT(). 1155 If PcdMaximumAsciiStringLength is not zero, and Source contains more than 1156 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1157 then ASSERT(). 1158 1159 @param Destination A pointer to a Null-terminated ASCII string. 1160 @param Source A pointer to a Null-terminated ASCII string. 1161 @param Length The maximum number of ASCII characters to copy. 1162 1163 @return Destination 1164 1165 **/ 1166 CHAR8 * 1167 EFIAPI 1168 AsciiStrnCpy ( 1169 OUT CHAR8 *Destination, 1170 IN CONST CHAR8 *Source, 1171 IN UINTN Length 1172 ) 1173 { 1174 CHAR8 *ReturnValue; 1175 1176 if (Length == 0) { 1177 return Destination; 1178 } 1179 1180 // 1181 // Destination cannot be NULL 1182 // 1183 ASSERT (Destination != NULL); 1184 1185 // 1186 // Destination and source cannot overlap 1187 // 1188 ASSERT ((UINTN)(Destination - Source) > AsciiStrLen (Source)); 1189 ASSERT ((UINTN)(Source - Destination) >= Length); 1190 1191 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) { 1192 ASSERT (Length <= PcdGet32 (PcdMaximumAsciiStringLength)); 1193 } 1194 1195 ReturnValue = Destination; 1196 1197 while (*Source != 0 && Length > 0) { 1198 *(Destination++) = *(Source++); 1199 Length--; 1200 } 1201 1202 ZeroMem (Destination, Length * sizeof (*Destination)); 1203 return ReturnValue; 1204 } 1205 #endif 1206 1207 /** 1208 Returns the length of a Null-terminated ASCII string. 1209 1210 This function returns the number of ASCII characters in the Null-terminated 1211 ASCII string specified by String. 1212 1213 If Length > 0 and Destination is NULL, then ASSERT(). 1214 If Length > 0 and Source is NULL, then ASSERT(). 1215 If PcdMaximumAsciiStringLength is not zero and String contains more than 1216 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1217 then ASSERT(). 1218 1219 @param String A pointer to a Null-terminated ASCII string. 1220 1221 @return The length of String. 1222 1223 **/ 1224 UINTN 1225 EFIAPI 1226 AsciiStrLen ( 1227 IN CONST CHAR8 *String 1228 ) 1229 { 1230 UINTN Length; 1231 1232 ASSERT (String != NULL); 1233 1234 for (Length = 0; *String != '\0'; String++, Length++) { 1235 // 1236 // If PcdMaximumUnicodeStringLength is not zero, 1237 // length should not more than PcdMaximumUnicodeStringLength 1238 // 1239 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) { 1240 ASSERT (Length < PcdGet32 (PcdMaximumAsciiStringLength)); 1241 } 1242 } 1243 return Length; 1244 } 1245 1246 /** 1247 Returns the size of a Null-terminated ASCII string in bytes, including the 1248 Null terminator. 1249 1250 This function returns the size, in bytes, of the Null-terminated ASCII string 1251 specified by String. 1252 1253 If String is NULL, then ASSERT(). 1254 If PcdMaximumAsciiStringLength is not zero and String contains more than 1255 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1256 then ASSERT(). 1257 1258 @param String A pointer to a Null-terminated ASCII string. 1259 1260 @return The size of String. 1261 1262 **/ 1263 UINTN 1264 EFIAPI 1265 AsciiStrSize ( 1266 IN CONST CHAR8 *String 1267 ) 1268 { 1269 return (AsciiStrLen (String) + 1) * sizeof (*String); 1270 } 1271 1272 /** 1273 Compares two Null-terminated ASCII strings, and returns the difference 1274 between the first mismatched ASCII characters. 1275 1276 This function compares the Null-terminated ASCII string FirstString to the 1277 Null-terminated ASCII string SecondString. If FirstString is identical to 1278 SecondString, then 0 is returned. Otherwise, the value returned is the first 1279 mismatched ASCII character in SecondString subtracted from the first 1280 mismatched ASCII character in FirstString. 1281 1282 If FirstString is NULL, then ASSERT(). 1283 If SecondString is NULL, then ASSERT(). 1284 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than 1285 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1286 then ASSERT(). 1287 If PcdMaximumAsciiStringLength is not zero and SecondString contains more 1288 than PcdMaximumAsciiStringLength ASCII characters, not including the 1289 Null-terminator, then ASSERT(). 1290 1291 @param FirstString A pointer to a Null-terminated ASCII string. 1292 @param SecondString A pointer to a Null-terminated ASCII string. 1293 1294 @retval ==0 FirstString is identical to SecondString. 1295 @retval !=0 FirstString is not identical to SecondString. 1296 1297 **/ 1298 INTN 1299 EFIAPI 1300 AsciiStrCmp ( 1301 IN CONST CHAR8 *FirstString, 1302 IN CONST CHAR8 *SecondString 1303 ) 1304 { 1305 // 1306 // ASSERT both strings are less long than PcdMaximumAsciiStringLength 1307 // 1308 ASSERT (AsciiStrSize (FirstString)); 1309 ASSERT (AsciiStrSize (SecondString)); 1310 1311 while ((*FirstString != '\0') && (*FirstString == *SecondString)) { 1312 FirstString++; 1313 SecondString++; 1314 } 1315 1316 return *FirstString - *SecondString; 1317 } 1318 1319 /** 1320 Converts a lowercase Ascii character to upper one. 1321 1322 If Chr is lowercase Ascii character, then converts it to upper one. 1323 1324 If Value >= 0xA0, then ASSERT(). 1325 If (Value & 0x0F) >= 0x0A, then ASSERT(). 1326 1327 @param Chr one Ascii character 1328 1329 @return The uppercase value of Ascii character 1330 1331 **/ 1332 CHAR8 1333 EFIAPI 1334 InternalBaseLibAsciiToUpper ( 1335 IN CHAR8 Chr 1336 ) 1337 { 1338 return (UINT8) ((Chr >= 'a' && Chr <= 'z') ? Chr - ('a' - 'A') : Chr); 1339 } 1340 1341 /** 1342 Convert a ASCII character to numerical value. 1343 1344 This internal function only deal with Unicode character 1345 which maps to a valid hexadecimal ASII character, i.e. 1346 '0' to '9', 'a' to 'f' or 'A' to 'F'. For other 1347 ASCII character, the value returned does not make sense. 1348 1349 @param Char The character to convert. 1350 1351 @return The numerical value converted. 1352 1353 **/ 1354 UINTN 1355 EFIAPI 1356 InternalAsciiHexCharToUintn ( 1357 IN CHAR8 Char 1358 ) 1359 { 1360 if (InternalIsDecimalDigitCharacter (Char)) { 1361 return Char - '0'; 1362 } 1363 1364 return (UINTN) (10 + InternalBaseLibAsciiToUpper (Char) - 'A'); 1365 } 1366 1367 1368 /** 1369 Performs a case insensitive comparison of two Null-terminated ASCII strings, 1370 and returns the difference between the first mismatched ASCII characters. 1371 1372 This function performs a case insensitive comparison of the Null-terminated 1373 ASCII string FirstString to the Null-terminated ASCII string SecondString. If 1374 FirstString is identical to SecondString, then 0 is returned. Otherwise, the 1375 value returned is the first mismatched lower case ASCII character in 1376 SecondString subtracted from the first mismatched lower case ASCII character 1377 in FirstString. 1378 1379 If FirstString is NULL, then ASSERT(). 1380 If SecondString is NULL, then ASSERT(). 1381 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than 1382 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1383 then ASSERT(). 1384 If PcdMaximumAsciiStringLength is not zero and SecondString contains more 1385 than PcdMaximumAsciiStringLength ASCII characters, not including the 1386 Null-terminator, then ASSERT(). 1387 1388 @param FirstString A pointer to a Null-terminated ASCII string. 1389 @param SecondString A pointer to a Null-terminated ASCII string. 1390 1391 @retval ==0 FirstString is identical to SecondString using case insensitive 1392 comparisons. 1393 @retval !=0 FirstString is not identical to SecondString using case 1394 insensitive comparisons. 1395 1396 **/ 1397 INTN 1398 EFIAPI 1399 AsciiStriCmp ( 1400 IN CONST CHAR8 *FirstString, 1401 IN CONST CHAR8 *SecondString 1402 ) 1403 { 1404 CHAR8 UpperFirstString; 1405 CHAR8 UpperSecondString; 1406 1407 // 1408 // ASSERT both strings are less long than PcdMaximumAsciiStringLength 1409 // 1410 ASSERT (AsciiStrSize (FirstString)); 1411 ASSERT (AsciiStrSize (SecondString)); 1412 1413 UpperFirstString = InternalBaseLibAsciiToUpper (*FirstString); 1414 UpperSecondString = InternalBaseLibAsciiToUpper (*SecondString); 1415 while ((*FirstString != '\0') && (UpperFirstString == UpperSecondString)) { 1416 FirstString++; 1417 SecondString++; 1418 UpperFirstString = InternalBaseLibAsciiToUpper (*FirstString); 1419 UpperSecondString = InternalBaseLibAsciiToUpper (*SecondString); 1420 } 1421 1422 return UpperFirstString - UpperSecondString; 1423 } 1424 1425 /** 1426 Compares two Null-terminated ASCII strings with maximum lengths, and returns 1427 the difference between the first mismatched ASCII characters. 1428 1429 This function compares the Null-terminated ASCII string FirstString to the 1430 Null-terminated ASCII string SecondString. At most, Length ASCII characters 1431 will be compared. If Length is 0, then 0 is returned. If FirstString is 1432 identical to SecondString, then 0 is returned. Otherwise, the value returned 1433 is the first mismatched ASCII character in SecondString subtracted from the 1434 first mismatched ASCII character in FirstString. 1435 1436 If Length > 0 and FirstString is NULL, then ASSERT(). 1437 If Length > 0 and SecondString is NULL, then ASSERT(). 1438 If PcdMaximumAsciiStringLength is not zero, and Length is greater than 1439 PcdMaximumAsciiStringLength, then ASSERT(). 1440 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than 1441 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1442 then ASSERT(). 1443 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than 1444 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1445 then ASSERT(). 1446 1447 @param FirstString A pointer to a Null-terminated ASCII string. 1448 @param SecondString A pointer to a Null-terminated ASCII string. 1449 @param Length The maximum number of ASCII characters for compare. 1450 1451 @retval ==0 FirstString is identical to SecondString. 1452 @retval !=0 FirstString is not identical to SecondString. 1453 1454 **/ 1455 INTN 1456 EFIAPI 1457 AsciiStrnCmp ( 1458 IN CONST CHAR8 *FirstString, 1459 IN CONST CHAR8 *SecondString, 1460 IN UINTN Length 1461 ) 1462 { 1463 if (Length == 0) { 1464 return 0; 1465 } 1466 1467 // 1468 // ASSERT both strings are less long than PcdMaximumAsciiStringLength 1469 // 1470 ASSERT (AsciiStrSize (FirstString)); 1471 ASSERT (AsciiStrSize (SecondString)); 1472 1473 if (PcdGet32 (PcdMaximumAsciiStringLength) != 0) { 1474 ASSERT (Length <= PcdGet32 (PcdMaximumAsciiStringLength)); 1475 } 1476 1477 while ((*FirstString != '\0') && 1478 (*SecondString != '\0') && 1479 (*FirstString == *SecondString) && 1480 (Length > 1)) { 1481 FirstString++; 1482 SecondString++; 1483 Length--; 1484 } 1485 return *FirstString - *SecondString; 1486 } 1487 1488 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 1489 1490 /** 1491 [ATTENTION] This function will be deprecated for security reason. 1492 1493 Concatenates one Null-terminated ASCII string to another Null-terminated 1494 ASCII string, and returns the concatenated ASCII string. 1495 1496 This function concatenates two Null-terminated ASCII strings. The contents of 1497 Null-terminated ASCII string Source are concatenated to the end of Null- 1498 terminated ASCII string Destination. The Null-terminated concatenated ASCII 1499 String is returned. 1500 1501 If Destination is NULL, then ASSERT(). 1502 If Source is NULL, then ASSERT(). 1503 If PcdMaximumAsciiStringLength is not zero and Destination contains more than 1504 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1505 then ASSERT(). 1506 If PcdMaximumAsciiStringLength is not zero and Source contains more than 1507 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1508 then ASSERT(). 1509 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and 1510 Source results in a ASCII string with more than PcdMaximumAsciiStringLength 1511 ASCII characters, then ASSERT(). 1512 1513 @param Destination A pointer to a Null-terminated ASCII string. 1514 @param Source A pointer to a Null-terminated ASCII string. 1515 1516 @return Destination 1517 1518 **/ 1519 CHAR8 * 1520 EFIAPI 1521 AsciiStrCat ( 1522 IN OUT CHAR8 *Destination, 1523 IN CONST CHAR8 *Source 1524 ) 1525 { 1526 AsciiStrCpy (Destination + AsciiStrLen (Destination), Source); 1527 1528 // 1529 // Size of the resulting string should never be zero. 1530 // PcdMaximumUnicodeStringLength is tested inside StrLen(). 1531 // 1532 ASSERT (AsciiStrSize (Destination) != 0); 1533 return Destination; 1534 } 1535 1536 /** 1537 [ATTENTION] This function will be deprecated for security reason. 1538 1539 Concatenates up to a specified length one Null-terminated ASCII string to 1540 the end of another Null-terminated ASCII string, and returns the 1541 concatenated ASCII string. 1542 1543 This function concatenates two Null-terminated ASCII strings. The contents 1544 of Null-terminated ASCII string Source are concatenated to the end of Null- 1545 terminated ASCII string Destination, and Destination is returned. At most, 1546 Length ASCII characters are concatenated from Source to the end of 1547 Destination, and Destination is always Null-terminated. If Length is 0, then 1548 Destination is returned unmodified. If Source and Destination overlap, then 1549 the results are undefined. 1550 1551 If Length > 0 and Destination is NULL, then ASSERT(). 1552 If Length > 0 and Source is NULL, then ASSERT(). 1553 If Source and Destination overlap, then ASSERT(). 1554 If PcdMaximumAsciiStringLength is not zero, and Length is greater than 1555 PcdMaximumAsciiStringLength, then ASSERT(). 1556 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than 1557 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1558 then ASSERT(). 1559 If PcdMaximumAsciiStringLength is not zero, and Source contains more than 1560 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, 1561 then ASSERT(). 1562 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and 1563 Source results in a ASCII string with more than PcdMaximumAsciiStringLength 1564 ASCII characters, not including the Null-terminator, then ASSERT(). 1565 1566 @param Destination A pointer to a Null-terminated ASCII string. 1567 @param Source A pointer to a Null-terminated ASCII string. 1568 @param Length The maximum number of ASCII characters to concatenate from 1569 Source. 1570 1571 @return Destination 1572 1573 **/ 1574 CHAR8 * 1575 EFIAPI 1576 AsciiStrnCat ( 1577 IN OUT CHAR8 *Destination, 1578 IN CONST CHAR8 *Source, 1579 IN UINTN Length 1580 ) 1581 { 1582 UINTN DestinationLen; 1583 1584 DestinationLen = AsciiStrLen (Destination); 1585 AsciiStrnCpy (Destination + DestinationLen, Source, Length); 1586 Destination[DestinationLen + Length] = '\0'; 1587 1588 // 1589 // Size of the resulting string should never be zero. 1590 // PcdMaximumUnicodeStringLength is tested inside StrLen(). 1591 // 1592 ASSERT (AsciiStrSize (Destination) != 0); 1593 return Destination; 1594 } 1595 #endif 1596 1597 /** 1598 Returns the first occurrence of a Null-terminated ASCII sub-string 1599 in a Null-terminated ASCII string. 1600 1601 This function scans the contents of the ASCII string specified by String 1602 and returns the first occurrence of SearchString. If SearchString is not 1603 found in String, then NULL is returned. If the length of SearchString is zero, 1604 then String is returned. 1605 1606 If String is NULL, then ASSERT(). 1607 If SearchString is NULL, then ASSERT(). 1608 1609 If PcdMaximumAsciiStringLength is not zero, and SearchString or 1610 String contains more than PcdMaximumAsciiStringLength Unicode characters 1611 not including the Null-terminator, then ASSERT(). 1612 1613 @param String A pointer to a Null-terminated ASCII string. 1614 @param SearchString A pointer to a Null-terminated ASCII string to search for. 1615 1616 @retval NULL If the SearchString does not appear in String. 1617 @retval others If there is a match return the first occurrence of SearchingString. 1618 If the length of SearchString is zero,return String. 1619 1620 **/ 1621 CHAR8 * 1622 EFIAPI 1623 AsciiStrStr ( 1624 IN CONST CHAR8 *String, 1625 IN CONST CHAR8 *SearchString 1626 ) 1627 { 1628 CONST CHAR8 *FirstMatch; 1629 CONST CHAR8 *SearchStringTmp; 1630 1631 // 1632 // ASSERT both strings are less long than PcdMaximumAsciiStringLength 1633 // 1634 ASSERT (AsciiStrSize (String) != 0); 1635 ASSERT (AsciiStrSize (SearchString) != 0); 1636 1637 if (*SearchString == '\0') { 1638 return (CHAR8 *) String; 1639 } 1640 1641 while (*String != '\0') { 1642 SearchStringTmp = SearchString; 1643 FirstMatch = String; 1644 1645 while ((*String == *SearchStringTmp) 1646 && (*String != '\0')) { 1647 String++; 1648 SearchStringTmp++; 1649 } 1650 1651 if (*SearchStringTmp == '\0') { 1652 return (CHAR8 *) FirstMatch; 1653 } 1654 1655 if (*String == '\0') { 1656 return NULL; 1657 } 1658 1659 String = FirstMatch + 1; 1660 } 1661 1662 return NULL; 1663 } 1664 1665 /** 1666 Convert a Null-terminated ASCII decimal string to a value of type 1667 UINTN. 1668 1669 This function returns a value of type UINTN by interpreting the contents 1670 of the ASCII string String as a decimal number. The format of the input 1671 ASCII string String is: 1672 1673 [spaces] [decimal digits]. 1674 1675 The valid decimal digit character is in the range [0-9]. The function will 1676 ignore the pad space, which includes spaces or tab characters, before the digits. 1677 The running zero in the beginning of [decimal digits] will be ignored. Then, the 1678 function stops at the first character that is a not a valid decimal character or 1679 Null-terminator, whichever on comes first. 1680 1681 If String has only pad spaces, then 0 is returned. 1682 If String has no pad spaces or valid decimal digits, then 0 is returned. 1683 If the number represented by String overflows according to the range defined by 1684 UINTN, then ASSERT(). 1685 If String is NULL, then ASSERT(). 1686 If PcdMaximumAsciiStringLength is not zero, and String contains more than 1687 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1688 then ASSERT(). 1689 1690 @param String A pointer to a Null-terminated ASCII string. 1691 1692 @retval Value translated from String. 1693 1694 **/ 1695 UINTN 1696 EFIAPI 1697 AsciiStrDecimalToUintn ( 1698 IN CONST CHAR8 *String 1699 ) 1700 { 1701 UINTN Result; 1702 1703 // 1704 // ASSERT Strings is less long than PcdMaximumAsciiStringLength 1705 // 1706 ASSERT (AsciiStrSize (String) != 0); 1707 1708 // 1709 // Ignore the pad spaces (space or tab) 1710 // 1711 while ((*String == ' ') || (*String == '\t' )) { 1712 String++; 1713 } 1714 1715 // 1716 // Ignore leading Zeros after the spaces 1717 // 1718 while (*String == '0') { 1719 String++; 1720 } 1721 1722 Result = 0; 1723 1724 while (InternalAsciiIsDecimalDigitCharacter (*String)) { 1725 // 1726 // If the number represented by String overflows according 1727 // to the range defined by UINTN, then ASSERT(). 1728 // 1729 ASSERT (Result <= ((((UINTN) ~0) - (*String - L'0')) / 10)); 1730 1731 Result = Result * 10 + (*String - '0'); 1732 String++; 1733 } 1734 1735 return Result; 1736 } 1737 1738 1739 /** 1740 Convert a Null-terminated ASCII decimal string to a value of type 1741 UINT64. 1742 1743 This function returns a value of type UINT64 by interpreting the contents 1744 of the ASCII string String as a decimal number. The format of the input 1745 ASCII string String is: 1746 1747 [spaces] [decimal digits]. 1748 1749 The valid decimal digit character is in the range [0-9]. The function will 1750 ignore the pad space, which includes spaces or tab characters, before the digits. 1751 The running zero in the beginning of [decimal digits] will be ignored. Then, the 1752 function stops at the first character that is a not a valid decimal character or 1753 Null-terminator, whichever on comes first. 1754 1755 If String has only pad spaces, then 0 is returned. 1756 If String has no pad spaces or valid decimal digits, then 0 is returned. 1757 If the number represented by String overflows according to the range defined by 1758 UINT64, then ASSERT(). 1759 If String is NULL, then ASSERT(). 1760 If PcdMaximumAsciiStringLength is not zero, and String contains more than 1761 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 1762 then ASSERT(). 1763 1764 @param String A pointer to a Null-terminated ASCII string. 1765 1766 @retval Value translated from String. 1767 1768 **/ 1769 UINT64 1770 EFIAPI 1771 AsciiStrDecimalToUint64 ( 1772 IN CONST CHAR8 *String 1773 ) 1774 { 1775 UINT64 Result; 1776 1777 // 1778 // ASSERT Strings is less long than PcdMaximumAsciiStringLength 1779 // 1780 ASSERT (AsciiStrSize (String) != 0); 1781 1782 // 1783 // Ignore the pad spaces (space or tab) 1784 // 1785 while ((*String == ' ') || (*String == '\t' )) { 1786 String++; 1787 } 1788 1789 // 1790 // Ignore leading Zeros after the spaces 1791 // 1792 while (*String == '0') { 1793 String++; 1794 } 1795 1796 Result = 0; 1797 1798 while (InternalAsciiIsDecimalDigitCharacter (*String)) { 1799 // 1800 // If the number represented by String overflows according 1801 // to the range defined by UINTN, then ASSERT(). 1802 // 1803 ASSERT (Result <= DivU64x32 (((UINT64) ~0) - (*String - L'0') , 10)); 1804 1805 Result = MultU64x32 (Result, 10) + (*String - '0'); 1806 String++; 1807 } 1808 1809 return Result; 1810 } 1811 1812 /** 1813 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN. 1814 1815 This function returns a value of type UINTN by interpreting the contents of 1816 the ASCII string String as a hexadecimal number. The format of the input ASCII 1817 string String is: 1818 1819 [spaces][zeros][x][hexadecimal digits]. 1820 1821 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1822 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 1823 appears in the input string, it must be prefixed with at least one 0. The function 1824 will ignore the pad space, which includes spaces or tab characters, before [zeros], 1825 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 1826 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 1827 digit. Then, the function stops at the first character that is a not a valid 1828 hexadecimal character or Null-terminator, whichever on comes first. 1829 1830 If String has only pad spaces, then 0 is returned. 1831 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then 1832 0 is returned. 1833 1834 If the number represented by String overflows according to the range defined by UINTN, 1835 then ASSERT(). 1836 If String is NULL, then ASSERT(). 1837 If PcdMaximumAsciiStringLength is not zero, 1838 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 1839 the Null-terminator, then ASSERT(). 1840 1841 @param String A pointer to a Null-terminated ASCII string. 1842 1843 @retval Value translated from String. 1844 1845 **/ 1846 UINTN 1847 EFIAPI 1848 AsciiStrHexToUintn ( 1849 IN CONST CHAR8 *String 1850 ) 1851 { 1852 UINTN Result; 1853 1854 // 1855 // ASSERT Strings is less long than PcdMaximumAsciiStringLength 1856 // 1857 ASSERT (AsciiStrSize (String) != 0); 1858 1859 // 1860 // Ignore the pad spaces (space or tab) 1861 // 1862 while ((*String == ' ') || (*String == '\t' )) { 1863 String++; 1864 } 1865 1866 // 1867 // Ignore leading Zeros after the spaces 1868 // 1869 while (*String == '0') { 1870 String++; 1871 } 1872 1873 if (InternalBaseLibAsciiToUpper (*String) == 'X') { 1874 ASSERT (*(String - 1) == '0'); 1875 if (*(String - 1) != '0') { 1876 return 0; 1877 } 1878 // 1879 // Skip the 'X' 1880 // 1881 String++; 1882 } 1883 1884 Result = 0; 1885 1886 while (InternalAsciiIsHexaDecimalDigitCharacter (*String)) { 1887 // 1888 // If the Hex Number represented by String overflows according 1889 // to the range defined by UINTN, then ASSERT(). 1890 // 1891 ASSERT (Result <= ((((UINTN) ~0) - InternalHexCharToUintn (*String)) >> 4)); 1892 1893 Result = (Result << 4) + InternalAsciiHexCharToUintn (*String); 1894 String++; 1895 } 1896 1897 return Result; 1898 } 1899 1900 1901 /** 1902 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64. 1903 1904 This function returns a value of type UINT64 by interpreting the contents of 1905 the ASCII string String as a hexadecimal number. The format of the input ASCII 1906 string String is: 1907 1908 [spaces][zeros][x][hexadecimal digits]. 1909 1910 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. 1911 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" 1912 appears in the input string, it must be prefixed with at least one 0. The function 1913 will ignore the pad space, which includes spaces or tab characters, before [zeros], 1914 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] 1915 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal 1916 digit. Then, the function stops at the first character that is a not a valid 1917 hexadecimal character or Null-terminator, whichever on comes first. 1918 1919 If String has only pad spaces, then 0 is returned. 1920 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then 1921 0 is returned. 1922 1923 If the number represented by String overflows according to the range defined by UINT64, 1924 then ASSERT(). 1925 If String is NULL, then ASSERT(). 1926 If PcdMaximumAsciiStringLength is not zero, 1927 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including 1928 the Null-terminator, then ASSERT(). 1929 1930 @param String A pointer to a Null-terminated ASCII string. 1931 1932 @retval Value translated from String. 1933 1934 **/ 1935 UINT64 1936 EFIAPI 1937 AsciiStrHexToUint64 ( 1938 IN CONST CHAR8 *String 1939 ) 1940 { 1941 UINT64 Result; 1942 1943 // 1944 // ASSERT Strings is less long than PcdMaximumAsciiStringLength 1945 // 1946 ASSERT (AsciiStrSize (String) != 0); 1947 1948 // 1949 // Ignore the pad spaces (space or tab) and leading Zeros 1950 // 1951 // 1952 // Ignore the pad spaces (space or tab) 1953 // 1954 while ((*String == ' ') || (*String == '\t' )) { 1955 String++; 1956 } 1957 1958 // 1959 // Ignore leading Zeros after the spaces 1960 // 1961 while (*String == '0') { 1962 String++; 1963 } 1964 1965 if (InternalBaseLibAsciiToUpper (*String) == 'X') { 1966 ASSERT (*(String - 1) == '0'); 1967 if (*(String - 1) != '0') { 1968 return 0; 1969 } 1970 // 1971 // Skip the 'X' 1972 // 1973 String++; 1974 } 1975 1976 Result = 0; 1977 1978 while (InternalAsciiIsHexaDecimalDigitCharacter (*String)) { 1979 // 1980 // If the Hex Number represented by String overflows according 1981 // to the range defined by UINTN, then ASSERT(). 1982 // 1983 ASSERT (Result <= RShiftU64 (((UINT64) ~0) - InternalHexCharToUintn (*String) , 4)); 1984 1985 Result = LShiftU64 (Result, 4); 1986 Result = Result + InternalAsciiHexCharToUintn (*String); 1987 String++; 1988 } 1989 1990 return Result; 1991 } 1992 1993 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES 1994 1995 /** 1996 [ATTENTION] This function is deprecated for security reason. 1997 1998 Convert one Null-terminated ASCII string to a Null-terminated 1999 Unicode string and returns the Unicode string. 2000 2001 This function converts the contents of the ASCII string Source to the Unicode 2002 string Destination, and returns Destination. The function terminates the 2003 Unicode string Destination by appending a Null-terminator character at the end. 2004 The caller is responsible to make sure Destination points to a buffer with size 2005 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes. 2006 2007 If Destination is NULL, then ASSERT(). 2008 If Destination is not aligned on a 16-bit boundary, then ASSERT(). 2009 If Source is NULL, then ASSERT(). 2010 If Source and Destination overlap, then ASSERT(). 2011 If PcdMaximumAsciiStringLength is not zero, and Source contains more than 2012 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, 2013 then ASSERT(). 2014 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than 2015 PcdMaximumUnicodeStringLength ASCII characters not including the 2016 Null-terminator, then ASSERT(). 2017 2018 @param Source A pointer to a Null-terminated ASCII string. 2019 @param Destination A pointer to a Null-terminated Unicode string. 2020 2021 @return Destination. 2022 2023 **/ 2024 CHAR16 * 2025 EFIAPI 2026 AsciiStrToUnicodeStr ( 2027 IN CONST CHAR8 *Source, 2028 OUT CHAR16 *Destination 2029 ) 2030 { 2031 CHAR16 *ReturnValue; 2032 2033 ASSERT (Destination != NULL); 2034 2035 // 2036 // ASSERT Source is less long than PcdMaximumAsciiStringLength 2037 // 2038 ASSERT (AsciiStrSize (Source) != 0); 2039 2040 // 2041 // Source and Destination should not overlap 2042 // 2043 ASSERT ((UINTN) ((CHAR8 *) Destination - Source) > AsciiStrLen (Source)); 2044 ASSERT ((UINTN) (Source - (CHAR8 *) Destination) >= (AsciiStrSize (Source) * sizeof (CHAR16))); 2045 2046 2047 ReturnValue = Destination; 2048 while (*Source != '\0') { 2049 *(Destination++) = (CHAR16) *(Source++); 2050 } 2051 // 2052 // End the Destination with a NULL. 2053 // 2054 *Destination = '\0'; 2055 2056 // 2057 // ASSERT Original Destination is less long than PcdMaximumUnicodeStringLength 2058 // 2059 ASSERT (StrSize (ReturnValue) != 0); 2060 2061 return ReturnValue; 2062 } 2063 2064 #endif 2065 2066 /** 2067 Converts an 8-bit value to an 8-bit BCD value. 2068 2069 Converts the 8-bit value specified by Value to BCD. The BCD value is 2070 returned. 2071 2072 If Value >= 100, then ASSERT(). 2073 2074 @param Value The 8-bit value to convert to BCD. Range 0..99. 2075 2076 @return The BCD value. 2077 2078 **/ 2079 UINT8 2080 EFIAPI 2081 DecimalToBcd8 ( 2082 IN UINT8 Value 2083 ) 2084 { 2085 ASSERT (Value < 100); 2086 return (UINT8) (((Value / 10) << 4) | (Value % 10)); 2087 } 2088 2089 /** 2090 Converts an 8-bit BCD value to an 8-bit value. 2091 2092 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit 2093 value is returned. 2094 2095 If Value >= 0xA0, then ASSERT(). 2096 If (Value & 0x0F) >= 0x0A, then ASSERT(). 2097 2098 @param Value The 8-bit BCD value to convert to an 8-bit value. 2099 2100 @return The 8-bit value is returned. 2101 2102 **/ 2103 UINT8 2104 EFIAPI 2105 BcdToDecimal8 ( 2106 IN UINT8 Value 2107 ) 2108 { 2109 ASSERT (Value < 0xa0); 2110 ASSERT ((Value & 0xf) < 0xa); 2111 return (UINT8) ((Value >> 4) * 10 + (Value & 0xf)); 2112 } 2113
