authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-07-26 15:24:25-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-07-26 15:24:25-07:00
logeab934814f39c1fc1f6e3e2a4007cdcabda260e5
treec909aa780161dbb1a345db6358209fce72944641
parent3b3c9d2081118c43311d1af726f575b93a6defdd

docs: ArrayHashMap: warn against the shrink footgun

1 files changed, 42 insertions(+), 8 deletions(-)

lib/std/array_hash_map.zig+42-8
......@@ -454,14 +454,23 @@ pub fn ArrayHashMap(
454454 return self.unmanaged.sortContext(sort_ctx, self.ctx);
455455 }
456456
457 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated
458 /// index entries. Keeps capacity the same.
457 /// Shrinks the underlying `Entry` array to `new_len` elements and
458 /// discards any associated index entries. Keeps capacity the same.
459 ///
460 /// Asserts the discarded entries remain initialized and capable of
461 /// performing hash and equality checks. Any deinitialization of
462 /// discarded entries must take place *after* calling this function.
459463 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
460464 return self.unmanaged.shrinkRetainingCapacityContext(new_len, self.ctx);
461465 }
462466
463 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated
464 /// index entries. Reduces allocated capacity.
467 /// Shrinks the underlying `Entry` array to `new_len` elements and
468 /// discards any associated index entries. Reduces allocated capacity.
469 ///
470 /// Asserts the discarded entries remain initialized and capable of
471 /// performing hash and equality checks. It is a bug to call this
472 /// function if the discarded entries require deinitialization. For
473 /// that use case, `shrinkRetainingCapacity` can be used instead.
465474 pub fn shrinkAndFree(self: *Self, new_len: usize) void {
466475 return self.unmanaged.shrinkAndFreeContext(self.allocator, new_len, self.ctx);
467476 }
......@@ -1359,13 +1368,24 @@ pub fn ArrayHashMapUnmanaged(
13591368 self.insertAllEntriesIntoNewHeader(if (store_hash) {} else ctx, header);
13601369 }
13611370
1362 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated
1363 /// index entries. Keeps capacity the same.
1371 /// Shrinks the underlying `Entry` array to `new_len` elements and
1372 /// discards any associated index entries. Keeps capacity the same.
1373 ///
1374 /// Asserts the discarded entries remain initialized and capable of
1375 /// performing hash and equality checks. Any deinitialization of
1376 /// discarded entries must take place *after* calling this function.
13641377 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
13651378 if (@sizeOf(ByIndexContext) != 0)
13661379 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkRetainingCapacityContext instead.");
13671380 return self.shrinkRetainingCapacityContext(new_len, undefined);
13681381 }
1382
1383 /// Shrinks the underlying `Entry` array to `new_len` elements and
1384 /// discards any associated index entries. Keeps capacity the same.
1385 ///
1386 /// Asserts the discarded entries remain initialized and capable of
1387 /// performing hash and equality checks. Any deinitialization of
1388 /// discarded entries must take place *after* calling this function.
13691389 pub fn shrinkRetainingCapacityContext(self: *Self, new_len: usize, ctx: Context) void {
13701390 self.pointer_stability.lock();
13711391 defer self.pointer_stability.unlock();
......@@ -1381,13 +1401,27 @@ pub fn ArrayHashMapUnmanaged(
13811401 self.entries.shrinkRetainingCapacity(new_len);
13821402 }
13831403
1384 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated
1385 /// index entries. Reduces allocated capacity.
1404 /// Shrinks the underlying `Entry` array to `new_len` elements and
1405 /// discards any associated index entries. Reduces allocated capacity.
1406 ///
1407 /// Asserts the discarded entries remain initialized and capable of
1408 /// performing hash and equality checks. It is a bug to call this
1409 /// function if the discarded entries require deinitialization. For
1410 /// that use case, `shrinkRetainingCapacity` can be used instead.
13861411 pub fn shrinkAndFree(self: *Self, allocator: Allocator, new_len: usize) void {
13871412 if (@sizeOf(ByIndexContext) != 0)
13881413 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkAndFreeContext instead.");
13891414 return self.shrinkAndFreeContext(allocator, new_len, undefined);
13901415 }
1416
1417 /// Shrinks the underlying `Entry` array to `new_len` elements and
1418 /// discards any associated index entries. Reduces allocated capacity.
1419 ///
1420 /// Asserts the discarded entries remain initialized and capable of
1421 /// performing hash and equality checks. It is a bug to call this
1422 /// function if the discarded entries require deinitialization. For
1423 /// that use case, `shrinkRetainingCapacityContext` can be used
1424 /// instead.
13911425 pub fn shrinkAndFreeContext(self: *Self, allocator: Allocator, new_len: usize, ctx: Context) void {
13921426 self.pointer_stability.lock();
13931427 defer self.pointer_stability.unlock();