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

Space&hyphen;efficient discriminated union holding a scalar or aggregate of `Datum` values&period;

== Synopsis

Declared in `&lt;bdld&lowbar;datum&period;h&gt;`

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

== Description

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

Representation on a 32&hyphen;bit Platforms&colon; Values are stored inside an 8&hyphen;byte unsigned char array (`d&lowbar;data`)&period; Any `double` value (including NaN and infinity values) can be stored inside `Datum`&period; When storing a value of a type other than `double`, the bits in `d&lowbar;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&period;

Representation on 64&hyphen;bit platforms&colon; Values are stored inside a 16 byte unsigned char array (`d&lowbar;data`) to store values&period; The type information is stored in the upper 2 bytes of the character array&period; Remaining 14 bytes are used to store the actual value or the pointer to the external memory that holds the value&period;

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&lowbar;datum&period;cpp`&period;

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

== Type Aliases

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


== Enums

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


== Member Functions

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


== 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`&period;
| xref:BloombergLP/bdld/Datum/adoptIntMap.adoc[`adoptIntMap`] 
| Return a datum that takes ownership of the specified `intMap`&period;
| xref:BloombergLP/bdld/Datum/adoptMap-0a.adoc[`adoptMap`] 
| `adoptMap` overloads
| xref:BloombergLP/bdld/Datum/adoptMapOwningKeys.adoc[`adoptMapOwningKeys`] 
| DEPRECATED&colon; Use `adoptMap` instead&period;
| xref:BloombergLP/bdld/Datum/copyBinary.adoc[`copyBinary`] 
| Return a datum owning a copy of the specified binary `value`&period;
| 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`&period;
| xref:BloombergLP/bdld/Datum/createDate.adoc[`createDate`] 
| Return a datum holding the specified date `value`&period;
| xref:BloombergLP/bdld/Datum/createDatetime.adoc[`createDatetime`] 
| Return a datum holding the specified datetime `value`&period;
| xref:BloombergLP/bdld/Datum/createDatetimeInterval.adoc[`createDatetimeInterval`] 
| Return a datum holding the specified datetime&hyphen;interval `value`&period;
| xref:BloombergLP/bdld/Datum/createDecimal64.adoc[`createDecimal64`] 
| Return a datum holding the specified Decimal64 `value`&period;
| xref:BloombergLP/bdld/Datum/createDouble.adoc[`createDouble`] 
| Return a datum holding the specified double `value`&period;
| 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`&period;
| xref:BloombergLP/bdld/Datum/createInteger64.adoc[`createInteger64`] 
| Return a datum holding the specified 64&hyphen;bit integer `value`&period;
| xref:BloombergLP/bdld/Datum/createNull.adoc[`createNull`] 
| Return, by value, a datum having no value&period;
| 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`&period;
| xref:BloombergLP/bdld/Datum/createUdt.adoc[`createUdt`] 
| Return a datum holding a user&hyphen;defined type reference&period;
| xref:BloombergLP/bdld/Datum/createUninitializedArray.adoc[`createUninitializedArray`] 
| Create an uninitialized datum array and load a reference into `result`&period;
| xref:BloombergLP/bdld/Datum/createUninitializedBinary.adoc[`createUninitializedBinary`] 
| Create an uninitialized binary buffer and load a datum referring to it&period;
| xref:BloombergLP/bdld/Datum/createUninitializedIntMap.adoc[`createUninitializedIntMap`] 
| Create an uninitialized datum int&hyphen;map and load a reference into `result`&period;
| xref:BloombergLP/bdld/Datum/createUninitializedMap-0ec.adoc[`createUninitializedMap`] 
| `createUninitializedMap` overloads
| xref:BloombergLP/bdld/Datum/createUninitializedMapOwningKeys.adoc[`createUninitializedMapOwningKeys`] 
| DEPRECATED&colon; Use `createUninitializedMap` instead&period;
| xref:BloombergLP/bdld/Datum/createUninitializedString.adoc[`createUninitializedString`] 
| Create an uninitialized string buffer and load a datum referring to it&period;
| xref:BloombergLP/bdld/Datum/dataTypeToAscii.adoc[`dataTypeToAscii`] 
| Return the ASCII name corresponding to the specified `type`&period;
| xref:BloombergLP/bdld/Datum/destroy.adoc[`destroy`] 
| Destroy `value` and deallocate any memory it owns via `allocator`&period;
| xref:BloombergLP/bdld/Datum/disposeUninitializedArray.adoc[`disposeUninitializedArray`] 
| Deallocate the storage of an uninitialized array without destroying elements&period;
| xref:BloombergLP/bdld/Datum/disposeUninitializedIntMap.adoc[`disposeUninitializedIntMap`] 
| Deallocate the storage of an uninitialized int&hyphen;map without destroying entries&period;
| xref:BloombergLP/bdld/Datum/disposeUninitializedMap-05a.adoc[`disposeUninitializedMap`] 
| `disposeUninitializedMap` overloads
| xref:BloombergLP/bdld/Datum/disposeUninitializedMapOwningKeys.adoc[`disposeUninitializedMapOwningKeys`] 
| DEPRECATED&colon; Use `disposeUninitializedMap` instead&period;
|===


== Data Members

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


== Friends

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


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