Merge branch 'master' into autodoc-pkg-mod

Author: kristoff-it

doc/langref.html.in

@@ -1422,7 +1422,8 @@ fn foo() i32 {
 
       {#header_open|Thread Local Variables#}
       <p>A variable may be specified to be a thread-local variable using the
-      {#syntax#}threadlocal{#endsyntax#} keyword:</p>
+      {#syntax#}threadlocal{#endsyntax#} keyword,
+      which makes each thread work with a separate instance of the variable:</p>
       {#code_begin|test|test_thread_local_variables#}
 const std = @import("std");
 const assert = std.debug.assert;
@@ -4278,7 +4279,7 @@ const expectError = std.testing.expectError;
 fn isFieldOptional(comptime T: type, field_index: usize) !bool {
     const fields = @typeInfo(T).Struct.fields;
     return switch (field_index) {
-        // This prong is analyzed `fields.len - 1` times with `idx` being an
+        // This prong is analyzed `fields.len - 1` times with `idx` being a
         // unique comptime-known value each time.
         inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .Optional,
         else => return error.IndexOutOfBounds,
@@ -4667,6 +4668,29 @@ test "for basics" {
         sum2 += @intCast(i32, i);
     }
     try expect(sum2 == 10);
+
+    // To iterate over consecutive integers, use the range syntax.
+    // Unbounded range is always a compile error.
+    var sum3 : usize = 0;
+    for (0..5) |i| {
+        sum3 += i;
+    }
+    try expect(sum3 == 10);
+}
+
+test "multi object for" {
+    const items = [_]usize{ 1, 2, 3 };
+    const items2 = [_]usize{ 4, 5, 6 };
+    var count: usize = 0;
+
+    // Iterate over multiple objects.
+    // All lengths must be equal at the start of the loop, otherwise detectable
+    // illegal behavior occurs.
+    for (items, items2) |i, j| {
+        count += i + j;
+    }
+
+    try expect(count == 21);
 }
 
 test "for reference" {
@@ -4710,8 +4734,8 @@ const expect = std.testing.expect;
 
 test "nested break" {
     var count: usize = 0;
-    outer: for ([_]i32{ 1, 2, 3, 4, 5 }) |_| {
-        for ([_]i32{ 1, 2, 3, 4, 5 }) |_| {
+    outer: for (1..6) |_| {
+        for (1..6) |_| {
             count += 1;
             break :outer;
         }
@@ -4721,8 +4745,8 @@ test "nested break" {
 
 test "nested continue" {
     var count: usize = 0;
-    outer: for ([_]i32{ 1, 2, 3, 4, 5, 6, 7, 8 }) |_| {
-        for ([_]i32{ 1, 2, 3, 4, 5 }) |_| {
+    outer: for (1..9) |_| {
+        for (1..6) |_| {
             count += 1;
             continue :outer;
         }
@@ -8017,7 +8041,7 @@ pub const CallModifier = enum {
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type or an integer vector type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
       <p>
-      This function counts the number of most-significant (leading in a big-Endian sense) zeroes in an integer.
+      Counts the number of most-significant (leading in a big-endian sense) zeroes in an integer - "count leading zeroes".
       </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
@@ -8167,7 +8191,7 @@ test "main" {
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type or an integer vector type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
       <p>
-      This function counts the number of least-significant (trailing in a big-Endian sense) zeroes in an integer.
+      Counts the number of least-significant (trailing in a big-endian sense) zeroes in an integer - "count trailing zeroes".
       </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
@@ -8553,16 +8577,27 @@ test "@hasDecl" {
       </p>
       <ul>
           <li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li>
-          <li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information.
+          <li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information
               The command <code>zig build-exe --show-builtin</code> outputs the source to stdout for reference.
           </li>
-          <li>{#syntax#}@import("root"){#endsyntax#} - Points to the root source file.
-              This is usually <code>src/main.zig</code> but it depends on what file is chosen to be built.
+          <li>{#syntax#}@import("root"){#endsyntax#} - Root source file
+              This is usually <code>src/main.zig</code> but depends on what file is built.
           </li>
       </ul>
       {#see_also|Compile Variables|@embedFile#}
       {#header_close#}
 
+      {#header_open|@inComptime#}
+      <pre>{#syntax#}@inComptime() bool{#endsyntax#}</pre>
+      <p>
+      Returns whether the builtin was run in a {#syntax#}comptime{#endsyntax#} context. The result is a compile-time constant.
+      </p>
+      <p>
+      This can be used to provide alternative, comptime-friendly implementations of functions. It should not be used, for instance, to exclude certain functions from being evaluated at comptime.
+      </p>
+      {#see_also|comptime#}
+      {#header_close#}
+
       {#header_open|@intCast#}
       <pre>{#syntax#}@intCast(comptime DestType: type, int: anytype) DestType{#endsyntax#}</pre>
       <p>
@@ -8780,7 +8815,9 @@ test "@wasmMemoryGrow" {
       <pre>{#syntax#}@popCount(operand: anytype) anytype{#endsyntax#}</pre>
       <p>{#syntax#}@TypeOf(operand){#endsyntax#} must be an integer type.</p>
       <p>{#syntax#}operand{#endsyntax#} may be an {#link|integer|Integers#} or {#link|vector|Vectors#}.</p>
-      <p>Counts the number of bits set in an integer.</p>
+      <p>
+      Counts the number of bits set in an integer - "population count".
+      </p>
       <p>
       If {#syntax#}operand{#endsyntax#} is a {#link|comptime#}-known integer,
       the return type is {#syntax#}comptime_int{#endsyntax#}.
@@ -8812,6 +8849,8 @@ test "@wasmMemoryGrow" {
 pub const PrefetchOptions = struct {
     /// Whether the prefetch should prepare for a read or a write.
     rw: Rw = .read,
+    /// The data's locality in an inclusive range from 0 to 3.
+    ///
     /// 0 means no temporal locality. That is, the data can be immediately
     /// dropped from the cache after it is accessed.
     ///
@@ -8821,12 +8860,12 @@ pub const PrefetchOptions = struct {
     /// The cache that the prefetch should be preformed on.
     cache: Cache = .data,
 
-    pub const Rw = enum {
+    pub const Rw = enum(u1) {
         read,
         write,
     };
 
-    pub const Cache = enum {
+    pub const Cache = enum(u1) {
         instruction,
         data,
     };
@@ -10948,7 +10987,7 @@ pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected toke
       </p>
       <p>{#syntax#}[*c]T{#endsyntax#} - C pointer.</p>
       <ul>
-        <li>Supports all the syntax of the other two pointer types.</li>
+        <li>Supports all the syntax of the other two pointer types ({#syntax#}*T{#endsyntax#}) and ({#syntax#}[*]T{#endsyntax#}).</li>
         <li>Coerces to other pointer types, as well as {#link|Optional Pointers#}.
             When a C pointer is coerced to a non-optional pointer, safety-checked
             {#link|Undefined Behavior#} occurs if the address is 0.
@@ -11966,6 +12005,17 @@ fn readU32Be() u32 {}
             </ul>
           </td>
         </tr>
+        <tr>
+          <th scope="row">
+            <pre>{#syntax#}noinline{#endsyntax#}</pre>
+          </th>
+          <td>
+            {#syntax#}noinline{#endsyntax#} disallows function to be inlined in all call sites.
+            <ul>
+              <li>See also {#link|Functions#}</li>
+            </ul>
+          </td>
+        </tr>
         <tr>
           <th scope="row">
             <pre>{#syntax#}nosuspend{#endsyntax#}</pre>

lib/std/Build/Cache.zig

@@ -184,7 +184,7 @@ pub const File = struct {
 pub const HashHelper = struct {
     hasher: Hasher = hasher_init,
 
-    /// Record a slice of bytes as an dependency of the process being cached
+    /// Record a slice of bytes as a dependency of the process being cached.
     pub fn addBytes(hh: *HashHelper, bytes: []const u8) void {
         hh.hasher.update(mem.asBytes(&bytes.len));
         hh.hasher.update(bytes);

lib/std/RingBuffer.zig

@@ -1,7 +1,7 @@
 //! This ring buffer stores read and write indices while being able to utilise
 //! the full backing slice by incrementing the indices modulo twice the slice's
 //! length and reducing indices modulo the slice's length on slice access. This
-//! means that whether the ring buffer if full or empty can be distinguished by
+//! means that whether the ring buffer is full or empty can be distinguished by
 //! looking at the difference between the read and write indices without adding
 //! an extra boolean flag or having to reserve a slot in the buffer.
 //!

lib/std/Uri.zig

@@ -1,4 +1,4 @@
-//! Implements URI parsing roughly adhering to <https://tools.ietf.org/html/rfc3986>.
+//! Uniform Resource Identifier (URI) parsing roughly adhering to <https://tools.ietf.org/html/rfc3986>.
 //! Does not do perfect grammar and character class checking, but should be robust against URIs in the wild.
 
 const Uri = @This();

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();
 

lib/std/bit_set.zig

@@ -35,9 +35,10 @@ const assert = std.debug.assert;
 const Allocator = std.mem.Allocator;
 
 /// Returns the optimal static bit set type for the specified number
-/// of elements.  The returned type will perform no allocations,
+/// of elements: either `IntegerBitSet` or `ArrayBitSet`,
+/// both of which fulfill the same interface.
+/// The returned type will perform no allocations,
 /// can be copied by value, and does not require deinitialization.
-/// Both possible implementations fulfill the same interface.
 pub fn StaticBitSet(comptime size: usize) type {
     if (size <= @bitSizeOf(usize)) {
         return IntegerBitSet(size);

lib/std/builtin.zig

@@ -144,22 +144,47 @@ pub const Mode = OptimizeMode;
 /// This data structure is used by the Zig language code generation and
 /// therefore must be kept in sync with the compiler implementation.
 pub const CallingConvention = enum {
+    /// This is the default Zig calling convention used when not using `export` on `fn`
+    /// and no other calling convention is specified.
     Unspecified,
+    /// Matches the C ABI for the target.
+    /// This is the default calling convention when using `export` on `fn`
+    /// and no other calling convention is specified.
     C,
+    /// This makes a function not have any function prologue or epilogue,
+    /// making the function itself uncallable in regular Zig code.
+    /// This can be useful when integrating with assembly.
     Naked,
+    /// Functions with this calling convention are called asynchronously,
+    /// as if called as `async function()`.
     Async,
+    /// Functions with this calling convention are inlined at all call sites.
     Inline,
+    /// x86-only.
     Interrupt,
     Signal,
+    /// x86-only.
     Stdcall,
+    /// x86-only.
     Fastcall,
+    /// x86-only.
     Vectorcall,
+    /// x86-only.
     Thiscall,
+    /// ARM Procedure Call Standard (obsolete)
+    /// ARM-only.
     APCS,
+    /// ARM Architecture Procedure Call Standard (current standard)
+    /// ARM-only.
     AAPCS,
+    /// ARM Architecture Procedure Call Standard Vector Floating-Point
+    /// ARM-only.
     AAPCSVFP,
+    /// x86-64-only.
     SysV,
+    /// x86-64-only.
     Win64,
+    /// AMD GPU, NVPTX, or SPIR-V kernel
     Kernel,
 };
 
@@ -716,6 +741,8 @@ pub const VaList = switch (builtin.cpu.arch) {
 pub const PrefetchOptions = struct {
     /// Whether the prefetch should prepare for a read or a write.
     rw: Rw = .read,
+    /// The data's locality in an inclusive range from 0 to 3.
+    ///
     /// 0 means no temporal locality. That is, the data can be immediately
     /// dropped from the cache after it is accessed.
     ///

lib/std/c/darwin.zig

@@ -3846,3 +3846,11 @@ pub extern "c" fn os_signpost_interval_begin(log: os_log_t, signpos: os_signpost
 pub extern "c" fn os_signpost_interval_end(log: os_log_t, signpos: os_signpost_id_t, func: [*]const u8, ...) void;
 pub extern "c" fn os_signpost_id_make_with_pointer(log: os_log_t, ptr: ?*anyopaque) os_signpost_id_t;
 pub extern "c" fn os_signpost_enabled(log: os_log_t) bool;
+
+pub extern "c" fn proc_listpids(tpe: u32, tinfo: u32, buffer: ?*anyopaque, buffersize: c_int) c_int;
+pub extern "c" fn proc_listallpids(buffer: ?*anyopaque, buffersize: c_int) c_int;
+pub extern "c" fn proc_listpgrppids(pgrpid: pid_t, buffer: ?*anyopaque, buffersize: c_int) c_int;
+pub extern "c" fn proc_listchildpids(ppid: pid_t, buffer: ?*anyopaque, buffersize: c_int) c_int;
+pub extern "c" fn proc_pidinfo(pid: c_int, flavor: c_int, arg: u64, buffer: ?*anyopaque, buffersize: c_int) c_int;
+pub extern "c" fn proc_name(pid: c_int, buffer: ?*anyopaque, buffersize: u32) c_int;
+pub extern "c" fn proc_pidpath(pid: c_int, buffer: ?*anyopaque, buffersize: u32) c_int;

lib/std/c/dragonfly.zig

@@ -1143,3 +1143,20 @@ pub const POLL = struct {
     pub const HUP = 0x0010;
     pub const NVAL = 0x0020;
 };
+
+pub const SIGEV = struct {
+    pub const NONE = 0;
+    pub const SIGNAL = 1;
+    pub const THREAD = 2;
+};
+
+pub const sigevent = extern struct {
+    sigev_notify: c_int,
+    __sigev_u: extern union {
+        __sigev_signo: c_int,
+        __sigev_notify_kqueue: c_int,
+        __sigev_notify_attributes: ?*pthread_attr_t,
+    },
+    sigev_value: sigval,
+    sigev_notify_function: ?*const fn (sigval) callconv(.C) void,
+};