Document formatters (and remove splitstring)

royalnet/utils/__init__.py

@@ -1,24 +1,18 @@
 from .asyncify import asyncify
 from .safeformat import safeformat
 from .sleep_until import sleep_until
-from .formatters import andformat, underscorize, ytdldateformat, numberemojiformat, splitstring, ordinalformat
+from .formatters import andformat, underscorize, ytdldateformat, numberemojiformat, ordinalformat
 from .urluuid import to_urluuid, from_urluuid
 from .multilock import MultiLock
 
 __all__ = [
     "asyncify",
     "safeformat",
-    "cdj",
     "sleep_until",
-    "plusformat",
     "andformat",
-    "plusformat",
     "underscorize",
     "ytdldateformat",
     "numberemojiformat",
-    "telegram_escape",
-    "discord_escape",
-    "splitstring",
     "ordinalformat",
     "to_urluuid",
     "from_urluuid",

royalnet/utils/formatters.py

@@ -80,6 +80,21 @@ def ytdldateformat(string: typing.Optional[str], separator: str = "-") -> str:
 
 
 def numberemojiformat(l: typing.List[str]) -> str:
+    """Convert a :class:`list` to a Unicode string with one item on every line numbered with emojis.
+
+    Parameters:
+        l: the list to convert.
+
+    Returns:
+        The resulting Unicode string.
+
+    Examples:
+        ::
+            >>> numberemojiformat(["First", "Second", "Third"])
+            "1️⃣ First\n2️⃣ Second\n3️⃣ Third\n"
+            >>> numberemojiformat(list(range(13)))
+            "1️⃣ 1\n2️⃣ 2\n3️⃣ 3\n4️⃣ 4\n5️⃣ 5\n6️⃣ 6\n7️⃣ 7\n8️⃣ 8\n9️⃣ 9\n🔟 10\n*️⃣ 11\n*️⃣ 12"
+    """
     number_emojis = ["1️⃣", "2️⃣", "3️⃣", "4️⃣", "5️⃣", "6️⃣", "7️⃣", "8️⃣", "9️⃣", "🔟"]
     extra_emoji = "*️⃣"
     result = ""
@@ -91,15 +106,30 @@ def numberemojiformat(l: typing.List[str]) -> str:
     return result
 
 
-def splitstring(s: str, max: int) -> typing.List[str]:
-    l = []
-    while s:
-        l.append(s[:max])
-        s = s[max:]
-    return l
+def ordinalformat(number: int) -> str:
+    """Convert a :class:`int` to the corresponding English ordinal :class:`str`.
 
+    Parameters:
+        number: the number to convert.
 
-def ordinalformat(number: int):
+    Returns:
+        The corresponding English `ordinal numeral <https://en.wikipedia.org/wiki/Ordinal_numeral>`.
+
+    Examples:
+        ::
+            >>> ordinalformat(1)
+            "1st"
+            >>> ordinalformat(2)
+            "2nd"
+            >>> ordinalformat(11)
+            "11th"
+            >>> ordinalformat(101)
+            "101st"
+            >>> ordinalformat(112)
+            "112th"
+            >>> ordinalformat(0)
+            "0th"
+    """
     if 10 <= number % 100 < 20:
         return f"{number}th"
     if number % 10 == 1: