1string(n) Tcl Built-In Commands string(n)
2______________________________________________________________________________
6
8 string - Manipulate strings
9
11 string option arg ?arg ...?
12______________________________________________________________________________
13
15 Performs one of several string operations, depending on option. The
16 legal options (which may be abbreviated) are:
17 string cat ?string1? ?string2...?
19 Concatenate the given strings just like placing them directly │
20 next to each other and return the resulting compound string. If │
21 no strings are present, the result is an empty string. │
22 This primitive is occasionally handier than juxtaposition of │
24 strings when mixed quoting is wanted, or when the aim is to │
25 return the result of a concatenation without resorting to return │
26 -level 0, and is more efficient than building a list of argu‐ │
27 ments and using join with an empty join string. │
28 string compare ?-nocase? ?-length length? string1 string2
30 Perform a character-by-character comparison of strings string1
31 and string2. Returns -1, 0, or 1, depending on whether string1
32 is lexicographically less than, equal to, or greater than
33 string2. If -length is specified, then only the first length
34 characters are used in the comparison. If -length is negative,
35 it is ignored. If -nocase is specified, then the strings are
36 compared in a case-insensitive manner.
37 string equal ?-nocase? ?-length length? string1 string2
39 Perform a character-by-character comparison of strings string1
40 and string2. Returns 1 if string1 and string2 are identical, or
41 0 when not. If -length is specified, then only the first length
42 characters are used in the comparison. If -length is negative,
43 it is ignored. If -nocase is specified, then the strings are
44 compared in a case-insensitive manner.
45 string first needleString haystackString ?startIndex?
47 Search haystackString for a sequence of characters that exactly
48 match the characters in needleString. If found, return the
49 index of the first character in the first such match within
50 haystackString. If not found, return -1. If startIndex is
51 specified (in any of the forms described in STRING INDICES),
52 then the search is constrained to start with the character in
53 haystackString specified by the index. For example,
54 string first a 0a23456789abcdef 5
56 will return 10, but
58 string first a 0123456789abcdef 11
60 will return -1.
62 string index string charIndex
64 Returns the charIndex'th character of the string argument. A
65 charIndex of 0 corresponds to the first character of the string.
66 charIndex may be specified as described in the STRING INDICES
67 section.
68 If charIndex is less than 0 or greater than or equal to the
70 length of the string then this command returns an empty string.
71 string is class ?-strict? ?-failindex varname? string
73 Returns 1 if string is a valid member of the specified character
74 class, otherwise returns 0. If -strict is specified, then an
75 empty string returns 0, otherwise an empty string will return 1
76 on any class. If -failindex is specified, then if the function
77 returns 0, the index in the string where the class was no longer
78 valid will be stored in the variable named varname. The varname
79 will not be set if string is returns 1. The following character
80 classes are recognized (the class name can be abbreviated):
81 alnum Any Unicode alphabet or digit character.
83 alpha Any Unicode alphabet character.
85 ascii Any character with a value less than \u0080 (those
87 that are in the 7-bit ascii range).
88 boolean Any of the forms allowed to Tcl_GetBoolean.
90 control Any Unicode control character.
92 digit Any Unicode digit character. Note that this
94 includes characters outside of the [0-9] range.
95 double Any of the forms allowed to Tcl_GetDoubleFromObj.
97 entier Any of the valid string formats for an integer value │
99 of arbitrary size in Tcl, with optional surrounding │
100 whitespace. The formats accepted are exactly those │
101 accepted by the C routine Tcl_GetBignumFromObj.
102 false Any of the forms allowed to Tcl_GetBoolean where the
104 value is false.
105 graph Any Unicode printing character, except space.
107 integer Any of the valid string formats for a 32-bit integer
109 value in Tcl, with optional surrounding whitespace.
110 In case of overflow in the value, 0 is returned and
111 the varname will contain -1.
112 list Any proper list structure, with optional surrounding
114 whitespace. In case of improper list structure, 0 is
115 returned and the varname will contain the index of
116 the “element” where the list parsing fails, or -1 if
117 this cannot be determined.
118 lower Any Unicode lower case alphabet character.
120 print Any Unicode printing character, including space.
122 punct Any Unicode punctuation character.
124 space Any Unicode whitespace character, mongolian vowel
126 separator (U+180e), zero width space (U+200b), word
127 joiner (U+2060) or zero width no-break space
128 (U+feff) (=BOM).
129 true Any of the forms allowed to Tcl_GetBoolean where the
131 value is true.
132 upper Any upper case alphabet character in the Unicode
134 character set.
135 wideinteger Any of the valid forms for a wide integer in Tcl,
137 with optional surrounding whitespace. In case of
138 overflow in the value, 0 is returned and the varname
139 will contain -1.
140 wordchar Any Unicode word character. That is any alphanu‐
142 meric character, and any Unicode connector punctua‐
143 tion characters (e.g. underscore).
144 xdigit Any hexadecimal digit character ([0-9A-Fa-f]).
146 In the case of boolean, true and false, if the function will
148 return 0, then the varname will always be set to 0, due to the
149 varied nature of a valid boolean value.
150 string last needleString haystackString ?lastIndex?
152 Search haystackString for a sequence of characters that exactly
153 match the characters in needleString. If found, return the
154 index of the first character in the last such match within
155 haystackString. If there is no match, then return -1. If
156 lastIndex is specified (in any of the forms described in STRING
157 INDICES), then only the characters in haystackString at or
158 before the specified lastIndex will be considered by the search.
159 For example,
160 string last a 0a23456789abcdef 15
162 will return 10, but
164 string last a 0a23456789abcdef 9
166 will return 1.
168 string length string
170 Returns a decimal string giving the number of characters in
171 string. Note that this is not necessarily the same as the num‐
172 ber of bytes used to store the string. If the value is a byte
173 array value (such as those returned from reading a binary
174 encoded channel), then this will return the actual byte length
175 of the value.
176 string map ?-nocase? mapping string
178 Replaces substrings in string based on the key-value pairs in
179 mapping. mapping is a list of key value key value ... as in
180 the form returned by array get. Each instance of a key in the
181 string will be replaced with its corresponding value. If
182 -nocase is specified, then matching is done without regard to
183 case differences. Both key and value may be multiple characters.
184 Replacement is done in an ordered manner, so the key appearing
185 first in the list will be checked first, and so on. string is
186 only iterated over once, so earlier key replacements will have
187 no affect for later key matches. For example,
188 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
190 will return the string 01321221.
192 Note that if an earlier key is a prefix of a later one, it will
194 completely mask the later one. So if the previous example is
195 reordered like this,
196 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
198 it will return the string 02c322c222c.
200 string match ?-nocase? pattern string
202 See if pattern matches string; return 1 if it does, 0 if it does
203 not. If -nocase is specified, then the pattern attempts to
204 match against the string in a case insensitive manner. For the
205 two strings to match, their contents must be identical except
206 that the following special sequences may appear in pattern:
207 * Matches any sequence of characters in string, includ‐
209 ing a null string.
210 ? Matches any single character in string.
212 [chars] Matches any character in the set given by chars. If a
214 sequence of the form x-y appears in chars, then any
215 character between x and y, inclusive, will match.
216 When used with -nocase, the end points of the range
217 are converted to lower case first. Whereas {[A-z]}
218 matches “_” when matching case-sensitively (since “_”
219 falls between the “Z” and “a”), with -nocase this is
220 considered like {[A-Za-z]} (and probably what was
221 meant in the first place).
222 \x Matches the single character x. This provides a way
224 of avoiding the special interpretation of the charac‐
225 ters *?[]\ in pattern.
226 string range string first last
228 Returns a range of consecutive characters from string, starting
229 with the character whose index is first and ending with the
230 character whose index is last. An index of 0 refers to the first
231 character of the string. first and last may be specified as for
232 the index method. If first is less than zero then it is treated
233 as if it were zero, and if last is greater than or equal to the
234 length of the string then it is treated as if it were end. If
235 first is greater than last then an empty string is returned.
236 string repeat string count
238 Returns string repeated count number of times.
239 string replace string first last ?newstring?
241 Removes a range of consecutive characters from string, starting
242 with the character whose index is first and ending with the
243 character whose index is last. An index of 0 refers to the
244 first character of the string. First and last may be specified
245 as for the index method. If newstring is specified, then it is
246 placed in the removed character range. If first is less than
247 zero then it is treated as if it were zero, and if last is
248 greater than or equal to the length of the string then it is
249 treated as if it were end. If first is greater than last or the
250 length of the initial string, or last is less than 0, then the
251 initial string is returned untouched.
252 string reverse string
254 Returns a string that is the same length as string but with its
255 characters in the reverse order.
256 string tolower string ?first? ?last?
258 Returns a value equal to string except that all upper (or title)
259 case letters have been converted to lower case. If first is
260 specified, it refers to the first char index in the string to
261 start modifying. If last is specified, it refers to the char
262 index in the string to stop at (inclusive). first and last may
263 be specified using the forms described in STRING INDICES.
264 string totitle string ?first? ?last?
266 Returns a value equal to string except that the first character
267 in string is converted to its Unicode title case variant (or
268 upper case if there is no title case variant) and the rest of
269 the string is converted to lower case. If first is specified,
270 it refers to the first char index in the string to start modify‐
271 ing. If last is specified, it refers to the char index in the
272 string to stop at (inclusive). first and last may be specified
273 using the forms described in STRING INDICES.
274 string toupper string ?first? ?last?
276 Returns a value equal to string except that all lower (or title)
277 case letters have been converted to upper 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 using the forms described in STRING INDICES.
282 string trim string ?chars?
284 Returns a value equal to string except that any leading or
285 trailing characters present in the string given by chars are
286 removed. If chars is not specified then white space is removed
287 (any character for which string is space returns 1, and "\0").
288 string trimleft string ?chars?
290 Returns a value equal to string except that any leading charac‐
291 ters present in the string given by chars are removed. If chars
292 is not specified then white space is removed (any character for
293 which string is space returns 1, and "\0").
294 string trimright string ?chars?
296 Returns a value equal to string except that any trailing charac‐
297 ters present in the string given by chars are removed. If chars
298 is not specified then white space is removed (any character for
299 which string is space returns 1, and "\0").
300 OBSOLETE SUBCOMMANDS
302 These subcommands are currently supported, but are likely to go away in
303 a future release as their functionality is either virtually never used
304 or highly misleading.
305 string bytelength string
307 Returns a decimal string giving the number of bytes used to rep‐
308 resent string in memory when encoded as Tcl's internal modified
309 UTF-8; Tcl may use other encodings for string as well, and does
310 not guarantee to only use a single encoding for a particular
311 string. Because UTF-8 uses a variable number of bytes to repre‐
312 sent Unicode characters, the byte length will not be the same as
313 the character length in general. The cases where a script cares
314 about the byte length are rare.
315 In almost all cases, you should use the string length operation
317 (including determining the length of a Tcl byte array value).
318 Refer to the Tcl_NumUtfChars manual entry for more details on
319 the UTF-8 representation.
320 Formally, the string bytelength operation returns the content of
322 the length field of the Tcl_Obj structure, after calling
323 Tcl_GetString to ensure that the bytes field is populated. This
324 is highly unlikely to be useful to Tcl scripts, as Tcl's inter‐
325 nal encoding is not strict UTF-8, but rather a modified CESU-8
326 with a denormalized NUL (identical to that used in a number of
327 places by Java's serialization mechanism) to enable basic pro‐
328 cessing with non-Unicode-aware C functions. As this representa‐
329 tion should only ever be used by Tcl's implementation, the num‐
330 ber of bytes used to store the representation is of very low
331 value (except to C extension code, which has direct access for
332 the purpose of memory management, etc.)
333 Compatibility note: it is likely that this subcommand will be
335 withdrawn in a future version of Tcl. It is better to use the
336 encoding convertto command to convert a string to a known encod‐
337 ing and then apply string length to that.
338 string length [encoding convertto utf-8 $theString]
340 string wordend string charIndex
342 Returns the index of the character just after the last one in
343 the word containing character charIndex of string. charIndex
344 may be specified using the forms in STRING INDICES. A word is
345 considered to be any contiguous range of alphanumeric (Unicode
346 letters or decimal digits) or underscore (Unicode connector
347 punctuation) characters, or any single character other than
348 these.
349 string wordstart string charIndex
351 Returns the index of the first character in the word containing
352 character charIndex of string. charIndex may be specified using
353 the forms in STRING INDICES. A word is considered to be any
354 contiguous range of alphanumeric (Unicode letters or decimal
355 digits) or underscore (Unicode connector punctuation) charac‐
356 ters, or any single character other than these.
357
359 When referring to indices into a string (e.g., for string index or
360 string range) the following formats are supported:
361 integer For any index value that passes string is integer -strict,
363 the char specified at this integral index (e.g., 2 would
364 refer to the “c” in “abcd”).
365 end The last char of the string (e.g., end would refer to the “d”
367 in “abcd”).
368 end-N The last char of the string minus the specified integer off‐
370 set N (e.g., “end-1” would refer to the “c” in “abcd”).
371 end+N The last char of the string plus the specified integer offset
373 N (e.g., “end+-1” would refer to the “c” in “abcd”).
374 M+N The char specified at the integral index that is the sum of
376 integer values M and N (e.g., “1+1” would refer to the “c” in
377 “abcd”).
378 M-N The char specified at the integral index that is the differ‐
380 ence of integer values M and N (e.g., “2-1” would refer to
381 the “b” in “abcd”).
382 In the specifications above, the integer value M contains no trailing
384 whitespace and the integer value N contains no leading whitespace.
385
387 Test if the string in the variable string is a proper non-empty prefix
388 of the string foobar.
389 set length [string length $string]
391 if {$length == 0} {
392 set isPrefix 0
393 } else {
394 set isPrefix [string equal -length $length $string "foobar"]
395 }
396
398 expr(n), list(n)
399
401 case conversion, compare, index, match, pattern, string, word, equal,
402 ctype, character, reverse
403Tcl 8.1 string(n)