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 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.

See also: ++lift, ++cork

++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

See also: ++turn, ++snag

++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.

See also: ++bind