@grain/stdlib 0.5.12 → 0.6.0

package/string.md

@@ -18,7 +18,7 @@ Utilities for working with strings.
 </details>
 
 ```grain
-import String from "string"
+from "string" include String
 ```
 
 ## Types
@@ -41,7 +41,7 @@ Byte encodings
 
 ## Values
 
-Functions for working with the String data type.
+Functions and constants included in the String module.
 
 ### String.**concat**
 
@@ -51,7 +51,7 @@ No other changes yet.
 </details>
 
 ```grain
-concat : (String, String) -> String
+concat : (str1: String, str2: String) => String
 ```
 
 Concatenate two strings.
@@ -83,7 +83,7 @@ No other changes yet.
 </details>
 
 ```grain
-length : String -> Number
+length : (string: String) => Number
 ```
 
 Returns the character length of the input string.
@@ -114,7 +114,7 @@ No other changes yet.
 </details>
 
 ```grain
-byteLength : String -> Number
+byteLength : (string: String) => Number
 ```
 
 Returns the byte length of the input string.
@@ -137,6 +137,31 @@ Examples:
 String.byteLength("🌾") == 4
 ```
 
+### String.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : (string: String) => Bool
+```
+
+Determines if the string contains no characters.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`string`|`String`|The string to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the string is empty and `false` otherwise|
+
 ### String.**indexOf**
 
 <details disabled>
@@ -145,7 +170,7 @@ No other changes yet.
 </details>
 
 ```grain
-indexOf : (String, String) -> Option<Number>
+indexOf : (search: String, string: String) => Option<Number>
 ```
 
 Finds the first position of a substring in the input string.
@@ -177,7 +202,7 @@ No other changes yet.
 </details>
 
 ```grain
-lastIndexOf : (String, String) -> Option<Number>
+lastIndexOf : (search: String, string: String) => Option<Number>
 ```
 
 Finds the last position of a substring in the input string.
@@ -209,7 +234,7 @@ No other changes yet.
 </details>
 
 ```grain
-charCodeAt : (Number, String) -> Number
+charCodeAt : (position: Number, string: String) => Number
 ```
 
 Get the Unicode code point at the position in the input string.
@@ -227,6 +252,16 @@ Returns:
 |----|-----------|
 |`Number`|The character code at the provided position|
 
+Throws:
+
+`Failure(String)`
+
+* When the `position` is out of bounds
+
+`MalformedUnicode`
+
+* When the `string` is malformed
+
 Examples:
 
 ```grain
@@ -241,7 +276,7 @@ No other changes yet.
 </details>
 
 ```grain
-charAt : (Number, String) -> Char
+charAt : (position: Number, string: String) => Char
 ```
 
 Get the character at the position in the input string.
@@ -259,6 +294,16 @@ Returns:
 |----|-----------|
 |`Char`|The character at the provided position|
 
+Throws:
+
+`Failure(String)`
+
+* When the `position` is out of bounds
+
+`MalformedUnicode`
+
+* When the `string` is malformed
+
 Examples:
 
 ```grain
@@ -273,7 +318,7 @@ No other changes yet.
 </details>
 
 ```grain
-explode : String -> Array<Char>
+explode : (string: String) => Array<Char>
 ```
 
 Split a string into its Unicode characters.
@@ -290,6 +335,12 @@ Returns:
 |----|-----------|
 |`Array<Char>`|An array containing all characters in the string|
 
+Throws:
+
+`MalformedUnicode`
+
+* When the `string` is malformed
+
 Examples:
 
 ```grain
@@ -304,7 +355,7 @@ No other changes yet.
 </details>
 
 ```grain
-implode : Array<Char> -> String
+implode : (arr: Array<Char>) => String
 ```
 
 Create a string from an array of characters.
@@ -335,7 +386,7 @@ No other changes yet.
 </details>
 
 ```grain
-reverse : String -> String
+reverse : (string: String) => String
 ```
 
 Create a string that is the given string reversed.
@@ -361,7 +412,7 @@ String.reverse("olleH") == "Hello"
 ### String.**split**
 
 ```grain
-split : (String, String) -> Array<String>
+split : (separator: String, string: String) => Array<String>
 ```
 
 Split a string by the given separator.
@@ -379,6 +430,12 @@ Returns:
 |----|-----------|
 |`Array<String>`|An array of substrings from the initial string|
 
+Throws:
+
+`MalformedUnicode`
+
+* When the `string` is malformed
+
 Examples:
 
 ```grain
