1====================================================================
2String examples
3====================================================================
4
5The type String provides character strings.  Character strings
6provide all the operations for a one-dimensional array of characters,
7plus additional operations for manipulating text.
8
9String values can be created using double quotes.
10
11  hello := "Hello, I'm FriCAS!"
12    "Hello, I'm FriCAS!"
13                               Type: String
14
15Note, however, that double quotes and underscores must be preceded by
16an extra underscore.
17
18  said := "Jane said, \_"Look!\_""
19    "Jane said, \"Look!\""
20                               Type: String
21
22  saw := "She saw exactly one underscore: \_\_."
23    "She saw exactly one underscore: \\."
24                               Type: String
25
26It is also possible to use new to create a string of any size filled
27with a given character.  Since there are many new functions it is
28necessary to indicate the desired type.
29
30  gasp: String := new(32, char "x")
31    "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
32                               Type: String
33
34The length of a string is given by #.
35
36  #gasp
37    32
38                               Type: PositiveInteger
39
40Indexing operations allow characters to be extracted or replaced in strings.
41For any string s, indices lie in the range 1..#s.
42
43  hello.2
44    e
45                               Type: Character
46
47Indexing is really just the application of a string to a subscript, so
48any application syntax works.
49
50  hello 2
51    e
52                               Type: Character
53
54  hello(2)
55    e
56                               Type: Character
57
58If it is important not to modify a given string, it should be copied
59before any updating operations are used.
60
61  hullo := copy hello
62    "Hello, I'm FriCAS!"
63                               Type: String
64
65  hullo.2 := char "u"; [hello, hullo]
66    ["Hello, I'm FriCAS!","Hullo, I'm FriCAS!"]
67                               Type: List String
68
69Operations are provided to split and join strings.  The concat
70operation allows several strings to be joined together.
71
72  saidsaw := concat ["alpha","---","omega"]
73    "alpha---omega"
74                               Type: String
75
76There is a version of concat that works with two strings.
77
78  concat("hello ","goodbye")
79    "hello goodbye"
80                               Type: String
81
82Juxtaposition can also be used to concatenate strings.
83
84  "This " "is " "several " "strings " "concatenated."
85    "This is several strings concatenated."
86                               Type: String
87
88Substrings are obtained by giving an index range.
89
90  hello(1..5)
91    "Hello"
92                               Type: String
93
94  hello(8..)
95    "I'm FriCAS!"
96                               Type: String
97
98A string can be split into several substrings by giving a separation
99character or character class.
100
101  split(hello, char " ")
102    ["Hello,","I'm","FriCAS!"]
103                               Type: List String
104
105  other := complement alphanumeric();
106                               Type: CharacterClass
107
108  split(saidsaw, other)
109    ["alpha","omega"]
110                               Type: List String
111
112Unwanted characters can be trimmed from the beginning or end of a string
113using the operations trim, leftTrim and rightTrim.
114
115  trim("## ++ relax ++ ##", char "#")
116    " ++ relax ++ "
117                               Type: String
118
119Each of these functions takes a string and a second argument to specify
120the characters to be discarded.
121
122  trim("## ++ relax ++ ##", other)
123    "relax"
124                               Type: String
125
126The second argument can be given either as a single character or as a
127character class.
128
129  leftTrim("## ++ relax ++ ##", other)
130    "relax ++ ##"
131                               Type: String
132
133  rightTrim("## ++ relax ++ ##", other)
134    "## ++ relax"
135                               Type: String
136
137Strings can be changed to upper case or lower case using the
138operations upperCase and lowerCase.
139
140  upperCase hello
141    "HELLO, I'M FRICAS!"
142                               Type: String
143
144The versions with the exclamation mark change the original string,
145while the others produce a copy.
146
147  lowerCase hello
148    "hello, i'm fricas!"
149                               Type: String
150
151Some basic string matching is provided.  The function prefix? tests
152whether one string is an initial prefix of another.
153
154  prefix?("He", "Hello")
155    true
156                               Type: Boolean
157
158  prefix?("Her", "Hello")
159    false
160                               Type: Boolean
161
162A similar function, suffix?, tests for suffixes.
163
164  suffix?("", "Hello")
165    true
166                               Type: Boolean
167
168  suffix?("LO", "Hello")
169    false
170                               Type: Boolean
171
172The function substring? tests for a substring given a starting position.
173
174  substring?("ll", "Hello", 3)
175    true
176                               Type: Boolean
177
178  substring?("ll", "Hello", 4)
179    false
180                               Type: Boolean
181
182A number of position functions locate things in strings.  If the first
183argument to position is a string, then position(s,t,i) finds the
184location of s as a substring of t starting the search at position i.
185
186  n := position("nd", "underground", 1)
187    2
188                               Type: PositiveInteger
189
190  n := position("nd", "underground", n+1)
191    10
192                               Type: PositiveInteger
193
194If s is not found, then 0 is returned (minIndex(s)-1 in IndexedString).
195
196  n := position("nd", "underground", n+1)
197    0
198                               Type: NonNegativeInteger
199
200To search for a specific character or a member of a character class,
201a different first argument is used.
202
203  position(char "d", "underground", 1)
204    3
205                               Type: PositiveInteger
206
207  position(hexDigit(), "underground", 1)
208    3
209                               Type: PositiveInteger
210
211See Also:
212o )help Character
213o )help CharacterClass
214o )show String
215o $AXIOM/doc/src/algebra/string.spad.dvi
216
217