authorgravatar for ratfactor@gmail.comDave Gauer <ratfactor@gmail.com> 2021-03-12 20:10:55-05:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2021-03-12 20:10:55-05:00
log95eb711ca8c0843ede117f61025c5eda0102f845
treea69f424ca311f21e6119b97bf2f0ccbc9a839e2b
parent8ebb18d9da0bfbe6a974636fd36e3391d1de253b
signaturebadge-question-mark Signed by PGP key 4AEE18F83AFDEB23

langref: Use "single-item pointer" and "many-item pointer" (#8217)

These terms give short, descriptive names for the two pointer types which reflect the names used in src/type.zig.

1 files changed, 12 insertions(+), 13 deletions(-)

doc/langref.html.in+12-13
......@@ -684,7 +684,7 @@ pub fn main() void {
684684 {#header_close#}
685685 {#header_open|String Literals and Unicode Code Point Literals#}
686686 <p>
687 String literals are single-item constant {#link|Pointers#} to null-terminated byte arrays.
687 String literals are constant single-item {#link|Pointers#} to null-terminated byte arrays.
688688 The type of string literals encodes both the length, and the fact that they are null-terminated,
689689 and thus they can be {#link|coerced|Type Coercion#} to both {#link|Slices#} and
690690 {#link|Null-Terminated Pointers|Sentinel-Terminated Pointers#}.
......@@ -1783,7 +1783,7 @@ comptime {
17831783 expect(message.len == 5);
17841784}
17851785
1786// A string literal is a pointer to an array literal.
1786// A string literal is a single-item pointer to an array literal.
17871787const same_message = "hello";
17881788
17891789comptime {
......@@ -1989,15 +1989,15 @@ test "null terminated array" {
19891989
19901990 {#header_open|Pointers#}
19911991 <p>
1992 Zig has two kinds of pointers:
1992 Zig has two kinds of pointers: single-item and many-item.
19931993 </p>
19941994 <ul>
1995 <li>{#syntax#}*T{#endsyntax#} - pointer to exactly one item.
1995 <li>{#syntax#}*T{#endsyntax#} - single-item pointer to exactly one item.
19961996 <ul>
19971997 <li>Supports deref syntax: {#syntax#}ptr.*{#endsyntax#}</li>
19981998 </ul>
19991999 </li>
2000 <li>{#syntax#}[*]T{#endsyntax#} - pointer to unknown number of items.
2000 <li>{#syntax#}[*]T{#endsyntax#} - many-item pointer to unknown number of items.
20012001 <ul>
20022002 <li>Supports index syntax: {#syntax#}ptr[i]{#endsyntax#}</li>
20032003 <li>Supports slice syntax: {#syntax#}ptr[start..end]{#endsyntax#}</li>
......@@ -2009,7 +2009,7 @@ test "null terminated array" {
20092009 </ul>
20102010 <p>These types are closely related to {#link|Arrays#} and {#link|Slices#}:</p>
20112011 <ul>
2012 <li>{#syntax#}*[N]T{#endsyntax#} - pointer to N items, same as single-item pointer to array.
2012 <li>{#syntax#}*[N]T{#endsyntax#} - pointer to N items, same as single-item pointer to an array.
20132013 <ul>
20142014 <li>Supports index syntax: {#syntax#}array_ptr[i]{#endsyntax#}</li>
20152015 <li>Supports slice syntax: {#syntax#}array_ptr[start..end]{#endsyntax#}</li>
......@@ -2038,7 +2038,7 @@ test "address of syntax" {
20382038 // Dereference a pointer:
20392039 expect(x_ptr.* == 1234);
20402040
2041 // When you get the address of a const variable, you get a const pointer to a single item.
2041 // When you get the address of a const variable, you get a const single-item pointer.
20422042 expect(@TypeOf(x_ptr) == *const i32);
20432043
20442044 // If you want to mutate the value, you'd need an address of a mutable variable:
......@@ -2051,7 +2051,7 @@ test "address of syntax" {
20512051
20522052test "pointer array access" {
20532053 // Taking an address of an individual element gives a
2054 // pointer to a single item. This kind of pointer
2054 // single-item pointer. This kind of pointer
20552055 // does not support pointer arithmetic.
20562056 var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
20572057 const ptr = &array[2];
......@@ -2320,8 +2320,8 @@ test "basic slices" {
23202320 expect(&slice[0] == &array[0]);
23212321 expect(slice.len == array.len);
23222322
2323 // Using the address-of operator on a slice gives a pointer to a single
2324 // item, while using the `ptr` field gives an unknown length pointer.
2323 // Using the address-of operator on a slice gives a single-item pointer,
2324 // while using the `ptr` field gives a many-item pointer.
23252325 expect(@TypeOf(slice.ptr) == [*]i32);
23262326 expect(@TypeOf(&slice[0]) == *i32);
23272327 expect(@ptrToInt(slice.ptr) == @ptrToInt(&slice[0]));
......@@ -5244,8 +5244,7 @@ test "*[N]T to []T" {
52445244 expect(std.mem.eql(f32, x2, &[2]f32{ 1.2, 3.4 }));
52455245}
52465246
5247// Single-item pointers to arrays can be coerced to
5248// unknown length pointers.
5247// Single-item pointers to arrays can be coerced to many-item pointers.
52495248test "*[N]T to [*]T" {
52505249 var buf: [5]u8 = "hello".*;
52515250 const x: [*]u8 = &buf;
......@@ -9853,7 +9852,7 @@ const c = @cImport({
98539852 </p>
98549853 <p>
98559854 When importing C header files, it is ambiguous whether pointers should be translated as
9856 single-item pointers ({#syntax#}*T{#endsyntax#}) or unknown-length pointers ({#syntax#}[*]T{#endsyntax#}).
9855 single-item pointers ({#syntax#}*T{#endsyntax#}) or many-item pointers ({#syntax#}[*]T{#endsyntax#}).
98579856 C pointers are a compromise so that Zig code can utilize translated header files directly.
98589857 </p>
98599858 <p>{#syntax#}[*c]T{#endsyntax#} - C pointer.</p>