git.iko.soy/elk
on 093d7af help sign in
elk/libraries/String.elm
324 lines 8.5 kB history raw
1module String where
2{-| A built-in representation for efficient string manipulation. String literals
3are enclosed in `"double quotes"`. Strings are *not* lists of characters.
5# Basics
6@docs isEmpty, length, reverse, repeat
8# Building and Splitting
9@docs cons, uncons, append, concat, split, join, words, lines
11# Get Substrings
12@docs sub, left, right, dropLeft, dropRight
14# Check for Substrings
15@docs contains, startsWith, endsWith, indexes, indices
17# Conversions
18@docs show, toInt, toFloat, toList, fromList
20# Formatting
21Cosmetic operations such as padding with extra characters or trimming whitespace.
23@docs toUpper, toLower,
24 pad, padLeft, padRight,
25 trim, trimLeft, trimRight
27# Higher-Order Functions
28@docs map, filter, foldl, foldr, any, all
29-}
31import Native.Show
32import Native.String
33import Maybe (Maybe)
35{-| Check if a string is empty `(isEmpty "" == True)` -}
36isEmpty : String -> Bool
37isEmpty = Native.String.isEmpty
39{-| Add a character to the beginning of a string -}
40cons : Char -> String -> String
41cons = Native.String.cons
43{-| Split a non-empty string into its head and tail. This lets you
44pattern match on strings exactly as you would with lists.
46 uncons "abc" == Just ('a',"bc")
47 uncons "" == Nothing
48-}
49uncons : String -> Maybe (Char, String)
50uncons = Native.String.uncons
52{-| Append two strings. You can also use [the `(++)` operator](/library/List.elm#++)
53to do this.
55 append "butter" "fly" == "butterfly"
56-}
57append : String -> String -> String
58append = Native.String.append
60{-| Concatenate many strings into one.
62 concat ["never","the","less"] == "nevertheless"
63-}
64concat : [String] -> String
65concat = Native.String.concat
67{-| Get the length of a string `(length "innumerable" == 11)` -}
68length : String -> Int
69length = Native.String.length
71{-| Transform every character in a string
73 map (\c -> if c == '/' then '.' else c) "a/b/c" == "a.b.c"
74-}
75map : (Char -> Char) -> String -> String
76map = Native.String.map
78{-| Keep only the characters that satisfy the predicate:
80 filter isDigit "R2-D2" == "22"
81-}
82filter : (Char -> Bool) -> String -> String
83filter = Native.String.filter
85{-| Reverse a string. `(reverse "stressed" == "desserts")` -}
86reverse : String -> String
87reverse = Native.String.reverse
89{-| Reduce a string from the left:
91 foldl cons "" "time" == "emit"
92-}
93foldl : (Char -> b -> b) -> b -> String -> b
94foldl = Native.String.foldl
96{-| Reduce a string from the right:
98 foldr cons "" "time" == "time"
99-}
100foldr : (Char -> b -> b) -> b -> String -> b
101foldr = Native.String.foldr
103{-| Split a string using a given separator.
105 split "," "cat,dog,cow" == ["cat","dog","cow"]
106 split "/" "home/evan/Desktop/" == ["home","evan","Desktop"]
108Use `Regex.split` if you need something more flexible.
109-}
110split : String -> String -> [String]
111split = Native.String.split
113{-| Put many strings together with a given separator.
115 join " " ["cat","dog","cow"] == "cat dog cow"
116 join "/" ["home","evan","Desktop"] == "home/evan/Desktop"
117-}
118join : String -> [String] -> String
119join = Native.String.join
121{-| Repeat a string N times `(repeat 3 "ha" == "hahaha")` -}
122repeat : Int -> String -> String
123repeat = Native.String.repeat
125{-| Take a substring given a start and end index. Negative indexes
126are taken starting from the *end* of the list.
128 sub 7 9 "snakes on a plane!" == "on"
129 sub 0 6 "snakes on a plane!" == "snakes"
130 sub 0 -7 "snakes on a plane!" == "snakes on a"
131 sub -6 -1 "snakes on a plane!" == "plane"
132-}
133sub : Int -> Int -> String -> String
134sub = Native.String.sub
136{-| Take N characters from the left side of a string. -}
137left : Int -> String -> String
138left = Native.String.left
140{-| Take N characters from the right side of a string. -}
141right : Int -> String -> String
142right = Native.String.right
144{-| Drop N characters from the left side of a string. -}
145dropLeft : Int -> String -> String
146dropLeft = Native.String.dropLeft
148{-| Drop N characters from the right side of a string. -}
149dropRight : Int -> String -> String
150dropRight = Native.String.dropRight
152{-| Pad a string on both sides until it has a given length.
154 pad 5 ' ' "1" == " 1 "
155 pad 5 ' ' "11" == " 11 "
156 pad 5 ' ' "121" == " 121 "
157-}
158pad : Int -> Char -> String -> String
159pad = Native.String.pad
161{-| Pad a string on the left until it has a given length.
163 pad 5 '.' "1" == "....1"
164 pad 5 '.' "11" == "...11"
165 pad 5 '.' "121" == "..121"
166-}
167padLeft : Int -> Char -> String -> String
168padLeft = Native.String.padLeft
170{-| Pad a string on the right until it has a given length.
172 pad 5 '.' "1" == "1...."
173 pad 5 '.' "11" == "11..."
174 pad 5 '.' "121" == "121.."
175-}
176padRight : Int -> Char -> String -> String
177padRight = Native.String.padRight
179{-| Get rid of whitespace on both sides of a string.
181 trim " hats \n" == "hats"
182-}
183trim : String -> String
184trim = Native.String.trim
186{-| Get rid of whitespace on the left of a string.
188 trimLeft " hats \n" == "hats \n"
189-}
190trimLeft : String -> String
191trimLeft = Native.String.trimLeft
193{-| Get rid of whitespace on the left of a string.
195 trimRight " hats \n" == " hats"
196-}
197trimRight : String -> String
198trimRight = Native.String.trimRight
200{-| Break a string into words, splitting on chunks of whitespace.
202 words "How are \t you? \n Good?" == ["How","are","you?","Good?"]
203-}
204words : String -> [String]
205words = Native.String.words
207{-| Break a string into lines, splitting on newlines.
209 lines "How are you?\nGood? == ["How are you?", "Good?"]
210-}
211lines : String -> [String]
212lines = Native.String.lines
214{-| Convert a string to all upper case. Useful for case insensitive comparisons
215and VIRTUAL YELLING.
216-}
217toUpper : String -> String
218toUpper = Native.String.toUpper
220{-| Convert a string to all lower case. Useful for case insensitive comparisons. -}
221toLower : String -> String
222toLower = Native.String.toLower
224{-| Check to see if *any* characters satisfy a predicate.
226 any isDigit "90210" == True
227 any isDigit "R2-D2" == True
228 any isDigit "heart" == False
229-}
230any : (Char -> Bool) -> String -> Bool
231any = Native.String.any
233{-| Check to see if *all* characters satisfy a predicate.
235 all isDigit "90210" == True
236 all isDigit "R2-D2" == False
237 all isDigit "heart" == False
238-}
239all : (Char -> Bool) -> String -> Bool
240all = Native.String.all
242{-| See if a string contains another one.
244 contains "the" "theory" == True
245 contains "hat" "theory" == False
246 contains "THE" "theory" == False
248Use `Regex.contains` if you need something more flexible.
249-}
250contains : String -> String -> Bool
251contains = Native.String.contains
253{-| See if a string starts with another one.
255 startsWith "the" "theory" == True
256 startsWith "ory" "theory" == False
257-}
258startsWith : String -> String -> Bool
259startsWith = Native.String.startsWith
261{-| See if a string ends with another one.
263 endsWith "the" "theory" == False
264 endsWith "ory" "theory" == True
265-}
266endsWith : String -> String -> Bool
267endsWith = Native.String.endsWith
269{-| Get all of the indexes for a substring.
271 indexes "i" "Mississippi" == [1,4,7,10]
272 indexes "ss" "Mississippi" == [2,5]
273 indexes "needle" "haystack" == []
274-}
275indexes : String -> String -> [Int]
276indexes = Native.String.indexes
278{-| Alias for `indexes` -}
279indices : String -> String -> [Int]
280indices = Native.String.indexes
282{-| Turn any kind of value into a string.
284 show 42 == "42"
285 show [1,2] == "[1,2]"
286-}
287show : a -> String
288show = Native.Show.show
290{-| Try to convert a string into an int, failing on improperly formatted strings.
292 toInt "123" == Just 123
293 toInt "-42" == Just -42
294 toInt "3.1" == Nothing
295 toInt "31a" == Nothing
296-}
297toInt : String -> Maybe Int
298toInt = Native.String.toInt
300{-| Try to convert a string into a float, failing on improperly formatted strings.
302 toFloat "123" == Just 123.0
303 toFloat "-42" == Just -42.0
304 toFloat "3.1" == Just 3.1
305 toFloat "31a" == Nothing
306-}
307toFloat : String -> Maybe Float
308toFloat = Native.String.toFloat
310{-| Convert a string to a list of characters.
312 toList "abc" == ['a','b','c']
313-}
314toList : String -> [Char]
315toList = Native.String.toList
317{-| Convert a list of characters into a String. Can be useful if you
318want to create a string primarly by consing, perhaps for decoding
319something.
321 fromList ['a','b','c'] == "abc"
322-}
323fromList : [Char] -> String
324fromList = Native.String.fromList