Update docs with proper assertions

1 files changed, 77 insertions, 141 deletions

diff --git a/api/text.yaml b/api/text.yaml
index dcdcfb67..2c21fa30 100644
--- a/api/text.yaml
+++ b/api/text.yaml
@@ -12,8 +12,7 @@ Text.as_c_string:
       description: >
         The text to be converted to a C-style string.
   example: |
-    >> "Hello".as_c_string()
-    = CString("Hello")
+    assert "Hello".as_c_string() == CString("Hello")
 
 Text.at:
   short: get a letter
@@ -37,8 +36,7 @@ Text.at:
       description: >
         The index of the graphical cluster (1-indexed).
   example: |
-    >> "Amélie".at(3)
-    = "é"
+    assert "Amélie".at(3) == "é"
 
 Text.by_line:
   short: iterate by line
@@ -144,8 +142,7 @@ Text.utf8:
       description: >
         The text to be converted to UTF8 bytes.
   example: |
-    >> "Amélie".utf8()
-    = [65, 109, 195, 169, 108, 105, 101]
+    assert "Amélie".utf8() == [65, 109, 195, 169, 108, 105, 101]
 
 Text.caseless_equals:
   short: case-insensitive comparison
@@ -171,12 +168,10 @@ Text.caseless_equals:
       description: >
         The ISO 639 language code for which casing rules to use.
   example: |
-    >> "A".caseless_equals("a")
-    = yes
+    assert "A".caseless_equals("a") == yes
 
     # Turkish lowercase "I" is "ı" (dotless I), not "i"
-    >> "I".caseless_equals("i", language="tr_TR")
-    = no
+    assert "I".caseless_equals("i", language="tr_TR") == no
 
 Text.codepoint_names:
   short: get unicode codepoint names
@@ -192,8 +187,14 @@ Text.codepoint_names:
       description: >
         The text from which to extract codepoint names.
   example: |
-    >> "Amélie".codepoint_names()
-    = ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"]
+    assert "Amélie".codepoint_names() == [
+        "LATIN CAPITAL LETTER A",
+        "LATIN SMALL LETTER M",
+        "LATIN SMALL LETTER E WITH ACUTE",
+        "LATIN SMALL LETTER L",
+        "LATIN SMALL LETTER I",
+        "LATIN SMALL LETTER E",
+    ]
 
 Text.ends_with:
   short: check suffix
@@ -219,13 +220,10 @@ Text.ends_with:
         If non-none, this value will be set to the rest of the text up to the trailing suffix.
         If the suffix is not found, this value will be set to the original text.
   example: |
-    >> "hello world".ends_with("world")
-    = yes
+    assert "hello world".ends_with("world") == yes
     remainder : Text
-    >> "hello world".ends_with("world", &remainder)
-    = yes
-    >> remainder
-    = "hello "
+    assert "hello world".ends_with("world", &remainder) == yes
+    assert remainder == "hello "
 
 Text.from:
   short: slice from a starting index
@@ -249,11 +247,8 @@ Text.from:
       description: >
         The index to begin the slice.
   example: |
-    >> "hello".from(2)
-    = "ello"
-
-    >> "hello".from(-2)
-    = "lo"
+    assert "hello".from(2) == "ello"
+    assert "hello".from(-2) == "lo"
 
 Text.from_utf8:
   short: convert UTF8 byte list to text
@@ -272,8 +267,7 @@ Text.from_utf8:
       description: >
         The UTF-8 bytes of the desired text.
   example: |
-    >> Text.from_utf8([195, 133, 107, 101])
-    = "Åke"
+    assert Text.from_utf8([195, 133, 107, 101]) == "Åke"
 
 Text.from_utf16:
   short: convert UTF16 list to text
@@ -292,10 +286,8 @@ Text.from_utf16:
       description: >
         The UTF-16 integers of the desired text.
   example: |
-    >> Text.from_utf16([197, 107, 101])
-    = "Åke"
-    >> Text.from_utf16([12371, 12435, 12395, 12385, 12399, 19990, 30028])
-    = "こんにちは世界".utf16()
+    assert Text.from_utf16([197, 107, 101]) == "Åke"
+    assert Text.from_utf16([12371, 12435, 12395, 12385, 12399, 19990, 30028]) == "こんにちは世界".utf16()
 
 Text.from_c_string:
   short: convert C-style string to text
