firebase::firestore::FieldValue

#include <field_value.h>

A field value represents variant datatypes as stored by Firestore.

Summary

FieldValue can be used when reading a particular field with DocumentSnapshot::Get() or fields with DocumentSnapshot::GetData(). When writing document fields with DocumentReference::Set() or DocumentReference::Update(), it can also represent sentinel values in addition to real data values.

For a non-sentinel instance, you can check whether it is of a particular type with is_foo() and get the value with foo_value(), where foo can be one of null, boolean, integer, double, timestamp, string, blob, reference, geo_point, array or map. If the instance is not of type foo, the call to foo_value() will fail (and cause a crash).

Constructors and Destructors
FieldValue()
Creates an invalid FieldValue that has to be reassigned before it can be used.
FieldValue(const FieldValue & other)
Copy constructor.
FieldValue(FieldValue && other)
Move constructor.
~FieldValue()

Public types
Type enum
The enumeration of all valid runtime types of FieldValue.

Friend classes
operator<<
friend std::ostream &
Outputs the string representation of this FieldValue to the given stream.

Public functions
ToString() const
std::string
Returns a string representation of this FieldValue for logging/debugging purposes.
array_value() const
std::vector< FieldValue >
Gets the vector of FieldValues contained in this FieldValue.
blob_size() const
size_t
Gets the blob size contained in this FieldValue.
blob_value() const
const uint8_t *
Gets the blob value contained in this FieldValue.
boolean_value() const
bool
Gets the boolean value contained in this FieldValue.
double_value() const
double
Gets the double value contained in this FieldValue.
geo_point_value() const
class GeoPoint
Gets the GeoPoint value contained in this FieldValue.
integer_value() const
int64_t
Gets the integer value contained in this FieldValue.
is_array() const
bool
Gets whether this FieldValue contains an array of FieldValues.
is_blob() const
bool
Gets whether this FieldValue contains a blob.
is_boolean() const
bool
Gets whether this FieldValue contains a boolean value.
is_double() const
bool
Gets whether this FieldValue contains a double value.
is_geo_point() const
bool
Gets whether this FieldValue contains a GeoPoint.
is_integer() const
bool
Gets whether this FieldValue contains an integer value.
is_map() const
bool
Gets whether this FieldValue contains a map of std::string to FieldValue.
is_null() const
bool
Gets whether this FieldValue is currently null.
is_reference() const
bool
Gets whether this FieldValue contains a reference to a document in the same Firestore.
is_string() const
bool
Gets whether this FieldValue contains a string.
is_timestamp() const
bool
Gets whether this FieldValue contains a timestamp.
is_valid() const
bool
Returns true if this FieldValue is valid, false if it is not valid.
map_value() const
Gets the map of string to FieldValue contained in this FieldValue.
operator=(const FieldValue & other)
Copy assignment operator.
operator=(FieldValue && other) noexcept
Move assignment operator.
reference_value() const
Gets the DocumentReference contained in this FieldValue.
string_value() const
std::string
Gets the string value contained in this FieldValue.
timestamp_value() const
class Timestamp
Gets the timestamp value contained in this FieldValue.
type() const
Gets the current type contained in this FieldValue.

Public static functions
Array(std::vector< FieldValue > value)
Constructs a FieldValue containing the given FieldValue vector value.
ArrayRemove(std::vector< FieldValue > elements)
Returns a special value that can be used with Set() or Update() that tells the server to remove the given elements from any array value that already exists on the server.
ArrayUnion(std::vector< FieldValue > elements)
Returns a special value that can be used with Set() or Update() that tells the server to union the given elements with any array value that already exists on the server.
Blob(const uint8_t *value, size_t size)
Constructs a FieldValue containing the given blob value of given size.
Boolean(bool value)
Constructs a FieldValue containing the given boolean value.
Delete()
Returns a sentinel for use with Update() to mark a field for deletion.
Double(double value)
Constructs a FieldValue containing the given double-precision floating point value.
GeoPoint(GeoPoint value)
Constructs a FieldValue containing the given GeoPoint value.
Increment(T by_value)
Returns a special value that can be used with Set() or Update() that tells the server to increment the field's current value by the given integer value.
Increment(T by_value)
Returns a special value that can be used with Set() or Update() that tells the server to increment the field's current value by the given floating point value.
Integer(int64_t value)
Constructs a FieldValue containing the given 64-bit integer value.
Map(MapFieldValue value)
Constructs a FieldValue containing the given FieldValue map value.
Null()
Constructs a null.
Reference(DocumentReference value)
Constructs a FieldValue containing the given reference value.
ServerTimestamp()
Returns a sentinel that can be used with Set() or Update() to include a server-generated timestamp in the written data.
String(std::string value)
Constructs a FieldValue containing the given std::string value.
Timestamp(Timestamp value)
Constructs a FieldValue containing the given Timestamp value.

