mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-07 23:03:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

@deprecated: add langref entry

Browse Source
This commit is contained in:
Loris Cro 2025-02-15 18:04:29 +01:00 committed by Andrew Kelley
parent ba7cd8121d
commit 06a66745a0
2 changed files with 59 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/langref.html.in
View File

@ -4741,6 +4741,43 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
{#see_also|@cVaArg|@cVaCopy|@cVaEnd#} {#see_also|@cVaArg|@cVaCopy|@cVaEnd#}
{#header_close#} {#header_close#}
{#header_open|@deprecated#}
<pre>{#syntax#}@deprecated(value: anytype) @TypeOf(value){#endsyntax#}</pre>
<pre>{#syntax#}@deprecated() void{#endsyntax#}</pre>
<p>
Used to mark a given code path as deprecated. It evaluates to the same value
passed in as argument, or the {#syntax#}void{#endsyntax#} value when given none.
</p>
<p>
As an example, in Zig 0.14.0 {#syntax#}std.time.sleep{#endsyntax#} was
deprecated and the sleep function was moved to {#syntax#}std.Thread.sleep{#endsyntax#}.
This is how this deprecation could have been expressed:
{#syntax_block|zig|lib/std/time.zig#}
pub const sleep = @deprecated(std.Thread.sleep); // moved
{#end_syntax_block#}
</p>
<p>
By default it is a <b>compile error</b> to depend on deprecated code in
a module defined by the root package, while it is not in modules defined
by dependencies. This behavior can be overridden for the entire dependency
tree by passing {#syntax#}-fallow-deprecated{#endsyntax#} or
{#syntax#}-fno-allow-deprecated{#endsyntax#} to {#syntax#}zig build{#endsyntax#}.
</p>
<p>
Usage of this builtin is meant to help <i>direct</i> consumers discover (and remove)
their dependance on deprecated code during the grace period before a deprecated
functionality is turned into a {#syntax#}@compileError{#endsyntax#} or
removed entirely.
</p>
<p>
{#syntax#}@deprecated{#endsyntax#} can also be used without argument:
{#code|test_deprecated_builtin.zig#}
</p>
{#header_close#}
{#header_open|@divExact#} {#header_open|@divExact#}
<pre>{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}</pre> <pre>{#syntax#}@divExact(numerator: T, denominator: T) T{#endsyntax#}</pre>
<p> <p>

22
doc/langref/test_deprecated_builtin.zig Normal file
View File

@ -0,0 +1,22 @@
test "deprecated code path" {
compute(.greedy, false, 42);
}
const Strategy = enum { greedy, expensive, fast };
fn compute(comptime strat: Strategy, comptime foo: bool, bar: usize) void {
switch (strat) {
.greedy => {
// This combination turned out to be ineffective.
if (!foo) @deprecated(); // use fast strategy when foo is false
runGreedy(foo, bar);
},
.expensive => runExpensive(foo, bar),
.fast => runFast(foo, bar),
}
}
extern fn runGreedy(foo: bool, bar: usize) void;
extern fn runExpensive(foo: bool, bar: usize) void;
extern fn runFast(foo: bool, bar: usize) void;
// test_error=deprecated