/help/Strings.dtx
Unknown | 3950 lines | 3883 code | 67 blank | 0 comment | 0 complexity | 01a9e65177b17ca7d571de1c5b8116a5 MD5 | raw file
Possible License(s): BSD-3-Clause
Large files files are truncated, but you can click here to view the full file
1@@StringManipulation.CharacterSearchandReplace 2<GROUP StringManipulation> 3<TITLE Character Search and Replace> 4<TOPICORDER 100> 5-------------------------------------------------------------------------------- 6@@StringManipulation.CharacterTestRoutines 7<GROUP StringManipulation> 8<TITLE Character Test Routines> 9<TOPICORDER 200> 10-------------------------------------------------------------------------------- 11@@StringManipulation.CharacterTransformationRoutines 12<GROUP StringManipulation> 13<TITLE Character Transformation Routines> 14<TOPICORDER 300> 15-------------------------------------------------------------------------------- 16@@StringManipulation.Miscellaneous 17<GROUP StringManipulation> 18<TITLE Miscellaneous> 19<TOPICORDER 400> 20-------------------------------------------------------------------------------- 21@@StringManipulation.MultiSz 22<GROUP StringManipulation> 23<TITLE MultiSz> 24<TOPICORDER 500> 25-------------------------------------------------------------------------------- 26@@StringManipulation.PCharVector 27<GROUP StringManipulation> 28<TITLE PCharVector> 29<TOPICORDER 600> 30-------------------------------------------------------------------------------- 31@@StringManipulation.StringExtraction 32<GROUP StringManipulation> 33<TITLE String Extraction> 34<TOPICORDER 700> 35-------------------------------------------------------------------------------- 36@@StringManipulation.StringManagement 37<GROUP StringManipulation> 38<TITLE String Management> 39<TOPICORDER 800> 40-------------------------------------------------------------------------------- 41@@StringManipulation.StringSearchandReplaceRoutines 42<GROUP StringManipulation> 43<TITLE String Search and Replace Routines> 44<TOPICORDER 900> 45-------------------------------------------------------------------------------- 46@@StringManipulation.StringTestRoutines 47<GROUP StringManipulation> 48<TITLE String Test Routines> 49<TOPICORDER 1000> 50-------------------------------------------------------------------------------- 51@@StringManipulation.StringTransformationRoutines 52<GROUP StringManipulation> 53<TITLE String Transformation Routines> 54<TOPICORDER 1100> 55-------------------------------------------------------------------------------- 56@@StringManipulation.Tabulation 57<GROUP StringManipulation> 58<TITLE Tabulation> 59<TOPICORDER 1150> 60-------------------------------------------------------------------------------- 61@@StringManipulation.TStringsManipulation 62<GROUP StringManipulation> 63<TITLE TStrings Manipulation> 64<TOPICORDER 1200> 65-------------------------------------------------------------------------------- 66@@StrIsAlpha 67<GROUP StringManipulation.StringTestRoutines> 68Summary: 69 Tests whether S contains only alpha characters. 70Description: 71 StrIsAlpha tests whether the supplied string consists only of alpha characters. 72 That is, whether or not all individual characters come from the ['a'..'z', 'A'..'Z'] 73 set. 74Parameters: 75 S - The string to test 76Result: 77 If S contains only alpha characters the result is True, otherwise the result is False. 78Notes: 79 If S is an empty string the result is False. 80See also: 81 StrConsistsOfNumberChars 82 StrIsAlphaNum 83Donator: 84 Nick Hodges 85-------------------------------------------------------------------------------- 86@@StrIsAlphaNum 87<GROUP StringManipulation.StringTestRoutines> 88Summary: 89 Tests whether S contains only alpha-numerical characters. 90Description: 91 StrIsAlphaNum tests whether the supplied string consists only of alpha-numerical 92 characters. That is, whether or not all individual characters come from 93 the ['a'..'z', 'A'..'Z', '0'..'9'] set. 94Parameters: 95 S - The string to test 96Result: 97 If S contains only alpha-numerical characters the result is True, otherwise the result is False. 98Notes: 99 If S is an empty string the result is False. 100See also: 101 StrIsAlpha 102 StrConsistsOfNumberChars 103 StrIsAlphaNumUnderscore 104Donator: 105 Marcel van Brakel 106-------------------------------------------------------------------------------- 107@@StrIsAlphaNumUnderscore 108<GROUP StringManipulation.StringTestRoutines> 109Summary: 110 Tests whether S contains only alpha-numerical and underscore characters. 111Description: 112 StrIsAlphaNum tests whether the supplied string consists only of alpha-numerical 113 and underscore characters. That is, whether or not all individual characters come 114 from the ['a'..'z', 'A'..'Z', '0'..'9', '_'] set. 115Parameters: 116 S - The string to test 117Result: 118 If S contains only alpha-numerical and underscore characters the result is True, 119 otherwise the result is False. 120Notes: 121 If S is an empty string the result is False. 122See also: 123 StrIsAlpha 124 StrConsistsOfNumberChars 125Donator: 126 Anthony Steele 127-------------------------------------------------------------------------------- 128@@StrContainsChars 129<GROUP StringManipulation.StringTestRoutines> 130Summary: 131 Determines whether a string contains a specified set of characters. 132Description: 133 StrContainsChars checks whether the specified string contains at least one character 134 that matches one of the characters in the Chars set. If CheckAll is True, the 135 function checks whether all characters in the Chars set appear at least once in 136 the specified string. 137Parameters: 138 S - The string to test. 139 Chars - The characters for which to test. 140 CheckAll - If True, all characters from Chars must appear at least once in the specified string. If False, at least one of the characters in Chars must appear at least once in the specified string. 141Result: 142 Returns True if the condition is met, otherwise it returns False. 143Donator: 144 Petr Vones 145-------------------------------------------------------------------------------- 146@@StrIsDigit 147<GROUP StringManipulation.StringTestRoutines> 148Summary: 149 Tests whether S contains only numerical characters. 150Description: 151 StrConsistsOfNumberChars tests whether the supplied string consists only of numerical characters. 152 That is, whether or not all individual characters come from the ['0'..'9'] set. 153 The test does not include the decimal separator. To include it in the test 154 use StrConsistsOfNumberChars instead. 155Parameters: 156 S - The string to test 157Result: 158 If S contains only numerical characters the result is True, otherwise the result is False. 159Notes: 160 If S is an empty string the result is False. 161See also: 162 StrIsAlpha 163 StrIsAlphaNum 164 StrConsistsOfNumberChars 165Donator: 166 Martin Kubecka 167-------------------------------------------------------------------------------- 168@@StrConsistsOfNumberChars 169<GROUP StringManipulation.StringTestRoutines> 170Summary: 171 Tests whether S contains only numerical characters. 172Description: 173 StrConsistsOfNumberChars tests whether the supplied string consists only of numerical characters. 174 That is, whether or not all individual characters come from the ['0'..'9'] set 175 including the decimal separator. To test for numerical characters without the 176 decimal separator, use StrIsDigit instead; 177Parameters: 178 S - The string to test 179Result: 180 If S contains only numerical characters the result is True, otherwise the result is False. 181Notes: 182 If S is an empty string the result is False. 183See also: 184 StrIsAlpha 185 StrIsAlphaNum 186 StrIsDigit 187Donator: 188 Nick Hodges 189-------------------------------------------------------------------------------- 190@@StrIsSubset 191<GROUP StringManipulation.StringTestRoutines> 192Summary: 193 Tests whether S contains only characters from the supplied set. 194Description: 195 StrIsSubset tests whether the supplied string contains only characters from the 196 supplied character set. Keep in mind that the test is case-sensitive. 197Parameters: 198 S - The string to test. 199 ValidChars - The set of characters allowed in S. 200Result: 201 If the string contains only characters from the supplied set the result is True, 202 otherwise the result is False. 203Notes: 204 If the supplied string is empty, the result is always True. If the supplied character 205 set is empty, the result is always False. Empty string overules empty set. 206Donator: 207 Marcel van Brakel 208-------------------------------------------------------------------------------- 209@@StrSame 210<GROUP StringManipulation.StringTestRoutines> 211Summary: 212 Tests two strings for equality. 213Description: 214 StrSame compares the two supplied strings and returns whether or not they are 215 identical. 216Parameters: 217 S1 - First string to compare. 218 S2 - Second string to compare. 219Result: 220 If the two strings are identical the return value is True, if they are not the 221 return value is False. 222See also: 223 StrCompare 224Donator: 225 Azret Botash 226-------------------------------------------------------------------------------- 227@@StrCenter 228<GROUP StringManipulation.StringTransformationRoutines> 229Summary: 230 Centers a string. 231Description: 232 The StrCenter routine takes the specified string and pads it 233 on both the left and right side with the specified character 234 until the resulting string is of the specified length. While 235 doing this the original string is kept centered. That is, 236 there is the same amount of padding at the left side as there 237 is on the right side. 238 239 If the specified length is smaller than the length of the 240 original the string remains unchanged. In cases where an odd 241 number of padding chars have to be inserted there is always 242 one more padding char on the right side than on the left 243 side. 244Parameters: 245 C - The character to use for padding. 246 L - The desired length of the resulting string. 247 S - The string to center. 248Result: 249 Returns the centered string. 250Donator: 251 Alexander Radchenko 252-------------------------------------------------------------------------------- 253@@StrDoubleQuote 254<GROUP StringManipulation.StringTransformationRoutines> 255Summary: 256 Returns a double-quoted version of the string. 257Description: 258 StrDoubleQuote returns a copy of the string encapsulated in double quotes ("). 259 That is, if you pass in 'Project JEDI' you'll get '"Project JEDI"' back. If double 260 quotes (") are already at the beginning and the end of the string they are added again. 261 If they should be added only if they are not already there use StrQuote instead. 262Parameters: 263 S - The string to encapsulate in quotes. Even an empty string. 264Result: 265 The double-quoted version of the string. 266See also: 267 StrQuote 268 StrSingleQuote 269 StrTrimQuotes 270Donator: 271 Anthony Steele 272-------------------------------------------------------------------------------- 273@@StrEnsurePrefix 274<GROUP StringManipulation.StringTransformationRoutines> 275Summary: 276 Forces Text to start with Prefix. 277Description: 278 StrEnsurePrefix tests whether the supplied text start with the supplied prefix. 279 If it doesn't then the prefix is prepended to the string otherwise the function 280 does nothing. Note that if Text is an empty string then the result will be Prefix. 281Parameters: 282 Prefix - The prefix to test for and apply. 283 Text - The string which must be forced to have a prefix. 284Result: 285 The function result is a copy of the supplied Text, prefixed with Prefix. 286See also: 287 StrEnsureNoPrefix 288 StrEnsureSuffix 289Donator: 290 Nick Hodges 291-------------------------------------------------------------------------------- 292@@StrEnsureNoPrefix 293<GROUP StringManipulation.StringTransformationRoutines> 294Summary: 295 Eventually removes Prefix from Text. 296Description: 297 StrEnsureNoPrefix tests whether the supplied text start with the supplied prefix. 298 If it does then the prefix is deleted from the string otherwise the function 299 does nothing. 300Parameters: 301 Prefix - The prefix to test for and apply. 302 Text - The string which must not have a prefix. 303Result: 304 The function result is a copy of the supplied Text, eventually minus the prefix. 305See also: 306 StrEnsurePrefix 307 StrEnsureNoSuffix 308Donator: 309 Olivier Sannier 310-------------------------------------------------------------------------------- 311@@StrEnsureSuffix 312<GROUP StringManipulation.StringTransformationRoutines> 313Summary: 314 Forces Text to end with Suffix. 315Description: 316 StrEnsureSuffix tests whether the supplied text ends in the supplied suffix. 317 If it doesn't then the suffix is appended to the string otherwise the function 318 does nothing. Note that if Text is an empty string then the result will be Suffix. 319Parameters: 320 Suffix - The suffix to test for and apply. 321 Text - The string which must be forced to have a suffix. 322Result: 323 The function result is a copy of the supplied Text, with the suffix. 324See also: 325 StrEnsureNoSuffix 326 StrEnsurePrefix 327Donator: 328 Marcel van Brakel 329-------------------------------------------------------------------------------- 330@@StrEnsureNoSuffix 331<GROUP StringManipulation.StringTransformationRoutines> 332Summary: 333 Eventually removes Suffix from Text. 334Description: 335 StrEnsureSuffix tests whether the supplied text ends in the supplied suffix. 336 If it does then the suffix is deleted from the string otherwise the function 337 does nothing. 338Parameters: 339 Suffix - The suffix to test for and apply. 340 Text - The string which must not have a suffix. 341Result: 342 The function result is a copy of the supplied Text, eventually minus the suffix. 343See also: 344 StrEnsureSuffix 345 StrEnsureNoPrefix 346Donator: 347 Olivier Sannier 348-------------------------------------------------------------------------------- 349@@StrEscapedToString 350<GROUP StringManipulation.StringTransformationRoutines> 351Summary: 352 Converts an escaped string to a string. 353Description: 354 StrEscapedToString converts a string which contains escape characters to a string 355 without escape characters by replacing all escape characters with their string 356 counterparts. For example, a string which contains a '\a' sequence will 357 have the '\a' sequence replaced with the BELL character #7. 358 The supported escape characters are: 359 <TABLE> 360Character Value Constant Description 361--------- ----- --------- ------------------ 362\a #7 BELL Bell 363\b #8 BACKSPACE Backspace 364\f #12 FF Form Feed 365\n #10 LR Line Feed 366\r #13 CR Carrage Return 367\t #9 TAB Tabulator 368\v #11 VT Vertical Tabulator 369\\ N/A N/A Backslash 370\" N/A N/A Double quotes 371</TABLE> 372 373 In addition it supports hexadecimal escape sequences (sequences that start with \x) 374 and octal escape sequences (sequences starting with '\0', '\1' ... '\9'). 375 The StrStringToEscaped is the "inverse" of this function. 376Parameters: 377 S - The "escaped" string to convert to a "normal" string. 378Result: 379 The string with all escape characters replaced with their string counterparts. 380See also: 381 StrStringToEscaped 382Donator: 383 Robert Marquardt 384-------------------------------------------------------------------------------- 385@@StrLower 386<GROUP StringManipulation.StringTransformationRoutines> 387Summary: 388 Lowercases all characters in a string. 389Description: 390 StrLower returns a copy of the string, converted to lowercase. That is, if you pass in 'Project JEDI' you'll get 'project jedi'. 391Parameters: 392 S - String to convert to lowercase. 393See also: 394 StrLowerInPLace 395 StrLowerBuff 396 StrUpper 397 StrUpperInPlace 398 StrUpperBuff 399Donator: 400 Pelle F. S. Liljendal 401-------------------------------------------------------------------------------- 402@@StrLowerInPlace 403<GROUP StringManipulation.StringTransformationRoutines> 404Summary: 405 Lowercases all characters in a string. 406Description: 407 StrLower converts all characters in the supplied string to lowercase. 408Parameters: 409 S - String to convert to lowercase. 410See also: 411 StrLower 412 StrLowerBuff 413 StrUpper 414 StrUpperInPlace 415 StrUpperBuff 416Donator: 417 Azret Botash 418-------------------------------------------------------------------------------- 419@@StrLowerBuff 420<GROUP StringManipulation.StringTransformationRoutines> 421Summary: 422 Lowercases all characters in a string. 423Description: 424 StrLowerBuff converts all characters in the supplied string to lowercase. 425Parameters: 426 P - String to convert to lowercase. 427See also: 428 StrLower 429 StrLowerInPlace 430 StrUpper 431 StrUpperInPlace 432 StrUpperBuff 433Donator: 434 Azret Botash 435-------------------------------------------------------------------------------- 436@@StrMove 437<GROUP StringManipulation.StringTransformationRoutines> 438Summary: 439 Copies a sub-string from one string to another. 440Description: 441 StrMove copies Count characters starting at FromIndex in the source string to 442 the destination string starting at ToIndex. The function checks the passed 443 parameters and if any is illegal the function does nothing. This includes 444 illegal indices and, for example, a zero-length destination string. 445Parameters: 446 Dest - The destination string which the sub-string is copied to. 447 Source - The source string from which the sub-string is copied. 448 ToIndex - The index into the destination string at which the sub-string is copied. 449 FromIndex - The starting index into the source string from which count characters are copied. 450 Count - Length of the sub-string to copy in characters. 451Donator: 452 Azret Botash 453-------------------------------------------------------------------------------- 454@@StrPadLeft 455<GROUP StringManipulation.StringTransformationRoutines> 456Summary: 457 Left pads a string with characters. 458Description: 459 StrPadLeft left pads a string with the specified character until the resulting 460 string is Len characters long. If the source string is already greater than or 461 equal in length to Len the function does nothing. 462Parameters: 463 S - Source string to left pad. 464 Len - The length of the resulting string. 465 C - The character to pad the string with. 466Result: 467 The string left padded with the specified character. 468See also: 469 StrPadRight 470 StrCenter 471Donator: 472 Marcel van Brakel 473-------------------------------------------------------------------------------- 474@@StrPadRight 475<GROUP StringManipulation.StringTransformationRoutines> 476Summary: 477 Right pads a string with characters. 478Description: 479 StrPadRight right pads a string with the specified character until the resulting 480 string is Len characters long. If the source string is already greater than or equal 481 in length to Len the function does nothing. 482Parameters: 483 S - Source string to right pad. 484 Len - The length of the resulting string. 485 C - The character to pad the string with. 486Result: 487 The string right padded with the specified character. 488See also: 489 StrPadLeft 490 StrCenter 491Donator: 492 Marcel van Brakel 493-------------------------------------------------------------------------------- 494@@StrProper 495<GROUP StringManipulation.StringTransformationRoutines> 496Summary: 497 Lowercases the supplied string and uppercases the first character. 498Description: 499 The StrProper routine lowercases the entire string and subsequently uppercases 500 the first character. 501Parameters: 502 S - The string to transform. 503Result: 504 The transformed string. 505Donator: 506 Azret Botash 507-------------------------------------------------------------------------------- 508@@StrProperBuff 509<GROUP StringManipulation.StringTransformationRoutines> 510Summary: 511 Lowercases the supplied string and uppercases the first character. 512Description: 513 The StrProper routine lowercases the entire string and subsequently uppercases 514 the first character. 515Parameters: 516 S - The string to transform. 517Donator: 518 Azret Botash 519-------------------------------------------------------------------------------- 520@@StrQuote 521<GROUP StringManipulation.StringTransformationRoutines> 522Summary: 523 Quotes a string with a specific character. 524Description: 525 StrQuote quotes the string with a specified character. Upon return the string is 526 guarenteed to begin and end with the specified character. Note that if the string 527 already starts or ends with this character, it is not added again. 528Parameters: 529 S - The string to quote. 530 C - The character with which to quote the string. 531Result: 532 The quoted string. 533Donator: 534 Azret Botash 535-------------------------------------------------------------------------------- 536@@StrRemoveChars 537<GROUP StringManipulation.StringTransformationRoutines> 538Summary: 539 Removes a set of characters from a string. 540Description: 541 StrRemoveChars removes all instances of the characters in the set from the source 542 string. For example, if you pass in 'Joint Endeavour of Delphi Innovators' and 543 specify ['e', 'a', 'o', 'u', 'i'] the resulting string will be 'Jnt Endvr f Dlph Innvtrs'. 544Parameters: 545 S - The source string from which to remove the characters. 546 Chars - The set of characters which are removed from S. 547Result: 548 The string with all characters from the supplied set removed. 549Notes: 550 The function is case sensitive. That is, specifying 'e' will not remove 'E'. 551Donator: 552 Marcel van Brakel 553-------------------------------------------------------------------------------- 554@@StrRepeat 555<GROUP StringManipulation.StringTransformationRoutines> 556Summary: 557 Repeats a string Count number of times. 558Description: 559 The StrRepeat routine returns a string consisting of the specified string, repeated 560 Count number of times. For example, StrRepeat('He', 3) returns 'HeHeHe'. 561Parameters: 562 S - The string to repeat. 563 Count - The number of times to repeat the specified string. 564Result: 565 The specified string, repeated Count number of times. 566Donator: 567 Marcel van Brakel 568-------------------------------------------------------------------------------- 569@@StrReverse 570<GROUP StringManipulation.StringTransformationRoutines> 571Summary: 572 Reverses a string. 573Description: 574 StrReverse returns a reversed copy of S. That is, if you pass in 'Delphi' the 575 function result will be 'ihpleD'. Note that the original string remains unmodified, 576 as the const modifier indicates. If you don't need the original string after 577 reversing it, then do not write code like S := StrReverse(S) but instead use 578 the StrReverseInPlace function because it's much faster. 579Parameters: 580 S - The string to reverse. 581Result: 582 A reversed copy of the supplied string. 583See also: 584 StrReverseInPlace 585Donator: 586 Marcel van Brakel 587-------------------------------------------------------------------------------- 588@@StrReverseInPlace 589<GROUP StringManipulation.StringTransformationRoutines> 590Summary: 591 Reverses a string. 592Description: 593 StrReverse reverses S. That is, if you pass in 'Delphi' then after the function 594 returns S contains the string 'ihpleD'. If you need to retain the original 595 string then use the StrReverse function instead. 596Parameters: 597 S - The string to reverse. 598See also: 599 StrReverse 600Donator: 601 Marcel van Brakel 602-------------------------------------------------------------------------------- 603@@StrSingleQuote 604<GROUP StringManipulation.StringTransformationRoutines> 605Summary: 606 Returns a single-quoted version of the string. 607Description: 608 StrSingleQuote returns a copy of the string encapsulated in single quotes ('). 609 That is, if you pass in 'Project JEDI' you'll get ''Project JEDI'' back. 610Parameters: 611 S - The string to encapsulate in quotes. Even an empty string. 612Result: 613 The single-quoted version of the string. 614See also: 615 StrDoubleQuote 616 StrTrimQuotes 617Donator: 618 Anthony Steele 619-------------------------------------------------------------------------------- 620@@StrSmartCase 621<GROUP StringManipulation.StringTransformationRoutines> 622Summary: 623 Converts a string to 'smartcase' or 'camelcase'. 624Description: 625 StrSmartCase converts specified characters within the supplied source string to 626 uppercase. The characters that are uppercased are determined by the Delimiters 627 character set. Each time the function finds a character in the source string that 628 is also present in the Delimiters set it uppercases the next character 629 in the source string. In addition, the function always converts the first character 630 to uppercase. For example, if you call StrSmartCase('project jedi rules', [' ']) 631 the function returns 'Project Jedi Rules'. As you can see, all characters that 632 immediately follow a space (as specified by Delimiters) are uppercased. 633Parameters: 634 S - Source string. 635 Delimiters - Set of characters to use as delimiters. These characters determine which other 636 characters are uppercased. If you supply an empty set the function assumes you want to use a 637 space only. That is, it sets Delimiters to [' ']. 638Result: 639 The string converted to smart case. 640Notes: 641 Original author is John C Molyneux (jaymol@hotmail.com). Function was rewritten by 642 Marcel van Brakel. 643Donator: 644 Marcel van Brakel 645-------------------------------------------------------------------------------- 646@@StrStringToEscaped 647<GROUP StringManipulation.StringTransformationRoutines> 648Summary: 649 Converts a string to an escaped string. 650Description: 651 StrStringToEscaped converts a string to an escaped string by replacing non-visual 652 character sequences with their escape characters. For example, if a string contains 653 the character #7 the resulting string will have the #7 character replaced with the '\a' 654 sequence. This function is the inverse of StrEscapedToString. 655 The function supports the following escape characters: 656 <TABLE> 657Character Value Constant Description 658--------- ----- --------- ------------------ 659\a #7 BELL Bell 660\b #8 BACKSPACE Backspace 661\f #12 FF Form Feed 662\n #10 LR Line Feed 663\r #13 CR Carrage Return 664\t #9 TAB Tabulator 665\v #11 VT Vertical Tabulator 666\\ N/A N/A Backslash 667\" N/A N/A Double quotes 668</TABLE> 669 670 All other characters whose ordinal value are smaller than Ord(' ') are escaped 671 as a hexadecimal sequence like '\x01'. The StrEscapedToString is the "inverse" 672 of this function. 673Parameters: 674 S - The string to convert to an escaped string. 675Result: 676 The "escaped" string. 677See also: 678 StrEscapedToString 679Donator: 680 Robert Marquardt 681-------------------------------------------------------------------------------- 682@@StrStripNonNumberChars 683<GROUP StringManipulation.StringTransformationRoutines> 684Summary: 685 Removes all non-number characters from a string. 686Description: 687 StrStripNonNumberChars removes all non-number characters from the specified string. 688 Hence the resulting string will contain only number characters. Testing whether 689 the individual characters are numbers is done using the CharIsNumberChar routine and 690 therefore characters that qualify are all digits (0..9), signs (+, -) and decimal 691 separators. 692Parameters: 693 S - The string from which to remove non-number characters. 694Result: 695 The string after all non-number characters are removed. 696Donator: 697 Anthony Steele 698-------------------------------------------------------------------------------- 699@@StrTrimQuotes 700<GROUP StringManipulation.StringTransformationRoutines> 701Summary: 702 Removes surrounding quotes from the supplied string. 703Description: 704 StrTrimQuotes removes surrounding quotes, either single or double-quotes, from 705 the string. For example if you pass in ''Project JEDI'' you'll get 'Project JEDI' 706 back. Note that this function only removes quotes if the string both begins and 707 ends with the same quote character. 708Parameters: 709 S - The string to unquote. 710Result: 711 The unquoted string. 712See also: 713 StrSingleQuote 714 StrDoubleQuote 715Donator: 716 Anthony Steele 717-------------------------------------------------------------------------------- 718@@StrToHex 719<GROUP StringManipulation.StringTransformationRoutines> 720Summary: 721 Converts a string of hex digit pairs to the corresponding bytes. 722Description: 723 The Source string is expected to contain pairs of hex digit 724 characters ['0'..'9', 'a'..'f', 'A'..'F']. Each pair is converted to a single 725 byte thus converting '40' to '@'. Any character not from the hex set 726 results in an empty string. If the string length of the Source is odd 727 then a '0' is prepended internally to make up the first byte. 728Parameters: 729 S - A string of hex digit pairs to be converted. 730Result: 731 The string of converted bytes. 732Donator: 733 Azret Botash 734-------------------------------------------------------------------------------- 735@@StrTrimCharLeft 736<GROUP StringManipulation.StringTransformationRoutines> 737Summary: 738 Removes leading characters from a string. 739Description: 740 The StrTrimCharLeft routine removes leading characters from the specified string. 741 For example, StrTrimCharLeft('000123', '0') returns '123'. 742Parameters: 743 S - The source string from which the leading characters need to be removed. 744 C - The character to remove. 745Result: 746 The function returns the source string S without any leading characters C. 747See also: 748 StrTrimCharRight 749Donator: 750 Jack N.A. Bakker 751-------------------------------------------------------------------------------- 752@@StrTrimCharRight 753<GROUP StringManipulation.StringTransformationRoutines> 754Summary: 755 Removes trailing characters from a string. 756Description: 757 The StrTrimCharRight routine removes trailing characters from the specified string. 758 For example, StrTrimCharRight('123000', '0') returns '123'. 759Parameters: 760 S - The source string from which the trailing characters need to be removed. 761 C - The character to remove. 762Result: 763 The function returns the source string S without any trailing characters C. 764See also: 765 StrTrimCharLeft 766Donator: 767 Jack N.A. Bakker 768-------------------------------------------------------------------------------- 769@@StrUpper 770<GROUP StringManipulation.StringTransformationRoutines> 771Summary: 772 Uppercases all characters in a string 773Description: 774 StrUpper returns a copy of the string, converted to uppercase. That is, if you pass 775 in 'Project JEDI' you'll get 'PROJECT JEDI'. 776Parameters: 777 S - String to convert to uppercase. 778See also: 779 StrUpperInPlace 780 StrUpperBuff 781 StrLower 782 StrLowerInPlace 783 StrLowerBuff 784Donator: 785 Azret Botash 786-------------------------------------------------------------------------------- 787@@StrUpperInPlace 788<GROUP StringManipulation.StringTransformationRoutines> 789Summary: 790 Uppercases all characters in a string. 791Description: 792 StrUpper converts all characters in the supplied string to uppercase. 793Parameters: 794 S - String to convert to uppercase. 795See also: 796 StrUpper 797 StrUpperBuff 798 StrLower 799 StrLowerInPlace 800 StrLowerBuff 801Donator: 802 Azret Botash 803-------------------------------------------------------------------------------- 804@@StrUpperBuff 805<GROUP StringManipulation.StringTransformationRoutines> 806Summary: 807 Uppercases all characters in a string. 808Description: 809 StrUpper converts all characters in the supplied string to uppercase. 810Parameters: 811 S - String to convert to uppercase. 812See also: 813 StrUpper 814 StrUpperInPlace 815 StrLower 816 StrLowerInPlace 817 StrLowerBuff 818Donator: 819 Azret Botash 820-------------------------------------------------------------------------------- 821@@StrAddRef 822<GROUP StringManipulation.StringManagement> 823Summary: 824 Increments the reference count of a long string. 825Description: 826 The StrAddRef routine increments the reference count of the specified long string. 827 Explicitly incrementing a strings reference count forces Delphi to keep the string 828 in memory even if the variable itself goes out of scope and all other references 829 were removed already. Note that if the string points to a string constant this 830 routine will call UniqueString on it forcing a string copy, after which the 831 reference count becomes 1. 832Parameters: 833 S - The long string whose reference count to increment. 834See also: 835 StrDecRef 836Donator: 837 Marcel van Brakel 838-------------------------------------------------------------------------------- 839@@StrAllocSize 840<GROUP StringManipulation.StringManagement> 841Summary: 842 Returns the memory allocated to store the string. 843Description: 844 A long string variable is a 4 byte pointer to a dynamically allocated block of 845 memory. This block of memory holds the actual string data, including a NULL 846 character. In addition this block of memory has, at a negative offset, a number 847 of 32 bit values used to manage the string. The StringAllocSize function looks 848 at this negative offset to determine the total amount of dynamic memory reserved 849 to hold the string and management data. 850 Note that this function will always return 0 for string literals, string constants 851 and string variables that are assigned to string constants, but haven't been 852 modified yet. This is not a bug but a result of the way in which Delphi manages 853 string constants. 854Parameters: 855 S - The string for which to determine the total amount of used memory. 856Result: 857 The amount of dynamic memory allocated for the string or 0 in the exceptions noted 858 above. Note that, at least in Delphi 5, the result will always be a multiple of 4. 859Notes: 860 This function relies on pseudo-undocumented knowledge and should only be used for 861 debugging purposes. 862See also: 863 StrRefCount 864Donator: 865 Marcel van Brakel 866-------------------------------------------------------------------------------- 867@@StrDecRef 868<GROUP StringManipulation.StringManagement> 869Summary: 870 Decrements the reference count of a long string. 871Description: 872 The StrDecRef routine decrements the reference count of the specified long string. 873 Note that if decrementing the reference count will set it to 0 the string is 874 released and the string pointer is set to nil. Therefore the string may be 875 inaccessible after calling this routine. 876Parameters: 877 S - The long string whose reference count to increment. Upon return the string may 878 have been freed. 879See also: 880 StrDecRef 881Donator: 882 Marcel van Brakel 883-------------------------------------------------------------------------------- 884@@StrLen 885<GROUP StringManipulation.StringManagement> 886Summary: 887 Returns the length of the supplied string. 888Description: 889 StrLen returns the length of the supplied string, in characters, excluding the 890 null terminating character. This function is identical to the StrLen routine from 891 SysUtils.pas except that it is much faster. 892Parameters: 893 S - Pointer to the null terminated string for which to determine the length. 894Result: 895 The length of the string, in characters. 896Donator: 897 Robert Lee 898-------------------------------------------------------------------------------- 899@@StrLength 900<GROUP StringManipulation.StringManagement> 901Summary: 902 Returns the length of the supplied string. 903Description: 904 StrLength returns the length of the supplied string. This is a duplication of the 905 standard Delphi Length function and is only supplied for completeness. You should 906 prefer the Length function over StrLength. 907Parameters: 908 S - The string for which to determine the length. 909Result: 910 The length of the string in characters. 911Notes: 912 This function relies on pseudo undocumented knowledge. 913See also: 914 StrAllocSize 915 StrRefCount 916Donator: 917 Marcel van Brakel 918-------------------------------------------------------------------------------- 919@@StrRefCount 920<GROUP StringManipulation.StringManagement> 921Summary: 922 Returns the reference count of the supplied string. 923Description: 924 StrRefCount returns the reference count of the string. Note that this function 925 will always return -1 for string literals, string constants and string variables 926 that are assigned to string constants, but haven't been modified yet. This is 927 not a bug but a result of the way in which Delphi manages string constants. 928Parameters: 929 S - String for which to determine the reference count. 930Result: 931 The reference count of the string or -1 if the string ultimately points to a 932 string constant. 933Notes: 934 This function relies on pseudo-undocumented knowledge and should only be used for 935 debugging purposes. 936See also: 937 StrAllocSize 938Donator: 939 Marcel van Brakel 940-------------------------------------------------------------------------------- 941@@StrResetLength 942<GROUP StringManipulation.StringManagement> 943Summary: 944 Resets the length of the supplied string. 945Description: 946 StrResetLength resets the length of the string to encompass only the actual number 947 of used characters. This is particularly useful when passing strings to API 948 functions which accept PChar's. These kind of functions do modify the string but 949 since they are unaware of how Delphi manages strings, the length is not changed 950 on return. Depending on how you use the string from that point on the results 951 may be incorrect if you do not apply StrResetLength. 952 The function resets the length to the C string length, i. e. the length up to the first #0 byte. 953Parameters: 954 S - The string whose length to reset. 955Donator: 956 Marcel van Brakel 957-------------------------------------------------------------------------------- 958@@StrCharCount 959<GROUP StringManipulation.StringSearchandReplaceRoutines> 960Summary: 961 Counts the occurrences of a character in a string. 962Description: 963 StrCharCount returns the number of occurrences of the specified character in the 964 supplied string. 965Parameters: 966 S - Source string. 967 C - The character whose occurrences to count. 968Result: 969 The number of occurrences of C in S. 970Donator: 971 Massimo Maria Ghisalberti 972-------------------------------------------------------------------------------- 973@@StrCompare 974<GROUP StringManipulation.StringTestRoutines> 975Summary: 976 Compares two strings. 977Description: 978 StrCompare implements a case-insensitive comparison between the two supplied 979 strings. If the two strings match the function returns 0 otherwise it returns 980 the number of different characters. If the supplied strings are of equal length 981 but are not identical the function returns the difference of the first mismatched 982 character. The table below demonstrates this: 983 <TABLE> 984S1 S2 Result 985------------ ------------ ------------------------------ 986jedi jedi 0 987jedi je 2 988di jedi -2 989project jedi jedi 8 990jedi project jedi -8 991jedi judi Ord('e') - Ord('u') 992JEDI Judi Ord(LowerCase('E')) - Ord('u') 993</TABLE> 994 995Parameters: 996 S1 - First string to compare. 997 S2 - Second string to compare. 998Result: 999 StrCompare returns 0 if the two strings match or the number of different characters 1000 in case of a mismatch. 1001Donator: 1002 Azret Botash 1003-------------------------------------------------------------------------------- 1004@@StrCompareRange 1005<GROUP StringManipulation.StringSearchandReplaceRoutines> 1006Description: 1007 StrCompareRange compares, case-sensitive, a sub-string from the 1008 first supplied string with the second string. If the two 1009 strings are identical the function returns 0 otherwise it 1010 returns an indication of difference between the two strings, 1011 The result is equal to the result returned by StrCompare. This 1012 function is particularly useful to avoid code such as: "if 1013 Copy(S, 1, 4) = 'JEDI' then ..." which is quite inefficient. 1014 This code would be rewritten to: "if StrCompareRange(S1, 1015 'JEDI', 1, 4) = 0 then ...". 1016Summary: 1017 Compares two (sub) strings. 1018Parameters: 1019 Count - Number of characters of the sub-string in S1 to compare to S2. 1020 Index - Starting index of sub-string in S1 to. 1021 S1 - First string to compare. 1022 S2 - Second string to compare. 1023Result: 1024 StrCompareRange returns 0 if the two strings match or the 1025 number of different characters in case of a mismatch. 1026See also: 1027 StrCompare 1028Donator: 1029 Azret Botash 1030-------------------------------------------------------------------------------- 1031@@StrFillChar 1032<GROUP StringManipulation.StringSearchandReplaceRoutines> 1033Summary: 1034 Creates a string consisting of the specified character repeated Count times. 1035Description: 1036 The StrFillChar routine returns a string consisting of the specified character 1037 repeated Count number of times. 1038Parameters: 1039 C - The character to repeat. 1040 Count - The number of times to repeat the character. 1041Result: 1042 A string consisting of the specified character repeated Count times. 1043Donator: 1044 Marcel van Brakel 1045-------------------------------------------------------------------------------- 1046@@StrFind 1047<GROUP StringManipulation.StringSearchandReplaceRoutines> 1048Summary: 1049 Returns the index of the first character in a specified sub-string that occurs in a given string. 1050Description: 1051 StrFind returns the index of the first character in a specified sub-string that 1052 occurs in a given string. The search starts at the supplied index and is case-insensitive. 1053Parameters: 1054 Substr - The sub-string to search for. 1055 Str - The string in which to search. 1056 Index - The index in Str at which to start the search. 1057Result: 1058 One-based index of the first character of SubStr in Str or 0 if SubStr does not 1059 occur in the supplied string. 1060See also: 1061 StrSearch 1062Donator: 1063 Azret Botash 1064-------------------------------------------------------------------------------- 1065@@StrHasPrefix 1066<GROUP StringManipulation.StringSearchandReplaceRoutines> 1067Summary: 1068 Returns whether a string is prefixed by one of the supplied strings. 1069Description: 1070 StrHasPrefix returns whether the string is prefixed with at least one of the strings 1071 supplied in the Prefixes array. In other words, for each string in the Prefixes 1072 array it's determined if the supplied string starts with that prefix. Note that 1073 the routine exits as soon as a match is found and matching is case-sensitive (use 1074 StrIHasPrefix for a case-insensitive matching version). 1075Parameters: 1076 S - The string to test. 1077 Prefixes - Array of prefixes to test for. 1078Result: 1079 If the supplied string is prefixed with one of the supplied prefixes the routine 1080 returns True, otherwise it returns False. 1081See also: 1082 StrIHasPrefix, StrPrefixIndex 1083Donator: 1084 Anthony Steele 1085-------------------------------------------------------------------------------- 1086@@StrIHasPrefix 1087<GROUP StringManipulation.StringSearchandReplaceRoutines> 1088Summary: 1089 Returns whether a string is prefixed by one of the supplied strings. 1090Description: 1091 StrHasPrefix returns whether the string is prefixed with at least one of the strings 1092 supplied in the Prefixes array. In other words, for each string in the Prefixes 1093 array it's determined if the supplied string starts with that prefix. Note that 1094 the routine exits as soon as a match is found and matching is case-insensitive (use 1095 StrHasPrefix for a case-sensitive matching version). 1096Parameters: 1097 S - The string to test. 1098 Prefixes - Array of prefixes to test for. 1099Result: 1100 If the supplied string is prefixed with one of the supplied prefixes the routine 1101 returns True, otherwise it returns False. 1102See also: 1103 StrHasPrefix, StrIPrefixIndex 1104Donator: 1105 Anthony Steele 1106-------------------------------------------------------------------------------- 1107@@StrIndex 1108<GROUP StringManipulation.StringSearchandReplaceRoutines> 1109Summary: 1110 Returns the index of a string in an array of strings. 1111Description: 1112 StrIndex returns the index into the List array at which S is positioned. This is 1113 particularly useful to create a case statement based on string labels. For example: 1114 1115 case StrIndex(S, ['zero', 'one', 'two']) of 1116 0: // handle case where S = 'zero' 1117 1: // handle case where S = 'one' 1118 2: // handle case where S = 'two' 1119 else 1120 // 1121 end; 1122 1123Parameters: 1124 S - The string to test. 1125 List - Array of strings to search in. 1126Result: 1127 If the supplied string exists in the List array the zero based index of the position 1128 at which it appears is returned. If the string doesn't exist in the array -1 is 1129 returned. Note that the string comparison is case insensitive but is based on the 1130 current locale (ie it uses AnsiSameText). 1131Donator: 1132 Anthony Steele 1133-------------------------------------------------------------------------------- 1134@@StrILastPos 1135<GROUP StringManipulation.StringSearchandReplaceRoutines> 1136Summary: 1137 Returns the index of the last occurrence of SubStr in S. 1138Description: 1139 StrILastPos scans the supplied string and returns the index of the first character 1140 of the last occurrence of the supplied sub-string. The comparison is case-insensitive. 1141Parameters: 1142 SubStr - The sub-string to find the last occurrence of. 1143 S - The string in which to search. 1144Result: 1145 The index of the last occurrence of SubStr in S. If the sub-string does not exist 1146 at all the result is 0. 1147See also: 1148 StrLastPos 1149Donator: 1150 Anthony Steele 1151-------------------------------------------------------------------------------- 1152@@StrLastPos 1153<GROUP StringManipulation.StringSearchandReplaceRoutines> 1154Summary: 1155 Returns the index of the last occurrence of SubStr in S. 1156Description: 1157 StrLastPos scans the supplied string and returns the index of the first character 1158 of the last occurrence of the supplied sub-string. The comparison is case-sensitive. 1159Parameters: 1160 SubStr - The sub-string to find the last occurrence of. 1161 S - The string in which to search. 1162Result: 1163 The index of the last occurrence of SubStr in S. If the sub-string does not exist 1164 at all the result is 0. 1165See also: 1166 StrILastPos 1167Donator: 1168 Marcel van Brakel 1169-------------------------------------------------------------------------------- 1170@@StrIPos 1171<GROUP StringManipulation.StringSearchandReplaceRoutines> 1172Summary: 1173 Returns the index of the first occurrence of SubStr in S. 1174Description: 1175 StrIPos scans the supplied string and returns the index of the first character 1176 of the first occurrence of the supplied sub-string. The comparison is case-insensitive. 1177Parameters: 1178 SubStr - The sub-string to find the first occurrence of. 1179 S - The string in which to search. 1180Result: 1181 The index of the first occurrence of SubStr in S. If the sub-string does not exist 1182 at all the result is 0. 1183Donator: 1184 Anthony Steele 1185-------------------------------------------------------------------------------- 1186@@StrIPrefixIndex 1187<GROUP StringManipulation.StringSearchandReplaceRoutines> 1188Summary: 1189 Returns the index at which a string appears which is used as a prefix. 1190Description: 1191 StrPrefixIndex returns the index into the prefixes array at which a string appears 1192 with which the supplied string is prefixed. For example, 1193 StrPrefixIndex('banana', ['call', 'ban', 'bana']) will return 1. Note that as 1194 can be seen from the example, as soon as a prefix is found the routine stops and 1195 doesn't attempt to find a better (longer) match. Matching is case-insensitive; use 1196 StrPrefixIndex for a case-insensitive version. 1197Parameters: 1198 S - The string to test. 1199 Prefixes - The list of prefixes. 1200Result: 1201 The zero based index into Prefixes at which the first string appears that is used 1202 as a prefix in the supplied string. If none of the Prefixes array strings qualifies 1203 the result is -1. 1204See Also 1205 StrIHasPrefix, StrPrefixIndex 1206Donator: 1207 Anthony Steele 1208-------------------------------------------------------------------------------- 1209@@StrIsOneOf 1210<GROUP StringManipulation.StringSearchandReplaceRoutines> 1211Summary: 1212 Tests whether the supplied string exists in the list of strings. 1213Description: 1214 StrIsOneOf tests whether the supplied string exists in the list of strings. Note 1215 that the comparison is case-insensitive. 1216Parameters: 1217 S - The string to test. 1218 List - The list of string in which to search. 1219Result: 1220 If the string exists in the supplied list the result is True, otherwise it's False. 1221Donator: 1222 Anthony Steele 1223-------------------------------------------------------------------------------- 1224@@StrNPos 1225<GROUP StringManipulation.StringSearchandReplaceRoutines> 1226Summary: 1227 Returns the position of the N-th occurence of a sub-string within a string. 1228Description: 1229 StrNPos returns the index into S of the N-th occurence of the specified sub-string. 1230 This function is case-sensitive and does not work with multibyte character sets. 1231 If the specified sub-string does not have N occurence in S the function returns 0. 1232Parameters: 1233 S - The string in which to search for N occurences of SubStr. 1234 SubStr - The sub-string to search for. 1235 Index - The number of occurences of sub-string in S. 1236Result: 1237 Index into S where the N-th occurence of SubStr is located. If SubStr has less 1238 than N occurences in S the result is 0. 1239Notes: 1240 This function was inspired by code submitted by George Tasker 1241See also: 1242 StrNIPos 1243Donator: 1244 Team JCL 1245-------------------------------------------------------------------------------- 1246@@StrNIPos 1247<GROUP StringManipulation.StringSearchandReplaceRoutines> 1248Summary: 1249 Returns the position of the N-th occurence of a sub-string within a string. 1250Description: 1251 StrNPos returns the index into S of the N-th occurence of the specified sub-string. 1252 This function is case-insensitive and does not work with multibyte character sets. 1253 If the specified sub-string does not have N occurence in S the function returns 0. 1254Parameters: 1255 S - The string in which to search for N occurences of SubStr. 1256 SubStr - The sub-string to search for. 1257 N - The number of occurences of sub-string in S. 1258Result: 1259 Index into S where the N-th occurence of SubStr is located. If SubStr has less 1260 than N occurences in S the result is 0. 1261Notes: 1262 This function was inspired by code submitted by George Tasker 1263See also: 1264 StrNPos 1265Donator: 1266 Team JCL 1267-------------------------------------------------------------------------------- 1268@@StrMatch 1269<GROUP StringManipulation.StringSearchandReplaceRoutines> 1270Summary: 1271 Returns the index of the first character in a specified sub-string that occurs in a given string. 1272Description: 1273 StrMatch returns the index of the first character in a specified sub-string that 1274 occurs in a given string. The search starts at the supplied index and is case-insensitive. 1275 The specified sub-string may contain wildcards. The '?' wildcard matches 1 character 1276 while the '*' wildcard matches 0 or more occurrences of a character. For example, 'J?DI' 1277 will find 'JEDI', 'JZDI' and 'JODI' (and more) while 'J*I' will find 'JEDI' and 'JI'. 1278Parameters: 1279 Substr - The sub-string to search for. May contain wildcards. 1280 Str - The string in which to search. 1281 Index - The index in Str at which to start the search. 1282Result: 1283 One-based index of the first character of SubStr in Str or 0 if SubStr does not 1284 occur in the supplied string. 1285Notes: 1286 The '*' wildcard currently doesn't work correctly, it produces the same result as '?'. 1287See also: 1288 StrSearch 1289Donator: 1290 Azret Botash 1291-------------------------------------------------------------------------------- 1292@@StrPrefixIndex 1293<GROUP StringManipulation.StringSearchandReplaceRoutines> 1294Summary: 1295 Returns the index at which a string appears which is used as a prefix. 1296Description: 1297 StrPrefixIndex returns the index into the prefixes array at which a string appears 1298 with which the supplied string is prefixed. F…
Large files files are truncated, but you can click here to view the full file