@@ -1,30 +1,82 @@
11
22module Basics where
33
4+{-| Tons of useful functions that get imported by default.
5+
6+The following libraries also get imported by default: List, Signal,
7+Text, Maybe, Time, Graphics.Element, Color, Graphics.Collage.
8+
9+# To Strings
10+@docs show
11+
12+# Equality
13+@docs (==), (/=)
14+
15+# Comparison
16+
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?
21+
22+@docs (<), (>), (<=), (>=), max, min, Order, compare
23+
24+# Booleans
25+@docs not, (&&), (||), xor, otherwise
26+
27+# Mathematics
28+@docs (+), (-), (*), (/), (^), div, rem, mod, abs, sqrt, clamp, logBase, e
29+
30+# Trigonometry
31+@docs pi, cos, sin, tan, acos, asin, atan, atan2
32+
33+# Number Conversions
34+@docs round, floor, ceiling, truncate, toFloat, readInt, readFloat
35+
36+# Angle Conversions
37+All angle conversions result in “standard Elm angles”
38+which happen to be radians.
39+
40+@docs degrees, radians, turns
41+
42+# Polar Coordinates
43+@docs toPolar, fromPolar
44+
45+# Tuples
46+@docs fst, snd
47+
48+# Higher-Order Helpers
49+@docs id, (<|), (|>), (.), flip, curry, uncurry
50+
51+-}
52+
453import Native.Basics
554
655type String = [Char]
756
8−-- Convert radians to standard Elm angles (radians).
57+{-| Convert radians to standard Elm angles (radians). -}
958radians : Float -> Float
1059radians t = t
1160
12−-- Convert degrees to standard Elm angles (radians).
61+{-| Convert degrees to standard Elm angles (radians). -}
1362degrees : Float -> Float
1463degrees d = d * Native.Basics.pi / 180
1564
16−-- Convert turns to standard Elm angles (radians).
17−-- One turn is equal to 360°.
65+{-| Convert turns to standard Elm angles (radians).
66+One turn is equal to 360°.
67+-}
1868turns : Float -> Float
1969turns r = 2 * Native.Basics.pi * r
2070
21−-- Start with polar coordinates (r,θ)
22−-- and get out cartesian coordinates (x,y).
71+{-| Start with polar coordinates (r,θ)
72+and get out cartesian coordinates (x,y).
73+-}
2374fromPolar : (Float,Float) -> (Float,Float)
2475fromPolar (r,t) = (r * Native.Basics.cos t, r * Native.Basics.sin t)
2576
26−-- Start with cartesian coordinates (x,y)
27−-- and get out polar coordinates (r,θ).
77+{-| Start with cartesian coordinates (x,y)
78+and get out polar coordinates (r,θ).
79+-}
2880toPolar : (Float,Float) -> (Float,Float)
2981toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
3082
@@ -37,23 +89,29 @@ toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
3789(*) : number -> number -> number
3890(*) = Native.Basics.mul
3991
40−-- Floating point division.
92+{-| Floating point division. -}
4193(/) : Float -> Float -> Float
4294(/) = Native.Basics.floatDiv
4395
44−-- Integer division, remainder is discarded.
96+infixl 6 +
97+infixl 6 -
98+infixl 7 *
99+infixl 7 /
100+infixl 8 ^
101+
102+{-| Integer division, remainder is discarded. -}
45103div : Int -> Int -> Int
46104div = Native.Basics.div
47105
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`` -}
49107rem : Int -> Int -> Int
50108rem = Native.Basics.rem
51109
52−-- Perform modular arithmetic: ``7 `mod` 2 == 1``
110+{-| Perform modular arithmetic: ``7 `mod` 2 == 1`` -}
53111mod : Int -> Int -> Int
54112mod = Native.Basics.mod
55113
56−-- Exponentiation: `3^2 == 9`
114+{-| Exponentiation: `3^2 == 9` -}
57115(^) : number -> number -> number
58116(^) = Native.Basics.exp
59117
@@ -72,58 +130,52 @@ acos = Native.Basics.acos
72130asin : Float -> Float
73131asin = Native.Basics.asin
74132
75−-- You probably do not want to use this. Because it takes `(y/x)` as the argument
76−-- there is no way to know where the negative signs come from so the resulting
77−-- angle is always between π/2 and -π/2 (in quadrants I and IV).
133+{-| You probably do not want to use this. Because it takes `(y/x)` as the
134+argument there is no way to know where the negative signs come from so the
135+resulting angle is always between π/2 and -π/2 (in quadrants I and IV).
136+-}
78137atan : Float -> Float
79138atan = Native.Basics.atan
80139
81−-- This helps you find the angle of a cartesian coordinate.
82−-- 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
84−-- quadrant the angle should really be in. The result will be between
85−-- π and -π, giving you the full range of angles.
140+{-| This helps you find the angle of a cartesian coordinate.
141+You will almost certainly want to use this instead of `atan`.
142+So `atan2 y x` computes *atan(y/x)* but also keeps track of which
143+quadrant the angle should really be in. The result will be between
144+π and -π, giving you the full range of angles.
145+-}
86146atan2 : Float -> Float -> Float
87147atan2 = Native.Basics.atan2
88148
89−-- Take the square root of a number.
149+{-| Take the square root of a number. -}
90150sqrt : number -> number
91151sqrt = Native.Basics.sqrt
92152
93−-- Take the absolute value of a number.
153+{-| Take the absolute value of a number. -}
94154abs : number -> number
95155abs = Native.Basics.abs
96156
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` -}
98158logBase : number -> number -> number
99159logBase = Native.Basics.logBase
100160
101−-- Given two comparables, returns the smaller one.
102−min : comparable -> comparable -> comparable
103−min = Native.Basics.min
161+{-| Clamps a number within a given range. With the expression
162+`clamp 100 200 x` the results are as follows:
104163
105−-- Given two comparables, returns the larger one.
106−max : comparable -> comparable -> comparable
107−max = Native.Basics.max
108−
109−-- Clamps a number within a given range. With the expression `clamp 100 200 x`
110−-- the results are as follows:
111−--
112−-- * `100 if x < 100`
113−-- * ` x if 100 <= x < 200`
114−-- * `200 if 200 <= x`
164+ 100 if x < 100
165+ x if 100 <= x < 200
166+ 200 if 200 <= x
167+-}
115168clamp : number -> number -> number -> number
116169clamp = Native.Basics.clamp
117170
118−-- An approximation of pi.
171+{-| An approximation of pi. -}
119172pi : Float
120173pi = Native.Basics.pi
121174
122−-- An approximation of e.
175+{-| An approximation of e. -}
123176e : Float
124177e = Native.Basics.e
125178
126−-- Compare any two values for structural equality. Functions cannot be compared.
127179(==) : a -> a -> Bool
128180(==) = Native.Basics.eq
129181
@@ -142,113 +194,141 @@ e = Native.Basics.e
142194(>=) : comparable -> comparable -> Bool
143195(>=) = Native.Basics.ge
144196
145−-- Compare any two comparable values. Comparable values include `String`, `Char`,
146−-- `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.
197+infix 4 ==
198+infix 4 /=
199+infix 4 <
200+infix 4 >
201+infix 4 <=
202+infix 4 >=
203+
204+{-| Compare any two comparable values. Comparable values include `String`, `Char`,
205+`Int`, `Float`, `Time`, or a list or tuple containing comparable values.
206+These are also the only values that work as `Dict` keys or `Set` members.
207+-}
148208compare : comparable -> comparable -> Order
149209compare = Native.Basics.compare
150210
151−-- Represents the relative ordering of two things.
152−-- The relations are less than, equal to, and greater than.
211+{-| Represents the relative ordering of two things.
212+The relations are less than, equal to, and greater than.
213+-}
153214data Order = LT | EQ | GT
154215
155−-- The and operator. True if both inputs are True.
216+{-| Given two comparables, returns the smaller one. -}
217+min : comparable -> comparable -> comparable
218+min = Native.Basics.min
219+
220+{-| Given two comparables, returns the larger one. -}
221+max : comparable -> comparable -> comparable
222+max = Native.Basics.max
223+
224+{-| The and operator. True if both inputs are True. -}
156225(&&) : Bool -> Bool -> Bool
157226(&&) = Native.Basics.and
158227
159−-- The or operator. True if one or both inputs are True.
228+{-| The or operator. True if one or both inputs are True. -}
160229(||) : Bool -> Bool -> Bool
161230(||) = Native.Basics.or
162231
163−-- The exclusive-or operator. True if exactly one input is True.
232+infixr 3 &&
233+infixr 2 ||
234+
235+{-| The exclusive-or operator. True if exactly one input is True. -}
164236xor : Bool -> Bool -> Bool
165237xor = Native.Basics.xor
166238
167−-- Negate a boolean value: `(not True == False)` and `(not False == True)`
239+{-| Negate a boolean value: `(not True == False)` and `(not False == True)` -}
168240not : Bool -> Bool
169241not = Native.Basics.not
170242
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. -}
172244otherwise : Bool
173245otherwise = True
174246
175247
176248-- Conversions
177249
178−-- Round a number to the nearest integer.
250+{-| Round a number to the nearest integer. -}
179251round : Float -> Int
180252round = Native.Basics.round
181253
182−-- Truncate a decimal number, rounding towards zero.
254+{-| Truncate a decimal number, rounding towards zero. -}
183255truncate : Float -> Int
184256truncate = Native.Basics.truncate
185257
186−-- Floor function, rounding down.
258+{-| Floor function, rounding down. -}
187259floor : Float -> Int
188260floor = Native.Basics.floor
189261
190−-- Ceiling function, rounding up.
262+{-| Ceiling function, rounding up. -}
191263ceiling : Float -> Int
192264ceiling = Native.Basics.ceiling
193265
194−-- Convert an integer into a float.
266+{-| Convert an integer into a float. -}
195267toFloat : Int -> Float
196268toFloat = Native.Basics.toFloat
197269
198270
199271-- Function Helpers
200272
201−-- Function composition: `(f . g == (\\x -> f (g x)))`
273+{-| Function composition: `(f . g == (\\x -> f (g x)))` -}
202274(.) : (b -> c) -> (a -> b) -> (a -> c)
203275(.) f g x = f (g x)
204276
205−-- Forward function application `x |> f == f x`. This function is useful
206−-- for avoiding parenthesis and writing code in a more natural way.
207−-- Consider the following code to create a pentagon:
208−--
209−-- scale 2 (move (10,10) (filled blue (ngon 5 30)))
210−--
211−-- This can also be written as:
212−--
213−-- ngon 5 30 |> filled blue
214−-- |> move (10,10)
215−-- |> scale 2
277+{-| Forward function application `x |> f == f x`. This function is useful
278+for avoiding parenthesis and writing code in a more natural way.
279+Consider the following code to create a pentagon:
280+
281+ scale 2 (move (10,10) (filled blue (ngon 5 30)))
282+
283+This can also be written as:
284+
285+ ngon 5 30 |> filled blue
286+ |> move (10,10)
287+ |> scale 2
288+-}
216289(|>) : a -> (a -> b) -> b
217290x |> f = f x
218291
219−-- Function application `f <| x == f x`. This function is useful for avoiding
220−-- parenthesis. Consider the following code to create a text element:
221−--
222−-- text (monospace (toText "code"))
223−--
224−-- This can also be written as:
225−--
226−-- text . monospace <| toText "code"
292+{-| Function application `f <| x == f x`. This function is useful for avoiding
293+parenthesis. Consider the following code to create a text element:
294+
295+ text (monospace (toText "code"))
296+
297+This can also be written as:
298+
299+ text . monospace <| toText "code"
300+-}
227301(<|) : (a -> b) -> a -> b
228302f <| x = f x
229303
230−-- Given a value, returns exactly the same value.
304+infixr 9 .
305+infixr 0 <|
306+infixl 0 |>
307+
308+{-| Given a value, returns exactly the same value. -}
231309id : a -> a
232310id x = x
233311
234−-- Given a 2-tuple, returns the first value.
312+{-| Given a 2-tuple, returns the first value. -}
235313fst : (a,b) -> a
236314fst = Native.Basics.fst
237315
238−-- Given a 2-tuple, returns the second value.
316+{-| Given a 2-tuple, returns the second value. -}
239317snd : (a,b) -> b
240318snd = Native.Basics.snd
241319
242−-- Flips the order of the first two arguments to a function.
320+{-| Flips the order of the first two arguments to a function. -}
243321flip : (a -> b -> c) -> (b -> a -> c)
244322flip f b a = f a b
245323
246−-- Change how arguments are passed to a function. This splits paired arguments
247−-- into two separate arguments.
324+{-| Change how arguments are passed to a function.
325+This splits paired arguments into two separate arguments.
326+-}
248327curry : ((a,b) -> c) -> a -> b -> c
249328curry = Native.Basics.curry
250329
251−-- Change how arguments are passed to a function. This combines two arguments
252−-- into a sigle pair.
330+{-| Change how arguments are passed to a function.
331+This combines two arguments into a sigle pair.
332+-}
253333uncurry : (a -> b -> c) -> (a,b) -> c
254334uncurry = Native.Basics.uncurry