@@ -387,13 +444,20 @@ String.split(" ", "Hello world") == [> "Hello", "world"]
 
 ### String.**slice**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.1.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.1.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Default `end` to the String length</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-slice : (Number, Number, String) -> String
+slice : (start: Number, ?end: Number, string: String) => String
 ```
 
 Get a portion of a string.
@@ -403,7 +467,7 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`start`|`Number`|The start position of the substring|
-|`to`|`Number`|The end position of the substring, exclusive|
+|`?end`|`Number`|The end position of the substring, exclusive|
 |`string`|`String`|The input string|
 
 Returns:
@@ -412,10 +476,27 @@ Returns:
 |----|-----------|
 |`String`|The substring from the initial string|
 
+Throws:
+
+`IndexOutOfBounds`
+
+* When `start` is out of bounds
+* When `end` is out of bounds
+
+`InvalidArgument(String)`
+
+* When the `start` index is not an integer
+* When the `to` index is not an integer
+* When `start` is greater than `end`
+
 Examples:
 
 ```grain
-String.slice(0, 5, "Hello world") == "Hello"
+String.slice(0, end=5, "Hello world") == "Hello"
+```
+
+```grain
+String.slice(0, "Hello world") == "Hello world"
 ```
 
 ### String.**contains**
@@ -426,7 +507,7 @@ No other changes yet.
 </details>
 
 ```grain
-contains : (String, String) -> Bool
+contains : (search: String, string: String) => Bool
 ```
 
 Check if a string contains a substring.
@@ -458,7 +539,7 @@ No other changes yet.
 </details>
 
 ```grain
-startsWith : (String, String) -> Bool
+startsWith : (search: String, string: String) => Bool
 ```
 
 Check if a string begins with another string.
@@ -490,7 +571,7 @@ No other changes yet.
 </details>
 
 ```grain
-endsWith : (String, String) -> Bool
+endsWith : (search: String, string: String) => Bool
 ```
 
 Check if a string ends with another string.
@@ -522,7 +603,8 @@ No other changes yet.
 </details>
 
 ```grain
-replaceFirst : (String, String, String) -> String
+replaceFirst :
+  (searchPattern: String, replacement: String, string: String) => String
 ```
 
 Replaces the first appearance of the search pattern in the string with the replacement value.
@@ -555,7 +637,8 @@ No other changes yet.
 </details>
 
 ```grain
-replaceLast : (String, String, String) -> String
+replaceLast :
+  (searchPattern: String, replacement: String, string: String) => String
 ```
 
 Replaces the last appearance of the search pattern in the string with the replacement value.
@@ -588,7 +671,8 @@ No other changes yet.
 </details>
 
 ```grain
-replaceAll : (String, String, String) -> String
+replaceAll :
+  (searchPattern: String, replacement: String, string: String) => String
 ```
 
 Replaces every appearance of the search pattern in the string with the replacement value.
@@ -615,16 +699,25 @@ String.replaceAll("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌎🌎"
 
 ### String.**encodeAt**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.4.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Added `includeBom` default argument</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-encodeAt : (String, Encoding, Bytes, Number) -> Bytes
+encodeAt :
+  (string: String, encoding: Encoding, dest: Bytes, destPos: Number,
+   ?includeBom: Bool) => Bytes
 ```
 
-Encodes the given string into a byte sequence at the supplied position, excluding any byte-order marker, using the encoding scheme provided.
+Encodes the given string into a byte sequence at the supplied position using the encoding scheme provided.
 
 Parameters:
 
@@ -634,6 +727,7 @@ Parameters:
 |`encoding`|`Encoding`|The encoding to use|
 |`dest`|`Bytes`|The byte sequence that will be copied|
 |`destPos`|`Number`|The location in the byte sequence to write the output|
+|`?includeBom`|`Bool`|Whether or not to include a byte order marker (false by default)|
 
 Returns:
 
@@ -641,72 +735,32 @@ Returns:
 |----|-----------|
 |`Bytes`|A copy of the input bytes with the encoded string replaced at the given position|
 
-### String.**encodeAtWithBom**
+Throws:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
-</details>
-
-```grain
-encodeAtWithBom : (String, Encoding, Bytes, Number) -> Bytes
-```
+`InvalidArgument(String)`
 
-Encodes the given string into a byte sequence at the supplied position, including any byte-order marker, using the encoding scheme provided.
-
-Parameters:
-
-|param|type|description|
-|-----|----|-----------|
-|`string`|`String`|The input string|
-|`encoding`|`Encoding`|The encoding to use|
-|`dest`|`Bytes`|The byte sequence that will be copied|
-|`destPos`|`Number`|The location in the byte sequence to write the output|
-
-Returns:
-
-|type|description|
-|----|-----------|
-|`Bytes`|A copy of the input bytes with the encoded string replaced at the given position|
+* When `destPos` is not an integer
+* When `destPos` is negative
 
 ### String.**encode**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
