Frag Logo
  Frag Home | Frag SF Project   index | contents | previous | next

Strings

Strings as Data Structures

One of the fundamental data structures in Frag, besides objects, are strings. Everything, including objects, can be represented as a string. Objects, for instance, have their object name as string representation. Lists, have the printed list structure with curly braces as their string representation.

Internally, Frag often converts strings to other data structures. For instance, if a string is handed to an expression for a calculation, Frag internally tries to convert it to a number, and if this fails, Frag yields an error.

String Matching

Frag supports a number of different alternatives for matching strings. Sometimes the matched strings can be object names or list elements. In many operations, such as list search or string match, different matching variants can be given as options. The operations for introspecting objects, methods, and variables, such as interp getObjects or Object's getClasses, accept a pattern argument. If such a pattern is given, Pattern Matching is performed (as described below).

Exact Matching

Exact matching means that a character by character comparison of the string is performed. If it is specified by an option, -exact is used. For instance, list search -exact uses exact matching.

Pattern Matching

In many case in Frag a simple form of pattern matching is used, following glob pattern matching as defined in Tcl. If it is specified by an option, -pattern is used. For instance, the following list search searches for all matches starting with 2, indicated by the * in 2*
list search -all -pattern {1 2 3 4 12 22 23} 2*

For a detailed description of the pattern matching syntax, see Tcl Glob Pattern Matching.

Regular Expression Matching

In many case in Frag it is possible to use regular expression matching. Then a Java regular expression can be used to specify the match pattern.

For instance, string match -regex can be used to check, whether there is a regex match in a string or not:
string match -regex {my text has "some text" and "some more text" in quotes} {"([^"]*)"}

This would yield true, because there are two matches in the string.

We can get the list of matches using string regex:
string regex {my text has "some text" and "some more text" in quotes} {"([^"]*)"}
This would return the list:
{"some text"} {"some more text"}
Finally, we could use string replace -regex to e.g. replace the double quotes with single quotes:
string replace -regex -all {my text has "some text" and "some more text" in quotes} {"([^"]*)"} {'$1'}
This would return:
my text has 'some text' and 'some more text' in quotes

String Manipulation

The command string offers a number of methods for manipulating strings. Each of the methods of string are presented below. All string methods have no side effect on the strings used as input - they only manipulate the resulting string.

string append

Syntax

string append <string> ?append strings ...?

Description

string append is used to append a variable number of strings to a given string, and the composed string is returned as a result.

Example

The following invocation:
string append 1 2 abc "long string"
returns the string:
12abclong string

string build

Syntax

string build ?build strings ...?

Description

string build explicitly creates one string from a number of given build strings.

Example

The following code builds up a string from four input strings. It produces the string "abc d ef".
set str [string build a b "c d e" f]
The following code demonstrates a typical use of string build, which assembles various unparsed region fragments and variable accesses into one string:
set r [string build `if {[list length $args] == 0} {
    if {![self varExists `$name`]} {
        return ""
    }
    self set `$name`}`]

string compare

Syntax

string compare <string> <compare string>

Description

string compare compares two strings lexicographically, and returns -1, 0, or 1, depending on whether string is lexicographically less than, equal to, or greater than compare string.

Example

The following code returns 0 because the two strings are equal.
string compare abcde abcde
The following code returns -1 because the first string is lexicographically less than the second.
string compare abcde abcdef

string index

Syntax

string index <string> <index>

Description

string index returns the character at index in string.

Example

The following code returns b, the character at index 2:
string index "a b c d" 2

string indexOf

Syntax

string indexOf <string> <index string> ?startIndex?

Description

string indexOf returns the index of the first occurrence of index string in string. Optionally startIndex can be given: Then the search is started at this index. -1 is returned, if index string does not occur in string.

Example

The following code returns 6 because ddd occurs first at the index 6 of the given string.
string indexOf "a b c ddd edsd ddd ddd" ddd
The following code returns -1 because a does not occur in abcde after index 1.
string indexOf abcde a 1

string lastIndexOf

Syntax

string lastIndexOf <string> <index string> ?startIndex?

Description

string lastIndexOf returns the index of the last occurrence of index string in string. Optionally startIndex can be given: Then the search is started at this index (going backwards through the string). -1 is returned, if index string does not occur in string.

Example

The following code returns 19 because this is the character index of the last occurrence of ddd in the string.
string lastIndexOf "a b c ddd edsd ddd ddd" ddd
The following code returns 0 because from character index 2 backwards, we find the occurrence of a in the string at index 0.
string lastIndexOf abcde a 2

