[BUSH User Guide]
 
Home Page Introduction Tutorials Reference Packages Hacking
 
  Packages  
4.1 Using Packages
4.2 text_io (Console I/O)
4.3 text_io (File I/O)
4.4 sound
4.5 source_info
4.6 System
4.7 numerics
4.8 strings
4.9 command_line
4.10 lock_files
4.11 cgi
4.12 calendar
4.13 units
4.14 arrays
4.15 files
4.16 db (Database)
4.17 stats
4.18 pen
4.19 mysql
4.20 os
4.21 directory_operations
 
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