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

Typeenum
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<<

friendstd::ostream&operator<<(std::ostream&out,constFieldValue&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(constFieldValue&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::stringToString()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_tblob_size()const

Gets the blob size contained in this FieldValue.

blob_value

constuint8_t*blob_value()const

Gets the blob value contained in this FieldValue.

boolean_value

boolboolean_value()const

Gets the boolean value contained in this FieldValue.

double_value

doubledouble_value()const

Gets the double value contained in this FieldValue.

geo_point_value

classGeoPointgeo_point_value()const

Gets the GeoPoint value contained in this FieldValue.

integer_value

int64_tinteger_value()const

Gets the integer value contained in this FieldValue.

is_array

boolis_array()const

Gets whether this FieldValue contains an array of FieldValues.

is_blob

boolis_blob()const

Gets whether this FieldValue contains a blob.

is_boolean

boolis_boolean()const

Gets whether this FieldValue contains a boolean value.

is_double

boolis_double()const

Gets whether this FieldValue contains a double value.

is_geo_point

boolis_geo_point()const

Gets whether this FieldValue contains a GeoPoint.

is_integer

boolis_integer()const

Gets whether this FieldValue contains an integer value.

is_map

boolis_map()const

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

is_null

boolis_null()const

Gets whether this FieldValue is currently null.

is_reference

boolis_reference()const

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

is_string

boolis_string()const

Gets whether this FieldValue contains a string.

is_timestamp

boolis_timestamp()const

Gets whether this FieldValue contains a timestamp.

is_valid

boolis_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

MapFieldValuemap_value()const

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

operator=

FieldValue&operator=(constFieldValue&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

DocumentReferencereference_value()const

Gets the DocumentReference contained in this FieldValue.

string_value

std::stringstring_value()const

Gets the string value contained in this FieldValue.

timestamp_value

classTimestamptimestamp_value()const

Gets the timestamp value contained in this FieldValue.

type

Typetype()const

Gets the current type contained in this FieldValue.

~FieldValue

~FieldValue()

Public static functions

Array

FieldValueArray(std::vector<FieldValue>value)

Constructs a FieldValue containing the given FieldValue vector value.

ArrayRemove

FieldValueArrayRemove(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

FieldValueArrayUnion(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

FieldValueBlob(constuint8_t*value,size_tsize)

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

value is copied into the returned FieldValue.

Boolean

FieldValueBoolean(boolvalue)

Constructs a FieldValue containing the given boolean value.

Delete

FieldValueDelete()

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

Double

FieldValueDouble(doublevalue)

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

GeoPoint

FieldValueGeoPoint(GeoPointvalue)

Constructs a FieldValue containing the given GeoPoint value.

Increment

FieldValueIncrement(Tby_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

FieldValueIncrement(Tby_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

FieldValueInteger(int64_tvalue)

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

Map

FieldValueMap(MapFieldValuevalue)

Constructs a FieldValue containing the given FieldValue map value.

Null

FieldValueNull()

Constructs a null.

Reference

FieldValueReference(DocumentReferencevalue)

Constructs a FieldValue containing the given reference value.

ServerTimestamp

FieldValueServerTimestamp()

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

String

FieldValueString(std::stringvalue)

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

Timestamp

FieldValueTimestamp(Timestampvalue)

Constructs a FieldValue containing the given Timestamp value.