docs revamp

docs/library/text.md

@@ -0,0 +1,123 @@
+# text
+
+The `text` function and its methods handle string conversion and manipulation.
+
+## Conversion
+
+### text(array, separator)
+
+Convert an array to text, joining elements with a separator (default: space).
+
+```javascript
+text([1, 2, 3])           // "1 2 3"
+text([1, 2, 3], ", ")     // "1, 2, 3"
+text(["a", "b"], "-")     // "a-b"
+```
+
+### text(number, radix)
+
+Convert a number to text. Radix is 2-36 (default: 10).
+
+```javascript
+text(255)        // "255"
+text(255, 16)    // "ff"
+text(255, 2)     // "11111111"
+```
+
+### text(text, from, to)
+
+Extract a substring from index `from` to `to`.
+
+```javascript
+text("hello world", 0, 5)   // "hello"
+text("hello world", 6)      // "world"
+```
+
+## Methods
+
+### text.lower(text)
+
+Convert to lowercase.
+
+```javascript
+text.lower("HELLO")  // "hello"
+```
+
+### text.upper(text)
+
+Convert to uppercase.
+
+```javascript
+text.upper("hello")  // "HELLO"
+```
+
+### text.trim(text, reject)
+
+Remove characters from both ends. Default removes whitespace.
+
+```javascript
+text.trim("  hello  ")      // "hello"
+text.trim("xxhelloxx", "x") // "hello"
+```
+
+### text.search(text, target, from)
+
+Find the position of `target` in `text`. Returns `null` if not found.
+
+```javascript
+text.search("hello world", "world")     // 6
+text.search("hello world", "xyz")       // null
+text.search("hello hello", "hello", 1)  // 6
+```
+
+### text.replace(text, target, replacement, limit)
+
+Replace occurrences of `target` with `replacement`.
+
+```javascript
+text.replace("hello", "l", "L")      // "heLLo"
+text.replace("hello", "l", "L", 1)   // "heLlo"
+
+// With function
+text.replace("hello", "l", function(match, pos) {
+  return pos == 2 ? "L" : match
+})  // "heLlo"
+```
+
+### text.format(text, collection, transformer)
+
+Substitute `{key}` placeholders with values from a collection.
+
+```javascript
+text.format("Hello, {name}!", {name: "World"})
+// "Hello, World!"
+
+text.format("{0} + {1} = {2}", [1, 2, 3])
+// "1 + 2 = 3"
+```
+
+### text.normalize(text)
+
+Unicode normalize the text (NFC form).
+
+```javascript
+text.normalize("café")  // normalized form
+```
+
+### text.codepoint(text)
+
+Get the Unicode codepoint of the first character.
+
+```javascript
+text.codepoint("A")     // 65
+text.codepoint("😀")    // 128512
+```
+
+### text.extract(text, pattern, from, to)
+
+Match a pattern and extract named groups.
+
+```javascript
+text.extract("2024-01-15", /(\d+)-(\d+)-(\d+)/)
+// Returns match info
+```