authorgravatar for mail@isaacfreund.comIsaac Freund <mail@isaacfreund.com> 2020-10-14 17:34:05+02:00
committergravatar for git@vexu.euVeikka Tuominen <git@vexu.eu> 2020-10-15 18:55:57+03:00
log7b150dd05ed3e647897e6f3b0beb08e10e73c92e
tree9562e476e2501f6581fc28337448174f14d2bb6d
parent3b4432d9a6ae7f01f66e5ddcc15bf579d2c47460

docs: snake_case enums/unions in langref examples

This follows the accepted change to the style guide: https://github.com/ziglang/zig/issues/2101

1 files changed, 151 insertions(+), 151 deletions(-)

doc/langref.html.in+151-151
......@@ -2839,81 +2839,81 @@ const mem = @import("std").mem;
28392839
28402840// Declare an enum.
28412841const Type = enum {
2842 Ok,
2843 NotOk,
2842 ok,
2843 not_ok,
28442844};
28452845
28462846// Declare a specific instance of the enum variant.
2847const c = Type.Ok;
2847const c = Type.ok;
28482848
28492849// If you want access to the ordinal value of an enum, you
28502850// can specify the tag type.
28512851const Value = enum(u2) {
2852 Zero,
2853 One,
2854 Two,
2852 zero,
2853 one,
2854 two,
28552855};
28562856
28572857// Now you can cast between u2 and Value.
28582858// The ordinal value starts from 0, counting up for each member.
28592859test "enum ordinal value" {
2860 assert(@enumToInt(Value.Zero) == 0);
2861 assert(@enumToInt(Value.One) == 1);
2862 assert(@enumToInt(Value.Two) == 2);
2860 assert(@enumToInt(Value.zero) == 0);
2861 assert(@enumToInt(Value.one) == 1);
2862 assert(@enumToInt(Value.two) == 2);
28632863}
28642864
28652865// You can override the ordinal value for an enum.
28662866const Value2 = enum(u32) {
2867 Hundred = 100,
2868 Thousand = 1000,
2869 Million = 1000000,
2867 hundred = 100,
2868 thousand = 1000,
2869 million = 1000000,
28702870};
28712871test "set enum ordinal value" {
2872 assert(@enumToInt(Value2.Hundred) == 100);
2873 assert(@enumToInt(Value2.Thousand) == 1000);
2874 assert(@enumToInt(Value2.Million) == 1000000);
2872 assert(@enumToInt(Value2.hundred) == 100);
2873 assert(@enumToInt(Value2.thousand) == 1000);
2874 assert(@enumToInt(Value2.million) == 1000000);
28752875}
28762876
28772877// Enums can have methods, the same as structs and unions.
28782878// Enum methods are not special, they are only namespaced
28792879// functions that you can call with dot syntax.
28802880const Suit = enum {
2881 Clubs,
2882 Spades,
2883 Diamonds,
2884 Hearts,
2881 clubs,
2882 spades,
2883 diamonds,
2884 hearts,
28852885
28862886 pub fn isClubs(self: Suit) bool {
2887 return self == Suit.Clubs;
2887 return self == Suit.clubs;
28882888 }
28892889};
28902890test "enum method" {
2891 const p = Suit.Spades;
2891 const p = Suit.spades;
28922892 assert(!p.isClubs());
28932893}
28942894
28952895// An enum variant of different types can be switched upon.
28962896const Foo = enum {
2897 String,
2898 Number,
2899 None,
2897 string,
2898 number,
2899 none,
29002900};
29012901test "enum variant switch" {
2902 const p = Foo.Number;
2902 const p = Foo.number;
29032903 const what_is_it = switch (p) {
2904 Foo.String => "this is a string",
2905 Foo.Number => "this is a number",
2906 Foo.None => "this is a none",
2904 Foo.string => "this is a string",
2905 Foo.number => "this is a number",
2906 Foo.none => "this is a none",
29072907 };
29082908 assert(mem.eql(u8, what_is_it, "this is a number"));
29092909}
29102910
29112911// @TagType can be used to access the integer tag type of an enum.
29122912const Small = enum {
2913 One,
2914 Two,
2915 Three,
2916 Four,
2913 one,
2914 two,
2915 three,
2916 four,
29172917};
29182918test "@TagType" {
29192919 assert(@TagType(Small) == u2);
......@@ -2922,12 +2922,12 @@ test "@TagType" {
29222922// @typeInfo tells us the field count and the fields names:
29232923test "@typeInfo" {
29242924 assert(@typeInfo(Small).Enum.fields.len == 4);
2925 assert(mem.eql(u8, @typeInfo(Small).Enum.fields[1].name, "Two"));
2925 assert(mem.eql(u8, @typeInfo(Small).Enum.fields[1].name, "two"));
29262926}
29272927
29282928// @tagName gives a []const u8 representation of an enum value:
29292929test "@tagName" {
2930 assert(mem.eql(u8, @tagName(Small.Three), "Three"));
2930 assert(mem.eql(u8, @tagName(Small.three), "three"));
29312931}
29322932 {#code_end#}
29332933 {#see_also|@typeInfo|@tagName|@sizeOf#}
......@@ -2937,14 +2937,14 @@ test "@tagName" {
29372937 By default, enums are not guaranteed to be compatible with the C ABI:
29382938 </p>
29392939 {#code_begin|obj_err|parameter of type 'Foo' not allowed in function with calling convention 'C'#}
2940const Foo = enum { A, B, C };
2940const Foo = enum { a, b, c };
29412941export fn entry(foo: Foo) void { }
29422942 {#code_end#}
29432943 <p>
29442944 For a C-ABI-compatible enum, use {#syntax#}extern enum{#endsyntax#}:
29452945 </p>
29462946 {#code_begin|obj#}
2947const Foo = extern enum { A, B, C };
2947const Foo = extern enum { a, b, c };
29482948export fn entry(foo: Foo) void { }
29492949 {#code_end#}
29502950 {#header_close#}
......@@ -2958,9 +2958,9 @@ const std = @import("std");
29582958
29592959test "packed enum" {
29602960 const Number = packed enum(u8) {
2961 One,
2962 Two,
2963 Three,
2961 one,
2962 two,
2963 three,
29642964 };
29652965 std.debug.assert(@sizeOf(Number) == @sizeOf(u8));
29662966}
......@@ -2977,23 +2977,23 @@ const std = @import("std");
29772977const assert = std.debug.assert;
29782978
29792979const Color = enum {
2980 Auto,
2981 Off,
2982 On,
2980 auto,
2981 off,
2982 on,
29832983};
29842984
29852985test "enum literals" {
2986 const color1: Color = .Auto;
2987 const color2 = Color.Auto;
2986 const color1: Color = .auto;
2987 const color2 = Color.auto;
29882988 assert(color1 == color2);
29892989}
29902990
29912991test "switch using enum literals" {
2992 const color = Color.On;
2992 const color = Color.on;
29932993 const result = switch (color) {
2994 .Auto => false,
2995 .On => true,
2996 .Off => false,
2994 .auto => false,
2995 .on => true,
2996 .off => false,
29972997 };
29982998 assert(result);
29992999}
......@@ -3017,23 +3017,23 @@ const std = @import("std");
30173017const assert = std.debug.assert;
30183018
30193019const Number = enum(u8) {
3020 One,
3021 Two,
3022 Three,
3020 one,
3021 two,
3022 three,
30233023 _,
30243024};
30253025
30263026test "switch on non-exhaustive enum" {
3027 const number = Number.One;
3027 const number = Number.one;
30283028 const result = switch (number) {
3029 .One => true,
3030 .Two,
3031 .Three => false,
3029 .one => true,
3030 .two,
3031 .three => false,
30323032 _ => false,
30333033 };
30343034 assert(result);
30353035 const is_one = switch (number) {
3036 .One => true,
3036 .one => true,
30373037 else => false,
30383038 };
30393039 assert(is_one);
......@@ -3055,13 +3055,13 @@ test "switch on non-exhaustive enum" {
30553055 </p>
30563056 {#code_begin|test_err|inactive union field#}
30573057const Payload = union {
3058 Int: i64,
3059 Float: f64,
3060 Bool: bool,
3058 int: i64,
3059 float: f64,
3060 boolean: bool,
30613061};
30623062test "simple union" {
3063 var payload = Payload{ .Int = 1234 };
3064 payload.Float = 12.34;
3063 var payload = Payload{ .int = 1234 };
3064 payload.float = 12.34;
30653065}
30663066 {#code_end#}
30673067 <p>You can activate another field by assigning the entire union:</p>
......@@ -3070,15 +3070,15 @@ const std = @import("std");
30703070const assert = std.debug.assert;
30713071
30723072const Payload = union {
3073 Int: i64,
3074 Float: f64,
3075 Bool: bool,
3073 int: i64,
3074 float: f64,
3075 boolean: bool,
30763076};
30773077test "simple union" {
3078 var payload = Payload{ .Int = 1234 };
3079 assert(payload.Int == 1234);
3080 payload = Payload{ .Float = 12.34 };
3081 assert(payload.Float == 12.34);
3078 var payload = Payload{ .int = 1234 };
3079 assert(payload.int == 1234);
3080 payload = Payload{ .float = 12.34 };
3081 assert(payload.float == 12.34);
30823082}
30833083 {#code_end#}
30843084 <p>
......@@ -3100,21 +3100,21 @@ const std = @import("std");
31003100const assert = std.debug.assert;
31013101
31023102const ComplexTypeTag = enum {
3103 Ok,
3104 NotOk,
3103 ok,
3104 not_ok,
31053105};
31063106const ComplexType = union(ComplexTypeTag) {
3107 Ok: u8,
3108 NotOk: void,
3107 ok: u8,
3108 not_ok: void,
31093109};
31103110
31113111test "switch on tagged union" {
3112 const c = ComplexType{ .Ok = 42 };
3113 assert(@as(ComplexTypeTag, c) == ComplexTypeTag.Ok);
3112 const c = ComplexType{ .ok = 42 };
3113 assert(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);
31143114
31153115 switch (c) {
3116 ComplexTypeTag.Ok => |value| assert(value == 42),
3117 ComplexTypeTag.NotOk => unreachable,
3116 ComplexTypeTag.ok => |value| assert(value == 42),
3117 ComplexTypeTag.not_ok => unreachable,
31183118 }
31193119}
31203120
......@@ -3123,11 +3123,11 @@ test "@TagType" {
31233123}
31243124
31253125test "coerce to enum" {
3126 const c1 = ComplexType{ .Ok = 42 };
3127 const c2 = ComplexType.NotOk;
3126 const c1 = ComplexType{ .ok = 42 };
3127 const c2 = ComplexType.not_ok;
31283128
3129 assert(c1 == .Ok);
3130 assert(c2 == .NotOk);
3129 assert(c1 == .ok);
3130 assert(c2 == .not_ok);
31313131}
31323132 {#code_end#}
31333133 <p>In order to modify the payload of a tagged union in a switch expression,
......@@ -3138,24 +3138,24 @@ const std = @import("std");
31383138const assert = std.debug.assert;
31393139
31403140const ComplexTypeTag = enum {
3141 Ok,
3142 NotOk,
3141 ok,
3142 not_ok,
31433143};
31443144const ComplexType = union(ComplexTypeTag) {
3145 Ok: u8,
3146 NotOk: void,
3145 ok: u8,
3146 not_ok: void,
31473147};
31483148
31493149test "modify tagged union in switch" {
3150 var c = ComplexType{ .Ok = 42 };
3151 assert(@as(ComplexTypeTag, c) == ComplexTypeTag.Ok);
3150 var c = ComplexType{ .ok = 42 };
3151 assert(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);
31523152
31533153 switch (c) {
3154 ComplexTypeTag.Ok => |*value| value.* += 1,
3155 ComplexTypeTag.NotOk => unreachable,
3154 ComplexTypeTag.ok => |*value| value.* += 1,
3155 ComplexTypeTag.not_ok => unreachable,
31563156 }
31573157
3158 assert(c.Ok == 43);
3158 assert(c.ok == 43);
31593159}
31603160 {#code_end#}
31613161 <p>
......@@ -3167,24 +3167,24 @@ const std = @import("std");
31673167const assert = std.debug.assert;
31683168
31693169const Variant = union(enum) {
3170 Int: i32,
3171 Bool: bool,
3170 int: i32,
3171 boolean: bool,
31723172
31733173 // void can be omitted when inferring enum tag type.
3174 None,
3174 none,
31753175
31763176 fn truthy(self: Variant) bool {
31773177 return switch (self) {
3178 Variant.Int => |x_int| x_int != 0,
3179 Variant.Bool => |x_bool| x_bool,
3180 Variant.None => false,
3178 Variant.int => |x_int| x_int != 0,
3179 Variant.boolean => |x_bool| x_bool,
3180 Variant.none => false,
31813181 };
31823182 }
31833183};
31843184
31853185test "union method" {
3186 var v1 = Variant{ .Int = 1 };
3187 var v2 = Variant{ .Bool = false };
3186 var v1 = Variant{ .int = 1 };
3187 var v2 = Variant{ .boolean = false };
31883188
31893189 assert(v1.truthy());
31903190 assert(!v2.truthy());
......@@ -3199,12 +3199,12 @@ const std = @import("std");
31993199const assert = std.debug.assert;
32003200
32013201const Small2 = union(enum) {
3202 A: i32,
3203 B: bool,
3204 C: u8,
3202 a: i32,
3203 b: bool,
3204 c: u8,
32053205};
32063206test "@tagName" {
3207 assert(std.mem.eql(u8, @tagName(Small2.C), "C"));
3207 assert(std.mem.eql(u8, @tagName(Small2.a), "a"));
32083208}
32093209 {#code_end#}
32103210 {#header_close#}
......@@ -3392,33 +3392,33 @@ test "switch on tagged union" {
33923392 y: u8,
33933393 };
33943394 const Item = union(enum) {
3395 A: u32,
3396 C: Point,
3397 D,
3398 E: u32,
3395 a: u32,
3396 c: Point,
3397 d,
3398 e: u32,
33993399 };
34003400
3401 var a = Item{ .C = Point{ .x = 1, .y = 2 } };
3401 var a = Item{ .c = Point{ .x = 1, .y = 2 } };
34023402
34033403 // Switching on more complex enums is allowed.
34043404 const b = switch (a) {
34053405 // A capture group is allowed on a match, and will return the enum
34063406 // value matched. If the payload types of both cases are the same
34073407 // they can be put into the same switch prong.
3408 Item.A, Item.E => |item| item,
3408 Item.a, Item.e => |item| item,
34093409
34103410 // A reference to the matched value can be obtained using `*` syntax.
3411 Item.C => |*item| blk: {
3411 Item.c => |*item| blk: {
34123412 item.*.x += 1;
34133413 break :blk 6;
34143414 },
34153415
34163416 // No else is required if the types cases was exhaustively handled
3417 Item.D => 8,
3417 Item.d => 8,
34183418 };
34193419
34203420 assert(b == 6);
3421 assert(a.C.x == 2);
3421 assert(a.c.x == 2);
34223422}
34233423 {#code_end#}
34243424 {#see_also|comptime|enum|@compileError|Compile Variables#}
......@@ -3430,16 +3430,16 @@ test "switch on tagged union" {
34303430 </p>
34313431 {#code_begin|test_err|not handled in switch#}
34323432const Color = enum {
3433 Auto,
3434 Off,
3435 On,
3433 auto,
3434 off,
3435 on,
34363436};
34373437
34383438test "exhaustive switching" {
3439 const color = Color.Off;
3439 const color = Color.off;
34403440 switch (color) {
3441 Color.Auto => {},
3442 Color.On => {},
3441 Color.auto => {},
3442 Color.on => {},
34433443 }
34443444}
34453445 {#code_end#}
......@@ -3455,17 +3455,17 @@ const std = @import("std");
34553455const assert = std.debug.assert;
34563456
34573457const Color = enum {
3458 Auto,
3459 Off,
3460 On,
3458 auto,
3459 off,
3460 on,
34613461};
34623462
34633463test "enum literals with switch" {
3464 const color = Color.Off;
3464 const color = Color.off;
34653465 const result = switch (color) {
3466 .Auto => false,
3467 .On => false,
3468 .Off => true,
3466 .auto => false,
3467 .on => false,
3468 .off => true,
34693469 };
34703470 assert(result);
34713471}
......@@ -5302,25 +5302,25 @@ const std = @import("std");
53025302const assert = std.debug.assert;
53035303
53045304const E = enum {
5305 One,
5306 Two,
5307 Three,
5305 one,
5306 two,
5307 three,
53085308};
53095309
53105310const U = union(E) {
5311 One: i32,
5312 Two: f32,
5313 Three,
5311 one: i32,
5312 two: f32,
5313 three,
53145314};
53155315
53165316test "coercion between unions and enums" {
5317 var u = U{ .Two = 12.34 };
5317 var u = U{ .two = 12.34 };
53185318 var e: E = u;
5319 assert(e == E.Two);
5319 assert(e == E.two);
53205320
5321 const three = E.Three;
5321 const three = E.three;
53225322 var another_u: U = three;
5323 assert(another_u == E.Three);
5323 assert(another_u == E.three);
53245324}
53255325 {#code_end#}
53265326 {#see_also|union|enum#}
......@@ -6096,44 +6096,44 @@ pub fn main() void {
60966096/// Calls print and then flushes the buffer.
60976097pub fn printf(self: *OutStream, comptime format: []const u8, args: anytype) anyerror!void {
60986098 const State = enum {
6099 Start,
6100 OpenBrace,
6101 CloseBrace,
6099 start,
6100 open_brace,
6101 close_brace,
61026102 };
61036103
61046104 comptime var start_index: usize = 0;
6105 comptime var state = State.Start;
6105 comptime var state = State.start;
61066106 comptime var next_arg: usize = 0;
61076107
61086108 inline for (format) |c, i| {
61096109 switch (state) {
6110 State.Start => switch (c) {
6110 State.start => switch (c) {
61116111 '{' => {
61126112 if (start_index < i) try self.write(format[start_index..i]);
6113 state = State.OpenBrace;
6113 state = State.open_brace;
61146114 },
61156115 '}' => {
61166116 if (start_index < i) try self.write(format[start_index..i]);
6117 state = State.CloseBrace;
6117 state = State.close_brace;
61186118 },
61196119 else => {},
61206120 },
6121 State.OpenBrace => switch (c) {
6121 State.open_brace => switch (c) {
61226122 '{' => {
6123 state = State.Start;
6123 state = State.start;
61246124 start_index = i;
61256125 },
61266126 '}' => {
61276127 try self.printValue(args[next_arg]);
61286128 next_arg += 1;
6129 state = State.Start;
6129 state = State.start;
61306130 start_index = i + 1;
61316131 },
61326132 else => @compileError("Unknown format character: " ++ c),
61336133 },
6134 State.CloseBrace => switch (c) {
6134 State.close_brace => switch (c) {
61356135 '}' => {
6136 state = State.Start;
6136 state = State.start;
61376137 start_index = i;
61386138 },
61396139 else => @compileError("Single '}' encountered in format string"),
......@@ -9069,9 +9069,9 @@ pub fn main() void {
90699069 <p>At compile-time:</p>
90709070 {#code_begin|test_err|has no tag matching integer value 3#}
90719071const Foo = enum {
9072 A,
9073 B,
9074 C,
9072 a,
9073 b,
9074 c,
90759075};
90769076comptime {
90779077 const a: u2 = 3;
......@@ -9083,9 +9083,9 @@ comptime {
90839083const std = @import("std");
90849084
90859085const Foo = enum {
9086 A,
9087 B,
9088 C,
9086 a,
9087 b,
9088 c,
90899089};
90909090
90919091pub fn main() void {