authorgravatar for remeh@remeh.frremeh <remeh@remeh.fr> 2022-10-31 18:19:55+01:00
committergravatar for git@vexu.euVeikka Tuominen <git@vexu.eu> 2022-11-18 14:49:31+02:00
loge7424d5d2ab4ac0a44c76dae15aaf35817a9743e
tree42dd0f9aa484ccae4a104cfab6e9edfb388fcfbf
parent3c0c0f899bfd9965e92dd1821b72150e9ec023ab

std.array_list: add a comment on every methods invalidating pointers.

While it is already mentioned on the `items` attributes of the structs, it is interesting to comment in every method potentially invalidating pointers to items that they may do so.

1 files changed, 16 insertions(+), 0 deletions(-)

lib/std/array_list.zig+16
......@@ -116,6 +116,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
116116
117117 /// Insert `item` at index `n` by moving `list[n .. list.len]` to make room.
118118 /// This operation is O(N).
119 /// Invalidates pointers if additional memory is needed.
119120 pub fn insert(self: *Self, n: usize, item: T) Allocator.Error!void {
120121 try self.ensureUnusedCapacity(1);
121122 self.items.len += 1;
......@@ -126,6 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
126127
127128 /// Insert slice `items` at index `i` by moving `list[i .. list.len]` to make room.
128129 /// This operation is O(N).
130 /// Invalidates pointers if additional memory is needed.
129131 pub fn insertSlice(self: *Self, i: usize, items: []const T) Allocator.Error!void {
130132 try self.ensureUnusedCapacity(items.len);
131133 self.items.len += items.len;
......@@ -163,6 +165,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
163165 }
164166
165167 /// Extend the list by 1 element. Allocates more memory as necessary.
168 /// Invalidates pointers if additional memory is needed.
166169 pub fn append(self: *Self, item: T) Allocator.Error!void {
167170 const new_item_ptr = try self.addOne();
168171 new_item_ptr.* = item;
......@@ -205,6 +208,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
205208
206209 /// Append the slice of items to the list. Allocates more
207210 /// memory as necessary.
211 /// Invalidates pointers if additional memory is needed.
208212 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {
209213 try self.ensureUnusedCapacity(items.len);
210214 self.appendSliceAssumeCapacity(items);
......@@ -223,6 +227,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
223227 /// Append an unaligned slice of items to the list. Allocates more
224228 /// memory as necessary. Only call this function if calling
225229 /// `appendSlice` instead would be a compile error.
230 /// Invalidates pointers if additional memory is needed.
226231 pub fn appendUnalignedSlice(self: *Self, items: []align(1) const T) Allocator.Error!void {
227232 try self.ensureUnusedCapacity(items.len);
228233 self.appendUnalignedSliceAssumeCapacity(items);
......@@ -257,6 +262,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
257262
258263 /// Same as `append` except it returns the number of bytes written, which is always the same
259264 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.
265 /// Invalidates pointers if additional memory is needed.
260266 fn appendWrite(self: *Self, m: []const u8) Allocator.Error!usize {
261267 try self.appendSlice(m);
262268 return m.len;
......@@ -264,6 +270,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
264270
265271 /// Append a value to the list `n` times.
266272 /// Allocates more memory as necessary.
273 /// Invalidates pointers if additional memory is needed.
267274 pub fn appendNTimes(self: *Self, value: T, n: usize) Allocator.Error!void {
268275 const old_len = self.items.len;
269276 try self.resize(self.items.len + n);
......@@ -281,6 +288,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
281288
282289 /// Adjust the list's length to `new_len`.
283290 /// Does not initialize added items if any.
291 /// Invalidates pointers if additional memory is needed.
284292 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {
285293 try self.ensureTotalCapacity(new_len);
286294 self.items.len = new_len;
......@@ -527,6 +535,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
527535 /// Insert `item` at index `n`. Moves `list[n .. list.len]`
528536 /// to higher indices to make room.
529537 /// This operation is O(N).
538 /// Invalidates pointers if additional memory is needed.
530539 pub fn insert(self: *Self, allocator: Allocator, n: usize, item: T) Allocator.Error!void {
531540 try self.ensureUnusedCapacity(allocator, 1);
532541 self.items.len += 1;
......@@ -538,6 +547,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
538547 /// Insert slice `items` at index `i`. Moves `list[i .. list.len]` to
539548 /// higher indicices make room.
540549 /// This operation is O(N).
550 /// Invalidates pointers if additional memory is needed.
541551 pub fn insertSlice(self: *Self, allocator: Allocator, i: usize, items: []const T) Allocator.Error!void {
542552 try self.ensureUnusedCapacity(allocator, items.len);
543553 self.items.len += items.len;
......@@ -557,6 +567,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
557567 }
558568
559569 /// Extend the list by 1 element. Allocates more memory as necessary.
570 /// Invalidates pointers if additional memory is needed.
560571 pub fn append(self: *Self, allocator: Allocator, item: T) Allocator.Error!void {
561572 const new_item_ptr = try self.addOne(allocator);
562573 new_item_ptr.* = item;
......@@ -598,6 +609,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
598609
599610 /// Append the slice of items to the list. Allocates more
600611 /// memory as necessary.
612 /// Invalidates pointers if additional memory is needed.
601613 pub fn appendSlice(self: *Self, allocator: Allocator, items: []const T) Allocator.Error!void {
602614 try self.ensureUnusedCapacity(allocator, items.len);
603615 self.appendSliceAssumeCapacity(items);
......@@ -616,6 +628,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
616628 /// Append the slice of items to the list. Allocates more
617629 /// memory as necessary. Only call this function if a call to `appendSlice` instead would
618630 /// be a compile error.
631 /// Invalidates pointers if additional memory is needed.
619632 pub fn appendUnalignedSlice(self: *Self, allocator: Allocator, items: []align(1) const T) Allocator.Error!void {
620633 try self.ensureUnusedCapacity(allocator, items.len);
621634 self.appendUnalignedSliceAssumeCapacity(items);
......@@ -654,6 +667,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
654667
655668 /// Same as `append` except it returns the number of bytes written, which is always the same
656669 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.
670 /// Invalidates pointers if additional memory is needed.
657671 fn appendWrite(context: WriterContext, m: []const u8) Allocator.Error!usize {
658672 try context.self.appendSlice(context.allocator, m);
659673 return m.len;
......@@ -661,6 +675,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
661675
662676 /// Append a value to the list `n` times.
663677 /// Allocates more memory as necessary.
678 /// Invalidates pointers if additional memory is needed.
664679 pub fn appendNTimes(self: *Self, allocator: Allocator, value: T, n: usize) Allocator.Error!void {
665680 const old_len = self.items.len;
666681 try self.resize(allocator, self.items.len + n);
......@@ -679,6 +694,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
679694
680695 /// Adjust the list's length to `new_len`.
681696 /// Does not initialize added items, if any.
697 /// Invalidates pointers if additional memory is needed.
682698 pub fn resize(self: *Self, allocator: Allocator, new_len: usize) Allocator.Error!void {
683699 try self.ensureTotalCapacity(allocator, new_len);
684700 self.items.len = new_len;