git.iko.soy/urbit.org
on cb112e8 help sign in
urbit.org/content/docs/hoon/reference/stdlib/4b.md
994 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
18### `++r:at`
20```hoon
21 ++ r
22 ?: ?& (gte (met 3 a) 2)
23 |-
24 ?: =(0 a)
25 &
26 =+ vis=(end 3 1 a)
27 ?& ?|(=('-' vis) ?&((gte vis 'a') (lte vis 'z')))
28 $(a (rsh 3 1 a))
29 ==
30 ==
31 rtam
32 ?: (lte (met 3 a) 2)
33 rud
34 rux
35```
38XX document
40### `++rf:at`
42```hoon
43 ++ rf `tape`[?-(a $& '&', $| '|', * !!) ~]
44```
47XX document
49### `++rn:at`
51```hoon
52 ++ rn `tape`[?>(=(0 a) '~') ~]
53```
55XX document
57### `++rt:at`
59```hoon
60 ++ rt `tape`['\'' (weld (mesc (trip a)) `tape`['\'' ~])]
61```
63XX document
65### `++rta:at`
67```hoon
68 ++ rta rt
69```
71XX document
73### `++rtam:at`
75```hoon
76 ++ rtam `tape`['%' (trip a)]
77```
79XX document
81### `++rub:at`
83```hoon
84 ++ rub `tape`['0' 'b' (rum 2 ~ |=(b/@ (add '0' b)))]
85```
87XX document
89### `++rud:at`
91```hoon
92 ++ rud (rum 10 ~ |=(b/@ (add '0' b)))
93```
95XX document
97### `++rum:at`
99```hoon
100 ++ rum
101 |= {b/@ c/tape d/$-(@ @)}
102 ^- tape
103 ?: =(0 a)
104 [(d 0) c]
105 =+ e=0
106 |- ^- tape
107 ?: =(0 a)
108 c
109 =+ f=&(!=(0 e) =(0 (mod e ?:(=(10 b) 3 4))))
110 %= $
111 a (div a b)
112 c [(d (mod a b)) ?:(f [?:(=(10 b) ',' '-') c] c)]
113 e +(e)
114 ==
115 ::
116```
118XX document
120### `++rup:at`
122```hoon
123 ++ rup
124 =+ b=(met 3 a)
125 ^- tape
126 :- '-'
127 |- ^- tape
128 ?: (gth (met 5 a) 1)
129 %+ weld
130 $(a (rsh 5 1 a), b (sub b 4))
131 `tape`['-' '-' $(a (end 5 1 a), b 4)]
132 ?: =(0 b)
133 ['~' ~]
134 ?: (lte b 1)
135 (trip (tos:po a))
136 |- ^- tape
137 ?: =(2 b)
138 =+ c=(rsh 3 1 a)
139 =+ d=(end 3 1 a)
140 (weld (trip (tod:po c)) (trip (tos:po (mix c d))))
141 =+ c=(rsh 3 2 a)
142 =+ d=(end 3 2 a)
143 (weld ^$(a c, b (met 3 c)) `tape`['-' $(a (mix c d), b 2)])
144 ::
145```
147XX document
149### `++ruv:at`
151```hoon
152 ++ ruv
153 ^- tape
154 :+ '0'
155 'v'
156 %^ rum
157 64
158 ~
159 |= b/@
160 ?: =(63 b)
161 '+'
162 ?: =(62 b)
163 '-'
164 ?:((lth b 26) (add 65 b) ?:((lth b 52) (add 71 b) (sub b 4)))
165 ::
166```
168XX document
170### `++rux:at`
172```hoon
173 ++ rux `tape`['0' 'x' (rum 16 ~ |=(b/@ (add b ?:((lth b 10) 48 87))))]
174 --
175 :::::::::::::::::::::::::::::::::::::::::::::::::::::: ::
176```
178XX document
180---
183---
185### `++cass`
187To lowercase
189Turn all occurences of uppercase letters in any `++tape` into lowercase
190letters. Returns a `++tape`.
192#### Accepts
194`vib` is a `++tape`.
196#### Produces
198A `++tape`.
200#### Source
202```hoon
203 ++ cass :: lowercase
204 |= vib/tape
205 ^- tape
206 (turn vib |=(a/@ ?.(&((gte a 'A') (lte a 'Z')) a (add 32 a))))
207```
209#### Examples
211```
212 > (cass "JOHN DOE")
213 "john doe"
215 > (cass "abc ABC 123 !@#")
216 "abc abc 123 !@#"
218 > (cass "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
219 "aabbccddeeffgghhiijjkkllmmnnooppqqrrssqqrrvvwwxxyyzz"
220```
222---
223### `++crip`
225Tape to cord
227Produce a `++cord` from a `++tape`.
229#### Accepts
231`a` is a `++tape`.
233#### Produces
235A `++cord`.
237#### Source
239```hoon
240 ++ crip |=(a=tape `@t`(rap 3 a)) :: tape to cord
241```
243#### Examples
245```
246 > (crip "john doe")
247 'john doe'
249 > (crip "abc 123 !@#")
250 'abc 123 !@#'
252 > `@ud`(crip "abc")
253 6.513.249
254```
256---
257### `++cuss`
259To uppercase
261Turn all occurences of lowercase letters in any `++tape` into uppercase
262letters. Returns a `++tape`.
264#### Accepts
266`vib` is a `++tape`.
268#### Produces
270A `++tape`.
272#### Source
274```hoon
275 ++ cuss :: uppercase
276 |= vib/tape
277 ^- tape
278 (turn vib |=(a/@ ?.(&((gte a 'a') (lte a 'z')) a (sub a 32))))
279```
281#### Examples
283```
284 > (cuss "john doe")
285 "JOHN DOE"
287 > (cuss "abc ABC 123 !@#")
288 "ABC ABC 123 !@#"
290 > (cuss "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsQqRrVvWwXxYyZz")
291 "AABBCCDDEEFFGGHHIIJJKKLLMMNNOOPPQQRRSSQQRRVVWWXXYYZZ"
292```
294---
295### `++mesc`
297Escape special chars
299Escape special characters, used in `++show`.
301#### Accepts
303`vib` is a `++tape`.
305#### Produces
307A `++tape`.
309#### Source
311```hoon
312 ++ mesc :: ctrl code escape
313 |= vib/tape
314 ^- tape
315 ?~ vib
316 ~
317 ?: =('\\' i.vib)
318 ['\\' '\\' $(vib t.vib)]
319 ?: ?|((gth i.vib 126) (lth i.vib 32) =(`@`39 i.vib))
320 ['\\' (welp ~(rux at i.vib) '/' $(vib t.vib))]
321 [i.vib $(vib t.vib)]
322```
324#### Examples
326```
327 > (mesc "ham lus")
328 "ham lus"
329 > (mesc "bas\\hur")
330 "bas\\\\hur"
331 > (mesc "as'saß")
332 "as\0x27/sa\0xc3/\0x9f/"
333```
336---
337### `++runt`
339Prepend `n` times
341Add `a` repetitions of character `b` to the head of `++tape` `c`.
343#### Accepts
345`a` and `b` are atoms.
347`c` is a `++tape`.
349#### Produces
351A `++tape`.
353#### Source
355```hoon
356 ++ runt :: prepend repeatedly
357 |= [[a/@ b/@] c/tape]
358 ^- tape
359 ?: =(0 a)
360 c
361 [b $(a (dec a))]
362 ::
363```
365#### Examples
367```
368 > (runt [2 '/'] "ham")
369 "//ham"
370 > (runt [10 'a'] "")
371 "aaaaaaaaaa"
372```
375---
376### `++sand`
378Soft-cast by aura
380Soft-cast validity by aura.
382#### Accepts
384`a` is a `++span` (`@ta`).
386`b` is an atom.
388#### Produces
390A `(unit @)`.
392#### Source
394```hoon
395 ++ sand :: atom sanity
396 |= a/@ta
397 |= b/@ ^- (unit @)
398 ?.(((sane a) b) ~ [~ b])
399 ::
400```
402#### Examples
404```
405 > `(unit @ta)`((sand %ta) 'sym-som')
406 [~ ~.sym-som]
407 > `(unit @ta)`((sand %ta) 'err!')
408 ~
409```
412---
413### `++sane`
415Check aura validity
417Check validity by aura. Produces a gate.
419#### Accepts
421`a` is a `++span` (`@ta`).
423`b` is an atom.
425#### Produces
427A boolean.
429#### Source
431```hoon
432 ++ sane :: atom sanity
433 |= a/@ta
434 |= b/@ ^- ?
435 ?. =(%t (end 3 1 a))
436 ~|(%sane-stub !!)
437 =+ [inx=0 len=(met 3 b)]
438 ?: =(%tas a)
439 |- ^- ?
440 ?: =(inx len) &
441 =+ cur=(cut 3 [inx 1] b)
442 ?& ?| &((gte cur 'a') (lte cur 'z'))
443 &(=('-' cur) !=(0 inx) !=(len inx))
444 &(&((gte cur '0') (lte cur '9')) !=(0 inx))
445 ==
446 $(inx +(inx))
447 ==
448 ?: =(%ta a)
449 |- ^- ?
450 ?: =(inx len) &
451 =+ cur=(cut 3 [inx 1] b)
452 ?& ?| &((gte cur 'a') (lte cur 'z'))
453 &((gte cur '0') (lte cur '9'))
454 |(=('-' cur) =('~' cur) =('_' cur) =('.' cur))
455 ==
456 $(inx +(inx))
457 ==
458 |- ^- ?
459 ?: =(0 b) &
460 =+ cur=(end 3 1 b)
461 ?: &((lth cur 32) !=(10 cur)) |
462 =+ len=(teff cur)
463 ?& |(=(1 len) =+(i=1 |-(|(=(i len) &((gte (cut 3 [i 1] b) 128) $(i +(i)))))))
464 $(b (rsh 3 len b))
465 ==
466 ::
467```
469#### Examples
471```
472 > ((sane %tas) %mol)
473 %.y
474 > ((sane %tas) 'lam')
475 %.y
476 > ((sane %tas) 'more ace')
477 %.n
478```
481---
482### `++teff`
484UTF8 Length
486Produces the number of utf8 bytes.
488#### Accepts
490`a` is a `@t`.
492#### Produces
494An atom.
496#### Source
498```hoon
499 |= a/@t ^- @
500 =+ b=(end 3 1 a)
501 ~| %bad-utf8
502 ?: =(0 b)
503 ?>(=(`@`0 a) 0)
504 ?> |((gte b 32) =(10 b))
505 ?:((lte b 127) 1 ?:((lte b 223) 2 ?:((lte b 239) 3 4)))
506```
508#### Examples
510```
511 > (teff 'a')
512 1
513 > (teff 'ß')
514 2
515```
518---
519### `++trim`
521Tape split
523Split first `a` characters off `++tape` `b`.
525#### Accepts
527`a` is an atom.
529`b` is a `++tape`.
531#### Produces
533A cell of `++tape`s, `p` and `q`.
535#### Source
537```hoon
538 ++ trim :: 31-bit nonzero
539 |= key/@
540 =+ syd=0xcafe.babe
541 |- ^- @
542 =+ haz=(spec syd key)
543 =+ ham=(mix (rsh 0 31 haz) (end 0 31 haz))
544 ?.(=(0 ham) ham $(syd +(syd)))
545 --
546 ::
547```
549#### Examples
551```
552 > (trim 5 "lasok termun")
553 [p="lasok" q=" termun"]
554 > (trim 5 "zam")
555 [p="zam" q=""]
556```
559---
560### `++trip`
562Cord to tape
564Produce a `++tape` from `++cord`.
566#### Accepts
568`a` is an atom.
570#### Produces
572A `++tape`.
574#### Source
576```hoon
577 ++ trip :: cord to tape
578 ~/ %trip
579 |= a/@ ^- tape
580 ?: =(0 (met 3 a))
581 ~
582 [^-(@ta (end 3 1 a)) $(a (rsh 3 1 a))]
583 ::
584```
586#### Examples
588```
589 > (trip 'john doe')
590 "john doe"
591 > (trip 'abc 123 !@#')
592 "abc 123 !@#"
593 > (trip 'abc')
594 "abc"
595```
598---
599### `++tuba`
601UTF8 to UTF32 tape
603Convert `++tape` to a `++list` of codepoints (`@c`).
605#### Accepts
607`a` is a `++tape`.
609#### Produces
611A `++list` of codepoints `@c`.
613#### Source
615```hoon
616 ++ tuba :: utf8 to utf32 tape
617 |= a/tape
618 ^- (list @c)
619 (rip 5 (turf (rap 3 a))) :: XX horrible
620 ::
621```
623#### Examples
625```
626 > (tuba "я тут")
627 ~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.]
628 > (tuba "chars")
629 ~[~-c ~-h ~-a ~-r ~-s]
630```
633---
634### `++tufa`
636UTF32 to UTF8 tape
638Wrap a `++list` of utf32 codepoints into a utf8 `++tape`.
640#### Accepts
642`a` is a `++list` of `@c`.
644#### Produces
646A `++tape`.
648#### Source
650```hoon
651 ++ tufa :: utf32 to utf8 tape
652 |= a=(list @c)
653 ^- tape
654 ?~ a ""
655 (weld (rip 3 (tuft i.a)) $(a t.a))
656 ::
657```
659#### Examples
661```hoon
662 > (tufa ~[~-~44f. ~-. ~-~442. ~-~443. ~-~442.])
663 "я тут"
664 > (tufa ((list @c) ~[%a %b 0xb1 %c]))
665 "ab±c"
666```
669---
670### `++tuft`
672UTF32 to UTF8 text
674Convert utf32 glyph to
675LSB utf8 `++cord`.
677#### Accepts
679`a` is a codepoint (`@c`).
681#### Produces
683A `++cord`.
685#### Source
687```hoon
688 ++ tuft :: utf32 to utf8 text
689 |= a/@c
690 ^- @t
691 %+ rap 3
692 |- ^- (list @)
693 ?: =(`@`0 a)
694 ~
695 =+ b=(end 5 1 a)
696 =+ c=$(a (rsh 5 1 a))
697 ?: (lte b 0x7f)
698 [b c]
699 ?: (lte b 0x7ff)
700 :* (mix 0b1100.0000 (cut 0 [6 5] b))
701 (mix 0b1000.0000 (end 0 6 b))
702 c
703 ==
704 ?: (lte b 0xffff)
705 :* (mix 0b1110.0000 (cut 0 [12 4] b))
706 (mix 0b1000.0000 (cut 0 [6 6] b))
707 (mix 0b1000.0000 (end 0 6 b))
708 c
709 ==
710 :* (mix 0b1111.0000 (cut 0 [18 3] b))
711 (mix 0b1000.0000 (cut 0 [12 6] b))
712 (mix 0b1000.0000 (cut 0 [6 6] b))
713 (mix 0b1000.0000 (end 0 6 b))
714 c
715 ==
716```
718#### Examples
720```
721 > (tuft `@c`%a)
722 'a'
723 > (tuft `@c`0xb6)
724 '¶'
725```
728---
729### `++turf`
731UTF8 to UTF32 cord
733Convert utf8 (`++cord`) to utf32 codepoints.
735#### Accepts
737`a` is a `@t`.
739#### Produces
741A `@c`, UTF-32 codepoint.
743#### Source
745```hoon
746 ++ turf :: utf8 to utf32
747 |= a/@t
748 ^- @c
749 %+ rap 5
750 |- ^- (list @c)
751 =+ b=(teff a)
752 ?: =(0 b) ~
753 =+ ^= c
754 %+ can 0
755 %+ turn
756 ^- (list {p/@ q/@})
757 ?+ b !!
758 $1 [[0 7] ~]
759 $2 [[8 6] [0 5] ~]
760 $3 [[16 6] [8 6] [0 4] ~]
761 $4 [[24 6] [16 6] [8 6] [0 3] ~]
762 ==
763 |=({p/@ q/@} [q (cut 0 [p q] a)])
764 ?. =((tuft c) (end 3 b a)) ~|(%bad-utf8 !!)
765 [c $(a (rsh 3 b a))]
766 ::
767```
769#### Examples
771```
772 > (turf 'my ßam')
773 ~-my.~df.am
774 > 'я тут'
775 'я тут'
776 > (turf 'я тут')
777 ~-~44f..~442.~443.~442.
778 > `@ux`'я тут'
779 0x82.d183.d182.d120.8fd1
780 > `@ux`(turf 'я тут')
781 0x442.0000.0443.0000.0442.0000.0020.0000.044f
782```
785---
786### `++wack`
788Coin format encode
790Escape `++span` `~` as `~~` and `_` as `~-`. Used for printing.
792#### Accepts
794`a` is a `++span` (`@ta`).
796#### Produces
798A `++span` (`@ta`).
800#### Source
802```hoon
803 ++ wack :: coin format
804 |= a/@ta
805 ^- @ta
806 =+ b=(rip 3 a)
807 %+ rap 3
808 |- ^- tape
809 ?~ b
810 ~
811 ?: =('~' i.b) ['~' '~' $(b t.b)]
812 ?: =('_' i.b) ['~' '-' $(b t.b)]
813 [i.b $(b t.b)]
814 ::
815```
817#### Examples
819```
820 > (wack '~20_sam~')
821 ~.~~20~-sam~~
823 > `@t`(wack '~20_sam~')
824 '~~20~-sam~~'
826 > ~(rend co %many ~[`ud/5 `ta/'~20_sam'])
827 "._5_~~.~~20~-sam__"
829 > ._5_~~.~~20~-sam__
830 [5 ~.~20_sam]
831```
833---
834### `++wick`
836Coin format decode
838Unescape `++span` `~~` as `~` and `~-` as `_`.
840#### Accepts
842`a` is a an atom.
844#### Produces
846A `++span` `@ta`.
848#### Source
850```hoon
851 ++ wick :: knot format
852 |= a/@
853 ^- (unit @ta)
854 =+ b=(rip 3 a)
855 =- ?^(b ~ (some (rap 3 (flop c))))
856 =| c/tape
857 |- ^- {b/tape c/tape}
858 ?~ b [~ c]
859 ?. =('~' i.b)
860 $(b t.b, c [i.b c])
861 ?~ t.b [b ~]
862 ?- i.t.b
863 $'~' $(b t.t.b, c ['~' c])
864 $'-' $(b t.t.b, c ['_' c])
865 @ [b ~]
866 ==
867 ::
868```
870#### Examples
872```
873 > `@t`(wick '~-ams~~lop')
874 '_ams~lop'
876 > `@t`(wick (wack '~20_sam~'))
877 '~20_sam~'
878```
881---
882### `++woad`
884Unescape cord
886Unescape `++cord` codepoints.
888#### Accepts
890`a` is a `@ta`.
892#### Produces
894A `++cord`.
896#### Source
898```hoon
899 ++ woad :: cord format
900 |= a/@ta
901 ^- @t
902 %+ rap 3
903 |- ^- (list @)
904 ?: =(`@`0 a)
905 ~
906 =+ b=(end 3 1 a)
907 =+ c=(rsh 3 1 a)
908 ?: =('.' b)
909 [' ' $(a c)]
910 ?. =('~' b)
911 [b $(a c)]
912 => .(b (end 3 1 c), c (rsh 3 1 c))
913 ?+ b =- (weld (rip 3 (tuft p.d)) $(a q.d))
914 ^= d
915 =+ d=0
916 |- ^- {p/@ q/@}
917 ?: =('.' b)
918 [d c]
919 ?< =(0 c)
920 %= $
921 b (end 3 1 c)
922 c (rsh 3 1 c)
923 d %+ add (mul 16 d)
924 %+ sub b
925 ?: &((gte b '0') (lte b '9')) 48
926 ?>(&((gte b 'a') (lte b 'z')) 87)
927 ==
928 $'.' ['.' $(a c)]
929 $'~' ['~' $(a c)]
930 ==
931 ::
932```
934#### Examples
936```
937 > (woad ~.~b6.20.as)
938 '¶20 as'
939```
942---
943### `++wood`
945Escape cord
947Escape `++cord` codepoints.
949#### Accepts
951`a` is a `++span` (`@ta`).
953#### Produces
955A `++span` (`@ta`).
957#### Source
959```hoon
960 ++ wood :: cord format
961 |= a/@t
962 ^- @ta
963 %+ rap 3
964 |- ^- (list @)
965 ?: =(`@`0 a)
966 ~
967 =+ b=(teff a)
968 =+ c=(turf (end 3 b a))
969 =+ d=$(a (rsh 3 b a))
970 ?: ?| &((gte c 'a') (lte c 'z'))
971 &((gte c '0') (lte c '9'))
972 =(`@`'-' c)
973 ==
974 [c d]
975 ?+ c
976 :- '~'
977 =+ e=(met 2 c)
978 |- ^- tape
979 ?: =(0 e)
980 ['.' d]
981 =. e (dec e)
982 =+ f=(rsh 2 e c)
983 [(add ?:((lte f 9) 48 87) f) $(c (end 2 e c))]
984 ::
985```
987#### Examples
989```
990 > (wood 'my ßam')
991 ~.my.~df.am
992```
994---