String.Graphemes

A built-in representation for efficient string manipulation. String literals are enclosed in "double quotes". Strings are not lists of characters.

Strings

isEmpty : String -> Bool

Determine if a string is empty.

isEmpty "" --> True


isEmpty "the world" --> False

length : String -> Int

Get the length of a string.

length "innumerable" --> 11


length "" --> 0


length "🇨🇦" --> 1

reverse : String -> String

Reverse a string.

reverse "stressed" --> "desserts"


reverse "🇨🇦🇲🇽" --> "🇲🇽🇨🇦"

repeat : Int -> String -> String

Repeat a string n times.

repeat 3 "ha" --> "hahaha"

replace : String -> String -> String -> String

Replace all occurrences of some substring.

replace "." "-" "Json.Decode.succeed" --> "Json-Decode-succeed"


replace "," "/" "a,b,c,d,e" --> "a/b/c/d/e"

Note: If you need more advanced replacements, check out the elm/parser or elm/regex package.

Building and Splitting

append : String -> String -> String

Append two strings. You can also use the (++) operator to do this.

append "butter" "fly" --> "butterfly"

concat : List String -> String

Concatenate many strings into one.

concat [ "never", "the", "less" ] --> "nevertheless"

split : String -> String -> List String

Split a string using a given separator.

split "," "cat,dog,cow" --> [ "cat", "dog", "cow" ]


split "/" "home/evan/Desktop/" --> [ "home", "evan", "Desktop", "" ]

Note: this will split a string very literally—including breaking grapheme boundaries. If this causes problems for you, please open an issue.

join : String -> List String -> String

Put many strings together with a given separator.

join "a" [ "H", "w", "ii", "n" ] --> "Hawaiian"


join " " [ "cat", "dog", "cow" ] --> "cat dog cow"


join "/" [ "home", "evan", "Desktop" ] --> "home/evan/Desktop"

words : String -> List String

Break a string into words, splitting on chunks of whitespace.

words "How are \t you? \n Good?" --> [ "How", "are", "you?", "Good?" ]

lines : String -> List String

Break a string into lines, splitting on newlines.

lines "How are you?\nGood?" --> [ "How are you?", "Good?" ]

Get Substrings

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

Take a substring given a start and end index. Negative indexes are taken starting from the end of the list.

slice 7 9 "snakes on a plane!" --> "on"


slice 0 6 "snakes on a plane!" --> "snakes"


slice 0 -7 "snakes on a plane!" --> "snakes on a"


slice -6 -1 "snakes on a plane!" --> "plane"

left : Int -> String -> String

Take n characters from the left side of a string.

left 2 "Mulder" --> "Mu"

right : Int -> String -> String

Take n characters from the right side of a string.

right 2 "Scully" --> "ly"

dropLeft : Int -> String -> String

Drop n characters from the left side of a string.

dropLeft 2 "The Lone Gunmen" --> "e Lone Gunmen"

dropRight : Int -> String -> String

Drop n characters from the right side of a string.

dropRight 2 "Cigarette Smoking Man" --> "Cigarette Smoking M"

Check for Substrings

contains : String -> String -> Bool

See if the second string contains the first one.

contains "the" "theory" --> True


contains "hat" "theory" --> False


contains "THE" "theory" --> False

startsWith : String -> String -> Bool

See if the second string starts with the first one.

startsWith "the" "theory" --> True


startsWith "ory" "theory" --> False

endsWith : String -> String -> Bool

See if the second string ends with the first one.

endsWith "the" "theory" --> False


endsWith "ory" "theory" --> True

indexes : String -> String -> List Int

Get all of the indexes for a substring in another string.

indexes "i" "Mississippi" --> [ 1, 4, 7, 10 ]


indexes "ss" "Mississippi" --> [ 2, 5 ]


indexes "needle" "haystack" --> []

indices : String -> String -> List Int

Alias for indexes.

Int Conversions

toInt : String -> Maybe Int

Try to convert a string into an int, failing on improperly formatted strings.

String.toInt "123" --> Just 123


String.toInt "-42" --> Just -42


String.toInt "3.1" --> Nothing


String.toInt "31a" --> Nothing

