git.iko.soy/elk
on c8eeedf help sign in
elk/libraries/String.elm
340 lines 8.8 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 slice, 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.
37 isEmpty "" == True
38 isEmpty "the world" == False
39-}
40isEmpty : String -> Bool
41isEmpty = Native.String.isEmpty
43{-| Add a character to the beginning of a string -}
44cons : Char -> String -> String
45cons = Native.String.cons
47{-| Split a non-empty string into its head and tail. This lets you
48pattern match on strings exactly as you would with lists.
50 uncons "abc" == Just ('a',"bc")
51 uncons "" == Nothing
52-}
53uncons : String -> Maybe (Char, String)
54uncons = Native.String.uncons
56{-| Append two strings. You can also use [the `(++)` operator](/library/List.elm#++)
57to do this.
59 append "butter" "fly" == "butterfly"
60-}
61append : String -> String -> String
62append = Native.String.append
64{-| Concatenate many strings into one.
66 concat ["never","the","less"] == "nevertheless"
67-}
68concat : [String] -> String
69concat = Native.String.concat
71{-| Get the length of a string.
73 length "innumerable" == 11
74 length "" == 0
76-}
77length : String -> Int
78length = Native.String.length
80{-| Transform every character in a string
82 map (\c -> if c == '/' then '.' else c) "a/b/c" == "a.b.c"
83-}
84map : (Char -> Char) -> String -> String
85map = Native.String.map
87{-| Keep only the characters that satisfy the predicate:
89 filter isDigit "R2-D2" == "22"
90-}
91filter : (Char -> Bool) -> String -> String
92filter = Native.String.filter
94{-| Reverse a string.
96 reverse "stressed" == "desserts"
97-}
98reverse : String -> String
99reverse = Native.String.reverse
101{-| Reduce a string from the left:
103 foldl cons "" "time" == "emit"
104-}
105foldl : (Char -> b -> b) -> b -> String -> b
106foldl = Native.String.foldl
108{-| Reduce a string from the right:
110 foldr cons "" "time" == "time"
111-}
112foldr : (Char -> b -> b) -> b -> String -> b
113foldr = Native.String.foldr
115{-| Split a string using a given separator.
117 split "," "cat,dog,cow" == ["cat","dog","cow"]
118 split "/" "home/evan/Desktop/" == ["home","evan","Desktop", ""]
120Use `Regex.split` if you need something more flexible.
121-}
122split : String -> String -> [String]
123split = Native.String.split
125{-| Put many strings together with a given separator.
127 join "a" ["H","w","ii","n"] == "Hawaiian"
128 join " " ["cat","dog","cow"] == "cat dog cow"
129 join "/" ["home","evan","Desktop"] == "home/evan/Desktop"
130-}
131join : String -> [String] -> String
132join = Native.String.join
134{-| Repeat a string N times.
136 repeat 3 "ha" == "hahaha"
137-}
138repeat : Int -> String -> String
139repeat = Native.String.repeat
141{-| Take a substring given a start and end index. Negative indexes
142are taken starting from the *end* of the list.
144 slice 7 9 "snakes on a plane!" == "on"
145 slice 0 6 "snakes on a plane!" == "snakes"
146 slice 0 -7 "snakes on a plane!" == "snakes on a"
147 slice -6 -1 "snakes on a plane!" == "plane"
148-}
149slice : Int -> Int -> String -> String
150slice = Native.String.slice
152{-| Take N characters from the left side of a string. -}
153left : Int -> String -> String
154left = Native.String.left
156{-| Take N characters from the right side of a string. -}
157right : Int -> String -> String
158right = Native.String.right
160{-| Drop N characters from the left side of a string. -}
161dropLeft : Int -> String -> String
162dropLeft = Native.String.dropLeft
164{-| Drop N characters from the right side of a string. -}
165dropRight : Int -> String -> String
166dropRight = Native.String.dropRight
168{-| Pad a string on both sides until it has a given length.
170 pad 5 ' ' "1" == " 1 "
171 pad 5 ' ' "11" == " 11 "
172 pad 5 ' ' "121" == " 121 "
173-}
174pad : Int -> Char -> String -> String
175pad = Native.String.pad
177{-| Pad a string on the left until it has a given length.
179 padLeft 5 '.' "1" == "....1"
180 padLeft 5 '.' "11" == "...11"
181 padLeft 5 '.' "121" == "..121"
182-}
183padLeft : Int -> Char -> String -> String
184padLeft = Native.String.padLeft
186{-| Pad a string on the right until it has a given length.
188 padRight 5 '.' "1" == "1...."
189 padRight 5 '.' "11" == "11..."
190 padRight 5 '.' "121" == "121.."
191-}
192padRight : Int -> Char -> String -> String
193padRight = Native.String.padRight
195{-| Get rid of whitespace on both sides of a string.
197 trim " hats \n" == "hats"
198-}
199trim : String -> String
200trim = Native.String.trim
202{-| Get rid of whitespace on the left of a string.
204 trimLeft " hats \n" == "hats \n"
205-}
206trimLeft : String -> String
207trimLeft = Native.String.trimLeft
209{-| Get rid of whitespace on the right of a string.
211 trimRight " hats \n" == " hats"
212-}
213trimRight : String -> String
214trimRight = Native.String.trimRight
216{-| Break a string into words, splitting on chunks of whitespace.
218 words "How are \t you? \n Good?" == ["How","are","you?","Good?"]
219-}
220words : String -> [String]
221words = Native.String.words
223{-| Break a string into lines, splitting on newlines.
225 lines "How are you?\nGood?" == ["How are you?", "Good?"]
226-}
227lines : String -> [String]
228lines = Native.String.lines
230{-| Convert a string to all upper case. Useful for case insensitive comparisons
231and VIRTUAL YELLING.
232-}
233toUpper : String -> String
234toUpper = Native.String.toUpper
236{-| Convert a string to all lower case. Useful for case insensitive comparisons. -}
237toLower : String -> String
238toLower = Native.String.toLower
240{-| Check to see if *any* characters satisfy a predicate.
242 any isDigit "90210" == True
243 any isDigit "R2-D2" == True
244 any isDigit "heart" == False
245-}
246any : (Char -> Bool) -> String -> Bool
247any = Native.String.any
249{-| Check to see if *all* characters satisfy a predicate.
251 all isDigit "90210" == True
252 all isDigit "R2-D2" == False
253 all isDigit "heart" == False
254-}
255all : (Char -> Bool) -> String -> Bool
256all = Native.String.all
258{-| See if the second string contains the first one.
260 contains "the" "theory" == True
261 contains "hat" "theory" == False
262 contains "THE" "theory" == False
264Use `Regex.contains` if you need something more flexible.
265-}
266contains : String -> String -> Bool
267contains = Native.String.contains
269{-| See if the second string starts with the first one.
271 startsWith "the" "theory" == True
272 startsWith "ory" "theory" == False
273-}
274startsWith : String -> String -> Bool
275startsWith = Native.String.startsWith
277{-| See if the second string ends with the first one.
279 endsWith "the" "theory" == False
280 endsWith "ory" "theory" == True
281-}
282endsWith : String -> String -> Bool
283endsWith = Native.String.endsWith
285{-| Get all of the indexes for a substring in another string.
287 indexes "i" "Mississippi" == [1,4,7,10]
288 indexes "ss" "Mississippi" == [2,5]
289 indexes "needle" "haystack" == []
290-}
291indexes : String -> String -> [Int]
292indexes = Native.String.indexes
294{-| Alias for `indexes` -}
295indices : String -> String -> [Int]
296indices = Native.String.indexes
298{-| Turn any kind of value into a string.
300 show 42 == "42"
301 show [1,2] == "[1,2]"
302-}
303show : a -> String
304show = Native.Show.show
306{-| Try to convert a string into an int, failing on improperly formatted strings.
308 toInt "123" == Just 123
309 toInt "-42" == Just -42
310 toInt "3.1" == Nothing
311 toInt "31a" == Nothing
312-}
313toInt : String -> Maybe Int
314toInt = Native.String.toInt
316{-| Try to convert a string into a float, failing on improperly formatted strings.
318 toFloat "123" == Just 123.0
319 toFloat "-42" == Just -42.0
320 toFloat "3.1" == Just 3.1
321 toFloat "31a" == Nothing
322-}
323toFloat : String -> Maybe Float
324toFloat = Native.String.toFloat
326{-| Convert a string to a list of characters.
328 toList "abc" == ['a','b','c']
329-}
330toList : String -> [Char]
331toList = Native.String.toList
333{-| Convert a list of characters into a String. Can be useful if you
334want to create a string primarly by consing, perhaps for decoding
335something.
337 fromList ['a','b','c'] == "abc"
338-}
339fromList : [Char] -> String
340fromList = Native.String.fromList