-</details>
-
-```grain
-encode : (String, Encoding) -> Bytes
-```
-
-Encodes the given string using the given encoding scheme, excluding any byte-order marker.
-
-Parameters:
-
-|param|type|description|
-|-----|----|-----------|
-|`string`|`String`|The input string|
-|`encoding`|`Encoding`|The encoding to use|
-
-Returns:
-
-|type|description|
-|----|-----------|
-|`Bytes`|The byte representation of the string in the given encoding|
-
-### String.**encodeWithBom**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.4.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Added `includeBom` default argument</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-encodeWithBom : (String, Encoding) -> Bytes
+encode : (string: String, encoding: Encoding, ?includeBom: Bool) => Bytes
 ```
 
-Encodes the given string using the given encoding scheme, including any byte-order marker.
+Encodes the given string using the given encoding scheme.
 
 Parameters:
 
@@ -714,6 +768,7 @@ Parameters:
 |-----|----|-----------|
 |`string`|`String`|The input string|
 |`encoding`|`Encoding`|The encoding to use|
+|`?includeBom`|`Bool`|Whether or not to include a byte order marker (false by default)|
 
 Returns:
 
@@ -723,16 +778,25 @@ Returns:
 
 ### String.**decodeRange**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.4.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Added `keepBom` default argument</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-decodeRange : (Bytes, Encoding, Number, Number) -> String
+decodeRange :
+  (bytes: Bytes, encoding: Encoding, start: Number, size: Number,
+   ?keepBom: Bool) => String
 ```
 
-Decodes the given byte sequence of the specified range into a string, excluding any byte-order marker, using encoding scheme provided.
+Decodes the given byte sequence of the specified range into a string using the encoding scheme provided.
 
 Parameters:
 
@@ -742,6 +806,7 @@ Parameters:
 |`encoding`|`Encoding`|The encoding to use|
 |`start`|`Number`|The byte offset to begin decoding from|
 |`size`|`Number`|The maximum number of bytes to decode|
+|`?keepBom`|`Bool`|Whether or not to include a byte order marker (false by default)|
 
 Returns:
 
@@ -749,18 +814,34 @@ Returns:
 |----|-----------|
 |`String`|The decoded string|
 
-### String.**decodeRangeKeepBom**
+Throws:
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
-No other changes yet.
+`InvalidArgument(String)`
+
+* When `start` is not an integer
+* When `start` is negative
+* When `size` is not an integer
+* When `size` is negative
+
+### String.**decode**
+
+<details>
+<summary>Added in <code>0.4.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Added `keepBom` default argument</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-decodeRangeKeepBom : (Bytes, Encoding, Number, Number) -> String
+decode : (bytes: Bytes, encoding: Encoding, ?keepBom: Bool) => String
 ```
 
-Decodes the given byte sequence of the specified range into a string, including any byte-order marker, using encoding scheme provided.
+Decodes the given byte sequence into a string using the given encoding scheme.
 
 Parameters:
 
@@ -768,8 +849,7 @@ Parameters:
 |-----|----|-----------|
 |`bytes`|`Bytes`|The input bytes|
 |`encoding`|`Encoding`|The encoding to use|
-|`start`|`Number`|The byte offset to begin decoding from|
-|`size`|`Number`|The maximum number of bytes to decode|
+|`?keepBom`|`Bool`|Whether or not to include a byte order marker (false by default)|
 
 Returns:
 
@@ -777,7 +857,7 @@ Returns:
 |----|-----------|
 |`String`|The decoded string|
 
-### String.**decode**
+### String.**forEachCodePoint**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.4.0</code></summary>
@@ -785,25 +865,25 @@ No other changes yet.
 </details>
 
 ```grain
-decode : (Bytes, Encoding) -> String
+forEachCodePoint : (fn: (Number => Void), str: String) => Void
 ```
 
-Decodes the given byte sequence into a string using the given encoding scheme, excluding any byte-order marker.
+Iterates over Unicode code points in a string.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`bytes`|`Bytes`|The input bytes|
-|`encoding`|`Encoding`|The encoding to use|
+|`fn`|`Number => Void`|The iterator function|
+|`str`|`String`|The string to iterate|
 
-Returns:
+Examples:
 
-|type|description|
-|----|-----------|
-|`String`|The decoded string|
+```grain
+String.forEachCodePoint(print, "Hello world")
+```
 
-### String.**decodeKeepBom**
+### String.**forEachCodePointi**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.4.0</code></summary>
@@ -811,79 +891,89 @@ No other changes yet.
 </details>
 
 ```grain
