BlueScript: String Procedures
Contents
Description
Procedures for manipulating strings.
Procedures
append
Usage
append var string
Returns
The contents of variable var after appending
string.
Appends string to the contents of variable var.
Note that the variable is passed as the variable name and not
as a variable substitution (i.e. the '$' is not prepended).
This allows the procedure to modify the variable itself. This
is generally more efficient than using string constructs and
setting the variable. For example, the following command
append x data
has the same effect as:
set x "${x}data"
but the append procedure avoids copying the string.
This can greatly improve performance, especially if data is
being appended to a large string.
Examples
1. Appending to a string
set x "Hello"
append x ", World!"
Result: Hello, World!
script
Usage
script string
Returns
A list built by splitting string in the same
manner as a script.
Splits a string using the rules for parsing scripts. This
means:
- each element corresponds to a line (unless the end-of-line
character is escaped
or quoted)
- blank lines and lines beginning with '#' (comments) are
ignored
Note that only parsing rules are applied - there is no
evaluation or substitution that is otherwise applied.
Examples
1. Splitting a string like a script
script {# this is a
comment
set x 40
set y 50
struct {
line
}
}
Result: {set x 40} {set y 50} {struct {
line
}}
split
Usage
split string [chars]
Returns
A list built by splitting string using
chars as delimiters.
Splits a string into a list using the given delimiters. If
chars is not specified then the set of white-space
characters is used. Empty elements are not discarded.
A special case is when chars is specified as an empty
string. In this case, string will be split into a
string where each element is exactly one character long.
Examples
1. Splitting a string
split abc::d:ef:g :
Result: abc {} d ef g
2. Splitting a string into characters
split {abc def} {}
Result: a b c { } d e f
stris
Usage
stris (integer|float|number|blank) string
Returns
True (1) if the string matches the given type or false
(0) if the string does not match.
The following types are recognized:
- integer - any of the BlueScript integer forms
(signed, unsigned, decimal, octal, hexadecimal)
- float - any of the BlueScript floating-point
forms
- number - true if the argument matches either the
float or integer representations
- blank - true if the argument is either empty or
comprised solely of white-space characters.
Examples
1. Checking for an integer
stris integer 124
Result: 1
2. Checking for an (incorrect) integer
stris integer R12F
Result: 0
strlen
Usage
strlen string
Returns
The length of string in characters.
Examples
1. Determining the length of a string
strlen "abcdefg"
Result: 7
strltrim
Usage
strltrim string [trimchars]
Returns
The string with any character in trimchars removed
from the left of the string.
Trims unwanted characters from the left of a
string. If trimchars is not specified, then it
defaults to the set of white-space characters.
Examples
1. Left-trimming a string
strtrim
{ foo }
Result: foo
strrtrim
Usage
strrtrim string [trimchars]
Returns
The string with any character in trimchars removed
from the right of the string.
Trims unwanted characters from the right of a
string. If trimchars is not specified, then it
defaults to the set of white-space characters.
Examples
1. Right-trimming a string
strtrim
{ foo }
Result: foo
strstr
Usage
strstr string sub
Returns
The offset of the first occurrence of string sub
in string or -1 if the string cannot be found.
Finds the location of a string (sub) within another
string (string). If the string is found, the offset of
the first occurrence (i.e. the left-most occurrence) is
returned. If the sub-string occurs at the beginning of the
string, then the offset is 0, if it occurs at the second
character, the offset is 1, etc.
Examples
1. Finding a substring
strstr foobar bar
Result: 3
2. Searching for a non-existent substring
strstr foobar
bug
Result: -1
strtrim
Usage
strtrim string [trimchars]
Returns
The string with any character in trimchars removed
from the left and the right.
Trims unwanted characters from the left and right of a
string. If trimchars is not specified, then it
defaults to the set of white-space characters.
Examples
1. Trimming a string
strtrim
{ foo }
Result: foo
substr
Usage
substr string start [length]
Returns
A substring of string of length characters
starting at offset start.
Extracts a substring of string starting at offset
start. An offset of 0 corresponds to the beginning of
the string. The substring will be length characters
long. If length is not specified, then the substring
will run to the end of string.
Examples
1. Extracting a substring
substr foobar 1 3
Result: oob
2. Extracting a substring to the end
substr foobar 1
Result: oobar