Builds a BitMaskedArray in which mask values are packed into a bitmap. More...

#include <LayoutBuilder.h>

Public Member Functions
	BitMasked ()
	Creates a new BitMasked layout builder by allocating a new `mask` buffer, using `AWKWARD_LAYOUTBUILDER_DEFAULT_OPTIONS` for initializing the buffer.

	BitMasked (const awkward::BuilderOptions &options)
	Creates a new BitMasked layout builder by allocating a new `mask` buffer, taking `options` from `BuilderOptions` for initializing the buffer.

BUILDER &	content () noexcept
	Returns the reference to the builder content.

bool	valid_when () const noexcept
	Determines when the builder content are valid.

bool	lsb_order () const noexcept
	Determines whether the position of each bit is in Least-Significant Bit order (LSB) or not.

BUILDER &	append_valid () noexcept
	Sets a bit in the mask. If current_byte_ and cast_: `0` indicates `null`, `1` indicates `valid` and vice versa.

BUILDER &	extend_valid (size_t size) noexcept
	Sets `size` number of bits in the mask. If current_byte_ and cast_: `0` indicates `null`, `1` indicates `valid` and vice versa.

BUILDER &	append_invalid () noexcept
	Sets current_byte_ and cast_ default to null, no change in current_byte_.

BUILDER &	extend_invalid (size_t size) noexcept
	Sets current_byte_ and cast_ default to null, no change in current_byte_.

const std::string &	parameters () const noexcept
	Parameters for the builder form.

void	set_parameters (std::string parameter) noexcept
	Sets the form parameters.

void	set_id (size_t &id) noexcept
	Assigns a unique ID to each node.

void	clear () noexcept
	Discards the accumulated mask and clears the content of the builder.

size_t	length () const noexcept
	Current length of the `mask` buffer.

bool	is_valid (std::string &error) const noexcept
	Checks for validity and consistency.

void	buffer_nbytes (std::map< std::string, size_t > &names_nbytes) const noexcept
	Retrieves the names and sizes (in bytes) of the buffers used in the builder and its contents.

void	to_buffers (std::map< std::string, void * > &buffers) const noexcept
	Copies and concatenates all the accumulated data in each of the buffers of the builder and its contents to user-defined pointers.

void	to_buffer (void buffer, const char name) const noexcept
	Copies and concatenates the accumulated data in the builder buffer to a user-defined pointer if the given node name matches with the node associated with the builder; otherwise, it searches the builder contents to locate a matching node.

void	to_char_buffers (std::map< std::string, uint8_t * > &buffers) const noexcept
	Copies and concatenates all the accumulated data in the builder to a map of user-allocated buffers.

std::string	form () const noexcept
	Generates a unique description of the builder and its contents in the form of a JSON-like string.

Detailed Description

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>
class awkward::LayoutBuilder::BitMasked< VALID_WHEN, LSB_ORDER, BUILDER >

Builds a BitMaskedArray in which mask values are packed into a bitmap.

