gitback/zig
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

langref: make more consistent

Browse Source 
* moves some langref into std.builtin doc comments
* use the same way of referencing stuff from std.builtin

closes #16483
This commit is contained in:
Andrew Kelley 2024-01-21 20:39:50 -07:00
parent 1b8e6b8ba9
commit ce7c66e2d0
2 changed files with 35 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
doc/langref.html.in
View File

@ -7754,7 +7754,7 @@ comptime {
{#header_close#}
{#header_open|@atomicLoad#}
<pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
<pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
<p>
This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.
</p>
@ -7762,11 +7762,12 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
{#header_open|@atomicRmw#}
<pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
<pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
<p>
This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically
modifies the value and returns the previous value.
@ -7775,27 +7776,13 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
<p>
Supported values for the {#syntax#}op{#endsyntax#} parameter:
</p>
<ul>
<li>{#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.</li>
<li>{#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition.
Also supports {#link|Floats#}.</li>
<li>{#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction.
Also supports {#link|Floats#}.</li>
<li>{#syntax#}.And{#endsyntax#} - bitwise and</li>
<li>{#syntax#}.Nand{#endsyntax#} - bitwise nand</li>
<li>{#syntax#}.Or{#endsyntax#} - bitwise or</li>
<li>{#syntax#}.Xor{#endsyntax#} - bitwise xor</li>
<li>{#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.</li>
<li>{#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.</li>
</ul>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
<p>{#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
{#header_open|@atomicStore#}
<pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}</pre>
<pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}</pre>
<p>
This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.
</p>
@ -7803,6 +7790,7 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
@ -8079,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v
an integer or an enum.
</p>
<p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#}
{#header_close#}
@ -8110,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
an integer or an enum.
</p>
<p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#}
{#header_close#}
@ -8400,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}
<p>
The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.
</p>
<p>
{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.
</p>
<p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
@ -8810,7 +8798,7 @@ test "@wasmMemoryGrow" {
{#header_close#}
{#header_open|@prefetch#}
<pre>{#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}</pre>
<pre>{#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}</pre>
<p>
This builtin tells the compiler to emit a prefetch instruction if supported by the
target CPU. If the target CPU does not support the requested prefetch instruction,
@ -8822,37 +8810,7 @@ test "@wasmMemoryGrow" {
address to prefetch. This function does not dereference the pointer, it is perfectly legal
to pass a pointer to invalid memory to this function and no illegal behavior will result.
</p>
<p>
The {#syntax#}options{#endsyntax#} argument is the following struct:
</p>
{#code_begin|syntax|builtin#}
/// This data structure is used by the Zig language code generation and
/// therefore must be kept in sync with the compiler implementation.
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.
///
/// 3 means high temporal locality. That is, the data should be kept in
/// the cache as it is likely to be accessed again soon.
locality: u2 = 3,
/// The cache that the prefetch should be preformed on.
cache: Cache = .data,
pub const Rw = enum(u1) {
read,
write,
};
pub const Cache = enum(u1) {
instruction,
data,
};
};
{#code_end#}
<p>{#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.</p>
{#header_close#}
{#header_open|@ptrCast#}
@ -8981,16 +8939,8 @@ test "foo" {
{#header_close#}
{#header_open|@setFloatMode#}
<pre>{#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}</pre>
<p>
Sets the floating point mode of the current scope. Possible values are:
</p>
{#code_begin|syntax|FloatMode#}
pub const FloatMode = enum {
Strict,
Optimized,
};
{#code_end#}
<pre>{#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}</pre>
<p>Changes the current scope's rules about how floating point operations are defined.</p>
<ul>
<li>
{#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
@ -9012,6 +8962,7 @@ pub const FloatMode = enum {
The floating point mode is inherited by child scopes, and can be overridden in any scope.
You can set the floating point mode in a struct or module scope by using a comptime block.
</p>
<p>{#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.</p>
{#see_also|Floating Point Operations#}
{#header_close#}

20
lib/std/builtin.zig
View File

@ -102,14 +102,34 @@ pub const ReduceOp = enum {
/// This data structure is used by the Zig language code generation and
/// therefore must be kept in sync with the compiler implementation.
pub const AtomicRmwOp = enum {
/// Exchange - store the operand unmodified.
/// Supports enums, integers, and floats.
Xchg,
/// Add operand to existing value.
/// Supports integers and floats.
/// For integers, two's complement wraparound applies.
Add,
/// Subtract operand from existing value.
/// Supports integers and floats.
/// For integers, two's complement wraparound applies.
Sub,
/// Perform bitwise AND on existing value with operand.
/// Supports integers.
And,
/// Perform bitwise NAND on existing value with operand.
/// Supports integers.
Nand,
/// Perform bitwise OR on existing value with operand.
/// Supports integers.
Or,
/// Perform bitwise XOR on existing value with operand.
/// Supports integers.
Xor,
/// Store operand if it is larger than the existing value.
/// Supports integers and floats.
Max,
/// Store operand if it is smaller than the existing value.
/// Supports integers and floats.
Min,
};