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 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 $2^{2^a}$ , where $a$ or .a is the block size. That's because a block of size $a$ contains $2^a$ bits, and a binary number that is $b$ or .b bits wide can represent $2^b$ values.

A +bloq of 0 has a bitwidth of 1. ( $2^0$ bits; can represent $2^{2^0}=2$ different values.)

A +bloq of 1 has a bitwidth of 2. ( $2^1$ bits; can represent $2^{2^1}=4$ different values.)

A +bloq of 2 has a bitwidth of 4. ( $2^2$ bits; can represent $2^{2^2}=16$ different values.)

A +bloq of 3 has a bitwidth of 8. ( $2^3$ bits; can represent $2^{2^3}=256$ different 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 $this.

Source

++  each
  |$  [this that]
  $%  [%| p=that]
      [%& p=this]
  ==

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.ddq [* <46.hgz 1.pnw %140>]>
<1.ddq [* <46.hgz 1.pnw %140>]>

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

> (`gate`|=(a=@ [a 'b']) 1)
mint-nice
-need.@
-have.*
nest-fail
dojo: hoon expression failed

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
  |$  [item]
  $@(~ [i=item t=(list item)])

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
  |$  [item]
  p=item

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
  |$  [head tail]
  [p=head q=tail]

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
  |$  [item]
  $@(~ [item (pole item)])

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
  |$  [first second third fourth]
  [p=first q=second r=third s=fourth]

Examples

> *(qual date time tape cord)
[p=[[a=%.y y=0] m=0 t=[d=0 h=0 m=0 s=0 f=~]] q=~2000.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 $item and the mold of $state.

Source

++  quip
  |$  [item state]
  [(list item) state]

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.

`+step`

Atom size or offset, in +bloqs.

Source

++  step
  _`@u`1

Examples

> `step`0
0

> `step`2
2

`+trap`

Core with one arm $.

A trap is a core with one arm $.

Source

++  trap
  |$  [product]
  _|?($:product)

Examples

> (*trap)
<1?ruo 1.mhl [product=<1|xpg [* * *]> <46.hgz 1.pnw %140>]>

> *(*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
  |$  [node]
  $@(~ [n=node l=(tree node) r=(tree node)])

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
  |$  [first second third]
  [p=first q=second r=third]

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=item], where $item is the type that was passed in.

Source

++  unit
  |$  [item]
  $@(~ [~ u=item])

Examples

> ? *(unit time)
  u(@da)
~

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

Discussion

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