From bc8e1e1de4a2f22c56528240d320f682f1ec4b69 Mon Sep 17 00:00:00 2001 From: zooster Date: Sun, 23 Apr 2023 20:06:21 +0200 Subject: Improvements to docs and text * docs(std.math): elaborate on difference between absCast and absInt * docs(std.rand.Random.weightedIndex): elaborate on likelihood I think this makes it easier to understand. * langref: add small reminder * docs(std.fs.path.extension): brevity * docs(std.bit_set.StaticBitSet): mention the specific types * std.debug.TTY: explain what purpose this struct serves This should also make it clearer that this struct is not supposed to provide unrelated terminal manipulation functionality such as setting the cursor position or something because terminals are complicated and we should keep this struct simple and focused on debugging. * langref(package listing): brevity * langref: explain what exactly `threadlocal` causes to happen * std.array_list: link between swapRemove and orderedRemove Maybe this can serve as a TLDR and make it easier to decide. * PrefetchOptions.locality: clarify docs that this is a range This confused me previously and I thought I can only use either 0 or 3. * fix typos and more * std.builtin.CallingConvention: document some CCs * langref: explain possibly cryptic names I think it helps knowing what exactly these acronyms (@clz and @ctz) and abbreviations (@popCount) mean. * variadic function error: add missing preposition * std.fmt.format docs: nicely hyphenate * help menu: say what to optimize for I think this is slightly more specific than just calling it "optimizations". These are speed optimizations. I used the word "performance" here. --- lib/std/array_list.zig | 2 ++ 1 file changed, 2 insertions(+) (limited to 'lib/std/array_list.zig') diff --git a/lib/std/array_list.zig b/lib/std/array_list.zig index 205649ae4d..1695e2bd87 100644 --- a/lib/std/array_list.zig +++ b/lib/std/array_list.zig @@ -221,6 +221,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type { /// Asserts the array has at least one item. /// Invalidates pointers to end of list. /// This operation is O(N). + /// This preserves item order. Use `swapRemove` if order preservation is not important. pub fn orderedRemove(self: *Self, i: usize) T { const newlen = self.items.len - 1; if (newlen == i) return self.pop(); @@ -235,6 +236,7 @@ pub fn ArrayListAligned(comptime T: type, comptime alignment: ?u29) type { /// Removes the element at the specified index and returns it. /// The empty slot is filled from the end of the list. /// This operation is O(1). + /// This may not preserve item order. Use `orderedRemove` if you need to preserve order. pub fn swapRemove(self: *Self, i: usize) T { if (self.items.len - 1 == i) return self.pop(); -- cgit v1.2.3