Skip to content

Rework AA properties table #4339

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 4 commits into from
Dec 4, 2025
Merged

Rework AA properties table #4339

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e7a539
Rework AA properties table
Bolpat Dec 2, 2025
b9d534b
`empty` is not defined in object.d
Bolpat Dec 4, 2025
bcff58b
Improve section associative array properties and operations
Bolpat Dec 4, 2025
ce716ea
Split into different tables
Bolpat Dec 4, 2025
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
129 changes: 84 additions & 45 deletions spec/hash-map.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,8 +333,8 @@ $(H2 $(LNAME2 advanced_updating, Advanced updating))
$(P Sometimes it is necessary to perform different operations depending on
whether a value already exists or needs to be constructed. The
$(D update) function provides a means to construct a new value via the
$(D create) delegate or update an existing value via the $(D update)
delegate. The $(D update) operation avoids the need to perform multiple
$(D creator) or update an existing value via the $(D updater).
The $(D update) operation avoids the need to perform multiple
key lookups.)

$(SPEC_RUNNABLE_EXAMPLE_RUN
Expand Down Expand Up @@ -430,57 +430,96 @@ $(SPEC_RUNNABLE_EXAMPLE_RUN
---
)

$(H2 $(LNAME2 properties, Properties))

$(P Properties for associative arrays are:)
$(H2 $(LNAME2 properties, Properties and Operations))

$(TABLE_2COLS Associative Array Properties,
$(THEAD Property, Description)
$(TROW $(D .sizeof), Returns 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 Returns number of values in the
$(THEAD Property 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.))
$(TROW $(D .dup), Create a new associative array of the same size
and copy the contents of the associative array into it.)
$(TROW $(D .keys), $(ARGS Returns dynamic array, the elements of which are the keys in
the associative array.))
$(TROW $(D .values), $(ARGS Returns dynamic array, the elements of which are the values in
the associative array.))
$(TROW $(D .rehash), $(ARGS Reorganizes the associative array in place so that lookups
are more efficient. $(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 remaining keys and values from an associative array.
The array is not rehashed after removal, to allow for the existing storage to be reused.
)

$(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`;
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.))
$(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`))
$(TROW $(D .byKey()), $(ARGS Returns a forward range suitable for use
as a $(I ForeachAggregate) to a $(GLINK2 statement, ForeachStatement)
which will iterate over the keys of the associative array.))
$(TROW $(D .byValue()), $(ARGS Returns a forward range suitable for use
as a $(I ForeachAggregate) to a $(GLINK2 statement, ForeachStatement)
which will iterate over the values of the associative array.))
$(TROW $(D .byKeyValue()), $(ARGS Returns a forward range suitable for
use as a $(I ForeachAggregate) to a $(GLINK2 statement,
ForeachStatement) which will iterate over key-value pairs of the
associative array. The returned pairs are represented by an opaque type
with $(D .key) and $(D .value) properties for accessing the key and
value of the pair, respectively. Note that this is a low-level
interface to iterating over the associative array and is not compatible
)

$(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.)

$(TABLE_2COLS Associative Array Iteration Operations,
$(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.
$(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 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.))
)

$(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,
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
returned by `byKey()`, `byValue()`, and `byKeyValue()`.)

$(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.))
$(TROW $(D .get(Key key, lazy Value defVal)),
$(ARGS Looks up $(D key); if it exists returns corresponding value
else evaluates and returns $(D defVal).))
$(TROW $(D .require(Key key, lazy Value value)),
$(ARGS Looks up $(D key); if it exists returns corresponding value
else evaluates $(D value), adds it to the associative array and returns it.))
$(TROW $(D .update(Key key, Value delegate() create, Value delegate(Value) update)),
$(ARGS Looks up $(D key); if it exists applies the $(D update) delegate
else evaluates the $(D create) delegate and adds it to the associative array))
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`)
directly for value iteration and key-value iteration.
It is recommended to use `ref` on the key and value variables 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.)

$(TABLE_2COLS Associative Array Elaborate Lookup Operations,
$(TROW $(D Value get(Key key, lazy Value defVal)),
$(ARGS Looks up $(D key);
if it 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;
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.))
)

$(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.)

$(H2 $(LNAME2 examples, Examples))

$(H3 $(LNAME2 aa_example, Associative Array Example: word count))
Expand Down