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