---
name: "string"
section: "n"
platform: "macos"
package: "tcl"
version: "152"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/string/n"
---

# string(n)

Manipulate strings

## NAME

string - Manipulate strings

## SYNOPSIS

**string** *option arg* ?*arg ...?*

## DESCRIPTION

Performs one of several string operations, depending on *option*. The legal *option*s (which may be abbreviated) are:

- **string bytelength** *string*

  Returns a decimal string giving the number of bytes used to represent *string* in 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 general.  The cases where a script cares about the byte length are rare.  In almost all cases, you should use the **string 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 representation.

- **string 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 than, equal to, or greater than *string2*.  If **-length** is specified, then only the first *length* characters are used in the comparison.  If **-length** is negative, it is ignored.  If **-nocase** is specified, then the strings are compared in a case-insensitive manner.

- **string equal** ?**-nocase**? ?**-length int**? *string1 string2*

  Perform a character-by-character comparison of strings *string1* and *string2*.  Returns 1 if *string1* and *string2* are identical, or 0 when not.  If **-length** is specified, then only the first *length* characters are used in the comparison.  If **-length** is negative, it is ignored.  If **-nocase** is specified, then the strings are compared in a case-insensitive manner.

- **string first** *needleString haystackString* ?*startIndex*?

  Search *haystackString* for a sequence of characters that exactly match the characters in *needleString*.  If found, return the index of the first character in the first such match within *haystackString*.  If not found, return -1.  If *startIndex* is specified (in any of the forms accepted by the **index** method), then the search is constrained to start with the character in *haystackString* specified by the index.  For example,

  **string first a 0a23456789abcdef 5** will return **10**, but **string first a 0123456789abcdef 11** will return **-1**.

