1c: Molds and Mold-Builders

`$bite`

Atom slice specifier.

Either a single atom representing block size, or a cell containing a block size and an atom representing the number of blocks, called step. If step is not supplied, it defaults to a value of 1.

Source

+$  bite  $@(bloq [=bloq =step])

Examples

    ::  ++end gets the least significant bits of an atom.

    > (end [1 1] 255)
    3

    > (end 1 255)
    3

    > (end 3 255)
    255

    > (end 3 65.535)
    255

    > (end [3 2] 65.535)
    65.535

    > (end [3 0] 65.535)
    0

`$bloq`

Blocksize

Atom representing block size. A block of size a has a bitwidth of 2^a.

Source

++  bloq  @

Examples

    ::  ++met measures how many a-bloqs long an atom is.

    > (met 3 256)
    2

    > (met 3 255)
    1

    > (met 3 65.535)
    2

    > (met 2 65.536)
    > 3

    > (met 0 4)
    3

    > (met 1 4)
    2

    > (met 5 9.999.999.999)
    2

    > (met 2 0xb5)
    2

Discussion

You can think of bloq as a numeral system that can represent values of a^2^2, where a is the block size. That's because a block of size a contains a^2 bits, and a binary number that is b bits wide can represent b^2 values.

A bloq of 0 has a bitwidth of 1. (2^0 bits; can represent 2 values.)

A bloq of 1 has a bitwidth of 2. (2^1 bits; can represent 4 values.)

A bloq of 2 has a bitwidth of 4. (2^2 bits; can represent 16 values.)

A bloq of 3 has a bitwidth of 8. (2^3 bits; can represent 256 values.)

And so on.

See the bit arithmetic section for operations that use bloqs.

`++each`

Mold of fork between two types

A mold generator. Produces a discriminated fork between two types, defaulting to a.

Source

    ++  each
      |*([a=mold b=mold] $%([$| p=b] [$& p=a]))

Examples

    > ? *(each cord time)
      ?({$.y p/@t} {$.n p/@da})
    [%.y p='']

    > ? *(each * tape)
      ?({$.y p/*} {$.n p/""})
    [%.y p=0]

`++gate`

Function

A core with one arm, $--the empty name--which transforms a sample noun into a product noun. If used dryly as a type, the subject must have a sample type of *.

Source

++  gate
      $-(* *)

Examples

    > ? gate
      <1.rdl {* <31.ohr 1.jmk $143>}>
    <1.rdl {* <31.ohr 1.jmk $143>}>

    > (`gate`|=(a=* [a 'b']) 1)
    [1 98]

    > (`gate`|=(a=@ [a 'b']) 1)
    ! nest-fail
    ! exit

Discussion

A gate is analogous to a function in other programming languages. We created this new jargon because other constructs in Urbit are "functions" in the mathematical sense. Any gate normalizes to an iron gate.

`++list`

List

A mold generator. Generates a mold of a null-terminated list of a homogenous type.

Source

++  list
      |*(a=mold $@($~ (lest a)))

Examples

    > *(list)
    ~

    > `(list @)`"abc"
    ~[97 98 99]

    > (snag 0 "abc")
    'a'

    > `(list @)`[1 2 'j' ~]
    ~[1 2 106]

Discussion

`++lone`

Face on mold

A mold generator. Puts face of p on the passed-in mold.

Source

++  lone
      |*(a=mold [p=a])

Examples

    > ? *cord
      @t
    ''
    > ? *(lone cord)
      p/@t
    p=''

    > ? *(lone @)
      p/@
    p=0
    > ? *@
      @
    0

`++pair`

Mold of pair of types

A mold generator. Produces a tuple of two of the types passed in.

Source

++  pair
      |*([a=mold b=mold] [p=a q=b])

Examples

    > *(pair ? cord)
    [p=%.y q='']

    > *(pair tape @)
    [p="" q=0]

`++pole`

Faceless list

A mold generator. A list without the faces i and t.

Source

++  pole
      |*(a=mold $@($~ [a (pole a)]))

Examples

    > =/(a "asdf" ?>(?=(^ a) `(lest @tD)`a))
    [i='a' t=[i='s' t=[i='d' t=[i='f' t=~]]]]

    > `(pole char)`"asdf"
    ['a' ['s' ['d' ['f' ~]]]]

`++qual`

Mold of 4-type tuple

A mold generator. Produces a tuple of four of the types passed in.

Source

++  qual
      |*  [a=mold b=mold c=mold d=mold]
      [p=a q=b r=c s=d]

Examples

    > *(qual date time tape cord)
    [p=[[a=%.y y=0] m=0 t=[d=0 h=0 m=0 s=0 f=~]] q=~292277024401-.1.1 r="" s='']

    > *(qual (list @) @u @ud @ux)
    [p=~ q=0 r=0 s=0x0]

`++quip`

Mold of pair of list and type

A mold generator. Produces a tuple of a list of a and the mold of b.

Source

++  quip
      |*([a=mold b=mold] [(list a) b])

Examples

    > *(quip @ _'hi')
    [~ 'hi']

    > `(quip @ @ux)`[[1 2 3 4 ~] 0x10]
    [~[1 2 3 4] 0x10]

Discussion

A common pattern in Hoon code is to return a list of changes, along with a new state. You'll often see quip used in Gall apps.

`++trap`

Core with one arm $

A trap is a core with one arm $.

Source

++  trap
      |*(a=mold _|?(*a))

Examples

    > (*trap)
    <1?dxy 1.oeg {a/<1|rbb {* <31.ohr 1.jmk $143>}> <31.ohr 1.jmk $143>}>

    > *(*trap)
    0

    > (|.(42))
    42

`++tree`

Tree mold generator

A mold generator. A tree can be empty, or contain a node of a type and left/right sub tree of the same type. Pretty-printed with {}.

Source

++  tree
      |*(a=mold $@($~ [n=a l=(tree a) r=(tree a)]))

Examples

    > `(tree [@ tape])`[[1 "hi"] [[2 "bye"] ~ ~] ~]
    {[2 "bye"] [1 "hi"]}

`++trel`

Mold of three types

A mold generator. A mold of the tuple of the three types passed in.

Source

++  trel
      |*([a=mold b=mold c=mold] [p=a q=b r=c])

Examples

    > *(trel @ud @t @s)
    [p=0 q='' r=--0]

    > *(trel cord bloq tape)
    [p='' q=0 r=""]

`++unit`

Maybe

A mold generator. A unit is either ~ or [~ u=a], where a is the type that was passed in.

Source

++  unit
      |*(a=mold $@($~ [$~ u=a]))

Examples

    > ? *(unit time)
      ?({$~ u/@da} $~)
     ~

    > =a |=  a=@
    ^-  (unit @)
    ?~  a  ~
    [~ a]
    > (a 2)
    [~ u=2]

Discussion

Using a unit allows you to specify something that may not be there.