#include <bdld_datum.h>

Detailed Description

This class implements a mechanism that provides a space-efficient discriminated union that holds the value of ether scalar type or an aggregate of Datum objects. The size of Datum is 8 bytes (same as a double) on 32-bit platforms and 16 bytes on 64-bit platforms. Separate representation are needed on 32 and 64 bit platforms because of the differing size of a pointer (a 64-bit pointer cannot reasonably be held in a 32-bit footprint).

Representation on a 32-bit Platforms: Values are stored inside an 8-byte unsigned char array (d_data). Any double value (including NaN and infinity values) can be stored inside Datum. When storing a value of a type other than double, the bits in d_data that correspond to the exponent part of a double value are set to 1, with the 4 bits in the fraction part used to indicate the type of value stored.

Representation on 64-bit platforms: Values are stored inside a 16 byte unsigned char array (d_data) to store values. The type information is stored in the upper 2 bytes of the character array. Remaining 14 bytes are used to store the actual value or the pointer to the external memory that holds the value.

For details on the internal representations that are used for various types on 32 and 64 bit platforms, please see the implementation notes in bdld_datum.cpp.

Datum objects are bitwise copyable and have trivial initialization, assignment and destruction. Only one of the copies of the same Datum object can be passed to destroy. The rest of those copies then become invalid and it is undefined behavior to deep-copy or destroy them. Although, these copies can be used on the left hand side of assignment.

See bdld_datum

Public Types
enum	DataType { e_NIL = 0 , e_INTEGER = 1 , e_DOUBLE = 2 , e_STRING = 3 , e_BOOLEAN = 4 , e_ERROR = 5 , e_DATE = 6 , e_TIME = 7 , e_DATETIME = 8 , e_DATETIME_INTERVAL = 9 , e_INTEGER64 = 10 , e_USERDEFINED = 11 , e_ARRAY = 12 , e_MAP = 13 , e_BINARY = 14 , e_DECIMAL64 = 15 , e_INT_MAP = 16 , e_REAL = e_DOUBLE , e_ERROR_VALUE = e_ERROR }

enum	{ k_NUM_TYPES = 17 }

typedef bsl::allocator	AllocatorType

typedef bsls::Types::size_type	SizeType

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (Datum, bsl::is_trivially_copyable)

	BSLMF_NESTED_TRAIT_DECLARATION (Datum, bsl::is_trivially_default_constructible)

	BSLMF_NESTED_TRAIT_DECLARATION (Datum, bslmf::IsBitwiseMoveable)

	BSLMF_NESTED_TRAIT_DECLARATION (Datum, bdlb::HasPrintMethod)

	Datum ()=default

	Datum (const Datum &original)=default

	~Datum ()=default

Datum &	operator= (const Datum &rhs)=default

template<class t_VISITOR >
void	apply (t_VISITOR &visitor) const

Datum	clone (const AllocatorType &allocator) const

bool	isArray () const

bool	isBinary () const

bool	isBoolean () const

bool	isDate () const

bool	isDatetime () const

bool	isDatetimeInterval () const

bool	isDecimal64 () const

bool	isDouble () const

bool	isError () const

bool	isExternalReference () const

bool	isInteger () const

bool	isInteger64 () const

bool	isIntMap () const

bool	isMap () const

bool	isNull () const

bool	isString () const

bool	isTime () const

bool	isUdt () const

DatumArrayRef	theArray () const

DatumBinaryRef	theBinary () const

bool	theBoolean () const

bdlt::Date	theDate () const

bdlt::Datetime	theDatetime () const

bdlt::DatetimeInterval	theDatetimeInterval () const

bdldfp::Decimal64	theDecimal64 () const

double	theDouble () const

DatumError	theError () const

int	theInteger () const

bsls::Types::Int64	theInteger64 () const

DatumIntMapRef	theIntMap () const

DatumMapRef	theMap () const

bslstl::StringRef	theString () const

bdlt::Time	theTime () const

DatumUdt	theUdt () const

DataType	type () const

bsl::ostream &	print (bsl::ostream &stream, int level=0, int spacesPerLevel=4) const

Static Public Member Functions
static Datum	createArrayReference (const Datum *array, SizeType length, const AllocatorType &allocator)

static Datum	createArrayReference (const DatumArrayRef &value, const AllocatorType &allocator)

static Datum	createBoolean (bool value)

static Datum	createDate (const bdlt::Date &value)

static Datum	createDatetime (const bdlt::Datetime &value, const AllocatorType &allocator)

static Datum	createDatetimeInterval (const bdlt::DatetimeInterval &value, const AllocatorType &allocator)

static Datum	createDecimal64 (bdldfp::Decimal64 value, const AllocatorType &allocator)

static Datum	createDouble (double value)

static Datum	createError (int code)

static Datum	createError (int code, const bslstl::StringRef &message, const AllocatorType &allocator)

