@grain/stdlib 0.4.3 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/array.gr +118 -49
  3. package/array.md +60 -5
  4. package/buffer.gr +95 -41
  5. package/hash.gr +7 -2
  6. package/list.gr +54 -0
  7. package/number.gr +24 -6
  8. package/number.md +32 -0
  9. package/option.gr +244 -37
  10. package/option.md +579 -0
  11. package/package.json +1 -1
  12. package/queue.gr +98 -29
  13. package/queue.md +191 -0
  14. package/range.md +1 -1
  15. package/regex.md +9 -9
  16. package/result.gr +216 -70
  17. package/result.md +446 -0
  18. package/runtime/stringUtils.gr +172 -0
  19. package/set.gr +172 -5
  20. package/set.md +502 -0
  21. package/string.gr +30 -3
  22. package/string.md +31 -0
package/queue.gr CHANGED
@@ -1,46 +1,115 @@
1
+ /**
2
+ * @module Queue: An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
3
+ * @example import Queue from "queue"
4
+ * @since v0.2.0
5
+ */
1
6
  import List from "list"
2
7
 
3
8
  record Queue<a> { forwards: List<a>, backwards: List<a> }
4
9
 
10
+ /**
11
+ * @section Values: Functions for working with queues.
12
+ */
13
+
14
+ /**
15
+ * Creates an empty queue.
16
+ *
17
+ * @returns An empty queue
18
+ * @since v0.2.0
19
+ */
5
20
  export let make = () => {
6
- { forwards: [], backwards: [] }
21
+ { forwards: [], backwards: [] }
7
22
  }
8
23
 
