#string

Operations on String and Char.

A string is an immutable sequence of Unicode codepoints, and a Char is one codepoint. Positions and lengths count codepoints, not bytes and not grapheme clusters. Character classification and case mapping are ASCII only: a non-ASCII character is never a letter, digit, or space to these functions, and passes through toUpper and toLower unchanged.

length and isEmpty are not defined here, to leave the Foldable methods of those names unshadowed. Use stringLength s and s == "". intToString renders an integer.

#Characters

#isDigit

isDigit : Char -> Bool
isDigit c

Whether c is an ASCII decimal digit, '0' to '9'.

> isDigit '7'
True
> isDigit 'x'
False

#isAlpha

isAlpha : Char -> Bool
isAlpha c

Whether c is an ASCII letter.

#isAlphaNum

isAlphaNum : Char -> Bool
isAlphaNum c

Whether c is an ASCII letter or digit.

#isSpace

isSpace : Char -> Bool
isSpace c

Whether c is ASCII whitespace.

#isUpper

isUpper : Char -> Bool
isUpper c

Whether c is an ASCII uppercase letter.

#isLower

isLower : Char -> Bool
isLower c

Whether c is an ASCII lowercase letter.

#isPunct

isPunct : Char -> Bool
isPunct c

Whether c is ASCII punctuation.

#fromDigit

fromDigit : Char -> Option Int
fromDigit c

The value of a hexadecimal digit: '0' to '9' give 0 to 9, and 'a' to 'f' or 'A' to 'F' give 10 to 15. None for any other character.

> fromDigit '7'
Some 7
> fromDigit 'f'
Some 15

#toDigit

toDigit : Int -> Option Char
toDigit n

The lowercase hexadecimal digit for a value from 0 to 15, or None outside that range. The inverse of fromDigit.

> toDigit 7
Some '7'
> toDigit 12
Some 'c'

#Conversion

#fromChar

fromChar : Char -> String
fromChar c

A string holding one character.

#toChars

toChars : String -> Array Char
toChars s

The codepoints of a string, as an array.

array.toList turns the result into a List Char when one is needed.

> arrayLength (toChars "héllo→")
6

#fromChars

fromChars : List Char -> String
fromChars cs

A string built from a list of characters.

For an Array Char, such as the result of toChars, use stringFromChars.

> fromChars ['h', 'i']
"hi"

#toUtf8

toUtf8 : String -> Array Int
toUtf8 s

The UTF-8 encoding of a string, one byte (0 to 255) per element.

A codepoint outside ASCII contributes several bytes; toChars gives the codepoints instead.

> arrayLength (toUtf8 "héllo")
6

#fromUtf8

fromUtf8 : Array Int -> String
fromUtf8 bytes

The string encoded by an array of UTF-8 bytes.

Only the low eight bits of each element are used. Each ill-formed sequence (a stray continuation byte, a truncated sequence, an overlong form, a surrogate, anything above U+10FFFF) becomes one U+FFFD replacement character per maximal subpart, as bytes.decodeUtf8Lossy does, so fromUtf8 (toUtf8 s) is s for every string, but toUtf8 (fromUtf8 bytes) is bytes only when bytes is valid UTF-8. Keep bytes that are not text in a bytes.Bytes.

> fromUtf8 (toUtf8 "héllo→")
"héllo→"

#utf8ByteLength

utf8ByteLength : String -> Int
utf8ByteLength s

The number of bytes in the string's UTF-8 encoding.

At least the codepoint count, and larger when the string has non-ASCII characters.

> utf8ByteLength "héllo"
6

#toInt

toInt : String -> Option Int
toInt s

The integer written in decimal in s, with an optional leading - or +.

None when s is empty, contains any other character, or names a value outside the Int range.

> toInt "42"
Some 42
> toInt "12x"
None

#toFloat

toFloat : String -> Option Float
toFloat s

The floating-point number written in s, or None when s is not one.

> toFloat "3.5"
Some 3.5
> toFloat "nope"
None

#Searching

#startsWith

startsWith : String -> String -> Bool
startsWith prefix s

Whether s begins with prefix.

> startsWith "he" "hello"
True
> startsWith "lo" "hello"
False

#endsWith

endsWith : String -> String -> Bool
endsWith suffix s

Whether s ends with suffix.

> endsWith "lo" "hello"
True

#stripPrefix

stripPrefix : String -> String -> Option String
stripPrefix prefix s

s without its leading prefix, or None when s does not begin with it.

Unlike drop, the result says whether the prefix was there.

> stripPrefix "he" "hello"
Some "llo"
> stripPrefix "xy" "hello"
None

#stripSuffix

stripSuffix : String -> String -> Option String
stripSuffix suffix s

s without its trailing suffix, or None when s does not end with it.

> stripSuffix "lo" "hello"
Some "hel"
> stripSuffix "xy" "hello"
None

#contains

contains : String -> String -> Bool
contains needle haystack

Whether needle occurs anywhere in haystack.

The empty string occurs in every string.

> contains "ell" "hello"
True
> contains "xyz" "hello"
False

#indexOf

indexOf : String -> String -> Option Int
indexOf needle haystack

The position of the first occurrence of needle in haystack, or None.

> indexOf "lo" "hello"
Some 3
> indexOf "z" "hello"
None

#lastIndexOf

lastIndexOf : String -> String -> Option Int
lastIndexOf needle haystack

The position of the last occurrence of needle in haystack, or None.

