15.2.19 string (Manipulate Character Strings)

Description

Performs string operations, such as comparisons, extractions, conversions, and fragmentation.

Synopsis

string option arg [arg ... ]

Options

option: Specify the option keyword that defines a string operation. How to define available options and their descriptions are shown below.

arg ...: Specify the argument required for string manipulation.

Each option is explained in the following table:

string compare string1 string2	Performs a string-by-string comparison. Returns -1, 0, or 1 depending on whether string1 lexicographically is less than string2.
string first string1 string2	Searches string2 for occurrences of string1. If found, it returns the index of the first character (see Note) of string1 in the first match within string2. If not found, it returns -1.
string index string charIndex	Returns the string of the place indicated by charIndex (index (see Note)).
string last string1 string2	Searches string2 for occurrences of string1. If found, it returns the index of the first character (see Note)) of string1 in the last match within string2. If not found, it returns -1.
string length string	Returns the length of string in string.
string match pattern string	Checks if pattern matches string. Returns 1 if it does, 0 if it does not. Special characters used to specify filenames in UNIX C Shell can be also used in pattern. Shown below are the characters treated as the special characters in pattern. : Interpreted as a sequence of characters, including a null string. E.g.) Pattern ab matches any strings that begin with ab. ?: Interpreted as any single character. E.g.) Pattern ab? matches a three-character sting that begins with ab. []: Interpreted as any single character enclosed in brackets. [a-z] is interpreted as any character between a and z. E.g.) Pattern ab[0-9] matches any three-character strings that begins with ab followed by a number. \: If written just before any of the special characters (?[] \) in pattern, it voids their special interpretation to treat them as a single character. E.g.) Pattern ab\ matches the string ab*. If any of these special characters is not included in the pattern, the two strings will match if string perfectly matches pattern.
string range string i j	Returns the string of the place (index (see Note)) indicated from character i to character j.
string tolower string	Returns the string which has been converted to lower case.
string totitle string	Returns the string the first character of which has been converted to upper case and the rest of which has been converted to lower case.
string toupper string	Returns the string which has been converted to upper case.
string trim string [chars]	If a character contained in the character set specified by chars exists at the beginning or end of string, this option returns a character string from which that character has been removed. If chars is not specified, white spaces are removed.
string trimleft string [chars]	If a list of characters specified by chars exists at the beginning of string, this option returns a character string from which that list of characters has been removed. If chars is not specified, white spaces are removed.
string trimright string [chars]	If a character contained in the character set specified by chars exists at the end of string, this option returns a character string from which that character has been removed. If chars is not specified, blank spaces are removed.
string wordend string index	Returns the position of the character just after the last one in the word containing the indexed (see Note) character in string.
string wordstart string index	Returns the position of the first character in the word containing the indexed (see Note) character in string.

Note:: The index represents the position in a string (nth character), when 0 corresponds to the first character.

Point

When using the string command to determine character strings, use the logical expression as shown below since complicated conditions cannot be specified with the command alone.

Example:

When string "AAA" or "BBB" is stored to variable EventText, it is displayed to standard output.

if {[string first "AAA" $EventText] > 0 || [string first "BBB" $EventText] > 0} {
  puts $EventText
}

Return Values

See the above table for each option.

Example

The following example extracts the first three characters from the string stored in the variable buf and stores them to the variable top.

set top [string range $buf 0 2]