Skip to content

[spec/hash-map] Improve Properties section #4342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thewilsonator merged 1 commit into from
Dec 7, 2025
Merged

[spec/hash-map] Improve Properties section #4342

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 45 additions & 47 deletions spec/hash-map.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -432,93 +432,91 @@ $(SPEC_RUNNABLE_EXAMPLE_RUN

$(H2 $(LNAME2 properties, Properties and Operations))

$(TABLE_2COLS Associative Array Properties,
$(THEAD Property name, Description)
$(TABLE
$(THEAD Name, Description)
$(TROW $(D sizeof), $(ARGS The size of the reference to the associative
array; it is 4 in 32-bit builds and 8 on 64-bit builds.))
$(TROW $(D length), $(ARGS The number of values in the
associative array. Unlike for dynamic arrays, it is read-only.))
)

$(P There is no built-in `empty` property.
Phobos provides an implementation of `empty` in `std.range.primitives`.)

$(TABLE_2COLS Associative Array Organizing Operations,
$(TROW $(D dup()), Returns `null` If the associative array is `null`;
$(TROW $(D dup()), Returns `null` if the associative array is `null`;
otherwise returns a newly allocated associative array with copies of the keys and values of the associative array.)
$(TROW $(D rehash()), $(ARGS Reorganizes the associative array in place so that lookups
are more efficient.))
are more efficient. Calling $(D rehash) is effective when, for example,
the program is done loading up a symbol table and now needs
fast lookups in it. Returns a reference to the reorganized array.))
$(TROW $(D clear()), $(ARGS Removes all keys and values from an associative array.
The array is not rehashed after removal to allow for the existing storage to be reused.
This will affect all references to the same instance and is not equivalent to `destroy(aa)`
which only sets the current reference to `null`))
which only sets the current reference to `null`.))
)

$(P Calling $(D rehash) is effective when, for example,
the program is done loading up a symbol table and now needs
fast lookups in it. Returns a reference to the reorganized array.)
$(NOTE There is no built-in `empty` property.
Phobos provides an implementation of `empty` in $(MREF std,range,primitives).)

$(P See $(MREF1 object) for examples.)

$(TABLE_2COLS Associative Array Iteration Operations,
$(H3 $(LNAME2 iteration-ops, Iteration Operations))

$(TABLE
$(THEAD Operation, Description)
$(TROW $(D keys()), $(ARGS Returns a newly allocated dynamic array containing copies of the keys in
the associative array in an order that is consistent with `values()` but otherwise unspecified.))
$(TROW $(D values()), $(ARGS Returns a newly allocated dynamic arraycontaining copies of the values in
the associative array in an order that is consistent with `keys()` but otherwise unspecified.))
$(TROW $(D byKey()), $(ARGS Returns a forward range enumerating the keys by reference
in an order that is consistent with `byValue()` but otherwise unspecified.
the associative array. The order is consistent with `values()` but otherwise unspecified.))
$(TROW $(D values()), $(ARGS Returns a newly allocated dynamic array containing copies of the values in
the associative array. The order is consistent with `keys()` but otherwise unspecified.))
$(TROW $(D byKey()), $(ARGS Returns a forward range enumerating the keys by reference.
The order is consistent with `byValue()` but otherwise unspecified.$(BR)
$(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
$(TROW $(D byValue()), $(ARGS Returns a forward range enumerating the values by reference
in an order that is consistent with `byKey()` but otherwise unspecified.))
$(TROW $(D byValue()), $(ARGS Returns a forward range enumerating the values by reference.
The order is consistent with `byKey()` but otherwise unspecified.))
$(TROW $(D byKeyValue()), $(ARGS Returns a forward range enumerating opaque objects that provide a `key` and a `value` property
in an unspecified order. The two properties return their result by reference.
$(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
in an unspecified order. The two properties return their result by reference.$(BR)
$(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.$(BR)
**Note:** `byKeyValue()` is not compatible with the $(REF_SHORT Tuple, std,typecons)
type in Phobos. For compatibility with `Tuple`, use $(REF byPair, std,array) instead.)))
)

$(P The order of keys and values returned by
`keys()` and `values()` as well as
`byKey()`, `byValue()`, and `byKeyValue()` is unspecified,
but is guaranteed to be consistent to each other
as long as the associative array has not been reorganized,
but is guaranteed to be consistent as long as the associative array has not been reorganized,
e.g. by adding or removing keys between the calls.
Associating a new value to an existing key does not reorganize an associative array.
Reorganizing an associative array invalidates any present input ranges
Reorganizing an associative array invalidates any input ranges
returned by `byKey()`, `byValue()`, and `byKeyValue()`.)

$(P Calling `keys()` and `values()` incurs an allocation unless the associative array is `null` or empty.
$(P Calling `keys()` and `values()` incurs an allocation (unless the associative array is `null` or empty).
Use them if you need an independent copy of the keys and/or values;
otherwise consider `byKey()` and `byValue()`.)

$(P Note that `byKeyValue()` is not compatible
with the $(LINK2 $(ROOT_DIR)phobos/std_typecons.html#.Tuple,`Tuple`)
type in Phobos. For compatibility with `Tuple`, use
$(LINK2 $(ROOT_DIR)phobos/std_array.html#.byPair,std.array.byPair) instead.)

$(P Associative arrays support $(LINK2 $(ROOT_DIR)spec/statement.html#foreach_over_associative_arrays, `foreach`)
$(BEST_PRACTICE Associative arrays support
$(DDSUBLINK spec/statement, foreach_over_associative_arrays, `foreach`)
directly for value iteration and key-value iteration.
It is recommended to use `ref` on the key and value variables to avoid unnecessary copies.
Use `ref` on the key and value variables when necessary to avoid unnecessary copies.
For iterating the keys only, use key-value iteration and ignore the value.
Use `byKey()`, `byValue()`, or `byKeyValue()` for more elaborate cases such as range algorithms.)
Use `byKey()`, `byValue()`, or `byKeyValue()` for more elaborate cases such as
$(MREF_ALTTEXT range algorithms, std,algorithm).)

$(TABLE_2COLS Associative Array Elaborate Lookup Operations,
$(H3 $(LNAME2 lookup-ops, Key Lookup Operations))

$(TABLE
$(THEAD Operation, Description)
$(TROW $(D Value get(Key key, lazy Value defVal)),
$(ARGS Looks up $(D key);
if it exists, returns corresponding value;
$(ARGS If the key exists, returns corresponding value;
otherwise evaluates and returns $(D defVal) without associating it with $(D key).))
$(TROW $(D ref Value require(Key key, lazy Value value)),
$(ARGS Looks up $(D key);
if it exists, returns corresponding value by reference;
$(ARGS If the key exists, returns corresponding value by reference;
otherwise evaluates $(D value) and associates it with $(D key) in the associative array,
then returns the newly stored value by reference.))
$(TROW $(D void update(Key key, Creator creator, Updater updater)),
$(ARGS Looks up $(D key);
if it exists, invokes the `updater(value)` on the value (passed by reference if possible)
and then, unless `updater(value)` is `void`, associates the result with the key;
otherwise invokes `creator()` and associates the result with `key` in the associative array.))
$(ARGS If the key exists, it calls `updater` with the corresponding value;
if it returns a value, it associates the value with the key.
If the key was not found, it invokes `creator()` and associates the result with the key.))
)

$(P The `update` operation works with any `creator` and `updater` that is invokable as specified.
An updater can modify the value in-place if it binds its argument by reference.
A `void` returning updater with by-reference parameter is recommended to avoid unnecessary copies.)
`updater` can modify the value in-place if it binds its argument by reference.)

$(BEST_PRACTICE A `void` returning `updater` with a `ref` parameter avoids unnecessary copies.)

$(H2 $(LNAME2 examples, Examples))

Expand Down