string(3,n)(n) Tcl Built-In Commands string(3,n)(n) NAME string(3,n) - Manipulate strings SYNOPSIS string(3,n) option arg ?arg ...? DESCRIPTION Performs one of several string(3,n) operations, depending on option. The legal options (which may be abbreviated) are: string(3,n) bytelength string(3,n) Returns a decimal string(3,n) giving the number of bytes used to rep- resent string(3,n) in(1,8) memory. Because UTF-8 uses one to three bytes to represent Unicode characters, the byte length will not be the same as the character length in(1,8) general. The cases where a script cares about the byte length are rare. In almost all cases, you should use the string(3,n) length operation (including determining the length of a Tcl ByteArray object). Refer to the Tcl_NumUtfChars manual entry for more details on the UTF-8 rep- resentation. string(3,n) compare ?-nocase? ?-length int? string1 string2 Perform a character-by-character comparison of strings string1 and string2. Returns -1, 0, or 1, depending on whether string1 is lexicographically less(1,3) than, equal to, or greater than string2. If -length is specified, then only the first length characters are used in(1,8) the comparison. If -length is negative, it is ignored. If -nocase is specified, then the strings are compared in(1,8) a case-insensitive manner. string(3,n) equal ?-nocase? ?-length int? string1 string2 Perform a character-by-character comparison of strings string1 and string2. Returns 1 if(3,n) string1 and string2 are identical, or 0 when not. If -length is specified, then only the first length characters are used in(1,8) the comparison. If -length is negative, it is ignored. If -nocase is specified, then the strings are compared in(1,8) a case-insensitive manner. string(3,n) first string1 string2 ?startIndex? Search string2 for a sequence of characters that exactly match the characters in(1,8) string1. If found, return the index of the first character in(1,8) the first such match within string2. If not found, return -1. If startIndex is specified (in(1,8) any of the forms accepted by the index method), then the search is con- strained to start with the character in(1,8) string2 specified by the index. For example, string(3,n) first a 0a23456789abcdef 5 will return 10, but string(3,n) first a 0123456789abcdef 11 will return -1. string(3,n) index string(3,n) charIndex Returns the charIndex'th character of the string(3,n) argument. A charIndex of 0 corresponds to the first character of the string. charIndex may be specified as follows: integer The char specified at this integral index. end The last char of the string. end-integer The last char of the string(3,n) minus the specified inte- ger offset (e.g. end-1 would refer to the "c" in(1,8) "abcd"). If charIndex is less(1,3) than 0 or greater than or equal to the length of the string(3,n) then an empty string(3,n) is returned. string(3,n) is class ?-strict? ?-failindex varname? string(3,n) Returns 1 if(3,n) string(3,n) is a valid member of the specified character class, otherwise returns 0. If -strict is specified, then an empty string(3,n) returns 0, otherwise and empty string(3,n) will return 1 on any class. If -failindex is specified, then if(3,n) the function returns 0, the index in(1,8) the string(3,n) where the class was no longer valid will be stored in(1,8) the variable named(5,8) varname. The varname will not be set(7,n,1 builtins) if(3,n) the function returns 1. The following char- acter classes are recognized (the class name can be abbrevi- ated): alnum Any Unicode alphabet or digit character. alpha Any Unicode alphabet character. ascii(1,7) Any character with a value less(1,3) than \u0080 (those that are in(1,8) the 7-bit ascii(1,7) range). boolean Any of the forms allowed to Tcl_GetBoolean. control Any Unicode control character. digit Any Unicode digit character. Note that this includes characters outside of the [0-9] range. double Any of the valid forms for a double in(1,8) Tcl, with optional surrounding whitespace. In case of under/overflow in(1,8) the value, 0 is returned and the varname will contain -1. false Any of the forms allowed to Tcl_GetBoolean where the value is false. graph Any Unicode printing character, except space. integer Any of the valid forms for a 32-bit integer in(1,8) Tcl, with optional surrounding whitespace. In case of under/overflow in(1,8) the value, 0 is returned and the varname will contain -1. lower Any Unicode lower case alphabet character. print Any Unicode printing character, including space. punct Any Unicode punctuation character. space Any Unicode space character. true Any of the forms allowed to Tcl_GetBoolean where the value is true. upper Any upper case alphabet character in(1,8) the Unicode char- acter set. wordchar Any Unicode word character. That is any alphanumeric character, and any Unicode connector punctuation char- acters (e.g. underscore). xdigit Any hexadecimal digit character ([0-9A-Fa-f]). In the case of boolean, true and false, if(3,n) the function will return 0, then the varname will always be set(7,n,1 builtins) to 0, due to the varied nature of a valid boolean value. string(3,n) last string1 string2 ?lastIndex? Search string2 for a sequence of characters that exactly match the characters in(1,8) string1. If found, return the index of the first character in(1,8) the last such match within string2. If there is no match, then return -1. If lastIndex is specified (in(1,8) any of the forms accepted by the index method), then only the char- acters in(1,8) string2 at or before the specified lastIndex will be considered by the search. For example, string(3,n) last a 0a23456789abcdef 15 will return 10, but string(3,n) last a 0a23456789abcdef 9 will return 1. string(3,n) length string(3,n) Returns a decimal string(3,n) giving the number of characters in(1,8) string(3,n). Note that this is not necessarily the same as the num- ber of bytes used to store the string. If the object is a ByteArray object (such as those returned from reading a binary encoded channel), then this will return the actual byte length of the object. string(3,n) map ?-nocase? charMap string(3,n) Replaces characters in(1,8) string(3,n) based on the key-value pairs in(1,8) charMap. charMap is a list of key value key value ... as in(1,8) the form returned by array get. Each instance of a key in(1,8) the string(3,n) will be replaced with its corresponding value. If -nocase is specified, then matching is done without regard to case differences. Both key and value may be multiple characters. Replacement is done in(1,8) an ordered manner, so the key appearing first in(1,8) the list will be checked first, and so on. string(3,n) is only iterated over once, so earlier key replacements will have no affect for later key matches. For example, string(3,n) map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc will return the string(3,n) 01321221. string(3,n) match ?-nocase? pattern string(3,n) See if(3,n) pattern matches string(3,n); return 1 if(3,n) it does, 0 if(3,n) it doesn't. If -nocase is specified, then the pattern attempts to match against the string(3,n) in(1,8) a case insensitive manner. For the two strings to match, their contents must be identical except that the following special sequences may appear in(1,8) pattern: * Matches any sequence of characters in(1,8) string(3,n), includ- ing a null string. ? Matches any single character in(1,8) string(3,n). [chars] Matches any character in(1,8) the set(7,n,1 builtins) given by chars. If a sequence of the form x-y appears in(1,8) chars, then any character between x and y, inclusive, will match. When used with -nocase, the end points of the range are converted to lower case first. Whereas {[A-z]} matches '_' when matching case-sensitively ('_' falls between the 'Z' and 'a'), with -nocase this is consid- ered like {[A-Za-z]} (and probably what was meant in(1,8) the first place). \x Matches the single character x. This provides a way of avoiding the special interpretation of the charac- ters *?[]\ in(1,8) pattern. string(3,n) range string(3,n) first last Returns a range of consecutive characters from string(3,n), starting with the character whose index is first and ending with the character whose index is last. An index of 0 refers to the first character of the string. first and last may be specified as for the index method. If first is less(1,3) than zero then it is treated as if(3,n) it were zero, and if(3,n) last is greater than or equal to the length of the string(3,n) then it is treated as if(3,n) it were end. If first is greater than last then an empty string(3,n) is returned. string(3,n) repeat string(3,n) count Returns string(3,n) repeated count number of times. string(3,n) replace string(3,n) first last ?newstring? Removes a range of consecutive characters from string(3,n), starting with the character whose index is first and ending with the character whose index is last. An index of 0 refers to the first character of the string. First and last may be specified as for the index method. If newstring is specified, then it is placed in(1,8) the removed character range. If first is less(1,3) than zero then it is treated as if(3,n) it were zero, and if(3,n) last is greater than or equal to the length of the string(3,n) then it is treated as if(3,n) it were end. If first is greater than last or the length of the initial string(3,n), or last is less(1,3) than 0, then the initial string(3,n) is returned untouched. string(3,n) tolower string(3,n) ?first? ?last? Returns a value equal to string(3,n) except that all upper (or title) case letters have been converted to lower case. If first is specified, it refers to the first char index in(1,8) the string(3,n) to start modifying. If last is specified, it refers to the char index in(1,8) the string(3,n) to stop at (inclusive). first and last may be specified as for the index method. string(3,n) totitle string(3,n) ?first? ?last? Returns a value equal to string(3,n) except that the first character in(1,8) string(3,n) is converted to its Unicode title case variant (or upper case if(3,n) there is no title case variant) and the rest of the string(3,n) is converted to lower case. If first is specified, it refers to the first char index in(1,8) the string(3,n) to start modify- ing. If last is specified, it refers to the char index in(1,8) the string(3,n) to stop at (inclusive). first and last may be specified as for the index method. string(3,n) toupper string(3,n) ?first? ?last? Returns a value equal to string(3,n) except that all lower (or title) case letters have been converted to upper case. If first is specified, it refers to the first char index in(1,8) the string(3,n) to start modifying. If last is specified, it refers to the char index in(1,8) the string(3,n) to stop at (inclusive). first and last may be specified as for the index method. string(3,n) trim string(3,n) ?chars? Returns a value equal to string(3,n) except that any leading or trailing characters from the set(7,n,1 builtins) given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string(3,n) trimleft string(3,n) ?chars? Returns a value equal to string(3,n) except that any leading charac- ters from the set(7,n,1 builtins) given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string(3,n) trimright string(3,n) ?chars? Returns a value equal to string(3,n) except that any trailing charac- ters from the set(7,n,1 builtins) given by chars are removed. If chars is not specified then white space is removed (spaces, tabs, newlines, and carriage returns). string(3,n) wordend string(3,n) charIndex Returns the index of the character just after the last one in(1,8) the word containing character charIndex of string(3,n). charIndex may be specified as for the index method. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. string(3,n) wordstart string(3,n) charIndex Returns the index of the first character in(1,8) the word containing character charIndex of string(3,n). charIndex may be specified as for the index method. A word is considered to be any contiguous range of alphanumeric (Unicode letters or decimal digits) or underscore (Unicode connector punctuation) characters, or any single character other than these. SEE ALSO expr(1,3,n)(n), list(n) KEYWORDS case conversion, compare, index, match, pattern, string(3,n), word, equal, ctype Tcl 8.1 string(3,n)(n)