elm-lang/core/2.1.0

NOTE: this package moved to elm/core

NOTE: this package is not compatible with Elm 0.19.1

Basics

Tons of useful functions that get imported by default.

Equality

(==) : a -> a -> Bool
(/=) : a -> a -> Bool

Comparison

These functions only work on comparable types. This includes numbers, characters, strings, lists of comparable things, and tuples of comparable things. Note that tuples with 7 or more elements are not comparable; why are your tuples so big?

(<) : comparable -> comparable -> Bool
(>) : comparable -> comparable -> Bool
(<=) : comparable -> comparable -> Bool
(>=) : comparable -> comparable -> Bool
max : comparable -> comparable -> comparable

Find the larger of two comparables.

min : comparable -> comparable -> comparable

Find the smaller of two comparables.

type Order
= LT
| EQ
| GT

Represents the relative ordering of two things. The relations are less than, equal to, and greater than.

compare : comparable -> comparable -> Order

Compare any two comparable values. Comparable values include String, Char, Int, Float, Time, or a list or tuple containing comparable values. These are also the only values that work as Dict keys or Set members.

Booleans

not : Bool -> Bool

Negate a boolean value.

not True == False
not False == True
(&&) : Bool -> Bool -> Bool

The logical AND operator. True if both inputs are True. This operator short-circuits to False if the first argument is False.

(||) : Bool -> Bool -> Bool

The logical OR operator. True if one or both inputs are True. This operator short-circuits to True if the first argument is True.

xor : Bool -> Bool -> Bool

The exclusive-or operator. True if exactly one input is True.

otherwise : Bool

Equal to True. Useful as the last case of a multi-way-if.

Mathematics

(+) : number -> number -> number
(-) : number -> number -> number
(*) : number -> number -> number
(/) : Float -> Float -> Float

Floating point division.

(^) : number -> number -> number

Exponentiation

3^2 == 9
(//) : Int -> Int -> Int

Integer division. The remainder is discarded.

rem : Int -> Int -> Int

Find the remainder after dividing one number by another.

 7 `rem` 2 == 1
-1 `rem` 4 == -1
(%) : Int -> Int -> Int

Perform modular arithmetic.

 7 % 2 == 1
-1 % 4 == 3
negate : number -> number

Negate a number.

negate 42 == -42
negate -42 == 42
negate 0 == 0
abs : number -> number

Take the absolute value of a number.

sqrt : Float -> Float

Take the square root of a number.

clamp : number -> number -> number -> number

Clamps a number within a given range. With the expression clamp 100 200 x the results are as follows:

100     if x < 100
 x      if 100 <= x < 200
200     if 200 <= x
logBase : Float -> Float -> Float

Calculate the logarithm of a number with a given base.

logBase 10 100 == 2
logBase 2 256 == 8
e : Float

An approximation of e.

Trigonometry

pi : Float

An approximation of pi.

cos : Float -> Float
sin : Float -> Float
tan : Float -> Float
acos : Float -> Float
asin : Float -> Float
atan : Float -> Float

You probably do not want to use this. It takes (y/x) as the argument, so there is no way to know whether the negative signs comes from the y or x. Thus, the resulting angle is always between π/2 and -π/2 (in quadrants I and IV). You probably want to use atan2 instead.

atan2 : Float -> Float -> Float

This helps you find the angle of a cartesian coordinate. You will almost certainly want to use this instead of atan. So atan2 y x computes atan(y/x) but also keeps track of which quadrant the angle should really be in. The result will be between π and -π, giving you the full range of angles.

Number Conversions

round : Float -> Int

Round a number to the nearest integer.

floor : Float -> Int

Floor function, rounding down.

ceiling : Float -> Int

Ceiling function, rounding up.

truncate : Float -> Int

Truncate a number, rounding towards zero.

toFloat : Int -> Float

Convert an integer into a float.

Angle Conversions

All angle conversions result in “standard Elm angles” which happen to be radians.

degrees : Float -> Float

Convert degrees to standard Elm angles (radians).

radians : Float -> Float

Convert radians to standard Elm angles (radians).

turns : Float -> Float

Convert turns to standard Elm angles (radians). One turn is equal to 360°.

Polar Coordinates

toPolar : ( Float, Float ) -> ( Float, Float )

Convert cartesian coordinates (x,y) to polar coordinates (r,θ).

fromPolar : ( Float, Float ) -> ( Float, Float )

Convert polar coordinates (r,θ) to cartesian coordinates (x,y).

Floating Point Checks

isNaN : Float -> Bool
isInfinite : Float -> Bool

Strings and Lists

toString : a -> String

Turn any kind of value into a string. When you view the resulting string with Text.fromString it should look just like the value it came from.

toString 42 == "42"
toString [1,2] == "[1,2]"
toString "he said, \"hi\"" == "\"he said, \\\"hi\\\"\""
(++) : appendable -> appendable -> appendable

Put two appendable things together. This includes strings, lists, and text.

"hello" ++ "world" == "helloworld"
[1,1,2] ++ [3,5,8] == [1,1,2,3,5,8]

Tuples

fst : ( a, b ) -> a

Given a 2-tuple, returns the first value.

snd : ( a, b ) -> b

Given a 2-tuple, returns the second value.

Higher-Order Helpers

identity : a -> a

Given a value, returns exactly the same value. This is called the identity function.

always : a -> b -> a

Create a constant function, a function that always returns the same value regardless of what input you give. It is defined as:

always a b = a

It totally ignores the second argument, so always 42 is a function that always returns 42. When you are dealing with higher-order functions, this comes in handy more often than you might expect. For example, creating a zeroed out list of length ten would be:

map (always 0) [0..9]
(<|) : (a -> b) -> a -> b

Backward function application f <| x == f x. This function is useful for avoiding parenthesis. Consider the following code to create a text element:

leftAligned (monospace (fromString "code"))

This can also be written as:

leftAligned << monospace <| fromString "code"
(|>) : a -> (a -> b) -> b

Forward function application x |> f == f x. This function is useful for avoiding parenthesis and writing code in a more natural way. Consider the following code to create a pentagon:

scale 2 (move (10,10) (filled blue (ngon 5 30)))

This can also be written as:

ngon 5 30
  |> filled blue
  |> move (10,10)
  |> scale 2
(<<) : (b -> c) -> (a -> b) -> a -> c

Function composition, passing results along in the suggested direction. For example, the following code checks if the square root of a number is odd:

not << isEven << sqrt

You can think of this operator as equivalent to the following:

(g << f)  ==  (\x -> g (f x))

So our example expands out to something like this:

\n -> not (isEven (sqrt n))
(>>) : (a -> b) -> (b -> c) -> a -> c

Function composition, passing results along in the suggested direction. For example, the following code checks if the square root of a number is odd:

sqrt >> isEven >> not

This direction of function composition seems less pleasant than (<<) which reads nicely in expressions like: filter (not << isRegistered) students

flip : (a -> b -> c) -> b -> a -> c

Flip the order of the first two arguments to a function.

curry : (( a, b ) -> c) -> a -> b -> c

Change how arguments are passed to a function. This splits paired arguments into two separate arguments.

uncurry : (a -> b -> c) -> ( a, b ) -> c

Change how arguments are passed to a function. This combines two arguments into a single pair.