1 //
2 // Copyright (c) 2006, Brian Frank and Andy Frank
3 // Licensed under the Academic Free License version 3.0
4 //
5 // History:
6 // 4 Dec 05 Brian Frank Creation
7 //
8
9 **
10 ** Str represents a sequence of Unicode characters.
11 **
12 const final class Str
13 {
14
15 //////////////////////////////////////////////////////////////////////////
16 // Constructor
17 //////////////////////////////////////////////////////////////////////////
18
19 **
20 ** Private constructor.
21 **
22 private new make()
23
24 //////////////////////////////////////////////////////////////////////////
25 // Obj Overrides
26 //////////////////////////////////////////////////////////////////////////
27
28 **
29 ** Return true if a Str with exact same char sequence.
30 **
31 override Bool equals(Obj obj)
32
33 **
34 ** Convenience for 'compareIgnoreCase(s) == 0'.
35 ** Only ASCII character case is taken into account.
36 ** See `localeCompare` for localized case insensitive
37 ** comparisions.
38 **
39 Bool equalsIgnoreCase(Str s)
40
41 **
42 ** Compare based on Unicode character values. Case is not
43 ** not taken into account - also see `compareIgnoreCase`
44 ** and `localeCompare`.
45 **
46 ** Examples:
47 ** "a".compare("b") -> -1
48 ** "hi".compare("hi") -> 0
49 ** "hi".compare("HI") -> 1
50 ** "b".compare("a") -> 1
51 **
52 override Int compare(Obj obj)
53
54 **
55 ** Compare two strings without regard to case and return -1, 0, or 1
56 ** if this string is less than, equal to, or greater than the specified
57 ** string. Only ASCII character case is taken into account.
58 ** See `localeCompare` for localized case insensitive comparisions.
59 **
60 ** Examples:
61 ** "a".compareIgnoreCase("b") -> -1
62 ** "hi".compareIgnoreCase("HI") -> 0
63 ** "b".compareIgnoreCase("a") -> 1
64 **
65 Int compareIgnoreCase(Str s)
66
67 **
68 ** The hash for a Str is platform dependent.
69 **
70 override Int hash()
71
72 **
73 ** Return this.
74 **
75 override Str toStr()
76
77 //////////////////////////////////////////////////////////////////////////
78 // Identity
79 //////////////////////////////////////////////////////////////////////////
80
81 **
82 ** Return if size() == 0.
83 **
84 Bool isEmpty()
85
86 **
87 ** Return number of characters in this string.
88 **
89 Int size()
90
91 **
92 ** Internalize this Str such that two strings which are equal
93 ** via the == operator will have the same reference such that
94 ** === will be true.
95 **
96 Str intern()
97
98 **
99 ** Return if this Str starts with the specified Str.
100 **
101 Bool startsWith(Str s)
102
103 **
104 ** Return if this Str ends with the specified Str.
105 **
106 Bool endsWith(Str s)
107
108 **
109 ** Return the first occurance of the specified substring searching
110 ** forward, starting at the specified offset index. A negative offset
111 ** may be used to access from the end of string. Return null if no
112 ** occurences are found.
113 **
114 ** Examples:
115 ** "abcabc".index("b") -> 1
116 ** "abcabc".index("b", 1) -> 1
117 ** "abcabc".index("b", 3) -> 4
118 ** "abcabc".index("b", -3) -> 4
119 ** "abcabc".index("x") -> null
120 **
121 Int index(Str s, Int offset := 0)
122
123 **
124 ** Reverse index - return the first occurance of the specified
125 ** substring searching backward, starting at the specified offset
126 ** index. A negative offset may be used to access from the end
127 ** of string. Return null if no occurences are found.
128 **
129 ** Examples:
130 ** "abcabc".indexr("b") -> 4
131 ** "abcabc".indexr("b", -3) -> 1
132 ** "abcabc".indexr("b", 0) -> null
133 **
134 Int indexr(Str s, Int offset := -1)
135
136 **
137 ** Return if this string contains the specified string.
138 ** Convenience for index(s) != null
139 **
140 Bool contains(Str s)
141
142 //////////////////////////////////////////////////////////////////////////
143 // Operators
144 //////////////////////////////////////////////////////////////////////////
145
146 **
147 ** Get the character at the zero based index as a Unicode code point.
148 ** Negative indexes may be used to access from the end of the string.
149 ** This method is accessed via the [] operator.
150 **
151 Int get(Int index)
152
153 **
154 ** Return a substring based on the specified range. Negative indexes
155 ** may be used to access from the end of the string. This method
156 ** is accessed via the [] operator. Throw IndexErr if range illegal.
157 **
158 ** Examples:
159 ** "abcd"[0..2] -> "abc"
160 ** "abcd"[3..3] -> "d"
161 ** "abcd"[-2..-1] -> "cd"
162 ** "abcd"[0...2] -> "ab"
163 ** "abcd"[1..-2] -> "bc"
164 ** "abcd"[4..-1] -> ""
165 **
166 Str slice(Range range)
167
168 **
169 ** Concat the value of obj.toStr
170 **
171 Str plus(Obj obj)
172
173 //////////////////////////////////////////////////////////////////////////
174 // Iterators
175 //////////////////////////////////////////////////////////////////////////
176
177 **
178 ** Call the specified function for every char in the starting
179 ** with index 0 and incrementing up to size-1. This method is
180 ** idempotent.
181 **
182 ** Example:
183 ** "abc".each |Int c| { echo(c.toChar) }
184 **
185 Void each(|Int ch, Int index| c)
186
187 **
188 ** Reverse each - call the specified function for every char in
189 ** the string starting with index size-1 and decrementing down
190 ** to 0. This method is idempotent.
191 **
192 ** Example:
193 ** "abc".eachr |Int c| { echo(c.toChar) }
194 **
195 Void eachr(|Int ch, Int index| c)
196
197 **
198 ** Return true if c returns true for any of the characters in
199 ** this string. If this string is empty, return false.
200 **
201 ** Example:
202 ** "Foo".any |Int c->Bool| { return c.isUpper } -> true
203 ** "foo".any |Int c->Bool| { return c.isUpper } -> false
204 **
205 Bool any(|Int ch, Int index->Bool| c)
206
207 **
208 ** Return true if c returns true for all of the characters in
209 ** this string. If this string is empty, return true.
210 **
211 ** Example:
212 ** "Bar".all |Int c->Bool| { return c.isUpper } -> false
213 ** "BAR".any |Int c->Bool| { return c.isUpper } -> true
214 **
215 Bool all(|Int ch, Int index->Bool| c)
216
217 //////////////////////////////////////////////////////////////////////////
218 // Utils
219 //////////////////////////////////////////////////////////////////////////
220
221 **
222 ** Get the a Str containing the specified number of spaces. Also
223 ** see `justl` and `justr` to justify an existing string.
224 **
225 ** Examples:
226 ** Str.spaces(1) -> " "
227 ** Str.spaces(2) -> " "
228 **
229 static Str spaces(Int n)
230
231 **
232 ** Return this string with all uppercase characters replaced
233 ** to lowercase. The case conversion is for ASCII only.
234 ** Also see `upper`, `localeLower`, `Int.lower`, `Int.localeLower`.
235 **
236 ** Example:
237 ** "Apple".lower -> "apple"
238 **
239 Str lower()
240
241 **
242 ** Return this string with all lowercase characters replaced
243 ** to uppercase. The case conversion is for ASCII only.
244 ** Also see `lower`, `localeUpper`, `Int.upper`, `Int.localeUpper`.
245 **
246 ** Example:
247 ** "Foo Bar".upper -> "FOO BAR"
248 **
249 Str upper()
250
251 **
252 ** Return this string with the first character converted
253 ** uppercase. The case conversion is for ASCII only.
254 ** Also see `decapitalize` and `localeCapitalize`.
255 **
256 ** Example:
257 ** "foo".capitalize -> "Foo"
258 **
259 Str capitalize()
260
261 **
262 ** Return this string with the first character converted
263 ** lowercase. The case conversion is for ASCII only.
264 ** Also see `capitalize` and `localeDecapitalize`.
265 **
266 ** Example:
267 ** "Foo".decapitalize -> "foo"
268 **
269 Str decapitalize()
270
271 **
272 ** If size is less than width, then add spaces to the right
273 ** to create a left justified string.
274 **
275 ** Examples:
276 ** "xyz".justl(2) -> "xyz"
277 ** "xyz".justl(4) -> "xyz "
278 **
279 Str justl(Int width)
280
281 **
282 ** If size is less than width, then add spaces to the left
283 ** to create a right justified string.
284 **
285 ** Examples:
286 ** "xyz".justr(2) -> "xyz"
287 ** "xyz".justr(4) -> " xyz"
288 **
289 Str justr(Int width)
290
291 **
292 ** Reverse the contents of this string.
293 **
294 ** Example:
295 ** "stressed".reverse -> "desserts"
296 **
297 Str reverse()
298
299 **
300 ** Trim whitespace from the beginning and end of the string. For the purposes
301 ** of this method, whitespace is defined as any character equal to or less
302 ** than the 0x20 space character (including ' ', '\r', '\n', and '\t').
303 **
304 ** Examples:
305 ** "foo".trim -> "foo"
306 ** " foo".trim -> "foo"
307 ** " foo\n".trim -> "foo"
308 **
309 Str trim()
310
311 **
312 ** Split a string into a list of substrings using the given separators
313 ** TODO: just temp hack
314 **
315 Str[] split(Str separators)
316
317 **
318 ** Replace all occurances of from with to.
319 ** TODO: just temp hack
320 **
321 Str replace(Str from, Str to)
322
323 **
324 ** Return if every character in this Str is whitespace: space \t \n \r \f
325 **
326 Bool isSpace()
327
328 **
329 ** Return if every character in this Str is ASCII uppercase: 'A'-'Z'.
330 **
331 Bool isUpper()
332
333 **
334 ** Return if every character in this Str is ASCII lowercase: 'a'-'z'.
335 **
336 Bool isLower()
337
338 //////////////////////////////////////////////////////////////////////////
339 // Locale
340 //////////////////////////////////////////////////////////////////////////
341
342 **
343 ** Compare two strings without regard to case according to the
344 ** current locale. Return -1, 0, or 1 if this string is less
345 ** than, equal to, or greater than the specified string.
346 **
347 ** Examples (assuming English locale):
348 ** "a".localeCompare("b") -> -1
349 ** "hi".localeCompare("HI") -> 0
350 ** "b".localeCompare("A") -> 1
351 **
352 Int localeCompare(Str s)
353
354 **
355 ** Return this string with all uppercase characters
356 ** replaced to lowercase using the current locale.
357 ** Also see `localeUpper`, `lower`, and `Int.localeLower`.
358 **
359 Str localeLower()
360
361 **
362 ** Return this string with all lowercase characters
363 ** replaced to uppercase using the current locale.
364 ** Also see `localeLower`, `upper`, and `Int.localeUpper`.
365 **
366 Str localeUpper()
367
368 **
369 ** Return this string with the first character
370 ** converted to uppercase using the current locale.
371 ** Also see `localeDecapitalize` and `capitalize`.
372 **
373 Str localeCapitalize()
374
375 **
376 ** Return this string with the first character
377 ** converted to lowercase using the current locale.
378 ** Also see `localeCapitalize` and `decapitalize`.
379 **
380 Str localeDecapitalize()
381
382 //////////////////////////////////////////////////////////////////////////
383 // Coersions
384 //////////////////////////////////////////////////////////////////////////
385
386 **
387 ** Convenience for `Bool.fromStr` using this string.
388 **
389 Bool toBool(Bool checked := true)
390
391 **
392 ** Convenience for `Int.fromStr` using this string.
393 **
394 Int toInt(Int radix := 10, Bool checked := true)
395
396 **
397 ** Convenience for `Float.fromStr` using this string.
398 **
399 Float toFloat(Bool checked := true)
400
401 **
402 ** Return this string as its Fan source code and serialization
403 ** representation surrounded by the specified quote character (which
404 ** defaults to '"'). If quote is null then the return is unquoted.
405 ** This method will backslash escape the following characters:
406 ** '\n \r \f \t \\ $'. If the quote character is the double quote,
407 ** single quote, or backtick then it is escaped too. If 'escapeUnicode'
408 ** is true then any character over 127 is also escaped as '\uXXXX'.
409 **
410 Str toCode(Int quote := '"', Bool escapeUnicode := false)
411
412 **
413 ** Convenience for `Uri.fromStr` using this string.
414 **
415 Uri toUri()
416
417 }