-decodeKeepBom : (Bytes, Encoding) -> String
+forEachCodePointi : (fn: ((Number, Number) => Void), str: String) => Void
 ```
 
-Decodes the given byte sequence into a string using the given encoding scheme, including any byte-order marker.
+Iterates over Unicode code points in a string. This is the same as
+`forEachCodePoint`, but provides the code point's index in the string
+as the second argument to the iterator function.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`bytes`|`Bytes`|The input bytes|
-|`encoding`|`Encoding`|The encoding to use|
+|`fn`|`(Number, Number) => Void`|The iterator function|
+|`str`|`String`|The string to iterate|
 
-Returns:
+Examples:
 
-|type|description|
-|----|-----------|
-|`String`|The decoded string|
+```grain
+String.forEachCodePointi((codepoint, index) => print((codepoint, index)), "Hello world")
+```
 
-### String.**forEachCodePoint**
+### String.**trimStart**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+<summary tabindex="-1">Added in <code>0.4.2</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-forEachCodePoint : ((Number -> Void), String) -> Void
+trimStart : (string: String) => String
 ```
 
-Iterates over Unicode code points in a string.
+Trims the beginning of a string—removing any leading whitespace characters.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`Number -> Void`|The iterator function|
-|`str`|`String`|The string to iterate|
+|`string`|`String`|The string to be trimmed|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|The trimmed string|
 
 Examples:
 
 ```grain
-String.forEachCodePoint(print, "Hello world")
+String.trimStart("   Hello World") == "Hello World"
 ```
 
-### String.**forEachCodePointi**
+### String.**trimEnd**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.4.0</code></summary>
+<summary tabindex="-1">Added in <code>0.4.2</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-forEachCodePointi : (((Number, Number) -> Void), String) -> Void
+trimEnd : (string: String) => String
 ```
 
-Iterates over Unicode code points in a string. This is the same as
-`forEachCodePoint`, but provides the code point's index in the string
-as the second argument to the iterator function.
+Trims the end of a string—removing any trailing whitespace characters.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(Number, Number) -> Void`|The iterator function|
-|`str`|`String`|The string to iterate|
+|`string`|`String`|The string to be trimmed|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|The trimmed string|
 
 Examples:
 
 ```grain
-String.forEachCodePointi((codepoint, index) => print((codepoint, index)), "Hello world")
+String.trimEnd("Hello World   ") == "Hello World"
 ```
 
-### String.**trimStart**
+### String.**trim**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.4.2</code></summary>
@@ -891,10 +981,10 @@ No other changes yet.
 </details>
 
 ```grain
-trimStart : String -> String
+trim : (string: String) => String
 ```
 
-Trims the beginning of a string—removing any leading whitespace characters.
+Trims a string—removing all leading and trailing whitespace characters.
 
 Parameters:
 
@@ -911,68 +1001,68 @@ Returns:
 Examples:
 
 ```grain
-String.trimStart("   Hello World") == "Hello World"
+String.trim("   Hello World   ") == "Hello World"
 ```
 
-### String.**trimEnd**
+### String.**toAsciiLowercase**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.4.2</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-trimEnd : String -> String
+toAsciiLowercase : (string: String) => String
 ```
 
-Trims the end of a string—removing any trailing whitespace characters.
+Converts all ASCII uppercase characters in the string to lowercase.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`string`|`String`|The string to be trimmed|
+|`string`|`String`|The string to convert|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`String`|The trimmed string|
+|`String`|The lowercased string|
 
 Examples:
 
 ```grain
-String.trimEnd("Hello World   ") == "Hello World"
+assert String.toAsciiLowercase("aBc123") == "abc123"
 ```
 
-### String.**trim**
+### String.**toAsciiUppercase**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.4.2</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-trim : String -> String
+toAsciiUppercase : (string: String) => String
 ```
 
-Trims a string—removing all leading and trailing whitespace characters.
+Converts all ASCII lowercase characters in the string to uppercase.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`string`|`String`|The string to be trimmed|
+|`string`|`String`|The string to convert|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`String`|The trimmed string|
+|`String`|The uppercased string|
 
 Examples:
 
 ```grain
-String.trim("   Hello World   ") == "Hello World"
+assert String.toAsciiUppercase("aBc123") == "ABC123"
 ```