@@ -12,7 +12,7 @@ module String where
1212@docs sub, left, right, dropLeft, dropRight
1313
1414# Check for Substrings
15−@docs contains, startsWith, endsWith, indices, indexes
15+@docs contains, startsWith, endsWith, indexes, indices
1616
1717# Conversion To Numbers
1818@docs toInt, toFloat
@@ -28,38 +28,42 @@ Cosmetic operations such as padding with extra characters or trimming whitespace
2828import Native.String
2929import Maybe (Maybe)
3030
31−{-|
32−-}
31+{-| Check if a string is empty `(isEmpty "" == True)` -}
3332isEmpty : String
3433isEmpty = Native.String.isEmpty
3534
36−{-|
37−-}
35+{-| Add a character to the beginning of a string -}
3836cons : Char -> String -> String
3937cons = Native.String.cons
4038
41−{-|
39+{-| Split a non-empty string into its head and tail. This lets you
40+pattern match on strings exactly as you would with lists.
41+
42+ uncons "abc" == Just ('a',"bc")
43+ uncons "" == Nothing
4244-}
4345uncons : String -> Maybe (Char, String)
4446uncons = Native.String.uncons
4547
46−{-|
47−-}
48+{-| Get the length of a string `(length "innumerable" == 11)` -}
4849length : String -> Int
4950length = Native.String.length
5051
51−{-|
52+{-| Transform every character in a string
53+
54+ map (\c -> if c == '/' then '.' else c) "a/b/c" == "a.b.c"
5255-}
5356map : (Char -> Char) -> String -> String
5457map = Native.String.map
5558
56−{-|
59+{-| Keep only the characters that satisfy the predicate:
60+
61+ filter isDigit "R2-D2" == "22"
5762-}
5863filter : (Char -> Bool) -> String -> String
5964filter = Native.String.filter
6065
61−{-|
62−-}
66+{-| Reverse a string. `(reverse "stressed" == "desserts")` -}
6367reverse : String -> String
6468reverse = Native.String.reverse
6569
@@ -73,135 +77,197 @@ foldl = Native.String.foldl
7377foldr : (Char -> b -> b) -> b -> String -> b
7478foldr = Native.String.foldr
7579
76−{-|
80+{-| Split a string using a given separator.
81+
82+ split "," "cat,dog,cow" == ["cat","dog","cow"]
83+ split "/" "home/evan/Desktop/" == ["home","evan","Desktop"]
7784-}
7885split : String -> String -> [String]
7986split = Native.String.split
8087
81−{-|
88+{-| Put many strings together with a given separator.
89+
90+ join " " ["cat","dog","cow"] == "cat dog cow"
91+ join "/" ["home","evan","Desktop"] == "home/evan/Desktop"
8292-}
8393join : String -> [String] -> String
8494join = Native.String.join
8595
86−{-|
87−-}
96+{-| Repeat a string N times `(repeat 3 "ha" == "hahaha")` -}
8897repeat : Int -> String -> String
8998repeat = Native.String.repeat
9099
100+{-| Take a substring given a start and end index. Negative indexes
101+are taken starting from the *end* of the list.
102+
103+ sub 7 9 "snakes on a plane!" == "on"
104+ sub 0 6 "snakes on a plane!" == "snakes"
105+ sub 0 -7 "snakes on a plane!" == "snakes on a"
106+ sub -6 -1 "snakes on a plane!" == "plane"
107+-}
91108sub : Int -> Int -> String -> String
92109sub = Native.String.sub
93110
94−{-|
95−-}
111+{-| Take N characters from the left side of a string. -}
96112left : Int -> String -> String
97113left = Native.String.left
98114
99−{-|
100−-}
115+{-| Take N characters from the right side of a string. -}
101116right : Int -> String -> String
102117right = Native.String.right
103118
104−{-|
105−-}
119+{-| Drop N characters from the left side of a string. -}
106120dropLeft : Int -> String -> String
107121dropLeft = Native.String.dropLeft
108122
109−{-|
110−-}
123+{-| Drop N characters from the right side of a string. -}
111124dropRight : Int -> String -> String
112125dropRight = Native.String.dropRight
113126
114−{-|
127+{-| Pad a string on both sides until it has a given length.
128+
129+ pad 5 ' ' "1" == " 1 "
130+ pad 5 ' ' "11" == " 11 "
131+ pad 5 ' ' "121" == " 121 "
115132-}
116133pad : Int -> Char -> String -> String
117134pad = Native.String.pad
118135
119−{-|
136+{-| Pad a string on the left until it has a given length.
137+
138+ pad 5 '.' "1" == "....1"
139+ pad 5 '.' "11" == "...11"
140+ pad 5 '.' "121" == "..121"
120141-}
121142padLeft : Int -> Char -> String -> String
122143padLeft = Native.String.padLeft
123144
124−{-|
145+{-| Pad a string on the right until it has a given length.
146+
147+ pad 5 '.' "1" == "1...."
148+ pad 5 '.' "11" == "11..."
149+ pad 5 '.' "121" == "121.."
125150-}
126151padRight : Int -> Char -> String -> String
127152padRight = Native.String.padRight
128153
129−{-|
154+{-| Get rid of whitespace on both sides of a string.
155+
156+ trim " hats \n" == "hats"
130157-}
131158trim : String -> String
132159trim = Native.String.trim
133160
134−{-|
161+{-| Get rid of whitespace on the left of a string.
162+
163+ trimLeft " hats \n" == "hats \n"
135164-}
136165trimLeft : String -> String
137166trimLeft = Native.String.trimLeft
138167
139−{-|
168+{-| Get rid of whitespace on the left of a string.
169+
170+ trimRight " hats \n" == " hats"
140171-}
141172trimRight : String -> String
142173trimRight = Native.String.trimRight
143174
144−{-|
175+{-| Break a string into words, splitting on chunks of whitespace.
176+
177+ words "How are \t you? \n Good?" == ["How","are","you?","Good?"]
145178-}
146179words : String -> [String]
147180words = Native.String.words
148181
149−{-|
182+{-| Break a string into lines, splitting on newlines.
183+
184+ lines "How are you?\nGood? == ["How are you?", "Good?"]
150185-}
151186lines : String -> [String]
152187lines = Native.String.lines
153188
154−{-|
189+{-| Convert a string to all upper case. Useful for case insensitive comparisons
190+and VIRTUAL YELLING.
155191-}
156192toUpper : String -> String
157193toUpper = Native.String.toUpper
158194
159−{-|
160−-}
195+{-| Convert a string to all lower case. Useful for case insensitive comparisons. -}
161196toLower : String -> String
162197toLower = Native.String.toLower
163198
164−{-|
199+{-| Check to see if *any* characters satisfy a predicate.
200+
201+ any isDigit "90210" == True
202+ any isDigit "R2-D2" == True
203+ any isDigit "heart" == False
165204-}
166205any : (Char -> Bool) -> String -> Bool
167206any = Native.String.any
168207
169−{-|
208+{-| Check to see if *all* characters satisfy a predicate.
209+
210+ all isDigit "90210" == True
211+ all isDigit "R2-D2" == False
212+ any isDigit "heart" == False
170213-}
171214all : (Char -> Bool) -> String -> Bool
172215all = Native.String.all
173216
174−{-|
217+{-| See if a string contains another one.
218+
219+ contains "the" "theory" == True
220+ contains "hat" "theory" == False
221+ contains "THE" "theory" == False
175222-}
176223contains : String -> String -> Bool
177224contains = Native.String.contains
178225
179−{-|
226+{-| See if a string starts with another one.
227+
228+ startsWith "the" "theory" == True
229+ startsWith "ory" "theory" == False
180230-}
181231startsWith : String -> String -> Bool
182232startsWith = Native.String.startsWith
183233
184−{-|
234+{-| See if a string ends with another one.
235+
236+ endsWith "the" "theory" == False
237+ endsWith "ory" "theory" == True
185238-}
186239endsWith : String -> String -> Bool
187240endsWith = Native.String.endsWith
188241
189−{-|
190−-}
191−indices : String -> String -> [Int]
192−indices = Native.String.indexes
242+{-| Get all of the indexes for a substring.
193243
194−{-|
244+ indexes "i" "Mississippi" == [1,4,7,10]
245+ indexes "ss" "Mississippi" == [2,5]
246+ indexes "needle" "haystack" == []
195247-}
196248indexes : String -> String -> [Int]
197249indexes = Native.String.indexes
198250
199−{-|
251+{-| Alias for `indexes` -}
252+indices : String -> String -> [Int]
253+indices = Native.String.indexes
254+
255+{-| Try to convert a string into an int, failing on improperly formatted strings.
256+
257+ toInt "123" == Just 123
258+ toInt "-42" == Just -42
259+ toInt "3.1" == Nothing
260+ toInt "31a" == Nothing
200261-}
201262toInt : String -> Maybe Int
202263toInt = Native.String.toInt
203264
204−{-|
265+{-| Try to convert a string into a float, failing on improperly formatted strings.
266+
267+ toFloat "123" == Just 123.0
268+ toFloat "-42" == Just -42.0
269+ toFloat "3.1" == Just 3.1
270+ toFloat "31a" == Nothing
205271-}
206272toFloat : String -> Maybe Float
207273toFloat = Native.String.toFloat