authorgravatar for nathan@nmichaels.orgNathan Michaels <nathan@nmichaels.org> 2019-10-28 03:57:23-04:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-10-28 03:57:23-04:00
log6fdeaac338f3a4a1f3455653ce29bf6ce4bbe335
tree97f799cf30331a81e8fe5b2a6fe9ac5bb7de8542
parent8af6c7e34ceebde898d32bb50aaee5faac538af2

Add some documentation for standard library things. (#3540)

* Add some documentation for standard library things. Added a bunch of descriptions for array_list. Added some usage notes for failing_allocator. Documented some of mem.Allocator.

3 files changed, 59 insertions(+), 0 deletions(-)

lib/std/array_list.zig+33
......@@ -5,6 +5,10 @@ const testing = std.testing;
55const mem = std.mem;
66const Allocator = mem.Allocator;
77
8/// List of items.
9///
10/// This is a wrapper around an array of T values. Initialize with
11/// `init`.
812pub fn ArrayList(comptime T: type) type {
913 return AlignedArrayList(T, null);
1014}
......@@ -37,18 +41,24 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
3741 };
3842 }
3943
44 /// Release all allocated memory.
4045 pub fn deinit(self: Self) void {
4146 self.allocator.free(self.items);
4247 }
4348
49 /// Return contents as a slice. Only valid while the list
50 /// doesn't change size.
4451 pub fn toSlice(self: Self) Slice {
4552 return self.items[0..self.len];
4653 }
4754
55 /// Return list as const slice. Only valid while the list
56 /// doesn't change size.
4857 pub fn toSliceConst(self: Self) SliceConst {
4958 return self.items[0..self.len];
5059 }
5160
61 /// Safely access index i of the list.
5262 pub fn at(self: Self, i: usize) T {
5363 return self.toSliceConst()[i];
5464 }
......@@ -66,10 +76,13 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
6676 self.items[i] = item;
6777 }
6878
79 /// Return length of the list.
6980 pub fn count(self: Self) usize {
7081 return self.len;
7182 }
7283
84 /// Return the maximum number of items the list can hold
85 /// without allocating more memory.
7386 pub fn capacity(self: Self) usize {
7487 return self.items.len;
7588 }
......@@ -93,6 +106,8 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
93106 return result;
94107 }
95108
109 /// Insert `item` at index `n`. Moves `list[n .. list.count()]`
110 /// to make room.
96111 pub fn insert(self: *Self, n: usize, item: T) !void {
97112 try self.ensureCapacity(self.len + 1);
98113 self.len += 1;
......@@ -101,6 +116,8 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
101116 self.items[n] = item;
102117 }
103118
119 /// Insert slice `items` at index `n`. Moves
120 /// `list[n .. list.count()]` to make room.
104121 pub fn insertSlice(self: *Self, n: usize, items: SliceConst) !void {
105122 try self.ensureCapacity(self.len + items.len);
106123 self.len += items.len;
......@@ -109,16 +126,22 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
109126 mem.copy(T, self.items[n .. n + items.len], items);
110127 }
111128
129 /// Extend the list by 1 element. Allocates more memory as
130 /// necessary.
112131 pub fn append(self: *Self, item: T) !void {
113132 const new_item_ptr = try self.addOne();
114133 new_item_ptr.* = item;
115134 }
116135
136 /// Extend the list by 1 element, but asserting `self.capacity`
137 /// is sufficient to hold an additional item.
117138 pub fn appendAssumeCapacity(self: *Self, item: T) void {
118139 const new_item_ptr = self.addOneAssumeCapacity();
119140 new_item_ptr.* = item;
120141 }
121142
143 /// Remove the element at index `i` from the list and return
144 /// its value. Asserts the array has at least one item.
122145 pub fn orderedRemove(self: *Self, i: usize) T {
123146 const newlen = self.len - 1;
124147 if (newlen == i) return self.pop();
......@@ -149,17 +172,22 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
149172 return self.swapRemove(i);
150173 }
151174
175 /// Append the slice of items to the list. Allocates more
176 /// memory as necessary.
152177 pub fn appendSlice(self: *Self, items: SliceConst) !void {
153178 try self.ensureCapacity(self.len + items.len);
154179 mem.copy(T, self.items[self.len..], items);
155180 self.len += items.len;
156181 }
157182
183 /// Adjust the list's length to `new_len`. Doesn't initialize
184 /// added items if any.
158185 pub fn resize(self: *Self, new_len: usize) !void {
159186 try self.ensureCapacity(new_len);
160187 self.len = new_len;
161188 }
162189
190 /// Reduce allocated capacity to `new_len`.
163191 pub fn shrink(self: *Self, new_len: usize) void {
164192 assert(new_len <= self.len);
165193 self.len = new_len;
......@@ -178,6 +206,7 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
178206 self.items = try self.allocator.realloc(self.items, better_capacity);
179207 }
180208
209 /// Increase length by 1, returning pointer to the new item.
181210 pub fn addOne(self: *Self) !*T {
182211 const new_length = self.len + 1;
183212 try self.ensureCapacity(new_length);
......@@ -191,11 +220,14 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
191220 return result;
192221 }
193222
223 /// Remove and return the last element from the list. Asserts
224 /// the list has at least one item.
194225 pub fn pop(self: *Self) T {
195226 self.len -= 1;
196227 return self.items[self.len];
197228 }
198229
230 /// Like `pop` but returns `null` if empty.
199231 pub fn popOrNull(self: *Self) ?T {
200232 if (self.len == 0) return null;
201233 return self.pop();
......@@ -218,6 +250,7 @@ pub fn AlignedArrayList(comptime T: type, comptime alignment: ?u29) type {
218250 }
219251 };
220252
253 /// Return an iterator over the list.
221254 pub fn iterator(self: *const Self) Iterator {
222255 return Iterator{
223256 .list = self,
lib/std/debug/failing_allocator.zig+16
......@@ -3,6 +3,14 @@ const mem = std.mem;
33
44/// Allocator that fails after N allocations, useful for making sure out of
55/// memory conditions are handled correctly.
6///
7/// To use this, first initialize it and get an allocator with
8///
9/// `const failing_allocator = &FailingAllocator.init(<allocator>,
10/// <fail_index>).allocator;`
11///
12/// Then use `failing_allocator` anywhere you would have used a
13/// different allocator.
614pub const FailingAllocator = struct {
715 allocator: mem.Allocator,
816 index: usize,
......@@ -13,6 +21,14 @@ pub const FailingAllocator = struct {
1321 allocations: usize,
1422 deallocations: usize,
1523
24 /// `fail_index` is the number of successful allocations you can
25 /// expect from this allocator. The next allocation will fail.
26 /// For example, if this is called with `fail_index` equal to 2,
27 /// the following test will pass:
28 ///
29 /// var a = try failing_alloc.create(i32);
30 /// var b = try failing_alloc.create(i32);
31 /// testing.expectError(error.OutOfMemory, failing_alloc.create(i32));
1632 pub fn init(allocator: *mem.Allocator, fail_index: usize) FailingAllocator {
1733 return FailingAllocator{
1834 .internal_allocator = allocator,
lib/std/mem.zig+10
......@@ -93,6 +93,14 @@ pub const Allocator = struct {
9393 assert(shrink_result.len == 0);
9494 }
9595
96 /// Allocates an array of `n` items of type `T` and sets all the
97 /// items to `undefined`. Depending on the Allocator
98 /// implementation, it may be required to call `free` once the
99 /// memory is no longer needed, to avoid a resource leak. If the
100 /// `Allocator` implementation is unknown, then correct code will
101 /// call `free` when done.
102 ///
103 /// For allocating a single item, see `create`.
96104 pub fn alloc(self: *Allocator, comptime T: type, n: usize) Error![]T {
97105 return self.alignedAlloc(T, null, n);
98106 }
......@@ -218,6 +226,8 @@ pub const Allocator = struct {
218226 return @bytesToSlice(T, @alignCast(new_alignment, byte_slice));
219227 }
220228
229 /// Free an array allocated with `alloc`. To free a single item,
230 /// see `destroy`.
221231 pub fn free(self: *Allocator, memory: var) void {
222232 const Slice = @typeInfo(@typeOf(memory)).Pointer;
223233 const bytes = @sliceToBytes(memory);