Memory-efficient array implementation for null data types. More...

#include <null_array.hpp>

Public Types
using	inner_value_type = null_type

using	value_type = nullable<inner_value_type>

using	iterator = empty_iterator<value_type>

using	reverse_iterator = std::reverse_iterator<iterator>

using	const_iterator = empty_iterator<value_type>

using	const_reverse_iterator = std::reverse_iterator<const_iterator>

using	reference = iterator::reference

using	const_reference = const_iterator::reference

using	size_type = std::size_t

using	difference_type = iterator::difference_type

using	iterator_tag = std::random_access_iterator_tag

using	const_value_iterator = empty_iterator<int>

using	const_bitmap_iterator = empty_iterator<bool>

using	const_value_range = std::ranges::subrange<const_value_iterator>

using	const_bitmap_range = std::ranges::subrange<const_bitmap_iterator>

Public Member Functions
template<input_metadata_container METADATA_RANGE = std::vector<metadata_pair>>
	null_array (size_t length, std::optional< std::string_view > name=std::nullopt, std::optional< METADATA_RANGE > metadata=std::nullopt)
	Constructs a null array with specified length and metadata.

SPARROW_API	null_array (arrow_proxy)
	Constructs null array from Arrow proxy.

SPARROW_API std::optional< std::string_view >	name () const
	Gets the optional name of the array.

SPARROW_API std::optional< key_value_view >	metadata () const
	Gets the metadata associated with the array.

SPARROW_API size_type	size () const
	Gets the number of elements in the array.

SPARROW_API reference	operator[] (size_type i)
	Gets mutable reference to element at specified position.

SPARROW_API const_reference	operator[] (size_type i) const
	Gets const reference to element at specified position.

SPARROW_API iterator	begin ()
	Gets iterator to the beginning of the array.

SPARROW_API iterator	end ()
	Gets iterator to the end of the array.

SPARROW_API const_iterator	begin () const
	Gets const iterator to the beginning of the array.

SPARROW_API const_iterator	end () const
	Gets const iterator to the end of the array.

SPARROW_API reverse_iterator	rbegin ()
	Gets reverse iterator to the beginning of reversed array.

SPARROW_API reverse_iterator	rend ()
	Gets reverse iterator to the end of reversed array.

SPARROW_API const_reverse_iterator	rbegin () const
	Gets const reverse iterator to the beginning of reversed array.

SPARROW_API const_reverse_iterator	rend () const
	Gets const reverse iterator to the end of reversed array.

SPARROW_API const_iterator	cbegin () const
	Gets const iterator to the beginning of the array.

SPARROW_API const_iterator	cend () const
	Gets const iterator to the end of the array.

SPARROW_API const_reverse_iterator	crbegin () const
	Gets const reverse iterator to the beginning of reversed array.

SPARROW_API const_reverse_iterator	crend () const
	Gets const reverse iterator to the end of reversed array.

SPARROW_API reference	front ()
	Gets reference to the first element.

SPARROW_API const_reference	front () const
	Gets const reference to the first element.

SPARROW_API reference	back ()
	Gets reference to the last element.

SPARROW_API const_reference	back () const
	Gets const reference to the last element.

SPARROW_API const_value_range	values () const
	Gets the values as a range (conceptually empty for null arrays).

SPARROW_API const_bitmap_range	bitmap () const
	Gets the validity bitmap as a range (all false for null arrays).

SPARROW_API void	resize (size_type new_size)
	Resizes the null array to the specified size.

Friends
class	detail::array_access

Detailed Description

Memory-efficient array implementation for null data types.

The null_array provides a specialized implementation for storing arrays where all values are null. This is a significant optimization that avoids allocating any memory buffers while still providing the full array interface.

Key features:

Zero memory allocation for data storage
All elements are conceptually null
Full STL-compatible container interface
Arrow format compatibility with "n" format
Efficient iteration without data access

This implementation is particularly useful for:

Placeholder columns in data processing
Testing and development scenarios
Memory-constrained environments
Large arrays of conceptually missing data

Related Apache Arrow specification: https://arrow.apache.org/docs/dev/format/Columnar.html#null-layout

Precondition: All operations assume null semantics

