From c0203cacd6cc1778739fccf17fd5dbd000fe8e00 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 16 Feb 2023 19:52:19 +0100 Subject: [PATCH 1/3] docs for Dict --- src/Core__Dict.resi | 173 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 src/Core__Dict.resi diff --git a/src/Core__Dict.resi b/src/Core__Dict.resi new file mode 100644 index 00000000..c8d0a699 --- /dev/null +++ b/src/Core__Dict.resi @@ -0,0 +1,173 @@ +/*** +A mutable dictionary with string keys. + +Compiles to a regular JavaScript object.*/ + +/** +Type representing a dictionary of value `'a`. +*/ +type t<'a> = Js.Dict.t<'a> + +/** +Returns the value at the provided key, if it exists. Returns an option. + +## Examples +```rescript +let dict = Dict.fromArray([("someKey", "someValue")]) + +switch dict->Dict.get("someKey") { +| None => Console.log("Nope, didn't have the key.") +| Some(value) => Console.log(value) +} +``` +*/ +@get_index +external get: (t<'a>, string) => option<'a> = "" + +/** +`set(dictionary, key, value)` sets the value at the provided key to the provided value. + +## Examples +```rescript +let dict = Dict.make() + +dict->Dict.set("someKey", "someValue") +``` +*/ +@set_index +external set: (t<'a>, string, 'a) => unit = "" + +/** +`delete(dictionary, key)` deletes the value at `key`, if it exists. + +## Examples +```rescript +let dict = Dict.fromArray([("someKey", "someValue")]) + +dict->Dict.delete("someKey") +``` +*/ +let delete: (t<'a>, string) => unit + +/** +`make()` creates a new, empty dictionary. + +## Examples +```rescript +let dict1: Dict.t = Dict.make() // You can annotate the type of the values of your dict yourself if you want + +let dict2 = Dict.make() // Or you can let ReScript infer it via usage. +dict2->Dict.set("someKey", 12) +``` +*/ +@obj +external make: unit => t<'a> = "" + +/** +`fromArray(entries)` creates a new dictionary from the provided array of key/value pairs. + +## Examples +```rescript +let dict = Dict.fromArray([("key1", "value1"), ("key2", "value2")]) +``` +*/ +@val +external fromArray: array<(string, 'a)> => t<'a> = "Object.fromEntries" + +/** +`fromIterator(entries)` creates a new dictionary from the provided iterator of key/value pairs. + +## Examples +```rescript +// Pretend we have an iterator of the correct shape +@val external someIterator: Iterator.t<(string, int)> = "someIterator" + +let dict = Dict.fromIterator(someIterator) // Dict.t +``` +*/ +@val +external fromIterator: Core__Iterator.t<(string, 'a)> => t<'a> = "Object.fromEntries" + +/** +`toArray(dictionary)` turns the dictionary into an array of key/value pairs. + +## Examples +```rescript +let dict = Dict.make() +dict->Dict.set("someKey", 1) +dict->Dict.set("someKey2", 2) +let asArray = dict->Dict.toArray +Console.log(asArray) // Logs `[["someKey", 1], ["someKey2", 2]]` to the console +``` +*/ +@val +external toArray: t<'a> => array<(string, 'a)> = "Object.entries" + +/** +`keysToArray(dictionary)` turns the dictionary into an array of its keys. + +## Examples +```rescript +let dict = Dict.make() +dict->Dict.set("someKey", 1) +dict->Dict.set("someKey2", 2) +let keys = dict->Dict.keysToArray +Console.log(keys) // Logs `["someKey", "someKey2"]` to the console +``` +*/ +@val +external keysToArray: t<'a> => array = "Object.keys" + +/** +`valuesToArray(dictionary)` turns the dictionary into an array of its values. + +## Examples +```rescript +let dict = Dict.make() +dict->Dict.set("someKey", 1) +dict->Dict.set("someKey2", 2) +let values = dict->Dict.valuesToArray +Console.log(values) // Logs `[1, 2]` to the console +``` +*/ +@val +external valuesToArray: t<'a> => array<'a> = "Object.values" + +/** +`assign(dictionary1, dictionary2)` [shallowly](https://developer.mozilla.org/en-US/docs/Glossary/Shallow_copy) merges dictionary2 into dictionary1, and returns dictionary1. + +Beware this will *mutate* dictionary1. If you're looking for a way to copy a dictionary, check out `Dict.copy`. + +## Examples +```rescript +let dict1 = Dict.make() +dict1->Dict.set("firstKey", 1) +Console.log(dict1->Dict.keysToArray) // Logs `["firstKey"]` + +let dict2 = Dict.make() +dict2->Dict.set("someKey", 2) +dict2->Dict.set("someKey2", 3) + +let dict1 = dict1->Dict.assign(dict2) + +Console.log(dict1->Dict.keysToArray) // Logs `["firstKey", "someKey", "someKey2"]` + +``` +*/ +@val +external assign: (t<'a>, t<'a>) => t<'a> = "Object.assign" + +/** +`copy(dictionary)` [shallowly copies](https://developer.mozilla.org/en-US/docs/Glossary/Shallow_copy) the provided dictionary to a new dictionary. + +## Examples +```rescript +let dict = Dict.fromArray([("key1", "value1"), ("key2", "value2")]) +let dict2 = dict->Dict.copy + +// Both log `["key1", "key2"]` here. +Console.log2(dict->Dict.keysToArray, dict2->Dict.keysToArray) +``` +*/ +@val +external copy: (@as(json`{}`) _, t<'a>) => t<'a> = "Object.assign" From c13862565221977954976c98b60984df2371db0e Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Thu, 16 Feb 2023 19:53:12 +0100 Subject: [PATCH 2/3] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b01b6bd5..073e8b4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,3 +17,4 @@ - Docstrings for `AsyncIterator`. https://github.com/rescript-association/rescript-core/pull/33 - Docstrings for `Type`. https://github.com/rescript-association/rescript-core/pull/32 - Docstrings for `Int`. https://github.com/rescript-association/rescript-core/pull/37 +- Docstrings for `Dict`. https://github.com/rescript-association/rescript-core/pull/40 From c4eacb87bc3e77863ac545295e5f621e061bdb41 Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Fri, 17 Feb 2023 19:51:17 +0100 Subject: [PATCH 3/3] wording --- src/Core__Dict.resi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Core__Dict.resi b/src/Core__Dict.resi index c8d0a699..54fef2ad 100644 --- a/src/Core__Dict.resi +++ b/src/Core__Dict.resi @@ -89,7 +89,7 @@ let dict = Dict.fromIterator(someIterator) // Dict.t external fromIterator: Core__Iterator.t<(string, 'a)> => t<'a> = "Object.fromEntries" /** -`toArray(dictionary)` turns the dictionary into an array of key/value pairs. +`toArray(dictionary)` returns an array of all the key/value pairs of the dictionary. ## Examples ```rescript @@ -104,7 +104,7 @@ Console.log(asArray) // Logs `[["someKey", 1], ["someKey2", 2]]` to the console external toArray: t<'a> => array<(string, 'a)> = "Object.entries" /** -`keysToArray(dictionary)` turns the dictionary into an array of its keys. +`keysToArray(dictionary)` returns an array of all the keys of the dictionary. ## Examples ```rescript @@ -119,7 +119,7 @@ Console.log(keys) // Logs `["someKey", "someKey2"]` to the console external keysToArray: t<'a> => array = "Object.keys" /** -`valuesToArray(dictionary)` turns the dictionary into an array of its values. +`valuesToArray(dictionary)` returns an array of all the values of the dictionary. ## Examples ```rescript