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

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)

Here is the call graph for this function:

◆ 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

◆ 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 561 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]

◆ size()

◆ values()

Friends And Related Symbol Documentation

◆ detail::array_access