const class sys::Str

sys::Obj
  sys::Str

Source

Str represents a sequence of Unicode characters.

all

Bool all(|Int,Int->Bool| c)

Source

Return true if c returns true for all of the characters in this string. If this string is empty, return true.

Example:

"Bar".all |c| { c.isUpper } => false
"BAR".all |c| { c.isUpper } => true

any

Bool any(|Int,Int->Bool| c)

Source

Return true if c returns true for any of the characters in this string. If this string is empty, return false.

Example:

"Foo".any |c| { c.isUpper } => true
"foo".any |c| { c.isUpper } => false

capitalize

Str capitalize()

Source

Return this string with the first character converted uppercase. The case conversion is for ASCII only. Also see decapitalize and localeCapitalize.

Example:

"foo".capitalize => "Foo"

chars

Int[] chars()

Source

Get the characters in this string as a list of integer code points. Also see fromChars.

compare

virtual override Int compare(Obj obj)

Source

Compare based on Unicode character values. Case is not taken into account - also see compareIgnoreCase and localeCompare.

Examples:

"a".compare("b")    =>  -1
"hi".compare("hi")  =>  0
"hi".compare("HI")  =>  1
"b".compare("a")    =>  1

compareIgnoreCase

Int compareIgnoreCase(Str s)

Source

Compare two strings without regard to case and return -1, 0, or 1 if this string is less than, equal to, or greater than the specified string. Only ASCII character case is taken into account. See localeCompare for localized case insensitive comparisions.

Examples:

"a".compareIgnoreCase("b")    =>  -1
"hi".compareIgnoreCase("HI")  =>  0
"b".compareIgnoreCase("a")    =>  1

contains

Bool contains(Str s)

Source

Return if this string contains the specified string. Convenience for index(s) != null

containsChar

Bool containsChar(Int ch)

Source

Return if this string contains the specified character.

decapitalize

Str decapitalize()

Source

Return this string with the first character converted lowercase. The case conversion is for ASCII only. Also see capitalize and localeDecapitalize.

Example:

"Foo".decapitalize => "foo"

defVal

const static Str defVal

Source

Default value is "".

each

Void each(|Int,Int| c)

Source

Call the specified function for every char in the string with index 0 and incrementing up to size-1.

Example:

"abc".each |Int c| { echo(c.toChar) }

eachWhile

Obj? eachWhile(|Int,Int->Obj?| c)

Source

Iterate each character in the string until the function returns non-null. If function returns non-null, then break the iteration and return the resulting object. Return null if the function returns null for every item.

eachr

Void eachr(|Int,Int| c)

Source

Reverse each - call the specified function for every char in the string starting with index size-1 and decrementing down to 0.

Example:

"abc".eachr |Int c| { echo(c.toChar) }

endsWith

Bool endsWith(Str s)

Source

Return if this Str ends with the specified Str.

equals

virtual override Bool equals(Obj? obj)

Source

Return true if a Str with exact same char sequence.

equalsIgnoreCase

Bool equalsIgnoreCase(Str s)

Source

Convenience for compareIgnoreCase(s) == 0. Only ASCII character case is taken into account. See localeCompare for localized case insensitive comparisions.

fromChars

static Str fromChars(Int[] chars)

Source

Construct a string from a list of unicode code points. Also see chars.

fromDisplayName

Str fromDisplayName()

Source

Translate a display name like "Foo Bar" to a programmatic name "fooBar". This method decapitalizes the first letter, then walks the string removing spaces. Also see toDisplayName.

Examples:

"Foo".fromDisplayName         ->  "foo"
"Foo Bar".fromDisplayName     ->  "fooBar"
"Foo Bar Baz".fromDisplayName ->  "fooBarBaz"
"Foo 33 Bar".fromDisplayName  ->  "foo33Bar"
"Foo XML".fromDisplayName     ->  "fooXML"
"foo bar".fromDisplayName     ->  "fooBar"

get

@Operator
Int get(Int index)

Source

Get the character at the zero based index as a Unicode code point. Negative indexes may be used to access from the end of the string. This method is accessed via the [] operator. Throw IndexErr if the index is out of range.

getRange

@Operator
Str getRange(Range range)

Source

Return a substring based on the specified range. Negative indexes may be used to access from the end of the string. This method is accessed via the [] operator. Throw IndexErr if range illegal.

Examples:

"abcd"[0..2]   => "abc"
"abcd"[3..3]   => "d"
"abcd"[-2..-1] => "cd"
"abcd"[0..<2]  => "ab"
"abcd"[1..-2]  => "bc"
"abcd"[4..-1]  => ""

getSafe

Int getSafe(Int index, Int def := 0)

Source

Get the character at the zero based index as a Unicode code point. Negative indexes may be used to access from the end of the string. Unlike get, this method does not throw IndexErr when the index is out or range, instead it returns def.

hash

virtual override Int hash()

Source

The hash for a Str is platform dependent.

in

InStream in()

Source

Create an input stream to read characters from this string. The input stream is designed only to read character data. Attempts to perform binary reads will throw UnsupportedErr.

index

Int? index(Str s, Int offset := 0)

Source

