git.iko.soy/elk
on ea28a87 help sign in
elk/libraries/String.elm
315 lines 8.4 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 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.String
32import Maybe (Maybe)
34{-| Check if a string is empty `(isEmpty "" == True)` -}
35isEmpty : String -> Bool
36isEmpty = Native.String.isEmpty
38{-| Add a character to the beginning of a string -}
39cons : Char -> String -> String
40cons = Native.String.cons
42{-| Split a non-empty string into its head and tail. This lets you
43pattern match on strings exactly as you would with lists.
45 uncons "abc" == Just ('a',"bc")
46 uncons "" == Nothing
47-}
48uncons : String -> Maybe (Char, String)
49uncons = Native.String.uncons
51{-| Append two strings. You can also use [the `(++)` operator](/library/List.elm#++)
52to do this.
54 append "butter" "fly" == "butterfly"
55-}
56append : String -> String -> String
57append = Native.String.append
59{-| Concatenate many strings into one.
61 concat ["never","the","less"] == "nevertheless"
62-}
63concat : [String] -> String
64concat = Native.String.concat
66{-| Get the length of a string `(length "innumerable" == 11)` -}
67length : String -> Int
68length = Native.String.length
70{-| Transform every character in a string
72 map (\c -> if c == '/' then '.' else c) "a/b/c" == "a.b.c"
73-}
74map : (Char -> Char) -> String -> String
75map = Native.String.map
77{-| Keep only the characters that satisfy the predicate:
79 filter isDigit "R2-D2" == "22"
80-}
81filter : (Char -> Bool) -> String -> String
82filter = Native.String.filter
84{-| Reverse a string. `(reverse "stressed" == "desserts")` -}
85reverse : String -> String
86reverse = Native.String.reverse
88{-| Reduce a string from the left:
90 foldl cons "" "time" == "emit"
91-}
92foldl : (Char -> b -> b) -> b -> String -> b
93foldl = Native.String.foldl
95{-| Reduce a string from the right:
97 foldr cons "" "time" == "time"
98-}
99foldr : (Char -> b -> b) -> b -> String -> b
100foldr = Native.String.foldr
102{-| Split a string using a given separator.
104 split "," "cat,dog,cow" == ["cat","dog","cow"]
105 split "/" "home/evan/Desktop/" == ["home","evan","Desktop"]
107Use `Regex.split` if you need something more flexible.
108-}
109split : String -> String -> [String]
110split = Native.String.split
112{-| Put many strings together with a given separator.
114 join " " ["cat","dog","cow"] == "cat dog cow"
115 join "/" ["home","evan","Desktop"] == "home/evan/Desktop"
116-}
117join : String -> [String] -> String
118join = Native.String.join
120{-| Repeat a string N times `(repeat 3 "ha" == "hahaha")` -}
121repeat : Int -> String -> String
122repeat = Native.String.repeat
124{-| Take a substring given a start and end index. Negative indexes
125are taken starting from the *end* of the list.
127 sub 7 9 "snakes on a plane!" == "on"
128 sub 0 6 "snakes on a plane!" == "snakes"
129 sub 0 -7 "snakes on a plane!" == "snakes on a"
130 sub -6 -1 "snakes on a plane!" == "plane"
131-}
132sub : Int -> Int -> String -> String
133sub = Native.String.sub
135{-| Take N characters from the left side of a string. -}
136left : Int -> String -> String
137left = Native.String.left
139{-| Take N characters from the right side of a string. -}
140right : Int -> String -> String
141right = Native.String.right
143{-| Drop N characters from the left side of a string. -}
144dropLeft : Int -> String -> String
145dropLeft = Native.String.dropLeft
147{-| Drop N characters from the right side of a string. -}
148dropRight : Int -> String -> String
149dropRight = Native.String.dropRight
151{-| Pad a string on both sides until it has a given length.
153 pad 5 ' ' "1" == " 1 "
154 pad 5 ' ' "11" == " 11 "
155 pad 5 ' ' "121" == " 121 "
156-}
157pad : Int -> Char -> String -> String
158pad = Native.String.pad
160{-| Pad a string on the left until it has a given length.
162 pad 5 '.' "1" == "....1"
163 pad 5 '.' "11" == "...11"
164 pad 5 '.' "121" == "..121"
165-}
166padLeft : Int -> Char -> String -> String
167padLeft = Native.String.padLeft
169{-| Pad a string on the right until it has a given length.
171 pad 5 '.' "1" == "1...."
172 pad 5 '.' "11" == "11..."
173 pad 5 '.' "121" == "121.."
174-}
175padRight : Int -> Char -> String -> String
176padRight = Native.String.padRight
178{-| Get rid of whitespace on both sides of a string.
180 trim " hats \n" == "hats"
181-}
182trim : String -> String
183trim = Native.String.trim
185{-| Get rid of whitespace on the left of a string.
187 trimLeft " hats \n" == "hats \n"
188-}
189trimLeft : String -> String
190trimLeft = Native.String.trimLeft
192{-| Get rid of whitespace on the left of a string.
194 trimRight " hats \n" == " hats"
195-}
196trimRight : String -> String
197trimRight = Native.String.trimRight
199{-| Break a string into words, splitting on chunks of whitespace.
201 words "How are \t you? \n Good?" == ["How","are","you?","Good?"]
202-}
203words : String -> [String]
204words = Native.String.words
206{-| Break a string into lines, splitting on newlines.
208 lines "How are you?\nGood? == ["How are you?", "Good?"]
209-}
210lines : String -> [String]
211lines = Native.String.lines
213{-| Convert a string to all upper case. Useful for case insensitive comparisons
214and VIRTUAL YELLING.
215-}
216toUpper : String -> String
217toUpper = Native.String.toUpper
219{-| Convert a string to all lower case. Useful for case insensitive comparisons. -}
220toLower : String -> String
221toLower = Native.String.toLower
223{-| Check to see if *any* characters satisfy a predicate.
225 any isDigit "90210" == True
226 any isDigit "R2-D2" == True
227 any isDigit "heart" == False
228-}
229any : (Char -> Bool) -> String -> Bool
230any = Native.String.any
232{-| Check to see if *all* characters satisfy a predicate.
234 all isDigit "90210" == True
235 all isDigit "R2-D2" == False
236 any isDigit "heart" == False
237-}
238all : (Char -> Bool) -> String -> Bool
239all = Native.String.all
241{-| See if a string contains another one.
243 contains "the" "theory" == True
244 contains "hat" "theory" == False
245 contains "THE" "theory" == False
247Use `Regex.contains` if you need something more flexible.
248-}
249contains : String -> String -> Bool
250contains = Native.String.contains
252{-| See if a string starts with another one.
254 startsWith "the" "theory" == True
255 startsWith "ory" "theory" == False
256-}
257startsWith : String -> String -> Bool
258startsWith = Native.String.startsWith
260{-| See if a string ends with another one.
262 endsWith "the" "theory" == False
263 endsWith "ory" "theory" == True
264-}
265endsWith : String -> String -> Bool
266endsWith = Native.String.endsWith
268{-| Get all of the indexes for a substring.
270 indexes "i" "Mississippi" == [1,4,7,10]
271 indexes "ss" "Mississippi" == [2,5]
272 indexes "needle" "haystack" == []
273-}
274indexes : String -> String -> [Int]
275indexes = Native.String.indexes
277{-| Alias for `indexes` -}
278indices : String -> String -> [Int]
279indices = Native.String.indexes
281{-| Try to convert a string into an int, failing on improperly formatted strings.
283 toInt "123" == Just 123
284 toInt "-42" == Just -42
285 toInt "3.1" == Nothing
286 toInt "31a" == Nothing
287-}
288toInt : String -> Maybe Int
289toInt = Native.String.toInt
291{-| Try to convert a string into a float, failing on improperly formatted strings.
293 toFloat "123" == Just 123.0
294 toFloat "-42" == Just -42.0
295 toFloat "3.1" == Just 3.1
296 toFloat "31a" == Nothing
297-}
298toFloat : String -> Maybe Float
299toFloat = Native.String.toFloat
301{-| Convert a string to a list of characters.
303 toList "abc" == ['a','b','c']
304-}
305toList : String -> [Char]
306toList = Native.String.toList
308{-| Convert a list of characters into a String. Can be useful if you
309want to create a string primarly by consing, perhaps for decoding
310something.
312 fromList ['a','b','c'] == "abc"
313-}
314fromList : [Char] -> String
315fromList = Native.String.fromList