code / tomo

   1 '\" t
   2 .\" Copyright (c) 2026 Bruce Hill
   3 .\" All rights reserved.
   4 .\"
   5 .TH Text 3 2026-03-14 "Tomo man-pages"
   6 .SH NAME
   7 Text \- a Tomo type
   8 .SH LIBRARY
   9 Tomo Standard Library
  10 .fi
  11 .SH METHODS
  12 
  13 .TP
  14 .BI Text.as_c_string\ :\ func(text:\ Text\ ->\ CString)
  15 Converts a \fBText\fR value to a C-style string. 
  16 
  17 For more, see:
  18 .BR Tomo-Text.as_c_string (3)
  19 
  20 
  21 .TP
  22 .BI Text.at\ :\ func(text:\ Text,\ index:\ Int\ ->\ Text)
  23 Get the graphical cluster at a given index. This is similar to \fBstr[i]\fR with ASCII text, but has more correct behavior for unicode text. 
  24 
  25 For more, see:
  26 .BR Tomo-Text.at (3)
  27 
  28 
  29 .TP
  30 .BI Text.by_line\ :\ func(text:\ Text\ ->\ func(->Text?))
  31 Returns an iterator function that can be used to iterate over the lines in a text. 
  32 
  33 For more, see:
  34 .BR Tomo-Text.by_line (3)
  35 
  36 
  37 .TP
  38 .BI Text.by_split\ :\ func(text:\ Text,\ delimiter:\ Text\ =\ ""\ ->\ func(->Text?))
  39 Returns an iterator function that can be used to iterate over text separated by a delimiter. 
  40 
  41 For more, see:
  42 .BR Tomo-Text.by_split (3)
  43 
  44 
  45 .TP
  46 .BI Text.by_split_any\ :\ func(text:\ Text,\ delimiters:\ Text\ =\ "\ $\[rs]t\[rs]r\[rs]n"\ ->\ func(->Text?))
  47 Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. 
  48 
  49 For more, see:
  50 .BR Tomo-Text.by_split_any (3)
  51 
  52 
  53 .TP
  54 .BI Text.caseless_equals\ :\ func(a:\ Text,\ b:\ Text,\ language:\ Text\ =\ "C"\ ->\ Bool)
  55 Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). 
  56 
  57 For more, see:
  58 .BR Tomo-Text.caseless_equals (3)
  59 
  60 
  61 .TP
  62 .BI Text.codepoint_names\ :\ func(text:\ Text\ ->\ [Text])
  63 Returns a list of the names of each codepoint in the text. 
  64 
  65 For more, see:
  66 .BR Tomo-Text.codepoint_names (3)
  67 
  68 
  69 .TP
  70 .BI Text.distance\ :\ func(a:\ Text,\ b:\ Text,\ language:\ Text\ =\ "C"\ ->\ Num)
  71 Get an approximate distance between two texts, such that when the distance is small, the texts are similar and when the distance is large, the texts are dissimilar. 
  72 
  73 For more, see:
  74 .BR Tomo-Text.distance (3)
  75 
  76 
  77 .TP
  78 .BI Text.ends_with\ :\ func(text:\ Text,\ suffix:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Bool)
  79 Checks if the \fBText\fR ends with a literal suffix text. 
  80 
  81 For more, see:
  82 .BR Tomo-Text.ends_with (3)
  83 
  84 
  85 .TP
  86 .BI Text.find\ :\ func(text:\ Text,\ target:\ Text,\ start:\ Int\ =\ 1\ ->\ Int)
  87 Find a substring within a text and return its index, if found. 
  88 
  89 For more, see:
  90 .BR Tomo-Text.find (3)
  91 
  92 
  93 .TP
  94 .BI Text.from\ :\ func(text:\ Text,\ first:\ Int\ ->\ Text)
  95 Get a slice of the text, starting at the given position. 
  96 
  97 For more, see:
  98 .BR Tomo-Text.from (3)
  99 
 100 
 101 .TP
 102 .BI Text.from_c_string\ :\ func(str:\ CString\ ->\ Text)
 103 Converts a C-style string to a \fBText\fR value. 
 104 
 105 For more, see:
 106 .BR Tomo-Text.from_c_string (3)
 107 
 108 
 109 .TP
 110 .BI Text.from_codepoint_names\ :\ func(codepoint_names:\ [Text]\ ->\ [Text])
 111 Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. 
 112 
 113 For more, see:
 114 .BR Tomo-Text.from_codepoint_names (3)
 115 
 116 
 117 .TP
 118 .BI Text.from_utf16\ :\ func(bytes:\ [Int16]\ ->\ [Text])
 119 Returns text that has been constructed from the given UTF16 sequence. 
 120 
 121 For more, see:
 122 .BR Tomo-Text.from_utf16 (3)
 123 
 124 
 125 .TP
 126 .BI Text.from_utf32\ :\ func(codepoints:\ [Int32]\ ->\ [Text])
 127 Returns text that has been constructed from the given UTF32 codepoints. 
 128 
 129 For more, see:
 130 .BR Tomo-Text.from_utf32 (3)
 131 
 132 
 133 .TP
 134 .BI Text.from_utf8\ :\ func(bytes:\ [Byte]\ ->\ [Text])
 135 Returns text that has been constructed from the given UTF8 bytes. 
 136 
 137 For more, see:
 138 .BR Tomo-Text.from_utf8 (3)
 139 
 140 
 141 .TP
 142 .BI Text.has\ :\ func(text:\ Text,\ target:\ Text\ ->\ Bool)
 143 Checks if the \fBText\fR contains some target text. 
 144 
 145 For more, see:
 146 .BR Tomo-Text.has (3)
 147 
 148 
 149 .TP
 150 .BI Text.join\ :\ func(glue:\ Text,\ pieces:\ [Text]\ ->\ Text)
 151 Joins a list of text pieces with a specified glue. 
 152 
 153 For more, see:
 154 .BR Tomo-Text.join (3)
 155 
 156 
 157 .TP
 158 .BI Text.left_pad\ :\ func(text:\ Text,\ width:\ Int,\ pad:\ Text\ =\ "\ ",\ language:\ Text\ =\ "C"\ ->\ Text)
 159 Pad some text on the left side so it reaches a target width. 
 160 
 161 For more, see:
 162 .BR Tomo-Text.left_pad (3)
 163 
 164 
 165 .TP
 166 .BI Text.lines\ :\ func(text:\ Text\ ->\ [Text])
 167 Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling \fB\r\n\fR the same as \fB\n\fR. 
 168 
 169 For more, see:
 170 .BR Tomo-Text.lines (3)
 171 
 172 
 173 .TP
 174 .BI Text.lower\ :\ func(text:\ Text,\ language:\ Text\ =\ "C"\ ->\ Text)
 175 Converts all characters in the text to lowercase. 
 176 
 177 For more, see:
 178 .BR Tomo-Text.lower (3)
 179 
 180 
 181 .TP
 182 .BI Text.matches_glob\ :\ func(path:\ Text,\ glob:\ Text\ ->\ Bool)
 183 Return whether or not the text matches the given glob. 
 184 
 185 For more, see:
 186 .BR Tomo-Text.matches_glob (3)
 187 
 188 
 189 .TP
 190 .BI Text.middle_pad\ :\ func(text:\ Text,\ width:\ Int,\ pad:\ Text\ =\ "\ ",\ language:\ Text\ =\ "C"\ ->\ Text)
 191 Pad some text on the left and right side so it reaches a target width. 
 192 
 193 For more, see:
 194 .BR Tomo-Text.middle_pad (3)
 195 
 196 
 197 .TP
 198 .BI Text.quoted\ :\ func(text:\ Text,\ color:\ Bool\ =\ no,\ quotation_mark:\ Text\ =\ `"`\ ->\ Text)
 199 Formats the text with quotation marks and escapes. 
 200 
 201 For more, see:
 202 .BR Tomo-Text.quoted (3)
 203 
 204 
 205 .TP
 206 .BI Text.repeat\ :\ func(text:\ Text,\ count:\ Int\ ->\ Text)
 207 Repeat some text multiple times. 
 208 
 209 For more, see:
 210 .BR Tomo-Text.repeat (3)
 211 
 212 
 213 .TP
 214 .BI Text.replace\ :\ func(text:\ Text,\ target:\ Text,\ replacement:\ Text\ ->\ Text)
 215 Replaces occurrences of a target text with a replacement text. 
 216 
 217 For more, see:
 218 .BR Tomo-Text.replace (3)
 219 
 220 
 221 .TP
 222 .BI Text.reversed\ :\ func(text:\ Text\ ->\ Text)
 223 Return a text that has the grapheme clusters in reverse order. 
 224 
 225 For more, see:
 226 .BR Tomo-Text.reversed (3)
 227 
 228 
 229 .TP
 230 .BI Text.right_pad\ :\ func(text:\ Text,\ width:\ Int,\ pad:\ Text\ =\ "\ ",\ language:\ Text\ =\ "C"\ ->\ Text)
 231 Pad some text on the right side so it reaches a target width. 
 232 
 233 For more, see:
 234 .BR Tomo-Text.right_pad (3)
 235 
 236 
 237 .TP
 238 .BI Text.slice\ :\ func(text:\ Text,\ from:\ Int\ =\ 1,\ to:\ Int\ =\ -1\ ->\ Text)
 239 Get a slice of the text. 
 240 
 241 For more, see:
 242 .BR Tomo-Text.slice (3)
 243 
 244 
 245 .TP
 246 .BI Text.split\ :\ func(text:\ Text,\ delimiter:\ Text\ =\ ""\ ->\ [Text])
 247 Splits the text into a list of substrings based on exact matches of a delimiter. 
 248 
 249 For more, see:
 250 .BR Tomo-Text.split (3)
 251 
 252 
 253 .TP
 254 .BI Text.split_any\ :\ func(text:\ Text,\ delimiters:\ Text\ =\ "\ $\[rs]t\[rs]r\[rs]n"\ ->\ [Text])
 255 Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). 
 256 
 257 For more, see:
 258 .BR Tomo-Text.split_any (3)
 259 
 260 
 261 .TP
 262 .BI Text.starts_with\ :\ func(text:\ Text,\ prefix:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Bool)
 263 Checks if the \fBText\fR starts with a literal prefix text. 
 264 
 265 For more, see:
 266 .BR Tomo-Text.starts_with (3)
 267 
 268 
 269 .TP
 270 .BI Text.title\ :\ func(text:\ Text,\ language:\ Text\ =\ "C"\ ->\ Text)
 271 Converts the text to title case (capitalizing the first letter of each word). 
 272 
 273 For more, see:
 274 .BR Tomo-Text.title (3)
 275 
 276 
 277 .TP
 278 .BI Text.to\ :\ func(text:\ Text,\ last:\ Int\ ->\ Text)
 279 Get a slice of the text, ending at the given position. 
 280 
 281 For more, see:
 282 .BR Tomo-Text.to (3)
 283 
 284 
 285 .TP
 286 .BI Text.translate\ :\ func(text:\ Text,\ translations:\ {Text:Text}\ ->\ Text)
 287 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. 
 288 
 289 For more, see:
 290 .BR Tomo-Text.translate (3)
 291 
 292 
 293 .TP
 294 .BI Text.trim\ :\ func(text:\ Text,\ to_trim:\ Text\ =\ "\ $\[rs]t\[rs]r\[rs]n",\ left:\ Bool\ =\ yes,\ right:\ Bool\ =\ yes\ ->\ Text)
 295 Trims the given characters (grapheme clusters) from the left and/or right side of the text. 
 296 
 297 For more, see:
 298 .BR Tomo-Text.trim (3)
 299 
 300 
 301 .TP
 302 .BI Text.upper\ :\ func(text:\ Text,\ language:\ Text\ =\ "C"\ ->\ Text)
 303 Converts all characters in the text to uppercase. 
 304 
 305 For more, see:
 306 .BR Tomo-Text.upper (3)
 307 
 308 
 309 .TP
 310 .BI Text.utf16\ :\ func(text:\ Text\ ->\ [Int16])
 311 Returns a list of Unicode code points for UTF16 encoding of the text. 
 312 
 313 For more, see:
 314 .BR Tomo-Text.utf16 (3)
 315 
 316 
 317 .TP
 318 .BI Text.utf32\ :\ func(text:\ Text\ ->\ [Int32])
 319 Returns a list of Unicode code points for UTF32 encoding of the text. 
 320 
 321 For more, see:
 322 .BR Tomo-Text.utf32 (3)
 323 
 324 
 325 .TP
 326 .BI Text.utf8\ :\ func(text:\ Text\ ->\ [Byte])
 327 Converts a \fBText\fR value to a list of bytes representing a UTF8 encoding of the text. 
 328 
 329 For more, see:
 330 .BR Tomo-Text.utf8 (3)
 331 
 332 
 333 .TP
 334 .BI Text.width\ :\ func(text:\ Text\ ->\ Int)
 335 Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's \fB.length\fR, but there are some characters like emojis that render wider than 1 cell. 
 336 
 337 For more, see:
 338 .BR Tomo-Text.width (3)
 339 
 340 
 341 .TP
 342 .BI Text.without_prefix\ :\ func(text:\ Text,\ prefix:\ Text\ ->\ Text)
 343 Returns the text with a given prefix removed (if present). 
 344 
 345 For more, see:
 346 .BR Tomo-Text.without_prefix (3)
 347 
 348 
 349 .TP
 350 .BI Text.without_suffix\ :\ func(text:\ Text,\ suffix:\ Text\ ->\ Text)
 351 Returns the text with a given suffix removed (if present). 
 352 
 353 For more, see:
 354 .BR Tomo-Text.without_suffix (3)
 355