authorgravatar for eleanor@eleanor-nb.comEleanor NB <eleanor@eleanor-nb.com> 2020-06-19 19:38:22+10:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2020-06-19 19:03:37-04:00
log605769ec25923a50fc01d29d5837fbc48abffcf1
treec438abe24a3000da109455a081a99c30184b440d
parent237c5429b0e8a089c89d13031ae6004ebac55ba9

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+78-79
......@@ -236,19 +236,18 @@ pub fn main() !void {
236236}
237237 {#code_end#}
238238 <p>
239 Usually you don't want to write to stdout. You want to write to stderr. And you
240 don't care if it fails. It's more like a <em>warning message</em> that you want
241 to emit. For that you can use a simpler API:
239 Usually you don't want to write to stdout. You want to write to stderr, and you
240 don't care if it fails. For that you can use a simpler API:
242241 </p>
243242 {#code_begin|exe|hello#}
244const warn = @import("std").debug.warn;
243const print = @import("std").debug.print;
245244
246245pub fn main() void {
247 warn("Hello, world!\n", .{});
246 print("Hello, world!\n", .{});
248247}
249248 {#code_end#}
250249 <p>
251 Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}warn{#endsyntax#} cannot fail.
250 Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}print{#endsyntax#} cannot fail.
252251 </p>
253252 {#see_also|Values|@import|Errors|Root Source File#}
254253 {#header_close#}
......@@ -307,7 +306,7 @@ const Timestamp = struct {
307306 {#header_open|Values#}
308307 {#code_begin|exe|values#}
309308// Top-level declarations are order-independent:
310const warn = std.debug.warn;
309const print = std.debug.print;
311310const std = @import("std");
312311const os = std.os;
313312const assert = std.debug.assert;
......@@ -315,14 +314,14 @@ const assert = std.debug.assert;
315314pub fn main() void {
316315 // integers
317316 const one_plus_one: i32 = 1 + 1;
318 warn("1 + 1 = {}\n", .{one_plus_one});
317 print("1 + 1 = {}\n", .{one_plus_one});
319318
320319 // floats
321320 const seven_div_three: f32 = 7.0 / 3.0;
322 warn("7.0 / 3.0 = {}\n", .{seven_div_three});
321 print("7.0 / 3.0 = {}\n", .{seven_div_three});
323322
324323 // boolean
325 warn("{}\n{}\n{}\n", .{
324 print("{}\n{}\n{}\n", .{
326325 true and false,
327326 true or false,
328327 !true,
......@@ -332,7 +331,7 @@ pub fn main() void {
332331 var optional_value: ?[]const u8 = null;
333332 assert(optional_value == null);
334333
335 warn("\noptional 1\ntype: {}\nvalue: {}\n", .{
334 print("\noptional 1\ntype: {}\nvalue: {}\n", .{
336335 @typeName(@TypeOf(optional_value)),
337336 optional_value,
338337 });
......@@ -340,7 +339,7 @@ pub fn main() void {
340339 optional_value = "hi";
341340 assert(optional_value != null);
342341
343 warn("\noptional 2\ntype: {}\nvalue: {}\n", .{
342 print("\noptional 2\ntype: {}\nvalue: {}\n", .{
344343 @typeName(@TypeOf(optional_value)),
345344 optional_value,
346345 });
......@@ -348,14 +347,14 @@ pub fn main() void {
348347 // error union
349348 var number_or_error: anyerror!i32 = error.ArgNotFound;
350349
351 warn("\nerror union 1\ntype: {}\nvalue: {}\n", .{
350 print("\nerror union 1\ntype: {}\nvalue: {}\n", .{
352351 @typeName(@TypeOf(number_or_error)),
353352 number_or_error,
354353 });
355354
356355 number_or_error = 1234;
357356
358 warn("\nerror union 2\ntype: {}\nvalue: {}\n", .{
357 print("\nerror union 2\ntype: {}\nvalue: {}\n", .{
359358 @typeName(@TypeOf(number_or_error)),
360359 number_or_error,
361360 });
......@@ -994,15 +993,15 @@ export fn foo_optimized(x: f64) f64 {
994993 which operates in strict mode.</p>
995994 {#code_begin|exe|float_mode#}
996995 {#code_link_object|foo#}
997const warn = @import("std").debug.warn;
996const print = @import("std").debug.print;
998997
999998extern fn foo_strict(x: f64) f64;
1000999extern fn foo_optimized(x: f64) f64;
10011000
10021001pub fn main() void {
10031002 const x = 0.001;
1004 warn("optimized = {}\n", .{foo_optimized(x)});
1005 warn("strict = {}\n", .{foo_strict(x)});
1003 print("optimized = {}\n", .{foo_optimized(x)});
1004 print("strict = {}\n", .{foo_strict(x)});
10061005}
10071006 {#code_end#}
10081007 {#see_also|@setFloatMode|Division by Zero#}
......@@ -2668,9 +2667,9 @@ const std = @import("std");
26682667
26692668pub fn main() void {
26702669 const Foo = struct {};
2671 std.debug.warn("variable: {}\n", .{@typeName(Foo)});
2672 std.debug.warn("anonymous: {}\n", .{@typeName(struct {})});
2673 std.debug.warn("function: {}\n", .{@typeName(List(i32))});
2670 std.debug.print("variable: {}\n", .{@typeName(Foo)});
2671 std.debug.print("anonymous: {}\n", .{@typeName(struct {})});
2672 std.debug.print("function: {}\n", .{@typeName(List(i32))});
26742673}
26752674
26762675fn List(comptime T: type) type {
......@@ -3869,7 +3868,7 @@ test "if error union" {
38693868 {#code_begin|test|defer#}
38703869const std = @import("std");
38713870const assert = std.debug.assert;
3872const warn = std.debug.warn;
3871const print = std.debug.print;
38733872
38743873// defer will execute an expression at the end of the current scope.
38753874fn deferExample() usize {
......@@ -3892,18 +3891,18 @@ test "defer basics" {
38923891// If multiple defer statements are specified, they will be executed in
38933892// the reverse order they were run.
38943893fn deferUnwindExample() void {
3895 warn("\n", .{});
3894 print("\n", .{});
38963895
38973896 defer {
3898 warn("1 ", .{});
3897 print("1 ", .{});
38993898 }
39003899 defer {
3901 warn("2 ", .{});
3900 print("2 ", .{});
39023901 }
39033902 if (false) {
39043903 // defers are not run if they are never executed.
39053904 defer {
3906 warn("3 ", .{});
3905 print("3 ", .{});
39073906 }
39083907 }
39093908}
......@@ -3918,15 +3917,15 @@ test "defer unwinding" {
39183917// This is especially useful in allowing a function to clean up properly
39193918// on error, and replaces goto error handling tactics as seen in c.
39203919fn deferErrorExample(is_error: bool) !void {
3921 warn("\nstart of function\n", .{});
3920 print("\nstart of function\n", .{});
39223921
39233922 // This will always be executed on exit
39243923 defer {
3925 warn("end of function\n", .{});
3924 print("end of function\n", .{});
39263925 }
39273926
39283927 errdefer {
3929 warn("encountered an error!\n", .{});
3928 print("encountered an error!\n", .{});
39303929 }
39313930
39323931 if (is_error) {
......@@ -5925,13 +5924,13 @@ const Node = struct {
59255924 Putting all of this together, let's see how {#syntax#}printf{#endsyntax#} works in Zig.
59265925 </p>
59275926 {#code_begin|exe|printf#}
5928const warn = @import("std").debug.warn;
5927const print = @import("std").debug.print;
59295928
59305929const a_number: i32 = 1234;
59315930const a_string = "foobar";
59325931
59335932pub fn main() void {
5934 warn("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
5933 print("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
59355934}
59365935 {#code_end#}
59375936
......@@ -6045,13 +6044,13 @@ pub fn printValue(self: *OutStream, value: var) !void {
60456044 And now, what happens if we give too many arguments to {#syntax#}printf{#endsyntax#}?
60466045 </p>
60476046 {#code_begin|test_err|Unused arguments#}
6048const warn = @import("std").debug.warn;
6047const print = @import("std").debug.print;
60496048
60506049const a_number: i32 = 1234;
60516050const a_string = "foobar";
60526051
60536052test "printf too many arguments" {
6054 warn("here is a string: '{}' here is a number: {}\n", .{
6053 print("here is a string: '{}' here is a number: {}\n", .{
60556054 a_string,
60566055 a_number,
60576056 a_number,
......@@ -6066,14 +6065,14 @@ test "printf too many arguments" {
60666065 only that it is a compile-time known value that can be coerced to a {#syntax#}[]const u8{#endsyntax#}:
60676066 </p>
60686067 {#code_begin|exe|printf#}
6069const warn = @import("std").debug.warn;
6068const print = @import("std").debug.print;
60706069
60716070const a_number: i32 = 1234;
60726071const a_string = "foobar";
60736072const fmt = "here is a string: '{}' here is a number: {}\n";
60746073
60756074pub fn main() void {
6076 warn(fmt, .{a_string, a_number});
6075 print(fmt, .{a_string, a_number});
60776076}
60786077 {#code_end#}
60796078 <p>
......@@ -6511,7 +6510,7 @@ pub fn main() void {
65116510
65126511fn amainWrap() void {
65136512 amain() catch |e| {
6514 std.debug.warn("{}\n", .{e});
6513 std.debug.print("{}\n", .{e});
65156514 if (@errorReturnTrace()) |trace| {
65166515 std.debug.dumpStackTrace(trace.*);
65176516 }
......@@ -6541,8 +6540,8 @@ fn amain() !void {
65416540 const download_text = try await download_frame;
65426541 defer allocator.free(download_text);
65436542
6544 std.debug.warn("download_text: {}\n", .{download_text});
6545 std.debug.warn("file_text: {}\n", .{file_text});
6543 std.debug.print("download_text: {}\n", .{download_text});
6544 std.debug.print("file_text: {}\n", .{file_text});
65466545}
65476546
65486547var global_download_frame: anyframe = undefined;
......@@ -6552,7 +6551,7 @@ fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
65526551 suspend {
65536552 global_download_frame = @frame();
65546553 }
6555 std.debug.warn("fetchUrl returning\n", .{});
6554 std.debug.print("fetchUrl returning\n", .{});
65566555 return result;
65576556}
65586557
......@@ -6563,7 +6562,7 @@ fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
65636562 suspend {
65646563 global_file_frame = @frame();
65656564 }
6566 std.debug.warn("readFile returning\n", .{});
6565 std.debug.print("readFile returning\n", .{});
65676566 return result;
65686567}
65696568 {#code_end#}
......@@ -6581,7 +6580,7 @@ pub fn main() void {
65816580
65826581fn amainWrap() void {
65836582 amain() catch |e| {
6584 std.debug.warn("{}\n", .{e});
6583 std.debug.print("{}\n", .{e});
65856584 if (@errorReturnTrace()) |trace| {
65866585 std.debug.dumpStackTrace(trace.*);
65876586 }
......@@ -6611,21 +6610,21 @@ fn amain() !void {
66116610 const download_text = try await download_frame;
66126611 defer allocator.free(download_text);
66136612
6614 std.debug.warn("download_text: {}\n", .{download_text});
6615 std.debug.warn("file_text: {}\n", .{file_text});
6613 std.debug.print("download_text: {}\n", .{download_text});
6614 std.debug.print("file_text: {}\n", .{file_text});
66166615}
66176616
66186617fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
66196618 const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
66206619 errdefer allocator.free(result);
6621 std.debug.warn("fetchUrl returning\n", .{});
6620 std.debug.print("fetchUrl returning\n", .{});
66226621 return result;
66236622}
66246623
66256624fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
66266625 const result = try std.mem.dupe(allocator, u8, "this is the file contents");
66276626 errdefer allocator.free(result);
6628 std.debug.warn("readFile returning\n", .{});
6627 std.debug.print("readFile returning\n", .{});
66296628 return result;
66306629}
66316630 {#code_end#}
......@@ -7121,7 +7120,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
71217120 compile-time executing code.
71227121 </p>
71237122 {#code_begin|test_err|found compile log statement#}
7124const warn = @import("std").debug.warn;
7123const print = @import("std").debug.print;
71257124
71267125const num1 = blk: {
71277126 var val1: i32 = 99;
......@@ -7133,7 +7132,7 @@ const num1 = blk: {
71337132test "main" {
71347133 @compileLog("comptime in main");
71357134
7136 warn("Runtime in main, num1 = {}.\n", .{num1});
7135 print("Runtime in main, num1 = {}.\n", .{num1});
71377136}
71387137 {#code_end#}
71397138 <p>
......@@ -7145,7 +7144,7 @@ test "main" {
71457144 program compiles successfully and the generated executable prints:
71467145 </p>
71477146 {#code_begin|test#}
7148const warn = @import("std").debug.warn;
7147const print = @import("std").debug.print;
71497148
71507149const num1 = blk: {
71517150 var val1: i32 = 99;
......@@ -7154,7 +7153,7 @@ const num1 = blk: {
71547153};
71557154
71567155test "main" {
7157 warn("Runtime in main, num1 = {}.\n", .{num1});
7156 print("Runtime in main, num1 = {}.\n", .{num1});
71587157}
71597158 {#code_end#}
71607159 {#header_close#}
......@@ -8555,7 +8554,7 @@ const std = @import("std");
85558554pub fn main() void {
85568555 var value: i32 = -1;
85578556 var unsigned = @intCast(u32, value);
8558 std.debug.warn("value: {}\n", .{unsigned});
8557 std.debug.print("value: {}\n", .{unsigned});
85598558}
85608559 {#code_end#}
85618560 <p>
......@@ -8577,7 +8576,7 @@ const std = @import("std");
85778576pub fn main() void {
85788577 var spartan_count: u16 = 300;
85798578 const byte = @intCast(u8, spartan_count);
8580 std.debug.warn("value: {}\n", .{byte});
8579 std.debug.print("value: {}\n", .{byte});
85818580}
85828581 {#code_end#}
85838582 <p>
......@@ -8611,7 +8610,7 @@ const std = @import("std");
86118610pub fn main() void {
86128611 var byte: u8 = 255;
86138612 byte += 1;
8614 std.debug.warn("value: {}\n", .{byte});
8613 std.debug.print("value: {}\n", .{byte});
86158614}
86168615 {#code_end#}
86178616 {#header_close#}
......@@ -8629,16 +8628,16 @@ pub fn main() void {
86298628 <p>Example of catching an overflow for addition:</p>
86308629 {#code_begin|exe_err#}
86318630const math = @import("std").math;
8632const warn = @import("std").debug.warn;
8631const print = @import("std").debug.print;
86338632pub fn main() !void {
86348633 var byte: u8 = 255;
86358634
86368635 byte = if (math.add(u8, byte, 1)) |result| result else |err| {
8637 warn("unable to add one: {}\n", .{@errorName(err)});
8636 print("unable to add one: {}\n", .{@errorName(err)});
86388637 return err;
86398638 };
86408639
8641 warn("result: {}\n", .{byte});
8640 print("result: {}\n", .{byte});
86428641}
86438642 {#code_end#}
86448643 {#header_close#}
......@@ -8657,15 +8656,15 @@ pub fn main() !void {
86578656 Example of {#link|@addWithOverflow#}:
86588657 </p>
86598658 {#code_begin|exe#}
8660const warn = @import("std").debug.warn;
8659const print = @import("std").debug.print;
86618660pub fn main() void {
86628661 var byte: u8 = 255;
86638662
86648663 var result: u8 = undefined;
86658664 if (@addWithOverflow(u8, byte, 10, &result)) {
8666 warn("overflowed result: {}\n", .{result});
8665 print("overflowed result: {}\n", .{result});
86678666 } else {
8668 warn("result: {}\n", .{result});
8667 print("result: {}\n", .{result});
86698668 }
86708669}
86718670 {#code_end#}
......@@ -8710,7 +8709,7 @@ const std = @import("std");
87108709pub fn main() void {
87118710 var x: u8 = 0b01010101;
87128711 var y = @shlExact(x, 2);
8713 std.debug.warn("value: {}\n", .{y});
8712 std.debug.print("value: {}\n", .{y});
87148713}
87158714 {#code_end#}
87168715 {#header_close#}
......@@ -8728,7 +8727,7 @@ const std = @import("std");
87288727pub fn main() void {
87298728 var x: u8 = 0b10101010;
87308729 var y = @shrExact(x, 2);
8731 std.debug.warn("value: {}\n", .{y});
8730 std.debug.print("value: {}\n", .{y});
87328731}
87338732 {#code_end#}
87348733 {#header_close#}
......@@ -8749,7 +8748,7 @@ pub fn main() void {
87498748 var a: u32 = 1;
87508749 var b: u32 = 0;
87518750 var c = a / b;
8752 std.debug.warn("value: {}\n", .{c});
8751 std.debug.print("value: {}\n", .{c});
87538752}
87548753 {#code_end#}
87558754 {#header_close#}
......@@ -8770,7 +8769,7 @@ pub fn main() void {
87708769 var a: u32 = 10;
87718770 var b: u32 = 0;
87728771 var c = a % b;
8773 std.debug.warn("value: {}\n", .{c});
8772 std.debug.print("value: {}\n", .{c});
87748773}
87758774 {#code_end#}
87768775 {#header_close#}
......@@ -8791,7 +8790,7 @@ pub fn main() void {
87918790 var a: u32 = 10;
87928791 var b: u32 = 3;
87938792 var c = @divExact(a, b);
8794 std.debug.warn("value: {}\n", .{c});
8793 std.debug.print("value: {}\n", .{c});
87958794}
87968795 {#code_end#}
87978796 {#header_close#}
......@@ -8810,20 +8809,20 @@ const std = @import("std");
88108809pub fn main() void {
88118810 var optional_number: ?i32 = null;
88128811 var number = optional_number.?;
8813 std.debug.warn("value: {}\n", .{number});
8812 std.debug.print("value: {}\n", .{number});
88148813}
88158814 {#code_end#}
88168815 <p>One way to avoid this crash is to test for null instead of assuming non-null, with
88178816 the {#syntax#}if{#endsyntax#} expression:</p>
88188817 {#code_begin|exe|test#}
8819const warn = @import("std").debug.warn;
8818const print = @import("std").debug.print;
88208819pub fn main() void {
88218820 const optional_number: ?i32 = null;
88228821
88238822 if (optional_number) |number| {
8824 warn("got number: {}\n", .{number});
8823 print("got number: {}\n", .{number});
88258824 } else {
8826 warn("it's null\n", .{});
8825 print("it's null\n", .{});
88278826 }
88288827}
88298828 {#code_end#}
......@@ -8846,7 +8845,7 @@ const std = @import("std");
88468845
88478846pub fn main() void {
88488847 const number = getNumberOrFail() catch unreachable;
8849 std.debug.warn("value: {}\n", .{number});
8848 std.debug.print("value: {}\n", .{number});
88508849}
88518850
88528851fn getNumberOrFail() !i32 {
......@@ -8856,15 +8855,15 @@ fn getNumberOrFail() !i32 {
88568855 <p>One way to avoid this crash is to test for an error instead of assuming a successful result, with
88578856 the {#syntax#}if{#endsyntax#} expression:</p>
88588857 {#code_begin|exe#}
8859const warn = @import("std").debug.warn;
8858const print = @import("std").debug.print;
88608859
88618860pub fn main() void {
88628861 const result = getNumberOrFail();
88638862
88648863 if (result) |number| {
8865 warn("got number: {}\n", .{number});
8864 print("got number: {}\n", .{number});
88668865 } else |err| {
8867 warn("got error: {}\n", .{@errorName(err)});
8866 print("got error: {}\n", .{@errorName(err)});
88688867 }
88698868}
88708869
......@@ -8891,7 +8890,7 @@ pub fn main() void {
88918890 var err = error.AnError;
88928891 var number = @errorToInt(err) + 500;
88938892 var invalid_err = @intToError(number);
8894 std.debug.warn("value: {}\n", .{number});
8893 std.debug.print("value: {}\n", .{number});
88958894}
88968895 {#code_end#}
88978896 {#header_close#}
......@@ -8921,7 +8920,7 @@ const Foo = enum {
89218920pub fn main() void {
89228921 var a: u2 = 3;
89238922 var b = @intToEnum(Foo, a);
8924 std.debug.warn("value: {}\n", .{@tagName(b)});
8923 std.debug.print("value: {}\n", .{@tagName(b)});
89258924}
89268925 {#code_end#}
89278926 {#header_close#}
......@@ -8958,7 +8957,7 @@ pub fn main() void {
89588957}
89598958fn foo(set1: Set1) void {
89608959 const x = @errSetCast(Set2, set1);
8961 std.debug.warn("value: {}\n", .{x});
8960 std.debug.print("value: {}\n", .{x});
89628961}
89638962 {#code_end#}
89648963 {#header_close#}
......@@ -9015,7 +9014,7 @@ pub fn main() void {
90159014
90169015fn bar(f: *Foo) void {
90179016 f.float = 12.34;
9018 std.debug.warn("value: {}\n", .{f.float});
9017 std.debug.print("value: {}\n", .{f.float});
90199018}
90209019 {#code_end#}
90219020 <p>
......@@ -9039,7 +9038,7 @@ pub fn main() void {
90399038
90409039fn bar(f: *Foo) void {
90419040 f.* = Foo{ .float = 12.34 };
9042 std.debug.warn("value: {}\n", .{f.float});
9041 std.debug.print("value: {}\n", .{f.float});
90439042}
90449043 {#code_end#}
90459044 <p>
......@@ -9058,7 +9057,7 @@ pub fn main() void {
90589057 var f = Foo{ .int = 42 };
90599058 f = Foo{ .float = undefined };
90609059 bar(&f);
9061 std.debug.warn("value: {}\n", .{f.float});
9060 std.debug.print("value: {}\n", .{f.float});
90629061}
90639062
90649063fn bar(f: *Foo) void {
......@@ -9178,7 +9177,7 @@ pub fn main() !void {
91789177 const allocator = &arena.allocator;
91799178
91809179 const ptr = try allocator.create(i32);
9181 std.debug.warn("ptr={*}\n", .{ptr});
9180 std.debug.print("ptr={*}\n", .{ptr});
91829181}
91839182 {#code_end#}
91849183 When using this kind of allocator, there is no need to free anything manually. Everything
......@@ -9712,7 +9711,7 @@ pub fn main() !void {
97129711 defer std.process.argsFree(std.heap.page_allocator, args);
97139712
97149713 for (args) |arg, i| {
9715 std.debug.warn("{}: {}\n", .{i, arg});
9714 std.debug.print("{}: {}\n", .{i, arg});
97169715 }
97179716}
97189717 {#code_end#}
......@@ -9734,7 +9733,7 @@ pub fn main() !void {
97349733 try preopens.populate();
97359734
97369735 for (preopens.asSlice()) |preopen, i| {
9737 std.debug.warn("{}: {}\n", .{ i, preopen });
9736 std.debug.print("{}: {}\n", .{ i, preopen });
97389737 }
97399738}
97409739 {#code_end#}