authorgravatar for camconn@users.noreply.github.comCameron Conn <camconn@users.noreply.github.com> 2021-01-02 18:06:51-06:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2021-01-02 19:06:51-05:00
logdb1e97d4b19d8399252e0fbc85fc3563b005a892
tree065247f953f6ea6f8926bc555d63d9472967cb4a
parent1856dfea6b797d852b496c2111dbb326dbe2957e
signaturebadge-question-mark Signed by PGP key 4AEE18F83AFDEB23

Improve documentation for ArrayList, ArrayListUnmanaged, etc. (#7624)

* Improve ArrayList & co documentation - Added doc comments about the validity of references to elements in an ArrayList and how they may become invalid after resizing operations. - This should help users avoid footguns in future. * Improve ArrayListUnmanaged & co's documentation - Port improved documentation from ArrayList and ArrayList aligned to their unmanaged counterparts. - Made documentation for ArrayListUnmanaged & co more inclusive and up-to-date. - Made documentation more consistent with `ArrayList`. * Corrections on ArrayList documentation. - Remove incorrect/unpreferred wording on ArrayList vs ArrayListUnmanaged. - Fix notes about the alignment of ArrayListAligned - Be more verbose with warnings on when pointers are invalidated. - Copy+paste a few warnings * add warning to replaceRange * revert changes to append documentation

1 files changed, 100 insertions(+), 42 deletions(-)

lib/std/array_list.zig+100-42
......@@ -12,10 +12,20 @@ const Allocator = mem.Allocator;
1212
1313/// A contiguous, growable list of items in memory.
1414/// This is a wrapper around an array of T values. Initialize with `init`.
15///
16/// This struct internally stores a `std.mem.Allocator` for memory management.
17/// To manually specify an allocator with each method call see `ArrayListUnmanaged`.
1518pub fn ArrayList(comptime T: type) type {
1619 return ArrayListAligned(T, null);
1720}
1821
22/// A contiguous, growable list of arbitrarily aligned items in memory.
23/// This is a wrapper around an array of T values aligned to `alignment`-byte
24/// addresses. If the specified alignment is `null`, then `@alignOf(T)` is used.
25/// Initialize with `init`.
26///
27/// This struct internally stores a `std.mem.Allocator` for memory management.
28/// To manually specify an allocator with each method call see `ArrayListAlignedUnmanaged`.
1929pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
2030 if (alignment) |a| {
2131 if (a == @alignOf(T)) {
......@@ -24,9 +34,18 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
2434 }
2535 return struct {
2636 const Self = @This();
27
28 /// Content of the ArrayList
37 /// Contents of the list. Pointers to elements in this slice are
38 /// **invalid after resizing operations** on the ArrayList, unless the
39 /// operation explicitly either: (1) states otherwise or (2) lists the
40 /// invalidated pointers.
41 ///
42 /// The allocator used determines how element pointers are
43 /// invalidated, so the behavior may vary between lists. To avoid
44 /// illegal behavior, take into account the above paragraph plus the
45 /// explicit statements given in each method.
2946 items: Slice,
47 /// How many T values this list can hold without allocating
48 /// additional memory.
3049 capacity: usize,
3150 allocator: *Allocator,
3251
......@@ -42,7 +61,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
4261 };
4362 }
4463
45 /// Initialize with capacity to hold at least num elements.
64 /// Initialize with capacity to hold at least `num` elements.
4665 /// Deinitialize with `deinit` or use `toOwnedSlice`.
4766 pub fn initCapacity(allocator: *Allocator, num: usize) !Self {
4867 var self = Self.init(allocator);
......@@ -79,11 +98,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
7998 };
8099 }
81100
101 /// Initializes an ArrayListUnmanaged with the `items` and `capacity` fields
102 /// of this ArrayList. This ArrayList retains ownership of underlying memory.
82103 pub fn toUnmanaged(self: Self) ArrayListAlignedUnmanaged(T, alignment) {
83104 return .{ .items = self.items, .capacity = self.capacity };
84105 }
85106
86 /// The caller owns the returned memory. ArrayList becomes empty.
107 /// The caller owns the returned memory. Empties this ArrayList.
87108 pub fn toOwnedSlice(self: *Self) Slice {
88109 const allocator = self.allocator;
89110 const result = allocator.shrink(self.allocatedSlice(), self.items.len);
......@@ -91,7 +112,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
91112 return result;
92113 }
93114
94 /// The caller owns the returned memory. ArrayList becomes empty.
115 /// The caller owns the returned memory. Empties this ArrayList.
95116 pub fn toOwnedSliceSentinel(self: *Self, comptime sentinel: T) ![:sentinel]T {
96117 try self.append(sentinel);
97118 const result = self.toOwnedSlice();
......@@ -118,9 +139,10 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
118139 mem.copy(T, self.items[i .. i + items.len], items);
119140 }
120141
121 /// Replace range of elements `list[start..start+len]` with `new_items`
122 /// grows list if `len < new_items.len`. may allocate
123 /// shrinks list if `len > new_items.len`
142 /// Replace range of elements `list[start..start+len]` with `new_items`.
143 /// Grows list if `len < new_items.len`.
144 /// Shrinks list if `len > new_items.len`.
145 /// Invalidates pointers if this ArrayList is resized.
124146 pub fn replaceRange(self: *Self, start: usize, len: usize, new_items: SliceConst) !void {
125147 const after_range = start + len;
126148 const range = self.items[start..after_range];
......@@ -151,15 +173,18 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
151173 new_item_ptr.* = item;
152174 }
153175
154 /// Extend the list by 1 element, but asserting `self.capacity`
155 /// is sufficient to hold an additional item.
176 /// Extend the list by 1 element, but assert `self.capacity`
177 /// is sufficient to hold an additional item. **Does not**
178 /// invalidate pointers.
156179 pub fn appendAssumeCapacity(self: *Self, item: T) void {
157180 const new_item_ptr = self.addOneAssumeCapacity();
158181 new_item_ptr.* = item;
159182 }
160183
161 /// Remove the element at index `i` from the list and return its value.
184 /// Remove the element at index `i`, shift elements after index
185 /// `i` forward, and return the removed element.
162186 /// Asserts the array has at least one item.
187 /// Invalidates pointers to end of list.
163188 /// This operation is O(N).
164189 pub fn orderedRemove(self: *Self, i: usize) T {
165190 const newlen = self.items.len - 1;
......@@ -191,7 +216,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
191216 }
192217
193218 /// Append the slice of items to the list, asserting the capacity is already
194 /// enough to store the new items.
219 /// enough to store the new items. **Does not** invalidate pointers.
195220 pub fn appendSliceAssumeCapacity(self: *Self, items: SliceConst) void {
196221 const oldlen = self.items.len;
197222 const newlen = self.items.len + items.len;
......@@ -227,7 +252,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
227252 }
228253
229254 /// Append a value to the list `n` times.
230 /// Asserts the capacity is enough.
255 /// Asserts the capacity is enough. **Does not** invalidate pointers.
231256 pub fn appendNTimesAssumeCapacity(self: *Self, value: T, n: usize) void {
232257 const new_len = self.items.len + n;
233258 assert(new_len <= self.capacity);
......@@ -243,7 +268,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
243268 }
244269
245270 /// Reduce allocated capacity to `new_len`.
246 /// Invalidates element pointers.
271 /// May invalidate element pointers.
247272 pub fn shrink(self: *Self, new_len: usize) void {
248273 assert(new_len <= self.items.len);
249274
......@@ -257,13 +282,14 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
257282 }
258283
259284 /// Reduce length to `new_len`.
260 /// Invalidates element pointers.
261 /// Keeps capacity the same.
285 /// Invalidates pointers for the elements `items[new_len..]`.
262286 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
263287 assert(new_len <= self.items.len);
264288 self.items.len = new_len;
265289 }
266290
291 /// Modify the array so that it can hold at least `new_capacity` items.
292 /// Invalidates pointers if additional memory is needed.
267293 pub fn ensureCapacity(self: *Self, new_capacity: usize) !void {
268294 var better_capacity = self.capacity;
269295 if (better_capacity >= new_capacity) return;
......@@ -280,14 +306,13 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
280306 }
281307
282308 /// Increases the array's length to match the full capacity that is already allocated.
283 /// The new elements have `undefined` values. This operation does not invalidate any
284 /// element pointers.
309 /// The new elements have `undefined` values. **Does not** invalidate pointers.
285310 pub fn expandToCapacity(self: *Self) void {
286311 self.items.len = self.capacity;
287312 }
288313
289314 /// Increase length by 1, returning pointer to the new item.
290 /// The returned pointer becomes invalid when the list is resized.
315 /// The returned pointer becomes invalid when the list resized.
291316 pub fn addOne(self: *Self) !*T {
292317 const newlen = self.items.len + 1;
293318 try self.ensureCapacity(newlen);
......@@ -297,6 +322,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
297322 /// Increase length by 1, returning pointer to the new item.
298323 /// Asserts that there is already space for the new item without allocating more.
299324 /// The returned pointer becomes invalid when the list is resized.
325 /// **Does not** invalidate element pointers.
300326 pub fn addOneAssumeCapacity(self: *Self) *T {
301327 assert(self.items.len < self.capacity);
302328
......@@ -306,6 +332,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
306332
307333 /// Resize the array, adding `n` new elements, which have `undefined` values.
308334 /// The return value is an array pointing to the newly allocated elements.
335 /// The returned pointer becomes invalid when the list is resized.
336 /// Resizes list if `self.capacity` is not large enough.
309337 pub fn addManyAsArray(self: *Self, comptime n: usize) !*[n]T {
310338 const prev_len = self.items.len;
311339 try self.resize(self.items.len + n);
......@@ -315,6 +343,8 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
315343 /// Resize the array, adding `n` new elements, which have `undefined` values.
316344 /// The return value is an array pointing to the newly allocated elements.
317345 /// Asserts that there is already space for the new item without allocating more.
346 /// **Does not** invalidate element pointers.
347 /// The returned pointer becomes invalid when the list is resized.
318348 pub fn addManyAsArrayAssumeCapacity(self: *Self, comptime n: usize) *[n]T {
319349 assert(self.items.len + n <= self.capacity);
320350 const prev_len = self.items.len;
......@@ -324,21 +354,23 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
324354
325355 /// Remove and return the last element from the list.
326356 /// Asserts the list has at least one item.
357 /// Invalidates pointers to the removed element.
327358 pub fn pop(self: *Self) T {
328359 const val = self.items[self.items.len - 1];
329360 self.items.len -= 1;
330361 return val;
331362 }
332363
333 /// Remove and return the last element from the list.
334 /// If the list is empty, returns `null`.
364 /// Remove and return the last element from the list, or
365 /// return `null` if list is empty.
366 /// Invalidates pointers to the removed element, if any.
335367 pub fn popOrNull(self: *Self) ?T {
336368 if (self.items.len == 0) return null;
337369 return self.pop();
338370 }
339371
340372 /// Returns a slice of all the items plus the extra capacity, whose memory
341 /// contents are undefined.
373 /// contents are `undefined`.
342374 pub fn allocatedSlice(self: Self) Slice {
343375 // For a nicer API, `items.len` is the length, not the capacity.
344376 // This requires "unsafe" slicing.
......@@ -346,7 +378,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
346378 }
347379
348380 /// Returns a slice of only the extra capacity after items.
349 /// This can be useful for writing directly into an `ArrayList`.
381 /// This can be useful for writing directly into an ArrayList.
350382 /// Note that such an operation must be followed up with a direct
351383 /// modification of `self.items.len`.
352384 pub fn unusedCapacitySlice(self: Self) Slice {
......@@ -355,12 +387,18 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
355387 };
356388}
357389
358/// Bring-your-own allocator with every function call.
359/// Initialize directly and deinitialize with `deinit` or use `toOwnedSlice`.
390/// An ArrayList, but the allocator is passed as a parameter to the relevant functions
391/// rather than stored in the struct itself. The same allocator **must** be used throughout
392/// the entire lifetime of an ArrayListUnmanaged. Initialize directly or with
393/// `initCapacity`, and deinitialize with `deinit` or use `toOwnedSlice`.
360394pub fn ArrayListUnmanaged(comptime T: type) type {
361395 return ArrayListAlignedUnmanaged(T, null);
362396}
363397
398/// An ArrayListAligned, but the allocator is passed as a parameter to the relevant
399/// functions rather than stored in the struct itself. The same allocator **must**
400/// be used throughout the entire lifetime of an ArrayListAlignedUnmanaged.
401/// Initialize directly or with `initCapacity`, and deinitialize with `deinit` or use `toOwnedSlice`.
364402pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) type {
365403 if (alignment) |a| {
366404 if (a == @alignOf(T)) {
......@@ -369,9 +407,18 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
369407 }
370408 return struct {
371409 const Self = @This();
372
373 /// Content of the ArrayList.
410 /// Contents of the list. Pointers to elements in this slice are
411 /// **invalid after resizing operations** on the ArrayList, unless the
412 /// operation explicitly either: (1) states otherwise or (2) lists the
413 /// invalidated pointers.
414 ///
415 /// The allocator used determines how element pointers are
416 /// invalidated, so the behavior may vary between lists. To avoid
417 /// illegal behavior, take into account the above paragraph plus the
418 /// explicit statements given in each method.
374419 items: Slice = &[_]T{},
420 /// How many T values this list can hold without allocating
421 /// additional memory.
375422 capacity: usize = 0,
376423
377424 pub const Slice = if (alignment) |a| ([]align(a) T) else []T;
......@@ -395,6 +442,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
395442 self.* = undefined;
396443 }
397444
445 /// Convert this list into an analogous memory-managed one.
446 /// The returned list has ownership of the underlying memory.
398447 pub fn toManaged(self: *Self, allocator: *Allocator) ArrayListAligned(T, alignment) {
399448 return .{ .items = self.items, .capacity = self.capacity, .allocator = allocator };
400449 }
......@@ -414,7 +463,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
414463 }
415464
416465 /// Insert `item` at index `n`. Moves `list[n .. list.len]`
417 /// to make room.
466 /// to higher indices to make room.
467 /// This operation is O(N).
418468 pub fn insert(self: *Self, allocator: *Allocator, n: usize, item: T) !void {
419469 try self.ensureCapacity(allocator, self.items.len + 1);
420470 self.items.len += 1;
......@@ -423,8 +473,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
423473 self.items[n] = item;
424474 }
425475
426 /// Insert slice `items` at index `i`. Moves
427 /// `list[i .. list.len]` to make room.
476 /// Insert slice `items` at index `i`. Moves `list[i .. list.len]` to
477 /// higher indicices make room.
428478 /// This operation is O(N).
429479 pub fn insertSlice(self: *Self, allocator: *Allocator, i: usize, items: SliceConst) !void {
430480 try self.ensureCapacity(allocator, self.items.len + items.len);
......@@ -435,8 +485,9 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
435485 }
436486
437487 /// Replace range of elements `list[start..start+len]` with `new_items`
438 /// grows list if `len < new_items.len`. may allocate
439 /// shrinks list if `len > new_items.len`
488 /// Grows list if `len < new_items.len`.
489 /// Shrinks list if `len > new_items.len`
490 /// Invalidates pointers if this ArrayList is resized.
440491 pub fn replaceRange(self: *Self, allocator: *Allocator, start: usize, len: usize, new_items: SliceConst) !void {
441492 var managed = self.toManaged(allocator);
442493 try managed.replaceRange(start, len, new_items);
......@@ -457,7 +508,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
457508 }
458509
459510 /// Remove the element at index `i` from the list and return its value.
460 /// Asserts the array has at least one item.
511 /// Asserts the array has at least one item. Invalidates pointers to
512 /// last element.
461513 /// This operation is O(N).
462514 pub fn orderedRemove(self: *Self, i: usize) T {
463515 const newlen = self.items.len - 1;
......@@ -472,6 +524,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
472524
473525 /// Removes the element at the specified index and returns it.
474526 /// The empty slot is filled from the end of the list.
527 /// Invalidates pointers to last element.
475528 /// This operation is O(1).
476529 pub fn swapRemove(self: *Self, i: usize) T {
477530 if (self.items.len - 1 == i) return self.pop();
......@@ -515,6 +568,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
515568 }
516569
517570 /// Append a value to the list `n` times.
571 /// **Does not** invalidate pointers.
518572 /// Asserts the capacity is enough.
519573 pub fn appendNTimesAssumeCapacity(self: *Self, value: T, n: usize) void {
520574 const new_len = self.items.len + n;
......@@ -524,14 +578,13 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
524578 }
525579
526580 /// Adjust the list's length to `new_len`.
527 /// Does not initialize added items if any.
581 /// Does not initialize added items, if any.
528582 pub fn resize(self: *Self, allocator: *Allocator, new_len: usize) !void {
529583 try self.ensureCapacity(allocator, new_len);
530584 self.items.len = new_len;
531585 }
532586
533587 /// Reduce allocated capacity to `new_len`.
534 /// Invalidates element pointers.
535588 pub fn shrink(self: *Self, allocator: *Allocator, new_len: usize) void {
536589 assert(new_len <= self.items.len);
537590
......@@ -545,13 +598,15 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
545598 }
546599
547600 /// Reduce length to `new_len`.
548 /// Invalidates element pointers.
601 /// Invalidates pointers to elements `items[new_len..]`.
549602 /// Keeps capacity the same.
550603 pub fn shrinkRetainingCapacity(self: *Self, new_len: usize) void {
551604 assert(new_len <= self.items.len);
552605 self.items.len = new_len;
553606 }
554607
608 /// Modify the array so that it can hold at least `new_capacity` items.
609 /// Invalidates pointers if additional memory is needed.
555610 pub fn ensureCapacity(self: *Self, allocator: *Allocator, new_capacity: usize) !void {
556611 var better_capacity = self.capacity;
557612 if (better_capacity >= new_capacity) return;
......@@ -568,13 +623,13 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
568623
569624 /// Increases the array's length to match the full capacity that is already allocated.
570625 /// The new elements have `undefined` values.
571 /// This operation does not invalidate any element pointers.
626 /// **Does not** invalidate pointers.
572627 pub fn expandToCapacity(self: *Self) void {
573628 self.items.len = self.capacity;
574629 }
575630
576631 /// Increase length by 1, returning pointer to the new item.
577 /// The returned pointer becomes invalid when the list is resized.
632 /// The returned pointer becomes invalid when the list resized.
578633 pub fn addOne(self: *Self, allocator: *Allocator) !*T {
579634 const newlen = self.items.len + 1;
580635 try self.ensureCapacity(allocator, newlen);
......@@ -583,8 +638,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
583638
584639 /// Increase length by 1, returning pointer to the new item.
585640 /// Asserts that there is already space for the new item without allocating more.
586 /// The returned pointer becomes invalid when the list is resized.
587 /// This operation does not invalidate any element pointers.
641 /// **Does not** invalidate pointers.
642 /// The returned pointer becomes invalid when the list resized.
588643 pub fn addOneAssumeCapacity(self: *Self) *T {
589644 assert(self.items.len < self.capacity);
590645
......@@ -594,6 +649,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
594649
595650 /// Resize the array, adding `n` new elements, which have `undefined` values.
596651 /// The return value is an array pointing to the newly allocated elements.
652 /// The returned pointer becomes invalid when the list is resized.
597653 pub fn addManyAsArray(self: *Self, allocator: *Allocator, comptime n: usize) !*[n]T {
598654 const prev_len = self.items.len;
599655 try self.resize(allocator, self.items.len + n);
......@@ -603,6 +659,8 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
603659 /// Resize the array, adding `n` new elements, which have `undefined` values.
604660 /// The return value is an array pointing to the newly allocated elements.
605661 /// Asserts that there is already space for the new item without allocating more.
662 /// **Does not** invalidate pointers.
663 /// The returned pointer becomes invalid when the list is resized.
606664 pub fn addManyAsArrayAssumeCapacity(self: *Self, comptime n: usize) *[n]T {
607665 assert(self.items.len + n <= self.capacity);
608666 const prev_len = self.items.len;
......@@ -612,7 +670,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
612670
613671 /// Remove and return the last element from the list.
614672 /// Asserts the list has at least one item.
615 /// This operation does not invalidate any element pointers.
673 /// Invalidates pointers to last element.
616674 pub fn pop(self: *Self) T {
617675 const val = self.items[self.items.len - 1];
618676 self.items.len -= 1;
......@@ -621,7 +679,7 @@ pub fn ArrayListAlignedUnmanaged(comptime T: type, comptime alignment: ?u29) typ
621679
622680 /// Remove and return the last element from the list.
623681 /// If the list is empty, returns `null`.
624 /// This operation does not invalidate any element pointers.
682 /// Invalidates pointers to last element.
625683 pub fn popOrNull(self: *Self) ?T {
626684 if (self.items.len == 0) return null;
627685 return self.pop();