string length

Syntax

string length <string>

Description

string length returns the length of the given string as an integer value.

Example

The following code counts the length of a little string, which is 15.
string length "a little string"

string match

Syntax

string match ?-options ...? <string> <pattern>
Options: -regex, -pattern, or -exact

Description

string match is used to test whether a specific string matches a given pattern or not. It returns 1, if the string matches the pattern, and 0 if not. The pattern matching can either be an exact matching, a pattern matching or a regex matching, which is defined using an option. Exact matching is the default, if no option is given or when -exact is used. -pattern selects pattern matching (see Section Pattern Matching). Using -regex a regular expression (see Section Regular Expression Matching) can be used to specify the pattern.

Examples

The following invocation:
string match "a b c" "a b c"
returns 1 because the strings match exactly. In contrast, the invocation
string match "a b c" "a b"
returns 0 because the strings do not match.

If simple pattern matching is selected, the following returns 1:
string match -pattern "a b c" a*
Alternatively, a regex-based match can be applied using a Java regex, such as in the following examples:
string match -regex "z r d" {[^abc]*}
string match -regex "a b c" "\[^abc\]*"
string match -regex "z r d" "\[^abc\]*"

string regex

Syntax

string regex ?-options ...? <string> <regex>
Options: -matches or -indices

Description

string regex applies a regular expression (see Section Regular Expression Matching) on a string. Per default it returns all matches of the regular expression in the string (also specified using the -matches option). Alternatively, you can also retrieve the (starting) indices of those matches using the -indices option.

Example

The following code returns a b, the two matches for the regular expression.
string regex "a b c" a?b*
You can also retrieve the (starting) indices of the same regular expression match, which would return 0 2:
string regex -indices "a b c" a?b*
The following code returns a b bbbbbb a abbbb abbbbbb, because the string contains multiple matches for the regular expression.
string regex "a b bbbbbb aabbbb abbbbbb" a?b*
You can also retrieve the (starting) indices of the same regular expression match, which would return 0 2 4 11 12 18:
string regex -indices "a b bbbbbb aabbbb abbbbbb" a?b*

string replace

Syntax

string replace ?-options ...? <string> <target> <replacement>
Options: -first, -all, -regex, or -exact

Description

string replace replaces a part of string that is specified by target with replacement.

target is per default searched exactly. This can also be specified by the -exact option. As an alternative, -regex can be used. Then a regular expression (see Section Regular Expression Matching) can be used to specify the target.

Per default, only the first match is replaced (specified via the -first option). Alternatively, all matches can be replaced (specified via the -all option).

Example

The following code returns abc because only the first (exact) occurence of abc is replaced. The result is: defdefabc.
string replace "abcdefabc" abc def
Using the -all modifier means that both occurrences are replaced, and the result is: defdefdef.
string replace "abcdefabc" abc def
The following code uses a Java regular expression for matching and replaces all matches of a?b with def. Hence the result is: adefxaaadefa.
string replace -regex -all "aabxaaaaba" a?b "def"

string subString

Syntax

string subString <string> <pos1> <pos2>

Description

string subString returns the part of string ranging from pos1 to pos2. pos1 and pos2 are integer indices.

Example

The following code returns the part of the string 012345678 from index 2 until before index 4, which is : 23.
string subString "012345678" 2 4

string toLower

Syntax

string toLower <string>

Description

string toLower returns the given string in lower-case characters.

Example

The following code returns abc def:
string toLower "Abc Def"

string toUpper

Syntax

string toUpper <string>

Description

string toUpper returns the given string in upper-case characters.

Example

The following code returns ABC DEF:
string toUpper "Abc Def"

string trim

Syntax

string trim <string> ?trim strings?

Description

string trim cuts characters on the left and right sides of string. Per default all white space characters are trimmed, but optionally trim strings can be given.

Example

The following code returns XYZ without the trailing or leading whitespaces.
string trim "    XYZ      "

string trimLeft

Syntax

string trimLeft <string> ?trim strings?

Description

string trimLeft cuts characters from the left side of string. Per default all white space characters are trimmed, but optionally trim strings can be given.

Example

The following code returns XYZ without the leading whitespaces.
string trim "    XYZ      "

string trimRight

Syntax

string trimRight <string> ?trim strings?

Description

string trimRight cuts characters from the right side of "string". Per default all white space characters are trimmed, but optionally trim strings can be given.

Example

The following code returns XYZ without the trailing whitespaces.
string trim "    XYZ      "

  index | contents | previous | next