An Array that knows about the amount of elements it holds.

result type

-- length >= 5
: ArraySized ... (Min (Up5 x_))


-- 2 <= length <= 12
: ArraySized ... (In (Up2 minX_) (Up12 maxX_))

Representing a result's numbers as this weird Up<n> x is what allows the little magic tricks in the library: attaching, taking, dropping, chunking, comparing, ...

argument type

-- length = 15
: ArraySized ... (Exactly (On N15))


-- length >= 4
: ArraySized ... (In (On (Add4 minFrom4_)) max_)


-- 4 <= length <= 15
: ArraySized ...
:     (In (On (Add4 minFrom4_)) (Up maxTo15_ To N15))

to allow the broadest range of desired lengths,

• to require nothing about the upper limit → leave the maximum as a variable
• fix lower limits to the desired minimum number + some variable
• require the actual upper limit to go Up a variable amount to arrive at the desired maximum number

stored type

in your Model for example. They look just like result types but every Up<n> x becomes On N<n>, avoiding type variables

-- length >= 4
: ArraySized ... (Min (On N4))


-- 4 <= length <= 15
: ArraySized ... (In (On N4) (On N15))


-- length = 15
: ArraySized ... (Exactly (On N15))

== on both ArraySizeds and Ns crashes elm. Compare safely or convert inToNumber

A given amount of same elements

import N exposing (n4)


ArraySized.repeat 'L' n4
    --: ArraySized Char (In (Up4 minX_) (Up4 maxX_))
    |> ArraySized.toList
--> [ 'L', 'L', 'L', 'L' ]


ArraySized.repeat 'L' atLeast3
--: Char ArraySized (Min (Up3 x_))

Increasing natural numbers from n1 until including a given number

import N exposing (n3, n0)


ArraySized.n1To n3
--: ArraySized
--:     (N (In (Up1 nMinX_) (Up3 maxX)))
--:     (In (Up3 minX_) (Up3 maxX))
    |> ArraySized.map N.toInt
    |> ArraySized.toList
--> [ 1, 2, 3 ]


ArraySized.n1To n0
--: ArraySized
--:     (N (In (Up1 nMinX_) (Up0 maxX)))
--:     (In (Up0 minX_) (Up0 maxX))
    |> ArraySized.map N.toInt
    |> ArraySized.toList
--> []
-- This does look weird at first glance...
-- The ArraySized says it has Ns in it that are impossible to construct!
-- but I promise it makes sense:
-- The ArraySized is empty, so we're all good after all


ArraySized.n1To between2And9
    |> ArraySized.map (N.add n3)
--: ArraySized
--:    (N (In (Up5 nMinX_) (Up12 maxX)))
--:    (In (Up3 minX_) (Up10 maxX))

To add index info to your ArraySized, use andIndexes

Random.Generator for a given amount of random elements

import N exposing (n5)


ArraySized.random (Random.float 0 1) n5
--: Random.Generator
--:     (ArraySized
--:         Float
--:         (In (Up5 minX_) (Up5 maxX_))
--:     )

Pairs well with

Random.andThen
    (ArraySized.random <element>)
    (N.randomIn ( <length min>, <length max> ))

Fuzzer for an ArraySized with a given length

import N exposing (n3)
import Fuzz


ArraySized.fuzz Fuzz.bool n3
    |> Fuzz.map ArraySized.toList
    --: Fuzzer (ArraySized Bool (In (Up3 minX_) (Up6 maxX_)))
    |> Fuzz.examples 3
--> [ [ False, True, False ]
--> , [ False, False, False ]
--> , [ False, False, True ]
--> ]

To fuzz an ArraySized with a length in a range, inFuzz

Fuzzer for an ArraySized with a length in a given range. For larger ranges, smaller lengths are preferred

import N exposing (n3, n6)
import Fuzz


ArraySized.inFuzz Fuzz.bool ( n3, n6 )
    |> Fuzz.map ArraySized.toList
    --: Fuzzer (ArraySized Bool (In (Up3 minX_) (Up6 maxX_)))
    |> Fuzz.examples 3
--> [ [ False, True, False, False, True, True ]
--> , [ False, False, False, True ]
--> , [ False, True, False, False, False, False ]
--> ]

Create from an Array. As every Array has >= 0 elements

arrayFromSomeOtherLibrary |> ArraySized.fromArray
--: ArraySized ... (Min (Up0 x_))

Don't use it for construction

ArraySized.fromArray
    (Array.fromList [ 0, 1, 2, 3, 4, 5, 6 ])
-- big no

Make sure the compiler knows as much as you about the amount of elements!

ArraySized.l7 0 1 2 3 4 5 6 -- ok


ArraySized.n1To n6 -- big yes

"wrap early, unwrap late"

Create from a List. As every List has >= 0 elements

listFromSomeOtherLibrary |> ArraySized.fromList
--: ArraySized ... (Min (Up0 x_))

Don't use for construction

ArraySized.fromList [ 0, 1, 2, 3, 4, 5, 6 ]
-- big no!

Make sure the compiler knows as much as you about the amount of elements!

ArraySized.l7 0 1 2 3 4 5 6 -- ok


ArraySized.n1To n6 -- big yes

"wrap early, unwrap late"

On Emptiable.filled ArraySized.one, on Emptiable.empty ArraySized.empty

