
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



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 \xmpref{Character} and
\xmpref{CharacterClass}.
You can also issue the system command \spadsys{)show String} to display
the full list of operations defined by \spadtype{String}.

\xtc{
String values can be created using double quotes.
}{
\spadcommand{hello := "Hello, I'm FriCAS!" \bound{hello}}
}
\xtc{
Note, however, that double quotes and underscores must be preceded by
an extra underscore.
}{
\spadcommand{said  := "Jane said, \_"Look!\_"" \bound{said}}
}
\xtc{
}{
\spadcommand{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.
}{
\spadcommand{gasp: String := new(32, char "x") \bound{gasp}}
}
\xtc{
The length of a string is given by \spadopFrom{#}{List}.
}{
\spadcommand{\#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}.
}{
\spadcommand{hello.2 \free{hello}}
}
\xtc{
Indexing is really just the application of a string to a subscript,
so any application syntax works.
}{
\spadcommand{hello 2  \free{hello}}
}
\xtc{
}{
\spadcommand{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.
}{
\spadcommand{hullo := copy hello \free{hello}\bound{hullo0}}
}
\xtc{
}{
\spadcommand{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.
}{
\spadcommand{saidsaw := concat ["alpha","---","omega"] \bound{saidsaw}}
}
\xtc{
There is a version of \spadfunFrom{concat}{String} that works with
two strings.
}{
\spadcommand{concat("hello ","goodbye")}
}
\xtc{
Juxtaposition can also be used to concatenate strings.
}{
\spadcommand{"This " "is " "several " "strings " "concatenated."}
}
\xtc{
Substrings are obtained by giving an index range.
}{
\spadcommand{hello(1..5) \free{hello}}
}
\xtc{
}{
\spadcommand{hello(8..) \free{hello}}
}
\xtc{
A string can be split into several substrings by giving a separation character
or character class.
}{
\spadcommand{split(hello, char " ")              \free{hello}}
}
\xtc{
}{
\spadcommand{other := complement alphanumeric(); \bound{other}}
}
\xtc{
}{
\spadcommand{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}.
}{
\spadcommand{trim     ("\#\# ++ relax ++ \#\#", char "\#")}
}
\xtc{
Each of these functions takes a string and a second argument to specify
the characters to be discarded.
}{
\spadcommand{trim     ("\#\# ++ relax ++ \#\#", other) \free{other}}
}
\xtc{
The second argument can be given
either as a single character or as a character class.
}{
\spadcommand{leftTrim ("\#\# ++ relax ++ \#\#", other) \free{other}}
}
\xtc{
}{
\spadcommand{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}.
}{
\spadcommand{upperCase hello \free{hello}}
}
\xtc{
The versions with the exclamation mark
change the original string, while the others produce a copy.
}{
\spadcommand{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.
}{
\spadcommand{prefix?("He", "Hello")}
}
\xtc{
}{
\spadcommand{prefix?("Her", "Hello")}
}
\xtc{
A similar function, \spadfunFrom{suffix?}{String}, tests for suffixes.
}{
\spadcommand{suffix?("", "Hello")}
}
\xtc{
}{
\spadcommand{suffix?("LO", "Hello")}
}
\xtc{
The function \spadfunFrom{substring?}{String} tests for a substring given a starting
position.
}{
\spadcommand{substring?("ll", "Hello", 3)}
}
\xtc{
}{
\spadcommand{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}.
}{
\spadcommand{n := position("nd", "underground",   1) \bound{n}}
}
\xtc{
}{
\spadcommand{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}).
}{
\spadcommand{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.
}{
\spadcommand{position(char "d", "underground", 1)}
}
\xtc{
}{
\spadcommand{position(hexDigit(), "underground", 1)}
}
