@@ -5,8 +5,7 @@ template = "doc.html"
55+++
66
77This document discusses hoon's two main string types: `cord`s (as well as its
8−subsets `knot` and `term`) and `tape`s. Cords are strings encoded in atoms, and
9−tapes are strings encoded as lists of single characters. The focus of this
8+subsets `knot` and `term`) and `tape`s. The focus of this
109document is on their basic properties, syntax and the most common text-related
1110functions you'll regularly encounter. In particular, it discusses conversions
1211and the encoding/decoding of atom auras in strings.
@@ -19,14 +18,41 @@ discussed in this document.
1918There are a good deal more text manipulation functions than are discussed here.
2019See the [Further Reading](#further-reading) section for details.
2120
22−## text atoms
21+## `tape`s vs. text atoms
22+
23+As mentioned, urbit mainly deals with two kinds of strings: `tape`s and
24+`cord`/`knot`/`term`s. The former is a list of individual UTF-8 characters.
25+The latter three encode UTF-8 strings in a single atom.
26+
27+Cords may contain any UTF-8 characters, while `knot`s and `term`s only allow a
28+smaller subset. Each of these are discussed below in the [Text
29+atoms](#text-atoms) section.
30+
31+Text atoms like `cord`s are more efficient to store and move around. They are
32+also more efficient to manipulate with simple bitwise operations. Their downside
33+is that UTF-8 characters vary in their byte-length. ASCII characters are all
34+8-bit, but others can occupy up to four bytes. Accounting for this variation in
35+character size can complicate otherwise simple functions. Tapes, on the other
36+hand, don't have this problem because each character is a separate item in the
37+list, regardless of it byte-length. This fact makes it much easier to process
38+tapes in non-trivial ways with simple list functions.
39+
40+In light of this, a general rule of thumb is to use cords for simple things like
41+storing chat messages or exchanging them over the network. If text requires
42+complex processing on the other hand, it is generally easier with tapes. Note
43+there _are_ cord manipulation functions in the standard library, so you needn't
44+always convert cords to tapes for processing, it just depends on the case.
45+
46+Next we'll look at these different types of strings in more detail.
47+
48+## Text atoms
2349
2450### `cord`
2551
26−A [`cord`](/docs/hoon/reference/stdlib/2q#cord) has an aura of
27−`@t`. It denotes UTF-8 text encoded in an atom, little-endian. That is, the
28−first character in the text is the least-significant byte. A cord may contain
29−any UTF-8 characters, there are no restrictions.
52+A [`cord`](/docs/hoon/reference/stdlib/2q#cord) has an aura of `@t`. It denotes
53+UTF-8 text encoded in an atom, little-endian. That is, the first character in
54+the text is the least-significant byte. A cord may contain any UTF-8 characters,
55+there are no restrictions.
3056
3157The `hoon` syntax for a cord is some text wrapped in single-quotes like:
3258
@@ -78,10 +104,10 @@ This will be parsed to:
78104
79105### `knot`
80106
81−A [`knot`](/docs/hoon/reference/stdlib/2q#knot) has an aura of
82−`@ta`, and is a subset of a [`cord`](#cord). It allows lower-case letters,
83−numbers, and four special characters: Hyphen, tilde, underscore and period. Its
84−restricted set of characters is intended to be URL-safe.
107+A [`knot`](/docs/hoon/reference/stdlib/2q#knot) has an aura of `@ta`, and is a
108+subset of a [`cord`](#cord). It allows lower-case letters, numbers, and four
109+special characters: Hyphen, tilde, underscore and period. Its restricted set of
110+characters is intended to be URL-safe.
85111
86112The `hoon` syntax for a knot is a string containing any of the aforementioned
87113characters prepended with `~.` like:
@@ -92,11 +118,11 @@ characters prepended with `~.` like:
92118
93119### `term`
94120
95−A [`term`](/docs/hoon/reference/stdlib/2q#term) has an aura of
96−`@tas`, and is a subset of a [`knot`](#knot). It only allows lower-case letters,
97−numbers, and hyphens. Additionally, the first character cannot be a hyphen or number. This
98−is a very restricted text atom, and is intended for naming data structures and
99−the like.
121+A [`term`](/docs/hoon/reference/stdlib/2q#term) has an aura of `@tas`, and is a
122+subset of a [`knot`](#knot). It only allows lower-case letters, numbers, and
123+hyphens. Additionally, the first character cannot be a hyphen or number. This is
124+a very restricted text atom, and is intended for naming data structures and the
125+like.
100126
101127The `hoon` syntax for a term is a string conforming to the prior description,
102128prepended with a `%` like:
@@ -489,12 +515,15 @@ Finally, `+stab` parses a cord containing a path to a `path`. For example:
489515
490516- [Parsing](/docs/hoon/guides/parsing) - A guide to writing fully-fledged
491517 functional parsers in hoon.
518+
492519- [Auras](/docs/hoon/reference/auras) - Details of auras in hoon.
493520
494521- [stdlib 2b: List logic](/docs/hoon/reference/stdlib/2b) - Standard library
495522 functions for manipulating lists, which are useful for dealing with tapes.
523+
496524- [stdlib 2q: Molds and Mold-builders](/docs/hoon/reference/stdlib/2q) - Several
497525 text types are defined in this section of the standard library.
526+
498527- [stdlib 4b: Text processing](/docs/hoon/reference/stdlib/4b) - Standard
499528 library functions for manipulating and converting tapes and strings.
500529