- **string index** *string charIndex*

  Returns the *charIndex*'th character of the *string* argument. A *charIndex* of 0 corresponds to the first character of the string.  *charIndex* may be specified as follows:

  - *integer*

    For any index value that passes **string is integer -strict**, the char specified at this integral index (e.g. **2** would refer to the in

  - **end**

    The last char of the string (e.g. **end** would refer to the in

  - **end**-*N*

    The last char of the string minus the specified integer offset *N* (e.g. **end**-1 would refer to the in

  - **end**+*N*

    The last char of the string plus the specified integer offset *N* (e.g. **end**+-1 would refer to the in

  - *M*+*N*

    The char specified at the integral index that is the sum of  integer values *M* and *N* (e.g. **1+1** would refer to the in

  - *M*-*N*

    The char specified at the integral index that is the difference of  integer values *M* and *N* (e.g. **2-1** would refer to the in

  In the specifications above, the integer value *M* contains no trailing whitespace and the integer value *N* contains no leading whitespace.

  If *charIndex* is less than 0 or greater than or equal to the length of the string then this command returns an empty string.

- **string is** *class* ?**-strict**? ?**-failindex** *varname*? *string*

  Returns 1 if *string* is a valid member of the specified character class, otherwise returns 0.  If **-strict** is specified, then an empty string returns 0, otherwise an empty string will return 1 on any class.  If **-failindex** is specified, then if the function returns 0, the index in the string where the class was no longer valid will be stored in the variable named *varname*.  The *varname* will not be set if the function returns 1.  The following character classes are recognized (the class name can be abbreviated):

  - **alnum**

    Any Unicode alphabet or digit character.

  - **alpha**

    Any Unicode alphabet character.

  - **ascii**

    Any character with a value less than \\u0080 (those that are in the 7-bit ascii 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 Tcl, with optional surrounding whitespace.  In case of under/overflow in 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 string formats for a 32-bit integer value in Tcl, with optional surrounding whitespace.  In case of under/overflow in the value, 0 is returned and the *varname* will contain -1.

  - **list**

    Any proper list structure, with optional surrounding whitespace. In case of improper list structure, 0 is returned and the *varname* will contain the index of the where the list parsing fails, or -1 if this cannot be determined.

  - **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 the Unicode character set.

  - **wideinteger**

    Any of the valid forms for a wide integer in Tcl, with optional surrounding whitespace.  In case of under/overflow in the value, 0 is returned and the *varname* will contain -1.

  - **wordchar**

    Any Unicode word character.  That is any alphanumeric character, and any Unicode connector punctuation characters (e.g. underscore).

  - **xdigit**

    Any hexadecimal digit character (\[0-9A-Fa-f\]).

  In the case of **boolean**, **true** and **false**, if the function will return 0, then the *varname* will always be set to 0, due to the varied nature of a valid boolean value.

- **string last** *needleString haystackString* ?*lastIndex*?

  Search *haystackString* for a sequence of characters that exactly match the characters in *needleString*.  If found, return the index of the first character in the last such match within *haystackString*.  If there is no match, then return -1.  If *lastIndex* is specified (in any of the forms accepted by the **index** method), then only the characters in *haystackString* at or before the specified *lastIndex* will be considered by the search.  For example,

  **string last a 0a23456789abcdef 15** will return **10**, but **string last a 0a23456789abcdef 9** will return **1**.

- **string length** *string*

  Returns a decimal string giving the number of characters in *string*.  Note that this is not necessarily the same as the number 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 map** ?**-nocase**? *mapping string*

  Replaces substrings in *string* based on the key-value pairs in *mapping*.  *mapping* is a list of *key value key value ...* as in the form returned by **array get**.  Each instance of a key in the string 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 an ordered manner, so the key appearing first in the list will be checked first, and so on. *string* is only iterated over once, so earlier key replacements will have no affect for later key matches.  For example,

  **string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc** will return the string **01321221**.

  Note that if an earlier *key* is a prefix of a later one, it will completely mask the later one.  So if the previous example is reordered like this, **string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc** it will return the string **02c322c222c**.

- **string match** ?**-nocase**? *pattern* *string*

  See if *pattern* matches *string*; return 1 if it does, 0 if it does not.  If **-nocase** is specified, then the pattern attempts to match against the string in a case insensitive manner.  For the two strings to match, their contents must be identical except that the following special sequences may appear in *pattern*:

  - **\***

    Matches any sequence of characters in *string*, including a null string.

  - **?**

    Matches any single character in *string*.

  - **\[***chars***\]**

    Matches any character in the set given by *chars*.  If a sequence of the form *x***-***y* appears in *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 (since falls between the and with **-nocase** this is considered like {\[A-Za-z\]} (and probably what was meant in the first place).

  - **\\***x*

    Matches the single character *x*.  This provides a way of avoiding the special interpretation of the characters **\*?\[\]\\** in *pattern*.

- **string range** *string first last*

  Returns a range of consecutive characters from *string*, 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 than zero then it is treated as if it were zero, and if *last* is greater than or equal to the length of the string then it is treated as if it were **end**.  If *first* is greater than *last* then an empty string is returned.

- **string repeat** *string count*

  Returns *string* repeated *count* number of times.

- **string replace** *string first last* ?*newstring*?

  Removes a range of consecutive characters from *string*, 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 the removed character range.  If *first* is less than zero then it is treated as if it were zero, and if *last* is greater than or equal to the length of the string then it is treated as if it were **end**.  If *first* is greater than *last* or the length of the initial string, or *last* is less than 0, then the initial string is returned untouched.

- **string reverse** *string*

  Returns a string that is the same length as *string* but with its characters in the reverse order.

- **string tolower** *string* ?*first*? ?*last*?

  Returns a value equal to *string* 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 the string to start modifying.  If *last* is specified, it refers to the char index in the string to stop at (inclusive).  *first* and *last* may be specified as for the **index** method.

- **string totitle** *string* ?*first*? ?*last*?

  Returns a value equal to *string* except that the first character in *string* is converted to its Unicode title case variant (or upper case if there is no title case variant) and the rest of the string is converted to lower case.  If *first* is specified, it refers to the first char index in the string to start modifying.  If *last* is specified, it refers to the char index in the string to stop at (inclusive).  *first* and *last* may be specified as for the **index** method.

- **string toupper** *string* ?*first*? ?*last*?

  Returns a value equal to *string* 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 the string to start modifying.  If *last* is specified, it refers to the char index in the string to stop at (inclusive).  *first* and *last* may be specified as for the **index** method.

- **string trim** *string* ?*chars*?

  Returns a value equal to *string* except that any leading or trailing characters present in the string given by *chars* are removed.  If *chars* is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).

- **string trimleft** *string* ?*chars*?

  Returns a value equal to *string* except that any leading characters present in the string given by *chars* are removed.  If *chars* is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).

- **string trimright** *string* ?*chars*?

  Returns a value equal to *string* except that any trailing characters present in the string given by *chars* are removed.  If *chars* is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).

- **string wordend** *string charIndex*

  Returns the index of the character just after the last one in the word containing character *charIndex* of *string*.  *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 wordstart** *string charIndex*

  Returns the index of the first character in the word containing character *charIndex* of *string*.  *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.

## EXAMPLE

Test if the string in the variable *string* is a proper non-empty prefix of the string **foobar**. set length \[**string length** $string\] if {$length == 0} {\
    set isPrefix 0 } else {\
    set isPrefix \[**string equal** -length $length $string "foobar"\] }

## SEE ALSO

[expr(n)](/expr/n.md), [list(n)](/list/n.md)

## KEYWORDS

case conversion, compare, index, match, pattern, string, word, equal, ctype, character, reverse