code / tomo

   1 Text.as_c_string:
   2   short: convert to C-style string
   3   description: >
   4     Converts a `Text` value to a C-style string.
   5   return:
   6     type: 'CString'
   7     description: >
   8       A C-style string (`CString`) representing the text.
   9   args:
  10     text:
  11       type: 'Text'
  12       description: >
  13         The text to be converted to a C-style string.
  14   example: |
  15     assert "Hello".as_c_string() == CString("Hello")
  16 
  17 Text.at:
  18   short: get a letter
  19   description: >
  20     Get the graphical cluster at a given index. This is similar to `str[i]` with
  21     ASCII text, but has more correct behavior for unicode text.
  22   return:
  23     type: 'Text'
  24     description: >
  25       A `Text` with the single graphical cluster at the given index.
  26   note: >
  27     Negative indices are counted from the back of the text, so `-1` means the
  28     last cluster, `-2` means the second-to-last, and so on.
  29   args:
  30     text:
  31       type: 'Text'
  32       description: >
  33         The text from which to get a cluster.
  34     index:
  35       type: 'Int'
  36       description: >
  37         The index of the graphical cluster (1-indexed).
  38   example: |
  39     assert "Amélie".at(3) == "é"
  40 
  41 Text.by_line:
  42   short: iterate by line
  43   description: >
  44     Returns an iterator function that can be used to iterate over the lines in a
  45     text.
  46   return:
  47     type: 'func(->Text?)'
  48     description: >
  49       An iterator function that returns one line at a time, until it runs out and
  50       returns `none`.
  51   note: >
  52     This function ignores a trailing newline if there is one. If you don't want
  53     this behavior, use `text.by_split($/{1 nl}/)` instead.
  54   args:
  55     text:
  56       type: 'Text'
  57       description: >
  58         The text to be iterated over, line by line.
  59   example: |
  60     text := "
  61         line one
  62         line two
  63     "
  64     lines := [line for line in text.by_line()]
  65     assert lines == ["line one", "line two"]
  66 
  67 Text.by_split:
  68   short: iterate by a spliting text
  69   description: >
  70     Returns an iterator function that can be used to iterate over text separated by
  71     a delimiter.
  72   return:
  73     type: 'func(->Text?)'
  74     description: >
  75       An iterator function that returns one chunk of text at a time, separated by the
  76       given delimiter, until it runs out and returns `none`.
  77   args:
  78     text:
  79       type: 'Text'
  80       description: >
  81         The text to be iterated over in delimited chunks.
  82     delimiter:
  83       type: 'Text'
  84       default: '""'
  85       description: >
  86         An exact delimiter to use for splitting the text.
  87   note: >
  88     To split based on a set of delimiters, use Text.by_split_any().
  89 
  90     If an empty text is given as the delimiter, then each split will be the
  91     graphical clusters of the text.
  92   example: |
  93     text := "one,two,three"
  94     chunks := [chunk for chunk in text.by_split(",")]
  95     assert chunks == ["one", "two", "three"]
  96 
  97 Text.by_split_any:
  98   short: iterate by one of many splitting characters
  99   description: >
 100     Returns an iterator function that can be used to iterate over text separated by
 101     one or more characters (grapheme clusters) from a given text of delimiters.
 102   return:
 103     type: 'func(->Text?)'
 104     description: >
 105       An iterator function that returns one chunk of text at a time, separated by the
 106       given delimiter characters, until it runs out and returns `none`.
 107   args:
 108     text:
 109       type: 'Text'
 110       description: >
 111         The text to be iterated over in delimited chunks.
 112     delimiters:
 113       type: 'Text'
 114       default: '" $\t\r\n"'
 115       description: >
 116         Grapheme clusters to use for splitting the text.
 117   note: >
 118     Splitting will occur on every place where one or more of the grapheme
 119     clusters in `delimiters` occurs.
 120 
 121     To split based on an exact delimiter, use Text.by_split().
 122   example: |
 123     text := "one,two,;,three"
 124     chunks := [chunk for chunk in text.by_split_any(",;")]
 125     assert chunks == ["one", "two", "three"]
 126 
 127 Text.utf8:
 128   short: get UTF8 bytes
 129   description: >
 130     Converts a `Text` value to a list of bytes representing a UTF8 encoding of
 131     the text.
 132   return:
 133     type: '[Byte]'
 134     description: >
 135       A list of bytes (`[Byte]`) representing the text in UTF8 encoding.
 136   args:
 137     text:
 138       type: 'Text'
 139       description: >
 140         The text to be converted to UTF8 bytes.
 141   example: |
 142     assert "Amélie".utf8() == [65, 109, 195, 169, 108, 105, 101]
 143 
 144 Text.caseless_equals:
 145   short: case-insensitive comparison
 146   description: >
 147     Checks whether two texts are equal, ignoring the casing of the letters (i.e.
 148     case-insensitive comparison).
 149   return:
 150     type: 'Bool'
 151     description: >
 152       `yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`.
 153   args:
 154     a:
 155       type: 'Text'
 156       description: >
 157         The first text to compare case-insensitively.
 158     b:
 159       type: 'Text'
 160       description: >
 161         The second text to compare case-insensitively.
 162     language:
 163       type: 'Text'
 164       default: '"C"'
 165       description: >
 166         The ISO 639 language code for which casing rules to use.
 167   example: |
 168     assert "A".caseless_equals("a") == yes
 169 
 170     # Turkish lowercase "I" is "ı" (dotless I), not "i"
 171     assert "I".caseless_equals("i", language="tr_TR") == no
 172 
 173 Text.codepoint_names:
 174   short: get unicode codepoint names
 175   description: >
 176     Returns a list of the names of each codepoint in the text.
 177   return:
 178     type: '[Text]'
 179     description: >
 180       A list of codepoint names (`[Text]`).
 181   args:
 182     text:
 183       type: 'Text'
 184       description: >
 185         The text from which to extract codepoint names.
 186   example: |
 187     assert "Amélie".codepoint_names() == [
 188         "LATIN CAPITAL LETTER A",
 189         "LATIN SMALL LETTER M",
 190         "LATIN SMALL LETTER E WITH ACUTE",
 191         "LATIN SMALL LETTER L",
 192         "LATIN SMALL LETTER I",
 193         "LATIN SMALL LETTER E",
 194     ]
 195 
 196 Text.ends_with:
 197   short: check suffix
 198   description: >
 199     Checks if the `Text` ends with a literal suffix text.
 200   return:
 201     type: 'Bool'
 202     description: >
 203       `yes` if the text has the target, `no` otherwise.
 204   args:
 205     text:
 206       type: 'Text'
 207       description: >
 208         The text to be searched.
 209     suffix:
 210       type: 'Text'
 211       description: >
 212         The literal suffix text to check for.
 213     remainder:
 214       type: '&Text?'
 215       default: 'none'
 216       description: >
 217         If non-none, this value will be set to the rest of the text up to the trailing suffix.
 218         If the suffix is not found, this value will be set to the original text.
 219   example: |
 220     assert "hello world".ends_with("world") == yes
 221     remainder : Text
 222     assert "hello world".ends_with("world", &remainder) == yes
 223     assert remainder == "hello "
 224 
 225 Text.distance:
 226   short: distance between two texts
 227   description: >
 228     Get an approximate distance between two texts, such that when the distance
 229     is small, the texts are similar and when the distance is large, the texts
 230     are dissimilar.
 231   note: >
 232     The exact distance algorithm is not specified and may be subject to change
 233     over time.
 234   return:
 235     type: 'Num'
 236     description: >
 237       The distance between the two texts (larger means more dissimilar).
 238   args:
 239     a:
 240       type: 'Text'
 241       description: >
 242         The first text to compare.
 243     b:
 244       type: 'Text'
 245       description: >
 246         The second text to compare.
 247     language:
 248       type: 'Text'
 249       default: '"C"'
 250       description: >
 251         The ISO 639 language code for which character width to use.
 252   example: |
 253     assert "hello".distance("hello") == 0
 254     texts := &["goodbye", "hello", "hallo"]
 255     texts.sort(func(a,b:&Text) a.distance("hello") <> b.distance("hello"))
 256     assert texts == ["hello", "hallo", "goodbye"]
 257 
 258 Text.find:
 259   short: find a substring
 260   description: >
 261     Find a substring within a text and return its index, if found.
 262   return:
 263     type: 'Int'
 264     description: >
 265       The index where the first occurrence of `target` appears, or `none` if it is not found.
 266   args:
 267     text:
 268       type: 'Text'
 269       description: >
 270         The text to be searched.
 271     target:
 272       type: 'Text'
 273       description: >
 274         The target text to find.
 275     start:
 276       type: 'Int'
 277       default: '1'
 278       description: >
 279         The index at which to begin searching.
 280   example: |
 281     assert "one two".find("one") == 1
 282     assert "one two".find("two") == 5
 283     assert "one two".find("three") == none
 284     assert "one two".find("o", start=2) == 7
 285 
 286 Text.from:
 287   short: slice from a starting index
 288   description: >
 289     Get a slice of the text, starting at the given position.
 290   return:
 291     type: 'Text'
 292     description: >
 293       The text from the given grapheme cluster to the end of the text.
 294   note: >
 295     A negative index counts backwards from the end of the text, so `-1` refers
 296     to the last cluster, `-2` the second-to-last, etc. Slice ranges will be
 297     truncated to the length of the text.
 298   args:
 299     text:
 300       type: 'Text'
 301       description: >
 302         The text to be sliced.
 303     first:
 304       type: 'Int'
 305       description: >
 306         The index to begin the slice.
 307   example: |
 308     assert "hello".from(2) == "ello"
 309     assert "hello".from(-2) == "lo"
 310 
 311 Text.from_utf8:
 312   short: convert UTF8 byte list to text
 313   description: >
 314     Returns text that has been constructed from the given UTF8 bytes.
 315   note: >
 316     The text will be normalized, so the resulting text's UTF8 bytes may not
 317     exactly match the input.
 318   return:
 319     type: '[Text]'
 320     description: >
 321       A new text based on the input UTF8 bytes after normalization has been applied.
 322   args:
 323     bytes:
 324       type: '[Byte]'
 325       description: >
 326         The UTF-8 bytes of the desired text.
 327   example: |
 328     assert Text.from_utf8([195, 133, 107, 101]) == "Åke"
 329 
 330 Text.from_utf16:
 331   short: convert UTF16 list to text
 332   description: >
 333     Returns text that has been constructed from the given UTF16 sequence.
 334   note: >
 335     The text will be normalized, so the resulting text's UTF16 sequence may not
 336     exactly match the input.
 337   return:
 338     type: '[Text]'
 339     description: >
 340       A new text based on the input UTF16 sequence after normalization has been applied.
 341   args:
 342     bytes:
 343       type: '[Int16]'
 344       description: >
 345         The UTF-16 integers of the desired text.
 346   example: |
 347     assert Text.from_utf16([197, 107, 101]) == "Åke"
 348     assert Text.from_utf16([12371, 12435, 12395, 12385, 12399, 19990, 30028]) == "こんにちは世界"
 349 
 350 Text.from_c_string:
 351   short: convert C-style string to text
 352   description: >
 353     Converts a C-style string to a `Text` value.
 354   return:
 355     type: 'Text'
 356     description: >
 357       A `Text` value representing the C-style string.
 358   args:
 359     str:
 360       type: 'CString'
 361       description: >
 362         The C-style string to be converted.
 363   example: |
 364     assert Text.from_c_string(CString("Hello")) == "Hello"
 365 
 366 Text.from_codepoint_names:
 367   short: convert list of unicode codepoint names to text
 368   description: >
 369     Returns text that has the given codepoint names (according to the Unicode
 370     specification) as its codepoints.
 371   note: >
 372     The text will be normalized, so the resulting text's codepoints may not
 373     exactly match the input codepoints.
 374   return:
 375     type: '[Text]'
 376     description: >
 377       A new text with the specified codepoints after normalization has been applied.
 378       Any invalid names are ignored.
 379   args:
 380     codepoint_names:
 381       type: '[Text]'
 382       description: >
 383         The names of each codepoint in the desired text (case-insentive).
 384   example: |
 385     text := Text.from_codepoint_names([
 386         "LATIN CAPITAL LETTER A WITH RING ABOVE",
 387         "LATIN SMALL LETTER K",
 388         "LATIN SMALL LETTER E",
 389     ])
 390     assert text == "Åke"
 391 
 392 Text.from_utf32:
 393   short: convert UTF32 codepoints to text
 394   description: >
 395     Returns text that has been constructed from the given UTF32 codepoints.
 396   note: >
 397     The text will be normalized, so the resulting text's codepoints may not
 398     exactly match the input codepoints.
 399   return:
 400     type: '[Text]'
 401     description: >
 402       A new text with the specified codepoints after normalization has been applied.
 403   args:
 404     codepoints:
 405       type: '[Int32]'
 406       description: >
 407         The UTF32 codepoints in the desired text.
 408   example: |
 409     assert Text.from_utf32([197, 107, 101]) == "Åke"
 410 
 411 Text.has:
 412   short: check for substring
 413   description: >
 414     Checks if the `Text` contains some target text.
 415   return:
 416     type: 'Bool'
 417     description: >
 418       `yes` if the target text is found, `no` otherwise.
 419   args:
 420     text:
 421       type: 'Text'
 422       description: >
 423         The text to be searched.
 424     target:
 425       type: 'Text'
 426       description: >
 427         The text to search for.
 428   example: |
 429     assert "hello world".has("wo") == yes
 430     assert "hello world".has("xxx") == no
 431 
 432 Text.join:
 433   short: concatenate with separator
 434   description: >
 435     Joins a list of text pieces with a specified glue.
 436   return:
 437     type: 'Text'
 438     description: >
 439       A single `Text` value with the pieces joined by the glue.
 440   args:
 441     glue:
 442       type: 'Text'
 443       description: >
 444         The text used to join the pieces.
 445     pieces:
 446       type: '[Text]'
 447       description: >
 448         The list of text pieces to be joined.
 449   example: |
 450     assert ", ".join(["one", "two", "three"]) == "one, two, three"
 451 
 452 Text.matches_glob:
 453   short: check if text matches a glob
 454   description: >
 455     Return whether or not the text matches the given glob.
 456   return:
 457     type: 'Bool'
 458     description: >
 459       Whether or not the text matches the given glob.
 460   args:
 461     path:
 462       type: 'Text'
 463       description: >
 464         The text to check.
 465     glob:
 466       type: 'Text'
 467       description: >
 468         The glob pattern to check.
 469   example: |
 470     assert "hello world".matches_glob("h* *d")
 471 
 472 Text.middle_pad:
 473   short: pad text, centered
 474   description: >
 475     Pad some text on the left and right side so it reaches a target width.
 476   return:
 477     type: 'Text'
 478     description: >
 479       Text with length at least `width`, with extra padding on the left and right as
 480       needed. If `pad` has length greater than 1, it may be partially repeated to
 481       reach the exact desired length.
 482   args:
 483     text:
 484       type: 'Text'
 485       description: >
 486         The text to pad.
 487     width:
 488       type: 'Int'
 489       description: >
 490         The target width.
 491     pad:
 492       type: 'Text'
 493       default: '" "'
 494       description: >
 495         The padding text.
 496     language:
 497       type: 'Text'
 498       default: '"C"'
 499       description: >
 500         The ISO 639 language code for which character width to use.
 501   example: |
 502     assert "x".middle_pad(6) == "  x   "
 503     assert "x".middle_pad(10, "ABC") == "ABCAxABCAB"
 504 
 505 Text.left_pad:
 506   short: left-pad text
 507   description: >
 508     Pad some text on the left side so it reaches a target width.
 509   return:
 510     type: 'Text'
 511     description: >
 512       Text with length at least `width`, with extra padding on the left as needed. If
 513       `pad` has length greater than 1, it may be partially repeated to reach the
 514       exact desired length.
 515   args:
 516     text:
 517       type: 'Text'
 518       description: >
 519         The text to pad.
 520     width:
 521       type: 'Int'
 522       description: >
 523         The target width.
 524     pad:
 525       type: 'Text'
 526       default: '" "'
 527       description: >
 528         The padding text.
 529     language:
 530       type: 'Text'
 531       default: '"C"'
 532       description: >
 533         The ISO 639 language code for which character width to use.
 534   example: |
 535     assert "x".left_pad(5) == "    x"
 536     assert "x".left_pad(5, "ABC") == "ABCAx"
 537 
 538 Text.lines:
 539   short: get list of lines
 540   description: >
 541     Splits the text into a list of lines of text, preserving blank lines,
 542     ignoring trailing newlines, and handling `\r\n` the same as `\n`.
 543   return:
 544     type: '[Text]'
 545     description: >
 546       A list of substrings resulting from the split.
 547   args:
 548     text:
 549       type: 'Text'
 550       description: >
 551         The text to be split into lines.
 552   example: |
 553     assert "one\ntwo\nthree".lines() == ["one", "two", "three"]
 554     assert "one\ntwo\nthree\n".lines() == ["one", "two", "three"]
 555     assert "one\ntwo\nthree\n\n".lines() == ["one", "two", "three", ""]
 556     assert "one\r\ntwo\r\nthree\r\n".lines() == ["one", "two", "three"]
 557     assert "".lines() == []
 558 
 559 Text.lower:
 560   short: convert to lowercase
 561   description: >
 562     Converts all characters in the text to lowercase.
 563   return:
 564     type: 'Text'
 565     description: >
 566       The lowercase version of the text.
 567   args:
 568     text:
 569       type: 'Text'
 570       description: >
 571         The text to be converted to lowercase.
 572     language:
 573       type: 'Text'
 574       default: '"C"'
 575       description: >
 576         The ISO 639 language code for which casing rules to use.
 577   example: |
 578     assert "AMÉLIE".lower() == "amélie"
 579     assert "I".lower(language="tr_TR") == "ı"
 580 
 581 Text.quoted:
 582   short: add quotation marks and escapes
 583   description: >
 584     Formats the text with quotation marks and escapes.
 585   return:
 586     type: 'Text'
 587     description: >
 588       The text formatted as a quoted text.
 589   args:
 590     text:
 591       type: 'Text'
 592       description: >
 593         The text to be quoted.
 594     color:
 595       type: 'Bool'
 596       default: 'no'
 597       description: >
 598         Whether to add color formatting.
 599     quotation_mark:
 600       type: 'Text'
 601       default: '`"`'
 602       description: >
 603         The quotation mark to use.
 604   example: |
 605     assert "one\ntwo".quoted() == "\"one\\ntwo\""
 606 
 607 Text.repeat:
 608   short: repeat text
 609   description: >
 610     Repeat some text multiple times.
 611   return:
 612     type: 'Text'
 613     description: >
 614       The text repeated the given number of times.
 615   args:
 616     text:
 617       type: 'Text'
 618       description: >
 619         The text to repeat.
 620     count:
 621       type: 'Int'
 622       description: >
 623         The number of times to repeat it. (Negative numbers are equivalent to zero).
 624   example: |
 625     assert "Abc".repeat(3) == "AbcAbcAbc"
 626 
 627 Text.replace:
 628   short: replace a substring
 629   description: >
 630     Replaces occurrences of a target text with a replacement text.
 631   return:
 632     type: 'Text'
 633     description: >
 634       The text with occurrences of the target replaced.
 635   args:
 636     text:
 637       type: 'Text'
 638       description: >
 639         The text in which to perform replacements.
 640     target:
 641       type: 'Text'
 642       description: >
 643         The target text to be replaced.
 644     replacement:
 645       type: 'Text'
 646       description: >
 647         The text to replace the target with.
 648   example: |
 649     assert "Hello world".replace("world", "there") == "Hello there"
 650 
 651 Text.reversed:
 652   short: get a reversed copy
 653   description: >
 654     Return a text that has the grapheme clusters in reverse order.
 655   return:
 656     type: 'Text'
 657     description: >
 658       A reversed version of the text.
 659   args:
 660     text:
 661       type: 'Text'
 662       description: >
 663         The text to reverse.
 664   example: |
 665     assert "Abc".reversed() == "cbA"
 666 
 667 Text.right_pad:
 668   short: right-pad text
 669   description: >
 670     Pad some text on the right side so it reaches a target width.
 671   return:
 672     type: 'Text'
 673     description: >
 674       Text with length at least `width`, with extra padding on the right as needed. If
 675       `pad` has length greater than 1, it may be partially repeated to reach the
 676       exact desired length.
 677   args:
 678     text:
 679       type: 'Text'
 680       description: >
 681         The text to pad.
 682     width:
 683       type: 'Int'
 684       description: >
 685         The target width.
 686     pad:
 687       type: 'Text'
 688       default: '" "'
 689       description: >
 690         The padding text.
 691     language:
 692       type: 'Text'
 693       default: '"C"'
 694       description: >
 695         The ISO 639 language code for which character width to use.
 696   example: |
 697     assert "x".right_pad(5) == "x    "
 698     assert "x".right_pad(5, "ABC") == "xABCA"
 699 
 700 Text.slice:
 701   short: get a slice of a text
 702   description: >
 703     Get a slice of the text.
 704   return:
 705     type: 'Text'
 706     description: >
 707       The text that spans the given grapheme cluster indices.
 708   note: >
 709     A negative index counts backwards from the end of the text, so `-1` refers
 710     to the last cluster, `-2` the second-to-last, etc. Slice ranges will be
 711     truncated to the length of the text.
 712   args:
 713     text:
 714       type: 'Text'
 715       description: >
 716         The text to be sliced.
 717     from:
 718       type: 'Int'
 719       default: '1'
 720       description: >
 721         The index of the first grapheme cluster to include (1-indexed).
 722     to:
 723       type: 'Int'
 724       default: '-1'
 725       description: >
 726         The index of the last grapheme cluster to include (1-indexed).
 727   example: |
 728     assert "hello".slice(2, 3) == "el"
 729     assert "hello".slice(to=-2) == "hell"
 730     assert "hello".slice(from=2) == "ello"
 731 
 732 Text.split:
 733   short: split a text by a delimiter
 734   description: >
 735     Splits the text into a list of substrings based on exact matches of a delimiter.
 736   return:
 737     type: '[Text]'
 738     description: >
 739       A list of subtexts resulting from the split.
 740   args:
 741     text:
 742       type: 'Text'
 743       description: >
 744         The text to be split.
 745     delimiter:
 746       type: 'Text'
 747       default: '""'
 748       description: >
 749         The delimiter used to split the text.
 750   note: >
 751     To split based on a set of delimiters, use Text.split_any().
 752 
 753     If an empty text is given as the delimiter, then each split will be the
 754     graphical clusters of the text.
 755 
 756   example: |
 757     assert "one,two,,three".split(",") == ["one", "two", "", "three"]
 758     assert "abc".split() == ["a", "b", "c"]
 759 
 760 Text.split_any:
 761   short: split a text by multiple delimiters
 762   description: >
 763     Splits the text into a list of substrings at one or more occurrences of a set
 764     of delimiter characters (grapheme clusters).
 765   return:
 766     type: '[Text]'
 767     description: >
 768       A list of subtexts resulting from the split.
 769   args:
 770     text:
 771       type: 'Text'
 772       description: >
 773         The text to be split.
 774     delimiters:
 775       type: 'Text'
 776       default: '" $\t\r\n"'
 777       description: >
 778         A text containing delimiters to use for splitting the text.
 779   note: >
 780     Splitting will occur on every place where one or more of the grapheme
 781     clusters in `delimiters` occurs.
 782 
 783     To split based on an exact delimiter, use Text.split().
 784   example: |
 785     assert "one, two,,three".split_any(", ") == ["one", "two", "three"]
 786 
 787 Text.starts_with:
 788   short: check prefix
 789   description: >
 790     Checks if the `Text` starts with a literal prefix text.
 791   return:
 792     type: 'Bool'
 793     description: >
 794       `yes` if the text has the given prefix, `no` otherwise.
 795   args:
 796     text:
 797       type: 'Text'
 798       description: >
 799         The text to be searched.
 800     prefix:
 801       type: 'Text'
 802       description: >
 803         The literal prefix text to check for.
 804     remainder:
 805       type: '&Text?'
 806       default: 'none'
 807       description: >
 808         If non-none, this value will be set to the rest of the text after the prefix.
 809         If the prefix is not found, this value will be set to the original text.
 810   example: |
 811     assert "hello world".starts_with("hello") == yes
 812     remainder : Text
 813     assert "hello world".starts_with("hello", &remainder) == yes
 814     assert remainder == " world"
 815 
 816 Text.title:
 817   short: titlecase
 818   description: >
 819     Converts the text to title case (capitalizing the first letter of each word).
 820   return:
 821     type: 'Text'
 822     description: >
 823       The text in title case.
 824   args:
 825     text:
 826       type: 'Text'
 827       description: >
 828         The text to be converted to title case.
 829     language:
 830       type: 'Text'
 831       default: '"C"'
 832       description: >
 833         The ISO 639 language code for which casing rules to use.
 834   example: |
 835     assert "amélie".title() == "Amélie"
 836 
 837     # In Turkish, uppercase "i" is "İ"
 838     assert "i".title(language="tr_TR") == "İ"
 839 
 840 Text.to:
 841   short: slice to an end index
 842   description: >
 843     Get a slice of the text, ending at the given position.
 844   return:
 845     type: 'Text'
 846     description: >
 847       The text up to and including the given grapheme cluster.
 848   note: >
 849     A negative index counts backwards from the end of the text, so `-1` refers
 850     to the last cluster, `-2` the second-to-last, etc. Slice ranges will be
 851     truncated to the length of the text.
 852   args:
 853     text:
 854       type: 'Text'
 855       description: >
 856         The text to be sliced.
 857     last:
 858       type: 'Int'
 859       description: >
 860         The index of the last grapheme cluster to include (1-indexed).
 861   example: |
 862     assert "goodbye".to(3) == "goo"
 863     assert "goodbye".to(-2) == "goodby"
 864 
 865 Text.translate:
 866   short: perform multiple replacements
 867   description: >
 868     Takes a table mapping target texts to their replacements and performs all the
 869     replacements in the table on the whole text. At each position, the first
 870     matching replacement is applied and the matching moves on to *after* the
 871     replacement text, so replacement text is not recursively modified. See
 872     Text.replace() for more information about replacement behavior.
 873   return:
 874     type: 'Text'
 875     description: >
 876       The text with all occurrences of the targets replaced with their corresponding
 877       replacement text.
 878   args:
 879     text:
 880       type: 'Text'
 881       description: >
 882         The text to be translated.
 883     translations:
 884       type: '{Text:Text}'
 885       description: >
 886         A table mapping from target text to its replacement.
 887   example: |
 888     text := "A <tag> & an ampersand".translate({
 889         "&": "&amp;",
 890         "<": "&lt;",
 891         ">": "&gt;",
 892         '"': "&quot",
 893         "'": "&#39;",
 894     })
 895     assert text == "A &lt;tag&gt; &amp; an ampersand"
 896 
 897 Text.trim:
 898   short: trim characters
 899   description: >
 900     Trims the given characters (grapheme clusters) from the left and/or right side of the text.
 901   return:
 902     type: 'Text'
 903     description: >
 904       The text without the trim characters at either end.
 905   args:
 906     text:
 907       type: 'Text'
 908       description: >
 909         The text to be trimmed.
 910     to_trim:
 911       type: 'Text'
 912       default: '" $\t\r\n"'
 913       description: >
 914         The characters to remove from the left/right of the text.
 915     left:
 916       type: 'Bool'
 917       default: 'yes'
 918       description: >
 919         Whether or not to trim from the front of the text.
 920     right:
 921       type: 'Bool'
 922       default: 'yes'
 923       description: >
 924         Whether or not to trim from the back of the text.
 925   example: |
 926     assert "   x y z    \n".trim() == "x y z"
 927     assert "one,".trim(",") == "one"
 928     assert "   xyz   ".trim(right=no) == "xyz   "
 929 
 930 Text.upper:
 931   short: uppercase
 932   description: >
 933     Converts all characters in the text to uppercase.
 934   return:
 935     type: 'Text'
 936     description: >
 937       The uppercase version of the text.
 938   args:
 939     text:
 940       type: 'Text'
 941       description: >
 942         The text to be converted to uppercase.
 943     language:
 944       type: 'Text'
 945       default: '"C"'
 946       description: >
 947         The ISO 639 language code for which casing rules to use.
 948   example: |
 949     assert "amélie".upper() == "AMÉLIE"
 950 
 951     # In Turkish, uppercase "i" is "İ"
 952     assert "i".upper(language="tr_TR") == "İ"
 953 
 954 Text.utf16:
 955   short: get UTF16 codepoints
 956   description: >
 957     Returns a list of Unicode code points for UTF16 encoding of the text.
 958   return:
 959     type: '[Int16]'
 960     description: >
 961       A list of 16-bit integer Unicode code points (`[Int16]`).
 962   args:
 963     text:
 964       type: 'Text'
 965       description: >
 966         The text from which to extract Unicode code points.
 967   example: |
 968     assert "Åke".utf16() == [197, 107, 101]
 969     assert "こんにちは世界".utf16() == [12371, 12435, 12395, 12385, 12399, 19990, 30028]
 970 
 971 Text.utf32:
 972   short: get UTF32 codepoints
 973   description: >
 974     Returns a list of Unicode code points for UTF32 encoding of the text.
 975   return:
 976     type: '[Int32]'
 977     description: >
 978       A list of 32-bit integer Unicode code points (`[Int32]`).
 979   args:
 980     text:
 981       type: 'Text'
 982       description: >
 983         The text from which to extract Unicode code points.
 984   example: |
 985     assert "Amélie".utf32() == [65, 109, 233, 108, 105, 101]
 986 
 987 Text.width:
 988   short: get display width
 989   description: >
 990     Returns the display width of the text as seen in a terminal with appropriate
 991     font rendering. This is usually the same as the text's `.length`, but there are
 992     some characters like emojis that render wider than 1 cell.
 993   note: >
 994     This will not always be exactly accurate when your terminal's font
 995     rendering can't handle some unicode displaying correctly.
 996   return:
 997     type: 'Int'
 998     description: >
 999       An integer representing the display width of the text.
