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 SparForte since AdaScript had no
array capabilities. SparForte 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, SparForte 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
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. A bad position returns an empty string (like the Linux/UNIX cut command).
Example
s := strings.csv_field( "a/b/c", 2, '/' ); -- returns "b"
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). A bad position returns an empty string (like the Linux/UNIX cut command).
Example
strings.csv_replace( "a/b/c", 2, "x", '/' ); -- now "a/x/c"
This should rightly be strings.match but the name conflicts with the
other strings.match. Glob also is a more descriptive name.
r := strings.head( s, c [, p] )
Return the first natural c characters of string s. If the number of
characters is greater than the strings, the remaining characters will be
padded using character p
Example
r := strings.head( "minimum", 3 ); -- returns "min"
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.
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
Parameters
Param
Mode
Type
Default
Description
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
Exceptions
-
See Also
-
Compare With
-
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
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 SparForte to check for identifiers with spelling mistakes.
Example
b := strings.is_typo_of( "apple", "app1e" ); -- returns true
Parameters
Param
Mode
Type
Default
Description
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
Exceptions
-
See Also
-
Compare With
PHP: levenshtein / similar_text
r := strings.is_upper( s )
True if the string completely contains Latin-1 upper-case letters.
Return the number of characters in the string. Returns zero if the string is empty.
Example
n := strings.length( "bounce" ); -- retuns 6
Parameters
Param
Mode
Type
Default
Description
s
in
universal_string
required
the string to count
n
return value
natural
required
the number of characters
Exceptions
-
See Also
-
Compare With
Ada: Ada.Strings.Unbounded.Length PHP: strlen Python: len
r := strings.lookup( s, k [, d] )
String s contains pairs of key-value substrings delimited by character d. Return the right-hand (value) substring of the pair beginning with left-hand (key) field k. An empty string is returned if the key is not found.
Example
s := strings.lookup( "a/b/c/d", "c", '/' ); -- returns "d" from pair "c/d"
s contains substring fields delimited by character d. Replace the fth substring field with new substring t. No change is made for a position that doesn't exist.
Example
strings.replace( s, 2, "*", '/' ); -- if s is "a/b/c", it is now "a/*/c"
Set unbounded string u with the value of string s. Provided for Ada 2005 compatibility.
Example
strings.set_unbounded_string( u, "foo" ); -- u is now "foo"
Parameters
Param
Mode
Type
Default
Description
u
in out
unbounded_string
required
the string to set
s
in
string
required
the string to provide the value
Exceptions
-
See Also
-
Compare With
Ada: Ada.Strings.Unbounded.Set_Unbounded_String
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"
Parameters
Param
Mode
Type
Default
Description
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
r
return value
string
required
the new string
Exceptions
A bad low position will raise an exception.
See Also
-
Compare With
Ada: Ada.Strings.Unbounded.Slice PHP: substr
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. A bad position will be constrained to legal values.
Example
strings.split( "hello there", l, r, 9 ); -- l is "hello " and r is "there"
Parameters
Param
Mode
Type
Default
Description
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
Exceptions
-
See Also
-
Compare With
PHP: wordwrap
r := strings.tail( s, c [, p] )
Return the last natural c characters of string s
Example
r := strings.tail( "maximum", 3 ); -- returns "mum"
r := strings.to_lower( "bOunce" ); -- retuns "bounce"
Parameters
Param
Mode
Type
Default
Description
s
in
string or character type
required
the string to change
r
return value
string or character type
required
the lower-case string
Exceptions
-
See Also
-
Compare With
PHP: strtolower Python: lower
r := strings.to_proper( s )
Return the string in proper (or mixed or title) case
Example
n := strings.to_proper( "proper" ); -- retuns "Proper"
Parameters
Param
Mode
Type
Default
Description
s
in
string or character type
required
the string to change
r
return value
string or character type
required
the proper-case string
Exceptions
-
See Also
-
Compare With
PHP: ucwords
r := strings.to_json( s )
Return the JSON encoding of the string. Encoding arbitrary control characters with \u is not yet supported, though carriage returns, line feeds, etc. are supported.
Convert unbounded string s to string s. If u is a json_string, convert JSON encoding of a string into the original string. Encoding arbitrary control characters with \u is not yet supported, though carriage returns, line feeds, etc. are supported. universal_string types (including string literals) are not accepted.
Example
s := strings.to_string( some_unbounded_string ); r := strings.to_string( json_string( ASCII.Quotation & "foobar\ntest" & ASCII.Quotation ) ); -- returns a string with foobar, a line feed, and test