# String

> Text operations on data values: length, case, trim, split, replace, slice, pad, repeat, search, regular expressions, format and JSON.

Source: https://docs.tune.toys/nodes/data.string/

String transforms text: change case, cut it into a list, replace parts of it, search it or turn it into numbers and JSON.

## What it does

The `text` input is read as text (a number becomes its digits, a list becomes its JSON). Operation chooses what happens to it. Some operations need more: `b` is the search text, separator or padding, and `c` is the replacement. When the `b` or `c` input is not connected, String uses the node's B or C text field instead.

| Operation                             | Result                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------ |
| Length                                | number of characters                                                     |
| Concatenate                           | text followed by B                                                       |
| Upper case, Lower case, Trim, Reverse | the changed text                                                         |
| Split                                 | a list of the pieces between each B; empty B splits into characters      |
| Replace, Replace all                  | the first, or every, B replaced by C                                     |
| Slice                                 | Count characters from Start; Count 0 means to the end                    |
| Pad start, Pad end                    | text padded with B (a space by default) to Count characters              |
| Repeat                                | text repeated Count times                                                |
| Character at                          | the character at Start, or empty text                                    |
| Index of                              | position of B at or after Start, or -1                                   |
| Match                                 | a list of the match and its groups, or no value when nothing matches     |
| Format                                | each `{}` in the text replaced by the next element of B; `{0}` picks one |
| To number, Parse JSON, To JSON        | conversions; text that does not convert sends no value                   |

Negative Start counts from the end. With Regular expression off, B is searched for literally; turn it on to read B as a pattern for Split, Replace, Replace all, Index of and Match. An invalid pattern sends no value and the inspector shows the error.

## When to use it

Use it to clean up typed or imported text, to split a list of names or numbers written on one line, to build labels from values with Format, or to pull numbers out of text with Match and To number. To join a list back into text, use [List](https://docs.tune.toys/nodes/data.list/) Join.

## Ports

<!-- ports:start -->

| Port    | Direction | Signal     | Lanes |
| ------- | --------- | ---------- | ----- |
| `text`  | Input     | Data (any) | 1     |
| `b`     | Input     | Data (any) | 1     |
| `c`     | Input     | Data (any) | 1     |
| `value` | Output    | Data (any) | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter | Label              | Range         | Default | Unit | Scale  | Notes                                                                                                                                                                                                                                                                                                    |
| --------- | ------------------ | ------------- | ------- | ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `op`      | Operation          | 0 to 19       | 0       |      | linear | Text operation; b and c are its arguments. Choices: 0 Length, 1 Concatenate, 2 Upper case, 3 Lower case, 4 Trim, 5 Split, 6 Replace, 7 Replace all, 8 Slice, 9 Pad start, 10 Pad end, 11 Repeat, 12 Reverse, 13 Character at, 14 Index of, 15 Match, 16 Format, 17 To number, 18 Parse JSON, 19 To JSON. |
| `start`   | Start              | -4096 to 4096 | 0       |      | linear | Start index; negative counts from the end. Shown when `op` is 8 or 13 or 14.                                                                                                                                                                                                                             |
| `count`   | Count              | 0 to 4096     | 1       |      | linear | Length, pad width or repeat count. Shown when `op` is 8 or 9 or 10 or 11.                                                                                                                                                                                                                                |
| `regex`   | Regular expression | 0 to 1        | 0       |      | linear | Treat b as a regular expression. Choices: 0 Off, 1 On. Shown when `op` is 5 or 6 or 7 or 14 or 15.                                                                                                                                                                                                       |
| `case`    | Case               | 0 to 1        | 0       |      | linear | Whether matching respects letter case. Choices: 0 Sensitive, 1 Insensitive. Shown when `op` is 5 or 6 or 7 or 14 or 15.                                                                                                                                                                                  |

<!-- parameters:end -->

<!-- data:start -->

- `b`: text.
- `c`: text.

<!-- data:end -->

### Operation (`op`)

The text operation, a discrete choice. See the table above for what each one does and which fields it uses.

### Start (`start`)

A character position from -4 096 to 4 096. 0 is the first character and -1 the last. Used by Slice, Character at and Index of.

### Count (`count`)

A number of characters or repeats, from 0 to 4 096. Slice takes Count characters (0 takes the rest), Pad start and Pad end pad to Count characters, Repeat repeats Count times.

### Regular expression (`regex`)

Off or On, a discrete choice. Off reads B as plain text, so `.` is a full stop. On reads B as a pattern, so `[0-9]+` means any run of digits and Match returns capture groups.

### Case (`case`)

Sensitive or Insensitive, a discrete choice. Insensitive makes Index of ignore case and adds the `i` flag to regular expressions.

## Tips

- To split on commas with or without spaces, turn Regular expression on and set B to `\s*,\s*`.
- To replace every number in a line, use Replace all with Regular expression on, B set to `[0-9]+` and C to the replacement.
- Format with B connected to a list builds labels: `"{} of {}"` with `[3, 8]` gives `"3 of 8"`.
- Text fields hold up to 1 024 characters; longer results are cut at 65 536 characters and flagged.

## See also

[Value](https://docs.tune.toys/nodes/data.value/), [List](https://docs.tune.toys/nodes/data.list/), [Compare](https://docs.tune.toys/nodes/data.compare/).