If you are extracting a number from some raw user input, you will typically want to use Maybe.withDefault to handle bad data:

Maybe.withDefault 0 (String.toInt "42") --> 42


Maybe.withDefault 0 (String.toInt "ab") --> 0

fromInt : Int -> String

Convert an Int to a String.

String.fromInt 123 --> "123"


String.fromInt -42 --> "-42"

Check out Debug.toString to convert any value to a string for debugging purposes.

Float Conversions

toFloat : String -> Maybe Float

Try to convert a string into a float, failing on improperly formatted strings.

fromFloat : Float -> String

Convert a Float to a String.

String.fromFloat 123 --> "123"


String.fromFloat -42 --> "-42"


String.fromFloat 3.9 --> "3.9"

Check out Debug.toString to convert any value to a string for debugging purposes.

Char Conversions

fromChar : Char -> String

Create a string from a given character.

fromChar 'a' --> "a"

cons : Char -> String -> String

Add a character to the beginning of a string.

cons 'T' "he truth is out there" --> "The truth is out there"

uncons : String -> Maybe ( String, String )

Split a non-empty string into its head and tail. This lets you pattern match on strings exactly as you would with lists.

uncons "abc" --> Just ( "a", "bc" )


uncons "" --> Nothing

List Conversions

toList : String -> List String

Convert a string to a list of characters.

toList "abc" --> [ "a", "b", "c" ]


toList "🙈🙉🙊" --> [ "🙈", "🙉", "🙊" ]

fromList : List String -> String

Convert a list of graphemes into a String. Can be useful if you want to create a string primarily by consing, perhaps for decoding something.

fromList [ "a", "b", "c" ] --> "abc"


fromList [ "🙈", "🙉", "🙊" ] --> "🙈🙉🙊"

Formatting

Cosmetic operations such as padding with extra characters or trimming whitespace.

toUpper : String -> String

Convert a string to all upper case. Useful for case-insensitive comparisons and VIRTUAL YELLING.

toUpper "skinner" --> "SKINNER"

toLower : String -> String

Convert a string to all lower case. Useful for case-insensitive comparisons.

toLower "X-FILES" --> "x-files"

pad : Int -> Char -> String -> String

Pad a string on both sides until it has a given length.

pad 5 ' ' "1" --> "  1  "


pad 5 ' ' "11" --> "  11 "


pad 5 ' ' "121" --> " 121 "

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

Pad a string on the left until it has a given length.

padLeft 5 '.' "1" --> "....1"


padLeft 5 '.' "11" --> "...11"


padLeft 5 '.' "121" --> "..121"

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

Pad a string on the right until it has a given length.

padRight 5 '.' "1" --> "1...."


padRight 5 '.' "11" --> "11..."


padRight 5 '.' "121" --> "121.."

trim : String -> String

Get rid of whitespace on both sides of a string.

trim "  hats  \n" --> "hats"

trimLeft : String -> String

Get rid of whitespace on the left of a string.

trimLeft "  hats  \n" --> "hats  \n"

trimRight : String -> String

Get rid of whitespace on the right of a string.

trimRight "  hats  \n" --> "  hats"

Higher-Order Functions

map : (String -> String) -> String -> String

Transform every grapheme in a string

filter : (String -> Bool) -> String -> String

Keep only the graphemes that pass the test.

filter (String.all Char.isDigit) "R2-D2" --> "22"

foldl : (String -> b -> b) -> b -> String -> b

Reduce a string from the left.

foldl (++) "" "time" --> "emit"

foldr : (String -> b -> b) -> b -> String -> b

Reduce a string from the right.

foldr (++) "" "time" --> "time"

any : (String -> Bool) -> String -> Bool

Determine whether any graphemes pass the test.

any (String.all Char.isDigit) "90210" --> True


any (String.all Char.isDigit) "R2-D2" --> True


any (String.all Char.isDigit) "heart" --> False

all : (String -> Bool) -> String -> Bool

Determine whether all graphemes pass the test.

all (String.all Char.isDigit) "90210" --> True


all (String.all Char.isDigit) "R2-D2" --> False


all (String.all Char.isDigit) "heart" --> False

Modules

String.Graphemes

BrianHicks/elm-string-graphemes/1.0.3