# 4b: Text Processing
## `+at`
Basic printing.
Container core for basic `$atom` printing functions.
**Note that these are largely deprecated, using outdated syntax, character mappings and encodings, and should generally not be used.**
#### Accepts
`.a` is a `@`.
#### Source
```hoon
++ at
|_ a=@
```
***
### `+r:at`
Print term, number or hex.
If `.a` is composed of the letters `a` through `z` and `-`, print as `@tas` syntax. If `.a` is an `$atom` of two bytes or less, print as an integer with comma-separated thousands. Otherwise, print `.a` as `@ux` syntax.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ r
?: ?& (gte (met 3 a) 2)
|-
?: =(0 a)
&
=+ vis=(end 3 a)
?& ?|(=('-' vis) ?&((gte vis 'a') (lte vis 'z')))
$(a (rsh 3 a))
==
==
rtam
?: (lte (met 3 a) 2)
rud
rux
```
#### Examples
```
> ~(r at 'foo-bar')
"%foo-bar"
```
```
> ~(r at 0xbeef)
"48,879"
```
```
> ~(r at 0xdead.beef)
"0xdead-beef"
```
***
### `+rf:at`
Print loobean.
If `.a` is a loobean, print as `|`/`&`, otherwise crash.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rf `tape`[?-(a %& '&', %| '|', * !!) ~]
```
#### Examples
```
> ~(rf at %.y)
"&"
```
```
> ~(rf at %.n)
"|"
```
```
> ~(rf at 'foo')
dojo: hoon expression failed
```
***
### `+rn:at`
Print null.
If `.a` is null, print `~`, otherwise crash.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rn `tape`[?>(=(0 a) '~') ~]
```
#### Examples
```
> ~(rn at ~)
"~"
```
```
> ~(rn at 'foo')
dojo: hoon expression failed
```
### `+rt:at`
Print cord, including escape characters.
Print `.a` with `$cord` syntax, including escape characters.
#### Accepts
`.a` is a `@`, and the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rt `tape`['\'' (weld (mesc (trip a)) `$tape`['\'' ~])]
```
#### Examples
```
> ~(rt at 'foo')
"'foo'"
```
```
> ~(rt at 'fo\\o')
"'fo\\\\o'"
```
```
> ~(rt at 'fo\'o')
"'fo\\0x27/o'"
```
***
### `+rta:at`
Same as `+rt:at`.
#### Source
```hoon
++ rta rt
```
***
### `+rtam:at`
Print cord with `@tas` syntax.
Treat `.a` as `$cord`, print it with `%` prefix.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rtam `tape`['%' (trip a)]
```
#### Examples
```
> ~(rtam at 'foo')
"%foo"
```
```
> ~(rtam at '12')
"%12"
```
```
> ~(rtam at '!!!')
"%!!!"
```
***
### `+rub:at`
Print binary.
Print `.a` as `@ub` syntax, except with `-` separators rather than `.` separators.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rub `tape`['0' 'b' (rum 2 ~ |=(b=@ (add '0' b)))]
```
#### Examples
```
> ~(rub at 0xbeef)
"0b1011-1110-1110-1111"
```
***
### `+rud:at`
Print `$atom` as integer.
Print `$atom` `.a` as an integer, with commas separating thousands.
#### Accepts
`.a` is a `@`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rud (rum 10 ~ |=(b=@ (add '0' b)))
```
#### Examples
```
> ~(rud at 0xbeef)
"48,879"
```
***
### `+rum:at`
Print base-n.
Print `.a` as base `.b` with suffix `.c` and using gate `.d` to convert blocks to characters. Each set of four characters will be separated by `-`, except for base 10 which will be printed with commas separating thousands.
#### Accepts
* `.a` is a `@`, and is the sample of `+at`.
* `.b` is a `@`, denoting the the base.
* `.c` is a `$tape`, and will be appended to the end of the result.
* `.d` is a `$gate` that takes `@` and produces `@`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rum
|= [b=@ c=tape d=$-(@ @)]
^- tape
?: =(0 a)
[(d 0) c]
=+ e=0
|- ^- tape
?: =(0 a)
c
=+ f=&(!=(0 e) =(0 (mod e ?:(=(10 b) 3 4))))
%= $
a (div a b)
c [(d (mod a b)) ?:(f [?:(=(10 b) ',' '-') c] c)]
e +(e)
==
```
#### Examples
```
> (~(rum at 0xdead.beef) 10 ~ |=(b=@ (add '0' b)))
"3,735,928,559"
```
```
> (~(rum at 0xdead.beef) 10 " m/s" |=(b=@ (add '0' b)))
"3,735,928,559 m/s"
```
```
> (~(rum at 0xdead.beef) 2 ~ |=(b=@ (add '0' b)))
"1101-1110-1010-1101-1011-1110-1110-1111"
```
***
### `+rup:at`
Print `@p` (outdated).
Print `.a` as a `@p`, but with outdated syntax and number<->syllable mapping. This function almost certainly should not be used.
#### Accepts
`.a` is a `@`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rup
=+ b=(met 3 a)
^- tape
:- '-'
|- ^- tape
?: (gth (met 5 a) 1)
%+ weld
$(a (rsh 5 a), b (sub b 4))
`tape`['-' '-' $(a (end 5 a), b 4)]
?: =(0 b)
['~' ~]
?: (lte b 1)
(trip (tos:po a))
|- ^- tape
?: =(2 b)
=+ c=(rsh 3 a)
=+ d=(end 3 a)
(weld (trip (tod:po c)) (trip (tos:po (mix c d))))
=+ c=(rsh [3 2] a)
=+ d=(end [3 2] a)
(weld ^$(a c, b (met 3 c)) `tape`['-' $(a (mix c d), b 2)])
```
#### Examples
```
> ~(rup at 0xdead.beef)
"-rylsal-sellac"
```
```
> ~(rup at ~sampel-palnet)
"-sellod-lebdiv"
```
```
> ~(rup at ~zod)
"-~"
```
***
### `+ruv:at`
Print base-64.
Print `.a` as **outdated** base-64 syntax, with `0v` rather than `0w` prefix, different character mappings and separators.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ ruv
^- tape
:+ '0'
'v'
%^ rum
64
~
|= b=@
?: =(63 b)
'+'
?: =(62 b)
'-'
?:((lth b 26) (add 65 b) ?:((lth b 52) (add 71 b) (sub b 4)))
```
#### Examples
```
> ~(ruv at 0xdead.beef)
"0vDe-rb7v"
```
Note this is how it should be rendered:
```
> `@uw`0xdead.beef
0w3.uHrXL
```
***
### `+rux:at`
Print hexadecimal.
Print `.a` as `@ux` except with `-` separators rather than `.`s.
#### Accepts
`.a` is a `@`, and is the sample of `+at`.
#### Produces
A `$tape`.
#### Source
```hoon
++ rux `tape`['0' 'x' (rum 16 ~ |=(b=@ (add b ?:((lth b 10) 48 87))))]
```
#### Examples
```
> ~(rux at 0xdead.beef)
"0xdead-beef"
```
***
## `+cass`
To lowercase.
Turn all occurences of uppercase letters in any `$tape` into lowercase letters. Returns a `$tape`.
#### Accepts
`.vib` is a `$tape`.
#### Produces
A `$tape`.
#### Source
```hoon
++ cass
|= vib=tape
^- tape
(turn vib |=(a=@ ?.(&((gte a 'A') (lte a 'Z')) a (add 32 a))))
```
#### Examples
```
> (cass "JOHN DOE")
"john doe"
```
```
> (cass "abc ABC 123 !@#")
"abc abc 123 !@#"
```
```
> (cass "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
"aabbccddeeffgghhiijjkkllmmnnooppqqrrssqqrrvvwwxxyyzz"
```
***
## `+crip`
Tape to cord.
Produce a `$cord` from a `$tape`.
#### Accepts
`.a` is a `$tape`.
#### Produces
A `$cord`.
#### Source
```hoon
++ crip |=(a=tape `@t`(rap 3 a))
```
#### Examples
```
> (crip "john doe")
'john doe'
```
```
> (crip "abc 123 !@#")
'abc 123 !@#'
```
```
> `@ud`(crip "abc")
6.513.249
```
***
## `+cuss`
To uppercase.
Turn all occurences of lowercase letters in any `$tape` into uppercase letters. Returns a `$tape`.
#### Accepts
`.vib` is a `$tape`.
#### Produces
A `$tape`.
#### Source
```hoon
++ cuss
|= vib=tape
^- tape
(turn vib |=(a=@ ?.(&((gte a 'a') (lte a 'z')) a (sub a 32))))
```
#### Examples
```
> (cuss "john doe")
"JOHN DOE"
```
```
> (cuss "abc ABC 123 !@#")
"ABC ABC 123 !@#"
```
```
> (cuss "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
"AABBCCDDEEFFGGHHIIJJKKLLMMNNOOPPQQRRSSQQRRVVWWXXYYZZ"
```
***
## `+mesc`
Escape special chars.
Escape special characters.
#### Accepts
`.vib` is a `$tape`.
#### Produces
A `$tape`.
#### Source
```hoon
++ mesc
|= vib=tape
^- tape
?~ vib
~
?: =('\\' i.vib)
['\\' '\\' $(vib t.vib)]
?: ?|((gth i.vib 126) (lth i.vib 32) =(`@`39 i.vib))
['\\' (welp ~(rux at i.vib) '/' $(vib t.vib))]
[i.vib $(vib t.vib)]
```
#### Examples
```
> (mesc "ham lus")
"ham lus"
```
```
> (mesc "bas\\hur")
"bas\\\\hur"
```
```
> (mesc "as'saß")
"as\0x27/sa\0xc3/\0x9f/"
```
***
## `+runt`
Prepend *n* times.
Add `.a` repetitions of character `.b` to the head of `$tape` `.c`.
#### Accepts
`.a` and `.b` are `$atom`s.
`.c` is a `$tape`.
#### Produces
A `$tape`.
#### Source
```hoon
++ runt
|= [[a=@ b=@] c=tape]
^- tape
?: =(0 a)
c
[b $(a (dec a))]
```
#### Examples
```
> (runt [2 '/'] "ham")
"//ham"
```
```
> (runt [10 'a'] "")
"aaaaaaaaaa"
```
***
## `+sand`
Soft-cast by aura.
Check characters in `.b` are valid for aura `.a`. Produce a `+unit` of `.a` if valid and a null `+unit` if not. Takes `.a` and produces a gate that takes `.b`.
#### Accepts
`.a` is a `@ta`, and specifies the aura like `%tas` or `%ta`.
`.b` is an `$atom`.
#### Produces
A `(unit @)`.
#### Source
```hoon
++ sand
|= a=@ta
(flit (sane a))
```
#### Examples
```
> `(unit @ta)`((sand %ta) 'sym-som')
[~ ~.sym-som]
```
```
> `(unit @ta)`((sand %ta) 'err!')
~
```
***
## `+sane`
Check aura validity.
Check validity of `.a` by aura `.b`. Takes `.b` and produces a gate that takes `.a`.
#### Accepts
`.a` is a `@ta`, and specifies the aura like `%tas` or `%ta`.
`.b` is an `$atom`.
#### Produces
A `$flag`.
#### Source
```hoon
++ sane
|= a=@ta
|= b=@ ^- ?
?. =(%t (end 3 a))
:: XX more and better sanity
::
&
=+ [inx=0 len=(met 3 b)]
?: =(%tas a)
|- ^- ?
?: =(inx len) &
=+ cur=(cut 3 [inx 1] b)
?& ?| &((gte cur 'a') (lte cur 'z'))
&(=('-' cur) !=(0 inx) !=(len inx))
&(&((gte cur '0') (lte cur '9')) !=(0 inx))
==
$(inx +(inx))
==
?: =(%ta a)
|- ^- ?
?: =(inx len) &
=+ cur=(cut 3 [inx 1] b)
?& ?| &((gte cur 'a') (lte cur 'z'))
&((gte cur '0') (lte cur '9'))
|(=('-' cur) =('~' cur) =('_' cur) =('.' cur))
==
$(inx +(inx))
==
|- ^- ?
?: =(0 b) &
=+ cur=(end 3 b)
?: &((lth cur 32) !=(10 cur)) |
=+ len=(teff cur)
?& |(=(1 len) =+(i=1 |-(|(=(i len) &((gte (cut 3 [i 1] b) 128) $(i +(i)))))))
$(b (rsh [3 len] b))
==
```
#### Examples
```
> ((sane %tas) %mol)
%.y
```
```
> ((sane %tas) 'lam')
%.y
```
```
> ((sane %tas) 'more ace')
%.n
```
***
## `+taft`
UTF-8 to UTF-32.
Convert `$cord` `.a` to a UTF-32 `@c`.
#### Accepts
`.a` is a `@t`.
#### Produces
A `@c`.
#### Source
```hoon
++ taft
|= a=@t
^- @c
%+ rap 5
|- ^- (list @c)
=+ b=(teff a)
?: =(0 b) ~
=+ ^= c
%+ can 0
%+ turn
^- (list [p=@ q=@])
?+ b !!
%1 [[0 7] ~]
%2 [[8 6] [0 5] ~]
%3 [[16 6] [8 6] [0 4] ~]
%4 [[24 6] [16 6] [8 6] [0 3] ~]
==
|=([p=@ q=@] [q (cut 0 [p q] a)])
?> =((tuft c) (end [3 b] a))
[c $(a (rsh [3 b] a))]
```
#### Examples
```
> (taft 'foobar')
~-foobar
```
```
> `@ux`'foobar'
0x7261.626f.6f66
```
```
> `@ux`~-foobar
0x72.0000.0061.0000.0062.0000.006f.0000.006f.0000.0066
```
***
## `+teff`
UTF-8 Length.
Produces the number of utf8 bytes of `.a`, a single `@t` character. If `.a` contains more than one character, it will produce the byte-length of the first one.
#### Accepts
`.a` is a `@t`.
#### Produces
An `$atom`.
#### Source
```hoon
++ teff
|= a=@t ^- @
=+ b=(end 3 a)
?: =(0 b)
?>(=(`@`0 a) 0)
?> |((gte b 32) =(10 b))
?:((lte b 127) 1 ?:((lte b 223) 2 ?:((lte b 239) 3 4)))
```
#### Examples
```
> (teff 'a')
1
```
```
> (teff 'ß')
2
```
```
> (teff 'aß')
1
```
***
## `+trim`
Tape split.
Split first `.a` characters off `$tape` `.b`.
#### Accepts
`.a` is an `$atom`.
`.b` is a `$tape`.
#### Produces
A cell of `$tape`s, `.p` and `.q`.
#### Source
```hoon
++ trim
|= [a=@ b=tape]
^- [p=tape q=tape]
?~ b
[~ ~]
?: =(0 a)
[~ b]
=+ c=$(a (dec a), b t.b)
[[i.b p.c] q.c]
```
#### Examples
```
> (trim 5 "lasok termun")
[p="lasok" q=" termun"]
```
```
> (trim 5 "zam")
[p="zam" q=""]
```
***
## `+trip`
Cord to tape.
Produce a `$tape` from `$cord` `.a`.
#### Accepts
`.a` is an `$atom`.
#### Produces
A `$tape`.
#### Source
```hoon
++ trip
~/ %trip
|= a=@ ^- tape
?: =(0 (met 3 a))
~
[^-(@ta (end 3 a)) $(a (rsh 3 a))]
```
#### Examples
```
> (trip 'john doe')
"john doe"
```
```
> (trip 'abc 123 !@#')
"abc 123 !@#"
```
```
> (trip 'abc')
"abc"
```
***
## `+tuba`
UTF-8 tape to UTF-32 tape.
Convert `$tape` to a `+list` of codepoints (`@c`).
#### Accepts
`.a` is a `$tape`.
#### Produces
A `(list @c)`.
#### Source
```hoon
++ tuba
|= a=tape
^- (list @c)
(rip 5 (taft (rap 3 a)))
```
#### Examples
```
> (tuba "я тут")
~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.]
```
```
> (tuba "chars")
~[~-c ~-h ~-a ~-r ~-s]
```
***
## `+tufa`
UTF-32 to UTF-8 tape.
Wrap a `+list` of UTF-32 codepoints into a UTF-8 `$tape`.
#### Accepts
`.a` is a `(list @c)`.
#### Produces
A `$tape`.
#### Source
```hoon
++ tufa
|= a=(list @c)
^- tape
?~ a ""
(weld (rip 3 (tuft i.a)) $(a t.a))
```
#### Examples
```
> (tufa ~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.])
"я тут"
```
```
> (tufa ((list @c) ~[%a %b 0xb1 %c]))
"ab±c"
```
***
## `+tuft`
UTF-32 to UTF-8.
Convert `@c` to `$cord`.
#### Accepts
`.a` is a `@c`.
#### Produces
A `$cord`.
#### Source
```hoon
++ tuft
|= a=@c
^- @t
%+ rap 3
|- ^- (list @)
?: =(`@`0 a)
~
=+ b=(end 5 a)
=+ c=$(a (rsh 5 a))
?: (lte b 0x7f)
[b c]
?: (lte b 0x7ff)
:* (mix 0b1100.0000 (cut 0 [6 5] b))
(mix 0b1000.0000 (end [0 6] b))
c
==
?: (lte b 0xffff)
:* (mix 0b1110.0000 (cut 0 [12 4] b))
(mix 0b1000.0000 (cut 0 [6 6] b))
(mix 0b1000.0000 (end [0 6] b))
c
==
:* (mix 0b1111.0000 (cut 0 [18 3] b))
(mix 0b1000.0000 (cut 0 [12 6] b))
(mix 0b1000.0000 (cut 0 [6 6] b))
(mix 0b1000.0000 (end [0 6] b))
c
==
```
#### Examples
```
> (tuft ~-foobar)
'foobar'
```
```
> `@ux`~-foobar
0x72.0000.0061.0000.0062.0000.006f.0000.006f.0000.0066
```
```
> `@ux`'foobar'
0x7261.626f.6f66
```
***
## `+wack`
Knot escape.
Escape `$knot` `~` as `~~` and `_` as `~-`. Used for printing.
#### Accepts
`.a` is a `$knot`.
#### Produces
A `$knot`.
#### Source
```hoon
++ wack
|= a=@ta
^- @ta
=+ b=(rip 3 a)
%+ rap 3
|- ^- tape
?~ b
~
?: =('~' i.b) ['~' '~' $(b t.b)]
?: =('_' i.b) ['~' '-' $(b t.b)]
[i.b $(b t.b)]
```
#### Examples
```
> (wack '~20_sam~')
~.~~20~-sam~~
```
```
> `@t`(wack '~20_sam~')
'~~20~-sam~~'
```
***
## `+wick`
Knot unescape.
Unescape `$knot` `~~` as `~` and `~-` as `_`. Produces a `+unit`, which is null if the `$knot` contains unescaped `~` characters.
#### Accepts
`.a` is a an `$atom`.
#### Produces
A `(unit @ta)`.
#### Source
```hoon
++ wick
|= a=@
^- (unit @ta)
=+ b=(rip 3 a)
=- ?^(b ~ (some (rap 3 (flop c))))
=| c=tape
|- ^- [b=tape c=tape]
?~ b [~ c]
?. =('~' i.b)
$(b t.b, c [i.b c])
?~ t.b [b ~]
?- i.t.b
%'~' $(b t.t.b, c ['~' c])
%'-' $(b t.t.b, c ['_' c])
@ [b ~]
==
```
#### Examples
```
> (wick ~.~~20~-sam~~)
[~ ~.~20_sam~]
```
```
> (wick ~.~20~-sam~~)
~
```
***
## `+woad`
Unescape cord.
Unescape `$knot`-encoded `$cord`.
#### Accepts
`.a` is a `@ta`.
#### Produces
A `$cord`.
#### Source
```hoon
++ woad
|= a=@ta
^- @t
%+ rap 3
|- ^- (list @)
?: =(`@`0 a)
~
=+ b=(end 3 a)
=+ c=(rsh 3 a)
?: =('.' b)
[' ' $(a c)]
?. =('~' b)
[b $(a c)]
=> .(b (end 3 c), c (rsh 3 c))
?+ b =- (weld (rip 3 (tuft p.d)) $(a q.d))
^= d
=+ d=0
|- ^- [p=@ q=@]
?: =('.' b)
[d c]
?< =(0 c)
%= $
b (end 3 c)
c (rsh 3 c)
d %+ add (mul 16 d)
%+ sub b
?: &((gte b '0') (lte b '9')) 48
?>(&((gte b 'a') (lte b 'z')) 87)
==
%'.' ['.' $(a c)]
%'~' ['~' $(a c)]
==
```
#### Examples
```
> (woad ~.foo.bar~21.)
'foo bar!'
```
***
## `+wood`
Escape cord.
Escape `$cord` `.a` so it can be encoded in a `$knot`.
#### Accepts
`.a` is a `$cord`.
#### Produces
A `$knot`.
#### Source
```hoon
++ wood
|= a=@t
^- @ta
%+ rap 3
|- ^- (list @)
?: =(`@`0 a)
~
=+ b=(teff a)
=+ c=(taft (end [3 b] a))
=+ d=$(a (rsh [3 b] a))
?: ?| &((gte c 'a') (lte c 'z'))
&((gte c '0') (lte c '9'))
=(`@`'-' c)
==
[c d]
?+ c
:- '~'
=+ e=(met 2 c)
|- ^- tape
?: =(0 e)
['.' d]
=. e (dec e)
=+ f=(rsh [2 e] c)
[(add ?:((lte f 9) 48 87) f) $(c (end [2 e] c))]
::
%' ' ['.' d]
%'.' ['~' '.' d]
%'~' ['~' '~' d]
==
```
#### Examples
```
> (wood 'foo bar!')
~.foo.bar~21.
```
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.urbit.org/hoon/stdlib/4b.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.