import N exposing (n0)
import Emptiable exposing (filled)


filled "hi"
    |> ArraySized.fromEmptiable
    --: ArraySized ... (In (Up0 minX_) (Up1 maxX_))
    |> ArraySized.toList
--> [ "hi" ]


Emptiable.empty
    |> ArraySized.fromEmptiable
    --: ArraySized ... (In (Up0 minX_) (Up1 maxX_))
    |> ArraySized.toList
--> []

Emptiness knowledge possiblyOrNever is transferred

Create from a stack. As every stack has >= 0 elements

Emptiable.empty |> ArraySized.fromStack
--: ArraySized ... (Min (On N0))


Stack.topBelow '#' [] |> ArraySized.fromStack
--: ArraySized Char (Min (On N1))

Don't use for construction

ArraySized.fromStackEmptiable
    (Stack.fromList [ 0, 1, 2, 3, 4, 5, 6 ])
-- big no!

Make sure the compiler knows as much as you about the amount of elements!

ArraySized.l7 0 1 2 3 4 5 6 -- ok


ArraySized.n1To n6 -- big yes

"wrap early, unwrap late"

Create from the Chars of a String. As every String has >= 0 elements

stringFromSomeOtherLibrary |> ArraySized.fromString
--: ArraySized Char (Min (Up0 minX_))

Try not to use this for construction and instead use the safe versions like l<n>

No elements

ArraySized.empty
--: ArraySized element_ (In (Up0 minX_) (Up0 maxX_))
    |> ArraySized.push ":)"
    --: ArraySized String (In (Up1 minX_) (Up1 maxX_))

Create with only 1 single given element

Create with 2 given elements in the order they are supplied

Create with 3 given elements in the order they are supplied

Create with 4 given elements in the order they are supplied

Create with 5 given elements in the order they are supplied

Create with 6 given elements in the order they are supplied

Create with 7 given elements in the order they are supplied

Create with 8 given elements in the order they are supplied

Create with 9 given elements in the order they are supplied

Create with 10 given elements in the order they are supplied

Create with 11 given elements in the order they are supplied

Create with 12 given elements in the order they are supplied

Create with 13 given elements in the order they are supplied

Create with 14 given elements in the order they are supplied

Create with 15 given elements in the order they are supplied

Create with 16 given elements in the order they are supplied

Its amount of elements

import N exposing (n3)


ArraySized.l3 1 2 3
    |> ArraySized.length
    --: N (In (Up3 minX_) (Up3 maxX_))
    |> N.toInt
--> 3


between3And5Elements |> ArraySized.length
--: N (In (Up3 minX_) (Up5 maxX_))


atLeast3Elements |> ArraySized.length
--: N (Min (Up3 minX_))

Its element at a valid location in a given Direction

Remember that indexes are 1-indexed!

import Linear exposing (Direction(..))
import N exposing (n1, n2)


ArraySized.l4 0 1 2 3
    |> ArraySized.element ( Up, n1 )
--> 0


ArraySized.l4 0 1 2 3
    |> ArraySized.element ( Down, n2 )
--> 2

Its element at a given location in a given Direction. Because the index doesn't promise it's <= the ArraySized's length minimum, elementTry gives back an Emptiable

Use element if you know your index always points to a valid location

import Linear exposing (Direction(..))
import Emptiable
import N exposing (n1, n5)


ArraySized.l4 0 1 2 3
    |> ArraySized.elementTry ( Up, n5 )
--> Emptiable.empty


ArraySized.l4 0 1 2 3
    |> ArraySized.elementTry ( Down, n1 )
--> Emptiable.filled 3

Its one and only, first and last element

ArraySized.one "hi" |> ArraySized.toOne
--> "hi"

Compared to a range from a lower to an upper bound, is its length in, BelowOrAbove range?

import N exposing (n10, n16)


chooseFormation :
    ArraySized Character (In minLength_ N50)
    -> Formation
chooseFormation characters =
    case characters |> ArraySized.hasIn ( n10, n16 ) of
        Ok between10And16 ->
            SpecialAttack between10And16


        Err (N.Below n9AtMost) ->
            Retreat n9AtMost


        Err (N.Above n17AtLeast) ->
            Fight n17AtLeast

Compare its length to a given exact length. Does it match or is it BelowOrAbove?

import N exposing (n7)


chooseFormation :
    ArraySized Character (In min N50)
    -> Formation
chooseFormation characters =
    case characters |> ArraySized.has n7 of
        Ok exactly7 ->
            SpecialAttack exactly7


        Err (N.Below l6AtLeast) ->
            Retreat l6AtLeast


        Err (N.Above l8AtLeast) ->
            Fight l8AtLeast

Is its length below (Err) or at least as big as (Ok) a given N?

import N exposing (n5)


atLeast5 :
    ArraySized element (In minLength_ max)
    -> Maybe (element ArraySized (In (Up5 minX_) max))
atLeast5 =
    ArraySized.hasAtLeast n5
        >> Result.toMaybe

Is its length atMost (Ok) or above (Err) a given length?

-- at least 3 and only up to 50 tags
tag :
    ArraySized
        String
        (In (On (Add3 minFrom3_)) (Up maxTo50_ To N50))
    -> (Metadata -> MetadataTagged)


tagIfValidTags :
    ArraySized String (In (On (Add3 minFrom3_)) max_)
    -> (Metadata -> Maybe MetadataTagged)
