urbit/pub/docs/dev/hoon/library/2a.md

chapter 2a, basic unsigned math
===============================

### `++add`

Add

    ++  add                                                 ::  add
      ~/  %add
      |=  [a=@ b=@]
      ^-  @
      ?:  =(0 a)  b
      $(a (dec a), b +(b))
    ::

Produces the sum of `a` and `b` as an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (add 2 2)
    4
    ~zod/try=> (add 1 1.000.000)
    1.000.001
    ~zod/try=> (add 1.333 (mul 2 2))
    1.337

------------------------------------------------------------------------

### `++cap`

Tree head

    ++  cap                                                 ::  tree head
      ~/  %cap
      |=  a=@
      ^-  ?(%2 %3)
      ?-  a
        %2        %2
        %3        %3
        ?(%0 %1)  !!
        *         $(a (div a 2))
      ==
    ::

Tests whether an `a` is in the head or tail of a noun. Produces the
[cube]() `%2` if it is within the head, or the [cube]() `%3` if is is
within the tail.

`a` is an [atom]().

    ~zod/try=> (cap 4)
    %2
    ~zod/try=> (cap 6)
    %3
    ~zod/try=> (cap (add 10 9))
    %2

------------------------------------------------------------------------

### `++dec`

Decrement

    ++  dec                                                 ::  decrement
      ~/  %dec
      |=  a=@
      ~|  %decrement-underflow
      ?<  =(0 a)
      =+  b=0
      |-  ^-  @
      ?:  =(a +(b))  b
      $(b +(b))
    ::

Produces `a-1` as an atom.

`a` is an [atom]().

    ~zod/try=> (dec 7)
    6
    ~zod/try=> (dec 0)
    ! decrement-underflow
    ! exit

------------------------------------------------------------------------

### `++div`

Divide

    ++  div                                                 ::  divide
      ~/  %div
      |=  [a=@ b=@]
      ^-  @
      ~|  'div'
      ?<  =(0 b)
      =+  c=0
      |-
      ?:  (lth a b)  c
      $(a (sub a b), c +(c))
    ::

Computes `a` divided by `b`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (div 4 2)
    2
    ~zod/try=> (div 17 8)
    2
    ~zod/try=> (div 20 30)
    0

------------------------------------------------------------------------

### `++fac`

Factorial

    ++  fac                                                 ::  factorial
      ~/  %fac
      |=  a=@
      ^-  @
      ?:  =(0 a)  1
      (mul a $(a (dec a)))
    ::

Computes the factorial of `a`, producing an atom.

`a` is an [atom]().

    ~zod/try=> (fac 3)
    6
    ~zod/try=> (fac 0)
    1
    ~zod/try=> (fac 11)
    39.916.800

------------------------------------------------------------------------

### `++gte`

Greater-than/equal

    ++  gte                                                 ::  greater-equal
      ~/  %gte
      |=  [a=@ b=@]
      ^-  ?
      !(lth a b)
    ::

Tests whether `a` is greater than a number `b`, producing a loobean.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (gte 100 10)
    %.y
    ~zod/try=> (gte 4 4)
    %.y
    ~zod/try=> (gte 3 4)
    %.n

------------------------------------------------------------------------

### `++gth`

Greater-than

    ++  gth                                                 ::  greater-than
      ~/  %gth
      |=  [a=@ b=@]
      ^-  ?
      !(lte a b)
    ::

Tests whether `a` is greater than `b`, producing a loobean.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (gth 'd' 'c')
    %.y
    ~zod/try=> (gth ~h1 ~m61)
    %.n

------------------------------------------------------------------------

### `++lte`

Less-than/equal

    ++  lte                                                 ::  less-equal
      ~/  %lte
      |=  [a=@ b=@]
      |(=(a b) (lth a b))
    ::

Tests whether `a` is less than or equal to `b`, producing a loobean.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (lte 4 5)
    %.y
    ~zod/try=> (lte 5 4)
    %.n
    ~zod/try=> (lte 5 5)
    %.y
    ~zod/try=> (lte 0 0)
    %.y

------------------------------------------------------------------------