@@ -311,8 +303,7 @@ Text.from_c_string:
       description: >
         The C-style string to be converted.
   example: |
-    >> Text.from_c_string(CString("Hello"))
-    = "Hello"
+    assert Text.from_c_string(CString("Hello")) == "Hello"
 
 Text.from_codepoint_names:
   short: convert list of unicode codepoint names to text
@@ -333,12 +324,12 @@ Text.from_codepoint_names:
       description: >
         The names of each codepoint in the desired text (case-insentive).
   example: |
-    >> Text.from_codepoint_names([
-    "LATIN CAPITAL LETTER A WITH RING ABOVE",
-    "LATIN SMALL LETTER K",
-    "LATIN SMALL LETTER E",
+    text := Text.from_codepoint_names([
+        "LATIN CAPITAL LETTER A WITH RING ABOVE",
+        "LATIN SMALL LETTER K",
+        "LATIN SMALL LETTER E",
     ]
-    = "Åke"
+    assert text == "Åke"
 
 Text.from_utf32:
   short: convert UTF32 codepoints to text
@@ -357,8 +348,7 @@ Text.from_utf32:
       description: >
         The UTF32 codepoints in the desired text.
   example: |
-    >> Text.from_utf32([197, 107, 101])
-    = "Åke"
+    assert Text.from_utf32([197, 107, 101]) == "Åke"
 
 Text.has:
   short: check for substring
@@ -378,10 +368,8 @@ Text.has:
       description: >
         The text to search for.
   example: |
-    >> "hello world".has("wo")
-    = yes
-    >> "hello world".has("xxx")
-    = no
+    assert "hello world".has("wo") == yes
+    assert "hello world".has("xxx") == no
 
 Text.join:
   short: concatenate with separator
@@ -401,8 +389,7 @@ Text.join:
       description: >
         The list of text pieces to be joined.
   example: |
-    >> ", ".join(["one", "two", "three"])
-    = "one, two, three"
+    assert ", ".join(["one", "two", "three"]) == "one, two, three"
 
 Text.middle_pad:
   short: pad text, centered
@@ -434,10 +421,8 @@ Text.middle_pad:
       description: >
         The ISO 639 language code for which character width to use.
   example: |
-    >> "x".middle_pad(6)
-    = "  x   "
-    >> "x".middle_pad(10, "ABC")
-    = "ABCAxABCAB"
+    assert "x".middle_pad(6) == "  x   "
+    assert "x".middle_pad(10, "ABC") == "ABCAxABCAB"
 
 Text.left_pad:
   short: left-pad text
@@ -469,10 +454,8 @@ Text.left_pad:
       description: >
         The ISO 639 language code for which character width to use.
   example: |
-    >> "x".left_pad(5)
-    = "    x"
-    >> "x".left_pad(5, "ABC")
-    = "ABCAx"
+    assert "x".left_pad(5) == "    x"
+    assert "x".left_pad(5, "ABC") == "ABCAx"
 
 Text.lines:
   short: get list of lines
@@ -489,16 +472,11 @@ Text.lines:
       description: >
         The text to be split into lines.
   example: |
-    >> "one\ntwo\nthree".lines()
-    = ["one", "two", "three"]
-    >> "one\ntwo\nthree\n".lines()
-    = ["one", "two", "three"]
-    >> "one\ntwo\nthree\n\n".lines()
-    = ["one", "two", "three", ""]
-    >> "one\r\ntwo\r\nthree\r\n".lines()
-    = ["one", "two", "three"]
-    >> "".lines()
-    = []
+    assert "one\ntwo\nthree".lines() == ["one", "two", "three"]
+    assert "one\ntwo\nthree\n".lines() == ["one", "two", "three"]
+    assert "one\ntwo\nthree\n\n".lines() == ["one", "two", "three", ""]
+    assert "one\r\ntwo\r\nthree\r\n".lines() == ["one", "two", "three"]
+    assert "".lines() == []
 
 Text.lower:
   short: convert to lowercase
@@ -519,11 +497,8 @@ Text.lower:
       description: >
         The ISO 639 language code for which casing rules to use.
   example: |
-    >> "AMÉLIE".lower()
-    = "amélie"
-
-    >> "I".lower(language="tr_TR")
-    >> "ı"
+    assert "AMÉLIE".lower() == "amélie"
+    assert "I".lower(language="tr_TR") == "ı"
 
 Text.quoted:
   short: add quotation marks and escapes
@@ -549,8 +524,7 @@ Text.quoted:
       description: >
         The quotation mark to use.
   example: |
-    >> "one\ntwo".quoted()
-    = "\"one\\ntwo\""
+    assert "one\ntwo".quoted() == "\"one\\ntwo\""
 
 Text.repeat:
   short: repeat text
@@ -570,8 +544,7 @@ Text.repeat:
       description: >
         The number of times to repeat it. (Negative numbers are equivalent to zero).
   example: |
-    >> "Abc".repeat(3)
-    = "AbcAbcAbc"
+    assert "Abc".repeat(3) == "AbcAbcAbc"
 
 Text.replace:
   short: replace a substring
@@ -595,8 +568,7 @@ Text.replace:
       description: >
         The text to replace the target with.
   example: |
-    >> "Hello world".replace("world", "there")
-    = "Hello there"
+    assert "Hello world".replace("world", "there") == "Hello there"
 
 Text.reversed:
   short: get a reversed copy
@@ -612,8 +584,7 @@ Text.reversed:
       description: >
         The text to reverse.
   example: |
-    >> "Abc".reversed()
-    = "cbA"
+    assert "Abc".reversed() == "cbA"
 
 Text.right_pad:
   short: right-pad text
@@ -645,10 +616,8 @@ Text.right_pad:
       description: >
         The ISO 639 language code for which character width to use.
   example: |
-    >> "x".right_pad(5)
-    = "x    "
-    >> "x".right_pad(5, "ABC")
-    = "xABCA"
+    assert "x".right_pad(5) == "x    "
+    assert "x".right_pad(5, "ABC") == "xABCA"
 
 Text.slice:
   short: get a slice of a text
@@ -678,14 +647,9 @@ Text.slice:
       description: >
         The index of the last grapheme cluster to include (1-indexed).
   example: |
-    >> "hello".slice(2, 3)
-    = "el"
-
-    >> "hello".slice(to=-2)
-    = "hell"
-
-    >> "hello".slice(from=2)
-    = "ello"
+    assert "hello".slice(2, 3) == "el"
+    assert "hello".slice(to=-2) == "hell"
+    assert "hello".slice(from=2) == "ello"
 
 Text.split:
   short: split a text by a delimiter
@@ -712,11 +676,8 @@ Text.split:
     graphical clusters of the text.
 
   example: |
-    >> "one,two,,three".split(",")
-    = ["one", "two", "", "three"]
-
-    >> "abc".split()
-    = ["a", "b", "c"]
+    assert "one,two,,three".split(",") == ["one", "two", "", "three"]
+    assert "abc".split() == ["a", "b", "c"]
 
 Text.split_any:
   short: split a text by multiple delimiters
@@ -743,8 +704,7 @@ Text.split_any:
 
     To split based on an exact delimiter, use Text.split().
   example: |
-    >> "one, two,,three".split_any(", ")
-    = ["one", "two", "three"]
+    assert "one, two,,three".split_any(", ") == ["one", "two", "three"]
 
 Text.starts_with:
   short: check prefix
@@ -770,13 +730,10 @@ Text.starts_with:
         If non-none, this value will be set to the rest of the text after the prefix.
         If the prefix is not found, this value will be set to the original text.
   example: |
-    >> "hello world".starts_with("hello")
-    = yes
+    assert "hello world".starts_with("hello") == yes
     remainder : Text
-    >> "hello world".starts_with("hello", &remainder)
-    = yes
-    >> remainder
-    = " world"
+    assert "hello world".starts_with("hello", &remainder) == yes
+    assert remainder == " world"
 
 Text.title:
   short: titlecase
@@ -797,12 +754,10 @@ Text.title:
       description: >
         The ISO 639 language code for which casing rules to use.
   example: |
-    >> "amélie".title()
-    = "Amélie"
+    assert "amélie".title() == "Amélie"
 
     # In Turkish, uppercase "i" is "İ"
-    >> "i".title(language="tr_TR")
-    = "İ"
+    assert "i".title(language="tr_TR") == "İ"
 
 Text.to:
   short: slice to an end index
@@ -826,11 +781,8 @@ Text.to:
       description: >
         The index of the last grapheme cluster to include (1-indexed).
   example: |
-    >> "goodbye".to(3)
-    = "goo"
-
-    >> "goodbye".to(-2)
-    = "goodby"
+    assert "goodbye".to(3) == "goo"
+    assert "goodbye".to(-2) == "goodby"
 
 Text.translate:
   short: perform multiple replacements
@@ -855,14 +807,14 @@ Text.translate:
       description: >
         A table mapping from target text to its replacement.
   example: |
-    >> "A <tag> & an amperand".translate({
+    text := "A <tag> & an amperand".translate({
         "&": "&amp;",
         "<": "&lt;",
         ">": "&gt;",
         '"": "&quot",
         "'": "&#39;",
     })
-    = "A &lt;tag&gt; &amp; an ampersand"
+    assert text == "A &lt;tag&gt; &amp; an ampersand"
 
 Text.trim:
   short: trim characters
@@ -893,14 +845,9 @@ Text.trim:
       description: >
         Whether or not to trim from the back of the text.
   example: |
-    >> "   x y z    \n".trim()
-    = "x y z"
-
-    >> "one,".trim(",")
-    = "one"
-
-    >> "   xyz   ".trim(right=no)
-    = "xyz   "
+    assert "   x y z    \n".trim() == "x y z"
+    assert "one,".trim(",") == "one"
+    assert "   xyz   ".trim(right=no) == "xyz   "
 
 Text.upper:
   short: uppercase
@@ -921,12 +868,10 @@ Text.upper:
       description: >
         The ISO 639 language code for which casing rules to use.
   example: |
-    >> "amélie".upper()
-    = "AMÉLIE"
+    assert "amélie".upper() == "AMÉLIE"
 
     # In Turkish, uppercase "i" is "İ"
-    >> "i".upper(language="tr_TR")
-    = "İ"
+    assert "i".upper(language="tr_TR") == "İ"
 
 Text.utf16:
   short: get UTF16 codepoints
@@ -942,10 +887,8 @@ Text.utf16:
       description: >
         The text from which to extract Unicode code points.
   example: |
-    >> "Åke".utf16()
-    = [197, 107, 101]
-    >> "こんにちは世界".utf16()
-    = [12371, 12435, 12395, 12385, 12399, 19990, 30028]
+    assert "Åke".utf16() == [197, 107, 101]
+    assert "こんにちは世界".utf16() == [12371, 12435, 12395, 12385, 12399, 19990, 30028]
 
 Text.utf32:
   short: get UTF32 codepoints
@@ -961,8 +904,7 @@ Text.utf32:
       description: >
         The text from which to extract Unicode code points.
   example: |
-    >> "Amélie".utf32()
-    = [65, 109, 233, 108, 105, 101]
+    assert "Amélie".utf32() == [65, 109, 233, 108, 105, 101]
 
 Text.width:
   short: get display width
@@ -983,10 +925,8 @@ Text.width:
       description: >
         The text whose length you want.
   example: |
-    >> "Amélie".width()
-    = 6
-    >> "🤠".width()
-    = 2
+    assert "Amélie".width() == 6
+    assert "🤠".width() == 2
 
 Text.without_prefix:
   short: remove prefix
@@ -1007,10 +947,8 @@ Text.without_prefix:
       description: >
         The prefix to remove.
   example: |
-    >> "foo:baz".without_prefix("foo:")
-    = "baz"
-    >> "qux".without_prefix("foo:")
-    = "qux"
+    assert "foo:baz".without_prefix("foo:") == "baz"
+    assert "qux".without_prefix("foo:") == "qux"
 
 Text.without_suffix:
   short: remove suffix
@@ -1031,8 +969,6 @@ Text.without_suffix:
       description: >
         The suffix to remove.
   example: |
-    >> "baz.foo".without_suffix(".foo")
-    = "baz"
-    >> "qux".without_suffix(".foo")
-    = "qux"
+    assert "baz.foo".without_suffix(".foo") == "baz"
+    assert "qux".without_suffix(".foo") == "qux"