% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.
\newcommand{\StringXmpTitle}{String}
\newcommand{\StringXmpNumber}{9.77}
%
% =====================================================================
\begin{page}{StringXmpPage}{9.77 String}
% =====================================================================
\beginscroll

The type \spadtype{String} provides character strings.
Character strings provide all the operations for a one-dimensional array
of characters, plus additional operations for manipulating text.
For more information on related topics, see \downlink{`Character'}{CharacterXmpPage}\ignore{Character} and
\downlink{`CharacterClass'}{CharacterClassXmpPage}\ignore{CharacterClass}.
You can also issue the system command \spadcmd{)show String} to display
the full list of operations defined by \spadtype{String}.

\xtc{
String values can be created using double quotes.
}{
\spadpaste{hello := "Hello, I'm AXIOM!" \bound{hello}}
}
\xtc{
Note, however, that double quotes and underscores must be preceded by
an extra underscore.
}{
\spadpaste{said  := "Jane said, _"Look!_"" \bound{said}}
}
\xtc{
}{
\spadpaste{saw   := "She saw exactly one underscore: __." \bound{saw}}
}
\xtc{
It is also possible to use \spadfunFrom{new}{String} to create a string of any size
filled with a given character.
Since there are many \spadfun{new} functions
it is necessary to indicate the desired type.
}{
\spadpaste{gasp: String := new(32, char "x") \bound{gasp}}
}
\xtc{
The length of a string is given by \spadopFrom{\#}{List}.
}{
\spadpaste{\#gasp \free{gasp}}
}
\xtc{
Indexing operations allow characters to be extracted or replaced in strings.
For any string \spad{s}, indices lie in the range \spad{1..\#s}.
}{
\spadpaste{hello.2 \free{hello}}
}
\xtc{
Indexing is really just the application of a string to a subscript,
so any application syntax works.
}{
\spadpaste{hello 2  \free{hello}}
}
\xtc{
}{
\spadpaste{hello(2) \free{hello}}
}
\xtc{
If it is important not to modify a given string, it should be copied
before any updating operations are used.
}{
\spadpaste{hullo := copy hello \free{hello}\bound{hullo0}}
}
\xtc{
}{
\spadpaste{hullo.2 := char "u"; [hello, hullo] \free{hullo0 hello}\bound{hullo}}
}

\xtc{
Operations are provided to split and join strings.
The \spadfunFrom{concat}{String} operation allows several strings to be joined
together.
}{
\spadpaste{saidsaw := concat ["alpha","---","omega"] \bound{saidsaw}}
}
\xtc{
There is a version of \spadfunFrom{concat}{String} that works with
two strings.
}{
\spadpaste{concat("hello ","goodbye")}
}
\xtc{
Juxtaposition can also be used to concatenate strings.
}{
\spadpaste{"This " "is " "several " "strings " "concatenated."}
}
\xtc{
Substrings are obtained by giving an index range.
}{
\spadpaste{hello(1..5) \free{hello}}
}
\xtc{
}{
\spadpaste{hello(8..) \free{hello}}
}
\xtc{
A string can be split into several substrings by giving a separation character
or character class.
}{
\spadpaste{split(hello, char " ")              \free{hello}}
}
\xtc{
}{
\spadpaste{other := complement alphanumeric(); \bound{other}}
}
\xtc{
}{
\spadpaste{split(saidsaw, other)               \free{saidsaw other}}
}
\xtc{
Unwanted characters can be trimmed from the beginning or end of a string
using the operations \spadfunFrom{trim}{String}, \spadfunFrom{leftTrim}{String}
and \spadfunFrom{rightTrim}{String}.
}{
\spadpaste{trim     ("\#\# ++ relax ++ \#\#", char "\#")}
}
\xtc{
Each of these functions takes a string and a second argument to specify
the characters to be discarded.
}{
\spadpaste{trim     ("\#\# ++ relax ++ \#\#", other) \free{other}}
}
\xtc{
The second argument can be given
either as a single character or as a character class.
}{
\spadpaste{leftTrim ("\#\# ++ relax ++ \#\#", other) \free{other}}
}
\xtc{
}{
\spadpaste{rightTrim("\#\# ++ relax ++ \#\#", other) \free{other}}
}

\xtc{
Strings can be changed to upper case or lower case using the operations
\spadfunFrom{upperCase}{String}, \spadfunFromX{upperCase}{String}, \spadfunFrom{lowerCase}{String} and
\spadfunFromX{lowerCase}{String}.
}{
\spadpaste{upperCase hello \free{hello}}
}
\xtc{
The versions with the exclamation mark
change the original string, while the others produce a copy.
}{
\spadpaste{lowerCase hello \free{hello}}
}

\xtc{
Some basic string matching is provided.
The function \spadfunFrom{prefix?}{String}
tests whether one string is an initial prefix of another.
}{
\spadpaste{prefix?("He", "Hello")}
}
\xtc{
}{
\spadpaste{prefix?("Her", "Hello")}
}
\xtc{
A similar function, \spadfunFrom{suffix?}{String}, tests for suffixes.
}{
\spadpaste{suffix?("", "Hello")}
}
\xtc{
}{
\spadpaste{suffix?("LO", "Hello")}
}
\xtc{
The function \spadfunFrom{substring?}{String} tests for a substring given a starting
position.
}{
\spadpaste{substring?("ll", "Hello", 3)}
}
\xtc{
}{
\spadpaste{substring?("ll", "Hello", 4)}
}

\xtc{
A number of \spadfunFrom{position}{String} functions locate things in strings.
If the first argument to position is a string, then \spad{position(s,t,i)}
finds the location of \spad{s} as a substring of \spad{t} starting the
search at position \spad{i}.
}{
\spadpaste{n := position("nd", "underground",   1) \bound{n}}
}
\xtc{
}{
\spadpaste{n := position("nd", "underground", n+1) \free{n} \bound{n1}}
}
\xtc{
If \spad{s} is not found, then \spad{0} is returned (\spad{minIndex(s)-1}
in \spadtype{IndexedString}).
}{
\spadpaste{n := position("nd", "underground", n+1) \free{n1}\bound{n2}}
}
\xtc{
To search for a specific character or a member of a character class,
a different first argument is used.
}{
\spadpaste{position(char "d", "underground", 1)}
}
\xtc{
}{
\spadpaste{position(hexDigit(), "underground", 1)}
}

\endscroll
\autobuttons
\end{page}
%