logo

const class

sys::Str

sys::Obj
  sys::Str
   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  }