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 {...@@ -63,7 +63,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
63 /// Deinitialize with `deinit` or use `toOwnedSlice`.63 /// Deinitialize with `deinit` or use `toOwnedSlice`.
64 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {64 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {
65 var self = Self.init(allocator);65 var self = Self.init(allocator);
66 try self.ensureTotalCapacityPrecise(num);66 try self.reserveTotalPrecise(num);
67 return self;67 return self;
68 }68 }
6969
...@@ -127,7 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -127,7 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
127 /// The caller owns the returned memory. Empties this ArrayList.127 /// The caller owns the returned memory. Empties this ArrayList.
128 pub fn toOwnedSliceSentinel(self: *Self, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {128 pub fn toOwnedSliceSentinel(self: *Self, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {
129 // This addition can never overflow because `self.items` can never occupy the whole address space129 // 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);
131 self.appendReserved(sentinel);131 self.appendReserved(sentinel);
132 const result = try self.toOwnedSlice();132 const result = try self.toOwnedSlice();
133 return result[0 .. result.len - 1 :sentinel];133 return result[0 .. result.len - 1 :sentinel];
...@@ -193,8 +193,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -193,8 +193,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
193 return addManyAtReserved(self, index, count);193 return addManyAtReserved(self, index, count);
194 }194 }
195195
196 // Make a new allocation, avoiding `ensureTotalCapacity` in order196 // Make a new allocation, avoiding extra memory copies by avoiding
197 // to avoid extra memory copies.197 // `reserveTotal`.
198 const new_memory = try self.allocator.alignedAlloc(T, alignment, new_capacity);198 const new_memory = try self.allocator.alignedAlloc(T, alignment, new_capacity);
199 const to_move = self.items[index..];199 const to_move = self.items[index..];
200 @memcpy(new_memory[0..index], self.items[0..index]);200 @memcpy(new_memory[0..index], self.items[0..index]);
...@@ -314,7 +314,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -314,7 +314,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
314 /// memory as necessary.314 /// memory as necessary.
315 /// Invalidates element pointers if additional memory is needed.315 /// Invalidates element pointers if additional memory is needed.
316 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {316 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {
317 try self.ensureUnusedCapacity(items.len);317 try self.reserveUnused(items.len);
318 self.appendSliceReserved(items);318 self.appendSliceReserved(items);
319 }319 }
320320
...@@ -337,7 +337,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -337,7 +337,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
337 /// `appendSlice` instead would be a compile error.337 /// `appendSlice` instead would be a compile error.
338 /// Invalidates element pointers if additional memory is needed.338 /// Invalidates element pointers if additional memory is needed.
339 pub fn appendUnalignedSlice(self: *Self, items: []align(1) const T) Allocator.Error!void {339 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);
341 self.appendUnalignedSliceReserved(items);341 self.appendUnalignedSliceReserved(items);
342 }342 }
343343
...@@ -425,7 +425,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -425,7 +425,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
425 /// Additional elements contain the value `undefined`.425 /// Additional elements contain the value `undefined`.
426 /// Invalidates element pointers if additional memory is needed.426 /// Invalidates element pointers if additional memory is needed.
427 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {427 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {
428 try self.ensureTotalCapacity(new_len);428 try self.reserveTotal(new_len);
429 self.items.len = new_len;429 self.items.len = new_len;
430 }430 }
431431
...@@ -458,10 +458,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -458,10 +458,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
458 self.capacity = 0;458 self.capacity = 0;
459 }459 }
460460
461 /// Deprecated. To be removed after 0.14.0 is tagged.
462 pub const ensureTotalCapacity = reserveTotal;
463
461 /// If the current capacity is less than `new_capacity`, this function will464 /// If the current capacity is less than `new_capacity`, this function will
462 /// modify the array so that it can hold at least `new_capacity` items.465 /// modify the array so that it can hold at least `new_capacity` items.
463 /// Invalidates element pointers if additional memory is needed.466 /// 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 {
465 if (@sizeOf(T) == 0) {468 if (@sizeOf(T) == 0) {
466 self.capacity = math.maxInt(usize);469 self.capacity = math.maxInt(usize);
467 return;470 return;
...@@ -470,13 +473,16 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -470,13 +473,16 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
470 if (self.capacity >= new_capacity) return;473 if (self.capacity >= new_capacity) return;
471474
472 const better_capacity = growCapacity(self.capacity, new_capacity);475 const better_capacity = growCapacity(self.capacity, new_capacity);
473 return self.ensureTotalCapacityPrecise(better_capacity);476 return self.reserveTotalPrecise(better_capacity);
474 }477 }
475478
479 /// Deprecated. To be removed after 0.14.0 is tagged.
480 pub const ensureTotalCapacityPrecise = reserveTotalPrecise;
481
476 /// If the current capacity is less than `new_capacity`, this function will482 /// If the current capacity is less than `new_capacity`, this function will
477 /// modify the array so that it can hold exactly `new_capacity` items.483 /// modify the array so that it can hold exactly `new_capacity` items.
478 /// Invalidates element pointers if additional memory is needed.484 /// 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 {
480 if (@sizeOf(T) == 0) {486 if (@sizeOf(T) == 0) {
481 self.capacity = math.maxInt(usize);487 self.capacity = math.maxInt(usize);
482 return;488 return;
...@@ -501,10 +507,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -501,10 +507,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
501 }507 }
502 }508 }
503509
510 /// Deprecated. To be removed after 0.14.0 is tagged.
511 pub const ensureUnusedCapacity = reserveUnused;
512
504 /// Modify the array so that it can hold at least `additional_count` **more** items.513 /// Modify the array so that it can hold at least `additional_count` **more** items.
505 /// Invalidates element pointers if additional memory is needed.514 /// Invalidates element pointers if additional memory is needed.
506 pub fn ensureUnusedCapacity(self: *Self, additional_count: usize) Allocator.Error!void {515 pub fn reserveUnused(self: *Self, additional_count: usize) Allocator.Error!void {
507 return self.ensureTotalCapacity(try addOrOom(self.items.len, additional_count));516 return self.reserveTotal(try addOrOom(self.items.len, additional_count));
508 }517 }
509518
510 /// Increases the array's length to match the full capacity that is already allocated.519 /// 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 {...@@ -519,7 +528,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
519 pub fn addOne(self: *Self) Allocator.Error!*T {528 pub fn addOne(self: *Self) Allocator.Error!*T {
520 // This can never overflow because `self.items` can never occupy the whole address space529 // This can never overflow because `self.items` can never occupy the whole address space
521 const newlen = self.items.len + 1;530 const newlen = self.items.len + 1;
522 try self.ensureTotalCapacity(newlen);531 try self.reserveTotal(newlen);
523 return self.addOneReserved();532 return self.addOneReserved();
524 }533 }
525534
...@@ -687,7 +696,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -687,7 +696,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
687 /// Deinitialize with `deinit` or use `toOwnedSlice`.696 /// Deinitialize with `deinit` or use `toOwnedSlice`.
688 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {697 pub fn initCapacity(allocator: Allocator, num: usize) Allocator.Error!Self {
689 var self = Self{};698 var self = Self{};
690 try self.ensureTotalCapacityPrecise(allocator, num);699 try self.reserveTotalPrecise(allocator, num);
691 return self;700 return self;
692 }701 }
693702
...@@ -754,7 +763,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -754,7 +763,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
754 /// The caller owns the returned memory. ArrayList becomes empty.763 /// The caller owns the returned memory. ArrayList becomes empty.
755 pub fn toOwnedSliceSentinel(self: *Self, allocator: Allocator, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {764 pub fn toOwnedSliceSentinel(self: *Self, allocator: Allocator, comptime sentinel: T) Allocator.Error!SentinelSlice(sentinel) {
756 // This addition can never overflow because `self.items` can never occupy the whole address space765 // 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);
758 self.appendReserved(sentinel);767 self.appendReserved(sentinel);
759 const result = try self.toOwnedSlice(allocator);768 const result = try self.toOwnedSlice(allocator);
760 return result[0 .. result.len - 1 :sentinel];769 return result[0 .. result.len - 1 :sentinel];
...@@ -954,7 +963,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -954,7 +963,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
954 /// memory as necessary.963 /// memory as necessary.
955 /// Invalidates element pointers if additional memory is needed.964 /// Invalidates element pointers if additional memory is needed.
956 pub fn appendSlice(self: *Self, allocator: Allocator, items: []const T) Allocator.Error!void {965 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);
958 self.appendSliceReserved(items);967 self.appendSliceReserved(items);
959 }968 }
960969
...@@ -976,7 +985,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -976,7 +985,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
976 /// be a compile error.985 /// be a compile error.
977 /// Invalidates element pointers if additional memory is needed.986 /// Invalidates element pointers if additional memory is needed.
978 pub fn appendUnalignedSlice(self: *Self, allocator: Allocator, items: []align(1) const T) Allocator.Error!void {987 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);
980 self.appendUnalignedSliceReserved(items);989 self.appendUnalignedSliceReserved(items);
981 }990 }
982991
...@@ -1049,6 +1058,9 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -1049,6 +1058,9 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
1049 @memset(self.items[old_len..self.items.len], value);1058 @memset(self.items[old_len..self.items.len], value);
1050 }1059 }
10511060
1061 /// Deprecated. To be removed after 0.14.0 is tagged.
1062 pub const appendNTimesAssumeCapacity = appendNTimesReserved;
1063
1052 /// Append a value to the list `n` times.1064 /// Append a value to the list `n` times.
1053 /// Never invalidates element pointers.1065 /// Never invalidates element pointers.
1054 /// The function is inline so that a comptime-known `value` parameter will1066 /// 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...@@ -1065,7 +1077,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
1065 /// Additional elements contain the value `undefined`.1077 /// Additional elements contain the value `undefined`.
1066 /// Invalidates element pointers if additional memory is needed.1078 /// Invalidates element pointers if additional memory is needed.
1067 pub fn resize(self: *Self, allocator: Allocator, new_len: usize) Allocator.Error!void {1079 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);
1069 self.items.len = new_len;1081 self.items.len = new_len;
1070 }1082 }
10711083
...@@ -1122,20 +1134,26 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -1122,20 +1134,26 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
1122 self.capacity = 0;1134 self.capacity = 0;
1123 }1135 }
11241136
1137 /// Deprecated. To be removed after 0.14.0 is tagged.
1138 pub const ensureTotalCapacity = reserveTotal;
1139
1125 /// If the current capacity is less than `new_capacity`, this function will1140 /// If the current capacity is less than `new_capacity`, this function will
1126 /// modify the array so that it can hold at least `new_capacity` items.1141 /// modify the array so that it can hold at least `new_capacity` items.
1127 /// Invalidates element pointers if additional memory is needed.1142 /// 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 {
1129 if (self.capacity >= new_capacity) return;1144 if (self.capacity >= new_capacity) return;
11301145
1131 const better_capacity = growCapacity(self.capacity, new_capacity);1146 const better_capacity = growCapacity(self.capacity, new_capacity);
1132 return self.ensureTotalCapacityPrecise(allocator, better_capacity);1147 return self.reserveTotalPrecise(allocator, better_capacity);
1133 }1148 }
11341149
1150 /// Deprecated. To be removed after 0.14.0 is tagged.
1151 pub const ensureTotalCapacityPrecise = reserveTotalPrecise;
1152
1135 /// If the current capacity is less than `new_capacity`, this function will1153 /// If the current capacity is less than `new_capacity`, this function will
1136 /// modify the array so that it can hold exactly `new_capacity` items.1154 /// modify the array so that it can hold exactly `new_capacity` items.
1137 /// Invalidates element pointers if additional memory is needed.1155 /// 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 {
1139 if (@sizeOf(T) == 0) {1157 if (@sizeOf(T) == 0) {
1140 self.capacity = math.maxInt(usize);1158 self.capacity = math.maxInt(usize);
1141 return;1159 return;
...@@ -1160,14 +1178,13 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -1160,14 +1178,13 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
1160 }1178 }
1161 }1179 }
11621180
1181 /// Deprecated. To be removed after 0.14.0 is tagged.
1182 pub const ensureUnusedCapacity = reserveUnused;
1183
1163 /// Modify the array so that it can hold at least `additional_count` **more** items.1184 /// Modify the array so that it can hold at least `additional_count` **more** items.
1164 /// Invalidates element pointers if additional memory is needed.1185 /// Invalidates element pointers if additional memory is needed.
1165 pub fn ensureUnusedCapacity(1186 pub fn reserveUnused(self: *Self, allocator: Allocator, additional_count: usize) Allocator.Error!void {
1166 self: *Self,1187 return self.reserveTotal(allocator, try addOrOom(self.items.len, additional_count));
1167 allocator: Allocator,
1168 additional_count: usize,
1169 ) Allocator.Error!void {
1170 return self.ensureTotalCapacity(allocator, try addOrOom(self.items.len, additional_count));
1171 }1188 }
11721189
1173 /// Increases the array's length to match the full capacity that is already allocated.1190 /// 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...@@ -1182,7 +1199,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
1182 pub fn addOne(self: *Self, allocator: Allocator) Allocator.Error!*T {1199 pub fn addOne(self: *Self, allocator: Allocator) Allocator.Error!*T {
1183 // This can never overflow because `self.items` can never occupy the whole address space1200 // This can never overflow because `self.items` can never occupy the whole address space
1184 const newlen = self.items.len + 1;1201 const newlen = self.items.len + 1;
1185 try self.ensureTotalCapacity(allocator, newlen);1202 try self.reserveTotal(allocator, newlen);
1186 return self.addOneReserved();1203 return self.addOneReserved();
1187 }1204 }
11881205
...@@ -2077,7 +2094,7 @@ test "addManyAsArray" {...@@ -2077,7 +2094,7 @@ test "addManyAsArray" {
2077 defer list.deinit();2094 defer list.deinit();
20782095
2079 (try list.addManyAsArray(4)).* = "aoeu".*;2096 (try list.addManyAsArray(4)).* = "aoeu".*;
2080 try list.ensureTotalCapacity(8);2097 try list.reserveTotal(8);
2081 list.addManyAsArrayReserved(4).* = "asdf".*;2098 list.addManyAsArrayReserved(4).* = "asdf".*;
20822099
2083 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");2100 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");
...@@ -2087,7 +2104,7 @@ test "addManyAsArray" {...@@ -2087,7 +2104,7 @@ test "addManyAsArray" {
2087 defer list.deinit(a);2104 defer list.deinit(a);
20882105
2089 (try list.addManyAsArray(a, 4)).* = "aoeu".*;2106 (try list.addManyAsArray(a, 4)).* = "aoeu".*;
2090 try list.ensureTotalCapacity(a, 8);2107 try list.reserveTotal(a, 8);
2091 list.addManyAsArrayReserved(4).* = "asdf".*;2108 list.addManyAsArrayReserved(4).* = "asdf".*;
20922109
2093 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");2110 try testing.expectEqualSlices(u8, list.items, "aoeuasdf");
...@@ -2304,7 +2321,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"...@@ -2304,7 +2321,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"
2304 try testing.expectError(error.OutOfMemory, list.addManyAsArray(a, 2));2321 try testing.expectError(error.OutOfMemory, list.addManyAsArray(a, 2));
2305 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(a, 2));2322 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(a, 2));
2306 try testing.expectError(error.OutOfMemory, list.insertSlice(a, 0, items));2323 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));
2308 }2325 }
23092326
2310 {2327 {
...@@ -2322,7 +2339,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"...@@ -2322,7 +2339,7 @@ test "return OutOfMemory when capacity would exceed maximum usize integer value"
2322 try testing.expectError(error.OutOfMemory, list.addManyAsArray(2));2339 try testing.expectError(error.OutOfMemory, list.addManyAsArray(2));
2323 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(2));2340 try testing.expectError(error.OutOfMemory, list.addManyAsSlice(2));
2324 try testing.expectError(error.OutOfMemory, list.insertSlice(0, items));2341 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));
2326 }2343 }
2327}2344}
23282345