1string(n) Tcl Built-In Commands string(n)
2______________________________________________________________________________
6
8 string - Manipulate strings
9
11 string option arg ?arg ...?
12_________________________________________________________________
13
16 Performs one of several string operations, depending on option. The
17 legal options (which may be abbreviated) are:
18 string bytelength string
20 Returns a decimal string giving the number of bytes used to rep‐
21 resent string in memory. Because UTF-8 uses one to three bytes
22 to represent Unicode characters, the byte length will not be the
23 same as the character length in general. The cases where a
24 script cares about the byte length are rare. In almost all
25 cases, you should use the string length operation (including
26 determining the length of a Tcl ByteArray object). Refer to the
27 Tcl_NumUtfChars manual entry for more details on the UTF-8 rep‐
28 resentation.
29 string compare ?-nocase? ?-length int? string1 string2
31 Perform a character-by-character comparison of strings string1
32 and string2. Returns -1, 0, or 1, depending on whether string1
33 is lexicographically less than, equal to, or greater than
34 string2. If -length is specified, then only the first length
35 characters are used in the comparison. If -length is negative,
36 it is ignored. If -nocase is specified, then the strings are
37 compared in a case-insensitive manner.
38 string equal ?-nocase? ?-length int? string1 string2
40 Perform a character-by-character comparison of strings string1
41 and string2. Returns 1 if string1 and string2 are identical, or
42 0 when not. If -length is specified, then only the first length
43 characters are used in the comparison. If -length is negative,
44 it is ignored. If -nocase is specified, then the strings are
45 compared in a case-insensitive manner.
46 string first needleString haystackString ?startIndex?
48 Search haystackString for a sequence of characters that exactly
49 match the characters in needleString. If found, return the
50 index of the first character in the first such match within
51 haystackString. If not found, return -1. If startIndex is
52 specified (in any of the forms accepted by the index method),
53 then the search is constrained to start with the character in
54 haystackString specified by the index. For example,
55 string first a 0a23456789abcdef 5
56 will return 10, but
57 string first a 0123456789abcdef 11
58 will return -1.
59 string index string charIndex
61 Returns the charIndex'th character of the string argument. A
62 charIndex of 0 corresponds to the first character of the string.
63 charIndex may be specified as follows: │
64 integer │
66 For any index value that passes string is integer │
67 -strict, the char specified at this integral index │
68 (e.g. 2 would refer to the “c” in “abcd”). │
69 end │
71 The last char of the string (e.g. end would refer to │
72 the “d” in “abcd”). │
73 end-N │
75 The last char of the string minus the specified inte‐ │
76 ger offset N (e.g. end-1 would refer to the “c” in │
77 “abcd”). │
78 end+N │
80 The last char of the string plus the specified integer │
81 offset N (e.g. end+-1 would refer to the “c” in │
82 “abcd”). │
83 M+N │
85 The char specified at the integral index that is the │
86 sum of integer values M and N (e.g. 1+1 would refer to │
87 the “c” in “abcd”). │
88 M-N │
90 The char specified at the integral index that is the │
91 difference of integer values M and N (e.g. 2-1 would │
92 refer to the “b” in “abcd”). │
93 In the specifications above, the integer value M contains no │
95 trailing whitespace and the integer value N contains no leading │
96 whitespace. │
97 If charIndex is less than 0 or greater than or equal to the │
99 length of the string then this command returns an empty string. │
100 string is class ?-strict? ?-failindex varname? string
102 Returns 1 if string is a valid member of the specified character
103 class, otherwise returns 0. If -strict is specified, then an
104 empty string returns 0, otherwise an empty string will return 1
105 on any class. If -failindex is specified, then if the function
106 returns 0, the index in the string where the class was no longer
107 valid will be stored in the variable named varname. The varname
108 will not be set if the function returns 1. The following char‐
109 acter classes are recognized (the class name can be abbrevi‐
110 ated):
111 alnum Any Unicode alphabet or digit character.
113 alpha Any Unicode alphabet character.
115 ascii Any character with a value less than \u0080 (those
117 that are in the 7-bit ascii range).
118 boolean Any of the forms allowed to Tcl_GetBoolean.
120 control Any Unicode control character.
122 digit Any Unicode digit character. Note that this
124 includes characters outside of the [0-9] range.
125 double Any of the valid forms for a double in Tcl, with
127 optional surrounding whitespace. In case of
128 under/overflow in the value, 0 is returned and the
129 varname will contain -1.
130 false Any of the forms allowed to Tcl_GetBoolean where the
132 value is false.
133 graph Any Unicode printing character, except space.
135 integer Any of the valid string formats for a 32-bit integer
137 value in Tcl, with optional surrounding whitespace.
138 In case of under/overflow in the value, 0 is
139 returned and the varname will contain -1.
140 list Any proper list structure, with optional surrounding
142 whitespace. In case of improper list structure, 0 is
143 returned and the varname will contain the index of
144 the “element” where the list parsing fails, or -1 if
145 this cannot be determined.
146 lower Any Unicode lower case alphabet character.
148 print Any Unicode printing character, including space.
150 punct Any Unicode punctuation character.
152 space Any Unicode space character.
154 true Any of the forms allowed to Tcl_GetBoolean where the
156 value is true.
157 upper Any upper case alphabet character in the Unicode
159 character set. │
160 wideinteger │
162 Any of the valid forms for a wide integer in Tcl, │
163 with optional surrounding whitespace. In case of │
164 under/overflow in the value, 0 is returned and the │
165 varname will contain -1.
166 wordchar Any Unicode word character. That is any alphanu‐
168 meric character, and any Unicode connector punctua‐
169 tion characters (e.g. underscore).
170 xdigit Any hexadecimal digit character ([0-9A-Fa-f]).
172 In the case of boolean, true and false, if the function will
174 return 0, then the varname will always be set to 0, due to the
175 varied nature of a valid boolean value.
176 string last needleString haystackString ?lastIndex?
178 Search haystackString for a sequence of characters that exactly
179 match the characters in needleString. If found, return the
180 index of the first character in the last such match within
181 haystackString. If there is no match, then return -1. If
182 lastIndex is specified (in any of the forms accepted by the
183 index method), then only the characters in haystackString at or
184 before the specified lastIndex will be considered by the search.
185 For example,
186 string last a 0a23456789abcdef 15
187 will return 10, but
188 string last a 0a23456789abcdef 9
189 will return 1.
190 string length string
192 Returns a decimal string giving the number of characters in
193 string. Note that this is not necessarily the same as the num‐
194 ber of bytes used to store the string. If the object is a
195 ByteArray object (such as those returned from reading a binary
196 encoded channel), then this will return the actual byte length
197 of the object.
198 string map ?-nocase? mapping string
200 Replaces substrings in string based on the key-value pairs in
201 mapping. mapping is a list of key value key value ... as in
202 the form returned by array get. Each instance of a key in the
203 string will be replaced with its corresponding value. If
204 -nocase is specified, then matching is done without regard to
205 case differences. Both key and value may be multiple characters.
206 Replacement is done in an ordered manner, so the key appearing
207 first in the list will be checked first, and so on. string is
208 only iterated over once, so earlier key replacements will have
209 no affect for later key matches. For example,
210 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
211 will return the string 01321221.
212 Note that if an earlier key is a prefix of a later one, it will
214 completely mask the later one. So if the previous example is
215 reordered like this,
216 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
217 it will return the string 02c322c222c.
218 string match ?-nocase? pattern string
220 See if pattern matches string; return 1 if it does, 0 if it does
221 not. If -nocase is specified, then the pattern attempts to
222 match against the string in a case insensitive manner. For the
223 two strings to match, their contents must be identical except
224 that the following special sequences may appear in pattern:
225 * Matches any sequence of characters in string, includ‐
227 ing a null string.
228 ? Matches any single character in string.
230 [chars] Matches any character in the set given by chars. If a
232 sequence of the form x-y appears in chars, then any
233 character between x and y, inclusive, will match.
234 When used with -nocase, the end points of the range
235 are converted to lower case first. Whereas {[A-z]}
236 matches “_” when matching case-sensitively (since “_”
237 falls between the “Z” and “a”), with -nocase this is
238 considered like {[A-Za-z]} (and probably what was
239 meant in the first place).
240 \x Matches the single character x. This provides a way
242 of avoiding the special interpretation of the charac‐
243 ters *?[]\ in pattern.
244 string range string first last
246 Returns a range of consecutive characters from string, starting
247 with the character whose index is first and ending with the
248 character whose index is last. An index of 0 refers to the first
249 character of the string. first and last may be specified as for
250 the index method. If first is less than zero then it is treated
251 as if it were zero, and if last is greater than or equal to the
252 length of the string then it is treated as if it were end. If
253 first is greater than last then an empty string is returned.
254 string repeat string count
256 Returns string repeated count number of times.
257 string replace string first last ?newstring?
259 Removes a range of consecutive characters from string, starting
260 with the character whose index is first and ending with the
261 character whose index is last. An index of 0 refers to the
262 first character of the string. First and last may be specified
263 as for the index method. If newstring is specified, then it is
264 placed in the removed character range. If first is less than
265 zero then it is treated as if it were zero, and if last is
266 greater than or equal to the length of the string then it is
267 treated as if it were end. If first is greater than last or the
268 length of the initial string, or last is less than 0, then the
269 initial string is returned untouched. │
270 string reverse string │
272 Returns a string that is the same length as string but with its │
273 characters in the reverse order.
274 string tolower string ?first? ?last?
276 Returns a value equal to string except that all upper (or title)
277 case letters have been converted to lower case. If first is
278 specified, it refers to the first char index in the string to
279 start modifying. If last is specified, it refers to the char
280 index in the string to stop at (inclusive). first and last may
281 be specified as for the index method.
282 string totitle string ?first? ?last?
284 Returns a value equal to string except that the first character
285 in string is converted to its Unicode title case variant (or
286 upper case if there is no title case variant) and the rest of
287 the string is converted to lower case. If first is specified,
288 it refers to the first char index in the string to start modify‐
289 ing. If last is specified, it refers to the char index in the
290 string to stop at (inclusive). first and last may be specified
291 as for the index method.
292 string toupper string ?first? ?last?
294 Returns a value equal to string except that all lower (or title)
295 case letters have been converted to upper case. If first is
296 specified, it refers to the first char index in the string to
297 start modifying. If last is specified, it refers to the char
298 index in the string to stop at (inclusive). first and last may
299 be specified as for the index method.
300 string trim string ?chars?
302 Returns a value equal to string except that any leading or
303 trailing characters present in the string given by chars are
304 removed. If chars is not specified then white space is removed
305 (spaces, tabs, newlines, and carriage returns).
306 string trimleft string ?chars?
308 Returns a value equal to string except that any leading charac‐
309 ters present in the string given by chars are removed. If chars
310 is not specified then white space is removed (spaces, tabs, new‐
311 lines, and carriage returns).
312 string trimright string ?chars?
314 Returns a value equal to string except that any trailing charac‐
315 ters present in the string given by chars are removed. If chars
316 is not specified then white space is removed (spaces, tabs, new‐
317 lines, and carriage returns).
318 string wordend string charIndex
320 Returns the index of the character just after the last one in
321 the word containing character charIndex of string. charIndex
322 may be specified as for the index method. A word is considered
323 to be any contiguous range of alphanumeric (Unicode letters or
324 decimal digits) or underscore (Unicode connector punctuation)
325 characters, or any single character other than these.
326 string wordstart string charIndex
328 Returns the index of the first character in the word containing
329 character charIndex of string. charIndex may be specified as
330 for the index method. A word is considered to be any contiguous
331 range of alphanumeric (Unicode letters or decimal digits) or
332 underscore (Unicode connector punctuation) characters, or any
333 single character other than these.
334
336 Test if the string in the variable string is a proper non-empty prefix
337 of the string foobar.
338 set length [string length $string]
339 if {$length == 0} {
340 set isPrefix 0
341 } else {
342 set isPrefix [string equal -length $length $string "foobar"]
343 }
344
347 expr(n), list(n)
348
351 case conversion, compare, index, match, pattern, string, word, equal,
352 ctype, character, reverse
353Tcl 8.1 string(n)