### `++lth`

Less-than

    ++  lth                                                 ::  less-than
      ~/  %lth
      |=  [a=@ b=@]
      ^-  ?
      ?&  !=(a b) 
          |-  
          ?|  =(0 a)  
              ?&  !=(0 b) 
                  $(a (dec a), b (dec b))
      ==  ==  ==
    ::

Tests whether `a` is less than `b`, producing a loobean.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (lth 4 5)
    %.y
    ~zod/try=> (lth 5 4)
    %.n
    ~zod/try=> (lth 5 5)
    %.n
    ~zod/try=> (lth 5 0)
    %.n

------------------------------------------------------------------------

### `++mas`

Axis within head/tail

    ++  mas                                                 ::  tree body
      ~/  %mas
      |=  a=@
      ^-  @
      ?-  a
        1   !!
        2   1
        3   1
        *   (add (mod a 2) (mul $(a (div a 2)) 2))
      ==
    ::

------------------------------------------------------------------------

Computes the axis of `a` within the head or the tail, producing an atom.

`a` is an [atom]().

    ~zod/try=> (mas 3)
    1
    ~zod/try=> (mas 4)
    2
    ~zod/try=> (mas 5)
    3
    ~zod/try=> (mas 6)
    2
    ~zod/try=> (mas 0)
    ! exit
    ~zod/try=> (mas 1)
    ! exit

### `++max`

Maximum

    ++  max                                                 ::  maximum
      ~/  %max
      |=  [a=@ b=@]
      ^-  @
      ?:  (gth a b)  a
      b
    ::

Computes the maximum of `a` and `b`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (max 10 100)
    100
    ~zod/try=> (max 10.443 9)
    10.443
    ~zod/try=> (max 0 1)
    1

------------------------------------------------------------------------

### `++min`

Minimum

    ++  min                                                 ::  minimum
      ~/  %min
      |=  [a=@ b=@]
      ^-  @
      ?:  (lth a b)  a
      b
    ::

Computes the minimum of `a` and `b`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (min 10 100)
    10
    ~zod/try=> (min 10.443 9)
    9
    ~zod/try=> (min 0 1)
    0

------------------------------------------------------------------------

### `++mod`

Modulus

    ++  mod                                                 ::  remainder
      ~/  %mod
      |=  [a=@ b=@]
      ^-  @
      ?<  =(0 b)
      (sub a (mul b (div a b)))
    ::

Computes the remainder of dividing `a` by `b`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

------------------------------------------------------------------------

### `++mul`

Multiply

    ++  mul                                                 ::  multiply
      ~/  %mul
      |=  [a=@ b=@]
      ^-  @
      =+  c=0
      |-
      ?:  =(0 a)  c
      $(a (dec a), c (add b c))
    ::

Multiplies `a` by `b`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (mul 3 4)
     12 
    ~zod/try=> (mul 0 1) 
    0

------------------------------------------------------------------------

### `++peg`

Axis within axis

    ++  peg                                                 ::  tree connect
      ~/  %peg
      |=  [a=@ b=@]
      ^-  @
      ?-  b
        1   a
        2   (mul a 2)
        3   +((mul a 2))
        *   (add (mod b 2) (mul $(b (div b 2)) 2))
      ==
    ::

Computes the axis of `b` within axis `a`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=>  (peg 4 1)
    4
    ~zod/try=>  (peg 4 2)
    8
    ~zod/try=>  (peg 8 45)
    269

------------------------------------------------------------------------

### `++sub`

Subtract

    ++  sub                                                 ::  subtract
      ~/  %sub
      |=  [a=@ b=@]
      ~|  %subtract-underflow
      ^-  @
      ?:  =(0 b)  a
      $(a (dec a), b (dec b))

Subtracts `b` from `a`, producing an atom.

`a` is an [atom]().

`b` is an [atom]().

    ~zod/try=> (sub 10 5)
    5
    ~zod/try=> (sub 243 44)
    199
    ~zod/try=> (sub 5 0)
    5
    ~zod/try=> (sub 0 5)
    ! subtract-underflow
    ! exit

------------------------------------------------------------------------