'\" t
.\" Copyright (c) 2025 Bruce Hill
.\" All rights reserved.
.\"
.TH Text.translate 3 2025-09-06 "Tomo man-pages"
.SH NAME
Text.translate \- perform multiple replacements
.SH LIBRARY
Tomo Standard Library
.SH SYNOPSIS
.nf
.BI Text.translate\ :\ func(text:\ Text,\ translations:\ {Text:Text}\ ->\ Text)
.fi
.SH DESCRIPTION
Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See Text.replace() for more information about replacement behavior.


.SH ARGUMENTS

.TS
allbox;
lb lb lbx lb
l l l l.
Name	Type	Description	Default
text	Text	The text to be translated. 	-
translations	{Text:Text}	A table mapping from target text to its replacement. 	-
.TE
.SH RETURN
The text with all occurrences of the targets replaced with their corresponding replacement text.

.SH EXAMPLES
.EX
>> "A <tag> & an amperand".translate({
    "&": "&amp;",
    "<": "&lt;",
    ">": "&gt;",
    '"": "&quot",
    "'": "&#39;",
})
= "A &lt;tag&gt; &amp; an ampersand"
.EE