Commit db1e97d4b19d8399252e0fbc85fc3563b005a892 | zig

author	Cameron Conn <camconn@users.noreply.github.com> 2021-01-02 18:06:51-06:00
committer	GitHub <noreply@github.com> 2021-01-02 19:06:51-05:00
log	db1e97d4b19d8399252e0fbc85fc3563b005a892
tree	065247f953f6ea6f8926bc555d63d9472967cb4a
parent	1856dfea6b797d852b496c2111dbb326dbe2957e
signature	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

lib/std/array_list.zig+100-42

...	@@ -12,10 +12,20 @@ const Allocator = mem.Allocator;	...	@@ -12,10 +12,20 @@ const Allocator = mem.Allocator;
12		12
13	/// A contiguous, growable list of items in memory.	13	/// A contiguous, growable list of items in memory.
14	/// This is a wrapper around an array of T values. Initialize with `init`.	14	/// 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`.
15	pub fn ArrayList(comptime T: type) type {	18	pub fn ArrayList(comptime T: type) type {
16	return ArrayListAligned(T, null);	19	return ArrayListAligned(T, null);
17	}	20	}
18		21
		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`.
19	pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {	29	pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
20	if (alignment) \|a\| {	30	if (alignment) \|a\| {
21	if (a == @alignOf(T)) {	31	if (a == @alignOf(T)) {
...	@@ -24,9 +34,18 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {	...	@@ -24,9 +34,18 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type {
24	}	34	}
25	return struct {	35	return struct {
26	const Self = @This();	36	const Self = @This();
27		37	/// Contents of the list. Pointers to elements in this slice are
28	/// Content of the ArrayList	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.
29	items: Slice,	46	items: Slice,
		47	/// How many T values this list can hold without allocating
		48	/// additional memory.
30	capacity: usize,	49	capacity: usize,
31	allocator: *Allocator,	50	allocator: *Allocator,
32		51