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 string1 string2 ?startIndex?
48 Search string2 for a sequence of characters that exactly match
49 the characters in string1. If found, return the index of the
50 first character in the first such match within string2. If not
51 found, return -1. If startIndex is specified (in any of the
52 forms accepted by the index method), then the search is con‐
53 strained to start with the character in string2 specified by the
54 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 The char specified at this integral index.
66 end The last char of the string.
68 end-integer
70 The last char of the string minus the specified inte‐
71 ger offset (e.g. end-1 would refer to the "c" in
72 "abcd").
73 If charIndex is less than 0 or greater than or equal to the
75 length of the string then an empty string is returned.
76 string is class ?-strict? ?-failindex varname? string
78 Returns 1 if string is a valid member of the specified character
79 class, otherwise returns 0. If -strict is specified, then an
80 empty string returns 0, otherwise and empty string will return 1
81 on any class. If -failindex is specified, then if the function
82 returns 0, the index in the string where the class was no longer
83 valid will be stored in the variable named varname. The varname
84 will not be set if the function returns 1. The following char‐
85 acter classes are recognized (the class name can be abbrevi‐
86 ated):
87 alnum Any Unicode alphabet or digit character.
89 alpha Any Unicode alphabet character.
91 ascii Any character with a value less than \u0080 (those
93 that are in the 7-bit ascii range).
94 boolean Any of the forms allowed to Tcl_GetBoolean.
96 control Any Unicode control character.
98 digit Any Unicode digit character. Note that this
100 includes characters outside of the [0-9] range.
101 double Any of the valid forms for a double in Tcl, with
103 optional surrounding whitespace. In case of
104 under/overflow in the value, 0 is returned and the
105 varname will contain -1.
106 false Any of the forms allowed to Tcl_GetBoolean where the
108 value is false.
109 graph Any Unicode printing character, except space.
111 integer Any of the valid forms for an ordinary integer in
113 Tcl, with optional surrounding whitespace. In case
114 of under/overflow in the value, 0 is returned and
115 the varname will contain -1.
116 lower Any Unicode lower case alphabet character.
118 print Any Unicode printing character, including space.
120 punct Any Unicode punctuation character.
122 space Any Unicode space character.
124 true Any of the forms allowed to Tcl_GetBoolean where the
126 value is true.
127 upper Any upper case alphabet character in the Unicode
129 character set.
130 wordchar Any Unicode word character. That is any alphanu‐
132 meric character, and any Unicode connector punctua‐
133 tion characters (e.g. underscore).
134 xdigit Any hexadecimal digit character ([0-9A-Fa-f]).
136 In the case of boolean, true and false, if the function will
138 return 0, then the varname will always be set to 0, due to the
139 varied nature of a valid boolean value.
140 string last string1 string2 ?lastIndex?
142 Search string2 for a sequence of characters that exactly match
143 the characters in string1. If found, return the index of the
144 first character in the last such match within string2. If there
145 is no match, then return -1. If lastIndex is specified (in any
146 of the forms accepted by the index method), then only the char‐
147 acters in string2 at or before the specified lastIndex will be
148 considered by the search. For example,
149 string last a 0a23456789abcdef 15
150 will return 10, but
151 string last a 0a23456789abcdef 9
152 will return 1.
153 string length string
155 Returns a decimal string giving the number of characters in
156 string. Note that this is not necessarily the same as the num‐
157 ber of bytes used to store the string. If the object is a
158 ByteArray object (such as those returned from reading a binary
159 encoded channel), then this will return the actual byte length
160 of the object.
161 string map ?-nocase? mapping string
163 Replaces substrings in string based on the key-value pairs in
164 mapping. mapping is a list of key value key value ... as in
165 the form returned by array get. Each instance of a key in the
166 string will be replaced with its corresponding value. If
167 -nocase is specified, then matching is done without regard to
168 case differences. Both key and value may be multiple characters.
169 Replacement is done in an ordered manner, so the key appearing
170 first in the list will be checked first, and so on. string is
171 only iterated over once, so earlier key replacements will have
172 no affect for later key matches. For example,
173 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
174 will return the string 01321221.
175 Note that if an earlier key is a prefix of a later one, it will
177 completely mask the later one. So if the previous example is
178 reordered like this,
179 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
180 it will return the string 02c322c222c.
181 string match ?-nocase? pattern string
183 See if pattern matches string; return 1 if it does, 0 if it
184 doesn't. If -nocase is specified, then the pattern attempts to
185 match against the string in a case insensitive manner. For the
186 two strings to match, their contents must be identical except
187 that the following special sequences may appear in pattern:
188 * Matches any sequence of characters in string, includ‐
190 ing a null string.
191 ? Matches any single character in string.
193 [chars] Matches any character in the set given by chars. If a
195 sequence of the form x-y appears in chars, then any
196 character between x and y, inclusive, will match.
197 When used with -nocase, the end points of the range
198 are converted to lower case first. Whereas {[A-z]}
199 matches '_' when matching case-sensitively ('_' falls
200 between the 'Z' and 'a'), with -nocase this is consid‐
201 ered like {[A-Za-z]} (and probably what was meant in
202 the first place).
203 \x Matches the single character x. This provides a way
205 of avoiding the special interpretation of the charac‐
206 ters *?[]\ in pattern.
207 string range string first last
209 Returns a range of consecutive characters from string, starting
210 with the character whose index is first and ending with the
211 character whose index is last. An index of 0 refers to the first
212 character of the string. first and last may be specified as for
213 the index method. If first is less than zero then it is treated
214 as if it were zero, and if last is greater than or equal to the
215 length of the string then it is treated as if it were end. If
216 first is greater than last then an empty string is returned.
217 string repeat string count
219 Returns string repeated count number of times.
220 string replace string first last ?newstring?
222 Removes a range of consecutive characters from string, starting
223 with the character whose index is first and ending with the
224 character whose index is last. An index of 0 refers to the
225 first character of the string. First and last may be specified
226 as for the index method. If newstring is specified, then it is
227 placed in the removed character range. If first is less than
228 zero then it is treated as if it were zero, and if last is
229 greater than or equal to the length of the string then it is
230 treated as if it were end. If first is greater than last or the
231 length of the initial string, or last is less than 0, then the
232 initial string is returned untouched.
233 string tolower string ?first? ?last?
235 Returns a value equal to string except that all upper (or title)
236 case letters have been converted to lower case. If first is
237 specified, it refers to the first char index in the string to
238 start modifying. If last is specified, it refers to the char
239 index in the string to stop at (inclusive). first and last may
240 be specified as for the index method.
241 string totitle string ?first? ?last?
243 Returns a value equal to string except that the first character
244 in string is converted to its Unicode title case variant (or
245 upper case if there is no title case variant) and the rest of
246 the string is converted to lower case. If first is specified,
247 it refers to the first char index in the string to start modify‐
248 ing. If last is specified, it refers to the char index in the
249 string to stop at (inclusive). first and last may be specified
250 as for the index method.
251 string toupper string ?first? ?last?
253 Returns a value equal to string except that all lower (or title)
254 case letters have been converted to upper case. If first is
255 specified, it refers to the first char index in the string to
256 start modifying. If last is specified, it refers to the char
257 index in the string to stop at (inclusive). first and last may
258 be specified as for the index method.
259 string trim string ?chars?
261 Returns a value equal to string except that any leading or
262 trailing characters from the set given by chars are removed. If
263 chars is not specified then white space is removed (spaces,
264 tabs, newlines, and carriage returns).
265 string trimleft string ?chars?
267 Returns a value equal to string except that any leading charac‐
268 ters from the set given by chars are removed. If chars is not
269 specified then white space is removed (spaces, tabs, newlines,
270 and carriage returns).
271 string trimright string ?chars?
273 Returns a value equal to string except that any trailing charac‐
274 ters from the set given by chars are removed. If chars is not
275 specified then white space is removed (spaces, tabs, newlines,
276 and carriage returns).
277 string wordend string charIndex
279 Returns the index of the character just after the last one in
280 the word containing character charIndex of string. charIndex
281 may be specified as for the index method. A word is considered
282 to be any contiguous range of alphanumeric (Unicode letters or
283 decimal digits) or underscore (Unicode connector punctuation)
284 characters, or any single character other than these.
285 string wordstart string charIndex
287 Returns the index of the first character in the word containing
288 character charIndex of string. charIndex may be specified as
289 for the index method. A word is considered to be any contiguous
290 range of alphanumeric (Unicode letters or decimal digits) or
291 underscore (Unicode connector punctuation) characters, or any
292 single character other than these.
293
295 Test if the string in the variable string is a proper non-empty prefix
296 of the string foobar.
297 set length [string length $string]
298 if {$length == 0} {
299 set isPrefix 0
300 } else {
301 set isPrefix [string equal -length $string $string "foobar"]
302 }
303
306 expr(n), list(n)
307
310 case conversion, compare, index, match, pattern, string, word, equal,
311 ctype
312Tcl 8.1 string(n)