# String Instructions — CONCAT, FIND, MID, INSERT, DELETE

Source: https://rungs.dev/docs/structured-text/instructions/string

> The Structured Text string instructions in rungs.dev join STRINGs, find text inside one, and take part of one out, each as a statement of its own.

A `STRING` tag holds text: up to 82 characters, with `LEN` saying how many are in use. These
five instructions build text and take it apart, for an operator message, a barcode, or a reply
from a serial device.

Each one is a **statement of its own** that writes its result into its last operand. None of
them gives back a value, so `PartNumber := MID(Barcode, 3, 4);` is refused: write
`MID(Barcode, 3, 4, PartNumber);`. The last operand may also be one the statement reads.

```iecst
CONCAT(AlarmPrefix, AlarmText, DisplayLine);   (* 'ALARM: ' and 'Low oil' give 'ALARM: Low oil' *)
FIND(Barcode, Separator, 1, SeparatorAt);       (* '-' in 'AB-123' is at 3 *)
MID(Barcode, 3, 4, PartNumber);                 (* 3 characters from character 4: '123' *)
INSERT(Reading, Unit, 5, Shown);                (* ' C' after '25.5': '25.5 C' *)
DELETE(Barcode, 3, 1, Suffix);                  (* 'AB-' removed: '123' *)
```

Characters are counted from **1**. `MID` and `DELETE` take the quantity before the start.

## Operands [#operands]

| Instruction | Operands, in order                     |
| ----------- | -------------------------------------- |
| `CONCAT`    | source A, source B, destination        |
| `FIND`      | source, search, start, result          |
| `MID`       | source, quantity, start, destination   |
| `INSERT`    | source A, source B, start, destination |
| `DELETE`    | source, quantity, start, destination   |

Every text operand is a `STRING` tag, an element of a `STRING` array, or a `STRING` member. A
start or a quantity is a `DINT`, `INT` or `SINT` tag, or a whole number typed in, never a
`REAL`: `MID(Barcode, 1.0, 4, PartNumber);` is refused. `FIND`'s result may be a `DINT`,
`INT`, `SINT` or `REAL`.

Each operand is a tag or a number, never an expression and never text in quotes:
`FIND(Barcode, Separator, Index + 1, SeparatorAt);` is refused. Work the value out into a tag
first. Text in quotes goes only in `:=` and in a comparison.

## What happens at the edges [#what-happens-at-the-edges]

| Instruction | When                                           | Result                                                |
| ----------- | ---------------------------------------------- | ----------------------------------------------------- |
| `CONCAT`    | The two hold more than 82 characters together  | The first 82, and a warning                           |
| `FIND`      | The search text is not there, or is empty      | `0`                                                   |
| `FIND`      | The start is not a character of the source     | `0`, and a warning                                    |
| `MID`       | The quantity runs past the end, or is negative | The rest from the start, and a warning                |
| `INSERT`    | The result would be longer than 82 characters  | The destination is left as it was, and a warning      |
| `DELETE`    | The quantity runs past the end, or is negative | Everything from the start removed, and a warning      |
| any         | A text operand's `LEN` is outside `0` to `82`  | Nothing is written (`FIND` stores `0`), and a warning |

`MID`, `INSERT` and `DELETE` also leave the destination as it was when the start is not a
character they can start at. For `INSERT` that is `1` to one past the end of source A.

## Related [#related]

- [String conversion](https://rungs.dev/docs/structured-text/instructions/string-conversion) — numbers to text and back, and letter case
- [String instructions in Ladder](https://rungs.dev/docs/ladder-logic/instructions/string)
- [Variables and assignment](https://rungs.dev/docs/structured-text/variables-and-assignment) — copying text with `:=`