It has an additional parameter, lsb_order; If true, the position of each bit is in Least-Significant Bit order (LSB) and if it is false, then in Most-Significant Bit / order (MSB).

    This is similar to NumPy's
    [unpackbits](https://numpy.org/doc/stable/reference/generated/numpy.unpackbits.html)
    with `bitorder="little"` for LSB, `bitorder="big"` for MSB.

    @tparam VALID_WHEN A boolean value which determines when the builder content are valid.
    @tparam LSB_ORDER A boolean value which determines whether the position of each bit is
    in LSB order or not.
    @tparam BUILDER The type of builder content.

Constructor & Destructor Documentation

◆ BitMasked() [1/2]

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BitMasked ( )

inline

Creates a new BitMasked layout builder by allocating a new mask buffer, using AWKWARD_LAYOUTBUILDER_DEFAULT_OPTIONS for initializing the buffer.

◆ BitMasked() [2/2]

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BitMasked ( const awkward::BuilderOptions & options )

inline

Creates a new BitMasked layout builder by allocating a new mask buffer, taking options from BuilderOptions for initializing the buffer.

Parameters

options Initial size configuration of a buffer.

Member Function Documentation

◆ append_invalid()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BUILDER & append_invalid ( )

inlinenoexcept

Sets current_byte_ and cast_ default to null, no change in current_byte_.

After this, a dummy (invalid) value is inserted in the builder content.

◆ append_valid()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BUILDER & append_valid ( )

inlinenoexcept

Sets a bit in the mask. If current_byte_ and cast_: 0 indicates null, 1 indicates valid and vice versa.

After this, a valid element is inserted in the builder content.

◆ buffer_nbytes()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void buffer_nbytes ( std::map< std::string, size_t > & names_nbytes ) const

inlinenoexcept

Retrieves the names and sizes (in bytes) of the buffers used in the builder and its contents.

◆ clear()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void clear ( )

inlinenoexcept

Discards the accumulated mask and clears the content of the builder.

◆ content()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BUILDER & content ( )

inlinenoexcept

Returns the reference to the builder content.

◆ extend_invalid()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BUILDER & extend_invalid ( size_t size )

inlinenoexcept

Sets current_byte_ and cast_ default to null, no change in current_byte_.

After this, size number of dummy (invalid) values are inserted in the builder content.

Just an interface; not actually faster than calling append many times.

◆ extend_valid()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

BUILDER & extend_valid ( size_t size )

inlinenoexcept

Sets size number of bits in the mask. If current_byte_ and cast_: 0 indicates null, 1 indicates valid and vice versa.

After this, size number of valid elements are inserted in the builder content.

Just an interface; not actually faster than calling append many times.

◆ form()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

std::string form ( ) const

inlinenoexcept

Generates a unique description of the builder and its contents in the form of a JSON-like string.

◆ is_valid()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

bool is_valid ( std::string & error ) const

inlinenoexcept

Checks for validity and consistency.

◆ length()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

size_t length ( ) const

inlinenoexcept

Current length of the mask buffer.

◆ lsb_order()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

bool lsb_order ( ) const

inlinenoexcept

Determines whether the position of each bit is in Least-Significant Bit order (LSB) or not.

◆ parameters()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

const std::string & parameters ( ) const

inlinenoexcept

Parameters for the builder form.

◆ set_id()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void set_id ( size_t & id )

inlinenoexcept

Assigns a unique ID to each node.

◆ set_parameters()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void set_parameters ( std::string parameter )

inlinenoexcept

Sets the form parameters.

◆ to_buffer()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void to_buffer	(	void *	buffer,
		const char *	name ) const

inlinenoexcept

Copies and concatenates the accumulated data in the builder buffer to a user-defined pointer if the given node name matches with the node associated with the builder; otherwise, it searches the builder contents to locate a matching node.

◆ to_buffers()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void to_buffers ( std::map< std::string, void * > & buffers ) const

inlinenoexcept

Copies and concatenates all the accumulated data in each of the buffers of the builder and its contents to user-defined pointers.

Used to fill the buffers map by allocating it with user-defined pointers using the same names and sizes (in bytes) obtained from buffer_nbytes.

◆ to_char_buffers()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

void to_char_buffers ( std::map< std::string, uint8_t * > & buffers ) const

inlinenoexcept

Copies and concatenates all the accumulated data in the builder to a map of user-allocated buffers.

The map keys and the buffer sizes are obtained from buffer_nbytes

◆ valid_when()

template<bool VALID_WHEN, bool LSB_ORDER, typename BUILDER>

bool valid_when ( ) const

inlinenoexcept

Determines when the builder content are valid.

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

/home/runner/work/awkward/awkward/awkward-cpp/header-only/layout-builder/awkward/LayoutBuilder.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BitMasked() [1/2]

◆ BitMasked() [2/2]

Member Function Documentation

◆ append_invalid()

◆ append_valid()

◆ buffer_nbytes()

◆ clear()

◆ content()

◆ extend_invalid()

◆ extend_valid()

◆ form()

◆ is_valid()

◆ length()

◆ lsb_order()

◆ parameters()

◆ set_id()

◆ set_parameters()

◆ to_buffer()

◆ to_buffers()

◆ to_char_buffers()

◆ valid_when()