====================================================================
String examples
====================================================================

The type String provides character strings.  Character strings
provide all the operations for a one-dimensional array of characters,
plus additional operations for manipulating text.  

String values can be created using double quotes.

  hello := "Hello, I'm AXIOM!"
    "Hello, I'm AXIOM!"
                               Type: String

Note, however, that double quotes and underscores must be preceded by
an extra underscore.

  said := "Jane said, \_"Look!\_""
    "Jane said, \"Look!\""
                               Type: String

  saw := "She saw exactly one underscore: \_\_." 
    "She saw exactly one underscore: \\."
                               Type: String

It is also possible to use new to create a string of any size filled
with a given character.  Since there are many new functions it is
necessary to indicate the desired type.

  gasp: String := new(32, char "x")
    "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                               Type: String

The length of a string is given by #.

  #gasp
    32
                               Type: PositiveInteger

Indexing operations allow characters to be extracted or replaced in strings.
For any string s, indices lie in the range 1..#s.

  hello.2
    e
                               Type: Character

Indexing is really just the application of a string to a subscript, so
any application syntax works.

  hello 2
    e
                               Type: Character

  hello(2)
    e
                               Type: Character

If it is important not to modify a given string, it should be copied
before any updating operations are used.

  hullo := copy hello
    "Hello, I'm AXIOM!"
                               Type: String

  hullo.2 := char "u"; [hello, hullo]
    ["Hello, I'm AXIOM!","Hullo, I'm AXIOM!"]
                               Type: List String

Operations are provided to split and join strings.  The concat
operation allows several strings to be joined together.

  saidsaw := concat ["alpha","---","omega"]
    "alpha---omega"
                               Type: String

There is a version of concat that works with two strings.

  concat("hello ","goodbye")
    "hello goodbye"
                               Type: String

Juxtaposition can also be used to concatenate strings.

  "This " "is " "several " "strings " "concatenated."
    "This is several strings concatenated."
                               Type: String

Substrings are obtained by giving an index range.

  hello(1..5)
    "Hello"
                               Type: String

  hello(8..)
    "I'm AXIOM!"
                               Type: String

A string can be split into several substrings by giving a separation
character or character class.

  split(hello, char " ")
    ["Hello,","I'm","AXIOM!"]
                               Type: List String

  other := complement alphanumeric();
                               Type: CharacterClass

  split(saidsaw, other)
    ["alpha","omega"]
                               Type: List String

Unwanted characters can be trimmed from the beginning or end of a string
using the operations trim, leftTrim and rightTrim.

  trim("## ++ relax ++ ##", char "#")
    " ++ relax ++ "
                               Type: String

Each of these functions takes a string and a second argument to specify
the characters to be discarded.

  trim("## ++ relax ++ ##", other)
    "relax"
                               Type: String

The second argument can be given either as a single character or as a
character class.

  leftTrim("## ++ relax ++ ##", other)
    "relax ++ ##"
                               Type: String

  rightTrim("## ++ relax ++ ##", other)
    "## ++ relax"
                               Type: String

Strings can be changed to upper case or lower case using the
operations upperCase and lowerCase.

  upperCase hello
    "HELLO, I'M AXIOM!"
                               Type: String

The versions with the exclamation mark change the original string,
while the others produce a copy.

  lowerCase hello
    "hello, i'm axiom!"
                               Type: String

Some basic string matching is provided.  The function prefix? tests
whether one string is an initial prefix of another.

  prefix?("He", "Hello")
    true
                               Type: Boolean

  prefix?("Her", "Hello")
    false
                               Type: Boolean

A similar function, suffix?, tests for suffixes.

  suffix?("", "Hello")
    true
                               Type: Boolean

  suffix?("LO", "Hello")
    false
                               Type: Boolean

The function substring? tests for a substring given a starting position.

  substring?("ll", "Hello", 3)
    true
                               Type: Boolean

  substring?("ll", "Hello", 4)
    false
                               Type: Boolean

A number of position functions locate things in strings.  If the first
argument to position is a string, then position(s,t,i) finds the
location of s as a substring of t starting the search at position i.

  n := position("nd", "underground", 1)
    2
                               Type: PositiveInteger

  n := position("nd", "underground", n+1)
    10
                               Type: PositiveInteger

If s is not found, then 0 is returned (minIndex(s)-1 in IndexedString).

  n := position("nd", "underground", n+1)
    0
                               Type: NonNegativeInteger

To search for a specific character or a member of a character class,
a different first argument is used.

  position(char "d", "underground", 1)
    3
                               Type: PositiveInteger

  position(hexDigit(), "underground", 1)
    3
                               Type: PositiveInteger

See Also:
o )help Character
o )help CharacterClass
o )show String

