String

Operations on text.

A String is always valid UTF-8 and is not normalized; a Char is one Unicode scalar value. Lengths and indices count scalars unless a name says bytes. Whitespace-aware operations (words, trim) recognize ASCII whitespace only: space, tab, line feed, carriage return, vertical tab, and form feed.

Uncons

type Uncons =    { first : Char    , rest : String    }Source

A nonempty string split after its first character, as uncons answers.

Fields

first

first : CharSource

The first character.

rest

rest : StringSource

Everything after it.

byteLength

byteLength : String -> IntSource

The number of bytes in the text’s UTF-8 encoding.

import String

String.byteLength "naïve" == 6

concat

concat : List String -> StringSource

The strings joined in list order, allocated once.

import String

String.concat ["ab", "", "c"] == "abc"
String.concat [] == ""

contains

contains : String -> String -> BoolSource

Whether needle occurs anywhere in text. The empty needle occurs in every string.

import String

String.contains "lo w" "hello world"
String.contains "" ""

fromChar

fromChar : Char -> StringSource

The one-character string.

import String

String.fromChar 'a' == "a"

fromList

fromList : List Char -> StringSource

The characters joined in list order, allocated once.

import String

String.fromList ['a', 'b'] == "ab"
String.fromList [] == ""

length

length : String -> IntSource

The number of Unicode scalar values.

import String

String.length "naïve" == 5
String.length "" == 0

padLeft

padLeft : Int -> Char -> String -> StringSource

The text widened to width characters by adding filler in front. Text already that wide is returned unchanged, never truncated.

import String

String.padLeft 3 '0' "7" == "007"
String.padLeft 1 '0' "42" == "42"

padRight

padRight : Int -> Char -> String -> StringSource

The text widened to width characters by adding filler after it. Text already that wide is returned unchanged, never truncated.

import String

String.padRight 3 '.' "ab" == "ab."

slice

slice : Int -> Int -> String -> StringSource

The characters from index start up to but not including end, counted in scalars from zero. Indices are clamped to the text, and the result is "" when end is not greater than start.

import String

String.slice 1 3 "abcd" == "bc"
String.slice 2 10 "abcd" == "cd"
String.slice 3 1 "abcd" == ""

span

span : (Char ->{e} Bool) -> String ->{e} (String, String)Source

The longest prefix whose characters all satisfy keep, and the rest. keep runs on each character from the start, including the first one it rejects, and then stops; on "" it never runs.

import String

String.span { c -> c /= ' ' } "hello world" == ("hello", " world")
String.span { c -> c /= ' ' } "" == ("", "")

split

split : String -> String -> List StringSource

The pieces of text between occurrences of separator, so n occurrences give n + 1 pieces and adjacent separators give empty ones. An empty separator yields the whole text as one piece.

import String

String.split "," "a,,b" == ["a", "", "b"]
String.split "," "" == [""]
String.split "" "ab" == ["ab"]

startsWith

startsWith : String -> String -> BoolSource

Whether text begins with prefix.

import String

String.startsWith "ab" "abc"
String.startsWith "" "abc"

toFloat

toFloat : String -> Maybe FloatSource

The number the whole text spells: an optional sign, decimal digits, an optional fraction with digits on both sides of ., and an optional decimal exponent. Whitespace, NaN, infinities, hexadecimal, .5, and 1. answer Nothing, as do values that overflow, or that are nonzero and underflow to zero. Every other finite value parses, negative zero and subnormal values included.

import String

String.toFloat "2.5e3" == Just 2500.0
String.toFloat "-0.25" == Just (-0.25)
String.toFloat ".5" == Nothing

toInt

toInt : String -> Maybe IntSource

The integer the whole text spells: an optional + or - sign followed by base-10 digits. Any other character, an empty digit sequence, and a value outside the signed 64-bit range answer Nothing. The most negative Int parses.

import String

String.toInt "007" == Just 7
String.toInt "-42" == Just (-42)
String.toInt "4 2" == Nothing
String.toInt "9223372036854775808" == Nothing
String.toInt "-9223372036854775808" == Just (-9223372036854775807 - 1)

trim

trim : String -> StringSource

The text without leading and trailing whitespace.

import String

String.trim "  a b \n" == "a b"
String.trim " \t " == ""

uncons

uncons : String -> Maybe UnconsSource

The first character and the rest of the text, or Nothing for "".

import String

firstOf : String -> Maybe Char
firstOf text =
    case String.uncons text of
        Just parts -> Just parts.first
        Nothing -> Nothing

firstOf "ab" == Just 'a'
firstOf "" == Nothing

words

words : String -> List StringSource

The runs of non-whitespace text, in order. Whitespace between, before, and after them is dropped.

import String

String.words "  one two\tthree\n" == ["one", "two", "three"]
String.words "  " == []