Skip to content

Commit 99cd2a5

Browse files
zthzth
authored
Docs for Map and Iterator (#34)
* change iterator bindings to be the same shape as async iterators, and add docstrings * docstrings for Map * changelog
1 parent dbc03ea commit 99cd2a5

File tree

5 files changed

+336
-5
lines changed

5 files changed

+336
-5
lines changed

‎CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
# @rescript/core Changelog
22

33
## master
4+
5+
- Docstrings for `Map` and `Iterator`. https://github.com/rescript-association/rescript-core/pull/34
6+
- Change `Map.set` to not return self, to indicate that it's mutable. https://github.com/rescript-association/rescript-core/pull/34
7+
- Change `Iterator` bindings to have the same shape as `AsyncIterator` for consistency. https://github.com/rescript-association/rescript-core/pull/34
8+
- Add `Iterator.toArray` binding for turning an iterator into an array. https://github.com/rescript-association/rescript-core/pull/34

‎src/Core__Iterator.res

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
type t<'a>
2-
type next<'a>
32

4-
@get external done: next<'a> => bool = "done"
5-
@get external value: next<'a> => option<'a> = "value"
3+
type value<'a> = {
4+
done: bool,
5+
value: option<'a>,
6+
}
67

7-
@send external next: t<'a> => next<'a> = "next"
8+
@send external next: t<'a> => value<'a> = "next"
9+
@scope("Array") external toArray: t<'a> => array<'a> = "from"

‎src/Core__Iterator.resi

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
/***
2+
Bindings to JavaScript iterators.
3+
4+
See [`iterator protocols`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN.
5+
*/
6+
7+
/**
8+
The type representing an iterator.
9+
*/
10+
type t<'a>
11+
12+
/**
13+
The current value of an iterator.
14+
*/
15+
type value<'a> = {
16+
/**
17+
Whether there are more values to iterate on before the iterator is done.
18+
*/
19+
done: bool,
20+
/**
21+
The value of this iteration, if any.
22+
*/
23+
value: option<'a>,
24+
}
25+
26+
/**
27+
Returns the next value of the iterator, if any.
28+
29+
See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN.
30+
31+
## Examples
32+
```rescript
33+
// Pulls out the next value of the iterator
34+
let {done, value} = someIterator->Iterator.next
35+
```
36+
*/
37+
@send
38+
external next: t<'a> => value<'a> = "next"
39+
40+
/**
41+
Turns an iterator into an array of the remaining values.
42+
Remember that each invocation of `next` of an iterator consumes a value. `Iterator.toArray` will consume all remaining values of the iterator and return them in an array to you.
43+
44+
See [iterator protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on MDN.
45+
46+
## Examples
47+
```rescript
48+
let map = Map.make()
49+
map->Map.set("someKey", "someValue")
50+
map->Map.set("someKey2", "someValue2")
51+
52+
// `Map.keys` returns all keys of the map as an iterator.
53+
let mapKeysAsArray = map->Map.keys->Iterator.toArray
54+
55+
Console.log(mapKeysAsArray) // Logs ["someKey", "someKey2"] to the console.
56+
```
57+
*/
58+
@scope("Array")
59+
external toArray: t<'a> => array<'a> = "from"

‎src/Core__Map.res

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ type t<'k, 'v>
1313

