git.iko.soy/urbit.org
on 883cb21 help sign in
urbit.org/content/docs/hoon/reference/stdlib/4b.md
993 lines 16 kB history raw
1+++
2title = "4b: Text Processing"
3weight = 29
4template = "doc.html"
5+++
7## `++at`
9```hoon
10 ++ at
11 |_ a=@
12```
14XX document
16### `++r:at`
18```hoon
19 ++ r
20 ?: ?& (gte (met 3 a) 2)
21 |-
22 ?: =(0 a)
23 &
24 =+ vis=(end 3 1 a)
25 ?& ?|(=('-' vis) ?&((gte vis 'a') (lte vis 'z')))
26 $(a (rsh 3 1 a))
27 ==
28 ==
29 rtam
30 ?: (lte (met 3 a) 2)
31 rud
32 rux
33```
35XX document
37### `++rf:at`
39```hoon
40 ++ rf `tape`[?-(a $& '&', $| '|', * !!) ~]
41```
43XX document
45### `++rn:at`
47```hoon
48 ++ rn `tape`[?>(=(0 a) '~') ~]
49```
51XX document
53### `++rt:at`
55```hoon
56 ++ rt `tape`['\'' (weld (mesc (trip a)) `tape`['\'' ~])]
57```
59XX document
61### `++rta:at`
63```hoon
64 ++ rta rt
65```
67XX document
69### `++rtam:at`
71```hoon
72 ++ rtam `tape`['%' (trip a)]
73```
75XX document
77### `++rub:at`
79```hoon
80 ++ rub `tape`['0' 'b' (rum 2 ~ |=(b/@ (add '0' b)))]
81```
83XX document
85### `++rud:at`
87```hoon
88 ++ rud (rum 10 ~ |=(b/@ (add '0' b)))
89```
91XX document
93### `++rum:at`
95```hoon
96 ++ rum
97 |= {b/@ c/tape d/$-(@ @)}
98 ^- tape
99 ?: =(0 a)
100 [(d 0) c]
101 =+ e=0
102 |- ^- tape
103 ?: =(0 a)
104 c
105 =+ f=&(!=(0 e) =(0 (mod e ?:(=(10 b) 3 4))))
106 %= $
107 a (div a b)
108 c [(d (mod a b)) ?:(f [?:(=(10 b) ',' '-') c] c)]
109 e +(e)
110 ==
111 ::
112```
114XX document
116### `++rup:at`
118```hoon
119 ++ rup
120 =+ b=(met 3 a)
121 ^- tape
122 :- '-'
123 |- ^- tape
124 ?: (gth (met 5 a) 1)
125 %+ weld
126 $(a (rsh 5 1 a), b (sub b 4))
127 `tape`['-' '-' $(a (end 5 1 a), b 4)]
128 ?: =(0 b)
129 ['~' ~]
130 ?: (lte b 1)
131 (trip (tos:po a))
132 |- ^- tape
133 ?: =(2 b)
134 =+ c=(rsh 3 1 a)
135 =+ d=(end 3 1 a)
136 (weld (trip (tod:po c)) (trip (tos:po (mix c d))))
137 =+ c=(rsh 3 2 a)
138 =+ d=(end 3 2 a)
139 (weld ^$(a c, b (met 3 c)) `tape`['-' $(a (mix c d), b 2)])
140 ::
141```
143XX document
145### `++ruv:at`
147```hoon
148 ++ ruv
149 ^- tape
150 :+ '0'
151 'v'
152 %^ rum
153 64
154 ~
155 |= b/@
156 ?: =(63 b)
157 '+'
158 ?: =(62 b)
159 '-'
160 ?:((lth b 26) (add 65 b) ?:((lth b 52) (add 71 b) (sub b 4)))
161 ::
162```
164XX document
166### `++rux:at`
168```hoon
169 ++ rux `tape`['0' 'x' (rum 16 ~ |=(b/@ (add b ?:((lth b 10) 48 87))))]
170 --
171 :::::::::::::::::::::::::::::::::::::::::::::::::::::: ::
172```
174XX document
176---
178---
180## `++cass`
182To lowercase
184Turn all occurences of uppercase letters in any `++tape` into lowercase
185letters. Returns a `++tape`.
187#### Accepts
189`vib` is a `++tape`.
191#### Produces
193A `++tape`.
195#### Source
197```hoon
198 ++ cass :: lowercase
199 |= vib/tape
200 ^- tape
201 (turn vib |=(a/@ ?.(&((gte a 'A') (lte a 'Z')) a (add 32 a))))
202```
204#### Examples
206```
207 > (cass "JOHN DOE")
208 "john doe"
210 > (cass "abc ABC 123 !@#")
211 "abc abc 123 !@#"
213 > (cass "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
214 "aabbccddeeffgghhiijjkkllmmnnooppqqrrssqqrrvvwwxxyyzz"
215```
217---
219## `++crip`
221Tape to cord
223Produce a `++cord` from a `++tape`.
225#### Accepts
227`a` is a `++tape`.
229#### Produces
231A `++cord`.
233#### Source
235```hoon
236 ++ crip |=(a=tape `@t`(rap 3 a)) :: tape to cord
237```
239#### Examples
241```
242 > (crip "john doe")
243 'john doe'
245 > (crip "abc 123 !@#")
246 'abc 123 !@#'
248 > `@ud`(crip "abc")
249 6.513.249
250```
252---
254## `++cuss`
256To uppercase
258Turn all occurences of lowercase letters in any `++tape` into uppercase
259letters. Returns a `++tape`.
261#### Accepts
263`vib` is a `++tape`.
265#### Produces
267A `++tape`.
269#### Source
271```hoon
272 ++ cuss :: uppercase
273 |= vib/tape
274 ^- tape
275 (turn vib |=(a/@ ?.(&((gte a 'a') (lte a 'z')) a (sub a 32))))
276```
278#### Examples
280```
281 > (cuss "john doe")
282 "JOHN DOE"
284 > (cuss "abc ABC 123 !@#")
285 "ABC ABC 123 !@#"
287 > (cuss "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
288 "AABBCCDDEEFFGGHHIIJJKKLLMMNNOOPPQQRRSSQQRRVVWWXXYYZZ"
289```
291---
293## `++mesc`
295Escape special chars
297Escape special characters, used in `++show`.
299#### Accepts
301`vib` is a `++tape`.
303#### Produces
305A `++tape`.
307#### Source
309```hoon
310 ++ mesc :: ctrl code escape
311 |= vib/tape
312 ^- tape
313 ?~ vib
314 ~
315 ?: =('\\' i.vib)
316 ['\\' '\\' $(vib t.vib)]
317 ?: ?|((gth i.vib 126) (lth i.vib 32) =(`@`39 i.vib))
318 ['\\' (welp ~(rux at i.vib) '/' $(vib t.vib))]
319 [i.vib $(vib t.vib)]
320```
322#### Examples
324```
325 > (mesc "ham lus")
326 "ham lus"
327 > (mesc "bas\\hur")
328 "bas\\\\hur"
329 > (mesc "as'saß")
330 "as\0x27/sa\0xc3/\0x9f/"
331```
333---
335## `++runt`
337Prepend `n` times
339Add `a` repetitions of character `b` to the head of `++tape` `c`.
341#### Accepts
343`a` and `b` are atoms.
345`c` is a `++tape`.
347#### Produces
349A `++tape`.
351#### Source
353```hoon
354 ++ runt :: prepend repeatedly
355 |= [[a/@ b/@] c/tape]
356 ^- tape
357 ?: =(0 a)
358 c
359 [b $(a (dec a))]
360 ::
361```
363#### Examples
365```
366 > (runt [2 '/'] "ham")
367 "//ham"
368 > (runt [10 'a'] "")
369 "aaaaaaaaaa"
370```
372---
374## `++sand`
376Soft-cast by aura
378Soft-cast validity by aura.
380#### Accepts
382`a` is a `++span` (`@ta`).
384`b` is an atom.
386#### Produces
388A `(unit @)`.
390#### Source
392```hoon
393 ++ sand :: atom sanity
394 |= a/@ta
395 |= b/@ ^- (unit @)
396 ?.(((sane a) b) ~ [~ b])
397 ::
398```
400#### Examples
402```
403 > `(unit @ta)`((sand %ta) 'sym-som')
404 [~ ~.sym-som]
405 > `(unit @ta)`((sand %ta) 'err!')
406 ~
407```
409---
411## `++sane`
413Check aura validity
415Check validity by aura. Produces a gate.
417#### Accepts
419`a` is a `++span` (`@ta`).
421`b` is an atom.
423#### Produces
425A boolean.
427#### Source
429```hoon
430 ++ sane :: atom sanity
431 |= a/@ta
432 |= b/@ ^- ?
433 ?. =(%t (end 3 1 a))
434 ~|(%sane-stub !!)
435 =+ [inx=0 len=(met 3 b)]
436 ?: =(%tas a)
437 |- ^- ?
438 ?: =(inx len) &
439 =+ cur=(cut 3 [inx 1] b)
440 ?& ?| &((gte cur 'a') (lte cur 'z'))
441 &(=('-' cur) !=(0 inx) !=(len inx))
442 &(&((gte cur '0') (lte cur '9')) !=(0 inx))
443 ==
444 $(inx +(inx))
445 ==
446 ?: =(%ta a)
447 |- ^- ?
448 ?: =(inx len) &
449 =+ cur=(cut 3 [inx 1] b)
450 ?& ?| &((gte cur 'a') (lte cur 'z'))
451 &((gte cur '0') (lte cur '9'))
452 |(=('-' cur) =('~' cur) =('_' cur) =('.' cur))
453 ==
454 $(inx +(inx))
455 ==
456 |- ^- ?
457 ?: =(0 b) &
458 =+ cur=(end 3 1 b)
459 ?: &((lth cur 32) !=(10 cur)) |
460 =+ len=(teff cur)
461 ?& |(=(1 len) =+(i=1 |-(|(=(i len) &((gte (cut 3 [i 1] b) 128) $(i +(i)))))))
462 $(b (rsh 3 len b))
463 ==
464 ::
465```
467#### Examples
469```
470 > ((sane %tas) %mol)
471 %.y
472 > ((sane %tas) 'lam')
473 %.y
474 > ((sane %tas) 'more ace')
475 %.n
476```
478---
480## `++teff`
482UTF8 Length
484Produces the number of utf8 bytes.
486#### Accepts
488`a` is a `@t`.
490#### Produces
492An atom.
494#### Source
496```hoon
497 |= a/@t ^- @
498 =+ b=(end 3 1 a)
499 ~| %bad-utf8
500 ?: =(0 b)
501 ?>(=(`@`0 a) 0)
502 ?> |((gte b 32) =(10 b))
503 ?:((lte b 127) 1 ?:((lte b 223) 2 ?:((lte b 239) 3 4)))
504```
506#### Examples
508```
509 > (teff 'a')
510 1
511 > (teff 'ß')
512 2
513```
515---
517## `++trim`
519Tape split
521Split first `a` characters off `++tape` `b`.
523#### Accepts
525`a` is an atom.
527`b` is a `++tape`.
529#### Produces
531A cell of `++tape`s, `p` and `q`.
533#### Source
535```hoon
536 ++ trim :: 31-bit nonzero
537 |= key/@
538 =+ syd=0xcafe.babe
539 |- ^- @
540 =+ haz=(spec syd key)
541 =+ ham=(mix (rsh 0 31 haz) (end 0 31 haz))
542 ?.(=(0 ham) ham $(syd +(syd)))
543 --
544 ::
545```
547#### Examples
549```
550 > (trim 5 "lasok termun")
551 [p="lasok" q=" termun"]
552 > (trim 5 "zam")
553 [p="zam" q=""]
554```
556---
558## `++trip`
560Cord to tape
562Produce a `++tape` from `++cord`.
564#### Accepts
566`a` is an atom.
568#### Produces
570A `++tape`.
572#### Source
574```hoon
575 ++ trip :: cord to tape
576 ~/ %trip
577 |= a/@ ^- tape
578 ?: =(0 (met 3 a))
579 ~
580 [^-(@ta (end 3 1 a)) $(a (rsh 3 1 a))]
581 ::
582```
584#### Examples
586```
587 > (trip 'john doe')
588 "john doe"
589 > (trip 'abc 123 !@#')
590 "abc 123 !@#"
591 > (trip 'abc')
592 "abc"
593```
595---
597## `++tuba`
599UTF8 to UTF32 tape
601Convert `++tape` to a `++list` of codepoints (`@c`).
603#### Accepts
605`a` is a `++tape`.
607#### Produces
609A `++list` of codepoints `@c`.
611#### Source
613```hoon
614 ++ tuba :: utf8 to utf32 tape
615 |= a/tape
616 ^- (list @c)
617 (rip 5 (turf (rap 3 a))) :: XX horrible
618 ::
619```
621#### Examples
623```
624 > (tuba "я тут")
625 ~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.]
626 > (tuba "chars")
627 ~[~-c ~-h ~-a ~-r ~-s]
628```
630---
632## `++tufa`
634UTF32 to UTF8 tape
636Wrap a `++list` of utf32 codepoints into a utf8 `++tape`.
638#### Accepts
640`a` is a `++list` of `@c`.
642#### Produces
644A `++tape`.
646#### Source
648```hoon
649 ++ tufa :: utf32 to utf8 tape
650 |= a=(list @c)
651 ^- tape
652 ?~ a ""
653 (weld (rip 3 (tuft i.a)) $(a t.a))
654 ::
655```
657#### Examples
659```hoon
660 > (tufa ~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.])
661 "я тут"
662 > (tufa ((list @c) ~[%a %b 0xb1 %c]))
663 "ab±c"
664```
666---
668## `++tuft`
670UTF32 to UTF8 text
672Convert utf32 glyph to
673LSB utf8 `++cord`.
675#### Accepts
677`a` is a codepoint (`@c`).
679#### Produces
681A `++cord`.
683#### Source
685```hoon
686 ++ tuft :: utf32 to utf8 text
687 |= a/@c
688 ^- @t
689 %+ rap 3
690 |- ^- (list @)
691 ?: =(`@`0 a)
692 ~
693 =+ b=(end 5 1 a)
694 =+ c=$(a (rsh 5 1 a))
695 ?: (lte b 0x7f)
696 [b c]
697 ?: (lte b 0x7ff)
698 :* (mix 0b1100.0000 (cut 0 [6 5] b))
699 (mix 0b1000.0000 (end 0 6 b))
700 c
701 ==
702 ?: (lte b 0xffff)
703 :* (mix 0b1110.0000 (cut 0 [12 4] b))
704 (mix 0b1000.0000 (cut 0 [6 6] b))
705 (mix 0b1000.0000 (end 0 6 b))
706 c
707 ==
708 :* (mix 0b1111.0000 (cut 0 [18 3] b))
709 (mix 0b1000.0000 (cut 0 [12 6] b))
710 (mix 0b1000.0000 (cut 0 [6 6] b))
711 (mix 0b1000.0000 (end 0 6 b))
712 c
713 ==
714```
716#### Examples
718```
719 > (tuft `@c`%a)
720 'a'
721 > (tuft `@c`0xb6)
722 '¶'
723```
725---
727## `++turf`
729UTF8 to UTF32 cord
731Convert utf8 (`++cord`) to utf32 codepoints.
733#### Accepts
735`a` is a `@t`.
737#### Produces
739A `@c`, UTF-32 codepoint.
741#### Source
743```hoon
744 ++ turf :: utf8 to utf32
745 |= a/@t
746 ^- @c
747 %+ rap 5
748 |- ^- (list @c)
749 =+ b=(teff a)
750 ?: =(0 b) ~
751 =+ ^= c
752 %+ can 0
753 %+ turn
754 ^- (list {p/@ q/@})
755 ?+ b !!
756 $1 [[0 7] ~]
757 $2 [[8 6] [0 5] ~]
758 $3 [[16 6] [8 6] [0 4] ~]
759 $4 [[24 6] [16 6] [8 6] [0 3] ~]
760 ==
761 |=({p/@ q/@} [q (cut 0 [p q] a)])
762 ?. =((tuft c) (end 3 b a)) ~|(%bad-utf8 !!)
763 [c $(a (rsh 3 b a))]
764 ::
765```
767#### Examples
769```
770 > (turf 'my ßam')
771 ~-my.~df.am
772 > 'я тут'
773 'я тут'
774 > (turf 'я тут')
775 ~-~44f..~442.~443.~442.
776 > `@ux`'я тут'
777 0x82.d183.d182.d120.8fd1
778 > `@ux`(turf 'я тут')
779 0x442.0000.0443.0000.0442.0000.0020.0000.044f
780```
782---
784## `++wack`
786Coin format encode
788Escape `++span` `~` as `~~` and `_` as `~-`. Used for printing.
790#### Accepts
792`a` is a `++span` (`@ta`).
794#### Produces
796A `++span` (`@ta`).
798#### Source
800```hoon
801 ++ wack :: coin format
802 |= a/@ta
803 ^- @ta
804 =+ b=(rip 3 a)
805 %+ rap 3
806 |- ^- tape
807 ?~ b
808 ~
809 ?: =('~' i.b) ['~' '~' $(b t.b)]
810 ?: =('_' i.b) ['~' '-' $(b t.b)]
811 [i.b $(b t.b)]
812 ::
813```
815#### Examples
817```
818 > (wack '~20_sam~')
819 ~.~~20~-sam~~
821 > `@t`(wack '~20_sam~')
822 '~~20~-sam~~'
824 > ~(rend co %many ~[`ud/5 `ta/'~20_sam'])
825 "._5_~~.~~20~-sam__"
827 > ._5_~~.~~20~-sam__
828 [5 ~.~20_sam]
829```
831---
833## `++wick`
835Coin format decode
837Unescape `++span` `~~` as `~` and `~-` as `_`.
839#### Accepts
841`a` is a an atom.
843#### Produces
845A `++span` `@ta`.
847#### Source
849```hoon
850 ++ wick :: knot format
851 |= a/@
852 ^- (unit @ta)
853 =+ b=(rip 3 a)
854 =- ?^(b ~ (some (rap 3 (flop c))))
855 =| c/tape
856 |- ^- {b/tape c/tape}
857 ?~ b [~ c]
858 ?. =('~' i.b)
859 $(b t.b, c [i.b c])
860 ?~ t.b [b ~]
861 ?- i.t.b
862 $'~' $(b t.t.b, c ['~' c])
863 $'-' $(b t.t.b, c ['_' c])
864 @ [b ~]
865 ==
866 ::
867```
869#### Examples
871```
872 > `@t`(wick '~-ams~~lop')
873 '_ams~lop'
875 > `@t`(wick (wack '~20_sam~'))
876 '~20_sam~'
877```
879---
881## `++woad`
883Unescape cord
885Unescape `++cord` codepoints.
887#### Accepts
889`a` is a `@ta`.
891#### Produces
893A `++cord`.
895#### Source
897```hoon
898 ++ woad :: cord format
899 |= a/@ta
900 ^- @t
901 %+ rap 3
902 |- ^- (list @)
903 ?: =(`@`0 a)
904 ~
905 =+ b=(end 3 1 a)
906 =+ c=(rsh 3 1 a)
907 ?: =('.' b)
908 [' ' $(a c)]
909 ?. =('~' b)
910 [b $(a c)]
911 => .(b (end 3 1 c), c (rsh 3 1 c))
912 ?+ b =- (weld (rip 3 (tuft p.d)) $(a q.d))
913 ^= d
914 =+ d=0
915 |- ^- {p/@ q/@}
916 ?: =('.' b)
917 [d c]
918 ?< =(0 c)
919 %= $
920 b (end 3 1 c)
921 c (rsh 3 1 c)
922 d %+ add (mul 16 d)
923 %+ sub b
924 ?: &((gte b '0') (lte b '9')) 48
925 ?>(&((gte b 'a') (lte b 'z')) 87)
926 ==
927 $'.' ['.' $(a c)]
928 $'~' ['~' $(a c)]
929 ==
930 ::
931```
933#### Examples
935```
936 > (woad ~.~b6.20.as)
937 '¶20 as'
938```
940---
942## `++wood`
944Escape cord
946Escape `++cord` codepoints.
948#### Accepts
950`a` is a `++span` (`@ta`).
952#### Produces
954A `++span` (`@ta`).
956#### Source
958```hoon
959 ++ wood :: cord format
960 |= a/@t
961 ^- @ta
962 %+ rap 3
963 |- ^- (list @)
964 ?: =(`@`0 a)
965 ~
966 =+ b=(teff a)
967 =+ c=(turf (end 3 b a))
968 =+ d=$(a (rsh 3 b a))
969 ?: ?| &((gte c 'a') (lte c 'z'))
970 &((gte c '0') (lte c '9'))
971 =(`@`'-' c)
972 ==
973 [c d]
974 ?+ c
975 :- '~'
976 =+ e=(met 2 c)
977 |- ^- tape
978 ?: =(0 e)
979 ['.' d]
980 =. e (dec e)
981 =+ f=(rsh 2 e c)
982 [(add ?:((lte f 9) 48 87) f) $(c (end 2 e c))]
983 ::
984```
986#### Examples
988```
989 > (wood 'my ßam')
990 ~.my.~df.am
991```
993---