Commit 605769ec25923a50fc01d29d5837fbc48abffcf1 | zig

author	Eleanor NB <eleanor@eleanor-nb.com> 2020-06-19 19:38:22+10:00
committer	Andrew Kelley <andrew@ziglang.org> 2020-06-19 19:03:37-04:00
log	605769ec25923a50fc01d29d5837fbc48abffcf1
tree	c438abe24a3000da109455a081a99c30184b440d
parent	237c5429b0e8a089c89d13031ae6004ebac55ba9

Replaced all occurrences of std.debug.warn in the docs with std.debug.print

1 files changed, 78 insertions(+), 79 deletions(-)

doc
- langref.html.in

doc/langref.html.in+78-79

 @@ -236,19 +236,18 @@ pub fn main() !void {
 }
       {#code_end#}
       <p>
-      Usually you don't want to write to stdout. You want to write to stderr. And you
+      Usually you don't want to write to stdout. You want to write to stderr, and you
-      don't care if it fails. It's more like a <em>warning message</em> that you want
+      don't care if it fails. For that you can use a simpler API:
-      to emit. For that you can use a simpler API:
       </p>
       {#code_begin|exe|hello#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 pub fn main() void {
-    warn("Hello, world!\n", .{});
+    print("Hello, world!\n", .{});
 }
       {#code_end#}
       <p>
-      Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}warn{#endsyntax#} cannot fail.
+      Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}print{#endsyntax#} cannot fail.
       </p>
       {#see_also|Values|@import|Errors|Root Source File#}
       {#header_close#}
 @@ -307,7 +306,7 @@ const Timestamp = struct {
       {#header_open|Values#}
       {#code_begin|exe|values#}
 // Top-level declarations are order-independent:
-const warn = std.debug.warn;
+const print = std.debug.print;
 const std = @import("std");
 const os = std.os;
 const assert = std.debug.assert;
 @@ -315,14 +314,14 @@ const assert = std.debug.assert;
 pub fn main() void {
     // integers
     const one_plus_one: i32 = 1 + 1;
-    warn("1 + 1 = {}\n", .{one_plus_one});
+    print("1 + 1 = {}\n", .{one_plus_one});
     // floats
     const seven_div_three: f32 = 7.0 / 3.0;
-    warn("7.0 / 3.0 = {}\n", .{seven_div_three});
+    print("7.0 / 3.0 = {}\n", .{seven_div_three});
     // boolean
-    warn("{}\n{}\n{}\n", .{
+    print("{}\n{}\n{}\n", .{
         true and false,
         true or false,
         !true,
 @@ -332,7 +331,7 @@ pub fn main() void {
     var optional_value: ?[]const u8 = null;
     assert(optional_value == null);
-    warn("\noptional 1\ntype: {}\nvalue: {}\n", .{
+    print("\noptional 1\ntype: {}\nvalue: {}\n", .{
         @typeName(@TypeOf(optional_value)),
         optional_value,
     });
 @@ -340,7 +339,7 @@ pub fn main() void {
     optional_value = "hi";
     assert(optional_value != null);
-    warn("\noptional 2\ntype: {}\nvalue: {}\n", .{
+    print("\noptional 2\ntype: {}\nvalue: {}\n", .{
         @typeName(@TypeOf(optional_value)),
         optional_value,
     });
 @@ -348,14 +347,14 @@ pub fn main() void {
     // error union
     var number_or_error: anyerror!i32 = error.ArgNotFound;
-    warn("\nerror union 1\ntype: {}\nvalue: {}\n", .{
+    print("\nerror union 1\ntype: {}\nvalue: {}\n", .{
         @typeName(@TypeOf(number_or_error)),
         number_or_error,
     });
     number_or_error = 1234;
-    warn("\nerror union 2\ntype: {}\nvalue: {}\n", .{
+    print("\nerror union 2\ntype: {}\nvalue: {}\n", .{
         @typeName(@TypeOf(number_or_error)),
         number_or_error,
     });
 @@ -994,15 +993,15 @@ export fn foo_optimized(x: f64) f64 {
       which operates in strict mode.</p>
       {#code_begin|exe|float_mode#}
       {#code_link_object|foo#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 extern fn foo_strict(x: f64) f64;
 extern fn foo_optimized(x: f64) f64;
 pub fn main() void {
     const x = 0.001;
-    warn("optimized = {}\n", .{foo_optimized(x)});
+    print("optimized = {}\n", .{foo_optimized(x)});
-    warn("strict = {}\n", .{foo_strict(x)});
+    print("strict = {}\n", .{foo_strict(x)});
 }
       {#code_end#}
       {#see_also|@setFloatMode|Division by Zero#}
 @@ -2668,9 +2667,9 @@ const std = @import("std");
 pub fn main() void {
     const Foo = struct {};
-    std.debug.warn("variable: {}\n", .{@typeName(Foo)});
+    std.debug.print("variable: {}\n", .{@typeName(Foo)});
-    std.debug.warn("anonymous: {}\n", .{@typeName(struct {})});
+    std.debug.print("anonymous: {}\n", .{@typeName(struct {})});
-    std.debug.warn("function: {}\n", .{@typeName(List(i32))});
+    std.debug.print("function: {}\n", .{@typeName(List(i32))});
 }
 fn List(comptime T: type) type {
 @@ -3869,7 +3868,7 @@ test "if error union" {
       {#code_begin|test|defer#}
 const std = @import("std");
 const assert = std.debug.assert;
-const warn = std.debug.warn;
+const print = std.debug.print;
 // defer will execute an expression at the end of the current scope.
 fn deferExample() usize {
 @@ -3892,18 +3891,18 @@ test "defer basics" {
 // If multiple defer statements are specified, they will be executed in
 // the reverse order they were run.
 fn deferUnwindExample() void {
-    warn("\n", .{});
+    print("\n", .{});
     defer {
-        warn("1 ", .{});
+        print("1 ", .{});
     }
     defer {
-        warn("2 ", .{});
+        print("2 ", .{});
     }
     if (false) {
         // defers are not run if they are never executed.
         defer {
-            warn("3 ", .{});
+            print("3 ", .{});
         }
     }
 }
 @@ -3918,15 +3917,15 @@ test "defer unwinding" {
 // This is especially useful in allowing a function to clean up properly
 // on error, and replaces goto error handling tactics as seen in c.
 fn deferErrorExample(is_error: bool) !void {
-    warn("\nstart of function\n", .{});
+    print("\nstart of function\n", .{});
     // This will always be executed on exit
     defer {
-        warn("end of function\n", .{});
+        print("end of function\n", .{});
     }
     errdefer {
-        warn("encountered an error!\n", .{});
+        print("encountered an error!\n", .{});
     }
     if (is_error) {
 @@ -5925,13 +5924,13 @@ const Node = struct {
       Putting all of this together, let's see how {#syntax#}printf{#endsyntax#} works in Zig.
       </p>
       {#code_begin|exe|printf#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 const a_number: i32 = 1234;
 const a_string = "foobar";
 pub fn main() void {
-    warn("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
+    print("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
 }
       {#code_end#}
 @@ -6045,13 +6044,13 @@ pub fn printValue(self: *OutStream, value: var) !void {
       And now, what happens if we give too many arguments to {#syntax#}printf{#endsyntax#}?
       </p>
       {#code_begin|test_err|Unused arguments#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 const a_number: i32 = 1234;
 const a_string = "foobar";
 test "printf too many arguments" {
-    warn("here is a string: '{}' here is a number: {}\n", .{
+    print("here is a string: '{}' here is a number: {}\n", .{
         a_string,
         a_number,
         a_number,
 @@ -6066,14 +6065,14 @@ test "printf too many arguments" {
       only that it is a compile-time known value that can be coerced to a {#syntax#}[]const u8{#endsyntax#}:
       </p>
       {#code_begin|exe|printf#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 const a_number: i32 = 1234;
 const a_string = "foobar";
 const fmt = "here is a string: '{}' here is a number: {}\n";
 pub fn main() void {
-    warn(fmt, .{a_string, a_number});
+    print(fmt, .{a_string, a_number});
 }
       {#code_end#}
       <p>
 @@ -6511,7 +6510,7 @@ pub fn main() void {
 fn amainWrap() void {
     amain() catch |e| {
-        std.debug.warn("{}\n", .{e});
+        std.debug.print("{}\n", .{e});
         if (@errorReturnTrace()) |trace| {
             std.debug.dumpStackTrace(trace.*);
         }
 @@ -6541,8 +6540,8 @@ fn amain() !void {
     const download_text = try await download_frame;
     defer allocator.free(download_text);
-    std.debug.warn("download_text: {}\n", .{download_text});
+    std.debug.print("download_text: {}\n", .{download_text});
-    std.debug.warn("file_text: {}\n", .{file_text});
+    std.debug.print("file_text: {}\n", .{file_text});
 }
 var global_download_frame: anyframe = undefined;
 @@ -6552,7 +6551,7 @@ fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
     suspend {
         global_download_frame = @frame();
     }
-    std.debug.warn("fetchUrl returning\n", .{});
+    std.debug.print("fetchUrl returning\n", .{});
     return result;
 }
 @@ -6563,7 +6562,7 @@ fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
     suspend {
         global_file_frame = @frame();
     }
-    std.debug.warn("readFile returning\n", .{});
+    std.debug.print("readFile returning\n", .{});
     return result;
 }
       {#code_end#}
 @@ -6581,7 +6580,7 @@ pub fn main() void {
 fn amainWrap() void {
     amain() catch |e| {
-        std.debug.warn("{}\n", .{e});
+        std.debug.print("{}\n", .{e});
         if (@errorReturnTrace()) |trace| {
             std.debug.dumpStackTrace(trace.*);
         }
 @@ -6611,21 +6610,21 @@ fn amain() !void {
     const download_text = try await download_frame;
     defer allocator.free(download_text);
-    std.debug.warn("download_text: {}\n", .{download_text});
+    std.debug.print("download_text: {}\n", .{download_text});
-    std.debug.warn("file_text: {}\n", .{file_text});
+    std.debug.print("file_text: {}\n", .{file_text});
 }
 fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
     const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
     errdefer allocator.free(result);
-    std.debug.warn("fetchUrl returning\n", .{});
+    std.debug.print("fetchUrl returning\n", .{});
     return result;
 }
 fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
     const result = try std.mem.dupe(allocator, u8, "this is the file contents");
     errdefer allocator.free(result);
-    std.debug.warn("readFile returning\n", .{});
+    std.debug.print("readFile returning\n", .{});
     return result;
 }
       {#code_end#}
 @@ -7121,7 +7120,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       compile-time executing code.
       </p>
       {#code_begin|test_err|found compile log statement#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 const num1 = blk: {
     var val1: i32 = 99;
 @@ -7133,7 +7132,7 @@ const num1 = blk: {
 test "main" {
     @compileLog("comptime in main");
-    warn("Runtime in main, num1 = {}.\n", .{num1});
+    print("Runtime in main, num1 = {}.\n", .{num1});
 }
       {#code_end#}
       <p>
 @@ -7145,7 +7144,7 @@ test "main" {
       program compiles successfully and the generated executable prints:
       </p>
       {#code_begin|test#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 const num1 = blk: {
     var val1: i32 = 99;
 @@ -7154,7 +7153,7 @@ const num1 = blk: {
 };
 test "main" {
-    warn("Runtime in main, num1 = {}.\n", .{num1});
+    print("Runtime in main, num1 = {}.\n", .{num1});
 }
       {#code_end#}
       {#header_close#}
 @@ -8555,7 +8554,7 @@ const std = @import("std");
 pub fn main() void {
     var value: i32 = -1;
     var unsigned = @intCast(u32, value);
-    std.debug.warn("value: {}\n", .{unsigned});
+    std.debug.print("value: {}\n", .{unsigned});
 }
       {#code_end#}
       <p>
 @@ -8577,7 +8576,7 @@ const std = @import("std");
 pub fn main() void {
     var spartan_count: u16 = 300;
     const byte = @intCast(u8, spartan_count);
-    std.debug.warn("value: {}\n", .{byte});
+    std.debug.print("value: {}\n", .{byte});
 }
       {#code_end#}
       <p>
 @@ -8611,7 +8610,7 @@ const std = @import("std");
 pub fn main() void {
     var byte: u8 = 255;
     byte += 1;
-    std.debug.warn("value: {}\n", .{byte});
+    std.debug.print("value: {}\n", .{byte});
 }
       {#code_end#}
       {#header_close#}
 @@ -8629,16 +8628,16 @@ pub fn main() void {
       <p>Example of catching an overflow for addition:</p>
       {#code_begin|exe_err#}
 const math = @import("std").math;
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 pub fn main() !void {
     var byte: u8 = 255;
     byte = if (math.add(u8, byte, 1)) |result| result else |err| {
-        warn("unable to add one: {}\n", .{@errorName(err)});
+        print("unable to add one: {}\n", .{@errorName(err)});
         return err;
     };
-    warn("result: {}\n", .{byte});
+    print("result: {}\n", .{byte});
 }
       {#code_end#}
       {#header_close#}
 @@ -8657,15 +8656,15 @@ pub fn main() !void {
       Example of {#link|@addWithOverflow#}:
       </p>
       {#code_begin|exe#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 pub fn main() void {
     var byte: u8 = 255;
     var result: u8 = undefined;
     if (@addWithOverflow(u8, byte, 10, &result)) {
-        warn("overflowed result: {}\n", .{result});
+        print("overflowed result: {}\n", .{result});
     } else {
-        warn("result: {}\n", .{result});
+        print("result: {}\n", .{result});
     }
 }
       {#code_end#}
 @@ -8710,7 +8709,7 @@ const std = @import("std");
 pub fn main() void {
     var x: u8 = 0b01010101;
     var y = @shlExact(x, 2);
-    std.debug.warn("value: {}\n", .{y});
+    std.debug.print("value: {}\n", .{y});
 }
       {#code_end#}
       {#header_close#}
 @@ -8728,7 +8727,7 @@ const std = @import("std");
 pub fn main() void {
     var x: u8 = 0b10101010;
     var y = @shrExact(x, 2);
-    std.debug.warn("value: {}\n", .{y});
+    std.debug.print("value: {}\n", .{y});
 }
       {#code_end#}
       {#header_close#}
 @@ -8749,7 +8748,7 @@ pub fn main() void {
     var a: u32 = 1;
     var b: u32 = 0;
     var c = a / b;
-    std.debug.warn("value: {}\n", .{c});
+    std.debug.print("value: {}\n", .{c});
 }
       {#code_end#}
       {#header_close#}
 @@ -8770,7 +8769,7 @@ pub fn main() void {
     var a: u32 = 10;
     var b: u32 = 0;
     var c = a % b;
-    std.debug.warn("value: {}\n", .{c});
+    std.debug.print("value: {}\n", .{c});
 }
       {#code_end#}
       {#header_close#}
 @@ -8791,7 +8790,7 @@ pub fn main() void {
     var a: u32 = 10;
     var b: u32 = 3;
     var c = @divExact(a, b);
-    std.debug.warn("value: {}\n", .{c});
+    std.debug.print("value: {}\n", .{c});
 }
       {#code_end#}
       {#header_close#}
 @@ -8810,20 +8809,20 @@ const std = @import("std");
 pub fn main() void {
     var optional_number: ?i32 = null;
     var number = optional_number.?;
-    std.debug.warn("value: {}\n", .{number});
+    std.debug.print("value: {}\n", .{number});
 }
       {#code_end#}
       <p>One way to avoid this crash is to test for null instead of assuming non-null, with
       the {#syntax#}if{#endsyntax#} expression:</p>
       {#code_begin|exe|test#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 pub fn main() void {
     const optional_number: ?i32 = null;
     if (optional_number) |number| {
-        warn("got number: {}\n", .{number});
+        print("got number: {}\n", .{number});
     } else {
-        warn("it's null\n", .{});
+        print("it's null\n", .{});
     }
 }
       {#code_end#}
 @@ -8846,7 +8845,7 @@ const std = @import("std");
 pub fn main() void {
     const number = getNumberOrFail() catch unreachable;
-    std.debug.warn("value: {}\n", .{number});
+    std.debug.print("value: {}\n", .{number});
 }
 fn getNumberOrFail() !i32 {
 @@ -8856,15 +8855,15 @@ fn getNumberOrFail() !i32 {
       <p>One way to avoid this crash is to test for an error instead of assuming a successful result, with
       the {#syntax#}if{#endsyntax#} expression:</p>
       {#code_begin|exe#}
-const warn = @import("std").debug.warn;
+const print = @import("std").debug.print;
 pub fn main() void {
     const result = getNumberOrFail();
     if (result) |number| {
-        warn("got number: {}\n", .{number});
+        print("got number: {}\n", .{number});
     } else |err| {
-        warn("got error: {}\n", .{@errorName(err)});
+        print("got error: {}\n", .{@errorName(err)});
     }
 }
 @@ -8891,7 +8890,7 @@ pub fn main() void {
     var err = error.AnError;
     var number = @errorToInt(err) + 500;
     var invalid_err = @intToError(number);
-    std.debug.warn("value: {}\n", .{number});
+    std.debug.print("value: {}\n", .{number});
 }
       {#code_end#}
       {#header_close#}
 @@ -8921,7 +8920,7 @@ const Foo = enum {
 pub fn main() void {
     var a: u2 = 3;
     var b = @intToEnum(Foo, a);
-    std.debug.warn("value: {}\n", .{@tagName(b)});
+    std.debug.print("value: {}\n", .{@tagName(b)});
 }
       {#code_end#}
       {#header_close#}
 @@ -8958,7 +8957,7 @@ pub fn main() void {
 }
 fn foo(set1: Set1) void {
     const x = @errSetCast(Set2, set1);
-    std.debug.warn("value: {}\n", .{x});
+    std.debug.print("value: {}\n", .{x});
 }
       {#code_end#}
       {#header_close#}
 @@ -9015,7 +9014,7 @@ pub fn main() void {
 fn bar(f: *Foo) void {
     f.float = 12.34;
-    std.debug.warn("value: {}\n", .{f.float});
+    std.debug.print("value: {}\n", .{f.float});
 }
       {#code_end#}
       <p>
 @@ -9039,7 +9038,7 @@ pub fn main() void {
 fn bar(f: *Foo) void {
     f.* = Foo{ .float = 12.34 };
-    std.debug.warn("value: {}\n", .{f.float});
+    std.debug.print("value: {}\n", .{f.float});
 }
       {#code_end#}
       <p>
 @@ -9058,7 +9057,7 @@ pub fn main() void {
     var f = Foo{ .int = 42 };
     f = Foo{ .float = undefined };
     bar(&f);
-    std.debug.warn("value: {}\n", .{f.float});
+    std.debug.print("value: {}\n", .{f.float});
 }
 fn bar(f: *Foo) void {
 @@ -9178,7 +9177,7 @@ pub fn main() !void {
     const allocator = &arena.allocator;
     const ptr = try allocator.create(i32);
-    std.debug.warn("ptr={*}\n", .{ptr});
+    std.debug.print("ptr={*}\n", .{ptr});
 }
               {#code_end#}
               When using this kind of allocator, there is no need to free anything manually. Everything
 @@ -9712,7 +9711,7 @@ pub fn main() !void {
     defer std.process.argsFree(std.heap.page_allocator, args);
     for (args) |arg, i| {
-        std.debug.warn("{}: {}\n", .{i, arg});
+        std.debug.print("{}: {}\n", .{i, arg});
     }
 }
       {#code_end#}
 @@ -9734,7 +9733,7 @@ pub fn main() !void {
     try preopens.populate();
     for (preopens.asSlice()) |preopen, i| {
-        std.debug.warn("{}: {}\n", .{ i, preopen });
+        std.debug.print("{}: {}\n", .{ i, preopen });
     }
 }
       {#code_end#}