google::cloud::spanner::Value Class Reference

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 (JsonB 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 (PgNumeric 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
JSONB	google::cloud::spanner::JsonB
NUMERIC	google::cloud::spanner::Numeric
NUMERIC(PG)	google::cloud::spanner::PgNumeric
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

Using 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

Using a null value.

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:

1. Passing an absl::optional<T>() with no value to Value's constructor.
2. 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

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

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.

Constructor & Destructor Documentation

Value() [1/20]

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

default

Constructs a Value that holds nothing.

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

Value() [2/20]

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

default

Value() [3/20]

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

default

Value() [4/20]

google::cloud::spanner::Value::Value ( bool  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [5/20]

google::cloud::spanner::Value::Value ( std::int64_t  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [6/20]

google::cloud::spanner::Value::Value ( double  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [7/20]

google::cloud::spanner::Value::Value ( std::string  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [8/20]

google::cloud::spanner::Value::Value ( Bytes  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [9/20]

google::cloud::spanner::Value::Value ( Json  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [10/20]

google::cloud::spanner::Value::Value ( JsonB  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [11/20]

google::cloud::spanner::Value::Value ( Numeric  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [12/20]

google::cloud::spanner::Value::Value ( PgNumeric  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [13/20]

google::cloud::spanner::Value::Value ( Timestamp  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [14/20]

google::cloud::spanner::Value::Value ( CommitTimestamp  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [15/20]

google::cloud::spanner::Value::Value ( absl::CivilDay  v )

inlineexplicit

Constructs an instance with the specified type and value.

Value() [16/20]

google::cloud::spanner::Value::Value ( int  v )

inlineexplicit

Constructs an instance from common C++ literal types that closely, though not exactly, match supported Spanner types.

An integer literal in C++ is of type int, which is not exactly an allowed Spanner type. This will be allowed but it will be implicitly up converted to a std::int64_t. Similarly, a C++ string literal will be implicitly converted to a std::string. For example:

spanner::Value v1(42);
assert(42 == *v1.get<std::int64_t>());
 
spanner::Value v2("hello");
assert("hello" == *v2.get<std::string>());

Value() [17/20]

google::cloud::spanner::Value::Value ( char const *  v )

inlineexplicit

Constructs an instance from common C++ literal types that closely, though not exactly, match supported Spanner types.

An integer literal in C++ is of type int, which is not exactly an allowed Spanner type. This will be allowed but it will be implicitly up converted to a std::int64_t. Similarly, a C++ string literal will be implicitly converted to a std::string. For example:

spanner::Value v1(42);
assert(42 == *v1.get<std::int64_t>());
 
spanner::Value v2("hello");
assert("hello" == *v2.get<std::string>());

Value() [18/20]

template<typename T >

google::cloud::spanner::Value::Value ( absl::optional< T >  opt )

inlineexplicit

Constructs a non-null instance if opt has a value, otherwise constructs a null instance with the specified type T.

Value() [19/20]

template<typename T >

google::cloud::spanner::Value::Value ( std::vector< T >  v )

inlineexplicit

Constructs an instance from a Spanner ARRAY of the specified type and values.

The type T may be any valid type shown above, except vectors of vectors are not allowed.

Warning

If T is a std::tuple with field names (i.e., at least one of its element types is a std::pair<std::string, T>) then, all of the vector's elements must have exactly the same field names. Any mismatch in in field names results in undefined behavior.

Value() [20/20]

template<typename... Ts>

google::cloud::spanner::Value::Value ( std::tuple< Ts... >  tup )

inlineexplicit

Constructs an instance from a Spanner STRUCT with a type and values matching the given std::tuple.

Any STRUCT field may optionally have a name, which is specified as std::pair<std::string, T>.

Member Function Documentation

get() [1/2]

template<typename T >

StatusOr< T > google::cloud::spanner::Value::get ( ) &&

inline

Returns the contained value wrapped in a google::cloud::StatusOr<T>.

Returns a non-OK status IFF:

• The contained value is "null", and T is not an absl::optional.
• There is an error converting the contained value to T.

Example

spanner::Value v{3.14};
StatusOr<double> d = v.get<double>();
if (d) {
  std::cout << "d=" << *d;
}
 
// Now using a "null" std::int64_t
v = spanner::MakeNullValue<std::int64_t>();
StatusOr<std::int64_t> i = v.get<std::int64_t>();
if (!i) {
  std::cerr << "Could not get integer: " << i.status();
}
StatusOr<absl::optional<std::int64_t>> j =
    v.get<absl::optional<std::int64_t>>();
assert(j.ok());  // Since we know the types match in this example
assert(!v->has_value());  // Since we know v was null in this example

get() [2/2]

template<typename T >

StatusOr< T > google::cloud::spanner::Value::get ( ) const &

inline

Returns the contained value wrapped in a google::cloud::StatusOr<T>.

Returns a non-OK status IFF:

• The contained value is "null", and T is not an absl::optional.
• There is an error converting the contained value to T.

Example

spanner::Value v{3.14};
StatusOr<double> d = v.get<double>();
if (d) {
  std::cout << "d=" << *d;
}
 
// Now using a "null" std::int64_t
v = spanner::MakeNullValue<std::int64_t>();
StatusOr<std::int64_t> i = v.get<std::int64_t>();
if (!i) {
  std::cerr << "Could not get integer: " << i.status();
}
StatusOr<absl::optional<std::int64_t>> j =
    v.get<absl::optional<std::int64_t>>();
assert(j.ok());  // Since we know the types match in this example
assert(!v->has_value());  // Since we know v was null in this example

operator=() [1/2]

Value & google::cloud::spanner::Value::operator= ( Value &&  )

default

operator=() [2/2]

Value & google::cloud::spanner::Value::operator= ( Value const &  )

default

Friends And Related Function Documentation

operator!=

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

friend

operator<<

std::ostream & operator<< ( std::ostream &  os, Value const &  v  )

friend

Outputs string representation of a given Value to the provided stream.

Warning

This is intended for debugging and human consumption only, not machine consumption, as the output format may change without notice.

Example:

spanner::Value v{42};
std::cout << v << "\n";

operator==

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

friend

PrintTo

void PrintTo ( Value const &  v, std::ostream *  os  )

friend

Prints the same output as operator<<.

Warning

DO NOT CALL. This function will be removed in a future release. Use operator<< instead.