static Datum	createInteger (int value)

static Datum	createInteger64 (bsls::Types::Int64 value, const AllocatorType &allocator)

static Datum	createNull ()

static Datum	createStringRef (const char *string, SizeType length, const AllocatorType &allocator)

static Datum	createStringRef (const char *string, const AllocatorType &allocator)

static Datum	createStringRef (const bslstl::StringRef &value, const AllocatorType &allocator)

static Datum	createTime (const bdlt::Time &value)

static Datum	createUdt (void *data, int type)

static Datum	copyBinary (const void *value, SizeType size, const AllocatorType &allocator)

static Datum	copyString (const char *string, SizeType length, const AllocatorType &allocator)

static Datum	copyString (const bslstl::StringRef &value, const AllocatorType &allocator)

static Datum	adoptArray (const DatumMutableArrayRef &array)

static Datum	adoptIntMap (const DatumMutableIntMapRef &intMap)

static Datum	adoptMap (const DatumMutableMapRef &map)

static Datum	adoptMap (const DatumMutableMapOwningKeysRef &map)

static void	createUninitializedArray (DatumMutableArrayRef *result, SizeType capacity, const AllocatorType &allocator)

static void	createUninitializedIntMap (DatumMutableIntMapRef *result, SizeType capacity, const AllocatorType &allocator)

static void	createUninitializedMap (DatumMutableMapRef *result, SizeType capacity, const AllocatorType &allocator)

static void	createUninitializedMap (DatumMutableMapOwningKeysRef *result, SizeType capacity, SizeType keysCapacity, const AllocatorType &allocator)

static char *	createUninitializedString (Datum *result, SizeType length, const AllocatorType &allocator)

static void *	createUninitializedBinary (Datum *result, SizeType size, const AllocatorType &allocator)

static const char *	dataTypeToAscii (DataType type)

static void	destroy (const Datum &value, const AllocatorType &allocator)

static void	disposeUninitializedArray (const DatumMutableArrayRef &array, const AllocatorType &allocator)

static void	disposeUninitializedIntMap (const DatumMutableIntMapRef &intMap, const AllocatorType &allocator)

static void	disposeUninitializedMap (const DatumMutableMapRef &map, const AllocatorType &allocator)

static void	disposeUninitializedMap (const DatumMutableMapOwningKeysRef &map, const AllocatorType &allocator)

static void	createUninitializedMapOwningKeys (DatumMutableMapOwningKeysRef *result, SizeType capacity, SizeType keysCapacity, const AllocatorType &allocator)

static Datum	adoptMapOwningKeys (const DatumMutableMapOwningKeysRef &mapping)

static void	disposeUninitializedMapOwningKeys (const DatumMutableMapOwningKeysRef &mapping, const AllocatorType &allocator)

Friends
bool	operator== (const Datum &lhs, const Datum &rhs)

bool	operator!= (const Datum &lhs, const Datum &rhs)

bsl::ostream &	operator<< (bsl::ostream &stream, const Datum &rhs)

Member Typedef Documentation

◆ AllocatorType

typedef bsl::allocator bdld::Datum::AllocatorType

◆ SizeType

typedef bsls::Types::size_type bdld::Datum::SizeType

SizeType is an alias for an unsigned integral value, representing the capacity of a datum array, the capacity of a datum map, the capacity of the keys-capacity of a datum-key-owning map or the length of a string.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
k_NUM_TYPES

◆ DataType

enum bdld::Datum::DataType

Enumeration used to discriminate among the different externally- exposed types of values that can be stored inside bdld::Datum.

Enumerator
e_NIL
e_INTEGER
e_DOUBLE
e_STRING
e_BOOLEAN
e_ERROR
e_DATE
e_TIME
e_DATETIME
e_DATETIME_INTERVAL
e_INTEGER64
e_USERDEFINED
e_ARRAY
e_MAP
e_BINARY
e_DECIMAL64
e_INT_MAP
e_REAL
e_ERROR_VALUE

Constructor & Destructor Documentation

◆ Datum() [1/2]

bdld::Datum::Datum ( )

default

Create a datum having an uninitialized value. The behavior for every accessor method is undefined until this object is assigned a value.

◆ Datum() [2/2]

bdld::Datum::Datum ( const Datum & original )

default

Create a datum having the value of the specified original.

◆ ~Datum()

bdld::Datum::~Datum ( )

default

Destroy this object.

Note: Note that this method does not deallocate any dynamically allocated memory used by this object (see destroy).

Member Function Documentation

◆ adoptArray()

Datum bdld::Datum::adoptArray ( const DatumMutableArrayRef & array )

inlinestatic

Return, by value, a datum that refers to the specified array.

Precondition: The behavior is undefined unless array was created using createUninitializedArray method. The behavior is also undefined unless each element in the held datum array has been assigned a value and the array's length has been set accordingly.

