authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-04-19 10:38:01-07:00
committergravatar for alex@alexrp.comAlex Rønne Petersen <alex@alexrp.com> 2026-04-20 01:59:20+02:00
logcf0ce50783e327e831559045da4b365bc2a83c87
tree952593613a7c410541ad5974e95542df754f02e9
parentc9a761348c8d702cb2b016fe488f3d086918cf44
signaturebadge-check Signed by SSH key SHA256:7B/LJ7bpR1eX8aCXSr4mtd5M45VMPKcx9zY8e95b5QM

langref: use the word "namespace" instead of "container"

10 files changed, 142 insertions(+), 166 deletions(-)

doc/langref.html.in+49-72
......@@ -388,22 +388,15 @@
388388 </p>
389389 {#see_also|Values|Tuples|@import|Errors|Entry Point|Source Encoding|try#}
390390 {#header_close#}
391
391392 {#header_open|Comments#}
392 <p>
393 Zig supports 3 types of comments. Normal comments are ignored, but doc comments
394 and top-level doc comments are used by the compiler to generate the package documentation.
395 </p>
396 <p>
397 The generated documentation is still experimental, and can be produced with:
398 </p>
399 {#shell_samp#}zig test -femit-docs main.zig{#end_shell_samp#}
393 <p>There are three types of comments. Normal comments are ignored, while {#link|Doc Comments#}
394 and {#link|Top-Level Doc Comments#} are used by the compiler to generate
395 the package documentation.</p>
400396 {#code|comments.zig#}
401397
402 <p>
403 There are no multiline comments in Zig (e.g. like <code class="c">/* */</code>
404 comments in C). This allows Zig to have the property that each line
405 of code can be tokenized out of context.
406 </p>
398 <p>There are no multiline comments. Zig has the property that each line
399 of code can be tokenized independently.</p>
407400 {#header_open|Doc Comments#}
408401 <p>
409402 A doc comment is one that begins with exactly three slashes (i.e.
......@@ -429,17 +422,28 @@
429422 {#header_open|Top-Level Doc Comments#}
430423 <p>
431424 A top-level doc comment is one that begins with two slashes and an exclamation
432 point: {#syntax#}//!{#endsyntax#}; it documents the current source file.
425 point: {#syntax#}//!{#endsyntax#}; it documents the type which owns the containing
426 {#link|Namespace#}.
433427 </p>
434428 <p>
435429 It is a compile error if a top-level doc comment is not placed at the start
436 of a {#link|container|Containers#}, before any expressions.
430 of a namespace, before any expressions.
437431 </p>
438432 {#code|tldoc_comments.zig#}
439433
440434 {#header_close#}
441435 {#header_close#}
442436
437 {#header_open|Namespace#}
438 <p>A namespace in Zig is created by {#link|struct#}, {#link|enum#}, {#link|union#}, and {#link|opaque#}.</p>
439 <p>They contain {#link|Namespace Level Variables#},
440 {#link|function|Functions#} declarations, and {#link|comptime#} blocks.</p>
441 <p>Although namespaces use curly braces to surround their definition,
442 they should not be confused with {#link|blocks|Blocks#} or function bodies.</p>
443 <p><strong>Every Zig source file is implicitly a struct</strong>, with the keyword
444 {#syntax#}struct{#endsyntax#} and curly braces omitted.</p>
445 {#header_close#}
446
443447 {#header_open|Identifiers#}
444448 <p>
445449 Identifiers must start with an alphabetic character or underscore and may be followed
......@@ -813,7 +817,7 @@
813817 {#code|destructuring_to_existing.zig#}
814818
815819 <p>
816 A destructuring expression may only appear within a block (i.e. not at container scope).
820 A destructuring expression may only appear within a block (i.e. not at {#link|Namespace#} scope).
817821 The left hand side of the assignment must consist of a comma separated list,
818822 each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration:
819823 </p>
......@@ -993,27 +997,23 @@
993997 </p>
994998 {#see_also|Exporting a C Library#}
995999
996 {#header_open|Container Level Variables#}
997 <p>
998 {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed.
999 The initialization value of container level variables is implicitly
1000 {#link|comptime#}. If a container level variable is {#syntax#}const{#endsyntax#} then its value is
1001 {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known.
1002 </p>
1003 {#code|test_container_level_variables.zig#}
1004
1005 <p>
1006 Container level variables may be declared inside a {#link|struct#}, {#link|union#}, {#link|enum#}, or {#link|opaque#}:
1007 </p>
1008 {#code|test_namespaced_container_level_variable.zig#}
1000 {#header_open|Namespace Level Variables#}
1001 <p>{#link|Namespace|Namespace#} level variables have global lifetime and are
1002 order-independent and lazily analyzed. The initialization value of
1003 namespace level variables is implicitly {#link|comptime#}. If a namespace
1004 level variable is {#syntax#}const{#endsyntax#} then its value is
1005 {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known.</p>
1006 {#code|test_namespace_level_variables.zig#}
1007 <p>Namespace level variables may be declared inside a {#link|struct#},
1008 {#link|union#}, {#link|enum#}, or {#link|opaque#}:</p>
1009 {#code|test_namespaced_variable.zig#}
10091010
10101011 {#header_close#}
10111012
1012 {#header_open|Static Local Variables#}
1013 <p>
1014 It is also possible to have local variables with static lifetime by using containers inside functions.
1015 </p>
1016 {#code|test_static_local_variable.zig#}
1013 {#header_open|Locally-Scoped Global Variables#}
1014 <p>It is also possible to have local variables with global lifetime by
1015 using {#link|namespaces|Namespace#} inside functions.</p>
1016 {#code|test_locally_scoped_global_variable.zig#}
10171017
10181018 {#header_close#}
10191019
......@@ -1022,10 +1022,8 @@
10221022 {#syntax#}threadlocal{#endsyntax#} keyword,
10231023 which makes each thread work with a separate instance of the variable:</p>
10241024 {#code|test_thread_local_variables.zig#}
1025
1026 <p>
1027 For {#link|Single Threaded Builds#}, all thread local variables are treated as regular {#link|Container Level Variables#}.
1028 </p>
1025 <p>For {#link|Single Threaded Builds#}, all thread local variables are
1026 treated as regular {#link|Namespace Level Variables#}.</p>
10291027 <p>
10301028 Thread local variables may not be {#syntax#}const{#endsyntax#}.
10311029 </p>
......@@ -4124,13 +4122,11 @@ fn performFn(start_value: i32) i32 {
41244122 </p>
41254123 {#code|test_fibonacci_comptime_unreachable.zig#}
41264124
4127
4128 <p>
4129 At {#link|container|Containers#} level (outside of any function), all expressions are implicitly
4130 {#syntax#}comptime{#endsyntax#} expressions. This means that we can use functions to
4131 initialize complex static data. For example:
4132 </p>
4133 {#code|test_container-level_comptime_expressions.zig#}
4125 <p>At {#link|Namespace#} level (outside of any function), all expressions
4126 are implicitly {#syntax#}comptime{#endsyntax#} expressions. This means
4127 that we can use functions to initialize complex constant data. For
4128 example:</p>
4129 {#code|test_namespace-level_comptime_expressions.zig#}
41344130
41354131 <p>
41364132 When we compile this program, Zig generates the constants
......@@ -4310,7 +4306,7 @@ pub fn print(self: *Writer, arg0: []const u8, arg1: i32) !void {
43104306
43114307 {#header_open|Global Assembly#}
43124308 <p>
4313 When an assembly expression occurs in a {#link|container|Containers#} level {#link|comptime#} block, this is
4309 When an assembly expression occurs in a {#link|Namespace#} level {#link|comptime#} block, this is
43144310 <strong>global assembly</strong>.
43154311 </p>
43164312 <p>
......@@ -5015,25 +5011,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
50155011 {#header_close#}
50165012
50175013 {#header_open|@hasDecl#}
5018 <pre>{#syntax#}@hasDecl(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}</pre>
5019 <p>
5020 Returns whether or not a {#link|container|Containers#} has a declaration
5021 matching {#syntax#}name{#endsyntax#}.
5022 </p>
5014 <pre>{#syntax#}@hasDecl(comptime Namespace: type, comptime name: []const u8) bool{#endsyntax#}</pre>
5015 <p>Returns whether or not a {#link|Namespace#} has a declaration matching {#syntax#}name{#endsyntax#}.</p>
50235016 {#code|test_hasDecl_builtin.zig#}
50245017
50255018 {#see_also|@hasField#}
50265019 {#header_close#}
50275020
50285021 {#header_open|@hasField#}
5029 <pre>{#syntax#}@hasField(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}</pre>
5022 <pre>{#syntax#}@hasField(comptime T: type, comptime name: []const u8) bool{#endsyntax#}</pre>
50305023 <p>Returns whether the field name of a struct, union, or enum exists.</p>
5031 <p>
5032 The result is a compile time constant.
5033 </p>
5034 <p>
5035 It does not include functions, variables, or constants.
5036 </p>
5024 <p>The result is a compile time constant.</p>
5025 <p>It does not include functions, variables, or constants.</p>
50375026 {#see_also|@hasDecl#}
50385027 {#header_close#}
50395028
......@@ -6049,7 +6038,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
60496038 {#header_open|Single Threaded Builds#}
60506039 <p>Zig has a compile option <kbd>-fsingle-threaded</kbd> which has the following effects:</p>
60516040 <ul>
6052 <li>All {#link|Thread Local Variables#} are treated as regular {#link|Container Level Variables#}.</li>
6041 <li>All {#link|Thread Local Variables#} are treated as regular {#link|Namespace Level Variables#}.</li>
60536042 <li>The overhead of {#link|Async Functions#} becomes equivalent to function call overhead.</li>
60546043 <li>The {#syntax#}@import("builtin").single_threaded{#endsyntax#} becomes {#syntax#}true{#endsyntax#}
60556044 and therefore various userland APIs which read this variable become more efficient.
......@@ -6704,7 +6693,7 @@ const builtin = @import("builtin");
67046693 {#header_open|Panic Handler#}
67056694 <p>
67066695 The Zig Standard Library looks for a declaration named {#syntax#}panic{#endsyntax#} in the root module's
6707 root source file. If present, it is expected to be a namespace (container type) with declarations
6696 root source file. If present, it is expected to be a {#link|Namespace#} with declarations
67086697 providing different panic handlers.
67096698 </p>
67106699 <p>
......@@ -7916,18 +7905,6 @@ fn readU32Be() u32 {}
79167905 {#header_close#}
79177906
79187907 {#header_open|Appendix#}
7919 {#header_open|Containers#}
7920 <p>
7921 A <em>container</em> in Zig is any syntactical construct that acts as a namespace to hold {#link|variable|Container Level Variables#} and {#link|function|Functions#} declarations.
7922 Containers are also type definitions which can be instantiated.
7923 {#link|Structs|struct#}, {#link|enums|enum#}, {#link|unions|union#}, {#link|opaques|opaque#}, and even Zig source files themselves are containers.
7924 </p>
7925 <p>
7926 Although containers (except Zig source files) use curly braces to surround their definition, they should not be confused with {#link|blocks|Blocks#} or functions.
7927 Containers do not contain statements.
7928 </p>
7929 {#header_close#}
7930
79317908 {#header_open|Grammar#}
79327909 {#syntax_block|peg|grammar.peg#}
79337910Root <- skip ContainerMembers eof
doc/langref/test_container-level_comptime_expressions.zig deleted-37
......@@ -1,37 +0,0 @@
1const first_25_primes = firstNPrimes(25);
2const sum_of_first_25_primes = sum(&first_25_primes);
3
4fn firstNPrimes(comptime n: usize) [n]i32 {
5 var prime_list: [n]i32 = undefined;
6 var next_index: usize = 0;
7 var test_number: i32 = 2;
8 while (next_index < prime_list.len) : (test_number += 1) {
9 var test_prime_index: usize = 0;
10 var is_prime = true;
11 while (test_prime_index < next_index) : (test_prime_index += 1) {
12 if (test_number % prime_list[test_prime_index] == 0) {
13 is_prime = false;
14 break;
15 }
16 }
17 if (is_prime) {
18 prime_list[next_index] = test_number;
19 next_index += 1;
20 }
21 }
22 return prime_list;
23}
24
25fn sum(numbers: []const i32) i32 {
26 var result: i32 = 0;
27 for (numbers) |x| {
28 result += x;
29 }
30 return result;
31}
32
33test "variable values" {
34 try @import("std").testing.expectEqual(1060, sum_of_first_25_primes);
35}
36
37// test
doc/langref/test_container_level_variables.zig deleted-16
......@@ -1,16 +0,0 @@
1var y: i32 = add(10, x);
2const x: i32 = add(12, 34);
3
4test "container level variables" {
5 try expectEqual(46, x);
6 try expectEqual(56, y);
7}
8
9fn add(a: i32, b: i32) i32 {
10 return a + b;
11}
12
13const std = @import("std");
14const expectEqual = std.testing.expectEqual;
15
16// test
doc/langref/test_locally_scoped_global_variable.zig created+17
......@@ -0,0 +1,17 @@
1const std = @import("std");
2const expectEqual = std.testing.expectEqual;
3
4test "static local variable" {
5 try expectEqual(1235, foo());
6 try expectEqual(1236, foo());
7}
8
9fn foo() i32 {
10 const S = struct {
11 var x: i32 = 1234;
12 };
13 S.x += 1;
14 return S.x;
15}
16
17// test
doc/langref/test_namespace-level_comptime_expressions.zig created+37
......@@ -0,0 +1,37 @@
1const first_25_primes = firstNPrimes(25);
2const sum_of_first_25_primes = sum(&first_25_primes);
3
4fn firstNPrimes(comptime n: usize) [n]i32 {
5 var prime_list: [n]i32 = undefined;
6 var next_index: usize = 0;
7 var test_number: i32 = 2;
8 while (next_index < prime_list.len) : (test_number += 1) {
9 var test_prime_index: usize = 0;
10 var is_prime = true;
11 while (test_prime_index < next_index) : (test_prime_index += 1) {
12 if (test_number % prime_list[test_prime_index] == 0) {
13 is_prime = false;
14 break;
15 }
16 }
17 if (is_prime) {
18 prime_list[next_index] = test_number;
19 next_index += 1;
20 }
21 }
22 return prime_list;
23}
24
25fn sum(numbers: []const i32) i32 {
26 var result: i32 = 0;
27 for (numbers) |x| {
28 result += x;
29 }
30 return result;
31}
32
33test "variable values" {
34 try @import("std").testing.expectEqual(1060, sum_of_first_25_primes);
35}
36
37// test
doc/langref/test_namespace_level_variables.zig created+16
......@@ -0,0 +1,16 @@
1var y: i32 = add(10, x);
2const x: i32 = add(12, 34);
3
4test "container level variables" {
5 try expectEqual(46, x);
6 try expectEqual(56, y);
7}
8
9fn add(a: i32, b: i32) i32 {
10 return a + b;
11}
12
13const std = @import("std");
14const expectEqual = std.testing.expectEqual;
15
16// test
doc/langref/test_namespaced_container_level_variable.zig deleted-18
......@@ -1,18 +0,0 @@
1const std = @import("std");
2const expectEqual = std.testing.expectEqual;
3
4test "namespaced container level variable" {
5 try expectEqual(1235, foo());
6 try expectEqual(1236, foo());
7}
8
9const S = struct {
10 var x: i32 = 1234;
11};
12
13fn foo() i32 {
14 S.x += 1;
15 return S.x;
16}
17
18// test
doc/langref/test_namespaced_variable.zig created+18
......@@ -0,0 +1,18 @@
1const std = @import("std");
2const expectEqual = std.testing.expectEqual;
3
4test "namespaced container level variable" {
5 try expectEqual(1235, foo());
6 try expectEqual(1236, foo());
7}
8
9const S = struct {
10 var x: i32 = 1234;
11};
12
13fn foo() i32 {
14 S.x += 1;
15 return S.x;
16}
17
18// test
doc/langref/test_static_local_variable.zig deleted-17
......@@ -1,17 +0,0 @@
1const std = @import("std");
2const expectEqual = std.testing.expectEqual;
3
4test "static local variable" {
5 try expectEqual(1235, foo());
6 try expectEqual(1236, foo());
7}
8
9fn foo() i32 {
10 const S = struct {
11 var x: i32 = 1234;
12 };
13 S.x += 1;
14 return S.x;
15}
16
17// test
doc/langref/tldoc_comments.zig+5-6
......@@ -1,11 +1,10 @@
1//! This module provides functions for retrieving the current date and
2//! time with varying degrees of precision and accuracy. It does not
3//! depend on libc, but will use functions from it if available.
1//! Provides functions for retrieving the current date and time with varying
2//! degrees of precision and accuracy.
43
54const S = struct {
6 //! Top level comments are allowed inside containers other than source
7 //! files, but it is not very useful. Currently, when producing the package
8 //! documentation, these comments are ignored.
5 //! Top level comments are allowed inside namespaces other than the
6 //! implicit struct created by files, but it is not very useful. Currently,
7 //! when producing the package documentation, these comments are ignored.
98};
109
1110// syntax