zig

commit 4dd3505e4329cf87a9ab5a7665ac2263fa2a4ec5 (tree)
parent 279607cae58f7be46335793df6a4a753d0a800aa
Author: Ryan Liptak <squeek502@hotmail.com>
Date:   Thu, 11 Jan 2024 16:09:32 -0800

std.ArrayList: Clarify that ensureTotalCapacity/ensureTotalCapacityPrecise will never shrink the array

Closes #18499

Diffstat:
M
lib/std/array_list.zig
 | 
16
++++++++--------

1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/lib/std/array_list.zig b/lib/std/array_list.zig
@@ -420,7 +420,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
             self.capacity = 0;
         }
 
-        /// Modify the array so that it can hold at least `new_capacity` items.
+        /// If the current capacity is less than `new_capacity`, this function will
+        /// modify the array so that it can hold at least `new_capacity` items.
         /// Invalidates pointers if additional memory is needed.
         pub fn ensureTotalCapacity(self: *Self, new_capacity: usize) Allocator.Error!void {
             if (@sizeOf(T) == 0) {
@@ -434,9 +435,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
             return self.ensureTotalCapacityPrecise(better_capacity);
         }
 
-        /// Modify the array so that it can hold `new_capacity` items.
-        /// Like `ensureTotalCapacity`, but the resulting capacity is guaranteed
-        /// to be equal to `new_capacity`.
+        /// If the current capacity is less than `new_capacity`, this function will
+        /// modify the array so that it can hold exactly `new_capacity` items.
         /// Invalidates pointers if additional memory is needed.
         pub fn ensureTotalCapacityPrecise(self: *Self, new_capacity: usize) Allocator.Error!void {
             if (@sizeOf(T) == 0) {
@@ -985,7 +985,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
             self.capacity = 0;
         }
 
-        /// Modify the array so that it can hold at least `new_capacity` items.
+        /// If the current capacity is less than `new_capacity`, this function will
+        /// modify the array so that it can hold at least `new_capacity` items.
         /// Invalidates pointers if additional memory is needed.
         pub fn ensureTotalCapacity(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
             if (self.capacity >= new_capacity) return;
@@ -994,9 +995,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
             return self.ensureTotalCapacityPrecise(allocator, better_capacity);
         }
 
-        /// Modify the array so that it can hold `new_capacity` items.
-        /// Like `ensureTotalCapacity`, but the resulting capacity is guaranteed
-        /// to be equal to `new_capacity`.
+        /// If the current capacity is less than `new_capacity`, this function will
+        /// modify the array so that it can hold exactly `new_capacity` items.
         /// Invalidates pointers if additional memory is needed.
         pub fn ensureTotalCapacityPrecise(self: *Self, allocator: Allocator, new_capacity: usize) Allocator.Error!void {
             if (@sizeOf(T) == 0) {