authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-12-08 23:46:50-05:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-12-08 23:46:50-05:00
log03396b3caac1ab76dae5f672800aafb176d46cad
tree82bab53cf670621b2cc08ea9ff743400f02f530b
parent5f9467d78f678932ec14946fc83ba50ad7fc2454
signature Commit is signed but in an unrecognized format.

update docs to new fmt API

3 files changed, 84 insertions(+), 72 deletions(-)

doc/langref.html.in+82-70
......@@ -205,7 +205,7 @@ const std = @import("std");
205205
206206pub fn main() !void {
207207 const stdout = &std.io.getStdOut().outStream().stream;
208 try stdout.print("Hello, {}!\n", "world");
208 try stdout.print("Hello, {}!\n", .{"world"});
209209}
210210 {#code_end#}
211211 <p>
......@@ -217,7 +217,7 @@ pub fn main() !void {
217217const warn = @import("std").debug.warn;
218218
219219pub fn main() void {
220 warn("Hello, world!\n");
220 warn("Hello, world!\n", .{});
221221}
222222 {#code_end#}
223223 <p>
......@@ -289,41 +289,50 @@ const assert = std.debug.assert;
289289pub fn main() void {
290290 // integers
291291 const one_plus_one: i32 = 1 + 1;
292 warn("1 + 1 = {}\n", one_plus_one);
292 warn("1 + 1 = {}\n", .{one_plus_one});
293293
294294 // floats
295295 const seven_div_three: f32 = 7.0 / 3.0;
296 warn("7.0 / 3.0 = {}\n", seven_div_three);
296 warn("7.0 / 3.0 = {}\n", .{seven_div_three});
297297
298298 // boolean
299 warn("{}\n{}\n{}\n",
299 warn("{}\n{}\n{}\n", .{
300300 true and false,
301301 true or false,
302 !true);
302 !true,
303 });
303304
304305 // optional
305306 var optional_value: ?[]const u8 = null;
306307 assert(optional_value == null);
307308
308 warn("\noptional 1\ntype: {}\nvalue: {}\n",
309 @typeName(@typeOf(optional_value)), optional_value);
309 warn("\noptional 1\ntype: {}\nvalue: {}\n", .{
310 @typeName(@typeOf(optional_value)),
311 optional_value,
312 });
310313
311314 optional_value = "hi";
312315 assert(optional_value != null);
313316
314 warn("\noptional 2\ntype: {}\nvalue: {}\n",
315 @typeName(@typeOf(optional_value)), optional_value);
317 warn("\noptional 2\ntype: {}\nvalue: {}\n", .{
318 @typeName(@typeOf(optional_value)),
319 optional_value,
320 });
316321
317322 // error union
318323 var number_or_error: anyerror!i32 = error.ArgNotFound;
319324
320 warn("\nerror union 1\ntype: {}\nvalue: {}\n",
321 @typeName(@typeOf(number_or_error)), number_or_error);
325 warn("\nerror union 1\ntype: {}\nvalue: {}\n", .{
326 @typeName(@typeOf(number_or_error)),
327 number_or_error,
328 });
322329
323330 number_or_error = 1234;
324331
325 warn("\nerror union 2\ntype: {}\nvalue: {}\n",
326 @typeName(@typeOf(number_or_error)), number_or_error);
332 warn("\nerror union 2\ntype: {}\nvalue: {}\n", .{
333 @typeName(@typeOf(number_or_error)),
334 number_or_error,
335 });
327336}
328337 {#code_end#}
329338 {#header_open|Primitive Types#}
......@@ -954,8 +963,8 @@ extern fn foo_optimized(x: f64) f64;
954963
955964pub fn main() void {
956965 const x = 0.001;
957 warn("optimized = {}\n", foo_optimized(x));
958 warn("strict = {}\n", foo_strict(x));
966 warn("optimized = {}\n", .{foo_optimized(x)});
967 warn("strict = {}\n", .{foo_strict(x)});
959968}
960969 {#code_end#}
961970 {#see_also|@setFloatMode|Division by Zero#}
......@@ -2182,7 +2191,7 @@ test "using slices for strings" {
21822191 // You can use slice syntax on an array to convert an array into a slice.
21832192 const all_together_slice = all_together[0..];
21842193 // String concatenation example.
2185 const hello_world = try fmt.bufPrint(all_together_slice, "{} {}", hello, world);
2194 const hello_world = try fmt.bufPrint(all_together_slice, "{} {}", .{hello, world});
21862195
21872196 // Generally, you can use UTF-8 and not worry about whether something is a
21882197 // string. If you don't need to deal with individual characters, no need
......@@ -2623,9 +2632,9 @@ const std = @import("std");
26232632
26242633pub fn main() void {
26252634 const Foo = struct {};
2626 std.debug.warn("variable: {}\n", @typeName(Foo));
2627 std.debug.warn("anonymous: {}\n", @typeName(struct {}));
2628 std.debug.warn("function: {}\n", @typeName(List(i32)));
2635 std.debug.warn("variable: {}\n", .{@typeName(Foo)});
2636 std.debug.warn("anonymous: {}\n", .{@typeName(struct {})});
2637 std.debug.warn("function: {}\n", .{@typeName(List(i32))});
26292638}
26302639
26312640fn List(comptime T: type) type {
......@@ -3806,18 +3815,18 @@ test "defer basics" {
38063815// If multiple defer statements are specified, they will be executed in
38073816// the reverse order they were run.
38083817fn deferUnwindExample() void {
3809 warn("\n");
3818 warn("\n", .{});
38103819
38113820 defer {
3812 warn("1 ");
3821 warn("1 ", .{});
38133822 }
38143823 defer {
3815 warn("2 ");
3824 warn("2 ", .{});
38163825 }
38173826 if (false) {
38183827 // defers are not run if they are never executed.
38193828 defer {
3820 warn("3 ");
3829 warn("3 ", .{});
38213830 }
38223831 }
38233832}
......@@ -3832,15 +3841,15 @@ test "defer unwinding" {
38323841// This is especially useful in allowing a function to clean up properly
38333842// on error, and replaces goto error handling tactics as seen in c.
38343843fn deferErrorExample(is_error: bool) !void {
3835 warn("\nstart of function\n");
3844 warn("\nstart of function\n", .{});
38363845
38373846 // This will always be executed on exit
38383847 defer {
3839 warn("end of function\n");
3848 warn("end of function\n", .{});
38403849 }
38413850
38423851 errdefer {
3843 warn("encountered an error!\n");
3852 warn("encountered an error!\n", .{});
38443853 }
38453854
38463855 if (is_error) {
......@@ -5843,7 +5852,7 @@ const a_number: i32 = 1234;
58435852const a_string = "foobar";
58445853
58455854pub fn main() void {
5846 warn("here is a string: '{}' here is a number: {}\n", a_string, a_number);
5855 warn("here is a string: '{}' here is a number: {}\n", .{a_string, a_number});
58475856}
58485857 {#code_end#}
58495858
......@@ -5960,8 +5969,11 @@ const a_number: i32 = 1234;
59605969const a_string = "foobar";
59615970
59625971test "printf too many arguments" {
5963 warn("here is a string: '{}' here is a number: {}\n",
5964 a_string, a_number, a_number);
5972 warn("here is a string: '{}' here is a number: {}\n", .{
5973 a_string,
5974 a_number,
5975 a_number,
5976 });
59655977}
59665978 {#code_end#}
59675979 <p>
......@@ -5979,7 +5991,7 @@ const a_string = "foobar";
59795991const fmt = "here is a string: '{}' here is a number: {}\n";
59805992
59815993pub fn main() void {
5982 warn(fmt, a_string, a_number);
5994 warn(fmt, .{a_string, a_number});
59835995}
59845996 {#code_end#}
59855997 <p>
......@@ -6417,7 +6429,7 @@ pub fn main() void {
64176429
64186430fn amainWrap() void {
64196431 amain() catch |e| {
6420 std.debug.warn("{}\n", e);
6432 std.debug.warn("{}\n", .{e});
64216433 if (@errorReturnTrace()) |trace| {
64226434 std.debug.dumpStackTrace(trace.*);
64236435 }
......@@ -6447,8 +6459,8 @@ fn amain() !void {
64476459 const download_text = try await download_frame;
64486460 defer allocator.free(download_text);
64496461
6450 std.debug.warn("download_text: {}\n", download_text);
6451 std.debug.warn("file_text: {}\n", file_text);
6462 std.debug.warn("download_text: {}\n", .{download_text});
6463 std.debug.warn("file_text: {}\n", .{file_text});
64526464}
64536465
64546466var global_download_frame: anyframe = undefined;
......@@ -6458,7 +6470,7 @@ fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
64586470 suspend {
64596471 global_download_frame = @frame();
64606472 }
6461 std.debug.warn("fetchUrl returning\n");
6473 std.debug.warn("fetchUrl returning\n", .{});
64626474 return result;
64636475}
64646476
......@@ -6469,7 +6481,7 @@ fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
64696481 suspend {
64706482 global_file_frame = @frame();
64716483 }
6472 std.debug.warn("readFile returning\n");
6484 std.debug.warn("readFile returning\n", .{});
64736485 return result;
64746486}
64756487 {#code_end#}
......@@ -6487,7 +6499,7 @@ pub fn main() void {
64876499
64886500fn amainWrap() void {
64896501 amain() catch |e| {
6490 std.debug.warn("{}\n", e);
6502 std.debug.warn("{}\n", .{e});
64916503 if (@errorReturnTrace()) |trace| {
64926504 std.debug.dumpStackTrace(trace.*);
64936505 }
......@@ -6517,21 +6529,21 @@ fn amain() !void {
65176529 const download_text = try await download_frame;
65186530 defer allocator.free(download_text);
65196531
6520 std.debug.warn("download_text: {}\n", download_text);
6521 std.debug.warn("file_text: {}\n", file_text);
6532 std.debug.warn("download_text: {}\n", .{download_text});
6533 std.debug.warn("file_text: {}\n", .{file_text});
65226534}
65236535
65246536fn fetchUrl(allocator: *Allocator, url: []const u8) ![]u8 {
65256537 const result = try std.mem.dupe(allocator, u8, "this is the downloaded url contents");
65266538 errdefer allocator.free(result);
6527 std.debug.warn("fetchUrl returning\n");
6539 std.debug.warn("fetchUrl returning\n", .{});
65286540 return result;
65296541}
65306542
65316543fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
65326544 const result = try std.mem.dupe(allocator, u8, "this is the file contents");
65336545 errdefer allocator.free(result);
6534 std.debug.warn("readFile returning\n");
6546 std.debug.warn("readFile returning\n", .{});
65356547 return result;
65366548}
65376549 {#code_end#}
......@@ -7103,7 +7115,7 @@ const num1 = blk: {
71037115test "main" {
71047116 @compileLog("comptime in main");
71057117
7106 warn("Runtime in main, num1 = {}.\n", num1);
7118 warn("Runtime in main, num1 = {}.\n", .{num1});
71077119}
71087120 {#code_end#}
71097121 <p>
......@@ -7124,7 +7136,7 @@ const num1 = blk: {
71247136};
71257137
71267138test "main" {
7127 warn("Runtime in main, num1 = {}.\n", num1);
7139 warn("Runtime in main, num1 = {}.\n", .{num1});
71287140}
71297141 {#code_end#}
71307142 {#header_close#}
......@@ -8706,7 +8718,7 @@ const std = @import("std");
87068718pub fn main() void {
87078719 var value: i32 = -1;
87088720 var unsigned = @intCast(u32, value);
8709 std.debug.warn("value: {}\n", unsigned);
8721 std.debug.warn("value: {}\n", .{unsigned});
87108722}
87118723 {#code_end#}
87128724 <p>
......@@ -8728,7 +8740,7 @@ const std = @import("std");
87288740pub fn main() void {
87298741 var spartan_count: u16 = 300;
87308742 const byte = @intCast(u8, spartan_count);
8731 std.debug.warn("value: {}\n", byte);
8743 std.debug.warn("value: {}\n", .{byte});
87328744}
87338745 {#code_end#}
87348746 <p>
......@@ -8762,7 +8774,7 @@ const std = @import("std");
87628774pub fn main() void {
87638775 var byte: u8 = 255;
87648776 byte += 1;
8765 std.debug.warn("value: {}\n", byte);
8777 std.debug.warn("value: {}\n", .{byte});
87668778}
87678779 {#code_end#}
87688780 {#header_close#}
......@@ -8785,11 +8797,11 @@ pub fn main() !void {
87858797 var byte: u8 = 255;
87868798
87878799 byte = if (math.add(u8, byte, 1)) |result| result else |err| {
8788 warn("unable to add one: {}\n", @errorName(err));
8800 warn("unable to add one: {}\n", .{@errorName(err)});
87898801 return err;
87908802 };
87918803
8792 warn("result: {}\n", byte);
8804 warn("result: {}\n", .{byte});
87938805}
87948806 {#code_end#}
87958807 {#header_close#}
......@@ -8814,9 +8826,9 @@ pub fn main() void {
88148826
88158827 var result: u8 = undefined;
88168828 if (@addWithOverflow(u8, byte, 10, &result)) {
8817 warn("overflowed result: {}\n", result);
8829 warn("overflowed result: {}\n", .{result});
88188830 } else {
8819 warn("result: {}\n", result);
8831 warn("result: {}\n", .{result});
88208832 }
88218833}
88228834 {#code_end#}
......@@ -8861,7 +8873,7 @@ const std = @import("std");
88618873pub fn main() void {
88628874 var x: u8 = 0b01010101;
88638875 var y = @shlExact(x, 2);
8864 std.debug.warn("value: {}\n", y);
8876 std.debug.warn("value: {}\n", .{y});
88658877}
88668878 {#code_end#}
88678879 {#header_close#}
......@@ -8879,7 +8891,7 @@ const std = @import("std");
88798891pub fn main() void {
88808892 var x: u8 = 0b10101010;
88818893 var y = @shrExact(x, 2);
8882 std.debug.warn("value: {}\n", y);
8894 std.debug.warn("value: {}\n", .{y});
88838895}
88848896 {#code_end#}
88858897 {#header_close#}
......@@ -8900,7 +8912,7 @@ pub fn main() void {
89008912 var a: u32 = 1;
89018913 var b: u32 = 0;
89028914 var c = a / b;
8903 std.debug.warn("value: {}\n", c);
8915 std.debug.warn("value: {}\n", .{c});
89048916}
89058917 {#code_end#}
89068918 {#header_close#}
......@@ -8921,7 +8933,7 @@ pub fn main() void {
89218933 var a: u32 = 10;
89228934 var b: u32 = 0;
89238935 var c = a % b;
8924 std.debug.warn("value: {}\n", c);
8936 std.debug.warn("value: {}\n", .{c});
89258937}
89268938 {#code_end#}
89278939 {#header_close#}
......@@ -8942,7 +8954,7 @@ pub fn main() void {
89428954 var a: u32 = 10;
89438955 var b: u32 = 3;
89448956 var c = @divExact(a, b);
8945 std.debug.warn("value: {}\n", c);
8957 std.debug.warn("value: {}\n", .{c});
89468958}
89478959 {#code_end#}
89488960 {#header_close#}
......@@ -8961,7 +8973,7 @@ const std = @import("std");
89618973pub fn main() void {
89628974 var bytes = [5]u8{ 1, 2, 3, 4, 5 };
89638975 var slice = @bytesToSlice(u32, bytes[0..]);
8964 std.debug.warn("value: {}\n", slice[0]);
8976 std.debug.warn("value: {}\n", .{slice[0]});
89658977}
89668978 {#code_end#}
89678979 {#header_close#}
......@@ -8980,7 +8992,7 @@ const std = @import("std");
89808992pub fn main() void {
89818993 var optional_number: ?i32 = null;
89828994 var number = optional_number.?;
8983 std.debug.warn("value: {}\n", number);
8995 std.debug.warn("value: {}\n", .{number});
89848996}
89858997 {#code_end#}
89868998 <p>One way to avoid this crash is to test for null instead of assuming non-null, with
......@@ -8991,9 +9003,9 @@ pub fn main() void {
89919003 const optional_number: ?i32 = null;
89929004
89939005 if (optional_number) |number| {
8994 warn("got number: {}\n", number);
9006 warn("got number: {}\n", .{number});
89959007 } else {
8996 warn("it's null\n");
9008 warn("it's null\n", .{});
89979009 }
89989010}
89999011 {#code_end#}
......@@ -9016,7 +9028,7 @@ const std = @import("std");
90169028
90179029pub fn main() void {
90189030 const number = getNumberOrFail() catch unreachable;
9019 std.debug.warn("value: {}\n", number);
9031 std.debug.warn("value: {}\n", .{number});
90209032}
90219033
90229034fn getNumberOrFail() !i32 {
......@@ -9032,9 +9044,9 @@ pub fn main() void {
90329044 const result = getNumberOrFail();
90339045
90349046 if (result) |number| {
9035 warn("got number: {}\n", number);
9047 warn("got number: {}\n", .{number});
90369048 } else |err| {
9037 warn("got error: {}\n", @errorName(err));
9049 warn("got error: {}\n", .{@errorName(err)});
90389050 }
90399051}
90409052
......@@ -9061,7 +9073,7 @@ pub fn main() void {
90619073 var err = error.AnError;
90629074 var number = @errorToInt(err) + 500;
90639075 var invalid_err = @intToError(number);
9064 std.debug.warn("value: {}\n", number);
9076 std.debug.warn("value: {}\n", .{number});
90659077}
90669078 {#code_end#}
90679079 {#header_close#}
......@@ -9091,7 +9103,7 @@ const Foo = enum {
90919103pub fn main() void {
90929104 var a: u2 = 3;
90939105 var b = @intToEnum(Foo, a);
9094 std.debug.warn("value: {}\n", @tagName(b));
9106 std.debug.warn("value: {}\n", .{@tagName(b)});
90959107}
90969108 {#code_end#}
90979109 {#header_close#}
......@@ -9128,7 +9140,7 @@ pub fn main() void {
91289140}
91299141fn foo(set1: Set1) void {
91309142 const x = @errSetCast(Set2, set1);
9131 std.debug.warn("value: {}\n", x);
9143 std.debug.warn("value: {}\n", .{x});
91329144}
91339145 {#code_end#}
91349146 {#header_close#}
......@@ -9184,7 +9196,7 @@ pub fn main() void {
91849196
91859197fn bar(f: *Foo) void {
91869198 f.float = 12.34;
9187 std.debug.warn("value: {}\n", f.float);
9199 std.debug.warn("value: {}\n", .{f.float});
91889200}
91899201 {#code_end#}
91909202 <p>
......@@ -9208,7 +9220,7 @@ pub fn main() void {
92089220
92099221fn bar(f: *Foo) void {
92109222 f.* = Foo{ .float = 12.34 };
9211 std.debug.warn("value: {}\n", f.float);
9223 std.debug.warn("value: {}\n", .{f.float});
92129224}
92139225 {#code_end#}
92149226 <p>
......@@ -9227,7 +9239,7 @@ pub fn main() void {
92279239 var f = Foo{ .int = 42 };
92289240 f = Foo{ .float = undefined };
92299241 bar(&f);
9230 std.debug.warn("value: {}\n", f.float);
9242 std.debug.warn("value: {}\n", .{f.float});
92319243}
92329244
92339245fn bar(f: *Foo) void {
......@@ -9348,7 +9360,7 @@ pub fn main() !void {
93489360 const allocator = &arena.allocator;
93499361
93509362 const ptr = try allocator.create(i32);
9351 std.debug.warn("ptr={*}\n", ptr);
9363 std.debug.warn("ptr={*}\n", .{ptr});
93529364}
93539365 {#code_end#}
93549366 When using this kind of allocator, there is no need to free anything manually. Everything
......@@ -9881,7 +9893,7 @@ pub fn main() !void {
98819893 defer std.process.argsFree(std.heap.page_allocator, args);
98829894
98839895 for (args) |arg, i| {
9884 std.debug.warn("{}: {}\n", i, arg);
9896 std.debug.warn("{}: {}\n", .{i, arg});
98859897 }
98869898}
98879899 {#code_end#}
lib/std/os/windows.zig+1-1
......@@ -323,7 +323,7 @@ pub fn GetQueuedCompletionStatus(
323323 ERROR.HANDLE_EOF => return GetQueuedCompletionStatusResult.EOF,
324324 else => |err| {
325325 if (std.debug.runtime_safety) {
326 std.debug.panic("unexpected error: {}\n", err);
326 std.debug.panic("unexpected error: {}\n", .{err});
327327 }
328328 },
329329 }
src-self-hosted/stage1.zig+1-1
......@@ -149,7 +149,7 @@ export fn stage2_fmt(argc: c_int, argv: [*]const [*:0]const u8) c_int {
149149 fmtMain(argc, argv) catch unreachable;
150150 } else {
151151 fmtMain(argc, argv) catch |e| {
152 std.debug.warn("{}\n", @errorName(e));
152 std.debug.warn("{}\n", .{@errorName(e)});
153153 return -1;
154154 };
155155 }