<commit_before>+++
title = "Strings"
weight = 4
template = "doc.html"
+++

This document discusses hoon's two main string types: `cord`s (as well as its
subsets `knot` and `term`) and `tape`s. Cords are strings encoded in atoms, and
tapes are strings encoded as lists of single characters. The focus of this
document is on their basic properties, syntax and the most common text-related
functions you'll regularly encounter. In particular, it discusses conversions
and the encoding/decoding of atom auras in strings.

Hoon has a system for writing more elaborate functional parsers, but that is not
touched on here. Instead, see the [Parsing](/docs/hoon/guides/parsing) guide.
Hoon also has a type for UTF-32 strings, but those are rarely used and not
discussed in this document.

There are a good deal more text manipulation functions than are discussed here.
See the [Further Reading](#further-reading) section for details.

## text atoms

### `cord`

A [`cord`](/docs/hoon/reference/stdlib/2q#cord) has an aura of
`@t`. It denotes UTF-8 text encoded in an atom, little-endian. That is, the
first character in the text is the least-significant byte. A cord may contain
any UTF-8 characters, there are no restrictions.

The `hoon` syntax for a cord is some text wrapped in single-quotes like:

```hoon
'This is a cord!'
```

single-quotes and backslashes must be escaped with a backslash like:

```hoon
'\'quotes\' \\backslashes\\'
```

Characters can also be entered as hex, they just have to be escaped by a
backslash. For example, `'\21\21\21'` will render as `'!!!'`. This is useful for
entering special characters such as line breaks like `'foo\0abar'`.

Cords divided over multiple lines are allowed. There are two ways to do this.
The first is to start and end with three single-quotes like:

```hoon
'''
foo
bar
baz
'''
```

The line endings will be encoded Unix-style as line feed characters like:

```hoon
'foo\0abar\0abaz'
```

The second is to begin with a single-quote like usual, then break the line by
ending it with a backslash and start the next line with a forward-slash like:

```hoon
'foo\
/bar\
/baz'
```

This will be parsed to:

```hoon
'foobarbaz'
```

### `knot`

A [`knot`](/docs/hoon/reference/stdlib/2q#knot) has an aura of
`@ta`, and is a subset of a [`cord`](#cord). It allows lower-case letters,
numbers, and four special characters: Hyphen, tilde, underscore and period. Its
restricted set of characters is intended to be URL-safe.

The `hoon` syntax for a knot is a string containing any of the aforementioned
characters prepended with `~.` like:

```hoon
~.abc-123.def_456~ghi
```

### `term`

A [`term`](/docs/hoon/reference/stdlib/2q#term) has an aura of
`@tas`, and is a subset of a [`knot`](#knot). It only allows lower-case letters,
numbers, and hyphens. Additionally, the first character cannot be a hyphen. This
is a very restricted text atom, and is intended for naming data structures and
the like.

The `hoon` syntax for a term is a string conforming to the prior description,
prepended with a `%` like:

```hoon
%foo-123
```

#### A note about `term` type inference

There is actually an even more restricted text atom form with the same `%foo`
syntax as a term, where the type of the text is the text itself. For example, in
the dojo:

```
> `%foo`%foo
%foo<commit_msg>clarify terms can't start with a number<commit_after>+++
title = "Strings"
weight = 4
template = "doc.html"
+++

This document discusses hoon's two main string types: `cord`s (as well as its
subsets `knot` and `term`) and `tape`s. Cords are strings encoded in atoms, and
tapes are strings encoded as lists of single characters. The focus of this
document is on their basic properties, syntax and the most common text-related
functions you'll regularly encounter. In particular, it discusses conversions
and the encoding/decoding of atom auras in strings.

Hoon has a system for writing more elaborate functional parsers, but that is not
touched on here. Instead, see the [Parsing](/docs/hoon/guides/parsing) guide.
Hoon also has a type for UTF-32 strings, but those are rarely used and not
discussed in this document.

There are a good deal more text manipulation functions than are discussed here.
See the [Further Reading](#further-reading) section for details.

## text atoms

### `cord`

A [`cord`](/docs/hoon/reference/stdlib/2q#cord) has an aura of
`@t`. It denotes UTF-8 text encoded in an atom, little-endian. That is, the
first character in the text is the least-significant byte. A cord may contain
any UTF-8 characters, there are no restrictions.

The `hoon` syntax for a cord is some text wrapped in single-quotes like:

```hoon
'This is a cord!'
```

single-quotes and backslashes must be escaped with a backslash like:

```hoon
'\'quotes\' \\backslashes\\'
```

Characters can also be entered as hex, they just have to be escaped by a
backslash. For example, `'\21\21\21'` will render as `'!!!'`. This is useful for
entering special characters such as line breaks like `'foo\0abar'`.

Cords divided over multiple lines are allowed. There are two ways to do this.
The first is to start and end with three single-quotes like:

```hoon
'''
foo
bar
baz
'''
```

The line endings will be encoded Unix-style as line feed characters like:

```hoon
'foo\0abar\0abaz'
```

The second is to begin with a single-quote like usual, then break the line by
ending it with a backslash and start the next line with a forward-slash like:

```hoon
'foo\
/bar\
/baz'
```

This will be parsed to:

```hoon
'foobarbaz'
```

### `knot`

A [`knot`](/docs/hoon/reference/stdlib/2q#knot) has an aura of
`@ta`, and is a subset of a [`cord`](#cord). It allows lower-case letters,
numbers, and four special characters: Hyphen, tilde, underscore and period. Its
restricted set of characters is intended to be URL-safe.

The `hoon` syntax for a knot is a string containing any of the aforementioned
characters prepended with `~.` like:

```hoon
~.abc-123.def_456~ghi
```

### `term`

A [`term`](/docs/hoon/reference/stdlib/2q#term) has an aura of
`@tas`, and is a subset of a [`knot`](#knot). It only allows lower-case letters,
numbers, and hyphens. Additionally, the first character cannot be a hyphen or number. This
is a very restricted text atom, and is intended for naming data structures and
the like.

The `hoon` syntax for a term is a string conforming to the prior description,
prepended with a `%` like:

```hoon
%foo-123
```

#### A note about `term` type inference

There is actually an even more restricted text atom form with the same `%foo`
syntax as a term, where the type of the text is the text itself. For example, in
the dojo:

```
> `%foo`%foo
%foo
{'fraction_non_alphanumeric': 0.10002999400119976, 'fraction_numerical': 0.007798440311937612, 'mean_word_length': 4.2388059701492535, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6700904', 'n_tokens_mistral': 2155, 'n_tokens_neox': 1995, 'n_words': 999}