# iRules string workbench

> Run a Tcl 8.4 string command (range, first, map, match, compare, trim and more) and see the result on a character ruler: what was searched, matched, returned or replaced, and how indexes like end-1 or 010 were read. Local, no network.

- Tool: https://ronutz.com/en/tools/f5-irules-string-workbench
- Family: Networking

---

## What it does

Runs one Tcl 8.4.6 `string` subcommand and draws the result on a character ruler: every character of the string with its index, coloured by what the command did with it (searched, matched, returned, replaced, trimmed, or the first difference in a comparison). Seventeen subcommands are covered: `length`, `bytelength`, `tolower`, `toupper`, `range`, `index`, `first`, `last`, `map`, `match`, `compare`, `equal`, `trim`, `trimleft`, `trimright`, `replace` and `repeat`.

## How to read the result

- **The command** is the exact line to paste into an iRule, quoted the way Tcl needs.
- **The ruler** numbers characters from 0, the way every index argument counts.
- **Index arguments** shows how each index was read: `end-1` means the last character but one, and an index written `010` is octal, so it means 8.
- **The single pass of string map** lists each position: kept, or replaced by which key and value.

## Worth knowing

- `length` counts characters; `bytelength` counts the bytes of Tcl's internal UTF-8, so `héllo` is 5 characters and 6 bytes.
- `string map` makes one pass from left to right. At each position the first key in the list that matches wins, and replaced text is never examined again: `string map {a 1 ab 2} abab` gives `1b1b`, while `{ab 2 a 1}` gives `22`.
- `compare` orders by character code, so `string compare bench Chair` is 1.
- `string index` and `string range` return an empty string, not an error, when the index is outside the string.
- `trim` removes a **set** of characters, in any order, not a word.
- Tcl 8.4.6 accepts `e` or `en` on their own as `end`, but `e-1` is an error.
- Case conversion uses Tcl 8.4.6's own Unicode tables, which differ from a modern browser's for about a thousand characters (for example, Tcl 8.4.6 has no upper-case form for `µ`).

## Limits

Characters beyond the Basic Multilingual Plane are refused, because Tcl 8.4 cannot hold them as one character. `string is`, `totitle`, `wordstart` and `wordend` are not modelled. Results are capped at 100,000 characters for `repeat`.

## Sources

- [Tcl 8.4 manual: string](https://www.tcl-lang.org/man/tcl8.4/TclCmd/string.htm) (read 2026-10-03)
- [F5 K6091: The version of Tcl used to develop iRules](https://my.f5.com/manage/s/article/K6091) (read 2026-10-03)
- [Tcl 8.4.6 source code, tag core-8-4-6](https://github.com/tcltk/tcl/tree/core-8-4-6) (the reference interpreter the engine is tested against)

## Standards and references

- [F5 K6091: The version of Tcl used to develop iRules](https://my.f5.com/manage/s/article/K6091) - the iRules command set was developed from Tcl base version 8.4.6, which is used in all BIG-IP versions; the engine models that version
- [Tcl 8.4 manual: string](https://www.tcl-lang.org/man/tcl8.4/TclCmd/string.htm) - the subcommands, index forms (integer, end, end-N), map ordering and its single pass, compare and bytelength
- [Tcl 8.4.6 source code, tag core-8-4-6 on GitHub](https://github.com/tcltk/tcl/tree/core-8-4-6) - the reference interpreter: the engine was differential-tested against tclsh built from this tag (commit bf3eeadc)

## Related reading

- [findstr, substr and getfield: what F5 documents, and what it leaves open](https://ronutz.com/en/learn/irules-findstr-substr-getfield.md): F5 adds three commands to iRules for cutting a piece out of a value. findstr finds and skips, substr starts at an index, getfield splits on a separator, and two of them take a terminator that is either a length or a stop text. Here is each rule with F5's own examples, the plain Tcl that does the same job, and the cases F5's pages do not settle.
- [Tcl string commands in iRules: indexes, map, match, compare and trim](https://ronutz.com/en/learn/irules-string-commands.md): The string command does most of the text work in an iRule, and each subcommand has one rule people get wrong: indexes that read 010 as octal, a map that is a single pass, a trim that removes a set of characters rather than a word, and a compare that puts every capital before every lower-case letter.
- [Zero or one: where BIG-IP starts counting](https://ronutz.com/en/learn/bigip-zero-or-one.md): Tcl counts from 0, several commands F5 adds count from 1, counters return 1 for the first item, many zeros in the configuration are values rather than positions, and the same path segment is element 1, field 2 or index 1 depending on who is asking. Here is where each one comes from, in F5's own words, with the traps and the places where F5's pages disagree with themselves.