From 1da05eb0cebed9595ee0d326d9bd67edd046af0d Mon Sep 17 00:00:00 2001 From: Matthew Dempsky Date: Wed, 21 Apr 2021 00:12:02 -0700 Subject: [PATCH] spec: add unsafe.Add and unsafe.Slice Updates #19367. Updates #40481. Change-Id: I578066ad68d2cd6bea50df1a534cf799e4404a7f Reviewed-on: https://go-review.googlesource.com/c/go/+/312212 Trust: Matthew Dempsky Trust: Robert Griesemer Reviewed-by: Ian Lance Taylor Reviewed-by: Rob Pike Reviewed-by: Robert Griesemer Reviewed-by: Russ Cox --- doc/go_spec.html | 32 +++++++++++++++++++++++++++++++- src/unsafe/unsafe.go | 23 +++++++++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index 13b8beb06c9..bbcdd54b027 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ @@ -6711,6 +6711,10 @@ type Pointer *ArbitraryType func Alignof(variable ArbitraryType) uintptr func Offsetof(selector ArbitraryType) uintptr func Sizeof(variable ArbitraryType) uintptr + +type IntegerType int // shorthand for an integer type; it is not a real type +func Add(ptr Pointer, len IntegerType) Pointer +func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType

@@ -6767,6 +6771,32 @@ Calls to Alignof, Offsetof, and Sizeof are compile-time constant expressions of type uintptr.

+

+The function Add adds len to ptr +and returns the updated pointer unsafe.Pointer(uintptr(ptr) + uintptr(len)). +The len argument must be of integer type or an untyped constant. +A constant len argument must be representable by a value of type int; +if it is an untyped constant it is given type int. +The rules for valid uses of Pointer still apply. +

+ +

+The function Slice returns a slice whose underlying array starts at ptr +and whose length and capacity are len: +

+ +
+(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
+
+ +

+The len argument must be of integer type or an untyped constant. +A constant len argument must be non-negative and representable by a value of type int; +if it is an untyped constant it is given type int. +If ptr is nil or len is negative at run time, +a run-time panic occurs. +

+

Size and alignment guarantees

diff --git a/src/unsafe/unsafe.go b/src/unsafe/unsafe.go index 272761d9363..ecbd28c523e 100644 --- a/src/unsafe/unsafe.go +++ b/src/unsafe/unsafe.go @@ -14,6 +14,10 @@ package unsafe // part of the unsafe package. It represents the type of an arbitrary Go expression. type ArbitraryType int +// IntegerType is here for the purposes of documentation only and is not actually +// part of the unsafe package. It represents any arbitrary integer type. +type IntegerType int + // Pointer represents a pointer to an arbitrary type. There are four special operations // available for type Pointer that are not available for other types: // - A pointer value of any type can be converted to a Pointer. @@ -203,3 +207,22 @@ func Offsetof(x ArbitraryType) uintptr // value returned by reflect.TypeOf(s.f).FieldAlign(). // The return value of Alignof is a Go constant. func Alignof(x ArbitraryType) uintptr + +// The function Add adds len to ptr and returns the updated pointer +// Pointer(uintptr(ptr) + uintptr(len)). +// The len argument must be of integer type or an untyped constant. +// A constant len argument must be representable by a value of type int; +// if it is an untyped constant it is given type int. +// The rules for valid uses of Pointer still apply. +func Add(ptr Pointer, len IntegerType) Pointer + +// The function Slice returns a slice whose underlying array starts at ptr +// and whose length and capacity are len: +// +// (*[len]ArbitraryType)(unsafe.Pointer(ptr))[:] +// +// The len argument must be of integer type or an untyped constant. +// A constant len argument must be non-negative and representable by a value of type int; +// if it is an untyped constant it is given type int. +// If ptr is nil or len is negative at run time, a run-time panic occurs. +func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType