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

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

== Synopsis

Declared in `<bdld_datum.h>`

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

== Description

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


== 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`] 
| Apply the specified `visitor` to the current value represented by this object by passing held value to the `visitor` object's `operator()` overload.
| xref:BloombergLP/bdld/Datum/clone.adoc[`clone`] 
| 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}.
| 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 `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.
| 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`] 
| 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 that this human‐readable format is not fully specified, and can change without notice.
| xref:BloombergLP/bdld/Datum/theArray.adoc[`theArray`] 
| Return the array value represented by this object as a `DatumArrayRef` object. The behavior is undefined unless this object actually represents an array of datums.
| xref:BloombergLP/bdld/Datum/theBinary.adoc[`theBinary`] 
| Return the binary reference represented by this object as a `DatumBinaryRef` object. The behavior is undefined unless this object actually represents a binary reference.
| 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 date+time value represented by this object as a `bdlt::Datetime` object. The behavior is undefined unless this object actually represents date+time value.
| xref:BloombergLP/bdld/Datum/theDatetimeInterval.adoc[`theDatetimeInterval`] 
| Return the date+time interval value represented by this object as a `bdlt::DatetimeInterval`. The behavior is undefined unless this object actually represents a date+time interval value.
| xref:BloombergLP/bdld/Datum/theDecimal64.adoc[`theDecimal64`] 
| Return the decimal floating point value represented by this object as a `bdlfpd::Decimal64` value. The behavior is undefined unless this object actually represents a decimal floating point value.
| xref:BloombergLP/bdld/Datum/theDouble.adoc[`theDouble`] 
| Return the double value represented by this object. 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}.
| 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 represented by this object as a `DatumIntMapRef` object. The behavior is undefined unless this object actually represents an int‐map of datums.
| 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 represented by this object as a `Int64` value. The behavior is undefined unless this object actually represents a 64‐bit integer value.
| 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 represented by this object as a `bslstl::StringRef` object. The behavior is undefined unless this object actually represents a string value.
| 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 object represented by this object as a `DatumUdt` object. The behavior is undefined unless this object actually represents a user‐defined 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, by value, a datum that refers to the specified `array`. 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 that the adopted array is owned and will be freed if `Datum::destroy` is called on the returned object.
| xref:BloombergLP/bdld/Datum/adoptIntMap.adoc[`adoptIntMap`] 
| Return, by value, a datum that refers to the specified `intMap`. 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 that the adopted map is owned and will be freed if `Datum::destroy` is called on the returned object.
| 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, 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). The behavior is undefined unless `size <= UINT_MAX`. Note that the copy of the binary data is owned and will be freed if `Datum::destroy` is called on the returned object.
| 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, by value, a datum having the specified `bool` `value`.
| xref:BloombergLP/bdld/Datum/createDate.adoc[`createDate`] 
| Return, by value, a datum having the specified `Date` `value`.
| xref:BloombergLP/bdld/Datum/createDatetime.adoc[`createDatetime`] 
| Return, by value, a datum having the specified `Datetime` `value`, using the specified `allocator` to supply memory (if needed).
| xref:BloombergLP/bdld/Datum/createDatetimeInterval.adoc[`createDatetimeInterval`] 
| Return, by value, a datum holding the specified `DatetimeInterval` `value`, using the specified `allocator` to supply memory (if needed).
| xref:BloombergLP/bdld/Datum/createDecimal64.adoc[`createDecimal64`] 
| Return, by value, a datum having the specified `Decimal64` `value`, using the specified `allocator` to supply memory (if needed). Note that the argument is passed by value because it is assumed to be a fundamental type.
| xref:BloombergLP/bdld/Datum/createDouble.adoc[`createDouble`] 
| 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}.
| xref:BloombergLP/bdld/Datum/createError-04.adoc[`createError`] 
| `createError` overloads
| xref:BloombergLP/bdld/Datum/createInteger.adoc[`createInteger`] 
| Return, by value, a datum having the specified `int` `value`.
| xref:BloombergLP/bdld/Datum/createInteger64.adoc[`createInteger64`] 
| Return, by value, a datum having the specified `Integer64` `value`, using the specified `allocator` to supply memory (if needed).
| 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, by value, a datum having the specified `Time` `value`.
| xref:BloombergLP/bdld/Datum/createUdt.adoc[`createUdt`] 
| Return, by value, a datum having the `DatumUdt` value with the specified `data` and the specified `type` values. The behavior is undefined unless `0 <= type <= 65535`. Note that `data` is held, not owned. Also note that the content pointed to by `data` object is not copied.
| xref:BloombergLP/bdld/Datum/createUninitializedArray.adoc[`createUninitializedArray`] 
| Load the specified `result` with a reference to a newly created datum array having the specified `capacity`, using the specified `allocator` to supply memory. The behavior is undefined if `capacity` `Datum` objects would exceed the addressable memory for the platform. 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`.
| xref:BloombergLP/bdld/Datum/createUninitializedBinary.adoc[`createUninitializedBinary`] 
| 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. The behavior is undefined unless `size <= UINT_MAX`. Note that the caller is responsible for initializing the returned buffer with binary data.
| xref:BloombergLP/bdld/Datum/createUninitializedIntMap.adoc[`createUninitializedIntMap`] 
| 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. The behavior is undefined if `capacity` `DatumIntMapEntry` objects would exceed the addressable memory for the platform. 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`.
| 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`] 
| 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. The behavior is undefined unless `length <= UINT_MAX`. Note that the caller is responsible for initializing the returned buffer with a UTF‐8 encoded string.
| xref:BloombergLP/bdld/Datum/dataTypeToAscii.adoc[`dataTypeToAscii`] 
| 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.
| xref:BloombergLP/bdld/Datum/destroy.adoc[`destroy`] 
| 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. 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 that after this operation completes, `value` is left in an uninitialized state, and must be assigned a new value before being accessed again.
| xref:BloombergLP/bdld/Datum/disposeUninitializedArray.adoc[`disposeUninitializedArray`] 
| 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. The behavior is undefined unless `array` was created with `createUninitializedArray` using `allocator`.
| xref:BloombergLP/bdld/Datum/disposeUninitializedIntMap.adoc[`disposeUninitializedIntMap`] 
| 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. The behavior is undefined unless `map` was created with `createUninitializedIntMap` using `allocator`.
| 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` 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
| `xref:BloombergLP/bdld/operator_not_eq-08.adoc[BloombergLP::bdld::operator!=]`
| 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`.
| `xref:BloombergLP/bdld/operator_eq-06.adoc[BloombergLP::bdld::operator==]`
| 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`.
|===


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