Public types

Type

 Type

The enumeration of all valid runtime types of FieldValue.

Friend classes

operator<<

friend std::ostream & operator<<(std::ostream &out, const FieldValue &value)

Outputs the string representation of this FieldValue to the given stream.

See also:ToString() for comments on the representation format.

Public functions

FieldValue

 FieldValue()

Creates an invalid FieldValue that has to be reassigned before it can be used.

Calling any member function on an invalid FieldValue will be a no-op. If the function returns a value, it will return a zero, empty, or invalid value, depending on the type of the value.

FieldValue

 FieldValue(
  const FieldValue & other
)

Copy constructor.

FieldValue is immutable and can be efficiently copied (no deep copy is performed).

Details
Parameters
other
FieldValue to copy from.

FieldValue

 FieldValue(
  FieldValue && other
) noexcept

Move constructor.

Moving is more efficient than copying for a FieldValue. After being moved from, a FieldValue is equivalent to its default-constructed state.

Details
Parameters
other
FieldValue to move data from.

ToString

std::string ToString() const

Returns a string representation of this FieldValue for logging/debugging purposes.

array_value

std::vector< FieldValue > array_value() const

Gets the vector of FieldValues contained in this FieldValue.

blob_size

size_t blob_size() const

Gets the blob size contained in this FieldValue.

blob_value

const uint8_t * blob_value() const

Gets the blob value contained in this FieldValue.

boolean_value

bool boolean_value() const

Gets the boolean value contained in this FieldValue.

double_value

double double_value() const

Gets the double value contained in this FieldValue.

geo_point_value

class GeoPoint geo_point_value() const

Gets the GeoPoint value contained in this FieldValue.

integer_value

int64_t integer_value() const

Gets the integer value contained in this FieldValue.

is_array

bool is_array() const

Gets whether this FieldValue contains an array of FieldValues.

is_blob

bool is_blob() const

Gets whether this FieldValue contains a blob.

is_boolean

bool is_boolean() const

Gets whether this FieldValue contains a boolean value.

is_double

bool is_double() const

Gets whether this FieldValue contains a double value.

is_geo_point

bool is_geo_point() const

Gets whether this FieldValue contains a GeoPoint.

is_integer

bool is_integer() const

Gets whether this FieldValue contains an integer value.

is_map

bool is_map() const

Gets whether this FieldValue contains a map of std::string to FieldValue.

is_null

bool is_null() const

Gets whether this FieldValue is currently null.

is_reference

bool is_reference() const

Gets whether this FieldValue contains a reference to a document in the same Firestore.

is_string

bool is_string() const

Gets whether this FieldValue contains a string.

is_timestamp

bool is_timestamp() const

Gets whether this FieldValue contains a timestamp.

is_valid

bool is_valid() const

Returns true if this FieldValue is valid, false if it is not valid.

An invalid FieldValue could be the result of:

  • Creating a FieldValue using the default constructor.
  • Moving from the FieldValue.
  • Calling DocumentSnapshot::Get(field) for a field that does not exist in the document.

Details
Returns
true if this FieldValue is valid, false if this FieldValue is invalid.

map_value

MapFieldValue map_value() const

Gets the map of string to FieldValue contained in this FieldValue.

operator=

FieldValue & operator=(
  const FieldValue & other
)

Copy assignment operator.

FieldValue is immutable and can be efficiently copied (no deep copy is performed).

Details
Parameters
other
FieldValue to copy from.
Returns
Reference to the destination FieldValue.

operator=

FieldValue & operator=(
  FieldValue && other
) noexcept