tagIfValidTags tags =
    case tags |> ArraySized.hasAtMost n50 of
        Ok atMost50 ->
            tag atMost50 >> Just


        Err _ ->
            \_ -> Nothing

Set the element at an index in a given Direction

import Linear exposing (Direction(..))
import N exposing (n1, n2)


ArraySized.l3 "I" "am" "ok"
    |> ArraySized.elementReplace ( Up, n2 )
        (\() -> "confusion")
    |> ArraySized.toList
--> [ "I", "am", "confusion" ]


ArraySized.l3 "I" "am" "ok"
    |> ArraySized.elementReplace ( Down, n1 )
        (\() -> "feel")
    |> ArraySized.toList
--> [ "I", "feel", "ok" ]

An index that's too high to point to an existing element is ignored and no element is replaced

import Linear exposing (Direction(..))
import N exposing (n3)


ArraySized.l3 "I" "am" "ok"
    |> ArraySized.elementReplace ( Down, n3 )
        (\() -> "feel")
    |> ArraySized.toList
--> [ "I", "am", "ok" ]

Change the element at an index in a given Direction based on its previous value

import Linear exposing (Direction(..))
import N exposing (n0)


ArraySized.l3 1 20 30
    |> ArraySized.elementAlter ( Up, n0 ) (\x -> x * 10)
    |> ArraySized.toList
--> [ 10, 20, 30 ]


ArraySized.l3 1 20 30
    |> ArraySized.elementAlter ( Down, n0 ) negate
    |> ArraySized.toList
--> [ 1, 20, -30 ]

An index that's too high to point to an existing element is ignored and no element is altered

import Linear exposing (Direction(..))
import N exposing (n3)


ArraySized.l3 1 20 30
    |> ArraySized.elementAlter ( Up, n3 ) (\x -> x * 10)
    |> ArraySized.toList
--> [ 1, 20, 30 ]

Flip the order of the elements

ArraySized.l4 "l" "i" "v" "e"
    |> ArraySized.reverse
    |> ArraySized.toList
--> [ "e", "v", "i", "l" ]

Add index info to each element.

import N exposing (n1, n2, n3)


ArraySized.l3 'a' 'b' 'c'
    |> ArraySized.andIndexes
    |> ArraySized.toList
--→ [ { element = 'a', index = n1 |> N.maxTo n3 }
--→ , { element = 'b', index = n2 |> N.minTo n1 |> N.maxTo n3 }
--→ , { element = 'b', index = n3 |> N.minTo n1 }
--→ ]

Change all elements based on their current values

import N exposing (n25)


aToZ : ArraySized Char (In N26 (N26Plus a_))
aToZ =
    ArraySized.n1To n25
        |> ArraySized.map inABC


inABC index =
    ('a' |> Char.toCode)
        + (index |> N.toInt)
        |> Char.fromCode

Oh look, more type-safety!

Map each element using information collected from previous steps, folding in a given Direction from given initial information.

Both the mapped ArraySized and the folded information will be returned

You'll often find this under the name "mapAccum"

import Linear exposing (Direction(..))


ArraySized.l3 1 2 3
    |> ArraySized.mapFoldFrom 0
        Down
        (\state ->
            { element = state.folded
            , folded = state.folded + state.element
            }
        )
--→ { mapped = ArraySized.l3 5 3 0, folded = 6 }


mapIndexed : Direction -> (Int -> a -> b) -> (ArraySized a l -> ArraySized b l)
mapIndexed indexDirection mapAtIndex =
    ArraySized.mapFoldFrom 0
        indexDirection
        (\state ->
            { element = state.element |> mapAtIndex state.folded
            , folded = state.folded + 1
            }
        )
        >> .mapped


ArraySized.l4 'h' 'i' 'y' 'o'
    |> mapIndexed Up Tuple.pair
--→ ArraySized.l4 ( 0, 'h' ) ( 1, 'i' ) ( 2, 'y' ) ( 3, 'o' )


ArraySized.l4 'h' 'i' 'y' 'o'
    |> mapIndexed Down Tuple.pair
--→ ArraySized.l4 ( 3, 'h' ) ( 2, 'i' ) ( 1, 'y' ) ( 0, 'o' )

Put a new element after all the others

between5And10Elements
    |> ArraySized.push "becomes the last"
--: ArraySized String (In (Up6 minX_) (Up11 maxX_))

pushMin if you don't know the length maximum

Put a new element after all the others

atLeast5Elements
    |> ArraySized.pushMin "becomes the last"
--: ArraySized String (Min (Up6 minX_))

push if you know the length maximum

Put an element in the ArraySized at a given index in a given Direction

Remember that indexes are 1-indexed!

import Linear exposing (Direction(..))
import N exposing (n2, n3)


ArraySized.l3 'a' 'c' 'd'
    |> ArraySized.insert ( Up, n2 ) 'b'
    --: ArraySized Char (In (On N4) (Up4 maxX_))
    |> ArraySized.toList
--> [ 'a', 'b', 'c', 'd' ]


ArraySized.l3 'a' 'c' 'd'
    |> ArraySized.insert ( Down, n3 ) 'b'
    |> ArraySized.toList
--> [ 'a', 'b', 'c', 'd' ]

insertMin if you don't know the length maximum

