innoave / bounded-number / Number.Bounded

A number bounded between a minimum and a maximum.

Once the bounds are set the value of a bounded number can not get greater than its max bound neither can it get lower than its min bound.

Bounded numbers


type Bounded number

An opaque type that defines a number that is guaranteed to be between a given min and max bound (inclusive).

Define bounds

between : number -> number -> Bounded number

Construct a new bounded number by giving it a lower and a upper bound (inclusive). The value will be initialized as the provided min. The min will always be the lower value, regardless of in which order you provide the arguments.

Increment / Decrement

inc : Bounded number -> Bounded number

Increment the bounded number by 1 and clip it to the max bound.

If the resulting value is greater than the max bound the actual value is the max bound.

dec : Bounded number -> Bounded number

Decrement the bounded number by 1 and clip it to the min bound.

If the resulting value is less than the min bound the actual value is the min bound.

tryInc : Bounded number -> Maybe (Bounded number)

Try to increment the bounded number by 1. If the resulting value is greater than the max bound Nothing is returned, otherwise Just the result is returned.

tryDec : Bounded number -> Maybe (Bounded number)

Try to decrement the bounded number by 1. If the resulting value is less than the min bound Nothing is returned, otherwise Just the result is returned.

incBy : number -> Bounded number -> Bounded number

Increment the bounded number by the given number and clip it to the max bound.

If the resulting value is greater than the max bound the actual value is the max bound.

decBy : number -> Bounded number -> Bounded number

Decrement the bounded number by the given number and clip it to the min bound.

If the resulting value is less than the min bound the actual value is the min bound.

tryIncBy : number -> Bounded number -> Maybe (Bounded number)

Try to increment the bounded number by the given number. If the resulting value is greater than the max bound Nothing is returned, otherwise Just the result is returned.

tryDecBy : number -> Bounded number -> Maybe (Bounded number)

Try to decrement the bounded number by the given number. If the resulting value is less than the min bound Nothing is returned, otherwise Just the result is returned.

Update

set : number -> Bounded number -> Bounded number

Set the value manually. If you try to set a value greater than the max bound, the actual value will be the max bound. Likewise, if you try to set a value less than the min bound, the actual value is the min bound.

trySet : number -> Bounded number -> Maybe (Bounded number)

Try to set the value manually. The returned Maybe indicates whether the given value is between the min and max bounds. If yes the new value is returned.

If you try to set a value that is greater than the upper bound or lower than the lower bound Nothing is returned. Only if the value is between the min and max bound (inclusive) the new Bounded value is returned.

map : (number -> number) -> Bounded number -> Bounded number

Transforms a Bounded value with the given function. If the value returned by the given function is greater than the max bound, it will clip at the max. Likewise, if the value returned by the given function is less than the min bound, it will clip at the min.

tryMap : (number -> number) -> Bounded number -> Maybe (Bounded number)

Try set transform a Bounded value with the given function. The returned Maybe indicates whether the result of the transformation is within the lower and upper bounds. If yes the transformed value is returned.

If the value returned by the given function is above the upper bound or below the lower bound Nothing is returned. Only if the value returned by the function is between the min and max bound (inclusive) the transformed Bounded value is returned.

Query

value : Bounded number -> number

Get the value

min : Bounded number -> number

Get the lower bound

max : Bounded number -> number

Get the upper bound

JSON encoding / decoding

decoder : Json.Decode.Decoder number -> Json.Decode.Decoder (Bounded number)

Get a JSON decoder for bounded numbers. You specify a JSON decoder for either ints or floats so that this function knows which number type it should parse.

The returned decoder expects that the JSON representation of a bounded number is a JSON object containing 3 number fields: "min", "max" and "value".

When using int values the JSON might look like this:

{ "min": 1
, "max": 15
, "value": 3
}

The JSON value of a bounded float value might look like this:

{ "min": 0
, "max": 1
, "value": 0.5
}

encode : (number -> Json.Encode.Value) -> Bounded number -> Json.Encode.Value

Encode a bounded number as a JSON value. You specify a JSON encoder for either ints or floats so that this function knows which number type to use.

The returned JSON value is a JSON object with 3 number fields: "min", "max" and "value".