Postcondition: Maintains Arrow null format compatibility ("n"); All elements are semantically null; Memory usage is O(1) regardless of array size; Thread-safe for read operations

//Create null array with 1000 elements
null_array arr(1000, "null_column");
 
//All elements are null
auto elem = arr[500];  // Returns nullable<null_type> in null state
assert(!elem.has_value());
 
//Iteration works normally
for(const auto& null_elem : arr) {
assert(!null_elem.has_value());
}

Definition at line 216 of file null_array.hpp.

Member Typedef Documentation

◆ const_bitmap_iterator

using sparrow::null_array::const_bitmap_iterator = empty_iterator<bool>

Definition at line 233 of file null_array.hpp.

◆ const_bitmap_range

using sparrow::null_array::const_bitmap_range = std::ranges::subrange<const_bitmap_iterator>

Definition at line 236 of file null_array.hpp.

◆ const_iterator

using sparrow::null_array::const_iterator = empty_iterator<value_type>

Definition at line 224 of file null_array.hpp.

◆ const_reference

using sparrow::null_array::const_reference = const_iterator::reference

Definition at line 227 of file null_array.hpp.

◆ const_reverse_iterator

using sparrow::null_array::const_reverse_iterator = std::reverse_iterator<const_iterator>

Definition at line 225 of file null_array.hpp.

◆ const_value_iterator

using sparrow::null_array::const_value_iterator = empty_iterator<int>

Definition at line 232 of file null_array.hpp.

◆ const_value_range

using sparrow::null_array::const_value_range = std::ranges::subrange<const_value_iterator>

Definition at line 235 of file null_array.hpp.

◆ difference_type

using sparrow::null_array::difference_type = iterator::difference_type

Definition at line 229 of file null_array.hpp.

◆ inner_value_type

using sparrow::null_array::inner_value_type = null_type

Definition at line 220 of file null_array.hpp.

◆ iterator

using sparrow::null_array::iterator = empty_iterator<value_type>

Definition at line 222 of file null_array.hpp.

◆ iterator_tag

using sparrow::null_array::iterator_tag = std::random_access_iterator_tag

Definition at line 230 of file null_array.hpp.

◆ reference

using sparrow::null_array::reference = iterator::reference

Definition at line 226 of file null_array.hpp.

◆ reverse_iterator

using sparrow::null_array::reverse_iterator = std::reverse_iterator<iterator>

Definition at line 223 of file null_array.hpp.

◆ size_type

using sparrow::null_array::size_type = std::size_t

Definition at line 228 of file null_array.hpp.

◆ value_type

using sparrow::null_array::value_type = nullable<inner_value_type>

Definition at line 221 of file null_array.hpp.

Constructor & Destructor Documentation

◆ null_array() [1/2]

template<input_metadata_container METADATA_RANGE = std::vector<metadata_pair>>

sparrow::null_array::null_array	(	size_t	length,
		std::optional< std::string_view >	name = std::nullopt,
		std::optional< METADATA_RANGE >	metadata = std::nullopt )

inline

Constructs a null array with specified length and metadata.

Template Parameters

METADATA_RANGE Type of metadata container

Parameters

length	Number of null elements in the array
name	Optional name for the array
metadata	Optional metadata key-value pairs

Precondition: length must be non-negative

Postcondition: Array contains length null elements; All elements are in null state; Array has Arrow format "n"; Memory usage is independent of length

Definition at line 253 of file null_array.hpp.

Here is the call graph for this function:

◆ null_array() [2/2]

SPARROW_API sparrow::null_array::null_array ( arrow_proxy )

explicit

Constructs null array from Arrow proxy.

Parameters

proxy Arrow proxy containing null array data and schema

Precondition: proxy must contain valid Arrow null array and schema; proxy format must be "n"

Postcondition: Array is initialized with data from proxy; All elements are conceptually null

Member Function Documentation

◆ back() [1/2]

SPARROW_API reference sparrow::null_array::back ( )

nodiscard

Gets reference to the last element.

Returns: Reference to the last null element

Precondition: Array must not be empty (size() > 0)

Postcondition: Returns null value; Equivalent to (*this)[size() - 1]

