git.iko.soy/elk
on 63243ca help sign in
elk/libraries/Basics.elm
338 lines 8.3 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# Tuples
43@docs fst, snd
45# Higher-Order Helpers
46@docs id, (<|), (|>), (.), flip, curry, uncurry
48-}
50import Native.Basics
52{-| Convert radians to standard Elm angles (radians). -}
53radians : Float -> Float
54radians t = t
56{-| Convert degrees to standard Elm angles (radians). -}
57degrees : Float -> Float
58degrees d = d * Native.Basics.pi / 180
60{-| Convert turns to standard Elm angles (radians).
61One turn is equal to 360&deg;.
62-}
63turns : Float -> Float
64turns r = 2 * Native.Basics.pi * r
66{-| Start with polar coordinates (r,&theta;)
67and get out cartesian coordinates (x,y).
68-}
69fromPolar : (Float,Float) -> (Float,Float)
70fromPolar (r,t) = (r * Native.Basics.cos t, r * Native.Basics.sin t)
72{-| Start with cartesian coordinates (x,y)
73and get out polar coordinates (r,&theta;).
74-}
75toPolar : (Float,Float) -> (Float,Float)
76toPolar (x,y) = (Native.Basics.sqrt (x^2 + y^2), Native.Basics.atan2 y x)
78(+) : number -> number -> number
79(+) = Native.Basics.add
81(-) : number -> number -> number
82(-) = Native.Basics.sub
84(*) : number -> number -> number
85(*) = Native.Basics.mul
87{-| Floating point division. -}
88(/) : Float -> Float -> Float
89(/) = Native.Basics.floatDiv
91infixl 6 +
92infixl 6 -
93infixl 7 *
94infixl 7 /
95infixl 8 ^
97infixl 7 `div`
98infixl 7 `mod`
99infixl 7 `rem`
101{-| Integer division, remainder is discarded. -}
102div : Int -> Int -> Int
103div = Native.Basics.div
105{-| Finds the remainder after dividing one number by another: ``4 `rem` 3 == 1`` -}
106rem : Int -> Int -> Int
107rem = Native.Basics.rem
109{-| Perform modular arithmetic: ``7 `mod` 2 == 1`` -}
110mod : Int -> Int -> Int
111mod = Native.Basics.mod
113{-| Exponentiation: `3^2 == 9` -}
114(^) : number -> number -> number
115(^) = Native.Basics.exp
117cos : Float -> Float
118cos = Native.Basics.cos
120sin : Float -> Float
121sin = Native.Basics.sin
123tan : Float -> Float
124tan = Native.Basics.tan
126acos : Float -> Float
127acos = Native.Basics.acos
129asin : Float -> Float
130asin = Native.Basics.asin
132{-| You probably do not want to use this. It takes `(y/x)` as the
133argument, so there is no way to know whether the negative signs comes from
134the `y` or `x`. Thus, the resulting angle is always between &pi;/2 and -&pi;/2
135(in quadrants I and IV). You probably want to use `atan2` instead.
136-}
137atan : Float -> Float
138atan = Native.Basics.atan
140{-| This helps you find the angle of a cartesian coordinate.
141You will almost certainly want to use this instead of `atan`.
142So `atan2 y x` computes *atan(y/x)* but also keeps track of which
143quadrant the angle should really be in. The result will be between
144&pi; and -&pi;, giving you the full range of angles.
145-}
146atan2 : Float -> Float -> Float
147atan2 = Native.Basics.atan2
149{-| Take the square root of a number. -}
150sqrt : number -> number
151sqrt = Native.Basics.sqrt
153{-| Take the absolute value of a number. -}
154abs : number -> number
155abs = Native.Basics.abs
157{-| Calculate the logarithm of a number with a given base: `logBase 10 100 == 2` -}
158logBase : number -> number -> number
159logBase = Native.Basics.logBase
161{-| Clamps a number within a given range. With the expression
162`clamp 100 200 x` the results are as follows:
164 100 if x < 100
165 x if 100 <= x < 200
166 200 if 200 <= x
167-}
168clamp : number -> number -> number -> number
169clamp = Native.Basics.clamp
171{-| An approximation of pi. -}
172pi : Float
173pi = Native.Basics.pi
175{-| An approximation of e. -}
176e : Float
177e = Native.Basics.e
179(==) : a -> a -> Bool
180(==) = Native.Basics.eq
182(/=) : a -> a -> Bool
183(/=) = Native.Basics.neq
185(<) : comparable -> comparable -> Bool
186(<) = Native.Basics.lt
188(>) : comparable -> comparable -> Bool
189(>) = Native.Basics.gt
191(<=) : comparable -> comparable -> Bool
192(<=) = Native.Basics.le
194(>=) : comparable -> comparable -> Bool
195(>=) = Native.Basics.ge
197infix 4 ==
198infix 4 /=
199infix 4 <
200infix 4 >
201infix 4 <=
202infix 4 >=
204{-| Compare any two comparable values. Comparable values include `String`, `Char`,
205`Int`, `Float`, `Time`, or a list or tuple containing comparable values.
206These are also the only values that work as `Dict` keys or `Set` members.
207-}
208compare : comparable -> comparable -> Order
209compare = Native.Basics.compare
211{-| Represents the relative ordering of two things.
212The relations are less than, equal to, and greater than.
213-}
214data Order = LT | EQ | GT
216{-| Given two comparables, returns the smaller one. -}
217min : comparable -> comparable -> comparable
218min = Native.Basics.min
220{-| Given two comparables, returns the larger one. -}
221max : comparable -> comparable -> comparable
222max = Native.Basics.max
224{-| The and operator. True if both inputs are True.
225This operator short-circuits if the first argument is False.
226-}
227(&&) : Bool -> Bool -> Bool
228(&&) = Native.Basics.and
230{-| The or operator. True if one or both inputs are True.
231This operator short-circuits if the first argument is True.
232-}
233(||) : Bool -> Bool -> Bool
234(||) = Native.Basics.or
236infixr 3 &&
237infixr 2 ||
239{-| The exclusive-or operator. True if exactly one input is True. -}
240xor : Bool -> Bool -> Bool
241xor = Native.Basics.xor
243{-| Negate a boolean value: `(not True == False)` and `(not False == True)` -}
244not : Bool -> Bool
245not = Native.Basics.not
247{-| Equal to true. Useful as the last case of a multi-way-if. -}
248otherwise : Bool
249otherwise = True
252-- Conversions
254{-| Round a number to the nearest integer. -}
255round : Float -> Int
256round = Native.Basics.round
258{-| Truncate a decimal number, rounding towards zero. -}
259truncate : Float -> Int
260truncate = Native.Basics.truncate
262{-| Floor function, rounding down. -}
263floor : Float -> Int
264floor = Native.Basics.floor
266{-| Ceiling function, rounding up. -}
267ceiling : Float -> Int
268ceiling = Native.Basics.ceiling
270{-| Convert an integer into a float. -}
271toFloat : Int -> Float
272toFloat = Native.Basics.toFloat
275-- Function Helpers
277{-| Function composition: `(f . g == (\\x -> f (g x)))` -}
278(.) : (b -> c) -> (a -> b) -> (a -> c)
279(.) f g x = f (g x)
281{-| Forward function application `x |> f == f x`. This function is useful
282for avoiding parenthesis and writing code in a more natural way.
283Consider the following code to create a pentagon:
285 scale 2 (move (10,10) (filled blue (ngon 5 30)))
287This can also be written as:
289 ngon 5 30 |> filled blue
290 |> move (10,10)
291 |> scale 2
292-}
293(|>) : a -> (a -> b) -> b
294x |> f = f x
296{-| Function application `f <| x == f x`. This function is useful for avoiding
297parenthesis. Consider the following code to create a text element:
299 text (monospace (toText "code"))
301This can also be written as:
303 text . monospace <| toText "code"
304-}
305(<|) : (a -> b) -> a -> b
306f <| x = f x
308infixr 9 .
309infixr 0 <|
310infixl 0 |>
312{-| Given a value, returns exactly the same value. -}
313id : a -> a
314id x = x
316{-| Given a 2-tuple, returns the first value. -}
317fst : (a,b) -> a
318fst (a,_) = a
320{-| Given a 2-tuple, returns the second value. -}
321snd : (a,b) -> b
322snd (_,b) = b
324{-| Flips the order of the first two arguments to a function. -}
325flip : (a -> b -> c) -> (b -> a -> c)
326flip f b a = f a b
328{-| Change how arguments are passed to a function.
329This splits paired arguments into two separate arguments.
330-}
331curry : ((a,b) -> c) -> a -> b -> c
332curry f a b = f (a,b)
334{-| Change how arguments are passed to a function.
335This combines two arguments into a single pair.
336-}
337uncurry : (a -> b -> c) -> (a,b) -> c
338uncurry f (a,b) = f a b