Strings
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.
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 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.
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.
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
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 <string> ?append strings ...?
string append is used to append a variable number of strings to a given
string, and the composed string is returned as a result.
The following invocation:
string append 1 2 abc "long string"
returns the string:
12abclong string
string build ?build strings ...?
string build explicitly creates one string from a number of given
build strings.
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 <string> <compare string>
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.
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 <string> <index>
string index returns the character at index in string.
The following code returns b, the character at index 2:
string index "a b c d" 2
string indexOf <string> <index string> ?startIndex?
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.
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 <string> <index string> ?startIndex?
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.
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 <string>
string length returns the length of the given string as an integer value.
The following code counts the length of a little string, which is 15.
string length "a little string"
string match ?-options ...? <string> <pattern>
Options: -regex, -pattern, or -exact
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.
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 ?-options ...? <string> <regex>
Options: -matches or -indices
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.
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 ?-options ...? <string> <target> <replacement>
Options: -first, -all, -regex, or -exact
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).
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 <string> <pos1> <pos2>
string subString returns the part of string ranging from pos1 to pos2.
pos1 and pos2 are integer indices.
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 <string>
string toLower returns the given string in lower-case characters.
The following code returns abc def:
string toLower "Abc Def"
string toUpper <string>
string toUpper returns the given string in upper-case characters.
The following code returns ABC DEF:
string toUpper "Abc Def"
string trim <string> ?trim strings?
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.
The following code returns XYZ without the trailing or leading whitespaces.
string trim " XYZ "
string trimLeft <string> ?trim strings?
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.
The following code returns XYZ without the leading whitespaces.
string trim " XYZ "
string trimRight <string> ?trim strings?
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.
The following code returns XYZ without the trailing whitespaces.
string trim " XYZ "