Return the first occurrence of the specified substring searching forward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurrences are found.

Examples:

"abcabc".index("b")     => 1
"abcabc".index("b", 1)  => 1
"abcabc".index("b", 3)  => 4
"abcabc".index("b", -3) => 4
"abcabc".index("x")     => null

indexIgnoreCase

Int? indexIgnoreCase(Str s, Int offset := 0)

Source

Find the index just like index, but ignoring case for ASCII chars only.

indexr

Int? indexr(Str s, Int offset := -1)

Source

Reverse index - return the first occurrence of the specified substring searching backward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurrences are found.

Examples:

"abcabc".indexr("b")     => 4
"abcabc".indexr("b", -3) => 1
"abcabc".indexr("b", 0)  => null

indexrIgnoreCase

Int? indexrIgnoreCase(Str s, Int offset := -1)

Source

Find the index just like indexr, but ignoring case for ASCII chars only.

intern

Str intern()

Source

Internalize this Str such that two strings which are equal via the == operator will have the same reference such that === will be true.

isAlpha

Bool isAlpha()

Source

Return if every char is an ASCII letter.

isAlphaNum

Bool isAlphaNum()

Source

Return if every char is an ASCII alpha-numeric.

isAscii

Bool isAscii()

Source

Return if every character in this Str is a US-ASCII character less than 128.

isEmpty

Bool isEmpty()

Source

Return if size() == 0.

isLower

Bool isLower()

Source

Return if every character in this Str is ASCII lowercase: a-'z'.

isSpace

Bool isSpace()

Source

Return if every character in this Str is whitespace: space \t \n \r \f

isUpper

Bool isUpper()

Source

Return if every character in this Str is ASCII uppercase: A-'Z'.

justl

Str justl(Int width)

Source

If size is less than width, then add spaces to the right to create a left justified string. Also see padr.

Examples:

"xyz".justl(2) => "xyz"
"xyz".justl(4) => "xyz "

justr

Str justr(Int width)

Source

If size is less than width, then add spaces to the left to create a right justified string. Also see padl.

Examples:

"xyz".justr(2) => "xyz"
"xyz".justr(4) => " xyz"

localeCapitalize

Str localeCapitalize()

Source

Return this string with the first character converted to uppercase using the current locale. Also see localeDecapitalize and capitalize.

localeCompare

Int localeCompare(Str s)

Source

Compare two strings without regard to case according to the current locale. Return -1, 0, or 1 if this string is less than, equal to, or greater than the specified string.

Examples (assuming English locale):

"a".localeCompare("b")   =>  -1
"hi".localeCompare("HI") =>  0
"b".localeCompare("A")   =>  1

localeDecapitalize

Str localeDecapitalize()

Source

Return this string with the first character converted to lowercase using the current locale. Also see localeCapitalize and decapitalize.

localeLower

Str localeLower()

Source

Return this string with all uppercase characters replaced to lowercase using the current locale. Also see localeUpper, lower, and Int.localeLower.

localeUpper

Str localeUpper()

Source

Return this string with all lowercase characters replaced to uppercase using the current locale. Also see localeLower, upper, and Int.localeUpper.

lower

Str lower()

Source

Return this string with all uppercase characters replaced to lowercase. The case conversion is for ASCII only. Also see upper, localeLower, Int.lower, Int.localeLower.

Example:

"Apple".lower => "apple"

mult

@Operator
Str mult(Int times)

Source

Duplicate this string the given number of times. Any integer less than or equal to zero returns an empty string.

Examples:

"x" * 4  =>  "xxxx"

numNewlines

Int numNewlines()

Source

Count the number of newline combinations: "\n", "\r", or "\r\n".

padl

Str padl(Int width, Int char := 32)

Source

If size is less than width, then add the given char to the left to achieve the specified width. Also see justr.

Examples:

"3".padl(3, '0') => "003"
"123".padl(2, '0') => "123"

padr

Str padr(Int width, Int char := 32)

Source

If size is less than width, then add the given char to the left to achieve the specified width. Also see justl.

Examples:

"xyz".padr(2, '.') => "xyz"
"xyz".padr(5, '-') => "xyz--"

plus

@Operator
Str plus(Obj? obj)

Source

Concat the value of obj.toStr

replace

Str replace(Str from, Str to)

Source

Replace all occurrences of from with to.

Examples:

"hello".replace("hell", "t")  =>  "to"
"aababa".replace("ab", "-")   =>  "a--a"

reverse

Str reverse()

Source

Reverse the contents of this string.

Example:

"stressed".reverse => "desserts"

size

Int size()

Source

Return number of characters in this string.

spaces

static Str spaces(Int n)

Source

Get a Str containing the specified number of spaces. Also see justl and justr to justify an existing string.

Examples:

Str.spaces(1)  =>  " "
Str.spaces(2)  =>  "  "

split

Str[] split(Int? separator := null, Bool trim := true)

Source

Split a string into a list of substrings using the given separator character. If there are contiguous separators, then they are split into empty strings. If trim is true, then whitespace is trimmed from the beginning and end of the results.