◆ back() [2/2]

SPARROW_API const_reference sparrow::null_array::back ( ) const

nodiscard

Gets const reference to the last element.

Returns: Const reference to the last null element

Precondition: Array must not be empty (size() > 0)

Postcondition: Returns null value; Equivalent to (*this)[size() - 1]

◆ begin() [1/2]

SPARROW_API iterator sparrow::null_array::begin ( )

nodiscard

Gets iterator to the beginning of the array.

Returns: Iterator pointing to the first null element

Postcondition: Iterator is valid for array traversal; For empty array, equals end()

◆ begin() [2/2]

SPARROW_API const_iterator sparrow::null_array::begin ( ) const

nodiscard

Gets const iterator to the beginning of the array.

Returns: Const iterator pointing to the first null element

Postcondition: Iterator is valid for array traversal; For empty array, equals end()

◆ bitmap()

SPARROW_API const_bitmap_range sparrow::null_array::bitmap ( ) const

nodiscard

Gets the validity bitmap as a range (all false for null arrays).

Returns: Range over validity flags (all false)

Postcondition: Range size equals array size; All bitmap values are false (indicating null)

◆ cbegin()

SPARROW_API const_iterator sparrow::null_array::cbegin ( ) const

nodiscard

Gets const iterator to the beginning of the array.

Returns: Const iterator pointing to the first null element

Postcondition: Iterator is valid for array traversal; Guarantees const iterator even for non-const array

◆ cend()

SPARROW_API const_iterator sparrow::null_array::cend ( ) const

nodiscard

Gets const iterator to the end of the array.

Returns: Const iterator pointing past the last null element

Postcondition: Iterator marks the end of the array range; Guarantees const iterator even for non-const array

◆ crbegin()

SPARROW_API const_reverse_iterator sparrow::null_array::crbegin ( ) const

nodiscard

Gets const reverse iterator to the beginning of reversed array.

Returns: Const reverse iterator pointing to the last null element

Postcondition: Iterator is valid for reverse traversal; For empty array, equals crend()

◆ crend()

SPARROW_API const_reverse_iterator sparrow::null_array::crend ( ) const

nodiscard

Gets const reverse iterator to the end of reversed array.

Returns: Const reverse iterator pointing before the first null element

Postcondition: Iterator marks the end of reverse traversal; Not dereferenceable

◆ end() [1/2]

SPARROW_API iterator sparrow::null_array::end ( )

nodiscard

Gets iterator to the end of the array.

Returns: Iterator pointing past the last null element

Postcondition: Iterator marks the end of the array range; Not dereferenceable

◆ end() [2/2]

SPARROW_API const_iterator sparrow::null_array::end ( ) const

nodiscard

Gets const iterator to the end of the array.

Returns: Const iterator pointing past the last null element

Postcondition: Iterator marks the end of the array range; Not dereferenceable

◆ front() [1/2]

SPARROW_API reference sparrow::null_array::front ( )

nodiscard

Gets reference to the first element.

Returns: Reference to the first null element

Precondition: Array must not be empty (size() > 0)

Postcondition: Returns null value; Equivalent to (*this)[0]

◆ front() [2/2]

SPARROW_API const_reference sparrow::null_array::front ( ) const

nodiscard

Gets const reference to the first element.

Returns: Const reference to the first null element

Precondition: Array must not be empty (size() > 0)

Postcondition: Returns null value; Equivalent to (*this)[0]

◆ metadata()

SPARROW_API std::optional< key_value_view > sparrow::null_array::metadata ( ) const

nodiscard

Gets the metadata associated with the array.

Returns: Optional view of key-value metadata pairs from Arrow schema

Postcondition: Returns nullopt if no metadata is set; Returned view remains valid while array exists

Here is the caller graph for this function:

◆ name()

SPARROW_API std::optional< std::string_view > sparrow::null_array::name ( ) const

nodiscard

Gets the optional name of the array.

Returns: Optional string view of the array name from Arrow schema

Postcondition: Returns nullopt if no name is set; Returned string view remains valid while array exists

Here is the caller graph for this function:

◆ operator[]() [1/2]

SPARROW_API reference sparrow::null_array::operator[] ( size_type i )

