diff --git a/src/boot/boot.janet b/src/boot/boot.janet index ee3a7b6e..bf70e423 100644 --- a/src/boot/boot.janet +++ b/src/boot/boot.janet @@ -1646,14 +1646,18 @@ (reverse! (seq [v :in t] v)))) (defn invert - ``Given an associative data structure `ds`, returns a new table where the - keys of `ds` are the values, and the values are the keys. If multiple keys - in `ds` are mapped to the same value, only one of those values will - become a key in the returned table.`` - [ds] + `` + Returns a table where the keys of `x` are the values, and the values + are the keys. If multiple keys in `x` are mapped to the same value, + only one of those values will become a key in the returned table. + + `x` can be a bytes, indexed, dictionary, or abstract type with a + `suitable next` method. + `` + [x] (def ret @{}) - (loop [k :keys ds] - (put ret (in ds k) k)) + (loop [k :keys x] + (put ret (in x k) k)) ret) (defn zipcoll @@ -1756,7 +1760,12 @@ container) (defn keys - "Get the keys of an associative data structure." + `` + Get the keys of `x` as an array. + + `x` can be a bytes, indexed, dictionary, or abstract type with a + suitable `next` method. + `` [x] (if (lengthable? x) (do @@ -1769,7 +1778,12 @@ (seq [k :keys x] k))) (defn values - "Get the values of an associative data structure." + `` + Get the values of `x` as an array. + + `x` can be a bytes, indexed, dictionary, fiber, or abstract type + with suitable `get` and `next` methods. + `` [x] (if (lengthable? x) (do @@ -1782,7 +1796,13 @@ (seq [v :in x] v))) (defn pairs - "Get the key-value pairs of an associative data structure." + `` + Return an array of tuples of the key-value pairs of `x`. For bytes + and indexed types, the integer indices are considered the keys. + + `x` can be a bytes, indexed, dictionary, or abstract type with + suitable `get` and `in` methods. + `` [x] (if (lengthable? x) (do diff --git a/src/core/corelib.c b/src/core/corelib.c index c8228435..bbfc34ad 100644 --- a/src/core/corelib.c +++ b/src/core/corelib.c @@ -1247,13 +1247,18 @@ JanetTable *janet_core_env(JanetTable *replacements) { "abstract type with a suitable `get` method.")); janet_quick_asm(env, JANET_FUN_PUT, "put", 3, 3, 3, 3, put_asm, sizeof(put_asm), - JDOC("(put ds key value)\n\n" - "Associate a key with a value in any mutable associative data structure. Indexed data structures " - "(arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds " - "value is provided. In an array, extra space will be filled with nils, and in a buffer, extra " - "space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype " - "will hide the association defined by the prototype, but will not mutate the prototype table. Putting " - "a value nil into a table will remove the key from the table. Returns the data structure ds.")); + JDOC("(put x key val)\n\n" + "Associate `key` with `val` for mutable `x`. Arrays " + "and buffers only accept non-negative integer keys, " + "and will expand if an out of bounds value is " + "provided. For an array, extra space will be filled " + "with `nil`s, while for buffers, 0 bytes are used " + "instead. For a table, putting a key that is in the " + "table prototype will hide the association defined by " + "the prototype, but will not mutate the prototype " + "table. Putting a `nil` value into a table will " + "remove the table's corresponding association. " + "Returns `x`.")); janet_quick_asm(env, JANET_FUN_LENGTH, "length", 1, 1, 1, 1, length_asm, sizeof(length_asm), JDOC("(length ds)\n\n"