@@ -1,30 +1,82 @@
2module Basics where
2module Basics where
4+{-| Tons of useful functions that get imported by default.
6+The following libraries also get imported by default: List, Signal,
7+Text, Maybe, Time, Graphics.Element, Color, Graphics.Collage.
17+These functions only work on `comparable` types. This includes numbers,
18+characters, strings, lists of comparable things, and tuples of comparable
19+things. Note that tuples with 7 or more elements are not comparable; why
20+are your tuples so big?
22+@docs (<), (>), (<=), (>=), max, min, Order, compare
25+@docs not, (&&), (||), xor, otherwise
28+@docs (+), (-), (*), (/), (^), div, rem, mod, abs, sqrt, clamp, logBase, e
31+@docs pi, cos, sin, tan, acos, asin, atan, atan2
34+@docs round, floor, ceiling, truncate, toFloat, readInt, readFloat
37+All angle conversions result in “standard Elm angles”
38+which happen to be radians.
40+@docs degrees, radians, turns
43+@docs toPolar, fromPolar
48+# Higher-Order Helpers
49+@docs id, (<|), (|>), (.), flip, curry, uncurry
4import Native.Basics
53import Native.Basics
6type String = [Char]
55type String = [Char]
8−-- Convert radians to standard Elm angles (radians).
57+{-| Convert radians to standard Elm angles (radians). -}
9radians : Float -> Float
58radians : Float -> Float
10radians t = t
59radians t = t
12−-- Convert degrees to standard Elm angles (radians).
61+{-| Convert degrees to standard Elm angles (radians). -}
13degrees : Float -> Float
62degrees : Float -> Float
14degrees d = d * Native.Basics.pi / 180
63degrees d = d * Native.Basics.pi / 180
16−-- Convert turns to standard Elm angles (radians).
65+{-| Convert turns to standard Elm angles (radians).
17−-- One turn is equal to 360°.
66+One turn is equal to 360°.
18turns : Float -> Float
68turns : Float -> Float
19turns r = 2 * Native.Basics.pi * r
69turns r = 2 * Native.Basics.pi * r
21−-- Start with polar coordinates (r,θ)
71+{-| Start with polar coordinates (r,θ)
22−-- and get out cartesian coordinates (x,y).
72+and get out cartesian coordinates (x,y).
23fromPolar : (Float,Float) -> (Float,Float)
74fromPolar : (Float,Float) -> (Float,Float)
24fromPolar (r,t) = (r * Native.Basics.cos t, r * Native.Basics.sin t)
75fromPolar (r,t) = (r * Native.Basics.cos t, r * Native.Basics.sin t)
26−-- Start with cartesian coordinates (x,y)
77+{-| Start with cartesian coordinates (x,y)
27−-- and get out polar coordinates (r,θ).
78+and get out polar coordinates (r,θ).
28toPolar : (Float,Float) -> (Float,Float)
80toPolar : (Float,Float) -> (Float,Float)
29toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
81toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
@@ -37,23 +89,29 @@ toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
37(*) : number -> number -> number
89(*) : number -> number -> number
38(*) = Native.Basics.mul
90(*) = Native.Basics.mul
40−-- Floating point division.
92+{-| Floating point division. -}
41(/) : Float -> Float -> Float
93(/) : Float -> Float -> Float
42(/) = Native.Basics.floatDiv
94(/) = Native.Basics.floatDiv
44−-- Integer division, remainder is discarded.
102+{-| Integer division, remainder is discarded. -}
45div : Int -> Int -> Int
103div : Int -> Int -> Int
46div = Native.Basics.div
104div = Native.Basics.div
48−-- Finds the remainder after dividing one number by another: ``4 `rem` 3 == 1``
106+{-| Finds the remainder after dividing one number by another: ``4 `rem` 3 == 1`` -}
49rem : Int -> Int -> Int
107rem : Int -> Int -> Int
50rem = Native.Basics.rem
108rem = Native.Basics.rem
52−-- Perform modular arithmetic: ``7 `mod` 2 == 1``
110+{-| Perform modular arithmetic: ``7 `mod` 2 == 1`` -}
53mod : Int -> Int -> Int
111mod : Int -> Int -> Int
54mod = Native.Basics.mod
112mod = Native.Basics.mod
56−-- Exponentiation: `3^2 == 9`
114+{-| Exponentiation: `3^2 == 9` -}
57(^) : number -> number -> number
115(^) : number -> number -> number
58(^) = Native.Basics.exp
116(^) = Native.Basics.exp
@@ -72,58 +130,52 @@ acos = Native.Basics.acos
72asin : Float -> Float
130asin : Float -> Float
73asin = Native.Basics.asin
131asin = Native.Basics.asin
75−-- You probably do not want to use this. Because it takes `(y/x)` as the argument
133+{-| You probably do not want to use this. Because it takes `(y/x)` as the
76−-- there is no way to know where the negative signs come from so the resulting
134+argument there is no way to know where the negative signs come from so the
77−-- angle is always between π/2 and -π/2 (in quadrants I and IV).
135+resulting angle is always between π/2 and -π/2 (in quadrants I and IV).
78atan : Float -> Float
137atan : Float -> Float
79atan = Native.Basics.atan
138atan = Native.Basics.atan
81−-- This helps you find the angle of a cartesian coordinate.
140+{-| This helps you find the angle of a cartesian coordinate.
82−-- You will almost certainly want to use this instead of `atan`.
141+You will almost certainly want to use this instead of `atan`.
83−-- So `atan2 y x` computes *atan(y/x)* but also keeps track of which
142+So `atan2 y x` computes *atan(y/x)* but also keeps track of which
84−-- quadrant the angle should really be in. The result will be between
143+quadrant the angle should really be in. The result will be between
85−-- π and -π, giving you the full range of angles.
144+π and -π, giving you the full range of angles.
86atan2 : Float -> Float -> Float
146atan2 : Float -> Float -> Float
87atan2 = Native.Basics.atan2
147atan2 = Native.Basics.atan2
89−-- Take the square root of a number.
149+{-| Take the square root of a number. -}
90sqrt : number -> number
150sqrt : number -> number
91sqrt = Native.Basics.sqrt
151sqrt = Native.Basics.sqrt
93−-- Take the absolute value of a number.
153+{-| Take the absolute value of a number. -}
94abs : number -> number
154abs : number -> number
95abs = Native.Basics.abs
155abs = Native.Basics.abs
97−-- Calculate the logarithm of a number with a given base: `logBase 10 100 == 2`
157+{-| Calculate the logarithm of a number with a given base: `logBase 10 100 == 2` -}
98logBase : number -> number -> number
158logBase : number -> number -> number
99logBase = Native.Basics.logBase
159logBase = Native.Basics.logBase
101−-- Given two comparables, returns the smaller one.
161+{-| Clamps a number within a given range. With the expression
102−min : comparable -> comparable -> comparable
162+`clamp 100 200 x` the results are as follows:
103−min = Native.Basics.min
105−-- Given two comparables, returns the larger one.
106−max : comparable -> comparable -> comparable
107−max = Native.Basics.max
109−-- Clamps a number within a given range. With the expression `clamp 100 200 x`
110−-- the results are as follows:
112−-- * `100 if x < 100`
164+ 100 if x < 100
113−-- * ` x if 100 <= x < 200`
165+ x if 100 <= x < 200
114−-- * `200 if 200 <= x`
166+ 200 if 200 <= x
115clamp : number -> number -> number -> number
168clamp : number -> number -> number -> number
116clamp = Native.Basics.clamp
169clamp = Native.Basics.clamp
118−-- An approximation of pi.
171+{-| An approximation of pi. -}
119pi : Float
172pi : Float
120pi = Native.Basics.pi
173pi = Native.Basics.pi
122−-- An approximation of e.
175+{-| An approximation of e. -}
124e = Native.Basics.e
177e = Native.Basics.e
126−-- Compare any two values for structural equality. Functions cannot be compared.
127(==) : a -> a -> Bool
179(==) : a -> a -> Bool
128(==) = Native.Basics.eq
180(==) = Native.Basics.eq
@@ -142,113 +194,141 @@ e = Native.Basics.e
142(>=) : comparable -> comparable -> Bool
194(>=) : comparable -> comparable -> Bool
143(>=) = Native.Basics.ge
195(>=) = Native.Basics.ge
145−-- Compare any two comparable values. Comparable values include `String`, `Char`,
204+{-| Compare any two comparable values. Comparable values include `String`, `Char`,
146−-- `Int`, `Float`, `Time`, or a list or tuple containing comparable values.
205+`Int`, `Float`, `Time`, or a list or tuple containing comparable values.
147−-- These are also the only values that work as `Dict` keys or `Set` members.
206+These are also the only values that work as `Dict` keys or `Set` members.
148compare : comparable -> comparable -> Order
208compare : comparable -> comparable -> Order
149compare = Native.Basics.compare
209compare = Native.Basics.compare
151−-- Represents the relative ordering of two things.
211+{-| Represents the relative ordering of two things.
152−-- The relations are less than, equal to, and greater than.
212+The relations are less than, equal to, and greater than.
153data Order = LT | EQ | GT
214data Order = LT | EQ | GT
216+{-| Given two comparables, returns the smaller one. -}
217+min : comparable -> comparable -> comparable
218+min = Native.Basics.min
220+{-| Given two comparables, returns the larger one. -}
221+max : comparable -> comparable -> comparable
222+max = Native.Basics.max
155−-- The and operator. True if both inputs are True.
224+{-| The and operator. True if both inputs are True. -}
156(&&) : Bool -> Bool -> Bool
225(&&) : Bool -> Bool -> Bool
157(&&) = Native.Basics.and
226(&&) = Native.Basics.and
159−-- The or operator. True if one or both inputs are True.
228+{-| The or operator. True if one or both inputs are True. -}
160(||) : Bool -> Bool -> Bool
229(||) : Bool -> Bool -> Bool
161(||) = Native.Basics.or
230(||) = Native.Basics.or
163−-- The exclusive-or operator. True if exactly one input is True.
235+{-| The exclusive-or operator. True if exactly one input is True. -}
164xor : Bool -> Bool -> Bool
236xor : Bool -> Bool -> Bool
165xor = Native.Basics.xor
237xor = Native.Basics.xor
167−-- Negate a boolean value: `(not True == False)` and `(not False == True)`
239+{-| Negate a boolean value: `(not True == False)` and `(not False == True)` -}
168not : Bool -> Bool
240not : Bool -> Bool
169not = Native.Basics.not
241not = Native.Basics.not
171−-- Equal to true. Useful as the last case of a multi-way-if.
243+{-| Equal to true. Useful as the last case of a multi-way-if. -}
172otherwise : Bool
244otherwise : Bool
173otherwise = True
245otherwise = True
176-- Conversions
248-- Conversions
178−-- Round a number to the nearest integer.
250+{-| Round a number to the nearest integer. -}
179round : Float -> Int
251round : Float -> Int
180round = Native.Basics.round
252round = Native.Basics.round
182−-- Truncate a decimal number, rounding towards zero.
254+{-| Truncate a decimal number, rounding towards zero. -}
183truncate : Float -> Int
255truncate : Float -> Int
184truncate = Native.Basics.truncate
256truncate = Native.Basics.truncate
186−-- Floor function, rounding down.
258+{-| Floor function, rounding down. -}
187floor : Float -> Int
259floor : Float -> Int
188floor = Native.Basics.floor
260floor = Native.Basics.floor
190−-- Ceiling function, rounding up.
262+{-| Ceiling function, rounding up. -}
191ceiling : Float -> Int
263ceiling : Float -> Int
192ceiling = Native.Basics.ceiling
264ceiling = Native.Basics.ceiling
194−-- Convert an integer into a float.
266+{-| Convert an integer into a float. -}
195toFloat : Int -> Float
267toFloat : Int -> Float
196toFloat = Native.Basics.toFloat
268toFloat = Native.Basics.toFloat
199-- Function Helpers
271-- Function Helpers
201−-- Function composition: `(f . g == (\\x -> f (g x)))`
273+{-| Function composition: `(f . g == (\\x -> f (g x)))` -}
202(.) : (b -> c) -> (a -> b) -> (a -> c)
274(.) : (b -> c) -> (a -> b) -> (a -> c)
203(.) f g x = f (g x)
275(.) f g x = f (g x)
205−-- Forward function application `x |> f == f x`. This function is useful
277+{-| Forward function application `x |> f == f x`. This function is useful
206−-- for avoiding parenthesis and writing code in a more natural way.
278+for avoiding parenthesis and writing code in a more natural way.
207−-- Consider the following code to create a pentagon:
279+Consider the following code to create a pentagon:
209−-- scale 2 (move (10,10) (filled blue (ngon 5 30)))
281+ scale 2 (move (10,10) (filled blue (ngon 5 30)))
211−-- This can also be written as:
283+This can also be written as:
213−-- ngon 5 30 |> filled blue
285+ ngon 5 30 |> filled blue
214−-- |> move (10,10)
286+ |> move (10,10)
215−-- |> scale 2
287+ |> scale 2
216(|>) : a -> (a -> b) -> b
289(|>) : a -> (a -> b) -> b
217x |> f = f x
290x |> f = f x
219−-- Function application `f <| x == f x`. This function is useful for avoiding
292+{-| Function application `f <| x == f x`. This function is useful for avoiding
220−-- parenthesis. Consider the following code to create a text element:
293+parenthesis. Consider the following code to create a text element:
222−-- text (monospace (toText "code"))
295+ text (monospace (toText "code"))
224−-- This can also be written as:
297+This can also be written as:
226−-- text . monospace <| toText "code"
299+ text . monospace <| toText "code"
227(<|) : (a -> b) -> a -> b
301(<|) : (a -> b) -> a -> b
228f <| x = f x
302f <| x = f x
230−-- Given a value, returns exactly the same value.
308+{-| Given a value, returns exactly the same value. -}
231id : a -> a
309id : a -> a
234−-- Given a 2-tuple, returns the first value.
312+{-| Given a 2-tuple, returns the first value. -}
235fst : (a,b) -> a
313fst : (a,b) -> a
236fst = Native.Basics.fst
314fst = Native.Basics.fst
238−-- Given a 2-tuple, returns the second value.
316+{-| Given a 2-tuple, returns the second value. -}
239snd : (a,b) -> b
317snd : (a,b) -> b
240snd = Native.Basics.snd
318snd = Native.Basics.snd
242−-- Flips the order of the first two arguments to a function.
320+{-| Flips the order of the first two arguments to a function. -}
243flip : (a -> b -> c) -> (b -> a -> c)
321flip : (a -> b -> c) -> (b -> a -> c)
244flip f b a = f a b
322flip f b a = f a b
246−-- Change how arguments are passed to a function. This splits paired arguments
324+{-| Change how arguments are passed to a function.
247−-- into two separate arguments.
325+This splits paired arguments into two separate arguments.
248curry : ((a,b) -> c) -> a -> b -> c
327curry : ((a,b) -> c) -> a -> b -> c
249curry = Native.Basics.curry
328curry = Native.Basics.curry
251−-- Change how arguments are passed to a function. This combines two arguments
330+{-| Change how arguments are passed to a function.
252−-- into a sigle pair.
331+This combines two arguments into a sigle pair.
253uncurry : (a -> b -> c) -> (a,b) -> c
333uncurry : (a -> b -> c) -> (a,b) -> c
254uncurry = Native.Basics.uncurry
334uncurry = Native.Basics.uncurry