Move assignment operator.

Moving is more efficient than copying for a FieldValue. After being moved from, a FieldValue is equivalent to its default-constructed state.

Details
Parameters
other
FieldValue to move data from.
Returns
Reference to the destination FieldValue.

reference_value

DocumentReference reference_value() const

Gets the DocumentReference contained in this FieldValue.

string_value

std::string string_value() const

Gets the string value contained in this FieldValue.

timestamp_value

class Timestamp timestamp_value() const

Gets the timestamp value contained in this FieldValue.

type

Type type() const

Gets the current type contained in this FieldValue.

~FieldValue

 ~FieldValue()

Public static functions

Array

FieldValue Array(
  std::vector< FieldValue > value
)

Constructs a FieldValue containing the given FieldValue vector value.

ArrayRemove

FieldValue ArrayRemove(
  std::vector< FieldValue > elements
)

Returns a special value that can be used with Set() or Update() that tells the server to remove the given elements from any array value that already exists on the server.

All instances of each element specified will be removed from the array. If the field being modified is not already an array, it will be overwritten with an empty array.

Details
Parameters
elements
The elements to remove from the array.
Returns
The FieldValue sentinel for use in a call to Set() or Update().

ArrayUnion

FieldValue ArrayUnion(
  std::vector< FieldValue > elements
)

Returns a special value that can be used with Set() or Update() that tells the server to union the given elements with any array value that already exists on the server.

Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array, it will be overwritten with an array containing exactly the specified elements.

Details
Parameters
elements
The elements to union into the array.
Returns
The FieldValue sentinel for use in a call to Set() or Update().

Blob

FieldValue Blob(
  const uint8_t *value,
  size_t size
)

Constructs a FieldValue containing the given blob value of given size.

value is copied into the returned FieldValue.

Boolean

FieldValue Boolean(
  bool value
)

Constructs a FieldValue containing the given boolean value.

Delete

FieldValue Delete()

Returns a sentinel for use with Update() to mark a field for deletion.

Double

FieldValue Double(
  double value
)

Constructs a FieldValue containing the given double-precision floating point value.

GeoPoint

FieldValue GeoPoint(
  GeoPoint value
)

Constructs a FieldValue containing the given GeoPoint value.

Increment

FieldValue Increment(
  T by_value
)

Returns a special value that can be used with Set() or Update() that tells the server to increment the field's current value by the given integer value.

If the current field value is an integer, possible integer overflows are resolved to LONG_MAX or LONG_MIN. If the current field value is a double, both values will be interpreted as doubles and the arithmetic will follow IEEE 754 semantics.

If field is not an integer or a double, or if the field does not yet exist, the transformation will set the field to the given value.

Details
Parameters
by_value
The integer value to increment by. Should be an integer type not larger than int64_t.
Returns
The FieldValue sentinel for use in a call to Set() or Update().

Increment

FieldValue Increment(
  T by_value
)

Returns a special value that can be used with Set() or Update() that tells the server to increment the field's current value by the given floating point value.

If the current field value is an integer, possible integer overflows are resolved to LONG_MAX or LONG_MIN. If the current field value is a double, both values will be interpreted as doubles and the arithmetic will follow IEEE 754 semantics.

If field is not an integer or a double, or if the field does not yet exist, the transformation will set the field to the given value.

Details
Parameters
by_value
The double value to increment by. Should be a floating point type no larger than double.
Returns
The FieldValue sentinel for use in a call to Set() or Update().

Integer

FieldValue Integer(
  int64_t value
)

Constructs a FieldValue containing the given 64-bit integer value.

Map

FieldValue Map(
  MapFieldValue value
)

Constructs a FieldValue containing the given FieldValue map value.

Null

FieldValue Null()

Constructs a null.

Reference

FieldValue Reference(
  DocumentReference value
)

Constructs a FieldValue containing the given reference value.

ServerTimestamp

FieldValue ServerTimestamp()

Returns a sentinel that can be used with Set() or Update() to include a server-generated timestamp in the written data.

String

FieldValue String(
  std::string value
)

Constructs a FieldValue containing the given std::string value.

Timestamp

FieldValue Timestamp(
  Timestamp value
)

Constructs a FieldValue containing the given Timestamp value.