urbit/base/pub/doc/hoon/library/2a.md

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

<h3 id="++add"><code>++add</code></h3>

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

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

<h3 id="++cap"><code>++cap</code></h3>

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

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

<h3 id="++dec"><code>++dec</code></h3>

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

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

<h3 id="++div"><code>++div</code></h3>

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

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

<h3 id="++fac"><code>++fac</code></h3>

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

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

<h3 id="++gte"><code>++gte</code></h3>

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

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

<h3 id="++gth"><code>++gth</code></h3>

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

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

<h3 id="++lte"><code>++lte</code></h3>

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

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

<h3 id="++lth"><code>++lth</code></h3>

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

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

<h3 id="++mas"><code>++mas</code></h3>

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

<h3 id="++max"><code>++max</code></h3>

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

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

<h3 id="++min"><code>++min</code></h3>

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

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

<h3 id="++mod"><code>++mod</code></h3>

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]().

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

<h3 id="++mul"><code>++mul</code></h3>

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

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

<h3 id="++peg"><code>++peg</code></h3>

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

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

<h3 id="++sub"><code>++sub</code></h3>

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

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