authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-04-16 17:56:30-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2021-04-16 17:56:30-07:00
logc8ae581fef6506a8234cdba1355ba7f0f449031a
tree19b5e68b63e296e73bfd17032c5a46352eae38fc
parent5ff45b3f44e7f1272b655b366cee4089d0aa8509

std: deprecate ensureCapacity, add two other capacity functions

I've run into this footgun enough times, nearly every time I want `ensureUnusedCapacity`, not `ensureCapacity`. This commit deprecates `ensureCapacity` in favor of `ensureTotalCapacity` and introduces `ensureUnusedCapacity`.

1 files changed, 36 insertions(+), 14 deletions(-)

lib/std/array_list.zig+36-14
......@@ -132,7 +132,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
132132 /// Insert `item` at index `n` by moving `list[n .. list.len]` to make room.
133133 /// This operation is O(N).
134134 pub fn insert(self: *Self, n: usize, item: T) !void {
135 try self.ensureCapacity(self.items.len + 1);
135 try self.ensureUnusedCapacity(1);
136136 self.items.len += 1;
137137
138138 mem.copyBackwards(T, self.items[n + 1 .. self.items.len], self.items[n .. self.items.len - 1]);
......@@ -142,7 +142,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
142142 /// Insert slice `items` at index `i` by moving `list[i .. list.len]` to make room.
143143 /// This operation is O(N).
144144 pub fn insertSlice(self: *Self, i: usize, items: SliceConst) !void {
145 try self.ensureCapacity(self.items.len + items.len);
145 try self.ensureUnusedCapacity(items.len);
146146 self.items.len += items.len;
147147
148148 mem.copyBackwards(T, self.items[i + items.len .. self.items.len], self.items[i .. self.items.len - items.len]);
......@@ -221,7 +221,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
221221 /// Append the slice of items to the list. Allocates more
222222 /// memory as necessary.
223223 pub fn appendSlice(self: *Self, items: SliceConst) !void {
224 try self.ensureCapacity(self.items.len + items.len);
224 try self.ensureUnusedCapacity(items.len);
225225 self.appendSliceAssumeCapacity(items);
226226 }
227227
......@@ -270,7 +270,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
270270 /// Adjust the list's length to `new_len`.
271271 /// Does not initialize added items if any.
272272 pub fn resize(self: *Self, new_len: usize) !void {
273 try self.ensureCapacity(new_len);
273 try self.ensureTotalCapacity(new_len);
274274 self.items.len = new_len;
275275 }
276276
......@@ -295,9 +295,12 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
295295 self.items.len = new_len;
296296 }
297297
298 /// Deprecated: call `ensureUnusedCapacity` or `ensureTotalCapacity`.
299 pub const ensureCapacity = ensureTotalCapacity;
300
298301 /// Modify the array so that it can hold at least `new_capacity` items.
299302 /// Invalidates pointers if additional memory is needed.
300 pub fn ensureCapacity(self: *Self, new_capacity: usize) !void {
303 pub fn ensureTotalCapacity(self: *Self, new_capacity: usize) !void {
301304 var better_capacity = self.capacity;
302305 if (better_capacity >= new_capacity) return;
303306
......@@ -312,6 +315,12 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
312315 self.capacity = new_memory.len;
313316 }
314317
318 /// Modify the array so that it can hold at least `additional_count` **more** items.
319 /// Invalidates pointers if additional memory is needed.
320 pub fn ensureUnusedCapacity(self: *Self, additional_count: usize) !void {
321 return self.ensureTotalCapacity(self.items.len + additional_count);
322 }
323
315324 /// Increases the array's length to match the full capacity that is already allocated.
316325 /// The new elements have `undefined` values. **Does not** invalidate pointers.
317326 pub fn expandToCapacity(self: *Self) void {
......@@ -322,7 +331,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
322331 /// The returned pointer becomes invalid when the list resized.
323332 pub fn addOne(self: *Self) !*T {
324333 const newlen = self.items.len + 1;
325 try self.ensureCapacity(newlen);
334 try self.ensureTotalCapacity(newlen);
326335 return self.addOneAssumeCapacity();
327336 }
328337
......@@ -473,7 +482,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
473482 /// to higher indices to make room.
474483 /// This operation is O(N).
475484 pub fn insert(self: *Self, allocator: *Allocator, n: usize, item: T) !void {
476 try self.ensureCapacity(allocator, self.items.len + 1);
485 try self.ensureUnusedCapacity(allocator, 1);
477486 self.items.len += 1;
478487
479488 mem.copyBackwards(T, self.items[n + 1 .. self.items.len], self.items[n .. self.items.len - 1]);
......@@ -484,7 +493,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
484493 /// higher indicices make room.
485494 /// This operation is O(N).
486495 pub fn insertSlice(self: *Self, allocator: *Allocator, i: usize, items: SliceConst) !void {
487 try self.ensureCapacity(allocator, self.items.len + items.len);
496 try self.ensureUnusedCapacity(allocator, items.len);
488497 self.items.len += items.len;
489498
490499 mem.copyBackwards(T, self.items[i + items.len .. self.items.len], self.items[i .. self.items.len - items.len]);
......@@ -544,7 +553,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
544553 /// Append the slice of items to the list. Allocates more
545554 /// memory as necessary.
546555 pub fn appendSlice(self: *Self, allocator: *Allocator, items: SliceConst) !void {
547 try self.ensureCapacity(allocator, self.items.len + items.len);
556 try self.ensureUnusedCapacity(allocator, items.len);
548557 self.appendSliceAssumeCapacity(items);
549558 }
550559
......@@ -579,7 +588,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
579588 /// Adjust the list's length to `new_len`.
580589 /// Does not initialize added items, if any.
581590 pub fn resize(self: *Self, allocator: *Allocator, new_len: usize) !void {
582 try self.ensureCapacity(allocator, new_len);
591 try self.ensureTotalCapacity(allocator, new_len);
583592 self.items.len = new_len;
584593 }
585594
......@@ -604,9 +613,12 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
604613 self.items.len = new_len;
605614 }
606615
616 /// Deprecated: call `ensureUnusedCapacity` or `ensureTotalCapacity`.
617 pub const ensureCapacity = ensureTotalCapacity;
618
607619 /// Modify the array so that it can hold at least `new_capacity` items.
608620 /// Invalidates pointers if additional memory is needed.
609 pub fn ensureCapacity(self: *Self, allocator: *Allocator, new_capacity: usize) !void {
621 pub fn ensureTotalCapacity(self: *Self, allocator: *Allocator, new_capacity: usize) !void {
610622 var better_capacity = self.capacity;
611623 if (better_capacity >= new_capacity) return;
612624
......@@ -620,6 +632,16 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
620632 self.capacity = new_memory.len;
621633 }
622634
635 /// Modify the array so that it can hold at least `additional_count` **more** items.
636 /// Invalidates pointers if additional memory is needed.
637 pub fn ensureUnusedCapacity(
638 self: *Self,
639 allocator: *Allocator,
640 additional_count: usize,
641 ) !void {
642 return self.ensureTotalCapacity(allocator, self.items.len + additional_count);
643 }
644
623645 /// Increases the array's length to match the full capacity that is already allocated.
624646 /// The new elements have `undefined` values.
625647 /// **Does not** invalidate pointers.
......@@ -631,7 +653,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
631653 /// The returned pointer becomes invalid when the list resized.
632654 pub fn addOne(self: *Self, allocator: *Allocator) !*T {
633655 const newlen = self.items.len + 1;
634 try self.ensureCapacity(allocator, newlen);
656 try self.ensureTotalCapacity(allocator, newlen);
635657 return self.addOneAssumeCapacity();
636658 }
637659
......@@ -1186,7 +1208,7 @@ test "std.ArrayList/ArrayListUnmanaged.addManyAsArray" {
11861208 defer list.deinit();
11871209
11881210 (try list.addManyAsArray(4)).* = "aoeu".*;
1189 try list.ensureCapacity(8);
1211 try list.ensureTotalCapacity(8);
11901212 list.addManyAsArrayAssumeCapacity(4).* = "asdf".*;
11911213
11921214 testing.expectEqualSlices(u8, list.items, "aoeuasdf");
......@@ -1196,7 +1218,7 @@ test "std.ArrayList/ArrayListUnmanaged.addManyAsArray" {
11961218 defer list.deinit(a);
11971219
11981220 (try list.addManyAsArray(a, 4)).* = "aoeu".*;
1199 try list.ensureCapacity(a, 8);
1221 try list.ensureTotalCapacity(a, 8);
12001222 list.addManyAsArrayAssumeCapacity(4).* = "asdf".*;
12011223
12021224 testing.expectEqualSlices(u8, list.items, "aoeuasdf");