Note: Note that the adopted array is owned and will be freed if Datum::destroy is called on the returned object.

◆ adoptIntMap()

Datum bdld::Datum::adoptIntMap ( const DatumMutableIntMapRef & intMap )

inlinestatic

Return, by value, a datum that refers to the specified intMap.

Precondition: The behavior is undefined unless map was created using createUninitializedIntMap method. The behavior is also undefined unless each element in the held map has been assigned a value and the size of the map has been set accordingly.

Note: Note that the adopted map is owned and will be freed if Datum::destroy is called on the returned object.

◆ adoptMap() [1/2]

Datum bdld::Datum::adoptMap ( const DatumMutableMapOwningKeysRef & map )

inlinestatic

Return, by value, a datum that refers to the specified map.

Precondition: The behavior is undefined unless map was created using createUninitializedMapOwningKeys method. The behavior is also undefined unless each element in the held map has been assigned a value and the size of the map has been set accordingly. The behavior is also undefined unless keys have been copied into the map.

Note: Note that the adopted map is owned and will be freed if Datum::destroy is called on the returned object.

◆ adoptMap() [2/2]

Datum bdld::Datum::adoptMap ( const DatumMutableMapRef & map )

inlinestatic

Return, by value, a datum that refers to the specified map.

Precondition: The behavior is undefined unless map was created using createUninitializedMap method. The behavior is also undefined unless each element in the held map has been assigned a value and the size of the map has been set accordingly.

Note: Note that the adopted map is owned and will be freed if Datum::destroy is called on the returned object.

◆ adoptMapOwningKeys()

Datum bdld::Datum::adoptMapOwningKeys ( const DatumMutableMapOwningKeysRef & mapping )

inlinestatic

Deprecated:: Use adoptMap instead.

◆ apply()

template<class t_VISITOR >

void bdld::Datum::apply ( t_VISITOR & visitor ) const

Apply the specified visitor to the current value represented by this object by passing held value to the visitor object's operator() overload.

◆ BSLMF_NESTED_TRAIT_DECLARATION() [1/4]

bdld::Datum::BSLMF_NESTED_TRAIT_DECLARATION	(	Datum	,
		bdlb::HasPrintMethod
	)

◆ BSLMF_NESTED_TRAIT_DECLARATION() [2/4]

bdld::Datum::BSLMF_NESTED_TRAIT_DECLARATION	(	Datum	,
		bsl::is_trivially_copyable
	)

◆ BSLMF_NESTED_TRAIT_DECLARATION() [3/4]

bdld::Datum::BSLMF_NESTED_TRAIT_DECLARATION	(	Datum	,
		bsl::is_trivially_default_constructible
	)

◆ BSLMF_NESTED_TRAIT_DECLARATION() [4/4]

bdld::Datum::BSLMF_NESTED_TRAIT_DECLARATION	(	Datum	,
		bslmf::IsBitwiseMoveable
	)

◆ clone()

Datum bdld::Datum::clone ( const AllocatorType & allocator ) const

Return a datum holding a "deep-copy" of this object, using the specified allocator to supply memory. This method creates an independent deep-copy of the data of this object, including any referenced data, with the exception of {User Defined Types}. For further information see {Deep Copying}.

◆ copyBinary()

static Datum bdld::Datum::copyBinary	(	const void *	value,
		SizeType	size,
		const AllocatorType &	allocator
	)

static

Return, by value, a datum referring to the copy of the specified value of the specified size, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless size <= UINT_MAX.

Note: Note that the copy of the binary data is owned and will be freed if Datum::destroy is called on the returned object.

◆ copyString() [1/2]

