git.iko.soy/elk
on 4bec310 help sign in
elk/libraries/Basics.elm
381 lines 9.7 kB history raw
2module Basics where
4{-| Tons of useful functions that get imported by default.
6The following libraries also get imported by default: List, Signal,
7Text, Maybe, Time, Graphics.Element, Color, Graphics.Collage.
9# Equality
10@docs (==), (/=)
12# Comparison
14These functions only work on `comparable` types. This includes numbers,
15characters, strings, lists of comparable things, and tuples of comparable
16things. Note that tuples with 7 or more elements are not comparable; why
17are your tuples so big?
19@docs (<), (>), (<=), (>=), max, min, Order, compare
21# Booleans
22@docs not, (&&), (||), xor, otherwise
24# Mathematics
25@docs (+), (-), (*), (/), (^), div, rem, mod, abs, sqrt, clamp, logBase, e
27# Trigonometry
28@docs pi, cos, sin, tan, acos, asin, atan, atan2
30# Number Conversions
31@docs round, floor, ceiling, truncate, toFloat
33# Angle Conversions
34All angle conversions result in &ldquo;standard Elm angles&rdquo;
35which happen to be radians.
37@docs degrees, radians, turns
39# Polar Coordinates
40@docs toPolar, fromPolar
42# Floating Point Checks
43@docs isNaN, isInfinite
45# Tuples
46@docs fst, snd
48# Higher-Order Helpers
49@docs id, (<|), (|>), (.), always, flip, curry, uncurry
51-}
53import Native.Basics
55{-| Convert radians to standard Elm angles (radians). -}
56radians : Float -> Float
57radians t = t
59{-| Convert degrees to standard Elm angles (radians). -}
60degrees : Float -> Float
61degrees d = d * Native.Basics.pi / 180
63{-| Convert turns to standard Elm angles (radians).
64One turn is equal to 360&deg;.
65-}
66turns : Float -> Float
67turns r = 2 * Native.Basics.pi * r
69{-| Start with polar coordinates (r,&theta;)
70and get out cartesian coordinates (x,y).
71-}
72fromPolar : (Float,Float) -> (Float,Float)
73fromPolar (r,t) = (r * Native.Basics.cos t, r * Native.Basics.sin t)
75{-| Start with cartesian coordinates (x,y)
76and get out polar coordinates (r,&theta;).
77-}
78toPolar : (Float,Float) -> (Float,Float)
79toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
81(+) : number -> number -> number
82(+) = Native.Basics.add
84(-) : number -> number -> number
85(-) = Native.Basics.sub
87(*) : number -> number -> number
88(*) = Native.Basics.mul
90{-| Floating point division. -}
91(/) : Float -> Float -> Float
92(/) = Native.Basics.floatDiv
94infixl 6 +
95infixl 6 -
96infixl 7 *
97infixl 7 /
98infixl 8 ^
100infixl 7 `div`
101infixl 7 `mod`
102infixl 7 `rem`
104{-| Integer division, remainder is discarded. -}
105div : Int -> Int -> Int
106div = Native.Basics.div
108{-| Finds the remainder after dividing one number by another: ``4 `rem` 3 == 1`` -}
109rem : Int -> Int -> Int
110rem = Native.Basics.rem
112{-| Perform modular arithmetic: ``7 `mod` 2 == 1`` -}
113mod : Int -> Int -> Int
114mod = Native.Basics.mod
116{-| Exponentiation: `3^2 == 9` -}
117(^) : number -> number -> number
118(^) = Native.Basics.exp
120cos : Float -> Float
121cos = Native.Basics.cos
123sin : Float -> Float
124sin = Native.Basics.sin
126tan : Float -> Float
127tan = Native.Basics.tan
129acos : Float -> Float
130acos = Native.Basics.acos
132asin : Float -> Float
133asin = Native.Basics.asin
135{-| You probably do not want to use this. It takes `(y/x)` as the
136argument, so there is no way to know whether the negative signs comes from
137the `y` or `x`. Thus, the resulting angle is always between &pi;/2 and -&pi;/2
138(in quadrants I and IV). You probably want to use `atan2` instead.
139-}
140atan : Float -> Float
141atan = Native.Basics.atan
143{-| This helps you find the angle of a cartesian coordinate.
144You will almost certainly want to use this instead of `atan`.
145So `atan2 y x` computes *atan(y/x)* but also keeps track of which
146quadrant the angle should really be in. The result will be between
147&pi; and -&pi;, giving you the full range of angles.
148-}
149atan2 : Float -> Float -> Float
150atan2 = Native.Basics.atan2
152{-| Take the square root of a number. -}
153sqrt : number -> number
154sqrt = Native.Basics.sqrt
156{-| Take the absolute value of a number. -}
157abs : number -> number
158abs = Native.Basics.abs
160{-| Calculate the logarithm of a number with a given base: `logBase 10 100 == 2` -}
161logBase : number -> number -> number
162logBase = Native.Basics.logBase
164{-| Clamps a number within a given range. With the expression
165`clamp 100 200 x` the results are as follows:
167 100 if x < 100
168 x if 100 <= x < 200
169 200 if 200 <= x
170-}
171clamp : number -> number -> number -> number
172clamp = Native.Basics.clamp
174{-| An approximation of pi. -}
175pi : Float
176pi = Native.Basics.pi
178{-| An approximation of e. -}
179e : Float
180e = Native.Basics.e
182(==) : a -> a -> Bool
183(==) = Native.Basics.eq
185(/=) : a -> a -> Bool
186(/=) = Native.Basics.neq
188(<) : comparable -> comparable -> Bool
189(<) = Native.Basics.lt
191(>) : comparable -> comparable -> Bool
192(>) = Native.Basics.gt
194(<=) : comparable -> comparable -> Bool
195(<=) = Native.Basics.le
197(>=) : comparable -> comparable -> Bool
198(>=) = Native.Basics.ge
200infix 4 ==
201infix 4 /=
202infix 4 <
203infix 4 >
204infix 4 <=
205infix 4 >=
207{-| Compare any two comparable values. Comparable values include `String`, `Char`,
208`Int`, `Float`, `Time`, or a list or tuple containing comparable values.
209These are also the only values that work as `Dict` keys or `Set` members.
210-}
211compare : comparable -> comparable -> Order
212compare = Native.Basics.compare
214{-| Represents the relative ordering of two things.
215The relations are less than, equal to, and greater than.
216-}
217data Order = LT | EQ | GT
219{-| Given two comparables, returns the smaller one. -}
220min : comparable -> comparable -> comparable
221min = Native.Basics.min
223{-| Given two comparables, returns the larger one. -}
224max : comparable -> comparable -> comparable
225max = Native.Basics.max
227{-| The and operator. True if both inputs are True.
228This operator short-circuits if the first argument is False.
229-}
230(&&) : Bool -> Bool -> Bool
231(&&) = Native.Basics.and
233{-| The or operator. True if one or both inputs are True.
234This operator short-circuits if the first argument is True.
235-}
236(||) : Bool -> Bool -> Bool
237(||) = Native.Basics.or
239infixr 3 &&
240infixr 2 ||
242{-| The exclusive-or operator. True if exactly one input is True. -}
243xor : Bool -> Bool -> Bool
244xor = Native.Basics.xor
246{-| Negate a boolean value: `(not True == False)` and `(not False == True)` -}
247not : Bool -> Bool
248not = Native.Basics.not
250{-| Equal to true. Useful as the last case of a multi-way-if. -}
251otherwise : Bool
252otherwise = True
255-- Conversions
257{-| Round a number to the nearest integer. -}
258round : Float -> Int
259round = Native.Basics.round
261{-| Truncate a decimal number, rounding towards zero. -}
262truncate : Float -> Int
263truncate = Native.Basics.truncate
265{-| Floor function, rounding down. -}
266floor : Float -> Int
267floor = Native.Basics.floor
269{-| Ceiling function, rounding up. -}
270ceiling : Float -> Int
271ceiling = Native.Basics.ceiling
273{-| Convert an integer into a float. -}
274toFloat : Int -> Float
275toFloat = Native.Basics.toFloat
277{- | Determines whether a float is an undefined or unrepresentable number.
278NaN stands for *not a number* and it is [a standardized part of floating point
279numbers](http://en.wikipedia.org/wiki/NaN).
281 isNaN (0/0) == True
282 isNaN (sqrt -1) == True
283 isNaN (1/0) == False -- infinity is a number
284 isNaN 1 == False
285-}
286isNaN : Float -> Bool
287isNaN = Native.Basics.isNaN
289{- | Determines whether a float is positive or negative infinity.
291 isInfinite (0/0) == False
292 isInfinite (sqrt -1) == False
293 isInfinite (1/0) == True
294 isInfinite 1 == False
296Notice that NaN is not infinite! For float `n` to be finite implies that
297`not (isInfinite n || isNaN n)` evaluates to `True`.
298-}
299isInfinite : Float -> Bool
300isInfinite = Native.Basics.isInfinite
302-- Function Helpers
304{-| Function composition: `(f . g == (\\x -> f (g x)))` -}
305(.) : (b -> c) -> (a -> b) -> (a -> c)
306(.) f g x = f (g x)
308{-| Forward function application `x |> f == f x`. This function is useful
309for avoiding parenthesis and writing code in a more natural way.
310Consider the following code to create a pentagon:
312 scale 2 (move (10,10) (filled blue (ngon 5 30)))
314This can also be written as:
316 ngon 5 30 |> filled blue
317 |> move (10,10)
318 |> scale 2
319-}
320(|>) : a -> (a -> b) -> b
321x |> f = f x
323{-| Function application `f <| x == f x`. This function is useful for avoiding
324parenthesis. Consider the following code to create a text element:
326 text (monospace (toText "code"))
328This can also be written as:
330 text . monospace <| toText "code"
331-}
332(<|) : (a -> b) -> a -> b
333f <| x = f x
335infixr 9 .
336infixr 0 <|
337infixl 0 |>
339{-| Given a value, returns exactly the same value. -}
340id : a -> a
341id x = x
343{-| Creates a [constant function](http://en.wikipedia.org/wiki/Constant_function),
344a function that *always* returns the same value regardless of what input you give.
345It is defined as:
347 always a b = a
349It totally ignores the second argument, so `always 42` is a function that always
350returns 42. When you are dealing with higher-order functions, this comes in
351handy more often than you might expect. For example, creating a zeroed out list
352of length ten would be:
354 map (always 0) [0..9]
355-}
356always : a -> b -> a
357always a _ = a
359{-| Given a 2-tuple, returns the first value. -}
360fst : (a,b) -> a
361fst (a,_) = a
363{-| Given a 2-tuple, returns the second value. -}
364snd : (a,b) -> b
365snd (_,b) = b
367{-| Flips the order of the first two arguments to a function. -}
368flip : (a -> b -> c) -> (b -> a -> c)
369flip f b a = f a b
371{-| Change how arguments are passed to a function.
372This splits paired arguments into two separate arguments.
373-}
374curry : ((a,b) -> c) -> a -> b -> c
375curry f a b = f (a,b)
377{-| Change how arguments are passed to a function.
378This combines two arguments into a single pair.
379-}
380uncurry : (a -> b -> c) -> (a,b) -> c
381uncurry f (a,b) = f a b