Need the length minimum to not become On (for results etc.) → |> minTo

Put a new element at an index in a given Direction

import Linear exposing (Direction(..))
import N exposing (n0, n1)


atLeast5Elements
    |> ArraySized.insertMin ( Down, n1 ) "before last"
    --: ArraySized String (Min (On N6))


minCons :
    element
    -> ArraySized element (In (On min) max_)
    -> ArraySized element (Min (On (Add1 min)))
minCons =
    ArraySized.insertMin ( Up, n0 )

insert if you know the length maximum

Need the length minimum to not become On (for results etc.) → |> minTo

Kick out the element at a given index in a given Direction

Remember that indexes are 1-indexed!

import Linear exposing (Direction(..))
import N exposing (n1)


removeLast between1And10Elements =
    between1And10Elements
        |> ArraySized.remove ( Down, n1 )

• Don't know the length maximum? → removeMin
• Want to remove an element beyond the length minimum? → removeMin

Kick out the element at an index in a given Direction

Remember that indexes are 1-indexed!

removeLast =
    ArraySized.removeMin ( Down, n0 )

This only works when the ArraySized has at minimum 1 element. To maybe remove an element, match on ArraySized.hasAtLeast n1

• Know the length maximum? → remove
• Want to make the length minimum a difference again (not On) for results, ...? → ArraySized.minTo

Take every filled value, drop every empty

import Emptiable exposing (filled)


ArraySized.l3 ("This" |> filled) Emptiable.empty ("fine" |> filled)
    |> ArraySized.fills
    --: ArraySized String (In (Up0 minX_) (Up3 maxX_))
    |> ArraySized.toList
--> [ "This", "fine" ]

Use map |> fills to get the same functionality as "filterMap"

import Emptiable


ArraySized.l3 "1.2" "2" "hello"
    |> ArraySized.map (String.toInt >> Emptiable.fromMaybe)
    |> ArraySized.fills
    |> ArraySized.toList
--> [ 2 ]

If every Emptiable is filled, all of the values. If any element is empty, empty

import Emptiable exposing (filled)


ArraySized.empty
    |> ArraySized.allFill
    |> Emptiable.map ArraySized.toList
--> filled []


ArraySized.l3 (filled 1) (filled 2) (filled 3)
    |> ArraySized.allFill
    |> Emptiable.map ArraySized.toList
--> filled [ 1, 2, 3 ]


ArraySized.l3 (filled 1) Emptiable.empty (filled 3)
    |> ArraySized.allFill
--> Emptiable.empty

Can also be used to check whether all/any elements satisfy a given test

import Possibly exposing (Possibly)
import Emptiable exposing (Emptiable)




atMost4 : Int -> Emptiable Int Possibly
atMost4 =
    \n ->
        if n <= 4 then
            n |> Emptiable.filled
        else
            Emptiable.empty


-- all




ArraySized.l2 2 3
    |> ArraySized.map atMost4
    |> ArraySized.allFill
    |> (/=) Emptiable.empty
--> True


ArraySized.l2 2 7
    |> ArraySized.map atMost4
    |> ArraySized.allFill
    |> (/=) Emptiable.empty
--> False




-- any




ArraySized.l2 -5 300
    |> ArraySized.map atMost4
    |> ArraySized.allFill
    |> (==) Emptiable.empty
--> True


ArraySized.l2 0 0
    |> ArraySized.map atMost4
    |> ArraySized.allFill
    |> (==) Emptiable.empty
--> False

Q: Why not expose any, all?

A: to push you towards parsing, not validating

Funny aside, allFill can sometimes even be nicer than mapN/andMap

groupCall =
    ArraySized.l5 aUser bUser cUser dUser eUser
        |> ArraySized.map .phoneNumber
        |> ArraySized.allFill


-- vs
groupCall =
    map5 ArraySized.l5
        aUser.phoneNumber
        bUser.phoneNumber
        cUser.phoneNumber
        dUser.phoneNumber
        eUser.phoneNumber

If every Result is Ok, all of the values. If any element is Err, all the errors.

import Stack


ArraySized.empty
    |> ArraySized.allOk
    |> Result.map ArraySized.toList
--> Ok []


ArraySized.l3 (Ok 1) (Ok 2) (Ok 3)
    |> ArraySized.allOk
    |> Result.map ArraySized.toList
--> Ok [ 1, 2, 3 ]


ArraySized.l3 (Ok 1) (Err "not a number") (Ok 3)
    |> ArraySized.allOk
--> Err (Stack.one "not a number")

A given number of elements in a given direction

import Linear exposing (Direction(..))
import N exposing (n7)


-- its three last elements
ArraySized.n1To n3AtLeast
    |> ArraySized.take Down { atLeast = n3 } n3

Is the amount taken less than the ArraySized's length minimum?

ArraySized.l8 0 1 2 3 4 5 6 7
    |> ArraySized.take Up { atLeast = n7 } n7
    --: ArraySized number_ (In (Up7 minX_) (Up7 maxX_))
    |> ArraySized.toList
--> [ 0, 1, 2, 3, 4, 5, 6 ]


ArraySized.l8 0 1 2 3 4 5 6 7
    |> ArraySized.take Up { atLeast = n7 } n7AtLeast
--: ArraySized number_ (Min (Up7 x_))