Occurrences may overlap. An empty needle is found at the end of the string.

> lastIndexOf "l" "hello"
Some 3
> lastIndexOf "z" "hello"
None

#countOccurrences

countOccurrences : String -> String -> Int
countOccurrences needle haystack

The number of non-overlapping occurrences of needle in haystack.

0 for an empty needle.

> countOccurrences "l" "hello"
2
> countOccurrences "ll" "lllll"
2

#Building

#prepend

prepend : String -> String -> String
prepend pre s

pre followed by s.

> prepend "un" "do"
"undo"

#concat

concat : List String -> String
concat parts

The strings joined end to end.

> concat ["a", "bc", "d"]
"abcd"

#join

join : String -> List String -> String
join sep parts

The strings joined with sep between each adjacent pair.

> join ", " ["a", "b", "c"]
"a, b, c"

#repeat

repeat : Int -> String -> String
repeat n s

s repeated n times.

Empty when n <= 0. Safe for large n: the call depth grows with log n, not n.

> repeat 3 "ab"
"ababab"

#Transformation

#reverse

reverse : String -> String
reverse s

The string with its characters in reverse order.

> reverse "abc"
"cba"

#trimLeft

trimLeft : String -> String
trimLeft s

The string without its leading whitespace.

> trimLeft "  hi  "
"hi  "

#trimRight

trimRight : String -> String
trimRight s

The string without its trailing whitespace.

> trimRight "  hi  "
"  hi"

#trim

trim : String -> String
trim s

The string without leading or trailing whitespace.

> trim "  hi  "
"hi"

#toUpper

toUpper : String -> String
toUpper s

The string with every ASCII letter in uppercase.

Other characters are unchanged, so ß stays ß.

> toUpper "Straße"
"STRAßE"

#toLower

toLower : String -> String
toLower s

The string with every ASCII letter in lowercase.

Other characters are unchanged.

> toLower "HÉLLO"
"hÉllo"

#capitalize

capitalize : String -> String
capitalize s

The string with its first character in uppercase.

> capitalize "hello"
"Hello"

#replace

replace : String -> String -> String -> String
replace old new s

The string with the first occurrence of old replaced by new.

Unchanged when old is absent or empty.

> replace "l" "L" "hello"
"heLlo"

#replaceAll

replaceAll : String -> String -> String -> String
replaceAll old new s

The string with every non-overlapping occurrence of old replaced by new.

Unchanged when old is empty.

> replaceAll "l" "L" "hello"
"heLLo"

#Slicing and splitting

#sliceClamped

sliceClamped : Int -> Int -> String -> String
sliceClamped lo hi s

The characters at positions [lo, hi).

Positions are clamped to the string, so an out-of-range slice is shorter rather than a panic. s.[lo..hi] is the panicking form.

> sliceClamped 1 4 "hello"
"ell"

#take

take : Int -> String -> String
take n s

The first n characters, or the whole string when it is shorter.

> take 3 "hello"
"hel"

#drop

drop : Int -> String -> String
drop n s

Everything after the first n characters.

> drop 3 "hello"
"lo"

#splitAt

splitAt : Int -> String -> (String, String)
splitAt n s

The first n characters, and the rest.

> splitAt 2 "hello"
("he", "llo")

#split

split : String -> String -> List String
split sep s

The pieces of s between occurrences of sep, with the separators removed.

An empty separator yields the whole string as the only piece.

> split "," "a,b,c"
["a", "b", "c"]
> split "," "abc"
["abc"]

#lines

lines : String -> List String
lines s

The lines of s, split on \n.

A \r before the \n is removed, so Windows line endings work too.

> lines "a\nb\nc"
["a", "b", "c"]

#stripCR

stripCR : String -> String
stripCR line

The line without one trailing \r.

Unchanged when there is none.

> stripCR "ab\r"
"ab"
> stripCR "ab"
"ab"

#words

words : String -> List String
words s

The words of s: the runs of characters between whitespace.

Leading, trailing, and repeated whitespace produce no empty words.

> words "  hello   world "
["hello", "world"]

#unlines

unlines : List String -> String
unlines parts

The lines joined with \n, with a newline after each one.

> unlines ["a", "b"]
"a\nb\n"

#unwords

unwords : List String -> String
unwords parts

The words joined with single spaces.

> unwords ["a", "b", "c"]
"a b c"

#Padding

#padLeft

padLeft : Int -> Char -> String -> String
padLeft n c s

The string padded on the left with c to length n.

Unchanged when it is already at least n long.

> padLeft 5 '.' "ab"
"...ab"

#padRight

padRight : Int -> Char -> String -> String
padRight n c s

The string padded on the right with c to length n.

Unchanged when it is already at least n long.

> padRight 5 '.' "ab"
"ab..."

#center

center : Int -> Char -> String -> String
center n c s

The string centered in a field of width n, padded with c.

When the padding is odd, the extra character goes on the right. Unchanged when the string is already at least n long.

> center 5 '.' "ab"
".ab.."

#Instances

• String: Eq, Semigroup, Monoid, Ord, Debug, Display, Hashable, Index, Slice, Arbitrary, Generic

#Index String Int Char

impl Index String Int Char

The character at a codepoint position: s[i].

Panics with an index error when the position is out of range. Positions count codepoints, matching string.toChars.

#Slice String

impl Slice String

The substring over codepoint positions [lo, hi).

Panics with a slice error when the range runs outside the string; string.sliceClamped clamps instead.

> slice "hello" 1 4
"ell"