|
This part of the guide contains detailed descriptions of the
BUSH built-in packages.
4.8 Strings Package
The BUSH strings package provides string operations. (Character positions
are numbered from 1.)
GCC Ada equivalent: Ada.Strings.Unbounded, GNAT.Regexp, GNAT.Regpat
Ada implements three different kinds of strings: standard "fixed" strings,
bounded strings and unbounded strings. They are implemented in different
packages and are incompatible with one another. The standard strings are
implemented as arrays and cannot be used in BUSH since AdaScript has no
array capabilities. BUSH implements strings as Ada unbounded strings.
For ease of use, string literals (like "hello world") are universal_string
types in AdaScript, but are fixed string types in Ada. String literals
should properly be converted to an unbounded string using the to_unbounded_string
(to_unbounded_string( "hello world" ) even though AdaScript doesn't enforce
this.
Likewise unbounded strings should be declared as "unbounded_string"
type variables. For ease of use, BUSH uses "string" instead.
When porting a script to Ada, unbounded_string types, to_unbounded_string
and to_string functions should be used.
There are 5 enumerated types used by the string functions:
- strings.alignment - alignment.left, alignment.right or alignment.center
- strings.truncation - truncation.left, truncation.right or truncation.error
- strings.membership - membership.inside or membership.outside
- strings.direction - direction.forward or direction.backward
- strings.trim_end - trim_end.left, trim_end.right or trim_end.both
n := strings.count( s, p )
return the occurrences in string s of substring p
Example: n := strings.count( "baby", "b" ); -- returns 2
Ada Equivalent: Ada.Strings.Unbounded.Count
Parameters:
s |
in |
universal_string |
required |
the string to check |
p |
in |
string |
required |
the substring to search for |
n |
return value |
natural |
required |
the number of occurrences (0 if none) |
|
r := strings.csv_field( s, c [, d] )
return the natural cth substring of s delimited by character d (typically
a comma). Double quotes will escape the delimiter. For use with Comma
Separated Value files.
Example: s := strings.csv_field( "a/b/c", 2, '/' ); -- returns "b"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the string to search |
c |
in |
natural |
required |
the field position (1 for first field) |
d |
in |
character |
',' |
the character delimiter |
r |
return value |
string |
required |
the field |
|
A bad position returns an empty string (like the Linux/UNIX cut command).
r := strings.csv_replace( s, f, t, [, d] )
replace the natural fth substring of s delimited by character d (typically
a comma) with string t. Double quotes will escape the delimiter. For use
with Comma Separated Value files (or ASCII.TAB for tab separated value file).
Example: strings.csv_replace( "a/b/c", 2, "x", '/' ); -- now "a/x/c"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in out |
universal_string |
required |
the string to search |
f |
in |
natural |
required |
the field position (1 for first field) |
t |
in |
string |
required |
the new field value |
d |
in |
character |
',' |
the character delimiter |
r |
return value |
string |
required |
the field |
|
A bad position returns an empty string (like the Linux/UNIX cut command).
r := strings.delete( s, l, h )
return a string with character positions positive l to natural h deleted
Example: r := strings.delete( "bowl", 4, 4 ); -- returns "bow"
Ada Equivalent: Ada.Strings.Unbounded.Delete
Parameters:
s |
in |
universal_string |
required |
the string to change |
l |
in |
positive |
required |
low position to delete (1 is the start of the string). |
h |
in |
natural |
required |
the high position to delete. |
n |
return value |
natural |
required |
the string with the positions removed |
|
A bad position raises an exception.
c := strings.element( s, p )
return the character located at positive position p
Example: c := strings.element( "baby", 2 ); -- returns 'a'
Ada Equivalent: Ada.Strings.Unbounded.Element
Parameters:
s |
in |
universal_string |
required |
the string to search |
p |
in |
positive |
required |
the string position (1 is the first character). |
c |
return value |
character |
required |
the character |
|
A bad position raises an exception.
r := strings.field( s, c [, d] )
return the natural cth substring of s delimited by character d. This is
similar to PERL split.
Example: s := strings.field( "a/b/c", 2, '/' ); -- returns "b"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the string to search |
c |
in |
natural |
required |
the field position (1 for first field) |
d |
in |
character |
ASCII.CR |
the character delimiter |
r |
return value |
string |
required |
the field |
|
A bad position returns an empty string (like the Linux/UNIX cut command).
b := strings.glob( e, s )
return true if string globbing expression e
Example: b := strings.glob( "app*", "apple" ); -- returns true
Ada Equivalent: GNAT.RegPat.Match (Note: Match not Glob)
Parameters:
s |
in |
universal_string |
required |
the string to search |
e |
in |
string |
required |
the globbing pattern to use |
b |
return value |
boolean |
required |
true if the pattern matched |
|
Glob characters include:
-
* - zero or more characters
-
? - a single character
-
[...] - a set of characters
-
[^...] - any not in set of characters
-
[c1...c2] - a range of characters between c1 and c2
r := strings.head( s, c [, p] )
return the first natural c characters of string s
Example: r := strings.head( "minimum", 3 ); -- returns "min"
Ada Equivalent: Ada.Strings.Unbounded.Head
Parameters:
s |
in |
universal_string |
required |
the string to search |
c |
in |
natural |
required |
the number of characters (0 for none) |
p |
in |
character |
' ' |
character to pad with if string is short |
r |
return value |
string |
required |
the substring |
|
A bad count raises an exception.
r := strings.is_alphanumeric( s )
true if the string completely contains alphanumeric chararacters (that is,
the same as is_letter and is_digit).
Example: r := strings.is_alphanumeric( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Alphanumeric does the equivalent for a single
character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is alphanumeric |
|
r := strings.is_basic( s )
true if the string completely contains basic Latin-1 letters (A..Z, a..z,
AE Diphtong, Icelandic Eth, Icelandic Thorn, German Sharp S). Accented
characters are not included.
Example: r := strings.basic( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Basic
does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is basic |
|
r := strings.is_control( s )
true if the string completely contains control chararacters (ASCII/Latin-1
0..31 and 127..159).
Example: r := strings.control( "hello" ); -- returns false
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Control does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is control characters |
|
r := strings.is_digit( s )
true if the string completely contains numeric digits (ASCII/Latin-1
48..57).
Example: r := strings.is_digit( "1234567890" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Digit does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is digits |
|
r := strings.is_fixed( s )
true if the string appears to be a fixed point number (that is, a number
with a decimal point). No check is made to see if the number is
representable by AdaScript.
Example: r := strings.is_fixed( "340.12" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is a number with a decimal point |
|
r := strings.is_graphic( s )
true if the string completely contains printable characters (that is,
not is_control).
Example: r := strings.is_graphic( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Graphic does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is printable |
|
r := strings.is_hexadecimal_digit( s )
true if the string completely contains hexadecimal numeric characters.
Example: r := strings.is_hexadecimal_digit( "FE00" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Hexadecimal_Digit does the equivalent for a single
character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is hexadecimal |
|
r := strings.is_letter( s )
true if the string completely contains Latin-1 letters (that is, is_basic
plus accented characters).
Example: r := strings.is_letter( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Letter does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is letters |
|
r := strings.is_lower( s )
true if the string completely contains Latin-1 lower-case letters.
Example: r := strings.is_lower( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Lower does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is lower-case letters |
|
r := strings.is_slashed_date( s )
true if the string appears to be an 8 or 10 character slashed
date. No check is made to see if the date is a real date.
Example: r := strings.is_slashed_date( "11/22/2003" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is a date |
|
r := strings.is_special( s )
true if the string completely contains special printable characters such
as punctuation marks (that is, is_graphic and not is_alphanumeric).
Example: r := strings.is_special( "!" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Special does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is special |
|
b := strings.is_typo_is( s1, s2 )
true if the string s1 is similar to s2. false if the strings are the
same, if the strings are too short to test or if the strings are very
different. The function is case-sensitive. This is the same algorithm used
by BUSH to check for identifiers with spelling mistakes.
Example: b := strings.is_typo_of( "apple", "app1e" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Parameters:
s1 |
in |
universal_string |
required |
the first string to compare |
s2 |
in |
universal_string |
required |
the second string to compare |
b |
return value |
string |
required |
true if the strings are a possible typo |
|
r := strings.is_upper( s )
true if the string completely contains Latin-1 upper-case letters.
Example: r := strings.is_upper( "HELLO" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.Is_Upper does the equivalent for a single character.
Parameters:
s |
in |
universal_string |
required |
the string to test |
r |
return value |
string |
required |
true if the string is upper-case letters |
|
r := strings.image( n )
convert numeric n to a string (inverse of numerics.value)
Example: r := strings.image( 35 ); -- retuns "35"
Ada Equivalent: 'image attribute
Parameters:
n |
in |
universal_string |
required |
the number to convert |
r |
return value |
string |
required |
the value as a string |
|
n := strings.index( s, p [, d] )
Return the first position of substring p in string s. Similar to
PERL index and rindex.
Example: n := strings.index( "catapult", "tap" ); -- returns 3
Ada Equivalent: Ada.Strings.Unbounded.Index
Parameters:
s |
in |
universal_string |
required |
the string to search |
p |
in |
string |
required |
the substring to find |
d |
in |
strings.direction |
direction.forward |
the direction of the search (forward from start or backward from end) |
n |
return value |
natural |
required |
the position of the match (0 if none) |
|
n n := strings.index_non_blank( s [,d] )
return the first non-blank position in string s
Example: n := strings.index_non_blank( " moon" ); -- retuns 2
Ada Equivalent: Ada.Strings.Unbounded.Index_Non_Blank
Parameters:
s |
in |
universal_string |
required |
the string to search |
d |
in |
strings.direction |
direction.forward |
the direction of the search |
n |
return value |
natural |
required |
the position of the first character that is not a space |
|
r := strings.insert( s, b, n )
return a string with substring n inserted before position positive
b
Example: r := strings.insert( "ale", 2, "pp" ); -- returns "apple"
Ada Equivalent: Ada.Strings.Unbounded.Insert
Parameters:
s |
in |
universal_string |
required |
the string to insert another string into |
b |
in |
positive |
required |
the position to insert the substring |
n |
in |
string |
required |
the substring to insert |
r |
return value |
string |
required |
the new string |
|
n := strings.length( s )
return the number of characters in the string
Example: n := strings.length( "bounce" ); -- retuns 6
Ada Equivalent: Ada.Strings.Unbounded.Length
Parameters:
s |
in |
universal_string |
required |
the string to count |
n |
return value |
natural |
required |
the number of characters |
|
r := strings.lookup( s, t [, d] )
s contains pairs of substrings delimited by character d. Return the
right-hand substring of the pair beginning with left-hand field t.
Example: s := strings.lookup( "a/b/c/d", "c", '/' ); -- returns "d" from pair "c/d"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the string to search |
t |
in |
string |
required |
the left-hand field of the string pairs to find |
d |
in |
character |
ASCII.CR |
the character delimiter |
r |
return value |
string |
required |
the right-hand string of the pair |
|
A bad position returns an empty string.
b := strings.match( e, s )
return true if string matches regular expression with PERL extensions.
This is similar to PERL m//.
Example: b := strings.match( "^app", "apple" ); -- returns true
Ada Equivalent: GNAT.RegExp.Match
Parameters:
s |
in |
universal_string |
required |
the string to search |
e |
in |
string |
required |
the regular expression with PERL extensions to use |
b |
return value |
boolean |
required |
true if the pattern matched |
|
Match characters include:
-
^ - at beginning
-
. - any character
-
$ - at end
-
? - zero or one character
-
[s] - any in set s
-
+ - one or more characters
-
[^s] - any not in set s
-
* - zero or more characters
-
\ - escape character
-
(e) - nested expression
-
| - alternative
Note: There's a known bug in GNAT 3.12 and 3.13 which causes strings.match
to fail.
r := strings.mktemp( p )
make a temporary file name using template p (like UNIX/Linux mktemp
command)
Example: r := strings.mktemp( "tempXXXXXX" );
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the path template ending with 6 dummy characters |
r |
return value |
string |
required |
the path with the dummy characters replaced with random characters |
|
r := strings.overwrite( s, p, n )
return a string with substring n overwriting positions starting at
positive p
Example: r := strings.overwrite( "goose", 2, "ee" ); -- returns "geese"
Ada Equivalent: Ada.Strings.Unbounded.Overwrite
Parameters:
s |
in |
universal_string |
required |
the string to overwrite |
p |
in |
positive |
required |
the position to start replacing characters |
n |
in |
string |
required |
the substring to replace characters with |
r |
return value |
string |
required |
the new string |
|
strings.replace( s, f, t [, d] )
s contains substrings delimited by character d. Replace the fth substring
field with new substring t.
Example: strings.replace( s, 2, "*", '/' ); -- if s is "a/b/c", it is now "a/*/c"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in out |
universal_string |
required |
the string to change |
f |
in |
natural |
required |
the index of the field to change |
t |
in |
universal_string |
required |
the new substring |
d |
in |
charater |
ASCII.CR |
the character delimiter |
|
A bad position returns an empty string.
r := strings.replace_slice( s, l, h, n )
return a string with positions positive l to natural h replaced by
substring n
Example: r := strings.replace_slice( "goose", 2, 3, "ee" ); -- returns
"geese"
Ada Equivalent: Ada.Strings.Unbounded.Replace_Slice
Parameters:
s |
in |
universal_string |
required |
the string to overwrite |
l |
in |
positive |
required |
low position to start replacing characters |
h |
in |
natural |
required |
high position to finish replacing characters |
n |
in |
string |
required |
the substring to replace characters with |
r |
return value |
string |
required |
the new string |
|
A bad low position will raise an exception.
r := strings.slice( s, l, h )
return a substring between the positions positive l and natural h
Example: r := strings.slice( "realize", 2, 4 ); -- returns "eal"
Ada Equivalent: Ada.Strings.Unbounded.Slice
Parameters:
s |
in |
universal_string |
required |
the string to overwrite |
l |
in |
positive |
required |
low position to start replacing characters |
h |
in |
natural |
required |
high position to finish replacing characters |
n |
in |
string |
required |
the substring to replace characters with |
r |
return value |
string |
required |
the new string |
|
A bad low position will raise an exception.
strings.split( s, l, r , p )
split string s into a left substring l and a right substring r at or to the
left of character position p. split will attempt to split on the nearest
space.
Example: strings.split( "hello there", l, r, 9 ); -- l is "hello " and r is "there"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the string to split |
l |
out |
unbounded_string |
required |
the left substring of s |
r |
out |
universal_string |
required |
the right substring of s |
p |
in |
natural |
required |
the maximum width of the left substring |
|
A bad position will be constrained to legal values.
r := strings.tail( s, c [, p] )
return the last natural c characters of string s
Example: r := strings.tail( "maximum", 3 ); -- returns "mum"
Ada Equivalent: Ada.Strings.Unbounded.Head
Parameters:
s |
in |
universal_string |
required |
the string to search |
c |
in |
natural |
required |
the number of characters (0 for none) |
p |
in |
character |
' ' |
character to pad with if string is short |
r |
return value |
string |
required |
the substring |
|
A bad count raises an exception.
r := strings.to_basic( s )
convert the string to basic letters (as defined for is_basic).
Example: r := strings.to_basic( "hello" ); -- retuns "hello"
Ada Equivalent: none (AdaScript extension).
Ada.Character_Handling.To_Basic does the equivalent for a single character.
Parameters:
s |
in |
string or character type |
required |
the string to change |
r |
return value |
string or character type |
required |
the basic string |
|
r := strings.to_escaped( s )
convert the string to printable character by replacing control characters
with "[# n]" where n is the ASCII/Latin-1 position.
Example: r := strings.to_escaped( "hello" & ASCII.CR ); -- retuns "hello[# 13]"
Ada Equivalent: none (AdaScript extension).
Parameters:
s |
in |
string or character type |
required |
the string to change |
r |
return value |
string or character type |
required |
the escaped string |
|
r := strings.to_lower( s )
return the string in lower-case
Example: r := strings.to_lower( "bOunce" ); -- retuns "bounce"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
string or character type |
required |
the string to change |
r |
return value |
string or character type |
required |
the lower-case string |
|
r := strings.to_proper( s )
return the string in proper (or mixed or title) case
Example: n := strings.to_proper( "proper" ); -- retuns "Proper"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
string or character type |
required |
the string to change |
r |
return value |
string or character type |
required |
the proper-case string |
|
s := strings.to_string( u )
convert unbounded string s to string s
Example: s := strings.to_string( some_unbounded_string );
Ada Equivalent: Ada.Strings.Unbounded.To_String
Parameters:
u |
in |
unbounded_string |
required |
the unbounded string to covert |
s |
return value |
string |
required |
the fixed string |
|
u := strings.to_unbounded_string( s )
convert unbounded string s to string s
Example: u unbounded_string := strings.to_unbounded_string( "test"
);
Ada Equivalent: Ada.Strings.Unbounded.To_Unbounded_String
Parameters:
s |
in |
string |
required |
the fixed string to covert |
u |
return value |
unbounded_string |
required |
the unbounded string |
|
r := strings.to_upper( s )
return the string in upper-case
Example: n := strings.to_upperr( "BoUNCE" ); -- retuns "BOUNCE"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
string or character type |
required |
the string to change |
r |
return value |
string or character type |
required |
the upper-case string |
|
r := strings.trim( s [, e] )
remove leading and/or trailing spaces from string s
Example: r := strings.trim( " many " ); -- returns "many"
Ada Equivalent: none (AdaScript extension)
Parameters:
s |
in |
universal_string |
required |
the string to trim |
e |
in |
strings.trim_end |
trim_end.both |
the end(s) of string to trim |
r |
return value |
string |
required |
the new string |
|
c := strings.val( n )
return the ASCII character with value n (inverse of numerics.pos)
Example: r := strings.val( 65 ); -- returns 'A'
Ada Equivalent: 'val attribute
Parameters:
n |
in |
natural |
required |
the ASCII value |
c |
return value |
character |
required |
the character |
|
Back to Top
|