ArraySized.l8 0 1 2 3 4 5 6 7
    |> ArraySized.minTo
    |> ArraySized.take Up { atLeast = n2 } between2And7
--: ArraySized number_ (In (Up2 minX_) (Up7 maxX_))

Is the amount taken greater than the ArraySized's length minimum?

ArraySized.n1To between3And6
    -- its first four elements
    |> ArraySized.take Down { atLeast = n3 } (n4 |> N.minTo n3)

If you're having trouble understanding the atLeast field, think of looking at the implementation of take will help:

take direction { atLeast } toTakeAmount =
    minTo atLeast
        >> takeCurrentMin direction toTakeAmount

Open for alternative API suggestions! I'm actually close to removing take in favor of takeCurrentMin and renaming that to take. Let me know what you think!

Take a given number of elements in a given direction

As the simpler version of take you can only take at least the type's minimum amount.

It's most of the time not what you want, since you usually want a shorter array minimum after taking.

Elements after a certain number of elements in a given Direction

import Linear exposing (Direction(..))
import N exposing (n2)


ArraySized.l4 0 1 2 3
    |> ArraySized.drop Down n2
    --: ArraySized number_ (In (Up2 minX_) (Up2 maxX_))
    |> ArraySized.toList
--> [ 0, 1 ]


between6And10Elements
    |> ArraySized.drop Up between2And3
    --: ArraySized number_ (In (Up3 minX_) (Up8 maxX_))

• Don't know its length maximum? → dropMin
• Can the dropped length's maximum be greater than its length's minimum? → dropMax

Elements after a certain number of elements in a given Direction

import Linear exposing (Direction(..))
import N exposing (n2)


atLeast6Elements
    |> ArraySized.dropMin Down n2
--: ArraySized ... (Min (On N4))

• Know its length maximum? → drop
• Can the dropped length's maximum be greater than its length's minimum? → dropMax

Elements after a certain number of elements in a given Direction

import Linear exposing (Direction(..))
import N exposing (n2, n5)


ArraySized.l4 0 1 2 3
    |> ArraySized.dropMax Down (3 |> N.intToIn ( n2, n5 ))
    --: ArraySized number_ (In (Up0 minX_) (On N2))
    |> ArraySized.toList
--> [ 0, 1 ]

• Is the dropped length's maximum less than its length's minimum? → drop
• Don't know the array's length maximum? → dropMin

Reach a given length:

• If the current length is greater than a given length, take the new length in a given direction

• If the current length is less than a given length, pad further in a given Direction based on the index in the final ArraySized

.

import N exposing (n8)
import Linear exposing (Direction(..))


type Bit
    = I
    | O


ArraySized.l3 I O I
    |> ArraySized.toSize Down n8 (\_ -> O)
    --: ArraySized Bit (In (On N8) (Up8 x_))
    |> ArraySized.toList
--> [ O, O, O, O, O, I, O, I ]


ArraySized.l4
    (ArraySized.l3 I I I |> ArraySized.maxTo n8)
    (ArraySized.l8 O I I I O I O O)
    (ArraySized.l8 O I I I O I O O)
    (ArraySized.l8 O I I I O I O O)
    |> ArraySized.map
        (ArraySized.toSize Down n8 (\_ -> O))
    |> ArraySized.map ArraySized.toList
    |> ArraySized.toList
--> [ [ O, O, O, O, O, I, I, I ]
--> , [ O, I, I, I, O, I, O, O ]
--> , [ O, I, I, I, O, I, O, O ]
--> , [ O, I, I, I, O, I, O, O ]
--> ]

Split the ArraySized into equal-sized (except remainder) slices in a given Direction

• chunks: the ArraySized divided into equal-sized Arrs
• remainder: values to one side that don't fill a whole group

↓

import Linear exposing (Direction(..))
import N exposing (n0, n5)


ArraySized.l7 1 2 3 4 5 6 7
    |> ArraySized.toChunksOf Up n5
    --: { chunks :
    --:     ArraySized
    --:         (ArraySized
    --:             number_
    --:             (In (Up5 chunkMinX_) (Up5 chunkMaxX))
    --:         )
    --:         (In (Up0 minX_) (Up7 maxX_))
    --: , remainder :
    --:     ArraySized
    --:         number_
    --:         (In
    --:             (Up0 remainderMinX_)
    --:             (Up4 chunkMaxX)
    --:         )
    --: }
    |> .remainder
    |> ArraySized.toList
--> [ 6, 7 ]




ArraySized.l7 1 2 3 4 5 6 7
    |> ArraySized.toChunksOf Down n5
    |> .remainder
    |> ArraySized.toList
--> [ 1, 2 ]

Combine each element with an element at the same index from a given ArraySized into a tuple

Every element beyond the minimum length of both is't part of the final ArraySized

import ArraySized


answer
    |> ArraySized.and guess
    |> ArraySized.map
        (\( answerChar, guessChar ) ->
            { directMatch = guessChar == answerChar }
        )

This is often misused

• multiple structures for different attributes of the same thing
  • example: one list for exercises, one matching the cards' indexes with progress
  • these should be in the same structure
• applying multiple changes for a sequence of indexes
  • example: https://github.com/Rototu/storefront/blob/f8fe0b7cb823e3a50f175985a13762f9482ae4a8/frontend/src/Page/Home.elm#L24-L32
  • each of those indices seem to have special meaning. Use a record to gain type-safety and be more descriptive