9
- export let isEmpty = (queue) => {
10
- match (queue) {
11
- { forwards: [], backwards: [] } => true,
12
- _ => false
13
- }
24
+ /**
25
+ * Checks if the given queue contains any values.
26
+ *
27
+ * @param queue: The queue to check
28
+ * @returns `true` if the given queue is empty or `false` otherwise
29
+ *
30
+ * @since v0.2.0
31
+ */
32
+ export let isEmpty = queue => {
33
+ match (queue) {
34
+ { forwards: [], backwards: [] } => true,
35
+ _ => false,
36
+ }
14
37
  }
15
38
 
16
- export let peek = (queue) => {
17
- match (queue) {
18
- { forwards: [], backwards: [] } => None,
19
- { forwards, backwards } => List.head(forwards)
20
- }
39
+ /**
40
+ * Returns the value at the beginning of the queue. It is not removed from the queue.
41
+ *
42
+ * @param queue: The queue to inspect
43
+ * @returns `Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty
44
+ *
45
+ * @since v0.3.2
46
+ * @history v0.2.0: Originally named `head`
47
+ * @history v0.3.2: Deprecated `head` function
48
+ * @history v0.4.0: Removed `head` function
49
+ */
50
+ export let peek = queue => {
51
+ match (queue) {
52
+ { forwards: [], backwards: [] } => None,
53
+ { forwards, backwards } => List.head(forwards),
54
+ }
21
55
  }
22
56
 
57
+ /**
58
+ * Adds a value to the end of the queue.
59
+ *
60
+ * @param value: The value to append
61
+ * @param queue: The queue to update
62
+ * @returns An updated queue
63
+ *
64
+ * @since v0.3.2
65
+ * @history v0.2.0: Originally named `enqueue`
66
+ * @history v0.3.2: Deprecated `enqueue` function
67
+ * @history v0.4.0: Removed `enqueue` function
68
+ */
23
69
  export let push = (value, queue) => {
24
- match (queue) {
25
- { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
26
- { forwards, backwards } => { forwards, backwards: [value, ...backwards] }
27
- }
70
+ match (queue) {
71
+ { forwards: [], backwards: [] } => { forwards: [value], backwards: [] },
72
+ { forwards, backwards } => { forwards, backwards: [value, ...backwards] },
73
+ }
28
74
  }
29
75
 
30
- export let pop = (queue) => {
31
- match (queue) {
32
- { forwards: [], backwards: [] } => queue,
33
- { forwards: [head], backwards: [] } => { forwards: [], backwards: [] },
34
- { forwards: [head], backwards } => { forwards: List.reverse(backwards), backwards: [] },
35
- { forwards: [head, ...ftail], backwards } => { forwards: ftail, backwards }
36
- }
76
+ /**
77
+ * Dequeues the next value in the queue.
78
+ *
79
+ * @param queue: The queue to change
80
+ * @returns An updated queue
81
+ *
82
+ * @since v0.3.2
83
+ * @history v0.2.0: Originally named `dequeue`
84
+ * @history v0.3.2: Deprecated `dequeue` function
85
+ * @history v0.4.0: Removed `dequeue` function
86
+ */
87
+ export let pop = queue => {
88
+ match (queue) {
89
+ { forwards: [], backwards: [] } => queue,
90
+ { forwards: [head], backwards: [] } => { forwards: [], backwards: [] },
91
+ { forwards: [head], backwards } =>
92
+ {
93
+ forwards: List.reverse(backwards),
94
+ backwards: [],
95
+ },
96
+ { forwards: [head, ...ftail], backwards } => { forwards: ftail, backwards },
97
+ }
37
98
  }
38
99
 
39
- export let size = (queue) => {
40
- match (queue) {
41
- { forwards: [], backwards: [] } => 0,
42
- { forwards, backwards: [] } => List.length(forwards),
43
- { forwards: [], backwards } => List.length(backwards),
44
- { forwards, backwards } => List.length(forwards) + List.length(backwards),
45
- }
100
+ /**
101
+ * Get the number of values in a queue.
102
+ *
103
+ * @param queue: The queue to inspect
104
+ * @returns The number of values in the queue
105
+ *
106
+ * @since v0.3.2
107
+ */
108
+ export let size = queue => {
109
+ match (queue) {
110
+ { forwards: [], backwards: [] } => 0,
111
+ { forwards, backwards: [] } => List.length(forwards),
112
+ { forwards: [], backwards } => List.length(backwards),
113
+ { forwards, backwards } => List.length(forwards) + List.length(backwards),
114
+ }
46
115
  }
package/queue.md ADDED
@@ -0,0 +1,191 @@
1
+ ---
2
+ title: Queue
3
+ ---
4
+
5
+ An immutable queue implementation. A queue is a FIFO (first-in-first-out) data structure where new values are added to the end and retrieved or removed from the beginning.
6
+
7
+ <details disabled>
8
+ <summary tabindex="-1">Added in <code>0.2.0</code></summary>
9
+ No other changes yet.
10
+ </details>
11
+
12
+ ```grain
13
+ import Queue from "queue"
14
+ ```
15
+
16
+ ## Values
17
+
18
+ Functions for working with queues.
19
+
20
+ ### Queue.**make**
21
+
22
+ <details disabled>
23
+ <summary tabindex="-1">Added in <code>0.2.0</code></summary>
24
+ No other changes yet.
25
+ </details>
26
+
27
+ ```grain
28
+ make : () -> Queue<a>
29
+ ```
30
+
31
+ Creates an empty queue.
32
+
33
+ Returns:
34
+
35
+ |type|description|
36
+ |----|-----------|
37
+ |`Queue<a>`|An empty queue|
38
+
39
+ ### Queue.**isEmpty**
40
+
41
+ <details disabled>
42
+ <summary tabindex="-1">Added in <code>0.2.0</code></summary>
43
+ No other changes yet.
44
+ </details>
45
+
46
+ ```grain
47
+ isEmpty : Queue<a> -> Bool
48
+ ```
49
+
50
+ Checks if the given queue contains any values.
51
+
52
+ Parameters:
53
+
54
+ |param|type|description|
55
+ |-----|----|-----------|
56
+ |`queue`|`Queue<a>`|The queue to check|
57
+
58
+ Returns:
59
+
60
+ |type|description|
61
+ |----|-----------|
62
+ |`Bool`|`true` if the given queue is empty or `false` otherwise|
63
+
64
+ ### Queue.**peek**
65
+
66
+ <details>
67
+ <summary>Added in <code>0.3.2</code></summary>
68
+ <table>
69
+ <thead>
70
+ <tr><th>version</th><th>changes</th></tr>
71
+ </thead>
72
+ <tbody>
73
+ <tr><td><code>0.2.0</code></td><td>Originally named `head`</td></tr>
74
+ <tr><td><code>0.3.2</code></td><td>Deprecated `head` function</td></tr>
75
+ <tr><td><code>0.4.0</code></td><td>Removed `head` function</td></tr>
76
+ </tbody>
77
+ </table>
78
+ </details>
79
+
80
+ ```grain
81
+ peek : Queue<a> -> Option<a>
82
+ ```
83
+
84
+ Returns the value at the beginning of the queue. It is not removed from the queue.
85
+
86
+ Parameters:
87
+
88
+ |param|type|description|
89
+ |-----|----|-----------|
90
+ |`queue`|`Queue<a>`|The queue to inspect|
91
+
92
+ Returns:
93
+
94
+ |type|description|
95
+ |----|-----------|
96
+ |`Option<a>`|`Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty|
97
+
98
+ ### Queue.**push**
99
+
100
+ <details>
101
+ <summary>Added in <code>0.3.2</code></summary>
102
+ <table>
103
+ <thead>
104
+ <tr><th>version</th><th>changes</th></tr>
105
+ </thead>
106
+ <tbody>
107
+ <tr><td><code>0.2.0</code></td><td>Originally named `enqueue`</td></tr>
108
+ <tr><td><code>0.3.2</code></td><td>Deprecated `enqueue` function</td></tr>
109
+ <tr><td><code>0.4.0</code></td><td>Removed `enqueue` function</td></tr>
110
+ </tbody>
111
+ </table>
112
+ </details>
113
+
114
+ ```grain
115
+ push : (a, Queue<a>) -> Queue<a>
116
+ ```
117
+
118
+ Adds a value to the end of the queue.
119
+
120
+ Parameters:
121
+
122
+ |param|type|description|
123
+ |-----|----|-----------|
124
+ |`value`|`a`|The value to append|
125
+ |`queue`|`Queue<a>`|The queue to update|
126
+
127
+ Returns:
128
+
129
+ |type|description|
130
+ |----|-----------|
131
+ |`Queue<a>`|An updated queue|
132
+
133
+ ### Queue.**pop**
134
+
135
+ <details>
136
+ <summary>Added in <code>0.3.2</code></summary>
137
+ <table>
138
+ <thead>
139
+ <tr><th>version</th><th>changes</th></tr>
140
+ </thead>
141
+ <tbody>
142
+ <tr><td><code>0.2.0</code></td><td>Originally named `dequeue`</td></tr>
143
+ <tr><td><code>0.3.2</code></td><td>Deprecated `dequeue` function</td></tr>
144
+ <tr><td><code>0.4.0</code></td><td>Removed `dequeue` function</td></tr>
145
+ </tbody>
146
+ </table>
147
+ </details>
148
+
149
+ ```grain
150
+ pop : Queue<a> -> Queue<a>
151
+ ```
152
+
153
+ Dequeues the next value in the queue.
154
+
155
+ Parameters:
156
+
157
+ |param|type|description|
158
+ |-----|----|-----------|
159
+ |`queue`|`Queue<a>`|The queue to change|
160
+
161
+ Returns:
162
+
163
+ |type|description|
164
+ |----|-----------|
165
+ |`Queue<a>`|An updated queue|
166
+
167
+ ### Queue.**size**
168
+
169
+ <details disabled>
170
+ <summary tabindex="-1">Added in <code>0.3.2</code></summary>
171
+ No other changes yet.
172
+ </details>
173
+
174
+ ```grain
175
+ size : Queue<a> -> Number
176
+ ```
177
+
178
+ Get the number of values in a queue.
179
+
180
+ Parameters:
181
+
182
+ |param|type|description|
183
+ |-----|----|-----------|
184
+ |`queue`|`Queue<a>`|The queue to inspect|
185
+
186
+ Returns:
187
+
188
+ |type|description|
189
+ |----|-----------|
190
+ |`Number`|The number of values in the queue|
191
+
package/range.md CHANGED
@@ -102,7 +102,7 @@ No other changes yet.
102
102
  </details>
103
103
 
104
104
  ```grain
105
- map : ((Number -> a), Range) -> List<b>
105
+ map : ((Number -> a), Range) -> List<a>
106
106
  ```
107
107
 
108
108
  Produces a list by calling the given function on each number included in the range. For increasing ranges, the value is increased by `1` in each iteration, and for decreasing ranges, the value is decreased by `1`. The value is always changed by `1`, even if non-integer values were provided in the range.
package/regex.md CHANGED
@@ -5,7 +5,7 @@ title: Regex
5
5
  Regular Expressions.
6
6
 
7
7
  <details disabled>
8
- <summary tabindex="-1">Added in <code>next</code></summary>
8
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
9
9
  No other changes yet.
10
10
  </details>
11
11
 
@@ -20,7 +20,7 @@ Functions for working with regular expressions.
20
20
  ### Regex.**make**
21
21
 
22
22
  <details disabled>
23
- <summary tabindex="-1">Added in <code>next</code></summary>
23
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
24
24
  No other changes yet.
25
25
  </details>
26
26
 
@@ -180,7 +180,7 @@ Returns the positions of all groups matched in this match object.
180
180
  ### Regex.**isMatch**
181
181
 
182
182
  <details disabled>
183
- <summary tabindex="-1">Added in <code>next</code></summary>
183
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
184
184
  No other changes yet.
185
185
  </details>
186
186
 
@@ -212,7 +212,7 @@ assert Regex.isMatch(Result.unwrap(Regex.make("ca+[at]")), "caaat") == true
212
212
  ### Regex.**isMatchRange**
213
213
 
214
214
  <details disabled>
215
- <summary tabindex="-1">Added in <code>next</code></summary>
215
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
216
216
  No other changes yet.
217
217
  </details>
218
218
 
@@ -250,7 +250,7 @@ assert Regex.isMatchRange(Result.unwrap(Regex.make("ca+[at]")), "caaat", 1, 5) =
250
250
  ### Regex.**find**
251
251
 
252
252
  <details disabled>
253
- <summary tabindex="-1">Added in <code>next</code></summary>
253
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
254
254
  No other changes yet.
255
255
  </details>
256
256
 
@@ -282,7 +282,7 @@ Regex.find(Result.unwrap(Regex.make("ca+[at]")), "caaat")
282
282
  ### Regex.**findRange**
283
283
 
284
284
  <details disabled>
285
- <summary tabindex="-1">Added in <code>next</code></summary>
285
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
286
286
  No other changes yet.
287
287
  </details>
288
288
 
@@ -339,7 +339,7 @@ Returns:
339
339
  ### Regex.**findAllRange**
340
340
 
341
341
  <details disabled>
342
- <summary tabindex="-1">Added in <code>next</code></summary>
342
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
343
343
  No other changes yet.
344
344
  </details>
345
345
 
@@ -375,7 +375,7 @@ Regex.findAllRange(Result.unwrap(Regex.make("ca+[at]")), "caaat", 0, 5)
375
375
  ### Regex.**replace**
376
376
 
377
377
  <details disabled>
378
- <summary tabindex="-1">Added in <code>next</code></summary>
378
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
379
379
  No other changes yet.
380
380
  </details>
381
381
 
@@ -416,7 +416,7 @@ assert Regex.replace(Result.unwrap(Regex.make("o")), "foo", "a") == "fao"
416
416
  ### Regex.**replaceAll**
417
417
 
418
418
  <details disabled>
419
- <summary tabindex="-1">Added in <code>next</code></summary>
419
+ <summary tabindex="-1">Added in <code>0.4.3</code></summary>
420
420
  No other changes yet.
421
421
  </details>
422
422