authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-21 17:41:21-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-21 17:54:58-07:00
log1e46e36eac8cbaf1c011d9753830eb807c386e67
treee4ca1d28176992cf944fe6cbe6626b755e08aa10
parent7bc0b74b6d57ff1a350a4f430f7d9e799a90edd0

std.array_hash_map: enhance doc comments

- more readable in markdown - remove confusing stuff - linkification - rewording - move parameter documentation to parameter documentation

1 files changed, 51 insertions(+), 38 deletions(-)

lib/std/array_hash_map.zig+51-38
......@@ -9,23 +9,26 @@ const Wyhash = std.hash.Wyhash;
99const Allocator = mem.Allocator;
1010const hash_map = @This();
1111
12/// An ArrayHashMap with default hash and equal functions.
13/// See AutoContext for a description of the hash and equal implementations.
12/// An `ArrayHashMap` with default hash and equal functions.
13///
14/// See `AutoContext` for a description of the hash and equal implementations.
1415pub fn AutoArrayHashMap(comptime K: type, comptime V: type) type {
1516 return ArrayHashMap(K, V, AutoContext(K), !autoEqlIsCheap(K));
1617}
1718
18/// An ArrayHashMapUnmanaged with default hash and equal functions.
19/// See AutoContext for a description of the hash and equal implementations.
19/// An `ArrayHashMapUnmanaged` with default hash and equal functions.
20///
21/// See `AutoContext` for a description of the hash and equal implementations.
2022pub fn AutoArrayHashMapUnmanaged(comptime K: type, comptime V: type) type {
2123 return ArrayHashMapUnmanaged(K, V, AutoContext(K), !autoEqlIsCheap(K));
2224}
2325
24/// Builtin hashmap for strings as keys.
26/// An `ArrayHashMap` with strings as keys.
2527pub fn StringArrayHashMap(comptime V: type) type {
2628 return ArrayHashMap([]const u8, V, StringContext, true);
2729}
2830
31/// An `ArrayHashMapUnmanaged` with strings as keys.
2932pub fn StringArrayHashMapUnmanaged(comptime V: type) type {
3033 return ArrayHashMapUnmanaged([]const u8, V, StringContext, true);
3134}
......@@ -50,29 +53,33 @@ pub fn hashString(s: []const u8) u32 {
5053 return @as(u32, @truncate(std.hash.Wyhash.hash(0, s)));
5154}
5255
53/// Insertion order is preserved.
54/// Deletions perform a "swap removal" on the entries list.
56/// A hash table of keys and values, each stored sequentially.
57///
58/// Insertion order is preserved. In general, this data structure supports the same
59/// operations as `std.ArrayList`.
60///
61/// Deletion operations:
62/// * `swapRemove` - O(1)
63/// * `orderedRemove` - O(N)
64///
5565/// Modifying the hash map while iterating is allowed, however, one must understand
5666/// the (well defined) behavior when mixing insertions and deletions with iteration.
57/// For a hash map that can be initialized directly that does not store an Allocator
58/// field, see `ArrayHashMapUnmanaged`.
59/// When `store_hash` is `false`, this data structure is biased towards cheap `eql`
60/// functions. It does not store each item's hash in the table. Setting `store_hash`
61/// to `true` incurs slightly more memory cost by storing each key's hash in the table
62/// but only has to call `eql` for hash collisions.
63/// If typical operations (except iteration over entries) need to be faster, prefer
64/// the alternative `std.HashMap`.
65/// Context must be a struct type with two member functions:
66/// hash(self, K) u32
67/// eql(self, K, K, usize) bool
68/// Adapted variants of many functions are provided. These variants
69/// take a pseudo key instead of a key. Their context must have the functions:
70/// hash(self, PseudoKey) u32
71/// eql(self, PseudoKey, K, usize) bool
67///
68/// See `ArrayHashMapUnmanaged` for a variant of this data structure that accepts an
69/// `Allocator` as a parameter when needed rather than storing it.
7270pub fn ArrayHashMap(
7371 comptime K: type,
7472 comptime V: type,
73 /// A namespace that provides these two functions:
74 /// * `pub fn hash(self, K) u32`
75 /// * `pub fn eql(self, K, K) bool`
76 ///
7577 comptime Context: type,
78 /// When `false`, this data structure is biased towards cheap `eql`
79 /// functions and avoids storing each key's hash in the table. Setting
80 /// `store_hash` to `true` incurs more memory cost but limits `eql` to
81 /// being called only once per insertion/deletion (provided there are no
82 /// hash collisions).
7683 comptime store_hash: bool,
7784) type {
7885 return struct {
......@@ -472,34 +479,40 @@ pub fn ArrayHashMap(
472479 };
473480}
474481
475/// General purpose hash table.
476/// Insertion order is preserved.
477/// Deletions perform a "swap removal" on the entries list.
482/// A hash table of keys and values, each stored sequentially.
483///
484/// Insertion order is preserved. In general, this data structure supports the same
485/// operations as `std.ArrayListUnmanaged`.
486///
487/// Deletion operations:
488/// * `swapRemove` - O(1)
489/// * `orderedRemove` - O(N)
490///
478491/// Modifying the hash map while iterating is allowed, however, one must understand
479492/// the (well defined) behavior when mixing insertions and deletions with iteration.
480/// This type does not store an Allocator field - the Allocator must be passed in
493///
494/// This type does not store an `Allocator` field - the `Allocator` must be passed in
481495/// with each function call that requires it. See `ArrayHashMap` for a type that stores
482/// an Allocator field for convenience.
496/// an `Allocator` field for convenience.
497///
483498/// Can be initialized directly using the default field values.
499///
484500/// This type is designed to have low overhead for small numbers of entries. When
485501/// `store_hash` is `false` and the number of entries in the map is less than 9,
486502/// the overhead cost of using `ArrayHashMapUnmanaged` rather than `std.ArrayList` is
487503/// only a single pointer-sized integer.
488/// When `store_hash` is `false`, this data structure is biased towards cheap `eql`
489/// functions. It does not store each item's hash in the table. Setting `store_hash`
490/// to `true` incurs slightly more memory cost by storing each key's hash in the table
491/// but guarantees only one call to `eql` per insertion/deletion.
492/// Context must be a struct type with two member functions:
493/// hash(self, K) u32
494/// eql(self, K, K) bool
495/// Adapted variants of many functions are provided. These variants
496/// take a pseudo key instead of a key. Their context must have the functions:
497/// hash(self, PseudoKey) u32
498/// eql(self, PseudoKey, K) bool
499504pub fn ArrayHashMapUnmanaged(
500505 comptime K: type,
501506 comptime V: type,
507 /// A namespace that provides these two functions:
508 /// * `pub fn hash(self, K) u32`
509 /// * `pub fn eql(self, K, K) bool`
502510 comptime Context: type,
511 /// When `false`, this data structure is biased towards cheap `eql`
512 /// functions and avoids storing each key's hash in the table. Setting
513 /// `store_hash` to `true` incurs more memory cost but limits `eql` to
514 /// being called only once per insertion/deletion (provided there are no
515 /// hash collisions).
503516 comptime store_hash: bool,
504517) type {
505518 return struct {