A Datum stores and possibly manage the memory resource of a read-only value of a plain fixed-length C++ type, a null-terminated string (cstring), or an object of a variable-length type. More...

#include <base/datum.h>

Inheritance diagram for taco::Datum:

Public Member Functions
	~Datum ()

	Datum (Datum &&d)
	Move constructor of Datum. More...

Datum &	operator= (Datum &&d)
	Move assignment operator of Datum. More...

bool	isnull () const

const char *	GetVarlenBytes () const
	Returns the variable-length value of a datum as an array of bytes. More...

uint32_t	GetVarlenSize () const
	Returns the size of the variable-length value of a datum. More...

absl::string_view	GetVarlenAsStringView () const

const Datum &	GetThis () const
	Returns a constant reference to ‘*this’. More...

bool	HasExternalRef () const
	Whether this datum is variable-length but does not own its byte array. More...

Datum	DeepCopy () const
	Returns a deep copy of this datum so that `HasExternalRef() == false` and the owned value is a copy of the old one. More...

Datum	Copy () const
	Makes a shallow copy of this datum. More...

Public Member Functions inherited from taco::datum_impl::NonVarlenGetters< Datum >
constexpr const char *	GetFixedlenBytes () const
	Return the pointer to the binary representation of a fixed-length datum that is passed by value. More...

constexpr bool	GetBool () const
	Returns boolean value of a datum. More...

constexpr char	GetChar () const
	Returns character value of a datum. More...

constexpr int8_t	GetInt8 () const
	Returns 8-bit integer value of a datum. More...

constexpr uint8_t	GetUInt8 () const
	Returns 8-bit unsigned integer value of a datum. More...

constexpr int16_t	GetInt16 () const
	Returns 16-bit integer value of a datum. More...

constexpr uint16_t	GetUInt16 () const
	Returns 16-bit unsigned integer value of a datum. More...

constexpr int32_t	GetInt32 () const
	Returns 32-bit integer value of a datum. More...

constexpr uint32_t	GetUInt32 () const
	Returns 32-bit unsigned integer value of a datum. More...

constexpr Oid	GetOid () const
	Returns object identifier value of a datum. More...

constexpr int64_t	GetInt64 () const
	Returns 64-bit integer value of a datum. More...

constexpr uint64_t	GetUInt64 () const
	Returns 64-bit unsigned integer value of a datum. More...

constexpr float	GetFloat () const
	Returns single-precision floating point value of a datum. More...

constexpr double	GetDouble () const
	Returns double-precision floating point value of a datum. More...

constexpr void *	GetPointer () const
	Returns pointer value of a datum. More...

constexpr T *	GetPointerAs () const
	Returns the pointer value of a datum as const T*. More...

Static Public Member Functions
static Datum	FromNull ()

static Datum	From (bool X)
	Returns datum representation for a boolean. More...

static Datum	From (char X)
	Returns datum representation for a character. More...

static Datum	From (int8_t X)
	Returns datum representation for an 8-bit integer. More...

static Datum	From (uint8_t X)
	Returns datum representation for an 8-bit unsigned integer. More...

static Datum	From (int16_t X)
	Returns datum representation for a 16-bit integer. More...

static Datum	From (uint16_t X)
	Returns datum representation for a 16-bit unsigned integer. More...

static Datum	From (int32_t X)
	Returns datum representation for a 32-bit integer. More...

static Datum	From (uint32_t X)
	Returns datum representation for a 32-bit unsigned integer. More...

static Datum	From (void *X)
	Returns datum representation for a pointer. More...

static Datum	From (int64_t X)
	Returns datum representation for a signed 64-bit integer. More...

static Datum	From (uint64_t X)
	Returns datum representation for an unsigned 64-bit integer. More...

static Datum	From (float X)
	Returns datum representation for a single-precision floating point number. More...

static Datum	From (double X)
	Returns datum representation for a double-precision floating point number. More...

static Datum	FromCString (const char *str)
	Returns datum representation of a null-terminated string that is not owned by this datum. More...

static Datum	FromCString (const char *str, bool isnull)

static Datum	FromCString (std::unique_ptr< char[]> str, bool isnull=false)
	Returns datum representation of a null-terminated string that is owned by this datum. More...

static Datum	FromVarlenBytes (const char *bytes, uint32_t size)
	Returns datum representation of a variable-length object that is not owned by this datum. More...

static Datum	FromVarlenBytes (const char *bytes, uint32_t size, bool isnull)
	Returns datum representation of a variable-length object that is not owned by this datum if isnull is false, or otherwise, returns a datum of a null value. More...

static Datum	FromVarlenBytes (unique_malloced_ptr bytes, uint32_t size, bool isnull=false)
	Returns datum representation of a variable-length object that is owned by this datum. More...

static Datum	FromVarlenAsStringView (absl::string_view bytes)
	Returns datum representation of a variable-length object stored as an absl::string_view that is not owned by this datum. More...

template<class T >
static Datum	From (T &&X, bool isnull)
	This template version of From accepts a second argument isnull and returns a Datum with a null value if that's true. More...

static Datum	FromFixedlenBytes (const char *bytes, uint32_t size)
	Returns a fixed-length datum that is passed by value by copying its binary representation. More...

Private Member Functions
	Datum ()
	Constructs a Datum with a null value. More...

	Datum (datum_impl::DatumRep value)

	Datum (datum_impl::DatumRep value, bool isowned, uint32_t size)
	Constructs a Datum with a non-null and non-variable-length value (except for CString). More...

	Datum (const Datum &)=default

Datum &	operator= (const Datum &)=default

Private Attributes
bool	m_isowned: 1
	Whether the managed object is owned by this Datum. More...

bool	m_isnull: 1
	Whether the value is null. More...

bool	m_isvarlen: 1
	Whether the managed object is a variable-length object that is not a null-terminated string. More...

uint32_t	m_size
	The length of the variable-length value of the datum. More...

datum_impl::DatumRep	m_val
	The actual value storage. More...

Friends
template<class DatumImpl >
class	datum_impl::NonVarlenGetters

template<class DatumImpl >
class	datum_impl::DatumRefVarlenGetters

class	DatumRef

class	NullableDatumRef

struct	DataArray

Additional Inherited Members
Protected Member Functions inherited from taco::datum_impl::NonVarlenGetters< Datum >
constexpr const DatumRep &	val () const

Detailed Description

A Datum stores and possibly manage the memory resource of a read-only value of a plain fixed-length C++ type, a null-terminated string (cstring), or an object of a variable-length type.

Datum is usually used for passing the runtime C++ representation of a value of a SQL type, but sometimes it can also be used to pass internal values of primitive types (see the caution below). It can be created using the From() static member functions. Datum may not be copied and may only be moved, as it represents a unique ownership of an object. The copy constructor and assignment operator are explicitly deleted because of that. A Datum does not store the type information. It is up to the caller to find out the correct GetXXX() function to call depending on the types.

To pass Datum around in the system, use the implicit conversions to DatumRef or NullableDatumRef, which can be freely copied. However, a DatumRef or NullableDatumRef must NOT be used once its referencing Datum is desctructed.

Caution: the pointer to an object of a type with a non-trivial destructor must NOT be owned by a Datum, because Datum does not know its type and will never call the destructor. The workaround is to manage the value using std::unique_ptr and directly get Datum or DatumRef from the plain pointer.

Implementation notes:

If a value is a fixed-length type is <= 8 bytes long, it is stored as a copy of the value. In this case, there are no dynamically allocated memory and m_isown is never true. Otherwise, m_isown is true if Datum is created from an std::unique_ptr (in which case the ownership of the pointer in the smart pointer is transfered to the Datum), or false if Datum is created from a plain pointer (in which case the caller retains the ownership of the data). The latter case is useful when we don't want to make a copy of an object located on a buffer page. To avoid break the assumption that Datum is read-only, the caller is responsible for the objected pointed by a plain pointer is not modified (e.g., the caller should have a lock on a tuple on a buffer page).

Note that the ownership of the memory resource is irrelevant to the ownership of the Datum. One should always ensure a Datum is live when it is referenced through a DatumRef or a NullableDatumRef, even if the value is copied into the reference when it fits into the m_val field in the current implementation.

Constructor & Destructor Documentation

◆ ~Datum()

taco::Datum::~Datum ( )

inline

◆ Datum() [1/5]

taco::Datum::Datum ( Datum && d )

inline

Move constructor of Datum.

This Datum assumes the ownership of the object in d'', andd'' will be set to null upon return.

◆ Datum() [2/5]

taco::Datum::Datum ( )

inlineprivate

Constructs a Datum with a null value.

◆ Datum() [3/5]

taco::Datum::Datum ( datum_impl::DatumRep value )

inlineprivate

◆ Datum() [4/5]

taco::Datum::Datum	(	datum_impl::DatumRep	value,
		bool	isowned,
		uint32_t	size
	)

inlineprivate

Constructs a Datum with a non-null and non-variable-length value (except for CString).

◆ Datum() [5/5]

taco::Datum::Datum ( const Datum & )

privatedefault

Member Function Documentation

◆ Copy()

Datum taco::Datum::Copy ( ) const

inline

Makes a shallow copy of this datum.

If this datum is variable-length and owns its memory, this function returns a new one that does not own the underlying memory.

◆ DeepCopy()

Datum taco::Datum::DeepCopy ( ) const

inline

Returns a deep copy of this datum so that HasExternalRef() == false and the owned value is a copy of the old one.

◆ From() [1/14]

