[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Strings Package

The SparForte built-in strings package provides subprograms to manipulate string and character values. (The 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 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

n := strings.count( s, p )

 

return the occurrences in string s of substring p

Example

n := strings.count( "baby", "b" ); -- returns 2

Parameters

Param Mode Type Default Description
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)

Exceptions

-

See Also

-

Compare With

Ada: Ada.Strings.Unbounded.Count
PHP: substr_count
Python: count

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. A bad position returns an empty string (like the Linux/UNIX cut command).

Example

s := strings.csv_field( "a/b/c", 2, '/' ); -- returns "b"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.field
strings.index
strings.lookup

Compare With

PHP: str_getcsv

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). 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"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.csv_field
strings.replace_slice

Compare With

PHP: str_putcsv

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"

Parameters

Param Mode Type Default Description
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

Exceptions

A bad position raises an exception.

See Also

strings.head
strings.slice
strings.tail

Compare With

Ada.Strings.Unbounded.Delete

c := strings.element( s, p )

 

return the character located at positive position p

Example

c := strings.element( "baby", 2 ); -- returns 'a'

Parameters

Param Mode Type Default Description
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

Exceptions

A bad position raises an exception.

See Also

strings.delete
strings.head
strings.slice
strings.tail

Compare With

Ada: Ada.Strings.Unbounded.Element

r := strings.field( s, c [, d] )

 

return the natural cth substring of s delimited by character d. A bad position returns an empty string (like the Linux/UNIX cut command).

Example

s := strings.field( "a/b/c", 2, '/' ); -- returns "b"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.csv_field
strings.index
strings.lookup
strings.replace

Compare With

Perl: split
PHP: explode

b := strings.glob( e, s )

 

return true if string globbing expression e. Globbing 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

Example

b := strings.glob( "app*", "apple" ); -- returns true

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.index
strings.match

Compare With

Ada: GNAT.RegPat.Match

Implementation Notes

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"

Parameters

Param Mode Type Default Description
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

Exceptions

A bad count raises an exception.

See Also

strings.delete
strings.element
strings.slice
strings.tail

Compare With

Ada: Ada.Strings.Unbounded.Head

r := strings.image( n )

 

Convert numeric value n to a string representation of the same value (inverse of numerics.value)

Example

r := strings.image( 35 ); -- retuns "35"

Parameters

Param Mode Type Default Description
n in universal_string required the number to convert
r return value string required the value as a string

Exceptions

-

See Also

numerics.value

Compare With

Ada: 'image attribute
PHP: strval

n := strings.index( s, p [, d] )

 

Return the first position of substring p in string s in direction d. Returns zero if the substring doesn't exist. The search is case-sensitive.

Example

n := strings.index( "catapult", "tap" ); -- returns 3

Parameters

Param Mode Type Default Description
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)

Exceptions

-

See Also

strings.csv_field
strings.field
strings.glob
strings.index_non_blank
strings.lookup
strings.match

Compare With

Ada: Ada.Strings.Unbounded.Index
Perl: index / rindex
PHP: strpos / strrpos
Python: find/index/rfind/rindex

n := strings.index_non_blank( s [,d] )

 

Return the first non-space position in string s in direction d. Returns zero if the string is all spaces.

Example

n := strings.index_non_blank( " moon" ); -- retuns 2

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.csv_field
strings.field
strings.glob
strings.index
strings.lookup
strings.match

Compare With

Ada: Ada.Strings.Unbounded.Index_Non_Blank

r := strings.insert( s, b, n )

 

Return a string with substring n inserted into string s before position positive b

Example

r := strings.insert( "ale", 2, "pp" ); -- returns "apple"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.overwrite

Compare With

Ada: Ada.Strings.Unbounded.Insert

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

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 alphanumeric

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Alphanumeric
PHP: ctype_alnum
Python: isalnum

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

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 basic

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Basic
Python: isalpha

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

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 control characters

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Control
PHP: ctype_cntrl

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

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 digits

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Digit
PHP: ctype_digit
Python: isnumeric

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

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

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 printable

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Graphic
PHP: ctype_graph

r := strings.is_hexadecimal_digit( s )

 

true if the string completely contains hexadecimal numeric characters.

Example

r := strings.is_hexadecimal_digit( "FE00" ); -- 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 hexadecimal

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Hexadecimal_Digit
PHP: ctype_xdigit

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

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 letters

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Letter
PHP: ctype_alpha
Python: isalpha

r := strings.is_lower( s )

 

True if the string completely contains Latin-1 lower-case letters.

Example

r := strings.is_lower( "hello" ); -- 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 lower-case letters

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Lower
PHP: ctype_lower
Python: islower

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

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 date

Exceptions

-

See Also

-

Compare With

-

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

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 special

Exceptions

-

See Also

-

Compare With

Ada: Ada.Character_Handling.Is_Special
PHP: ctype_punct

