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 {...@@ -684,7 +684,7 @@ pub fn main() void {
684 {#header_close#}684 {#header_close#}
685 {#header_open|String Literals and Unicode Code Point Literals#}685 {#header_open|String Literals and Unicode Code Point Literals#}
686 <p>686 <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.
688 The type of string literals encodes both the length, and the fact that they are null-terminated,688 The type of string literals encodes both the length, and the fact that they are null-terminated,
689 and thus they can be {#link|coerced|Type Coercion#} to both {#link|Slices#} and689 and thus they can be {#link|coerced|Type Coercion#} to both {#link|Slices#} and
690 {#link|Null-Terminated Pointers|Sentinel-Terminated Pointers#}.690 {#link|Null-Terminated Pointers|Sentinel-Terminated Pointers#}.
...@@ -1783,7 +1783,7 @@ comptime {...@@ -1783,7 +1783,7 @@ comptime {
1783 expect(message.len == 5);1783 expect(message.len == 5);
1784}1784}
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.
1787const same_message = "hello";1787const same_message = "hello";
17881788
1789comptime {1789comptime {
...@@ -1989,15 +1989,15 @@ test "null terminated array" {...@@ -1989,15 +1989,15 @@ test "null terminated array" {
19891989
1990 {#header_open|Pointers#}1990 {#header_open|Pointers#}
1991 <p>1991 <p>
1992 Zig has two kinds of pointers:1992 Zig has two kinds of pointers: single-item and many-item.
1993 </p>1993 </p>
1994 <ul>1994 <ul>
1995 <li>{#syntax#}*T{#endsyntax#} - pointer to exactly one item.1995 <li>{#syntax#}*T{#endsyntax#} - single-item pointer to exactly one item.
1996 <ul>1996 <ul>
1997 <li>Supports deref syntax: {#syntax#}ptr.*{#endsyntax#}</li>1997 <li>Supports deref syntax: {#syntax#}ptr.*{#endsyntax#}</li>
1998 </ul>1998 </ul>
1999 </li>1999 </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.
2001 <ul>2001 <ul>
2002 <li>Supports index syntax: {#syntax#}ptr[i]{#endsyntax#}</li>2002 <li>Supports index syntax: {#syntax#}ptr[i]{#endsyntax#}</li>
2003 <li>Supports slice syntax: {#syntax#}ptr[start..end]{#endsyntax#}</li>2003 <li>Supports slice syntax: {#syntax#}ptr[start..end]{#endsyntax#}</li>
...@@ -2009,7 +2009,7 @@ test "null terminated array" {...@@ -2009,7 +2009,7 @@ test "null terminated array" {
2009 </ul>2009 </ul>
2010 <p>These types are closely related to {#link|Arrays#} and {#link|Slices#}:</p>2010 <p>These types are closely related to {#link|Arrays#} and {#link|Slices#}:</p>
2011 <ul>2011 <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.
2013 <ul>2013 <ul>
2014 <li>Supports index syntax: {#syntax#}array_ptr[i]{#endsyntax#}</li>2014 <li>Supports index syntax: {#syntax#}array_ptr[i]{#endsyntax#}</li>
2015 <li>Supports slice syntax: {#syntax#}array_ptr[start..end]{#endsyntax#}</li>2015 <li>Supports slice syntax: {#syntax#}array_ptr[start..end]{#endsyntax#}</li>
...@@ -2038,7 +2038,7 @@ test "address of syntax" {...@@ -2038,7 +2038,7 @@ test "address of syntax" {
2038 // Dereference a pointer:2038 // Dereference a pointer:
2039 expect(x_ptr.* == 1234);2039 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.
2042 expect(@TypeOf(x_ptr) == *const i32);2042 expect(@TypeOf(x_ptr) == *const i32);
20432043
2044 // If you want to mutate the value, you'd need an address of a mutable variable:2044 // If you want to mutate the value, you'd need an address of a mutable variable:
...@@ -2051,7 +2051,7 @@ test "address of syntax" {...@@ -2051,7 +2051,7 @@ test "address of syntax" {
20512051
2052test "pointer array access" {2052test "pointer array access" {
2053 // Taking an address of an individual element gives a2053 // Taking an address of an individual element gives a
2054 // pointer to a single item. This kind of pointer2054 // single-item pointer. This kind of pointer
2055 // does not support pointer arithmetic.2055 // does not support pointer arithmetic.
2056 var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };2056 var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
2057 const ptr = &array[2];2057 const ptr = &array[2];
...@@ -2320,8 +2320,8 @@ test "basic slices" {...@@ -2320,8 +2320,8 @@ test "basic slices" {
2320 expect(&slice[0] == &array[0]);2320 expect(&slice[0] == &array[0]);
2321 expect(slice.len == array.len);2321 expect(slice.len == array.len);
23222322
2323 // Using the address-of operator on a slice gives a pointer to a single2323 // Using the address-of operator on a slice gives a single-item pointer,
2324 // item, while using the `ptr` field gives an unknown length pointer.2324 // while using the `ptr` field gives a many-item pointer.
2325 expect(@TypeOf(slice.ptr) == [*]i32);2325 expect(@TypeOf(slice.ptr) == [*]i32);
2326 expect(@TypeOf(&slice[0]) == *i32);2326 expect(@TypeOf(&slice[0]) == *i32);
2327 expect(@ptrToInt(slice.ptr) == @ptrToInt(&slice[0]));2327 expect(@ptrToInt(slice.ptr) == @ptrToInt(&slice[0]));
...@@ -5244,8 +5244,7 @@ test "*[N]T to []T" {...@@ -5244,8 +5244,7 @@ test "*[N]T to []T" {
5244 expect(std.mem.eql(f32, x2, &[2]f32{ 1.2, 3.4 }));5244 expect(std.mem.eql(f32, x2, &[2]f32{ 1.2, 3.4 }));
5245}5245}
52465246
5247// Single-item pointers to arrays can be coerced to5247// Single-item pointers to arrays can be coerced to many-item pointers.
5248// unknown length pointers.
5249test "*[N]T to [*]T" {5248test "*[N]T to [*]T" {
5250 var buf: [5]u8 = "hello".*;5249 var buf: [5]u8 = "hello".*;
5251 const x: [*]u8 = &buf;5250 const x: [*]u8 = &buf;
...@@ -9853,7 +9852,7 @@ const c = @cImport({...@@ -9853,7 +9852,7 @@ const c = @cImport({
9853 </p>9852 </p>
9854 <p>9853 <p>
9855 When importing C header files, it is ambiguous whether pointers should be translated as9854 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#}).
9857 C pointers are a compromise so that Zig code can utilize translated header files directly.9856 C pointers are a compromise so that Zig code can utilize translated header files directly.
9858 </p>9857 </p>
9859 <p>{#syntax#}[*c]T{#endsyntax#} - C pointer.</p>9858 <p>{#syntax#}[*c]T{#endsyntax#} - C pointer.</p>