feat(pkg): add ptr package handle pointers

Author: colin404

.todo.md

@@ -35,6 +35,7 @@
 [?] onex-apiserver 后端对接 ES
 [?] 诊断平台
 [?] GraphQL API
+[?] 添加状态机
 ---
 
 [?] 创建一个项目开发者社区网站 + 群？？？

pkg/ptr/README.md

@@ -0,0 +1,3 @@
+# Pointer
+
+This package provides some functions for pointer-based operations.

pkg/ptr/doc.go

@@ -0,0 +1,3 @@
+// Package gptr provides generic operations for pointers.
+
+package ptr

pkg/ptr/ptr.go

@@ -0,0 +1,146 @@
+/*
+Copyright 2023 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package ptr
+
+import (
+	"fmt"
+	"reflect"
+)
+
+// AllPtrFieldsNil tests whether all pointer fields in a struct are nil.  This is useful when,
+// for example, an API struct is handled by plugins which need to distinguish
+// "no plugin accepted this spec" from "this spec is empty".
+//
+// This function is only valid for structs and pointers to structs.  Any other
+// type will cause a panic.  Passing a typed nil pointer will return true.
+func AllPtrFieldsNil(obj interface{}) bool {
+	v := reflect.ValueOf(obj)
+	if !v.IsValid() {
+		panic(fmt.Sprintf("reflect.ValueOf() produced a non-valid Value for %#v", obj))
+	}
+	if v.Kind() == reflect.Ptr {
+		if v.IsNil() {
+			return true
+		}
+		v = v.Elem()
+	}
+	for i := 0; i < v.NumField(); i++ {
+		if v.Field(i).Kind() == reflect.Ptr && !v.Field(i).IsNil() {
+			return false
+		}
+	}
+	return true
+}
+
+// To returns a pointer to the given value.
+func To[T any](v T) *T {
+	return &v
+}
+
+// From returns the value pointed to by the pointer p.
+// If the pointer is nil, returns the zero value of T instead.
+func From[T any](v *T) T {
+	var zero T
+	if v != nil {
+		return *v
+	}
+
+	return zero
+}
+
+// FromOr dereferences ptr and returns the value it points to if no nil, or else
+// returns def.
+func FromOr[T any](ptr *T, def T) T {
+	if ptr != nil {
+		return *ptr
+	}
+	return def
+}
+
+// IsNil returns whether the given pointer v is nil.
+func IsNil[T any](p *T) bool {
+	return p == nil
+}
+
+// IsNotNil is negation of [IsNil].
+func IsNotNil[T any](p *T) bool {
+	return p != nil
+}
+
+// Clone returns a shallow copy of the slice.
+// If the given pointer is nil, nil is returned.
+//
+// HINT: The element is copied using assignment (=), so this is a shallow clone.
+// If you want to do a deep clone, use [CloneBy] with an appropriate element
+// clone function.
+//
+// AKA: Copy
+func Clone[T any](p *T) *T {
+	if p == nil {
+		return nil
+	}
+	clone := *p
+	return &clone
+}
+
+// CloneBy is variant of [Clone], it returns a copy of the map.
+// Element is copied using function f.
+// If the given pointer is nil, nil is returned.
+func CloneBy[T any](p *T, f func(T) T) *T {
+	return Map(p, f)
+}
+
+// Equal returns true if both arguments are nil or both arguments
+// dereference to the same value.
+func Equal[T comparable](a, b *T) bool {
+	if (a == nil) != (b == nil) {
+		return false
+	}
+	if a == nil {
+		return true
+	}
+	return *a == *b
+}
+
+// EqualTo returns whether the value of pointer p is equal to value v.
+// It a shortcut of "x != nil && *x == y".
+//
+// EXAMPLE:
+//
+//	x, y := 1, 2
+//	Equal(&x, 1)   ⏩  true
+//	Equal(&y, 1)   ⏩n false
+//	Equal(nil, 1)  ⏩  false
+func EqualTo[T comparable](p *T, v T) bool {
+	return p != nil && *p == v
+}
+
+// Map applies function f to element of pointer p.
+// If p is nil, f will not be called and nil is returned, otherwise,
+// result of f are returned as a new pointer.
+//
+// EXAMPLE:
+//
+//	i := 1
+//	Map(&i, strconv.Itoa)       ⏩  (*string)("1")
+//	Map[int](nil, strconv.Itoa) ⏩  (*string)(nil)
+func Map[F, T any](p *F, f func(F) T) *T {
+	if p == nil {
+		return nil
+	}
+	return To(f(*p))
+}

pkg/ptr/ptr_test.go

@@ -0,0 +1,184 @@
+/*
+Copyright 2023 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package ptr
+
+import (
+	"fmt"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAllPtrFieldsNil(t *testing.T) {
+	testCases := []struct {
+		obj      interface{}
+		expected bool
+	}{
+		{struct{}{}, true},
+		{struct{ Foo int }{12345}, true},
+		{&struct{ Foo int }{12345}, true},
+		{struct{ Foo *int }{nil}, true},
+		{&struct{ Foo *int }{nil}, true},
+		{struct {
+			Foo int
+			Bar *int
+		}{12345, nil}, true},
+		{&struct {
+			Foo int
+			Bar *int
+		}{12345, nil}, true},
+		{struct {
+			Foo *int
+			Bar *int
+		}{nil, nil}, true},
+		{&struct {
+			Foo *int
+			Bar *int
+		}{nil, nil}, true},
+		{struct{ Foo *int }{new(int)}, false},
+		{&struct{ Foo *int }{new(int)}, false},
+		{struct {
+			Foo *int
+			Bar *int
+		}{nil, new(int)}, false},
+		{&struct {
+			Foo *int
+			Bar *int
+		}{nil, new(int)}, false},
+		{(*struct{})(nil), true},
+	}
+	for i, tc := range testCases {
+		name := fmt.Sprintf("case[%d]", i)
+		t.Run(name, func(t *testing.T) {
+			if actual := AllPtrFieldsNil(tc.obj); actual != tc.expected {
+				t.Errorf("%s: expected %t, got %t", name, tc.expected, actual)
+			}
+		})
+	}
+}
+
+func TestRef(t *testing.T) {
+	type T int
+
+	val := T(0)
+	pointer := To(val)
+	if *pointer != val {
+		t.Errorf("expected %d, got %d", val, *pointer)
+	}
+
+	val = T(1)
+	pointer = To(val)
+	if *pointer != val {
+		t.Errorf("expected %d, got %d", val, *pointer)
+	}
+}
+
+func TestFrom(t *testing.T) {
+	assert.Equal(t, 543, From(To(543)))
+	assert.Equal(t, "Alice", From(To("Alice")))
+	assert.Zero(t, From[int](nil))
+	assert.Nil(t, From[interface{}](nil))
+	assert.Nil(t, From(To[fmt.Stringer](nil)))
+}
+
+func TestFromOr(t *testing.T) {
+	type T int
+
+	var val, def T = 1, 0
+
+	out := FromOr(&val, def)
+	if out != val {
+		t.Errorf("expected %d, got %d", val, out)
+	}
+
+	out = FromOr(nil, def)
+	if out != def {
+		t.Errorf("expected %d, got %d", def, out)
+	}
+}
+
+func TestIsNil(t *testing.T) {
+	assert.False(t, IsNil(To(1)))
+	assert.True(t, IsNil[int](nil))
+}
+
+func TestClone(t *testing.T) {
+	assert.True(t, IsNil(Clone(((*int)(nil)))))
+
+	v := 1
+	assert.True(t, Clone(&v) != &v)
+	assert.True(t, Equal(Clone(&v), &v))
+
+	src := To(1)
+	dst := Clone(&src)
+	assert.Equal(t, &src, dst)
+	assert.True(t, src == *dst)
+}
+
+func TestCloneBy(t *testing.T) {
+	assert.True(t, IsNil(CloneBy(((**int)(nil)), Clone[int])))
+
+	src := To(1)
+	dst := CloneBy(&src, Clone[int])
+	assert.Equal(t, &src, dst)
+	assert.False(t, src == *dst)
+}
+
+func TestEqual(t *testing.T) {
+	type T int
+
+	if !Equal[T](nil, nil) {
+		t.Errorf("expected true (nil == nil)")
+	}
+	if !Equal(To(T(123)), To(T(123))) {
+		t.Errorf("expected true (val == val)")
+	}
+	if Equal(nil, To(T(123))) {
+		t.Errorf("expected false (nil != val)")
+	}
+	if Equal(To(T(123)), nil) {
+		t.Errorf("expected false (val != nil)")
+	}
+	if Equal(To(T(123)), To(T(456))) {
+		t.Errorf("expected false (val != val)")
+	}
+}
+
+func TestEqualTo(t *testing.T) {
+	assert.True(t, EqualTo(To(1), 1))
+	assert.False(t, EqualTo(To(2), 1))
+	assert.False(t, EqualTo(nil, 0))
+}
+
+func TestMap(t *testing.T) {
+	i := 1
+	assert.Equal(t, To("1"), Map(&i, strconv.Itoa))
+	assert.True(t, Map(nil, strconv.Itoa) == nil)
+
+	assert.NotPanics(t, func() {
+		_ = Map(nil, func(int) string {
+			panic("Q_Q")
+		})
+	})
+
+	assert.Panics(t, func() {
+		_ = Map(&i, func(int) string {
+			panic("Q_Q")
+		})
+	})
+}