• stupid stuff where another operation like map would be more appropriate
  • example: https://github.com/dclutr/a-toastmasters-certificates-tool/blob/0cb97c2766c6c51bb32881a1e7c77beb21b1c32a/Main.elm#L165-L172

Glue elements of an ArraySized with an amount of elements in a range to the end of a given direction

import Linear exposing (Direction(..))


ArraySized.l3 1 2 3
    |> ArraySized.attach Up (ArraySized.l3 4 5 6)
    --: ArraySized number_ (In (Up6 minX_) (Up6 maxX_))
    |> ArraySized.toList
--> [ 1, 2, 3, 4, 5, 6 ]


ArraySized.l3 1 2 3
    |> ArraySized.attach Down (ArraySized.l3 4 5 6)
    |> ArraySized.toList
--> [ 4, 5, 6, 1, 2, 3 ]

Don't know both length maxima? → attachMin

Glue elements of an ArraySized to the end of a given direction

ArraySized.l3 1 2 3
    |> ArraySized.attachMin Up atLeast3Elements
--: ArraySized ... (Min (Up6 x_))


ArraySized.l3 1 2 3
    |> ArraySized.attachMin Down atLeast3Elements
--: ArraySized ... (Min (Up6 x_))

Know both length maxima? → attach

Place all elements of an ArraySized between all current members. Extra elements of either ArraySized are attached to the end without separating elements from the other ArraySized

import N exposing (n2)


ArraySized.l3 "turtles" "turtles" "turtles"
    |> ArraySized.interweave (ArraySized.repeat "on" n2)
    --: ArraySized String (In (Up5 minX_) (Up5 maxX_))
    |> ArraySized.toList
--> [ "turtles", "on", "turtles", "on", "turtles" ]


ArraySized.l3 "turtles" "turtles" "turtles"
    |> ArraySized.interweave (ArraySized.repeat "on" between5And10)
--→ "turtles" "on" "turtles" "on" "turtles" "on" "on" "on" ...
--: ArraySized String (In (Up5 minX_) (Up13 maxX_))

Don't know both maxima → interweaveMin

Place all elements of an ArraySized between all current members. Extra elements of either ArraySized are attached to the end without separating elements from the other ArraySized

import N exposing (n2)


ArraySized.l3 "turtles" "turtles" "turtles"
    |> ArraySized.interweaveMin
        (ArraySized.repeat "on" atLeast2)
    --: ArraySized String (Min (Up5 minX_))

Know both maxima → interweave

Reduce an ArraySized in a given Direction

import Linear exposing (Direction(..))


ArraySized.l4 'l' 'i' 'v' 'e'
    |> ArraySized.foldFrom "" Down String.cons
--> "live"


ArraySized.l4 'l' 'i' 'v' 'e'
    |> ArraySized.foldFrom "" Up String.cons
--> "evil"


sum =
    ArraySized.foldFrom 0 Up (\soFar n -> soFar + n)


product =
    ArraySized.foldFrom 0 Up (\soFar n -> soFar * n)

A fold in a given Direction where the initial result is the first element in the ArraySized

import Linear exposing (Direction(..))


ArraySized.l3 234 345 543
    |> ArraySized.fold Up Basics.max
--> 543


ArraySized.l3 "go" "to" "uni"
    |> ArraySized.fold Down
        (\word soFar -> soFar ++ " " ++ word)
--> "uni to go"

Fold, starting from one end element transformed to the initial accumulation value, then reducing what's accumulated in a given Direction Usually used to convert to a different non-empty structure

import Emptiable exposing (Emptiable)
import N exposing (Add1, In, On)
import Stack exposing (Stacked)


toStackFilled :
    ArraySized
        element
        (In (On (Add1 minFrom1_)) max_)
    -> Emptiable (Stacked element) Never
toStackFilled =
    ArraySized.foldFromOne Stack.one Stack.onTopLay

fold is a simple version that folds directly from the start element:

Stack.fold =
    Stack.foldFromOne identity

Convert to an Array.

Make these kinds of conversions your final step. Try to keep extra information as long as you can: "wrap early, unwrap late"

import N exposing (n4)
import Array


ArraySized.n1To n4
    |> ArraySized.map N.toInt
    |> ArraySized.toArray
--> Array.fromList [ 1, 2, 3, 4 ]

Convert to a List.

Make these kinds of conversions your final step. Try to keep extra information as long as you can: "wrap early, unwrap late"

import N exposing (n4)


ArraySized.n1To n4
    |> ArraySized.map N.toInt
    |> ArraySized.toList
--> [ 1, 2, 3, 4 ]

On empty Emptiable.empty, on one filled with its only value

Emptiness type information is transferred

Convert to an Emptiable (Stacked ...) never_.

Make these kinds of conversions your final step. Try to keep extra information as long as you can: "wrap early, unwrap late"

import N exposing (n4)
import Emptiable
import Stack


ArraySized.n1To n4
    |> ArraySized.map N.toInt
    |> ArraySized.toStack
--> Stack.topBelow 1 [ 2, 3, 4 ]
--: Emptiable (Stacked Int) Never


ArraySized.l4 (0 |> Emptiable.filled) Emptiable.empty Emptiable.empty (3 |> Emptiable.filled)
    |> ArraySized.fills
    |> ArraySized.toStack
--> Stack.topBelow 0 [ 3 ]
--: Emptiable (Stacked Int) Possibly

Convert to a String.

Make these kinds of conversions your final step. Try to keep extra information as long as you can: "wrap early, unwrap late"

import N exposing (n4)


ArraySized.n1To n4
    |> ArraySized.map
        (\n ->
            ('a' |> Char.toCode)
                + (n |> N.toInt) - 1
                |> Char.fromCode
        )
    |> ArraySized.toString
--> "abcd"

Transform into a Toop.T2 to simplify accessing elements, pattern matching

Transform into a Toop.T3 to simplify accessing elements, pattern matching

Transform into a Toop.T4 to simplify accessing elements, pattern matching

Transform into a Toop.T5 to simplify accessing elements, pattern matching

Transform into a Toop.T6 to simplify accessing elements, pattern matching

Transform into a Toop.T7 to simplify accessing elements, pattern matching

Transform into a Toop.T8 to simplify accessing elements, pattern matching

Transform into a Toop.T9 to simplify accessing elements, pattern matching

Transform into a Toop.T10 to simplify accessing elements, pattern matching

Transform into a Toop.T11 to simplify accessing elements, pattern matching

Transform into a Toop.T12 to simplify accessing elements, pattern matching

Transform into a Toop.T13 to simplify accessing elements, pattern matching

Transform into a Toop.T14 to simplify accessing elements, pattern matching

Transform into a Toop.T15 to simplify accessing elements, pattern matching

Transform into a Toop.T16 to simplify accessing elements, pattern matching

ArraySized with a length of On range → equatable OnValue range

If you have a Min length, you instead only need minToNumber

ArraySized with a length of equatable OnValue range → On range, allowing it to be altered, compared, ...

If you have a Min length, you instead only need minToOn

ArraySized with a length with an On minimum → equatable OnValue minimum

You'll usually use this to convert to a Min (OnValue ...) length

ArraySized with a length with an equatable OnValue minimum → On minimum, allowing it to be altered, compared, ...

You'll usually use this to convert to a Min (On ...) length

ArraySized with a length with an On maximum → equatable OnValue maximum

ArraySized with a length with an equatable OnValue maximum → On maximum, allowing it to be altered, compared, ...

Make an ArraySized with a on maximum length fit into functions with require a higher maximum length

type alias Row =
    ArraySized Field (Exactly (On N18))

Row's length range can't be added to another length

attach2TemporaryFields : Row -> ...
attach2TemporaryFields rowFromModelOrSomeStorage =
    ArraySized.repeat Temporary n2
        |> ArraySized.attach Up rowFromModelOrSomeStorage

Only Up<n> x can do that

attach2TemporaryFields :
    Row
    ->
        ArraySized
            Field
            (In (Up20 minX_) (Up20 maxX_))
attach2TemporaryFields rowFromModelOrSomeStorage =
    ArraySized.repeat Temporary n2
        |> ArraySized.attach Up
            (rowFromModelOrSomeStorage
                |> ArraySized.minTo n18
                |> ArraySized.maxTo n18
            )

Equivalent to minTo n0, except that the current length minimum isn't required to be On.

It can be used to make argument types to functions look nicer.

Have a specific minimum in mind? → minTo

Want to increase the upper bound by a on amount? ↓

ArraySized.l4 'a' 'b' 'c' 'd'
    --: ArraySized Char (In (Up4 minX_) (Up4 maxX_))
    |> ArraySized.minSubtract n2
--: ArraySized Char (In (Up2 minX_) (Up4 maxX_))

When is this useful? Very rarely, to preserve type variables

emptiablePush :
    Emptiable element possiblyOrNever_
    ->
        (ArraySized
            element
            (In
                (Up minX To minPlusX)
                (Up maxX To maxPlusX)
            )
         ->
            ArraySized
                element
                (In (Up minX To minPlusX) (Up maxX To (Add1 maxPlusX)))
        )
emptiablePush emptiableElementToPush =
    case emptiableElementToPush of
        Emptiable.Empty _ ->
            ArraySized.maxAdd n1


        Emptiable.Filled elementToPush ->
            ArraySized.push elementToPush
                >> ArraySized.minSubtract n1

Here, you could alternatively attach its fromEmptiable.

More in N.minSubtract

Decrease the start and end of its length minimum difference

ArraySized.repeat () n3
    --: ArraySized () (In (Up3 (Add2 minX_)) (Up3 maxX_))
    |> ArraySized.minEndsSubtract n2
--: ArraySized () (In (Up5 minX_) (Up5 maxX_))

N.maxEndsSubtract has an example of where this can be useful.

Make an ArraySized with a on maximum length fit into functions with require a higher maximum length

type alias Row =
    ArraySized Field (Exactly (On N18))

Row's length range can't be added to another length

attach2TemporaryFields : Row -> ...
attach2TemporaryFields rowFromModelOrSomeStorage =
    ArraySized.repeat Temporary n2
        |> ArraySized.attach Up rowFromModelOrSomeStorage

Only Up<n> x can do that

attach2TemporaryFields :
    Row
    ->
        ArraySized
            Field
            (In (Up20 minX_) (Up20 maxX_))
