Google Cloud Spanner C++ Client  1.32.1
A C++ Client Library for Google Cloud Spanner
Classes | Public Member Functions | Friends | List of all members
google::cloud::spanner::v1::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
 
Valueoperator= (Value const &)=default
 
Valueoperator= (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";
StatusOr<std::string> copy = v.get<std::string>();
if (copy) {
std::cout << *copy; // prints "hello"
}
The Value class represents a type-safe, nullable Spanner value.
Definition: value.h:168
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.
StatusOr< T > get() const &
Returns the contained value wrapped in a google::cloud::StatusOr<T>.
Definition: value.h:297
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 (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};
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}};
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

◆ Value() [4/18]

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

Constructs an instance with the specified type and value.

Definition at line 184 of file value.h.

◆ Value() [5/18]

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

Constructs an instance with the specified type and value.

Definition at line 186 of file value.h.

◆ Value() [6/18]

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

Constructs an instance with the specified type and value.

Definition at line 188 of file value.h.

◆ Value() [7/18]

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

Constructs an instance with the specified type and value.

Definition at line 190 of file value.h.

◆ Value() [8/18]

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

Constructs an instance with the specified type and value.

Definition at line 192 of file value.h.

◆ Value() [9/18]

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

Constructs an instance with the specified type and value.

Definition at line 194 of file value.h.

◆ Value() [10/18]

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

Constructs an instance with the specified type and value.

Definition at line 196 of file value.h.

◆ Value() [11/18]

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

Constructs an instance with the specified type and value.

Definition at line 198 of file value.h.

◆ Value() [12/18]

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

Constructs an instance with the specified type and value.

Definition at line 200 of file value.h.

◆ Value() [13/18]

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

Constructs an instance with the specified type and value.

Definition at line 203 of file value.h.

◆ Value() [14/18]

google::cloud::spanner::v1::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:

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

Definition at line 223 of file value.h.

◆ Value() [15/18]

google::cloud::spanner::v1::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:

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

Definition at line 225 of file value.h.

◆ Value() [16/18]

template<typename T >
google::cloud::spanner::v1::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.

Definition at line 232 of file value.h.

◆ Value() [17/18]

template<typename T >
google::cloud::spanner::v1::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.

Definition at line 248 of file value.h.

◆ Value() [18/18]

template<typename... Ts>
google::cloud::spanner::v1::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>.

Definition at line 261 of file value.h.

Member Function Documentation

◆ get() [1/2]

template<typename T >
StatusOr<T> google::cloud::spanner::v1::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
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

Definition at line 309 of file value.h.

◆ get() [2/2]

template<typename T >
StatusOr<T> google::cloud::spanner::v1::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
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

Definition at line 297 of file value.h.

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

Friends And Related Function Documentation

◆ operator!=

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

Definition at line 265 of file value.h.

◆ 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:
std::cout << v << "\n";

Definition at line 194 of file value.cc.

◆ operator==

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

Definition at line 190 of file value.cc.

◆ 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.

Definition at line 340 of file value.h.