[#BloombergLP-bdld-Datum]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdld.adoc[bdld]::Datum
:relfileprefix: ../../
:mrdocs:

Space‐efficient discriminated union holding a scalar or aggregate of `Datum` values.

== Synopsis

Declared in `<bdld_datum.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Datum;
----

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

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/Datum/AllocatorType.adoc[`AllocatorType`] 
| This `typedef` is an alias for `AllocatorType`.
| xref:BloombergLP/bdld/Datum/SizeType.adoc[`SizeType`] 
| Unsigned integral type for capacities, key sizes, and string lengths.
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/Datum/_04enum.adoc[`Unnamed enum`] 
| Number of distinct externally exposed datum types.
| xref:BloombergLP/bdld/Datum/DataType.adoc[`DataType`] 
| Enumeration used to discriminate among the different externally‐ exposed types of values that can be stored inside `bdld::Datum`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/Datum/apply.adoc[`apply`] 
| Invoke `visitor` on the value currently held by this object.
| xref:BloombergLP/bdld/Datum/clone.adoc[`clone`] 
| Return a deep copy of this datum using the specified `allocator`.
| xref:BloombergLP/bdld/Datum/isArray.adoc[`isArray`] 
| Return `true` if this object represents an array of `Datum`s and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isBinary.adoc[`isBinary`] 
| Return `true` if this object represents a binary value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isBoolean.adoc[`isBoolean`] 
| Return `true` if this object represents a boolean value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isDate.adoc[`isDate`] 
| Return `true` if this object represents a `bdlt::Date` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isDatetime.adoc[`isDatetime`] 
| Return `true` if this object represents a `bdlt::Datetime` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isDatetimeInterval.adoc[`isDatetimeInterval`] 
| Return `true` if this object represents a `bdlt::DatetimeInterval` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isDecimal64.adoc[`isDecimal64`] 
| Return `true` if this object represents a `bdlfpd::Decimal64` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isDouble.adoc[`isDouble`] 
| Return `true` if this object represents a `double` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isError.adoc[`isError`] 
| Return `true` if this object represents a `DatumError` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isExternalReference.adoc[`isExternalReference`] 
| Return whether this object refers to externally managed data.
| xref:BloombergLP/bdld/Datum/isIntMap.adoc[`isIntMap`] 
| Return `true` if this object represents a map of datums that are keyed by 32‐bit int values and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isInteger.adoc[`isInteger`] 
| Return `true` if this object represents an integer value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isInteger64.adoc[`isInteger64`] 
| Return `true` if this object represents a `Int64` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isMap.adoc[`isMap`] 
| Return `true` if this object represents a map of datums that are keyed by string values and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isNull.adoc[`isNull`] 
| Return `true` if this object represents no value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isString.adoc[`isString`] 
| Return `true` if this object represents a string value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isTime.adoc[`isTime`] 
| Return `true` if this object represents a `bdlt::Time` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/isUdt.adoc[`isUdt`] 
| Return `true` if this object represents a `DatumUdt` value and `false` otherwise.
| xref:BloombergLP/bdld/Datum/print.adoc[`print`] 
| Format this object to the specified output stream.
| xref:BloombergLP/bdld/Datum/theArray.adoc[`theArray`] 
| Return the array value held by this object.
| xref:BloombergLP/bdld/Datum/theBinary.adoc[`theBinary`] 
| Return the binary reference held by this object.
| xref:BloombergLP/bdld/Datum/theBoolean.adoc[`theBoolean`] 
| Return the boolean value represented by this object. The behavior is undefined unless this object actually represents a `bool` value.
| xref:BloombergLP/bdld/Datum/theDate.adoc[`theDate`] 
| Return the date value represented by this object as a `bdlt::Date` object. The behavior is undefined unless this object actually represents a date value.
| xref:BloombergLP/bdld/Datum/theDatetime.adoc[`theDatetime`] 
| Return the datetime value held by this object.
| xref:BloombergLP/bdld/Datum/theDatetimeInterval.adoc[`theDatetimeInterval`] 
| Return the datetime‐interval value held by this object.
| xref:BloombergLP/bdld/Datum/theDecimal64.adoc[`theDecimal64`] 
| Return the Decimal64 value held by this object.
| xref:BloombergLP/bdld/Datum/theDouble.adoc[`theDouble`] 
| Return the double value held by this object.
| xref:BloombergLP/bdld/Datum/theError.adoc[`theError`] 
| Return the error value represented by this object as a `DatumError` value. The behavior is undefined unless this object actually represents an error value.
| xref:BloombergLP/bdld/Datum/theIntMap.adoc[`theIntMap`] 
| Return the int‐map value held by this object.
| xref:BloombergLP/bdld/Datum/theInteger.adoc[`theInteger`] 
| Return the integer value represented by this object. The behavior is undefined unless this object actually represents an integer value.
| xref:BloombergLP/bdld/Datum/theInteger64.adoc[`theInteger64`] 
| Return the 64‐bit integer value held by this object.
| xref:BloombergLP/bdld/Datum/theMap.adoc[`theMap`] 
| Return the map value represented by this object as a `DatumMapRef` object. The behavior is undefined unless this object actually represents a map of datums.
| xref:BloombergLP/bdld/Datum/theString.adoc[`theString`] 
| Return the string value held by this object.
| xref:BloombergLP/bdld/Datum/theTime.adoc[`theTime`] 
| Return the time value represented by this object as a `bdlt::Time` object. The behavior is undefined unless this object actually represents a time value.
| xref:BloombergLP/bdld/Datum/theUdt.adoc[`theUdt`] 
| Return the user‐defined type reference held by this object.
| xref:BloombergLP/bdld/Datum/type.adoc[`type`] 
| Return the type of value represented by this object as one of the enumeration values defined in `DataType`.
| xref:BloombergLP/bdld/Datum/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Datum, HasPrintMethod>`] 
| Declare nested type traits for this type.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/Datum/adoptArray.adoc[`adoptArray`] 
| Return a datum that takes ownership of the specified `array`.
| xref:BloombergLP/bdld/Datum/adoptIntMap.adoc[`adoptIntMap`] 
| Return a datum that takes ownership of the specified `intMap`.
| xref:BloombergLP/bdld/Datum/adoptMap-0a.adoc[`adoptMap`] 
| `adoptMap` overloads
| xref:BloombergLP/bdld/Datum/adoptMapOwningKeys.adoc[`adoptMapOwningKeys`] 
| DEPRECATED: Use `adoptMap` instead.
| xref:BloombergLP/bdld/Datum/copyBinary.adoc[`copyBinary`] 
| Return a datum owning a copy of the specified binary `value`.
| xref:BloombergLP/bdld/Datum/copyString-04.adoc[`copyString`] 
| `copyString` overloads
| xref:BloombergLP/bdld/Datum/createArrayReference-02.adoc[`createArrayReference`] 
| `createArrayReference` overloads
| xref:BloombergLP/bdld/Datum/createBoolean.adoc[`createBoolean`] 
| Return a datum holding the specified boolean `value`.
| xref:BloombergLP/bdld/Datum/createDate.adoc[`createDate`] 
| Return a datum holding the specified date `value`.
| xref:BloombergLP/bdld/Datum/createDatetime.adoc[`createDatetime`] 
| Return a datum holding the specified datetime `value`.
| xref:BloombergLP/bdld/Datum/createDatetimeInterval.adoc[`createDatetimeInterval`] 
| Return a datum holding the specified datetime‐interval `value`.
| xref:BloombergLP/bdld/Datum/createDecimal64.adoc[`createDecimal64`] 
| Return a datum holding the specified Decimal64 `value`.
| xref:BloombergLP/bdld/Datum/createDouble.adoc[`createDouble`] 
| Return a datum holding the specified double `value`.
| xref:BloombergLP/bdld/Datum/createError-04.adoc[`createError`] 
| `createError` overloads
| xref:BloombergLP/bdld/Datum/createInteger.adoc[`createInteger`] 
| Return a datum holding the specified integer `value`.
| xref:BloombergLP/bdld/Datum/createInteger64.adoc[`createInteger64`] 
| Return a datum holding the specified 64‐bit integer `value`.
| xref:BloombergLP/bdld/Datum/createNull.adoc[`createNull`] 
| Return, by value, a datum having no value.
| xref:BloombergLP/bdld/Datum/createStringRef-04e.adoc[`createStringRef`] 
| `createStringRef` overloads
| xref:BloombergLP/bdld/Datum/createTime.adoc[`createTime`] 
| Return a datum holding the specified time `value`.
| xref:BloombergLP/bdld/Datum/createUdt.adoc[`createUdt`] 
| Return a datum holding a user‐defined type reference.
| xref:BloombergLP/bdld/Datum/createUninitializedArray.adoc[`createUninitializedArray`] 
| Create an uninitialized datum array and load a reference into `result`.
| xref:BloombergLP/bdld/Datum/createUninitializedBinary.adoc[`createUninitializedBinary`] 
| Create an uninitialized binary buffer and load a datum referring to it.
| xref:BloombergLP/bdld/Datum/createUninitializedIntMap.adoc[`createUninitializedIntMap`] 
| Create an uninitialized datum int‐map and load a reference into `result`.
| xref:BloombergLP/bdld/Datum/createUninitializedMap-0ec.adoc[`createUninitializedMap`] 
| `createUninitializedMap` overloads
| xref:BloombergLP/bdld/Datum/createUninitializedMapOwningKeys.adoc[`createUninitializedMapOwningKeys`] 
| DEPRECATED: Use `createUninitializedMap` instead.
| xref:BloombergLP/bdld/Datum/createUninitializedString.adoc[`createUninitializedString`] 
| Create an uninitialized string buffer and load a datum referring to it.
| xref:BloombergLP/bdld/Datum/dataTypeToAscii.adoc[`dataTypeToAscii`] 
| Return the ASCII name corresponding to the specified `type`.
| xref:BloombergLP/bdld/Datum/destroy.adoc[`destroy`] 
| Destroy `value` and deallocate any memory it owns via `allocator`.
| xref:BloombergLP/bdld/Datum/disposeUninitializedArray.adoc[`disposeUninitializedArray`] 
| Deallocate the storage of an uninitialized array without destroying elements.
| xref:BloombergLP/bdld/Datum/disposeUninitializedIntMap.adoc[`disposeUninitializedIntMap`] 
| Deallocate the storage of an uninitialized int‐map without destroying entries.
| xref:BloombergLP/bdld/Datum/disposeUninitializedMap-05a.adoc[`disposeUninitializedMap`] 
| `disposeUninitializedMap` overloads
| xref:BloombergLP/bdld/Datum/disposeUninitializedMapOwningKeys.adoc[`disposeUninitializedMapOwningKeys`] 
| DEPRECATED: Use `disposeUninitializedMap` instead.
|===


== Data Members

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/Datum/d_as.adoc[`d_as`] [.small]#[variant member]#
| Typed access to the datum representation.
| xref:BloombergLP/bdld/Datum/d_data.adoc[`d_data`] [.small]#[variant member]#
| Raw storage for the datum representation.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdld/operator_lshift-015.adoc[BloombergLP::bdld::operator<<]`
| Write the specified `rhs` datum to the specified output `stream`.
| `xref:BloombergLP/bdld/operator_not_eq-08.adoc[BloombergLP::bdld::operator!=]`
| Return whether `lhs` and `rhs` represent different values.
| `xref:BloombergLP/bdld/operator_eq-06.adoc[BloombergLP::bdld::operator==]`
| Return whether `lhs` and `rhs` represent the same value.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#