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(...@@ -454,14 +454,23 @@ pub fn ArrayHashMap(
454 return self.unmanaged.sortContext(sort_ctx, self.ctx);454 return self.unmanaged.sortContext(sort_ctx, self.ctx);
455 }455 }
456456
457 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated457 /// Shrinks the underlying `Entry` array to `new_len` elements and
458 /// index entries. Keeps capacity the same.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.
459 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {463 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
460 return self.unmanaged.shrinkRetainingCapacityContext(new_len, self.ctx);464 return self.unmanaged.shrinkRetainingCapacityContext(new_len, self.ctx);
461 }465 }
462466
463 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated467 /// Shrinks the underlying `Entry` array to `new_len` elements and
464 /// index entries. Reduces allocated capacity.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.
465 pub fn shrinkAndFree(self: *Self, new_len: usize) void {474 pub fn shrinkAndFree(self: *Self, new_len: usize) void {
466 return self.unmanaged.shrinkAndFreeContext(self.allocator, new_len, self.ctx);475 return self.unmanaged.shrinkAndFreeContext(self.allocator, new_len, self.ctx);
467 }476 }
...@@ -1359,13 +1368,24 @@ pub fn ArrayHashMapUnmanaged(...@@ -1359,13 +1368,24 @@ pub fn ArrayHashMapUnmanaged(
1359 self.insertAllEntriesIntoNewHeader(if (store_hash) {} else ctx, header);1368 self.insertAllEntriesIntoNewHeader(if (store_hash) {} else ctx, header);
1360 }1369 }
13611370
1362 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated1371 /// Shrinks the underlying `Entry` array to `new_len` elements and
1363 /// index entries. Keeps capacity the same.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.
1364 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {1377 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
1365 if (@sizeOf(ByIndexContext) != 0)1378 if (@sizeOf(ByIndexContext) != 0)
1366 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkRetainingCapacityContext instead.");1379 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkRetainingCapacityContext instead.");
1367 return self.shrinkRetainingCapacityContext(new_len, undefined);1380 return self.shrinkRetainingCapacityContext(new_len, undefined);
1368 }1381 }
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.
1369 pub fn shrinkRetainingCapacityContext(self: *Self, new_len: usize, ctx: Context) void {1389 pub fn shrinkRetainingCapacityContext(self: *Self, new_len: usize, ctx: Context) void {
1370 self.pointer_stability.lock();1390 self.pointer_stability.lock();
1371 defer self.pointer_stability.unlock();1391 defer self.pointer_stability.unlock();
...@@ -1381,13 +1401,27 @@ pub fn ArrayHashMapUnmanaged(...@@ -1381,13 +1401,27 @@ pub fn ArrayHashMapUnmanaged(
1381 self.entries.shrinkRetainingCapacity(new_len);1401 self.entries.shrinkRetainingCapacity(new_len);
1382 }1402 }
13831403
1384 /// Shrinks the underlying `Entry` array to `new_len` elements and discards any associated1404 /// Shrinks the underlying `Entry` array to `new_len` elements and
1385 /// index entries. Reduces allocated capacity.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.
1386 pub fn shrinkAndFree(self: *Self, allocator: Allocator, new_len: usize) void {1411 pub fn shrinkAndFree(self: *Self, allocator: Allocator, new_len: usize) void {
1387 if (@sizeOf(ByIndexContext) != 0)1412 if (@sizeOf(ByIndexContext) != 0)
1388 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkAndFreeContext instead.");1413 @compileError("Cannot infer context " ++ @typeName(Context) ++ ", call shrinkAndFreeContext instead.");
1389 return self.shrinkAndFreeContext(allocator, new_len, undefined);1414 return self.shrinkAndFreeContext(allocator, new_len, undefined);
1390 }1415 }
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.
1391 pub fn shrinkAndFreeContext(self: *Self, allocator: Allocator, new_len: usize, ctx: Context) void {1425 pub fn shrinkAndFreeContext(self: *Self, allocator: Allocator, new_len: usize, ctx: Context) void {
1392 self.pointer_stability.lock();1426 self.pointer_stability.lock();
1393 defer self.pointer_stability.unlock();1427 defer self.pointer_stability.unlock();