1000   args:
1001     text:
1002       type: 'Text'
1003       description: >
1004         The text whose length you want.
1005   example: |
1006     assert "Amélie".width() == 6
1007     assert "🤠".width() == 2
1008 
1009 Text.without_prefix:
1010   short: remove prefix
1011   description: >
1012     Returns the text with a given prefix removed (if present).
1013   return:
1014     type: 'Text'
1015     description: >
1016       A text without the given prefix (if present) or the unmodified text if the
1017       prefix is not present.
1018   args:
1019     text:
1020       type: 'Text'
1021       description: >
1022         The text to remove the prefix from.
1023     prefix:
1024       type: 'Text'
1025       description: >
1026         The prefix to remove.
1027   example: |
1028     assert "foo:baz".without_prefix("foo:") == "baz"
1029     assert "qux".without_prefix("foo:") == "qux"
1030 
1031 Text.without_suffix:
1032   short: remove suffix
1033   description: >
1034     Returns the text with a given suffix removed (if present).
1035   return:
1036     type: 'Text'
1037     description: >
1038       A text without the given suffix (if present) or the unmodified text if the
1039       suffix is not present.
1040   args:
1041     text:
1042       type: 'Text'
1043       description: >
1044         The text to remove the suffix from.
1045     suffix:
1046       type: 'Text'
1047       description: >
1048         The suffix to remove.
1049   example: |
1050     assert "baz.foo".without_suffix(".foo") == "baz"
1051     assert "qux".without_suffix(".foo") == "qux"
1052