====================================================================
String
====================================================================

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 FriCAS!"
    "Hello, I'm FriCAS!"
                               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 FriCAS!"
                               Type: String

  hullo.2 := char "u"; [hello, hullo]
    ["Hello, I'm FriCAS!","Hullo, I'm FriCAS!"]
                               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 FriCAS!"
                               Type: String

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

  split(hello, char " ")
    ["Hello,","I'm","FriCAS!"]
                               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 FRICAS!"
                               Type: String

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

  lowerCase hello
    "hello, i'm fricas!"
                               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:

* )help Character
* )help CharacterClass
* )show String
* $AXIOM/doc/src/algebra/string.spad.dvi