1414
@send external get: (t<'k, 'v>, 'k) => option<'v> = "get"
1515
@send external has: (t<'k, 'v>, 'k) => bool = "has"
16-
@send external set: (t<'k, 'v>, 'k, 'v) => t<'k, 'v> = "set"
16+
@send external set: (t<'k, 'v>, 'k, 'v) => unit = "set"
1717
@send external delete: (t<'k, 'v>, 'k) => bool = "delete"
1818

1919
@send external keys: t<'k, 'v> => Core__Iterator.t<'k> = "keys"

‎src/Core__Map.resi

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
/***
2+
Bindings to the mutable JavaScript `Map`.
3+
4+
See [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) on MDN.
5+
*/
6+
7+
/**
8+
Type representing an instance of `Map`.
9+
*/
10+
type t<'k, 'v>
11+
12+
/**
13+
Creates a new, mutable JavaScript `Map`. A `Map` can have any values as both keys and values.
14+
15+
See [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) on MDN.
16+
17+
18+
19+
## Examples
20+
```rescript
21+
`make()`
22+
// You can annotate the type of your map if you want to
23+
let myMap: Map.t<string, int> = Map.make()
24+
25+
// Or you can let ReScript infer what's in your map
26+
let map = Map.make()
27+
map->Map.set("lang", "ReScript") // Inferred as Map.t<string, string>
28+
```
29+
30+
## Alternatives
31+
A JavaScript `Map` is mutable. If you're looking for an immutable alternative, check out`Belt.Map`.
32+
*/
33+
@new
34+
external make: unit => t<'k, 'v> = "Map"
35+
36+
/**
37+
Turns an array of key/value pairs into a Map.
38+
39+
## Examples
40+
```rescript
41+
type languages = ReScript | JavaScript | TypeScript
42+
let languageRank = [(ReScript, 1), (JavaScript, 2), (TypeScript, 3)]
43+
44+
let map = Map.fromArray(languageRank) // Map.t<languages, int>
45+
46+
switch map->Map.get(ReScript) {
47+
| Some(1) => Console.log("Yay, ReScript is #1!")
48+
| _ => Console.log("Uh-oh, something is _terribly_ wrong with this program... abort.")
49+
}
50+
```
51+
*/
52+
@new
53+
external fromArray: array<('k, 'v)> => t<'k, 'v> = "Map"
54+
55+
/**
56+
Turns an iterator in the shape of `('key, 'value)` into a `Map`.
57+
58+
## Examples
59+
```rescript
60+
// Let's pretend we have an interator in the correct shape
61+
@val external someIterator: Iterator.t<(string, int)> = "someIterator"
62+
63+
let map = Map.fromIterator(someIterator) // Map.t<string, int>
64+
```
65+
*/
66+
@new
67+
external fromIterator: Core__Iterator.t<('k, 'v)> => t<'k, 'v> = "Map"
68+
69+
/**
70+
Returns the size, the number of key/value pairs, of the map.
71+
72+
## Examples
73+
```rescript
74+
let map = Map.make()
75+
76+
map->Map.set("someKey", "someValue")
77+
78+
let size = map->Map.size // 1
79+
```
80+
*/
81+
@get
82+
external size: t<'k, 'v> => int = "size"
83+
84+
/**
85+
Clears all entries in the map.
86+
87+
## Examples
88+
```rescript
89+
let map = Map.make()
90+
91+
map->Map.set("someKey", "someValue")
92+
let size = map->Map.size // 1
93+
94+
map->Map.clear
95+
let size = map->Map.size // 0
96+
```
97+
*/
98+
@send
99+
external clear: t<'k, 'v> => unit = "clear"
100+
101+
/**
102+
Iterates through all values of the map.
103+
104+
> Please note that this is *without the keys*, just the values. If you need the key as well, use `Map.forEachWithKey`.
105+
106+
## Examples
107+
```rescript
108+
let map = Map.make()
109+
map->Map.set("someKey", "someValue")
110+
map->Map.set("someKey2", "someValue2")
111+
112+
map->Map.forEach(value => {
113+
Console.log(value)
114+
})
115+
```
116+
*/
117+
@send
118+
external forEach: (t<'k, 'v>, 'v => unit) => unit = "forEach"
119+
120+
/**
121+
Iterates through all values of the map, including the key for each value.
122+
123+
## Examples
124+
```rescript
125+
let map = Map.make()
126+
map->Map.set("someKey", "someValue")
127+
map->Map.set("someKey2", "someValue2")
128+
129+
map->Map.forEachWithKey((value, key) => {
130+
Console.log2(value, key)
131+
})
132+
```
133+
*/
134+
@send
135+
external forEachWithKey: (t<'k, 'v>, ('v, 'k) => unit) => unit = "forEach"
136+
137+
/**
138+
Returns the value for a key, if a value exists at that key.
139+
140+
## Examples
141+
```rescript
142+
let map = Map.make()
143+
map->Map.set("someKey", "someValue")
144+
145+
switch map->Map.get("someKey") {
146+
| None => Console.log("Nope, didn't have it.")
147+
| Some(value) => Console.log2("Yay, had the value, and it's:", value)
148+
}
149+
```
150+
*/
151+
@send
152+
external get: (t<'k, 'v>, 'k) => option<'v> = "get"
153+
154+
/**
155+
Checks whether the map has a specific key.
156+
157+
## Examples
158+
```rescript
159+
let map = Map.make()
160+
map->Map.set("someKey", "someValue")
161+
162+
switch map->Map.has("someKey") {
163+
| false => Console.log("Nope, didn't have it.")
164+
| true => Console.log("Yay, we have the value!")
165+
}
166+
```
167+
*/
168+
@send
169+
external has: (t<'k, 'v>, 'k) => bool = "has"
170+
171+
/**
172+
Sets the provided `value` to the provided `key`.
173+
174+
## Examples
175+
```rescript
176+
let map = Map.make()
177+
map->Map.set("someKey", "someValue")
178+
```
179+
*/
180+
@send
181+
external set: (t<'k, 'v>, 'k, 'v) => unit = "set"
182+
183+
/**
184+
Deletes the provided `key` and its value from the map. Returns a `bool` for whether the key existed, and was deleted.
185+
186+
## Examples
187+
```rescript
188+
let map = Map.make()
189+
map->Map.set("someKey", "someValue")
190+
let didDeleteKey = map->Map.delete("someKey")
191+
Console.log(didDeleteKey) // Logs `true` to the console, becuase the map had the key, so it was successfully deleted
192+
193+
let didDeleteKey = map->Map.delete("someNonExistantKey")
194+
Console.log(didDeleteKey) // Logs `false` to the console, becuase the key did not exist
195+
```
196+
*/
197+
@send
198+
external delete: (t<'k, 'v>, 'k) => bool = "delete"
199+
200+
/**
201+
Returns an iterator that holds all keys of the map.
202+
203+
## Examples
204+
```rescript
205+
let map = Map.make()
206+
map->Map.set("someKey", "someValue")
207+
map->Map.set("anotherKey", "anotherValue")
208+
209+
let keys = map->Map.keys
210+
211+
// Logs the first key
212+
Console.log(Iterator.next(keys).value)
213+
214+
// You can also turn the iterator into an array.
215+
// Remember that an iterator consumes values. We'll need a fresh keys iterator to get an array of all keys, since we consumed a value via `next` above already.
216+
Console.log(map->Map.keys->Iterator.toArray)
217+
```
218+
*/
219+
@send
220+
external keys: t<'k, 'v> => Core__Iterator.t<'k> = "keys"
221+
222+
/**
223+
Returns an iterator that holds all values of the map.
224+
225+
## Examples
226+
```rescript
227+
let map = Map.make()
228+
map->Map.set("someKey", "someValue")
229+
map->Map.set("anotherKey", "anotherValue")
230+
231+
let values = map->Map.values
232+
233+
// Logs the first value
234+
Console.log(Iterator.next(values).value)
235+
236+
// You can also turn the iterator into an array.
237+
// Remember that an iterator consumes values. We'll need a fresh values iterator to get an array of all values, since we consumed a value via `next` above already.
238+
Console.log(map->Map.values->Iterator.toArray)
239+
```
240+
*/
241+
@send
242+
external values: t<'k, 'v> => Core__Iterator.t<'v> = "values"
243+
244+
/**
245+
Returns an iterator that holds all entries of the map.
246+
An entry is represented as a tuple of `('key, 'value)`,
247+
248+
## Examples
249+
```rescript
250+
let map = Map.make()
251+
map->Map.set("someKey", "someValue")
252+
map->Map.set("anotherKey", "anotherValue")
253+
254+
let entries = map->Map.entries
255+
256+
// Logs the first value
257+
Console.log(Iterator.next(entries).value)
258+
259+
// You can also turn the iterator into an array.
260+
// Remember that an iterator consumes entries. We'll need a fresh entries iterator to get an array of all entries, since we consumed a value via `next` above already.
261+
Console.log(map->Map.entries->Iterator.toArray)
262+
```
263+
*/
264+
@send
265+
external entries: t<'k, 'v> => Core__Iterator.t<('k, 'v)> = "entries"

0 commit comments

Comments
 (0)