gcvctor

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 17 Imported by: 1

Documentation

Overview

Package gcvctor constructs cloud.google.com/go/spanner.GenericColumnValue values from Go values and explicit cloud.google.com/go/spanner/apiv1/spannerpb.Type metadata, using github.com/apstndb/spantype/typector for type shapes.

ArrayValue infers the element type from the first element (or uses a default empty ARRAY<INT64> when len==0, whether the variadic slice is nil or empty). ArrayValueOf takes the element type explicitly; len==0 yields an empty ARRAY<elemType>. For a SQL NULL ARRAY, use NullOf with github.com/apstndb/spantype/typector.ElemTypeToArrayType or github.com/apstndb/spantype/typector.ElemCodeToArrayType instead of relying on variadic nil. NormalizeArrayElements rewrites SQL NULL elements to NullOf with elemType before a strict ArrayValueOf call when callers already know the final array element type. StructValueOf pairs field names with values; counts must match.

ARRAY-typed cloud.google.com/go/spanner/apiv1/spannerpb.Type values require array_element_type (protobuf: array_element_type; Go field name ArrayElementType); omitting it yields an invalid ARRAY shape and Spanner may reject the request.

Zero-argument ArrayValue returns an empty ARRAY<INT64> with complete type metadata in the Type field of the cloud.google.com/go/spanner.GenericColumnValue. For empty arrays, callers typically must supply explicit SQL type information through these constructors or through the ParamTypes field (protobuf: param_types) on cloud.google.com/go/spanner/apiv1/spannerpb.ExecuteSqlRequest, because an empty list value does not specify an element type by itself.

NullOf returns a typed NULL for any cloud.google.com/go/spanner/apiv1/spannerpb.Type, including STRUCT and ARRAY; the cloud.google.com/go/spanner.GenericColumnValue Value field is always a scalar protobuf null at the top level. NullFromCode does the same for simple scalar type codes only—it cannot express STRUCT field layouts or ARRAY element types. NullOf, NullArrayOf, and EmptyArrayOf normalize a nil Type pointer input to TYPE_CODE_UNSPECIFIED so they never fabricate malformed nil Type pointers. Neither encodes a non-null STRUCT whose fields are all null; use StructValueOf with per-field nulls when you need that shape.

NumericValueChecked and PGNumericValueChecked return errors on nil *big.Rat input instead of panicking. The legacy NumericValue and PGNumericValue helpers keep their original signatures and return typed SQL NULL values on nil input.

PGNumericValue and PGJSONBValue build PostgreSQL-dialect annotated NUMERIC/JSON values (cloud.google.com/go/spanner/apiv1/spannerpb.TypeAnnotationCode_PG_NUMERIC, cloud.google.com/go/spanner/apiv1/spannerpb.TypeAnnotationCode_PG_JSONB).

Formatting these values as strings is provided by the sibling package github.com/apstndb/spanvalue.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrTypeMismatch is returned by [ArrayValueOf] when an element's type does not match elemType.
	ErrTypeMismatch = errors.New("gcvctor: type mismatch")
	// ErrMismatchedCounts is returned by [StructValueOf] when len(names) != len(gcvs).
	ErrMismatchedCounts = errors.New("gcvctor: mismatched name/value count")
	// ErrNilElementType is returned by [ArrayValueOf] when elemType is nil.
	ErrNilElementType = errors.New("gcvctor: nil array element type")
	// ErrNilFieldType is returned by [StructValueOf] when a field's Type is nil.
	ErrNilFieldType = errors.New("gcvctor: nil struct field type")
	// ErrNilNumeric is returned by [NumericValueChecked] and [PGNumericValueChecked] when v is nil.
	ErrNilNumeric = errors.New("gcvctor: nil numeric input")
)

Functions

func ArrayValue 