b := strings.is_typo_of( 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 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.

Example

r := strings.is_upper( "HELLO" ); -- 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 upper-case letters

Exceptions

-

See Also

strings.is_lower

Compare With

Ada: Ada.Character_Handling.Is_Upper
PHP: ctype_upper
Python: isupper

n := strings.length( s )

 

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"

Parameters

Param Mode Type Default Description
s in universal_string required the string to search
k in string required the key to find
d in character ASCII.CR the character delimiter
r return value string required the value of the key

Exceptions

-

See Also

strings.csv_field
strings.field
strings.glob
strings.index
strings.index_non_blank
strings.match

Compare With

-

b := strings.match( e, s )

 

Return true if the string matches regular expression with PERL extensions.

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

Example

b := strings.match( "^app", "apple" ); -- returns true

Parameters

Param Mode Type Default Description
s in universal_string required the string to search
e in string required the regular expression
b return value boolean required true if the pattern matched

Exceptions

-

See Also

strings.csv_field
strings.field
strings.glob
strings.index
strings.index_non_blank
strings.lookup

Compare With

Ada: GNAT.RegExp.Match
Perl: m//
PHP: preg_match

Implementation 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" );

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

-

Compare With

PHP: tempnam

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"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

strings.insert
strings.replace_slice

Compare With

Ada: Ada.Strings.Unbounded.Overwrite
PHP: substr_replace

strings.replace( s, f, t [, 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"

Parameters

Param Mode Type Default Description
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 character ASCII.CR the character delimiter

Exceptions

A bad low position will raise an exception.

See Also

strings.field
strings.lookup

Compare With

Python: replace

replace_slice( s, l, h, b )

 

Replace the characters in s between positions low l and high h with substring b

Example

strings.replace_slice( s, 2, 3, , 'foo' ); -- if s is "1234", it is now "1foo34"

Parameters

Param Mode Type Default Description
s in out universal_string required the string to change
l in positive required the position of the first character
h in natural required the position of the last character
b in universal_string required the new substring

Exceptions

A bad low position will raise an exception.

See Also

strings.insert
strings.overwrite

Compare With

-

strings.set_unbounded_string( u, s )

 

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"

Parameters

Param Mode Type Default Description
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

Exceptions

A bad count raises an exception.

See Also

strings.delete
strings.element
strings.head
strings.slice

Compare With

Ada: Ada.Strings.Unbounded.Tail

r := strings.to_basic( s )

 

Convert the string to basic letters (as defined for strings.is_basic).

Example

r := strings.to_basic( "hello" ); -- retuns "hello"

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 basic string

Exceptions

-

See Also

strings.is_basic

Compare With

Ada: Ada.Character_Handling.To_Basic

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]"

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 escaped string

Exceptions

-

See Also

-

Compare With

-

r := strings.to_lower( s )

 

Return the string in lower-case

Example

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.

Example

r := strings.to_json( "foobar" & ASCII.LF & "test" ); -- returns "foobar\ntest"

Parameters

Param Mode Type Default Description
s in string required the string expression to encode
r return value string required the JSON string

Exceptions

-

See Also

strings.to_string

Compare With

PHP: json_encode

r := strings.to_string( s )

 

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

Parameters

Param Mode Type Default Description
s in string required the string expression to encode
r return value string required the JSON string

Exceptions

Bad JSON data can raise exceptions

See Also

arrays.to_array
records.to_record
strings.to_string

Compare With

Ada: Ada.Strings.Unbounded.To_String
PHP: json_decode

u := strings.to_unbounded_string( s )

 

Convert string s to unbounded string u. For compatibility with Ada 95.

Example

unbounded_string := strings.to_unbounded_string( "test" );

Parameters

Param Mode Type Default Description
s in string required the fixed string to covert
u return value unbounded_string required the unbounded string

Exceptions

-

See Also

-

Compare With

-

r := strings.to_upper( s )

 

Return the string in upper-case

Example

n := strings.to_upper( "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 upper-case string

Exceptions

-

See Also

strings.is_upper

Compare With

PHP: strtoupper
Python: upper

r := strings.trim( s [, e] )

 

Remove leading and/or trailing spaces (depending on e) from string s

Example

r := strings.trim( "  many  " ); -- returns "many"

Parameters

Param Mode Type Default Description
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

Exceptions

-

See Also

-

Compare With

Ada: Ada.Strings.Unbounded.Trim
PHP: trim
Python: strip

r := strings.unbounded_slice( s, l, h )

 

Return a substring between the positions positive l and natural h. For compatibility with Ada—normally use strings.slice.

Example

r := strings.unbounded_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 unbounded_string required the new string

Exceptions

-

See Also

strings.slice

Compare With

Ada: Ada.Strings.Unbounded.Unbounded_Slice

c := strings.val( n )

 

Return the ASCII character with value n (inverse of numerics.pos)

Example

r := strings.val( 65 ); -- returns 'A'

Parameters

Param Mode Type Default Description
n in natural required the ASCII value
c return value character required the character

Exceptions

-

See Also

-

Compare With

Ada: 'val attribute
PHP: ord

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]