Business Shell (BUSH) Guide
Author: Ken Burtch

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