If separator is null, then the string is split according to any sequence of whitespace characters (any character equal to or less than the 0x20 space character including , \r, \n, and \t).

If this is the empty string or there are no splits return a list of one item.

Examples:

// split on whitespace
"".split                   =>  [""]
"x".split                  =>  ["x"]
"x y".split                =>  ["x", "y"]
" x y ".split              =>  ["x", "y"]
" x \n y \n z ".split      =>  ["x", "y", "z"]

// split on sep with trim
"".split('|')              =>  [""]
"22".split(';')            =>  ["22"]
"22;33".split(';')         =>  ["22","33"]
"22, 33".split(',')        =>  ["22","33"]
" 22 ; 33 ".split(';')     =>  ["22","33"]

// split on sep with no trim
"22#33".split('#', false)  =>  ["22","33"]
" x ; y".split(';', false) =>  [" x "," y"]

splitLines

Str[] splitLines()

Source

Split this string into individual lines where lines are terminated by \n, \r\n, or \r. The returned strings do not contain the newline character.

Examples:

"x\ny".splitLines  => ["x", "y"]
"".splitLines      => [""]
"x".splitLines     => ["x"]
"\r\n".splitLines  => ["", ""]
"x\n".splitLines   => ["x", ""]

startsWith

Bool startsWith(Str s)

Source

Return if this Str starts with the specified Str.

toBool

Bool? toBool(Bool checked := true)

Source

Convenience for Bool.fromStr using this string.

toBuf

Buf toBuf(Charset charset := Charset.utf8())

Source

Get this string encoded into a buffer of bytes.

toCode

Str toCode(Int? quote := 34, Bool escapeUnicode := false)

Source

Return this string as its Fantom source code and serialization representation surrounded by the specified quote character (which defaults to "). If quote is null then the return is unquoted. This method will backslash escape the following characters: \n \r \f \t \\ $. If the quote character is the double quote, single quote, or backtick then it is escaped too. Control chars less than 0x20 are escaped as \uXXXX. If escapeUnicode is true then any char over 0x7F is escaped as \uXXXX.

toDecimal

Decimal? toDecimal(Bool checked := true)

Source

Convenience for Decimal.fromStr using this string.

toDisplayName

Str toDisplayName()

Source

Translate a programmer name like "fooBar" to "Foo Bar". This method capitalizes the first letter, then walks the string looking for ASCII capital letters and inserting a space. Any underbars are replaced with a space. Also see fromDisplayName.

Examples:

"foo".toDisplayName       ->  "Foo
"fooBar".toDisplayName    ->  "Foo Bar"
"fooBarBaz".toDisplayName ->  "Foo Bar Baz"
"foo33".toDisplayName     ->  "Foo 33"
"fooXML".toDisplayName    ->  "Foo XML"
"Foo".toDisplayName       ->  "Foo"
"foo_bar".toDisplayName   ->  "Foo Bar"

toFloat

Float? toFloat(Bool checked := true)

Source

Convenience for Float.fromStr using this string.

toInt

Int? toInt(Int radix := 10, Bool checked := true)

Source

Convenience for Int.fromStr using this string.

toLocale

Str toLocale()

Source

Return this. This method is used to enable toLocale to be used with duck typing across most built-in types.

toRegex

Regex toRegex()

Source

Convenience for Regex.fromStr using this string.

toStr

virtual override Str toStr()

Source

Return this.

toUri

Uri toUri()

Source

Convenience for Uri.fromStr using this string.

toXml

Str toXml()

Source

Return this string as valid XML text. The special control characters amp, lt, apos and quot are always escaped. The gt char is escaped only if it is the first char or if preceded by the ] char. Also see OutStream.writeXml which is more efficient if streaming.

trim

Str trim()

Source

Trim whitespace from the beginning and end of the string. For the purposes of this method, whitespace is defined as any character equal to or less than the 0x20 space character (including , \r, \n, and \t).

Examples:

"foo".trim      =>  "foo"
"  foo".trim    =>  "foo"
" foo ".trim    =>  "foo"
"  foo\n".trim  =>  "foo"
"   ".trim      =>  ""

trimEnd

Str trimEnd()

Source

Trim whitespace only from the end of the string. See trim for definition of whitespace.

Examples:

"foo".trim    =>  "foo"
" foo ".trim  =>  " foo"

trimStart

Str trimStart()

Source

Trim whitespace only from the beginning of the string. See trim for definition of whitespace.

Examples:

"foo".trim    =>  "foo"
" foo ".trim  =>  "foo "

trimToNull

Str? trimToNull()

Source

Trim whitespace from the beginning and end of the string. Should the resultant string be empty, null is returned.

For the purposes of this method, whitespace is defined as any character equal to or less than the 0x20 space character (including , \r, \n, and \t).

Examples:

"foo".trimToNull      =>  "foo"
"  foo  ".trimToNull  =>  "foo"
"".trimToNull         =>  null
"   ".trimToNull      =>  null

upper

Str upper()

Source

Return this string with all lowercase characters replaced to uppercase. The case conversion is for ASCII only. Also see lower, localeUpper, Int.upper, Int.localeUpper.

Example:

"Foo Bar".upper => "FOO BAR"