Text and numbers.

Work with Unicode text and convert external text into numeric values.

A String is valid UTF-8 text, and a Char is a single Unicode scalar value. If your input might not be text at all, use Bytes instead.

API reference: String · Text.Builder · Char · Basics

String.

import String

main() =
    print (String.length "café")
    print (String.byteLength "café")
    print (String.slice 0 3 "café")
    print (String.split "," "a,,b")

This prints 4, 5, caf, and ["a", "", "b"]. Lengths and slice positions count Unicode scalars, not bytes and not what a reader would see as characters. Slice bounds are clamped to the string, and the end is exclusive.

String.startsWith prefix text checks a prefix, and contains needle text looks anywhere in the text. concat joins a list of chunks. split keeps the empty pieces between neighbouring separators, and an empty separator leaves the input as a single piece.

To build text, an interpolated string such as "#{name}: #{count}" covers most needs (see Syntax), and concat joins a list you already have. When you assemble text piece by piece, for example across a loop, use a Text.Builder, an immutable value that appends efficiently and gives you the final string with Text.Builder.toString. Custom Display instances write through the same builders.

words and trim recognize ASCII whitespace. The library doesn’t normalize text, and it doesn’t offer grapheme segmentation or general Unicode case conversion.

Parse a number.

import String

main() =
    case String.toInt "007" of
        Just value -> print (value + 1)
        Nothing -> print "invalid integer"
    print (String.toFloat "1.25e2")

The outputs are 8 and Just 125. A conversion has to consume the whole string, and it won’t skip whitespace around the number. Invalid input, or a value out of range, gives Nothing.

toInt accepts an optional sign followed by decimal digits, within the signed 64-bit range. toFloat accepts finite decimal numbers with an optional exponent, and rejects forms such as .5, 1., NaN, and infinity.

Char.

A character is a Unicode scalar, not a byte. Char converts between a character and its code point:

import Char

main() =
    print (Char.toCode 'é')
    print (Char.fromCode 233)
    print (Char.fromCode 55296)

233
Just 'é'
Nothing

55296 is where the surrogate range begins, and those values aren’t valid scalars. fromCode also rejects negative numbers and anything above the Unicode limit. To turn text into bytes for transport, pick an Encoding. The code point 233 takes two bytes in UTF-8 and one in Latin-1.

Basics: integer arithmetic.

The integer division helpers live in Basics, so import them explicitly. Note that the divisor comes first:

import Basics exposing (modBy, quotientBy, remainderBy)

main() =
    print (quotientBy 3 (-7))
    print (remainderBy 3 (-7))
    print (modBy 3 (-7))

This prints -2, -1, and 2. The quotient truncates toward zero, the remainder takes the sign of the dividend, and the modulus takes the sign of the divisor. A zero divisor crashes the program, so check for it before calling these.