static Datum taco::Datum::From ( bool X )

inlinestatic

Returns datum representation for a boolean.

◆ From() [2/14]

static Datum taco::Datum::From ( char X )

inlinestatic

Returns datum representation for a character.

◆ From() [3/14]

static Datum taco::Datum::From ( double X )

inlinestatic

Returns datum representation for a double-precision floating point number.

◆ From() [4/14]

static Datum taco::Datum::From ( float X )

inlinestatic

Returns datum representation for a single-precision floating point number.

◆ From() [5/14]

static Datum taco::Datum::From ( int16_t X )

inlinestatic

Returns datum representation for a 16-bit integer.

◆ From() [6/14]

static Datum taco::Datum::From ( int32_t X )

inlinestatic

Returns datum representation for a 32-bit integer.

◆ From() [7/14]

static Datum taco::Datum::From ( int64_t X )

inlinestatic

Returns datum representation for a signed 64-bit integer.

◆ From() [8/14]

static Datum taco::Datum::From ( int8_t X )

inlinestatic

Returns datum representation for an 8-bit integer.

◆ From() [9/14]

template<class T >

static Datum taco::Datum::From	(	T &&	X,
		bool	isnull
	)

inlinestatic

This template version of From accepts a second argument isnull and returns a Datum with a null value if that's true.

Otherwise, it just forwards the argument to the corresponding single-argument From() function.

◆ From() [10/14]

static Datum taco::Datum::From ( uint16_t X )

inlinestatic

Returns datum representation for a 16-bit unsigned integer.

◆ From() [11/14]

static Datum taco::Datum::From ( uint32_t X )

inlinestatic

Returns datum representation for a 32-bit unsigned integer.

Note: there is no From(Oid) because an Oid is represented as a uint32_t in C++.

◆ From() [12/14]

static Datum taco::Datum::From ( uint64_t X )

inlinestatic

Returns datum representation for an unsigned 64-bit integer.

◆ From() [13/14]

static Datum taco::Datum::From ( uint8_t X )

inlinestatic

Returns datum representation for an 8-bit unsigned integer.

◆ From() [14/14]

static Datum taco::Datum::From ( void * X )

inlinestatic

Returns datum representation for a pointer.

◆ FromCString() [1/3]

static Datum taco::Datum::FromCString ( const char * str )

inlinestatic

Returns datum representation of a null-terminated string that is not owned by this datum.

A null-terminated string is always treated as a variable-length datum so you have to call GetVarlenAsStringView() to convert it back to a string (though there is no guarantee that the returned string_view has a pointer to a null-terminated string).

◆ FromCString() [2/3]

static Datum taco::Datum::FromCString	(	const char *	str,
		bool	isnull
	)

inlinestatic

◆ FromCString() [3/3]

static Datum taco::Datum::FromCString	(	std::unique_ptr< char[]>	str,
		bool	isnull = `false`
	)

inlinestatic

Returns datum representation of a null-terminated string that is owned by this datum.

Upon return the pointer stored in `‘str’' is released and owned by the Datum returned. A null-terminated string is always treated as a variable-length datum so you have to call GetVarlenAsStringView() to convert it back to a string (though there is no guarantee that the returned string_view has a pointer to a null-terminated string).

The optional second argument isnull is ignored if `‘str’' stores a nullptr. Otherwise, isnull takes precedence in deciding whether the Datum is null or not. Note that a non-null pointer in `‘bytes’' will be deallocated if isnull is true.

◆ FromFixedlenBytes()

static Datum taco::Datum::FromFixedlenBytes	(	const char *	bytes,
		uint32_t	size
	)

inlinestatic

Returns a fixed-length datum that is passed by value by copying its binary representation.

◆ FromNull()

static Datum taco::Datum::FromNull ( )

inlinestatic

◆ FromVarlenAsStringView()

static Datum taco::Datum::FromVarlenAsStringView ( absl::string_view bytes )

inlinestatic

Returns datum representation of a variable-length object stored as an absl::string_view that is not owned by this datum.

◆ FromVarlenBytes() [1/3]

static Datum taco::Datum::FromVarlenBytes	(	const char *	bytes,
		uint32_t	size
	)

inlinestatic

Returns datum representation of a variable-length object that is not owned by this datum.

◆ FromVarlenBytes() [2/3]

static Datum taco::Datum::FromVarlenBytes	(	const char *	bytes,
		uint32_t	size,
		bool	isnull
	)

inlinestatic

Returns datum representation of a variable-length object that is not owned by this datum if isnull is false, or otherwise, returns a datum of a null value.

◆ FromVarlenBytes() [3/3]

static Datum taco::Datum::FromVarlenBytes	(	unique_malloced_ptr	bytes,
		uint32_t	size,
		bool	isnull = `false`
	)

inlinestatic