attach2TemporaryFields rowFromModelOrSomeStorage =
    ArraySized.repeat Temporary n2
        |> ArraySized.attach Up
            (rowFromModelOrSomeStorage
                |> ArraySized.minTo n18
                |> ArraySized.maxTo n18
            )

Another example: re-enabling an argument's maximum difference

atMost18Elements : ArraySized ... (In min_ (Up maxTo18_ To N18))

The argument in atMost18Elements should also fit in atMost19Elements for example

atMost19Elements theArgument -- error


atMost19Elements (theArgument |> ArraySized.maxTo n19)

maxAdd n1 is also possible, but unless you want to preserve the maxTo18_ type variable, there's no need to not use this absolute operation

Convert the ArraySized (In min ...) to a ArraySized (Min min)

between4And10Elements |> ArraySized.maxToInfinity
--: ArraySized ... (Min (Up4 x_))

There is only 1 situation you should use this

To make these the same type

[ atLeast1Element, between1And10Elements ]

Elm complains

all the previous elements in the list are ArraySized ... (Min N1)

[ atLeast1Element
, between1And10Elements |> ArraySized.maxToInfinity
]

Have a specific maximum in mind? → maxTo

Want to increase the upper bound by a on amount? ↓

ArraySized.l4 'a' 'b' 'c' 'd'
    --: ArraySized Char (In (Up4 minX_) (Up4 maxX_))
    |> ArraySized.maxAdd n2
--: ArraySized Char (In (Up4 minX_) (Up6 maxX_))

When is this useful? Very rarely, to preserve type variables

emptiablePush :
    Emptiable element possiblyOrNever_
    ->
        (ArraySized
            element
            (In
                (Up minX To minPlusX)
                (Up maxX To maxPlusX)
            )
         ->
            ArraySized
                element
                (In (Up minX To minPlusX) (Up maxX To (Add1 maxPlusX)))
        )
emptiablePush emptiableElementToPush =
    case emptiableElementToPush of
        Emptiable.Empty _ ->
            ArraySized.maxAdd n1


        Emptiable.Filled elementToPush ->
            ArraySized.push elementToPush
                >> ArraySized.minSubtract n1

Here, you could alternatively attach its fromEmptiable.

More in N.maxAdd

Decrease the start and end of its length maximum difference

ArraySized.repeat () n3
    --: ArraySized () (In (Up3 minX_) (Up3 (Add2 maxX_)))
    |> ArraySized.maxEndsSubtract n2
--: ArraySized () (In (Up5 minX_) (Up5 maxX_))

N.maxEndsSubtract has an example of where this can be useful.

Transfer the knowledge about whether 0 is a possible length

toEmptiable :
    ArraySized
        element
        (In (On (N0OrAdd1 possiblyOrNever minFrom1_)) (Up maxTo1_ To N1))
    -> Emptiable element possiblyOrNever
toEmptiable =
    \arraySized ->
        arraySized
            |> ArraySized.hasAtLeast1
            |> Emptiable.map ArraySized.toOne

It really is just that simple: first try hasAtLeast1, then map that possibility using the knowledge that the ArraySized has at least 1 element

toStack :
    ArraySized
        element
        (In (On (N0OrAdd1 possiblyOrNever minFrom1_)) max_)
    -> Emptiable (Stacked element) possiblyOrNever
toStack =
    \arraySized ->
        arraySized
            |> ArraySized.hasAtLeast1
            |> Emptiable.mapFlat
                (ArraySized.foldFromOne Stack.one Down Stack.onTopLay)

Change the possiblyOrNever type for the case that its length minimum is 0

never allows you to adapt any variable, \_ -> yourVariablePossiblyOrNever swaps it for your given variable

fromEmptiable :
    Emptiable element possiblyOrNever
    ->
        ArraySized
            element
            (In (On (N0OrAdd1 possiblyOrNever N0)) (Up1 maxX_))
fromEmptiable =
    \emptiable ->
        case emptiable of
            Emptiable.Filled content ->
                ArraySized.one content
                    -- min = 0 can never happen → any variable possible
                    |> ArraySized.min0Adapt never


            Emptiable.Empty possiblyOrNever ->
                ArraySized.empty
                    |> ArraySized.min0Adapt (\_ -> possiblyOrNever)
                    -- there's no min successor → any variable possible
                    |> ArraySized.minAtLeast1Never
                    -- the other has max = 1. Let's adapt that higher max here
                    |> ArraySized.maxAdd n1

using minAtLeast1Never, maxAdd

Read more at N.min0Adapt

Change the successor type for the case that its length minimum is 1 + ... to allow adapting any variable

fromEmptiable :
    Emptiable element possiblyOrNever
    ->
        ArraySized
            element
            (In (On (N0OrAdd1 possiblyOrNever N0)) (Up1 maxX_))
fromEmptiable =
    \emptiable ->
        case emptiable of
            Emptiable.Filled content ->
                ArraySized.one content
                    -- min = 0 can never happen → any variable possible
                    |> ArraySized.min0Adapt never


            Emptiable.Empty possiblyOrNever ->
                ArraySized.empty
                    |> ArraySized.min0Adapt (\_ -> possiblyOrNever)
                    -- there's no min successor → any variable possible
                    |> ArraySized.minAtLeast1Never
                    -- the other has max = 1. Let's adapt that higher max here
                    |> ArraySized.maxAdd n1

using hasAtLeast1, min0Adapt.