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 {...@@ -116,6 +116,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
116116
117 /// Insert `item` at index `n` by moving `list[n .. list.len]` to make room.117 /// Insert `item` at index `n` by moving `list[n .. list.len]` to make room.
118 /// This operation is O(N).118 /// This operation is O(N).
119 /// Invalidates pointers if additional memory is needed.
119 pub fn insert(self: *Self, n: usize, item: T) Allocator.Error!void {120 pub fn insert(self: *Self, n: usize, item: T) Allocator.Error!void {
120 try self.ensureUnusedCapacity(1);121 try self.ensureUnusedCapacity(1);
121 self.items.len += 1;122 self.items.len += 1;
...@@ -126,6 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -126,6 +127,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
126127
127 /// Insert slice `items` at index `i` by moving `list[i .. list.len]` to make room.128 /// Insert slice `items` at index `i` by moving `list[i .. list.len]` to make room.
128 /// This operation is O(N).129 /// This operation is O(N).
130 /// Invalidates pointers if additional memory is needed.
129 pub fn insertSlice(self: *Self, i: usize, items: []const T) Allocator.Error!void {131 pub fn insertSlice(self: *Self, i: usize, items: []const T) Allocator.Error!void {
130 try self.ensureUnusedCapacity(items.len);132 try self.ensureUnusedCapacity(items.len);
131 self.items.len += items.len;133 self.items.len += items.len;
...@@ -163,6 +165,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -163,6 +165,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
163 }165 }
164166
165 /// Extend the list by 1 element. Allocates more memory as necessary.167 /// Extend the list by 1 element. Allocates more memory as necessary.
168 /// Invalidates pointers if additional memory is needed.
166 pub fn append(self: *Self, item: T) Allocator.Error!void {169 pub fn append(self: *Self, item: T) Allocator.Error!void {
167 const new_item_ptr = try self.addOne();170 const new_item_ptr = try self.addOne();
168 new_item_ptr.* = item;171 new_item_ptr.* = item;
...@@ -205,6 +208,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -205,6 +208,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
205208
206 /// Append the slice of items to the list. Allocates more209 /// Append the slice of items to the list. Allocates more
207 /// memory as necessary.210 /// memory as necessary.
211 /// Invalidates pointers if additional memory is needed.
208 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {212 pub fn appendSlice(self: *Self, items: []const T) Allocator.Error!void {
209 try self.ensureUnusedCapacity(items.len);213 try self.ensureUnusedCapacity(items.len);
210 self.appendSliceAssumeCapacity(items);214 self.appendSliceAssumeCapacity(items);
...@@ -223,6 +227,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -223,6 +227,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
223 /// Append an unaligned slice of items to the list. Allocates more227 /// Append an unaligned slice of items to the list. Allocates more
224 /// memory as necessary. Only call this function if calling228 /// memory as necessary. Only call this function if calling
225 /// `appendSlice` instead would be a compile error.229 /// `appendSlice` instead would be a compile error.
230 /// Invalidates pointers if additional memory is needed.
226 pub fn appendUnalignedSlice(self: *Self, items: []align(1) const T) Allocator.Error!void {231 pub fn appendUnalignedSlice(self: *Self, items: []align(1) const T) Allocator.Error!void {
227 try self.ensureUnusedCapacity(items.len);232 try self.ensureUnusedCapacity(items.len);
228 self.appendUnalignedSliceAssumeCapacity(items);233 self.appendUnalignedSliceAssumeCapacity(items);
...@@ -257,6 +262,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -257,6 +262,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
257262
258 /// Same as `append` except it returns the number of bytes written, which is always the same263 /// Same as `append` except it returns the number of bytes written, which is always the same
259 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.264 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.
265 /// Invalidates pointers if additional memory is needed.
260 fn appendWrite(self: *Self, m: []const u8) Allocator.Error!usize {266 fn appendWrite(self: *Self, m: []const u8) Allocator.Error!usize {
261 try self.appendSlice(m);267 try self.appendSlice(m);
262 return m.len;268 return m.len;
...@@ -264,6 +270,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -264,6 +270,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
264270
265 /// Append a value to the list `n` times.271 /// Append a value to the list `n` times.
266 /// Allocates more memory as necessary.272 /// Allocates more memory as necessary.
273 /// Invalidates pointers if additional memory is needed.
267 pub fn appendNTimes(self: *Self, value: T, n: usize) Allocator.Error!void {274 pub fn appendNTimes(self: *Self, value: T, n: usize) Allocator.Error!void {
268 const old_len = self.items.len;275 const old_len = self.items.len;
269 try self.resize(self.items.len + n);276 try self.resize(self.items.len + n);
...@@ -281,6 +288,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {...@@ -281,6 +288,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
281288
282 /// Adjust the list's length to `new_len`.289 /// Adjust the list's length to `new_len`.
283 /// Does not initialize added items if any.290 /// Does not initialize added items if any.
291 /// Invalidates pointers if additional memory is needed.
284 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {292 pub fn resize(self: *Self, new_len: usize) Allocator.Error!void {
285 try self.ensureTotalCapacity(new_len);293 try self.ensureTotalCapacity(new_len);
286 self.items.len = new_len;294 self.items.len = new_len;
...@@ -527,6 +535,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -527,6 +535,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
527 /// Insert `item` at index `n`. Moves `list[n .. list.len]`535 /// Insert `item` at index `n`. Moves `list[n .. list.len]`
528 /// to higher indices to make room.536 /// to higher indices to make room.
529 /// This operation is O(N).537 /// This operation is O(N).
538 /// Invalidates pointers if additional memory is needed.
530 pub fn insert(self: *Self, allocator: Allocator, n: usize, item: T) Allocator.Error!void {539 pub fn insert(self: *Self, allocator: Allocator, n: usize, item: T) Allocator.Error!void {
531 try self.ensureUnusedCapacity(allocator, 1);540 try self.ensureUnusedCapacity(allocator, 1);
532 self.items.len += 1;541 self.items.len += 1;
...@@ -538,6 +547,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -538,6 +547,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
538 /// Insert slice `items` at index `i`. Moves `list[i .. list.len]` to547 /// Insert slice `items` at index `i`. Moves `list[i .. list.len]` to
539 /// higher indicices make room.548 /// higher indicices make room.
540 /// This operation is O(N).549 /// This operation is O(N).
550 /// Invalidates pointers if additional memory is needed.
541 pub fn insertSlice(self: *Self, allocator: Allocator, i: usize, items: []const T) Allocator.Error!void {551 pub fn insertSlice(self: *Self, allocator: Allocator, i: usize, items: []const T) Allocator.Error!void {
542 try self.ensureUnusedCapacity(allocator, items.len);552 try self.ensureUnusedCapacity(allocator, items.len);
543 self.items.len += items.len;553 self.items.len += items.len;
...@@ -557,6 +567,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -557,6 +567,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
557 }567 }
558568
559 /// Extend the list by 1 element. Allocates more memory as necessary.569 /// Extend the list by 1 element. Allocates more memory as necessary.
570 /// Invalidates pointers if additional memory is needed.
560 pub fn append(self: *Self, allocator: Allocator, item: T) Allocator.Error!void {571 pub fn append(self: *Self, allocator: Allocator, item: T) Allocator.Error!void {
561 const new_item_ptr = try self.addOne(allocator);572 const new_item_ptr = try self.addOne(allocator);
562 new_item_ptr.* = item;573 new_item_ptr.* = item;
...@@ -598,6 +609,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -598,6 +609,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
598609
599 /// Append the slice of items to the list. Allocates more610 /// Append the slice of items to the list. Allocates more
600 /// memory as necessary.611 /// memory as necessary.
612 /// Invalidates pointers if additional memory is needed.
601 pub fn appendSlice(self: *Self, allocator: Allocator, items: []const T) Allocator.Error!void {613 pub fn appendSlice(self: *Self, allocator: Allocator, items: []const T) Allocator.Error!void {
602 try self.ensureUnusedCapacity(allocator, items.len);614 try self.ensureUnusedCapacity(allocator, items.len);
603 self.appendSliceAssumeCapacity(items);615 self.appendSliceAssumeCapacity(items);
...@@ -616,6 +628,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -616,6 +628,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
616 /// Append the slice of items to the list. Allocates more628 /// Append the slice of items to the list. Allocates more
617 /// memory as necessary. Only call this function if a call to `appendSlice` instead would629 /// memory as necessary. Only call this function if a call to `appendSlice` instead would
618 /// be a compile error.630 /// be a compile error.
631 /// Invalidates pointers if additional memory is needed.
619 pub fn appendUnalignedSlice(self: *Self, allocator: Allocator, items: []align(1) const T) Allocator.Error!void {632 pub fn appendUnalignedSlice(self: *Self, allocator: Allocator, items: []align(1) const T) Allocator.Error!void {
620 try self.ensureUnusedCapacity(allocator, items.len);633 try self.ensureUnusedCapacity(allocator, items.len);
621 self.appendUnalignedSliceAssumeCapacity(items);634 self.appendUnalignedSliceAssumeCapacity(items);
...@@ -654,6 +667,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -654,6 +667,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
654667
655 /// Same as `append` except it returns the number of bytes written, which is always the same668 /// Same as `append` except it returns the number of bytes written, which is always the same
656 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.669 /// as `m.len`. The purpose of this function existing is to match `std.io.Writer` API.
670 /// Invalidates pointers if additional memory is needed.
657 fn appendWrite(context: WriterContext, m: []const u8) Allocator.Error!usize {671 fn appendWrite(context: WriterContext, m: []const u8) Allocator.Error!usize {
658 try context.self.appendSlice(context.allocator, m);672 try context.self.appendSlice(context.allocator, m);
659 return m.len;673 return m.len;
...@@ -661,6 +675,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -661,6 +675,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
661675
662 /// Append a value to the list `n` times.676 /// Append a value to the list `n` times.
663 /// Allocates more memory as necessary.677 /// Allocates more memory as necessary.
678 /// Invalidates pointers if additional memory is needed.
664 pub fn appendNTimes(self: *Self, allocator: Allocator, value: T, n: usize) Allocator.Error!void {679 pub fn appendNTimes(self: *Self, allocator: Allocator, value: T, n: usize) Allocator.Error!void {
665 const old_len = self.items.len;680 const old_len = self.items.len;
666 try self.resize(allocator, self.items.len + n);681 try self.resize(allocator, self.items.len + n);
...@@ -679,6 +694,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ...@@ -679,6 +694,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
679694
680 /// Adjust the list's length to `new_len`.695 /// Adjust the list's length to `new_len`.
681 /// Does not initialize added items, if any.696 /// Does not initialize added items, if any.
697 /// Invalidates pointers if additional memory is needed.
682 pub fn resize(self: *Self, allocator: Allocator, new_len: usize) Allocator.Error!void {698 pub fn resize(self: *Self, allocator: Allocator, new_len: usize) Allocator.Error!void {
683 try self.ensureTotalCapacity(allocator, new_len);699 try self.ensureTotalCapacity(allocator, new_len);
684 self.items.len = new_len;700 self.items.len = new_len;