string

string is an ensemble of routines for manipulating strings.

See Also

everything is a string

Format

string forward compatibility

Additional string functions

string compare ...

regmap, by SS

Apply scripts to matching substrings.

Documentation

official reference

Synopsis

string bytelength string

string cat ?string ...?
(new in Tcl 8.6.2)

string compare ?-nocase? ?-length int? string1 string2

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

string first string1 string2 ?startIndex?

string index string charIndex

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

string last string1 string2 ?startIndex?

string length string

string map ?-nocase? charMap string

string match ?-nocase? pattern string

string range string first last

string repeat string count

string replace string first last ?newstring?

string reverse string

string tolower string ?first? ?last?

string totitle string ?first? ?last?

string toupper string ?first? ?last?

string trim string ?chars?

string trimleft string ?chars?

string trimright string ?chars?

string wordend string charIndex

string wordstart string charIndex

Missing Functionality

pyk 2020-04-08: string is currently missing a routine, perhaps called string common, that indicates the character at which two strings diverge. Desirable options include -start and -direction.

Misc

Is this correct behavior?

% set str {} 
% string is true $str
1
% string is false $str
1
% string is integer $str
1
% string is alpha $str
1

Sadly, yes, that is correct. You'll have to use the -strict option to keep empty strings from passing all tests.

This is an unfortunate legacy from the origin of string is as a tool for entry validation, where it's important the empty string pass everything so that every input doesn't fail immediately.

Using string Functions for Binary data

In Tcl, working with binary data generally means retricting the characters in a value to the first 256 unicode characters so that the value can be neatly sent through a channel that is configured to -translation binary, where character is encoded as a single byte that has the same value as the unicode value of the character. In other words, binary data is just text that meets certain constrains.

Internally, Tcl sometimes stores binary data in a more compact form than it uses for textual data that contains a broader ranger of characters. It's not typically necesary to be aware of these internals, here is a list of routines that, as of 8.5 may take advantage of an internal ByteArray representation.

• string range
• string index
• string match
• string length
• string compare (both objects must be ByteArrays)

The following routines user an internal String type containing an array of unicode characters:

• string first
• string last
• string map
• string replace
• string reverse

MG: Since Tcl 8.5, an index in the string commands can include basic math;

string range $string $startChar+1 $endChar-1

is now equivalent to

string range $string [expr {$startChar + 1}] [expr {$endChar - 1}]

While the first may be clearer, though, it seems to be (potentially quite a lot) slower for me, running 8.5a6:

% set string "This is a test string"
This is a test string
% set startChar 3
3
% set endChar 12
12

% time {string range $string [expr {$startChar+1}] [expr {$endChar-1}]} 500000
2.55498 microseconds per iteration
% time {string range $string $startChar+1 $endChar-1} 500000
5.092856 microseconds per iteration

Using expr there is quite drastically faster...