# Working With Strings

Strings in RETRO are NULL terminated sequences of values
representing characters. Being NULL terminated, they can't
contain a NULL (ASCII 0).

The character words in RETRO are built around ASCII, but
strings can contain UTF8 encoded data if the host platform
allows. Words like `s:length` will return the number of bytes,
not the number of logical characters in this case.

## Sigil

Strings begin with a single `'`.

    'Hello
    'This_is_a_string
    'This_is_a_much_longer_string_12345_67890_!!!

RETRO will replace spaces with underscores. If you need both
spaces and underscores in a string, escape the underscores and
use `s:format`:

    'This_has_spaces_and_under\_scored_words. s:format

## Namespace

Words operating on strings are in the `s:` namespace.

## Lifetime

At the interpreter, strings get allocated in a rotating buffer.
This is used by the words operating on strings, so if you need
to keep them around, use `s:keep` or `s:copy` to move them to
more permanent storage.

In a definition, the string is compiled inline and so is in
permanent memory.

You can manually manage the string lifetime by using `s:keep`
to place it into permanent memory or `s:temp` to copy it to
the rotating buffer.

## Mutability

Strings are mutable. If you need to ensure that a string is
not altered, make a copy before operating on it or see the
individual glossary entries for notes on words that may do
this automatically.

## Searching

RETRO provides four words for searching within a string.

* `s:contains-char?` 
* `s:contains-string?`
* `s:index-of`
* `s:index-of-string`

## Comparisons

* `s:eq?`
* `s:case`

## Extraction

To obtain a new string containing the first `n` characters from
a source string, use `s:left`:

    'Hello_World #5 s:left

To obtain a new string containing the last `n` characters from
a source string, use `s:right`:

    'Hello_World #5 s:right

If you need to extract data from the middle of the string, use
`s:substr`. This takes a string, the offset of the first
character, and the number of characters to extract.

    'Hello_World #3 #5 s:substr

## Joining

You can use `s:append` or `s:prepend` to merge two strings.

    'First 'Second s:append
    'Second 'First s:prepend

## Tokenization

* `s:tokenize`
* `s:tokenize-on-string`
* `s:split`
* `s:split-on-string`

## Conversions

To convert the case of a string, RETRO provides `s:to-lower`
and `s:to-upper`.

`s:to-number` is provided to convert a string to an integer
value. This has a few limitations:

- only supports decimal
- non-numeric characters will result in incorrect values

## Cleanup

RETRO provides a handful of words for cleaning up strings.

`s:chop` will remove the last character from a string. This
is done by replacing it with an ASCII:NULL.

`s:trim` removes leading and trailing whitespace from a string.
For more control, there is also `s:trim-left` and `s:trim-right`
which let you trim just the leading or trailing end as desired.

## Combinators

* `s:for-each`
* `s:filter`
* `s:map`

## Other

* `s:evaluate`
* `s:copy`
* `s:reverse`
* `s:hash`
* `s:length`
* `s:replace`
* `s:format`
* `s:empty`

## Controlling The Temporary Buffers

As dicussed in the Lifetime subsection, temporary strings are
allocated in a rotating buffer. The details of this can be
altered by updating two variables.

    | Variable      | Holds                                    |
    | ------------- | ---------------------------------------- |
    | TempStrings   | The number of temporary strings          |
    | TempStringMax | The maximum length of a temporary string |

For example, to increase the number of temporary strings to
48:

    #48 !TempStrings

The defaults are:

    | Variable      | Default |
    | ------------- | ------- |
    | TempStrings   | 32      |
    | TempStringMax | 512     |

It's also important to note that altering these will affect
the memory map for all temporary buffers. Do not use anything
already in the buffers after updating these or you will risk
data corruption and possible crashes.