func ArrayValue(vs ...spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

ArrayValue constructs ARRAY GenericColumnValue.

With no elements (including a nil or empty variadic slice), it returns an empty ARRAY<INT64> (SQL length zero, not SQL NULL), using a concrete element type so the Type field is a well-formed cloud.google.com/go/spanner/apiv1/spannerpb.Type (including array_element_type for ARRAY shapes). For a typed NULL ARRAY<INT64>, use NullOf with github.com/apstndb/spantype/typector.ElemCodeToArrayType (or github.com/apstndb/spantype/typector.ElemTypeToArrayType).

For other element types or explicit typing policy, use ArrayValueOf or EmptyArrayOf.

Note: Currently, it doesn't support implicit type conversion a.k.a. coercion so variant typed input is not supported. If the inferred element type from vs[0] is invalid, the error is wrapped in ArrayElementError with Index 0.

func ArrayValueOf added in v0.2.0 

func ArrayValueOf(elemType *sppb.Type, elems ...spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

ArrayValueOf constructs ARRAY GenericColumnValue using elemType as the element type instead of inferring it from the first element. When elems is empty (nil or length zero), it returns an empty ARRAY<elemType> (SQL length zero, not SQL NULL). For a typed NULL ARRAY<elemType>, use NullOf with github.com/apstndb/spantype/typector.ElemTypeToArrayType or github.com/apstndb/spantype/typector.ElemCodeToArrayType.

Each element's Type must match elemType (no coercion). A nil elemType returns ErrNilElementType. Per-element failures are wrapped in ArrayElementError. To accept SQL NULL elements regardless of their current Type metadata, normalize them first with NormalizeArrayElements.

func BoolValue 

func BoolValue(v bool) spanner.GenericColumnValue

BoolValue returns a non-null BOOL GenericColumnValue.

func BytesBasedValueOf added in v0.2.0 

func BytesBasedValueOf(typ *sppb.Type, v []byte) spanner.GenericColumnValue

BytesBasedValueOf constructs a GenericColumnValue with an arbitrary bytes-compatible cloud.google.com/go/spanner/apiv1/spannerpb.Type and base64-encoded payload in Value.

func BytesValue 

func BytesValue(v []byte) spanner.GenericColumnValue

BytesValue returns a non-null BYTES GenericColumnValue (base64 wire encoding).

func DateStringValue added in v0.3.0 

func DateStringValue(v string) (spanner.GenericColumnValue, error)

DateStringValue validates an RFC3339 full-date string and returns a non-null DATE GenericColumnValue using the canonical DATE wire string.

func DateValue 

func DateValue(v civil.Date) spanner.GenericColumnValue

DateValue returns a non-null DATE GenericColumnValue.

func EmptyArrayFromCode added in v0.2.0 

func EmptyArrayFromCode(code sppb.TypeCode) spanner.GenericColumnValue

EmptyArrayFromCode returns a non-null empty ARRAY<T> for a simple scalar element type code.

func EmptyArrayOf added in v0.2.0 

func EmptyArrayOf(elemType *sppb.Type) spanner.GenericColumnValue

EmptyArrayOf returns a non-null empty ARRAY<elemType> (length zero). A nil elemType is normalized to TYPE_CODE_UNSPECIFIED, so EmptyArrayOf(nil) returns an empty ARRAY<TYPE_CODE_UNSPECIFIED> rather than an invalid ARRAY shape.

func EnumValue 

func EnumValue(fqn string, v int64) spanner.GenericColumnValue

EnumValue returns a non-null ENUM GenericColumnValue for the fully qualified enum name fqn.

func Float32Value added in v0.1.5 

func Float32Value(v float32) spanner.GenericColumnValue

Float32Value returns a non-null FLOAT32 GenericColumnValue. NaN and ±Inf use string wire values matching Spanner's encoding.

func Float64Value 

func Float64Value(v float64) spanner.GenericColumnValue

Float64Value returns a non-null FLOAT64 GenericColumnValue. NaN and ±Inf use string wire values matching Spanner's encoding.

func Int64Value 

func Int64Value(v int64) spanner.GenericColumnValue

Int64Value returns a non-null INT64 GenericColumnValue (decimal string wire format).

func IntervalStringValue added in v0.3.0 

func IntervalStringValue(v string) (spanner.GenericColumnValue, error)

IntervalStringValue validates an ISO8601 duration string and returns a non-null INTERVAL GenericColumnValue using spanner.Interval's canonical wire string.

Example 
gcv := must(gcvctor.IntervalStringValue("P1Y2M3DT4H5M6S"))

fmt.Println(gcv.Type.Code.String(), gcv.Value.GetStringValue())

Output:
INTERVAL P1Y2M3DT4H5M6S

func IntervalValue added in v0.1.6 

func IntervalValue(v spanner.Interval) spanner.GenericColumnValue

IntervalValue returns a non-null INTERVAL GenericColumnValue.

func JSONValue 

func JSONValue(v any) (spanner.GenericColumnValue, error)

JSONValue marshals v to JSON and returns a non-null JSON GenericColumnValue.

func NormalizeArrayElements added in v0.3.0 

func NormalizeArrayElements(elemType *sppb.Type, elems ...spanner.GenericColumnValue) ([]spanner.GenericColumnValue, error)

NormalizeArrayElements rewrites SQL NULL elements to NullOf with elemType while preserving strict type checks for non-NULL elements. A nil elemType returns ErrNilElementType. Per-element failures are wrapped in ArrayElementError.

Example 
elemType := typector.CodeToSimpleType(sppb.TypeCode_DATE)
elems := []spanner.GenericColumnValue{
	must(gcvctor.DateStringValue("2026-04-01")),
	gcvctor.NullOf(nil),
	must(gcvctor.DateStringValue("2026-04-03")),
}

normalized := must(gcvctor.NormalizeArrayElements(elemType, elems...))
array := must(gcvctor.ArrayValueOf(elemType, normalized...))
values := array.Value.GetListValue().Values

fmt.Println(array.Type.Code.String(), array.Type.ArrayElementType.Code.String(), len(values))
fmt.Println(values[0].GetStringValue())
fmt.Println(spanvalue.IsNull(spanner.GenericColumnValue{Type: elemType, Value: values[1]}))
fmt.Println(values[2].GetStringValue())

Output:
ARRAY DATE 3
2026-04-01
true
2026-04-03

func NullArrayFromCode added in v0.2.0 

func NullArrayFromCode(elemCode sppb.TypeCode) spanner.GenericColumnValue

NullArrayFromCode returns a typed SQL NULL for ARRAY<T> where T is a simple scalar type code.

func NullArrayOf added in v0.2.0 

func NullArrayOf(elemType *sppb.Type) spanner.GenericColumnValue

NullArrayOf returns a typed SQL NULL for ARRAY<elemType>. A nil elemType is normalized to TYPE_CODE_UNSPECIFIED, so NullArrayOf(nil) returns a NULL ARRAY<TYPE_CODE_UNSPECIFIED> rather than an invalid ARRAY shape.

func NullFromCode added in v0.2.0 

func NullFromCode(code sppb.TypeCode) spanner.GenericColumnValue

NullFromCode returns a typed SQL NULL for a simple scalar type code. The cloud.google.com/go/spanner.GenericColumnValue Value field is always a protobuf NullValue; see NullOf for STRUCT and ARRAY semantics.

func NullOf added in v0.2.0 

func NullOf(typ *sppb.Type) spanner.GenericColumnValue

NullOf returns a typed SQL NULL for typ. The cloud.google.com/go/spanner.GenericColumnValue Value field is always a protobuf NullValue, including when typ is STRUCT or ARRAY. It does not represent a non-null STRUCT whose fields are all null—use StructValueOf with per-field nulls (using NullOf or NullFromCode for each field) when you need that shape. A nil typ is normalized to TYPE_CODE_UNSPECIFIED to avoid a malformed nil Type pointer.

Example 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	scalar := gcvctor.NullOf(typector.CodeToSimpleType(sppb.TypeCode_INT64))
	array := gcvctor.NullOf(typector.ElemCodeToArrayType(sppb.TypeCode_DATE))

	fmt.Println(scalar.Type.Code.String(), spanvalue.IsNull(scalar))
	fmt.Println(array.Type.Code.String(), array.Type.ArrayElementType.Code.String(), spanvalue.IsNull(array))
}

Output:
INT64 true
ARRAY DATE true

func NumericValue 

func NumericValue(v *big.Rat) spanner.GenericColumnValue

NumericValue returns a NUMERIC GenericColumnValue. A nil v returns a typed SQL NULL NUMERIC for backward compatibility; use NumericValueChecked to reject nil input with ErrNilNumeric.

func NumericValueChecked added in v0.3.0 

func NumericValueChecked(v *big.Rat) (spanner.GenericColumnValue, error)

NumericValueChecked returns a non-null NUMERIC GenericColumnValue. A nil v returns ErrNilNumeric.

func PGJSONBValue added in v0.2.1 

func PGJSONBValue(v any) (spanner.GenericColumnValue, error)

PGJSONBValue marshals v to JSON and returns a non-null PostgreSQL-dialect JSON GenericColumnValue (sppb.TypeAnnotationCode_PG_JSONB).

func PGNumericValue added in v0.2.1 

func PGNumericValue(v *big.Rat) spanner.GenericColumnValue

PGNumericValue returns a PostgreSQL-dialect NUMERIC GenericColumnValue (sppb.TypeAnnotationCode_PG_NUMERIC). A nil v returns a typed SQL NULL PG NUMERIC for backward compatibility; use PGNumericValueChecked to reject nil input with ErrNilNumeric.

func PGNumericValueChecked added in v0.3.0 

func PGNumericValueChecked(v *big.Rat) (spanner.GenericColumnValue, error)

PGNumericValueChecked returns a non-null PostgreSQL-dialect NUMERIC GenericColumnValue (sppb.TypeAnnotationCode_PG_NUMERIC). A nil v returns ErrNilNumeric.

func ProtoValue 

func ProtoValue(fqn string, b []byte) spanner.GenericColumnValue

ProtoValue returns a non-null PROTO GenericColumnValue for the fully qualified message name fqn.

func StringBasedValueFromCode added in v0.2.0 

func StringBasedValueFromCode(code sppb.TypeCode, v string) spanner.GenericColumnValue

StringBasedValueFromCode constructs a GenericColumnValue for a simple scalar type code with a string wire payload.

Example (ValidatedDate) 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	raw := gcvctor.StringBasedValueFromCode(sppb.TypeCode_DATE, "not-a-date")
	_, err := gcvctor.DateStringValue("not-a-date")

	fmt.Println(raw.Type.Code.String(), raw.Value.GetStringValue())
	fmt.Println(err != nil)
}

