The Value class represents a type-safe, nullable Spanner value. More...

#include <google/cloud/spanner/value.h>

Public Member Functions
	Value ()=default
	Constructs a `Value` that holds nothing. More...

	Value (Value const &)=default

	Value (Value &&)=default

Value &	operator= (Value const &)=default

Value &	operator= (Value &&)=default

	Value (bool v)
	Constructs an instance with the specified type and value. More...

	Value (std::int64_t v)
	Constructs an instance with the specified type and value. More...

	Value (double v)
	Constructs an instance with the specified type and value. More...

	Value (std::string v)
	Constructs an instance with the specified type and value. More...

	Value (Bytes v)
	Constructs an instance with the specified type and value. More...

	Value (Json v)
	Constructs an instance with the specified type and value. More...

	Value (Numeric v)
	Constructs an instance with the specified type and value. More...

	Value (Timestamp v)
	Constructs an instance with the specified type and value. More...

	Value (CommitTimestamp v)
	Constructs an instance with the specified type and value. More...

	Value (absl::CivilDay v)
	Constructs an instance with the specified type and value. More...

	Value (int v)
	Constructs an instance from common C++ literal types that closely, though not exactly, match supported Spanner types. More...

	Value (char const *v)
	Constructs an instance from common C++ literal types that closely, though not exactly, match supported Spanner types. More...

template<typename T >
	Value (absl::optional< T > opt)
	Constructs a non-null instance if `opt` has a value, otherwise constructs a null instance with the specified type `T`. More...

template<typename T >
	Value (std::vector< T > v)
	Constructs an instance from a Spanner ARRAY of the specified type and values. More...

template<typename... Ts>
	Value (std::tuple< Ts... > tup)
	Constructs an instance from a Spanner STRUCT with a type and values matching the given `std::tuple`. More...

template<typename T >
StatusOr< T >	get () const &
	Returns the contained value wrapped in a `google::cloud::StatusOr<T>`. More...

template<typename T >
StatusOr< T >	get () &&
	Returns the contained value wrapped in a `google::cloud::StatusOr<T>`. More...

Friends
bool	operator== (Value const &a, Value const &b)

bool	operator!= (Value const &a, Value const &b)

std::ostream &	operator<< (std::ostream &os, Value const &v)
	Outputs string representation of a given Value to the provided stream. More...

void	PrintTo (Value const &v, std::ostream *os)
	Prints the same output as `operator<<`. More...

Detailed Description

The Value class represents a type-safe, nullable Spanner value.

It is conceptually similar to a std::any except the only allowed types are those supported by Spanner, and a "null" value (similar to a std::any without a value) still has an associated type. The supported types are shown in the following table along with how they map to the Spanner types (https://cloud.google.com/spanner/docs/data-types):

Spanner Type	C++ Type `T`
BOOL	`bool`
INT64	`std::int64_t`
FLOAT64	`double`
STRING	`std::string`
BYTES	`google::cloud::spanner::Bytes`
JSON	`google::cloud::spanner::Json`
NUMERIC	`google::cloud::spanner::Numeric`
TIMESTAMP	`google::cloud::spanner::Timestamp`
DATE	`absl::CivilDay`
ARRAY	`std::vector<T>` // [1]
STRUCT	`std::tuple<Ts...>`

[1] The type T may be any of the other supported types, except for ARRAY/std::vector.

Value is a regular C++ value type with support for copy, move, equality, etc. A default-constructed Value represents an empty value with no type.

Note: There is also a C++ type of CommitTimestamp that corresponds to a Cloud Spanner TIMESTAMP object for setting the commit timestamp on a column with the allow_commit_timestamp set to true in the schema.

See also: https://cloud.google.com/spanner/docs/commit-timestamp

Callers may create instances by passing any of the supported values (shown in the table above) to the constructor. "Null" values are created using the MakeNullValue<T>() factory function or by passing an empty absl::optional<T> to the Value constructor..

Example with a non-null value

std::string msg = "hello";
spanner::Value v(msg);
StatusOr<std::string> copy = v.get<std::string>();
if (copy) {
  std::cout << *copy;  // prints "hello"
}

Example with a null

spanner::Value v = spanner::MakeNullValue<std::int64_t>();
StatusOr<std::int64_t> i = v.get<std::int64_t>();
assert(!i.ok());  // Can't get the value because v is null
StatusOr < absl::optional<std::int64_t> j =
    v.get<absl::optional<std::int64_t>>();
assert(j.ok());  // OK because an empty option can represent the null
assert(!j->has_value());  // v held no value.

Nullness

All of the supported types (above) are "nullable". A null is created in one of two ways:

Passing an absl::optional<T>() with no value to Value's constructor.
Using the MakeNullValue<T>() helper function (defined below).

Nulls can be retrieved from a Value::get<T> by specifying the type T as an absl::optional<U>. The returned optional will either be empty (indicating null) or it will contain the actual value. See the documentation for Value::get<T> below for more details.

Spanner Arrays (i.e., std::vector<T>)

Spanner arrays are represented in C++ as a std::vector<T>, where the type T may be any of the other allowed Spanner types, such as bool, std::int64_t, etc. The only exception is that arrays may not directly contain another array; to achieve a similar result you could create an array of a 1-element struct holding an array. The following examples show usage of arrays.

std::vector<std::int64_t> vec = {1, 2, 3, 4, 5};
spanner::Value v(vec);
auto copy = *v.get<std::vector<std::int64_t>>();
assert(vec == copy);

Spanner Structs (i.e., std::tuple<Ts...>)

Spanner structs are represented in C++ as instances of std::tuple holding zero or more of the allowed Spanner types, such as bool, std::int64_t, std::vector, and even other std::tuple objects. Each tuple element corresponds to a single field in a Spanner STRUCT.

Spanner STRUCT fields may optionally contain a string indicating the field's name. Fields names may be empty, unique, or repeated. A named field may be specified as a tuple element of type std::pair<std::string, T>, where the pair's .first member indicates the field's name, and the .second member is any valid Spanner type T.

using Struct = std::tuple<bool, std::pair<std::string, std::int64_t>>;
Struct s  = {true, {"Foo", 42}};
spanner::Value v(s);
assert(s == *v.get<Struct>());

Note: While a STRUCT's (optional) field names are not part of its C++ type, they are part of its Spanner STRUCT type. Array's (i.e., std::vector) must contain a single element type, therefore it is an error to construct a std::vector of std::tuple objects with differently named fields.

Definition at line 168 of file value.h.

Constructor & Destructor Documentation

◆ Value() [1/18]

google::cloud::spanner::v1::Value::Value ( )

default

Constructs a Value that holds nothing.

All calls to get<T>() will return an error.

◆ Value() [2/18]

google::cloud::spanner::v1::Value::Value ( Value const & )

default

◆ Value() [3/18]

google::cloud::spanner::v1::Value::Value ( Value && )

default