Datum bdld::Datum::copyString	(	const bslstl::StringRef &	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum having the copy of the specified StringRef value, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless value.length() <= UINT_MAX.

Note: Note that the copied string is owned, and will be freed if Datum::destroy is called on the returned object.

◆ copyString() [2/2]

static Datum bdld::Datum::copyString	(	const char *	string,
		SizeType	length,
		const AllocatorType &	allocator
	)

static

Return, by value, a datum that refers to the copy of the specified string having the specified length, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless 0 != string || 0 == length. The behavior is also undefined unless length <= UINT_MAX.

Note: Note that the copied string is owned and will be freed if Datum::destroy is called on the returned object.

◆ createArrayReference() [1/2]

Datum bdld::Datum::createArrayReference	(	const Datum *	array,
		SizeType	length,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum referring to the specified array, having the specified length, using the specified allocator to supply memory (if needed). array is not copied, and is not freed when the returned object is destroyed with Datum::destroy.

Precondition: The behavior is undefined unless array contains at least length elements. The behavior is also undefined unless length <= UINT_MAX.

◆ createArrayReference() [2/2]

Datum bdld::Datum::createArrayReference	(	const DatumArrayRef &	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum having the specified value, using the specified allocator to supply memory (if needed). The array referenced by value is not copied, and is not freed if Datum::destroy is called on the returned object.

Precondition: The behavior is undefined unless value.length() <= UINT_MAX.

◆ createBoolean()

Datum bdld::Datum::createBoolean ( bool value )

inlinestatic

Return, by value, a datum having the specified bool value.

◆ createDate()

Datum bdld::Datum::createDate ( const bdlt::Date & value )

inlinestatic

Return, by value, a datum having the specified Date value.

◆ createDatetime()

Datum bdld::Datum::createDatetime	(	const bdlt::Datetime &	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum having the specified Datetime value, using the specified allocator to supply memory (if needed).

◆ createDatetimeInterval()

Datum bdld::Datum::createDatetimeInterval	(	const bdlt::DatetimeInterval &	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum holding the specified DatetimeInterval value, using the specified allocator to supply memory (if needed).

◆ createDecimal64()

static Datum bdld::Datum::createDecimal64	(	bdldfp::Decimal64	value,
		const AllocatorType &	allocator
	)

static

Return, by value, a datum having the specified Decimal64 value, using the specified allocator to supply memory (if needed).

Note: Note that the argument is passed by value because it is assumed to be a fundamental type.

◆ createDouble()

Datum bdld::Datum::createDouble ( double value )

inlinestatic

Return, by value, a datum having the specified double value. When value is NaN this method guarantees only that a NaN value is stored. The sign and NaN payload bits of a NaN value later retrieved by the theDouble method are unspecified (see also {Special Floating Point Values}.

◆ createError() [1/2]

Datum bdld::Datum::createError ( int code )

inlinestatic

Return, by value, a datum having a DatumError value with the specified code.

◆ createError() [2/2]

static Datum bdld::Datum::createError	(	int	code,
		const bslstl::StringRef &	message,
		const AllocatorType &	allocator
	)

static

Return, by value, a datum having a DatumError value with the specified code and the specified message, using the specified allocator to supply memory (if needed).

◆ createInteger()

Datum bdld::Datum::createInteger ( int value )

inlinestatic

Return, by value, a datum having the specified int value.

◆ createInteger64()

Datum bdld::Datum::createInteger64	(	bsls::Types::Int64	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum having the specified Integer64 value, using the specified allocator to supply memory (if needed).

◆ createNull()

Datum bdld::Datum::createNull ( )

inlinestatic

Return, by value, a datum having no value.

◆ createStringRef() [1/3]

Datum bdld::Datum::createStringRef	(	const bslstl::StringRef &	value,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum having the specified StringRef value, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless value.length() <= UINT_MAX.

Note: Note that string is not copied, and is not freed if Datum::destroy is called on the returned object.

◆ createStringRef() [2/3]

Datum bdld::Datum::createStringRef	(	const char *	string,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum that refers to the specified string, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless string points to a UTF-8 encoded c-string. The behavior is also undefined unless 'strlen(string) <= UINT_MAX'.

Note: Note that string is not copied, and is not freed if Datum::destroy is called on the returned object.

◆ createStringRef() [3/3]

Datum bdld::Datum::createStringRef	(	const char *	string,
		SizeType	length,
		const AllocatorType &	allocator
	)

inlinestatic

Return, by value, a datum that refers to the specified string having the specified length, using the specified allocator to supply memory (if needed).

Precondition: The behavior is undefined unless 0 != string || 0 == length. The behavior is also undefined unless length <= UINT_MAX.

Note: Note that string is not copied, and is not freed if Datum::destroy is called on the returned object.

◆ createTime()

Datum bdld::Datum::createTime ( const bdlt::Time & value )

inlinestatic

Return, by value, a datum having the specified Time value.

◆ createUdt()

Datum bdld::Datum::createUdt	(	void *	data,
		int	type
	)

inlinestatic

Return, by value, a datum having the DatumUdt value with the specified data and the specified type values.

Precondition: The behavior is undefined unless 0 <= type <= 65535.

Note: Note that data is held, not owned. Also note that the content pointed to by data object is not copied.

◆ createUninitializedArray()

static void bdld::Datum::createUninitializedArray	(	DatumMutableArrayRef *	result,
		SizeType	capacity,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created datum array having the specified capacity, using the specified allocator to supply memory.

Precondition: The behavior is undefined if capacity Datum objects would exceed the addressable memory for the platform.

Note: Note that the caller is responsible for filling in elements into the datum array and setting its length accordingly. The number of elements in the datum array cannot exceed capacity. Also note that any elements in the datum array that need dynamic memory must be allocated with allocator.

◆ createUninitializedBinary()

static void * bdld::Datum::createUninitializedBinary	(	Datum *	result,
		SizeType	size,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created binary buffer of the specified size, using the specified allocator to supply memory, and return the address of this buffer.

Precondition: The behavior is undefined unless size <= UINT_MAX.

Note: Note that the caller is responsible for initializing the returned buffer with binary data.

◆ createUninitializedIntMap()

static void bdld::Datum::createUninitializedIntMap	(	DatumMutableIntMapRef *	result,
		SizeType	capacity,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created datum int-map having the specified capacity, using the specified allocator to supply memory.

Precondition: The behavior is undefined if capacity DatumIntMapEntry objects would exceed the addressable memory for the platform.

Note: Note that the caller is responsible for filling in elements into the datum int-map and setting its size accordingly. The number of elements in the datum int-map cannot exceed capacity. Also note that any elements in the datum int-map that need dynamic memory, should also be allocated with allocator.

◆ createUninitializedMap() [1/2]

static void bdld::Datum::createUninitializedMap	(	DatumMutableMapOwningKeysRef *	result,
		SizeType	capacity,
		SizeType	keysCapacity,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created datum-key-owning map having the specified capacity and keysCapacity, using the specified allocator to supply memory.

Precondition: The behavior is undefined if capacity DatumMapEntry object plus keysCapacity would exceed the addressable memory for the platform.

Note: Note that the caller is responsible for filling in elements into the datum-key-owning map, copying the keys into it, and setting its size accordingly. The number of elements in the datum-key-owning map cannot exceed capacity and total size of all the keys cannot exceed keysCapacity. Also note that any elements in the datum-key-owning map that need dynamic memory, should also be allocated with allocator.

◆ createUninitializedMap() [2/2]

static void bdld::Datum::createUninitializedMap	(	DatumMutableMapRef *	result,
		SizeType	capacity,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created datum map having the specified capacity, using the specified allocator to supply memory.

Precondition: The behavior is undefined if capacity DatumMapEntry objects would exceed the addressable memory for the platform.

Note: Note that the caller is responsible for filling in elements into the datum map and setting its size accordingly. The number of elements in the datum map cannot exceed capacity. Also note that any elements in the datum map that need dynamic memory, should also be allocated with allocator.

◆ createUninitializedMapOwningKeys()

void bdld::Datum::createUninitializedMapOwningKeys	(	DatumMutableMapOwningKeysRef *	result,
		SizeType	capacity,
		SizeType	keysCapacity,
		const AllocatorType &	allocator
	)

inlinestatic

Deprecated:: Use createUninitializedMap instead.

◆ createUninitializedString()

static char * bdld::Datum::createUninitializedString	(	Datum *	result,
		SizeType	length,
		const AllocatorType &	allocator
	)

static

Load the specified result with a reference to a newly created character buffer of the specified length, using the specified allocator to supply memory, and return the address of this buffer.

Precondition: The behavior is undefined unless length <= UINT_MAX.

Note: Note that the caller is responsible for initializing the returned buffer with a UTF-8 encoded string.

◆ dataTypeToAscii()

static const char * bdld::Datum::dataTypeToAscii ( DataType type )

static

Return the non-modifiable string representation corresponding to the specified type, if it exists, and a unique (error) string otherwise. The string representation of type matches its corresponding enumerator name with the e_ prefix elided.

For example:

bsl::cout << bdld::Datum::dataTypeToAscii(bdld::Datum::e_NIL);

bdld::Datum::dataTypeToAscii

static const char * dataTypeToAscii(DataType type)

bdld::Datum::e_NIL

@ e_NIL

Definition bdld_datum.h:812

will print the following on standard output:

NIL

Note: Note that specifying a type that does not match any of the enumerators will result in a string representation that is distinct from any of those corresponding to the enumerators, but is otherwise unspecified.

◆ destroy()

static void bdld::Datum::destroy	(	const Datum &	value,
		const AllocatorType &	allocator
	)

static

Deallocate any memory that was previously allocated within the specified value using the specified allocator. If the value contains an adopted array of datums, destroy is called on each array element. If the value contains an adopted map of datums, destroy is called on each map element.

Precondition: The behavior is undefined unless all dynamically allocated memory owned by value was allocated using allocator, and has not previously been released by a call to destroy, either on this object, or on another object referring to same contents as this object (i.e., only one copy of a Datum object can be destroyed). The behavior is also undefined if value has an uninitialized or partially initialized array or map (created using createUninitializedArray, createUninitializedMap or createUninitializeMapOwningKeys).

Note: Note that after this operation completes, value is left in an uninitialized state, and must be assigned a new value before being accessed again.

◆ disposeUninitializedArray()

void bdld::Datum::disposeUninitializedArray	(	const DatumMutableArrayRef &	array,
		const AllocatorType &	allocator
	)

inlinestatic

Deallocate the memory used by the specified array (but not memory allocated for its contained elements) using the specified allocator. This method does not destroy individual array elements and the memory allocated for those elements must be explicitly deallocated before calling this method.

Precondition: The behavior is undefined unless array was created with createUninitializedArray using allocator.

◆ disposeUninitializedIntMap()

void bdld::Datum::disposeUninitializedIntMap	(	const DatumMutableIntMapRef &	intMap,
		const AllocatorType &	allocator
	)

inlinestatic

Deallocate the memory used by the specified intMap (but not memory allocated for its contained elements) using the specified allocator. This method does not destroy individual map elements and the memory allocated for those elements must be explicitly deallocated before calling this method.

Precondition: The behavior is undefined unless map was created with createUninitializedIntMap using allocator.

◆ disposeUninitializedMap() [1/2]

void bdld::Datum::disposeUninitializedMap	(	const DatumMutableMapOwningKeysRef &	map,
		const AllocatorType &	allocator
	)

inlinestatic

◆ disposeUninitializedMap() [2/2]

void bdld::Datum::disposeUninitializedMap	(	const DatumMutableMapRef &	map,
		const AllocatorType &	allocator
	)

inlinestatic

Deallocate the memory used by the specified map (but not memory allocated for its contained elements) using the specified allocator. This method does not destroy individual map elements and the memory allocated for those elements must be explicitly deallocated before calling this method.

Precondition: The behavior is undefined unless map was created with createUninitializedMap using allocator.

◆ disposeUninitializedMapOwningKeys()

void bdld::Datum::disposeUninitializedMapOwningKeys	(	const DatumMutableMapOwningKeysRef &	mapping,
		const AllocatorType &	allocator
	)

inlinestatic

Deprecated:: Use disposeUninitializedMap instead.

◆ isArray()

bool bdld::Datum::isArray ( ) const

inline

Return true if this object represents an array of Datums and false otherwise.

◆ isBinary()

bool bdld::Datum::isBinary ( ) const

inline

Return true if this object represents a binary value and false otherwise.

◆ isBoolean()

bool bdld::Datum::isBoolean ( ) const

inline

Return true if this object represents a boolean value and false otherwise.

◆ isDate()

bool bdld::Datum::isDate ( ) const

inline

Return true if this object represents a bdlt::Date value and false otherwise.

◆ isDatetime()

bool bdld::Datum::isDatetime ( ) const

inline

Return true if this object represents a bdlt::Datetime value and false otherwise.

◆ isDatetimeInterval()

bool bdld::Datum::isDatetimeInterval ( ) const

inline

Return true if this object represents a bdlt::DatetimeInterval value and false otherwise.

◆ isDecimal64()

bool bdld::Datum::isDecimal64 ( ) const

inline

Return true if this object represents a bdlfpd::Decimal64 value and false otherwise.

◆ isDouble()

bool bdld::Datum::isDouble ( ) const

inline

Return true if this object represents a double value and false otherwise.

◆ isError()

bool bdld::Datum::isError ( ) const

inline

Return true if this object represents a DatumError value and false otherwise.

◆ isExternalReference()

bool bdld::Datum::isExternalReference ( ) const

inline

Return true if this object represents a reference to an externally managed array, string or user-defined object and false otherwise. If this method returns false, calling destroy on this object will release the memory used by the array, string, or used-defined object as well as any meta-data directly used by this datum (e.g., length information); otherwise (if this method returns true) calling destroy on this object will release any allocated meta-data, but will not impact the externally managed array, string, or user-defined object.

◆ isInteger()

bool bdld::Datum::isInteger ( ) const

inline

Return true if this object represents an integer value and false otherwise.

◆ isInteger64()

bool bdld::Datum::isInteger64 ( ) const

inline

Return true if this object represents a Int64 value and false otherwise.

◆ isIntMap()

bool bdld::Datum::isIntMap ( ) const

inline

Return true if this object represents a map of datums that are keyed by 32-bit int values and false otherwise.

◆ isMap()

bool bdld::Datum::isMap ( ) const

inline

Return true if this object represents a map of datums that are keyed by string values and false otherwise.

◆ isNull()

bool bdld::Datum::isNull ( ) const

inline

Return true if this object represents no value and false otherwise.

◆ isString()

bool bdld::Datum::isString ( ) const

inline

Return true if this object represents a string value and false otherwise.

◆ isTime()

bool bdld::Datum::isTime ( ) const

inline

Return true if this object represents a bdlt::Time value and false otherwise.

◆ isUdt()

bool bdld::Datum::isUdt ( ) const

inline

Return true if this object represents a DatumUdt value and false otherwise.

◆ operator=()

Datum & bdld::Datum::operator= ( const Datum & rhs )

default

◆ print()

bsl::ostream & bdld::Datum::print	(	bsl::ostream &	stream,
		int	level = `0`,
		int	spacesPerLevel = `4`
	)		const

Write the value of this object to the specified output stream in a human-readable format, and return a reference to the modifiable stream. Optionally specify an initial indentation level, whose absolute value is incremented recursively for nested objects. If level is specified, optionally specify spacesPerLevel, whose absolute value indicates the number of spaces per indentation level for this and all of its nested objects. If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by level). If stream is not valid on entry, this operation has no effect.

Note: Note that this human-readable format is not fully specified, and can change without notice.

◆ theArray()

DatumArrayRef bdld::Datum::theArray ( ) const

inline

Return the array value represented by this object as a DatumArrayRef object.

Precondition: The behavior is undefined unless this object actually represents an array of datums.

◆ theBinary()

DatumBinaryRef bdld::Datum::theBinary ( ) const

inline

Return the binary reference represented by this object as a DatumBinaryRef object.

Precondition: The behavior is undefined unless this object actually represents a binary reference.

◆ theBoolean()

bool bdld::Datum::theBoolean ( ) const

inline

Return the boolean value represented by this object.

Precondition: The behavior is undefined unless this object actually represents a bool value.

◆ theDate()

bdlt::Date bdld::Datum::theDate ( ) const

inline

Return the date value represented by this object as a bdlt::Date object.

Precondition: The behavior is undefined unless this object actually represents a date value.

◆ theDatetime()

bdlt::Datetime bdld::Datum::theDatetime ( ) const

inline

Return the date+time value represented by this object as a bdlt::Datetime object.

Precondition: The behavior is undefined unless this object actually represents date+time value.

◆ theDatetimeInterval()

bdlt::DatetimeInterval bdld::Datum::theDatetimeInterval ( ) const

inline

Return the date+time interval value represented by this object as a bdlt::DatetimeInterval.

Precondition: The behavior is undefined unless this object actually represents a date+time interval value.

◆ theDecimal64()

bdldfp::Decimal64 bdld::Datum::theDecimal64 ( ) const

Return the decimal floating point value represented by this object as a bdlfpd::Decimal64 value.

Precondition: The behavior is undefined unless this object actually represents a decimal floating point value.

◆ theDouble()

double bdld::Datum::theDouble ( ) const

inline

Return the double value represented by this object.

Precondition: The behavior is undefined unless this object actually represents a double value. If the returned value is NaN this method guarantees only that a NaN value will be returned. The sign and NaN payload bits of NaN values returned are unspecified (see also {Special Floating Point Values}.

◆ theError()

DatumError bdld::Datum::theError ( ) const

inline

Return the error value represented by this object as a DatumError value.

Precondition: The behavior is undefined unless this object actually represents an error value.

◆ theInteger()

int bdld::Datum::theInteger ( ) const

inline

Return the integer value represented by this object.

Precondition: The behavior is undefined unless this object actually represents an integer value.

◆ theInteger64()

bsls::Types::Int64 bdld::Datum::theInteger64 ( ) const

inline

Return the 64-bit integer value represented by this object as a Int64 value.

Precondition: The behavior is undefined unless this object actually represents a 64-bit integer value.

◆ theIntMap()

DatumIntMapRef bdld::Datum::theIntMap ( ) const

inline

Return the int-map value represented by this object as a DatumIntMapRef object.

Precondition: The behavior is undefined unless this object actually represents an int-map of datums.

◆ theMap()

DatumMapRef bdld::Datum::theMap ( ) const

inline

Return the map value represented by this object as a DatumMapRef object.

Precondition: The behavior is undefined unless this object actually represents a map of datums.

◆ theString()

bslstl::StringRef bdld::Datum::theString ( ) const

inline

Return the string value represented by this object as a bslstl::StringRef object.

Precondition: The behavior is undefined unless this object actually represents a string value.

◆ theTime()

bdlt::Time bdld::Datum::theTime ( ) const

inline

Return the time value represented by this object as a bdlt::Time object.

Precondition: The behavior is undefined unless this object actually represents a time value.

◆ theUdt()

DatumUdt bdld::Datum::theUdt ( ) const

inline

Return the user-defined object represented by this object as a DatumUdt object.

Precondition: The behavior is undefined unless this object actually represents a user-defined object.

◆ type()

Datum::DataType bdld::Datum::type ( ) const

inline

Return the type of value represented by this object as one of the enumeration values defined in DataType.

Friends And Related Symbol Documentation

◆ operator!=

bool operator!=	(	const Datum &	lhs,
		const Datum &	rhs
	)

friend

Return true if the specified lhs and rhs datums do not represent the same value, and false otherwise. Two datums do not represent the same value if they do not hold values of the same type, or they hold values of the same type but invoking == operator on the stored values returns false. Two strings do not have the same value if they have different lengths or values at one of the respective character position are not the same. Two DatumUdt objects are not equal if they have different pointer or type values. Two bslmf::Nil values are always equal. Two datums with NaN values are never equal. Two datums that hold arrays of datums have different values if the underlying arrays have different lengths or invoking == operator on at least one of the corresponding pair of contained elements returns false. Two datums that hold maps of datums have different values if the underlying maps have different sizes or at least one of the corresponding pair of elements in the maps have different keys or invoking == operator on the values returns false.

◆ operator<<

bsl::ostream & operator<<	(	bsl::ostream &	stream,
		const Datum &	rhs
	)

friend

Write the specified rhs value to the specified output stream in the format shown in the second column in the table below (based on the type of value stored, indicated by the first column):

null                   - nil
 
bool                   - true/false
 
DatumError             - error(code)/error(code, `msg`)
                         where `code` is the integer error code and
                         `msg` is the error description message
 
int                    - plain integer value
 
Int64                  - plain Int64 value
 
double                 - plain double value
 
string                 - plain double-quoted string value
 
array                  - [ elem0, ..., elemN]
                         where elem1..elemN are output for individual
                         array elements
 
int-map                - [key0 = val0, ..., keyN = valN]
                         where keyX and valX are respectively key and
                         value of the map entry elements of the map
 
map                    - [key0 = val0, ..., keyN = valN]
                         where keyX and valX are respectively key and
                         value of the map entry elements of the map
 
bdlt::Date             - ddMONyyyy
 
bdlt::Time             - hh:mm:ss.sss
 
bdlt::Datetime         - ddMONyyyy_hh:mm:ss.sss
 
bdlt::DatetimeInterval - sDD_HH:MM:SS.SSS (where s is the sign(+/-))
 
DatumUdt               - user-defined(address,type)
                         where `address` is a hex encoded pointer to
                         the user-defined object and `type` is its type

and return a reference to the modifiable stream. The function will have no effect if the specified stream is not valid.

◆ operator==

bool operator==	(	const Datum &	lhs,
		const Datum &	rhs
	)

friend

Return true if the specified lhs and rhs represent the same value, and false otherwise. Two datums (not holding strings and user- defined objects) represent the same value if they have the same type of value stored inside them and invoking == operator on the stored values returns true. Two datums holding strings are equal if the strings have the same length and and values at each respective character position are also same. Two datums holding user-defined objects are equal if the user-defined objects have the same pointer and type values. Two nil datums are always equal. Two Datum objects holding NaN values are never equal. Two datums that hold arrays of datums have the same value if the underlying arrays have the same length and invoking == operator on each corresponding element returns true. Two datums that hold maps of datums have the same value if the underlying maps have the same size and each corresponding pair of elements in the maps have the same keys and invoking == operator on the values returns true.

Member Data Documentation

◆ d_as

TypedAccess bdld::Datum::d_as

◆ d_data

bsls::AlignedBuffer<16> bdld::Datum::d_data

The documentation for this class was generated from the following file:

bdld_datum.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Friends

Member Typedef Documentation

◆ AllocatorType

◆ SizeType

Member Enumeration Documentation

◆ anonymous enum

◆ DataType

Constructor & Destructor Documentation

◆ Datum() [1/2]

◆ Datum() [2/2]

◆ ~Datum()

Member Function Documentation

◆ adoptArray()

◆ adoptIntMap()

◆ adoptMap() [1/2]

◆ adoptMap() [2/2]

◆ adoptMapOwningKeys()

◆ apply()

◆ BSLMF_NESTED_TRAIT_DECLARATION() [1/4]

◆ BSLMF_NESTED_TRAIT_DECLARATION() [2/4]

◆ BSLMF_NESTED_TRAIT_DECLARATION() [3/4]

◆ BSLMF_NESTED_TRAIT_DECLARATION() [4/4]

◆ clone()

◆ copyBinary()

◆ copyString() [1/2]

◆ copyString() [2/2]

◆ createArrayReference() [1/2]

◆ createArrayReference() [2/2]

◆ createBoolean()

◆ createDate()

◆ createDatetime()

◆ createDatetimeInterval()

◆ createDecimal64()

◆ createDouble()

◆ createError() [1/2]

◆ createError() [2/2]

◆ createInteger()

◆ createInteger64()

◆ createNull()

◆ createStringRef() [1/3]

◆ createStringRef() [2/3]

◆ createStringRef() [3/3]

◆ createTime()

◆ createUdt()

◆ createUninitializedArray()

◆ createUninitializedBinary()

◆ createUninitializedIntMap()

◆ createUninitializedMap() [1/2]

◆ createUninitializedMap() [2/2]

◆ createUninitializedMapOwningKeys()

◆ createUninitializedString()

◆ dataTypeToAscii()

◆ destroy()

◆ disposeUninitializedArray()

◆ disposeUninitializedIntMap()

◆ disposeUninitializedMap() [1/2]

◆ disposeUninitializedMap() [2/2]

◆ disposeUninitializedMapOwningKeys()

◆ isArray()

◆ isBinary()

◆ isBoolean()

◆ isDate()

◆ isDatetime()

◆ isDatetimeInterval()

◆ isDecimal64()

◆ isDouble()

◆ isError()

◆ isExternalReference()

◆ isInteger()

◆ isInteger64()

◆ isIntMap()

◆ isMap()

◆ isNull()

◆ isString()

◆ isTime()

◆ isUdt()