Returns datum representation of a variable-length object that is owned by this datum.

Upon return the pointer stored in `‘bytes’' is released and owned by the Datum returned.

The optional second argument isnull is ignored if `‘bytes’' stores a nullptr. Otherwise, isnull takes precedence in deciding whether the Datum is null or not. Note that a non-null pointer in `‘bytes’' will be deallocated if isnull is true.

The first argument `‘bytes’' must point to some byte buffer allocated via malloc()/aligned_alloc() (or unique_aligned_alloc()/unique_malloc()) rather than C++ new expression. That means it must NOT point to some object that requires non-trivial destruction (see Caution in the class documentation), i.e., one should never try to bypass the restriction by casting a pointer T* where T is some class with non-trivial destructor into char* and create a unique_ptr of that as the first argument!!

◆ GetThis()

const Datum& taco::Datum::GetThis ( ) const

inline

Returns a constant reference to ‘*this’.

◆ GetVarlenAsStringView()

absl::string_view taco::Datum::GetVarlenAsStringView ( ) const

inline

◆ GetVarlenBytes()

const char* taco::Datum::GetVarlenBytes ( ) const

inline

Returns the variable-length value of a datum as an array of bytes.

◆ GetVarlenSize()

uint32_t taco::Datum::GetVarlenSize ( ) const

inline

Returns the size of the variable-length value of a datum.

◆ HasExternalRef()

bool taco::Datum::HasExternalRef ( ) const

inline

Whether this datum is variable-length but does not own its byte array.

A Datum with HasExternalRef() == true may only be read when the byte array it references is still alive (e.g., it must be pinned if it is referencing a buffer frame). Otherwise, a Datum is safe to be read at any time.

◆ isnull()

bool taco::Datum::isnull ( ) const

inline

◆ operator=() [1/2]

Datum& taco::Datum::operator= ( const Datum & )

privatedefault

◆ operator=() [2/2]

Datum& taco::Datum::operator= ( Datum && d )

inline

Move assignment operator of Datum.

This Datum assumes the ownership of the object in d'', andd'' will be set to null upon return.

Friends And Related Function Documentation

◆ DataArray

friend struct DataArray

friend

◆ datum_impl::DatumRefVarlenGetters

template<class DatumImpl >

friend class datum_impl::DatumRefVarlenGetters

friend

◆ datum_impl::NonVarlenGetters

template<class DatumImpl >

friend class datum_impl::NonVarlenGetters

friend

◆ DatumRef

friend class DatumRef

friend

◆ NullableDatumRef

friend class NullableDatumRef

friend

Member Data Documentation

◆ m_isnull

bool taco::Datum::m_isnull

private

Whether the value is null.

◆ m_isowned

bool taco::Datum::m_isowned

private

Whether the managed object is owned by this Datum.

Currently we assume any owned object is passed by reference and its memory is allocated on the heap via new().

◆ m_isvarlen

bool taco::Datum::m_isvarlen

private

Whether the managed object is a variable-length object that is not a null-terminated string.

◆ m_size

uint32_t taco::Datum::m_size

private

The length of the variable-length value of the datum.

This is only valid when m_isvarlen == true.

◆ m_val

datum_impl::DatumRep taco::Datum::m_val

private

The actual value storage.

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

base/datum.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~Datum()

◆ Datum() [1/5]

◆ Datum() [2/5]

◆ Datum() [3/5]

◆ Datum() [4/5]

◆ Datum() [5/5]

Member Function Documentation

◆ Copy()

◆ DeepCopy()

◆ From() [1/14]

◆ From() [2/14]

◆ From() [3/14]

◆ From() [4/14]

◆ From() [5/14]

◆ From() [6/14]

◆ From() [7/14]

◆ From() [8/14]

◆ From() [9/14]

◆ From() [10/14]

◆ From() [11/14]

◆ From() [12/14]

◆ From() [13/14]

◆ From() [14/14]

◆ FromCString() [1/3]

◆ FromCString() [2/3]

◆ FromCString() [3/3]

◆ FromFixedlenBytes()

◆ FromNull()

◆ FromVarlenAsStringView()

◆ FromVarlenBytes() [1/3]

◆ FromVarlenBytes() [2/3]

◆ FromVarlenBytes() [3/3]

◆ GetThis()

◆ GetVarlenAsStringView()

◆ GetVarlenBytes()

◆ GetVarlenSize()

◆ HasExternalRef()

◆ isnull()

◆ operator=() [1/2]

◆ operator=() [2/2]

Friends And Related Function Documentation

◆ DataArray

◆ datum_impl::DatumRefVarlenGetters

◆ datum_impl::NonVarlenGetters

◆ DatumRef

◆ NullableDatumRef

Member Data Documentation

◆ m_isnull

◆ m_isowned

◆ m_isvarlen

◆ m_size

◆ m_val