authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-12-03 16:51:58-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-12-03 16:51:58-08:00
logb3cd5b23a228d4f2b0253d90efa9bc326338b66c
treefb7e109c076bd06c21116685c26ca1f8667902fd
parent702d014f07e1403e5b52a85b3cc290707e3dc8ef

ArrayList: rename "ensure" to "reserve"

Matches the same word used for the corresponding append functions.

1 files changed, 49 insertions(+), 32 deletions(-)

lib/std/array_list.zig+49-32
......@@ -63,7 +63,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
6363 /// Deinitialize with `deinit` or use `toOwnedSlice`.
6464 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {
6565 var self = Self.init(allocator);
66 try self.ensureTotalCapacityPrecise(num);
66 try self.reserveTotalPrecise(num);
6767 return self;
6868 }
6969
......@@ -127,7 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
127127 /// The caller owns the returned memory. Empties this ArrayList.
128128 pub fn toOwnedSliceSentinel(self: *Self, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {
129129 // This addition can never overflow because `self.items` can never occupy the whole address space
130 try self.ensureTotalCapacityPrecise(self.items.len + 1);
130 try self.reserveTotalPrecise(self.items.len + 1);
131131 self.appendReserved(sentinel);
132132 const result = try self.toOwnedSlice();
133133 return result[0 .. result.len - 1 :sentinel];
......@@ -193,8 +193,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
193193 return addManyAtReserved(self, index, count);
194194 }
195195
196 // Make a new allocation, avoiding `ensureTotalCapacity` in order
197 // to avoid extra memory copies.
196 // Make a new allocation, avoiding extra memory copies by avoiding
197 // `reserveTotal`.
198198 const new_memory = try self.allocator.alignedAlloc(T, alignment, new_capacity);
199199 const to_move = self.items[index..];
200200 @memcpy(new_memory[0..index], self.items[0..index]);
......@@ -314,7 +314,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
314314 /// memory as necessary.
315315 /// Invalidates element pointers if additional memory is needed.
316316 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {
317 try self.ensureUnusedCapacity(items.len);
317 try self.reserveUnused(items.len);
318318 self.appendSliceReserved(items);
319319 }
320320
......@@ -337,7 +337,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
337337 /// `appendSlice` instead would be a compile error.
338338 /// Invalidates element pointers if additional memory is needed.
339339 pub fn appendUnalignedSlice(self: *Self, items: []align(1) const T) Allocator.Error!void {
340 try self.ensureUnusedCapacity(items.len);
340 try self.reserveUnused(items.len);
341341 self.appendUnalignedSliceReserved(items);
342342 }
343343
......@@ -425,7 +425,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
425425 /// Additional elements contain the value `undefined`.
426426 /// Invalidates element pointers if additional memory is needed.
427427 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {
428 try self.ensureTotalCapacity(new_len);
428 try self.reserveTotal(new_len);
429429 self.items.len = new_len;
430430 }
431431
......@@ -458,10 +458,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
458458 self.capacity = 0;
459459 }
460460
461 /// Deprecated. To be removed after 0.14.0 is tagged.
462 pub const ensureTotalCapacity = reserveTotal;
463
461464 /// If the current capacity is less than `new_capacity`, this function will
462465 /// modify the array so that it can hold at least `new_capacity` items.
463466 /// Invalidates element pointers if additional memory is needed.
464 pub fn ensureTotalCapacity(self: *Self, new_capacity: usize) Allocator.Error!void {
467 pub fn reserveTotal(self: *Self, new_capacity: usize) Allocator.Error!void {
465468 if (@sizeOf(T) == 0) {
466469 self.capacity = math.maxInt(usize);
467470 return;
......@@ -470,13 +473,16 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
470473 if (self.capacity >= new_capacity) return;
471474
472475 const better_capacity = growCapacity(self.capacity, new_capacity);
473 return self.ensureTotalCapacityPrecise(better_capacity);
476 return self.reserveTotalPrecise(better_capacity);
474477 }
475478
479 /// Deprecated. To be removed after 0.14.0 is tagged.
480 pub const ensureTotalCapacityPrecise = reserveTotalPrecise;
481
476482 /// If the current capacity is less than `new_capacity`, this function will
477483 /// modify the array so that it can hold exactly `new_capacity` items.
478484 /// Invalidates element pointers if additional memory is needed.
479 pub fn ensureTotalCapacityPrecise(self: *Self, new_capacity: usize) Allocator.Error!void {
485 pub fn reserveTotalPrecise(self: *Self, new_capacity: usize) Allocator.Error!void {
480486 if (@sizeOf(T) == 0) {
481487 self.capacity = math.maxInt(usize);
482488 return;
......@@ -501,10 +507,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
501507 }
502508 }
503509
510 /// Deprecated. To be removed after 0.14.0 is tagged.
511 pub const ensureUnusedCapacity = reserveUnused;
512
504513 /// Modify the array so that it can hold at least `additional_count` **more** items.
505514 /// Invalidates element pointers if additional memory is needed.
506 pub fn ensureUnusedCapacity(self: *Self, additional_count: usize) Allocator.Error!void {
507 return self.ensureTotalCapacity(try addOrOom(self.items.len, additional_count));
515 pub fn reserveUnused(self: *Self, additional_count: usize) Allocator.Error!void {
516 return self.reserveTotal(try addOrOom(self.items.len, additional_count));
508517 }
509518
510519 /// Increases the array's length to match the full capacity that is already allocated.
......@@ -519,7 +528,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
519528 pub fn addOne(self: *Self) Allocator.Error!*T {
520529 // This can never overflow because `self.items` can never occupy the whole address space
521530 const newlen = self.items.len + 1;
522 try self.ensureTotalCapacity(newlen);
531 try self.reserveTotal(newlen);
523532 return self.addOneReserved();
524533 }
525534
......@@ -687,7 +696,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
687696 /// Deinitialize with `deinit` or use `toOwnedSlice`.
688697 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {
689698 var self = Self{};
690 try self.ensureTotalCapacityPrecise(allocator, num);
699 try self.reserveTotalPrecise(allocator, num);
691700 return self;
692701 }
693702
......@@ -754,7 +763,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
754763 /// The caller owns the returned memory. ArrayList becomes empty.
755764 pub fn toOwnedSliceSentinel(self: *Self, allocator: Allocator, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {
756765 // This addition can never overflow because `self.items` can never occupy the whole address space
757 try self.ensureTotalCapacityPrecise(allocator, self.items.len + 1);
766 try self.reserveTotalPrecise(allocator, self.items.len + 1);
758767 self.appendReserved(sentinel);
759768 const result = try self.toOwnedSlice(allocator);
760769 return result[0 .. result.len - 1 :sentinel];
......@@ -954,7 +963,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
954963 /// memory as necessary.
955964 /// Invalidates element pointers if additional memory is needed.
956965 pub fn appendSlice(self: *Self, allocator: Allocator, items: []const T) Allocator.Error!void {
957 try self.ensureUnusedCapacity(allocator, items.len);
966 try self.reserveUnused(allocator, items.len);
958967 self.appendSliceReserved(items);
959968 }
960969
......@@ -976,7 +985,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
976985 /// be a compile error.
977986 /// Invalidates element pointers if additional memory is needed.
978987 pub fn appendUnalignedSlice(self: *Self, allocator: Allocator, items: []align(1) const T) Allocator.Error!void {
979 try self.ensureUnusedCapacity(allocator, items.len);
988 try self.reserveUnused(allocator, items.len);
980989 self.appendUnalignedSliceReserved(items);
981990 }
982991
......@@ -1049,6 +1058,9 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
10491058 @memset(self.items[old_len..self.items.len], value);
10501059 }
10511060
1061 /// Deprecated. To be removed after 0.14.0 is tagged.
1062 pub const appendNTimesAssumeCapacity = appendNTimesReserved;
1063
10521064 /// Append a value to the list `n` times.
10531065 /// Never invalidates element pointers.
10541066 /// The function is inline so that a comptime-known `value` parameter will
......@@ -1065,7 +1077,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
10651077 /// Additional elements contain the value `undefined`.
10661078 /// Invalidates element pointers if additional memory is needed.
10671079 pub fn resize(self: *Self, allocator: Allocator, new_len: usize) Allocator.Error!void {
1068 try self.ensureTotalCapacity(allocator, new_len);
1080 try self.reserveTotal(allocator, new_len);
10691081 self.items.len = new_len;
10701082 }
10711083
......@@ -1122,20 +1134,26 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
11221134 self.capacity = 0;
11231135 }
11241136
1137 /// Deprecated. To be removed after 0.14.0 is tagged.
1138 pub const ensureTotalCapacity = reserveTotal;
1139
11251140 /// If the current capacity is less than `new_capacity`, this function will
11261141 /// modify the array so that it can hold at least `new_capacity` items.
11271142 /// Invalidates element pointers if additional memory is needed.
1128 pub fn ensureTotalCapacity(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
1143 pub fn reserveTotal(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
11291144 if (self.capacity >= new_capacity) return;
11301145
11311146 const better_capacity = growCapacity(self.capacity, new_capacity);
1132 return self.ensureTotalCapacityPrecise(allocator, better_capacity);
1147 return self.reserveTotalPrecise(allocator, better_capacity);
11331148 }
11341149
1150 /// Deprecated. To be removed after 0.14.0 is tagged.
1151 pub const ensureTotalCapacityPrecise = reserveTotalPrecise;
1152
11351153 /// If the current capacity is less than `new_capacity`, this function will
11361154 /// modify the array so that it can hold exactly `new_capacity` items.
11371155 /// Invalidates element pointers if additional memory is needed.
1138 pub fn ensureTotalCapacityPrecise(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
1156 pub fn reserveTotalPrecise(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
11391157 if (@sizeOf(T) == 0) {
11401158 self.capacity = math.maxInt(usize);
11411159 return;
......@@ -1160,14 +1178,13 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
11601178 }
11611179 }
11621180
1181 /// Deprecated. To be removed after 0.14.0 is tagged.
1182 pub const ensureUnusedCapacity = reserveUnused;
1183
11631184 /// Modify the array so that it can hold at least `additional_count` **more** items.
11641185 /// Invalidates element pointers if additional memory is needed.
1165 pub fn ensureUnusedCapacity(
1166 self: *Self,
1167 allocator: Allocator,
1168 additional_count: usize,
1169 ) Allocator.Error!void {
1170 return self.ensureTotalCapacity(allocator, try addOrOom(self.items.len, additional_count));
1186 pub fn reserveUnused(self: *Self, allocator: Allocator, additional_count: usize) Allocator.Error!void {
1187 return self.reserveTotal(allocator, try addOrOom(self.items.len, additional_count));
11711188 }
11721189
11731190 /// Increases the array's length to match the full capacity that is already allocated.
......@@ -1182,7 +1199,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
11821199 pub fn addOne(self: *Self, allocator: Allocator) Allocator.Error!*T {
11831200 // This can never overflow because `self.items` can never occupy the whole address space
11841201 const newlen = self.items.len + 1;
1185 try self.ensureTotalCapacity(allocator, newlen);
1202 try self.reserveTotal(allocator, newlen);
11861203 return self.addOneReserved();
11871204 }
11881205
......@@ -2077,7 +2094,7 @@ test "addManyAsArray" {
20772094 defer list.deinit();
20782095
20792096 (try list.addManyAsArray(4)).* = "aoeu".*;
2080 try list.ensureTotalCapacity(8);
2097 try list.reserveTotal(8);
20812098 list.addManyAsArrayReserved(4).* = "asdf".*;
20822099
20832100 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");
......@@ -2087,7 +2104,7 @@ test "addManyAsArray" {
20872104 defer list.deinit(a);
20882105
20892106 (try list.addManyAsArray(a, 4)).* = "aoeu".*;
2090 try list.ensureTotalCapacity(a, 8);
2107 try list.reserveTotal(a, 8);
20912108 list.addManyAsArrayReserved(4).* = "asdf".*;
20922109
20932110 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");
......@@ -2304,7 +2321,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"
23042321 try testing.expectError(error.OutOfMemory, list.addManyAsArray(a, 2));
23052322 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(a, 2));
23062323 try testing.expectError(error.OutOfMemory, list.insertSlice(a, 0, items));
2307 try testing.expectError(error.OutOfMemory, list.ensureUnusedCapacity(a, 2));
2324 try testing.expectError(error.OutOfMemory, list.reserveUnused(a, 2));
23082325 }
23092326
23102327 {
......@@ -2322,7 +2339,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"
23222339 try testing.expectError(error.OutOfMemory, list.addManyAsArray(2));
23232340 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(2));
23242341 try testing.expectError(error.OutOfMemory, list.insertSlice(0, items));
2325 try testing.expectError(error.OutOfMemory, list.ensureUnusedCapacity(2));
2342 try testing.expectError(error.OutOfMemory, list.reserveUnused(2));
23262343 }
23272344}
23282345