Basics

Core

Core helpers shared across modules. Comparison constructors feed List.sortWith. (Operators like (+), (==), and (|>) are language builtins; this module exposes the helpers that live as named values on the BEAM.)

Types

Order

type Order
= LT
| EQ
| GT

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

Examples

compare 1 2 == LT
compare 2 2 == EQ
compare 3 2 == GT

Never

type Never = JustOneMore Never

A value that can never happen. Used by Parser (no context) as the impossible context type.

Examples

-- Never has no values; use it for impossible branches only.

Values

identity

identity : a -> a

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

Examples

identity 42 == 42
List.map identity [1,2] == [1,2]

always

always : a -> b -> a

Create a function that *always* returns the same value. Useful with functions like map:

Examples

List.map (always 0) [1,2,3,4,5] == [0,0,0,0,0]

-- List.map (\_ -> 0) [1,2,3,4,5] == [0,0,0,0,0]
-- always = (\x _ -> x)

clamp

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

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

Examples

100     if x < 100
 x      if 100 <= x < 200
200     if 200 <= x

negate

negate : number -> number

Negate a number.

Examples

negate 42 == -42
negate -42 == 42
negate 0 == 0

abs

abs : number -> number

Get the absolute value of a number.

Examples

abs 16 == 16
abs -4 == 4

toFloat

toFloat : Int -> Float

Convert an integer into a float.

Examples

toFloat 42 == 42.0

round

round : Float -> Int

Round a number to the nearest integer.

Examples

round 1.0 == 1
round 1.2 == 1
round 1.5 == 2
round 1.8 == 2

round -1.2 == -1
round -1.5 == -1
round -1.8 == -2

floor

floor : Float -> Int

Floor function, rounding down.

Examples

floor 1.0 == 1
floor 1.2 == 1
floor 1.5 == 1
floor 1.8 == 1

floor -1.2 == -2
floor -1.5 == -2
floor -1.8 == -2

ceiling

ceiling : Float -> Int

Ceiling function, rounding up.

Examples

ceiling 1.0 == 1
ceiling 1.2 == 2
ceiling 1.5 == 2
ceiling 1.8 == 2

ceiling -1.2 == -1
ceiling -1.5 == -1
ceiling -1.8 == -1

truncate

truncate : Float -> Int

Truncate a number, rounding towards zero.

Examples

truncate 1.0 == 1
truncate 1.2 == 1
truncate 1.5 == 1
truncate 1.8 == 1

truncate -1.2 == -1
truncate -1.5 == -1
truncate -1.8 == -1

modBy

modBy : Int -> Int -> Int

Perform modular arithmetic. A common trick is to use (n mod 2) to detect even and odd numbers:

Examples

modBy 2 0 == 0
modBy 2 1 == 1
modBy 2 2 == 0
modBy 2 3 == 1

Our modBy function works in the typical mathematical way when you run into negative numbers:

List.map (modBy 4) [ -5, -4, -3, -2, -1,  0,  1,  2,  3,  4,  5 ]
--                 [  3,  0,  1,  2,  3,  0,  1,  2,  3,  0,  1 ]

Use remainderBy for a different treatment of negative numbers.

remainderBy

remainderBy : Int -> Int -> Int

Get the remainder after division. Here are a bunch of examples of dividing by four:

Examples

List.map (remainderBy 4) [ -5, -4, -3, -2, -1,  0,  1,  2,  3,  4,  5 ]
--                       [ -1,  0, -3, -2, -1,  0,  1,  2,  3,  0,  1 ]

Use modBy for a different treatment of negative numbers.

compare

compare : comparable -> comparable -> Order

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

Examples

compare 3 4 == LT
compare 4 4 == EQ
compare 5 4 == GT

max

max : comparable -> comparable -> comparable

Find the larger of two comparables.

Examples

max 42 12345678 == 12345678
max "abc" "xyz" == "xyz"

min

min : comparable -> comparable -> comparable

Find the smaller of two comparables.

Examples

min 42 12345678 == 42
min "abc" "xyz" == "abc"

xor

xor : Bool -> Bool -> Bool

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

Examples

xor True  True  == False
xor True  False == True
xor False True  == True
xor False False == False

sqrt

sqrt : Float -> Float

Take the square root of a number.

Examples

sqrt  4 == 2
sqrt  9 == 3
sqrt 16 == 4
sqrt 25 == 5

logBase

logBase : Float -> Float -> Float

Calculate the logarithm of a number with a given base.

Examples

logBase 10 100 == 2
logBase 2 256 == 8

e

e : Float

An approximation of e.

pi

pi : Float

An approximation of pi.

cos

cos : Float -> Float

Figure out the cosine given an angle in radians.

sin

sin : Float -> Float

Figure out the sine given an angle in radians.

tan

tan : Float -> Float

Figure out the tangent given an angle in radians.

acos

acos : Float -> Float

Figure out the arccosine for adjacent / hypotenuse in radians.

asin

asin : Float -> Float

Figure out the arcsine for opposite / hypotenuse in radians.

atan

atan : Float -> Float

Figure out the arctangent given y/x in radians.

atan2

atan2 : Float -> Float -> Float

Figure out the angle (in radians) to an (x,y) coordinate.

degrees

degrees : Float -> Float

Convert degrees to standard Elm angles (radians).

Examples

degrees 180 == 3.141592653589793

radians

radians : Float -> Float

Convert radians to standard Elm angles (radians).

Examples

radians pi == 3.141592653589793

turns

turns : Float -> Float

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

Examples

turns (1/2) == 3.141592653589793

toPolar

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

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

Examples

toPolar (3, 4) == ( 5, 0.9272952180016122 )

fromPolar

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

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

Examples

fromPolar (sqrt 2, degrees 45) == (1, 1)

isNaN

isNaN : Float -> Bool

Determine whether a float is an undefined or unrepresentable number. NaNs can happen if you divide by zero or take the square root of negative numbers.

Examples

isNaN (0/0)     == True
isNaN (sqrt -1) == True
isNaN (1/0)     == False
isNaN 1         == False

isInfinite

isInfinite : Float -> Bool

Determine whether a float is positive or negative infinity.

Examples

isInfinite (0/0)     == False
isInfinite (sqrt -1) == False
isInfinite (1/0)     == True
isInfinite 1         == False

never

never : Never -> a

A function that can never be called. Useful when mapping Html Never into another message type.