nodiscard

Gets mutable reference to element at specified position.

Parameters

i	Index of the element to access

Returns: Reference to null value at position i

Precondition: i must be < size()

Postcondition: Returns null value regardless of index; Reference represents conceptually null element

◆ operator[]() [2/2]

SPARROW_API const_reference sparrow::null_array::operator[] ( size_type i ) const

nodiscard

Gets const reference to element at specified position.

Parameters

i	Index of the element to access

Returns: Const reference to null value at position i

Precondition: i must be < size()

Postcondition: Returns null value regardless of index; Reference represents conceptually null element

◆ rbegin() [1/2]

SPARROW_API reverse_iterator sparrow::null_array::rbegin ( )

nodiscard

Gets reverse iterator to the beginning of reversed array.

Returns: Reverse iterator pointing to the last null element

Postcondition: Iterator is valid for reverse traversal; For empty array, equals rend()

◆ rbegin() [2/2]

SPARROW_API const_reverse_iterator sparrow::null_array::rbegin ( ) const

nodiscard

Gets const reverse iterator to the beginning of reversed array.

Returns: Const reverse iterator pointing to the last null element

Postcondition: Iterator is valid for reverse traversal; For empty array, equals rend()

◆ rend() [1/2]

SPARROW_API reverse_iterator sparrow::null_array::rend ( )

nodiscard

Gets reverse iterator to the end of reversed array.

Returns: Reverse iterator pointing before the first null element

Postcondition: Iterator marks the end of reverse traversal; Not dereferenceable

◆ rend() [2/2]

SPARROW_API const_reverse_iterator sparrow::null_array::rend ( ) const

nodiscard

Gets const reverse iterator to the end of reversed array.

Returns: Const reverse iterator pointing before the first null element

Postcondition: Iterator marks the end of reverse traversal; Not dereferenceable

◆ resize()

SPARROW_API void sparrow::null_array::resize ( size_type new_size )

Resizes the null array to the specified size.

Changes the number of null elements in the array. Since all elements are conceptually null, this operation only updates the size metadata without requiring any data buffer reallocation.

Parameters

new_size The new number of null elements

Precondition: new_size must be non-negative

Postcondition: size() returns new_size; All elements (old and new) remain null; Memory usage remains O(1) regardless of new_size; Iterator ranges are updated to reflect new size

null_array arr(100);
arr.resize(200);  // Array now has 200 null elements
assert(arr.size() == 200);

Here is the call graph for this function:

◆ size()

SPARROW_API size_type sparrow::null_array::size ( ) const

nodiscard

Gets the number of elements in the array.

Returns: Number of null elements in the array

Postcondition: Returns non-negative value; All size() elements are null

◆ values()

SPARROW_API const_value_range sparrow::null_array::values ( ) const

nodiscard

Gets the values as a range (conceptually empty for null arrays).

Returns: Range over conceptual values (empty for null arrays)

Postcondition: Range represents the conceptual values in the null array; All values are conceptually absent/null

Friends And Related Symbol Documentation

◆ detail::array_access

friend class detail::array_access

friend

Definition at line 584 of file null_array.hpp.

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

/home/runner/work/sparrow/sparrow/include/sparrow/null_array.hpp

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ const_bitmap_iterator

◆ const_bitmap_range

◆ const_iterator

◆ const_reference

◆ const_reverse_iterator

◆ const_value_iterator

◆ const_value_range

◆ difference_type

◆ inner_value_type

◆ iterator

◆ iterator_tag

◆ reference

◆ reverse_iterator

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ null_array() [1/2]

◆ null_array() [2/2]

Member Function Documentation

◆ back() [1/2]

◆ back() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ bitmap()

◆ cbegin()

◆ cend()

◆ crbegin()

◆ crend()

◆ end() [1/2]

◆ end() [2/2]

◆ front() [1/2]

◆ front() [2/2]

◆ metadata()

◆ name()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ rbegin() [1/2]

◆ rbegin() [2/2]

◆ rend() [1/2]

◆ rend() [2/2]

◆ resize()

◆ size()

◆ values()

Friends And Related Symbol Documentation

◆ detail::array_access