Output:
DATE not-a-date
true

func StringValue 

func StringValue(v string) spanner.GenericColumnValue

StringValue returns a non-null STRING GenericColumnValue.

func StructValueOf added in v0.2.0 

func StructValueOf(names []string, gcvs []spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

StructValueOf constructs STRUCT GenericColumnValue. A nil field Type returns ErrNilFieldType wrapped in StructFieldError. Note: Currently, it doesn't support implicit type conversion a.k.a. coercion so variant typed input is not supported.

func TimestampStringValue added in v0.3.0 

func TimestampStringValue(v string) (spanner.GenericColumnValue, error)

TimestampStringValue validates an RFC3339Nano timestamp string and returns a non-null TIMESTAMP GenericColumnValue using the canonical UTC wire string.

func TimestampValue 

func TimestampValue(v time.Time) spanner.GenericColumnValue

TimestampValue returns a non-null TIMESTAMP GenericColumnValue (RFC3339Nano string wire format).

func UUIDValue added in v0.1.8 

func UUIDValue(v uuid.UUID) spanner.GenericColumnValue

UUIDValue returns a non-null UUID GenericColumnValue.

Example 
package main

import (
	"fmt"

	"github.com/google/uuid"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	gcv := gcvctor.UUIDValue(uuid.MustParse("550e8400-e29b-41d4-a716-446655440000"))

	fmt.Println(gcv.Type.Code.String(), gcv.Value.GetStringValue())
}

Output:
UUID 550e8400-e29b-41d4-a716-446655440000

Types

type ArrayElementError added in v0.3.0 

type ArrayElementError struct {
	Index int
	Err   error
}

ArrayElementError adds an element index to an ARRAY construction error while preserving the wrapped cause for errors.Is and errors.As.

func (*ArrayElementError) Error added in v0.3.0 

func (e *ArrayElementError) Error() string

func (*ArrayElementError) Unwrap added in v0.3.0 

func (e *ArrayElementError) Unwrap() error

type StructFieldError added in v0.3.0 

type StructFieldError struct {
	Index int
	Name  string
	Err   error
}

StructFieldError adds a field index (and optional field name) to a STRUCT construction error while preserving the wrapped cause for errors.Is and errors.As.

func (*StructFieldError) Error added in v0.3.0 

func (e *StructFieldError) Error() string

func (*StructFieldError) Unwrap added in v0.3.0 

func (e *StructFieldError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.