Skip to content

Commit 80d9afd

Browse files
BolpatBolpat
authored
Rework AA properties table (#4339)
1 parent c5600a9 commit 80d9afd

File tree

1 file changed

+84
-45
lines changed

1 file changed

+84
-45
lines changed

‎spec/hash-map.dd‎

Lines changed: 84 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -333,8 +333,8 @@ $(H2 $(LNAME2 advanced_updating, Advanced updating))
333333
$(P Sometimes it is necessary to perform different operations depending on
334334
whether a value already exists or needs to be constructed. The
335335
$(D update) function provides a means to construct a new value via the
336-
$(D create) delegate or update an existing value via the $(D update)
337-
delegate. The $(D update) operation avoids the need to perform multiple
336+
$(D creator) or update an existing value via the $(D updater).
337+
The $(D update) operation avoids the need to perform multiple
338338
key lookups.)
339339

340340
$(SPEC_RUNNABLE_EXAMPLE_RUN
@@ -430,57 +430,96 @@ $(SPEC_RUNNABLE_EXAMPLE_RUN
430430
---
431431
)
432432

433-
$(H2 $(LNAME2 properties, Properties))
434-
435-
$(P Properties for associative arrays are:)
433+
$(H2 $(LNAME2 properties, Properties and Operations))
436434

437435
$(TABLE_2COLS Associative Array Properties,
438-
$(THEAD Property, Description)
439-
$(TROW $(D .sizeof), Returns the size of the reference to the associative
440-
array; it is 4 in 32-bit builds and 8 on 64-bit builds.)
441-
$(TROW $(D .length), $(ARGS Returns number of values in the
436+
$(THEAD Property name, Description)
437+
$(TROW $(D sizeof), $(ARGS The size of the reference to the associative
438+
array; it is 4 in 32-bit builds and 8 on 64-bit builds.))
439+
$(TROW $(D length), $(ARGS The number of values in the
442440
associative array. Unlike for dynamic arrays, it is read-only.))
443-
$(TROW $(D .dup), Create a new associative array of the same size
444-
and copy the contents of the associative array into it.)
445-
$(TROW $(D .keys), $(ARGS Returns dynamic array, the elements of which are the keys in
446-
the associative array.))
447-
$(TROW $(D .values), $(ARGS Returns dynamic array, the elements of which are the values in
448-
the associative array.))
449-
$(TROW $(D .rehash), $(ARGS Reorganizes the associative array in place so that lookups
450-
are more efficient. $(D rehash) is effective when, for example,
451-
the program is done loading up a symbol table and now needs
452-
fast lookups in it. Returns a reference to the reorganized array.))
453-
$(TROW $(D .clear), $(ARGS Removes all remaining keys and values from an associative array.
454-
The array is not rehashed after removal, to allow for the existing storage to be reused.
441+
)
442+
443+
$(P There is no built-in `empty` property.
444+
Phobos provides an implementation of `empty` in `std.range.primitives`.)
445+
446+
$(TABLE_2COLS Associative Array Organizing Operations,
447+
$(TROW $(D dup()), Returns `null` If the associative array is `null`;
448+
otherwise returns a newly allocated associative array with copies of the keys and values of the associative array.)
449+
$(TROW $(D rehash()), $(ARGS Reorganizes the associative array in place so that lookups
450+
are more efficient.))
451+
$(TROW $(D clear()), $(ARGS Removes all keys and values from an associative array.
452+
The array is not rehashed after removal to allow for the existing storage to be reused.
455453
This will affect all references to the same instance and is not equivalent to `destroy(aa)`
456454
which only sets the current reference to `null`))
457-
$(TROW $(D .byKey()), $(ARGS Returns a forward range suitable for use
458-
as a $(I ForeachAggregate) to a $(GLINK2 statement, ForeachStatement)
459-
which will iterate over the keys of the associative array.))
460-
$(TROW $(D .byValue()), $(ARGS Returns a forward range suitable for use
461-
as a $(I ForeachAggregate) to a $(GLINK2 statement, ForeachStatement)
462-
which will iterate over the values of the associative array.))
463-
$(TROW $(D .byKeyValue()), $(ARGS Returns a forward range suitable for
464-
use as a $(I ForeachAggregate) to a $(GLINK2 statement,
465-
ForeachStatement) which will iterate over key-value pairs of the
466-
associative array. The returned pairs are represented by an opaque type
467-
with $(D .key) and $(D .value) properties for accessing the key and
468-
value of the pair, respectively. Note that this is a low-level
469-
interface to iterating over the associative array and is not compatible
455+
)
456+
457+
$(P Calling $(D rehash) is effective when, for example,
458+
the program is done loading up a symbol table and now needs
459+
fast lookups in it. Returns a reference to the reorganized array.)
460+
461+
$(TABLE_2COLS Associative Array Iteration Operations,
462+
$(THEAD Operation, Description)
463+
$(TROW $(D keys()), $(ARGS Returns a newly allocated dynamic array containing copies of the keys in
464+
the associative array in an order that is consistent with `values()` but otherwise unspecified.))
465+
$(TROW $(D values()), $(ARGS Returns a newly allocated dynamic arraycontaining copies of the values in
466+
the associative array in an order that is consistent with `keys()` but otherwise unspecified.))
467+
$(TROW $(D byKey()), $(ARGS Returns a forward range enumerating the keys by reference
468+
in an order that is consistent with `byValue()` but otherwise unspecified.
469+
$(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
470+
$(TROW $(D byValue()), $(ARGS Returns a forward range enumerating the values by reference
471+
in an order that is consistent with `byKey()` but otherwise unspecified.))
472+
$(TROW $(D byKeyValue()), $(ARGS Returns a forward range enumerating opaque objects that provide a `key` and a `value` property
473+
in an unspecified order. The two properties return their result by reference.
474+
$(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
475+
)
476+
477+
$(P The order of keys and values returned by
478+
`keys()` and `values()` as well as
479+
`byKey()`, `byValue()`, and `byKeyValue()` is unspecified,
480+
but is guaranteed to be consistent to each other
481+
as long as the associative array has not been reorganized,
482+
e.g. by adding or removing keys between the calls.
483+
Associating a new value to an existing key does not reorganize an associative array.
484+
Reorganizing an associative array invalidates any present input ranges
485+
returned by `byKey()`, `byValue()`, and `byKeyValue()`.)
486+
487+
$(P Calling `keys()` and `values()` incurs an allocation unless the associative array is `null` or empty.
488+
Use them if you need an independent copy of the keys and/or values;
489+
otherwise consider `byKey()` and `byValue()`.)
490+
491+
$(P Note that `byKeyValue()` is not compatible
470492
with the $(LINK2 $(ROOT_DIR)phobos/std_typecons.html#.Tuple,`Tuple`)
471-
type in Phobos. For compatibility with `Tuple`, use
472-
$(LINK2 $(ROOT_DIR)phobos/std_array.html#.byPair,std.array.byPair) instead.))
473-
$(TROW $(D .get(Key key, lazy Value defVal)),
474-
$(ARGS Looks up $(D key); if it exists returns corresponding value
475-
else evaluates and returns $(D defVal).))
476-
$(TROW $(D .require(Key key, lazy Value value)),
477-
$(ARGS Looks up $(D key); if it exists returns corresponding value
478-
else evaluates $(D value), adds it to the associative array and returns it.))
479-
$(TROW $(D .update(Key key, Value delegate() create, Value delegate(Value) update)),
480-
$(ARGS Looks up $(D key); if it exists applies the $(D update) delegate
481-
else evaluates the $(D create) delegate and adds it to the associative array))
493+
type in Phobos. For compatibility with `Tuple`, use
494+
$(LINK2 $(ROOT_DIR)phobos/std_array.html#.byPair,std.array.byPair) instead.)
495+
496+
$(P Associative arrays support $(LINK2 $(ROOT_DIR)spec/statement.html#foreach_over_associative_arrays, `foreach`)
497+
directly for value iteration and key-value iteration.
498+
It is recommended to use `ref` on the key and value variables to avoid unnecessary copies.
499+
For iterating the keys only, use key-value iteration and ignore the value.
500+
Use `byKey()`, `byValue()`, or `byKeyValue()` for more elaborate cases such as range algorithms.)
501+
502+
$(TABLE_2COLS Associative Array Elaborate Lookup Operations,
503+
$(TROW $(D Value get(Key key, lazy Value defVal)),
504+
$(ARGS Looks up $(D key);
505+
if it exists, returns corresponding value;
506+
otherwise evaluates and returns $(D defVal) without associating it with $(D key).))
507+
$(TROW $(D ref Value require(Key key, lazy Value value)),
508+
$(ARGS Looks up $(D key);
509+
if it exists, returns corresponding value by reference;
510+
otherwise evaluates $(D value) and associates it with $(D key) in the associative array,
511+
then returns the newly stored value by reference.))
512+
$(TROW $(D void update(Key key, Creator creator, Updater updater)),
513+
$(ARGS Looks up $(D key);
514+
if it exists, invokes the `updater(value)` on the value (passed by reference if possible)
515+
and then, unless `updater(value)` is `void`, associates the result with the key;
516+
otherwise invokes `creator()` and associates the result with `key` in the associative array.))
482517
)
483518

519+
$(P The `update` operation works with any `creator` and `updater` that is invokable as specified.
520+
An updater can modify the value in-place if it binds its argument by reference.
521+
A `void` returning updater with by-reference parameter is recommended to avoid unnecessary copies.)
522+
484523
$(H2 $(LNAME2 examples, Examples))
485524

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

0 commit comments

Comments
 (0)