Types

BitMaskedArray{CONTENT<:Content,BEHAVIOR} <: OptionType{BEHAVIOR}

Specialized array type designed to handle masked arrays, where certain elements can be marked as valid or invalid using a BitVector.

Inherits from OptionType.

struct BitMaskedArray{CONTENT<:Content,BEHAVIOR} <: OptionType{BEHAVIOR}
    mask::BitVector
    content::CONTENT
    valid_when::Bool
    parameters::Parameters

    BitMaskedArray(
        mask::BitVector,
        content::CONTENT;
        valid_when::Bool = false,
        parameters::Parameters = Parameters(),
        behavior::Symbol = :default,
    ) where {CONTENT<:Content} =
        new{CONTENT,behavior}(mask, content, valid_when, parameters)
end

Type Parameters:

• CONTENT<:Content: The CONTENT type parameter is constrained to be a subtype of Content.
• BEHAVIOR: A type parameter that can represent different behaviors associated with the array.

Inheritance:

• <: OptionType{BEHAVIOR}: Indicates that BitMaskedArray is a subtype of OptionType parameterized by BEHAVIOR.

Fields:

• mask::BitVector: A BitVector indicating which elements are valid or invalid.
• content::CONTENT: The actual data content, constrained to be a subtype of Content.
• valid_when::Bool: A flag indicating when the mask is valid (by default false).

• parameters::Parameters: Additional parameters associated with the array, defined elsewhere.

Constructor:

BitMaskedArray(
    mask::BitVector, 
    content::CONTENT; 
    valid_when::Bool = false, 
    parameters::Parameters = Parameters(), 
    behavior::Symbol = :default
) where {CONTENT<:Content}

This is the outer constructor for the BitMaskedArray struct. It initializes a new instance of BitMaskedArray with the given mask, content, and optional valid_when, parameters, and behavior. The where {CONTENT<:Content} clause ensures that CONTENT satisfies the specified constraint.

new{CONTENT,behavior}(mask, content, valid_when, parameters)

creates a new instance of BitMaskedArray with the specified type parameters and field values.

BitMaskedArray{CONTENT}(;
    valid_when::Bool = false,
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENT<:Content}

Outer constructor to create an instance of BitMaskedArray with default or specified values for valid_when, parameters, and behavior, while initializing the mask and content with default empty instances.

BitMaskedArray{CONTENT}(;
    valid_when::Bool = false,
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENT<:Content} = BitMaskedArray(
    BitVector(),
    CONTENT(),
    valid_when = valid_when,
    parameters = parameters,
    behavior = behavior,
)

ByteMaskedArray{INDEX<:IndexBool, CONTENT<:Content, BEHAVIOR} <: OptionType{BEHAVIOR}

Specialized array type designed to handle arrays where elements can be optionally masked using a mask of type INDEX (which is constrained to be a subtype of IndexBool).

Inherits from OptionType.

struct ByteMaskedArray{INDEX<:IndexBool, CONTENT<:Content, BEHAVIOR} <: OptionType{BEHAVIOR}
    mask::INDEX
    content::CONTENT
    valid_when::Bool
    parameters::Parameters

    ByteMaskedArray(
        mask::INDEX,
        content::CONTENT;
        valid_when::Bool = false,  # the NumPy MaskedArray convention
        parameters::Parameters = Parameters(),
        behavior::Symbol = :default,
    ) where {INDEX<:IndexBool, CONTENT<:Content} =
        new{INDEX, CONTENT, behavior}(mask, content, valid_when, parameters)
end

Type Parameters:

• INDEX<:IndexBool: The INDEX type parameter is constrained to be a subtype of IndexBool, indicating that the mask is of a specific boolean index type.
• CONTENT<:Content: The CONTENT type parameter is constrained to be a subtype of Content.
• BEHAVIOR: A type parameter that can represent different behaviors associated with the array.

Inheritance:

• <: OptionType{BEHAVIOR}: Indicates that ByteMaskedArray is a subtype of OptionType parameterized by BEHAVIOR.

Fields:

• mask::INDEX: The mask used to indicate valid or invalid elements, constrained to be a subtype of IndexBool.
• content::CONTENT: The actual data content, constrained to be a subtype of Content.
• valid_when::Bool: A flag indicating when the mask is valid (by default false).
• parameters::Parameters: Additional parameters associated with the array, defined elsewhere.

Constructor:

ByteMaskedArray(
    mask::INDEX, 
    content::CONTENT; 
    valid_when::Bool = false, 
    parameters::Parameters = Parameters(), 
    behavior::Symbol = :default
) where {INDEX<:IndexBool, CONTENT<:Content}:

This is the outer constructor for the ByteMaskedArray struct. It initializes a new instance of ByteMaskedArray with the given mask, content, and optional valid_when, parameters, and behavior. The where {INDEX<:IndexBool, CONTENT<:Content} clause ensures that INDEX and CONTENT satisfy the specified constraints.

new{INDEX, CONTENT, behavior}(mask, content, valid_when, parameters)

creates a new instance of ByteMaskedArray with the specified type parameters and field values.

ByteMaskedArray{INDEX,CONTENT}(;
    valid_when::Bool = false,
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBool} where {CONTENT<:Content}

Convenience constructor for the ByteMaskedArray struct. This constructor allows you to create a ByteMaskedArray instance with default values for its fields, particularly for the mask and content, by specifying only the optional parameters.

ByteMaskedArray{INDEX,CONTENT}(;
    valid_when::Bool = false,
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBool} where {CONTENT<:Content} = ByteMaskedArray(
    INDEX([]),
    CONTENT(),
    valid_when = valid_when,
    parameters = parameters,
    behavior = behavior,
)

Abstract Content type. Each layout is subtype from this.

List of functions

Every Content subclass has the following built-in functions:

• Base.length
• Base.size (1-tuple of length)
• Base.firstindex, Base.lastindex (1-based or inherited from its index)
• Base.getindex: select by Int (single item), UnitRange{Int} (slice), and Symbol (record field)
• Base.iterate
• Base.:(==) (equality defined by values: a ListOffsetArray and a ListArray may be considered the same)
• Base.push!
• Base.append!
• Base.show

They also have the following functions for manipulating and checking structure:

• AwkwardArray.parameters_of: gets all parameters
• AwkwardArray.has_parameter: returns true if a parameter exists
• AwkwardArray.get_parameter: returns a parameter or raises an error
• AwkwardArray.with_parameter: returns a copy of this node with a specified parameter
• AwkwardArray.copy: shallow-copy of the array, allowing properties to be replaced
• AwkwardArray.is_valid: verifies that the structure adheres to Awkward Array's protocol

They have the following functions for filling an array:

• AwkwardArray.end_list!: closes off a ListType array (ListOffsetArray, ListArray, or RegularArray) in the manner of Python's ak.ArrayBuilder (no begin_list is necessary)
• AwkwardArray.end_record!: closes off a RecordArray
• AwkwardArray.end_tuple!: closes off a TupleArray
• AwkwardArray.push_null!: pushes a missing value onto OptionType arrays (IndexedOptionArray, ByteMaskedArray, BitMaskedArray, or UnmaskedArray)
• AwkwardArray.push_dummy!: pushes an unspecified value onto the array (used by ByteMaskedArray and BitMaskedArray, which need to have a placeholder in memory behind each missing value)

RecordArray and TupleArray have the following for selecting fields (as opposed to rows):

• AwkwardArray.slot: gets a RecordArray or TupleArray field, to avoid conflicts with Base.getindex for TupleArrays (both use integers to select a field)
• AwkwardArray.Record: scalar representation of an item from a RecordArray
• AwkwardArray.SlotRecord: scalar representation of an item from a TupleArray (note: not the same as Base.Tuple)

UnionArray has the following for dealing with specializations:

• AwkwardArray.Specialization: selects a UnionArray specialization for push!, append!, etc.

Finally, all Content subclasses can be converted with the following:

• AwkwardArray.layout_for: returns an appropriately-nested Content type for a given Julia type (DataType)
• AwkwardArray.from_iter: converts Julia data into an Awkward Array
• AwkwardArray.to_vector: converts an Awkward Array into Julia data
• AwkwardArray.from_buffers: constructs an Awkward Array from a Form (JSON), length, and buffers for zero-copy passing from Python
• AwkwardArray.to_buffers: deconstructs an Awkward Array into a Form (JSON), length, and buffers for zero-copy passing to Python

Represents an array that is always empty.

struct EmptyArray{BEHAVIOR} <: LeafType{BEHAVIOR}
    behavior::Symbol
    
    function EmptyArray(; behavior::Symbol = :default)
        new{behavior}(behavior)
    end
end

Type Parameter:

• {BEHAVIOR}: The EmptyArray type has a parameter BEHAVIOR which is used to parameterize the type. This can be useful for specifying different behaviors or properties for different instances of EmptyArray.

Inheritance:

• <: LeafType{BEHAVIOR}: This indicates that EmptyArray is a subtype of LeafType with the same BEHAVIOR parameter.

Field:

• behavior::Symbol: This field stores a Symbol indicating the behavior of the empty array. A Symbol in Julia is a type that represents interned strings and is often used for identifiers and labels.

Constructor:

function EmptyArray(; behavior::Symbol = :default): This is an inner constructor that allows for the creation of EmptyArray instances. The behavior argument is optional and defaults to :default if not provided. new{behavior}(behavior): The new function is used to create an instance of EmptyArray with the specified behavior. The {behavior} syntax is used to pass the type parameter to the instance.

IndexedArray{INDEX<:IndexBig,CONTENT<:Content,BEHAVIOR} <: Content{BEHAVIOR}

IndexedArray represents an array that references its elements through an index.

struct IndexedArray{INDEX<:IndexBig, CONTENT<:Content, BEHAVIOR} <: Content{BEHAVIOR}
    index::INDEX
    content::CONTENT
    parameters::Parameters

    IndexedArray(
        index::INDEX,
        content::CONTENT;
        parameters::Parameters = Parameters(),
        behavior::Symbol = :default,
    ) where {INDEX<:IndexBig, CONTENT<:Content} =
        new{INDEX, CONTENT, behavior}(index, content, parameters)
end

Type Parameters:

• {INDEX<:IndexBig, CONTENT<:Content, BEHAVIOR}: These are the type parameters for the struct.
• INDEX<:IndexBig: INDEX must be a subtype of IndexBig.
• CONTENT<:Content: CONTENT must be a subtype of Content.
• BEHAVIOR: A type parameter for specifying behavior, often used for distinguishing different kinds of behaviors or properties in the array.

Inheritance:

• <: Content{BEHAVIOR}: This indicates that IndexedArray is a subtype of Content with the specified BEHAVIOR parameter.

Fields:

• index::INDEX: An index of type INDEX, which is a subtype of IndexBig.
• content::CONTENT: The actual content of the array, of type CONTENT, which is a subtype of Content.
• parameters::Parameters: An instance of Parameters that holds additional metadata or configuration for the array.

Constructor:

IndexedArray(index::INDEX, content::CONTENT; parameters::Parameters = Parameters(), behavior::Symbol = :default)

This is an inner constructor that allows for the creation of IndexedArray instances. It takes the following arguments:

• index: The index for the array.
• content: The content of the array.
• parameters: Optional parameters for the array, defaulting to a new Parameters instance.
• behavior: An optional symbol indicating the behavior, defaulting to :default.

@example new{INDEX, CONTENT, behavior}(index, content, parameters) The new function is used to create an instance of IndexedArray with the specified fields and type parameters.

IndexedArray{INDEX,CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBig} where {CONTENT<:Content}

Constructor for the IndexedArray, allowing for the creation of an IndexedArray with default values for its components when specific instances are not provided.

IndexedArray{INDEX, CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBig} where {CONTENT<:Content} =
    IndexedArray(INDEX([]), CONTENT(), parameters = parameters, behavior = behavior)

IndexedOptionArray{INDEX<:IndexBigSigned, CONTENT<:Content, BEHAVIOR} <: OptionType{BEHAVIOR}

A type of array where elements are indexed and can be optionally present or missing.

struct IndexedOptionArray{INDEX<:IndexBigSigned, CONTENT<:Content, BEHAVIOR} <: OptionType{BEHAVIOR}
    index::INDEX
    content::CONTENT
    parameters::Parameters

    IndexedOptionArray(
        index::INDEX,
        content::CONTENT;
        parameters::Parameters = Parameters(),
        behavior::Symbol = :default,
    ) where {INDEX<:IndexBigSigned, CONTENT<:Content} =
        new{INDEX, CONTENT, behavior}(index, content, parameters)
end

Type Parameters:

• INDEX<:IndexBigSigned: The INDEX type parameter must be a subtype of IndexBigSigned.
• CONTENT<:Content: The CONTENT type parameter must be a subtype of Content.
• BEHAVIOR: A type parameter without constraints, allowing flexibility in specifying behavior.

Fields:

• index::INDEX: Holds the index values, which determine the presence or absence of elements.
• content::CONTENT: Holds the actual data elements.
• parameters::Parameters: Holds any additional parameters or metadata associated with the array.

Constructor:

The inner constructor IndexedOptionArray takes three arguments: index, content, and optionally parameters and behavior. Default values are provided for parameters (Parameters()) and behavior (:default). The constructor uses new{INDEX, CONTENT, behavior}(index, content, parameters) to create an instance of IndexedOptionArray with the specified types and values.

Inheritance:

<: OptionType{BEHAVIOR} means that IndexedOptionArray is a subtype of OptionType{BEHAVIOR}. This indicates that it is a specialized form of OptionType designed to handle optional or nullable data.

IndexedOptionArray{INDEX,CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBigSigned} where {CONTENT<:Content}

Constructor for the IndexedOptionArray with default values for its parameters and behavior.

LeafType{BEHAVIOR} <: Content{BEHAVIOR}

Abstract type LeafType inherits from Content and is parameterized by BEHAVIOR.

This allows to create a flexible and hierarchical type system where different kinds of content can be represented, and specific behaviors can be parameterized.

ListArray{INDEX<:IndexBig,CONTENT<:Content,BEHAVIOR} <: ListType{BEHAVIOR}

An array of variable-length lists, where the lengths and positions of the lists are specified by starts and stops indices.

Type Parameters:

• INDEX<:IndexBig: This ensures that the type INDEX is a subtype of IndexBig.
• CONTENT<:Content: This ensures that the type CONTENT is a subtype of Content.
• BEHAVIOR: This parameter allows for any type and is used to specify the behavior of the ListArray.

Fields:

• starts::INDEX: An index specifying the starting positions of the lists within the content.
• stops::INDEX: An index specifying the stopping positions of the lists within the content.
• content::CONTENT: The actual content of the array, which contains the elements of the lists.
• parameters::Parameters: Additional parameters that can provide metadata or other information.

Constructor:

The primary constructor initializes a ListArray with given starts, stops indices, and content. parameters::Parameters = Parameters(): This sets a default value for parameters if it is not provided when the constructor is called. behavior::Symbol = :default: This sets a default value for behavior if it is not provided when the constructor is called.

ListArray{INDEX,CONTENT,BEHAVIOR}(;
    parameters::Parameters = Parameters(),
) where {INDEX<:IndexBig} where {CONTENT<:Content} where {BEHAVIOR}

Constructor of a ListArray with default parameters, initializing the starts, stops and content with default values.

ListArray{INDEX,CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBig} where {CONTENT<:Content}

Constructor of a ListArray with default parameters, initializing the starts, stops, content and behavior with default values.

ListOffsetArray{INDEX<:IndexBig,CONTENT<:Content,BEHAVIOR} <: ListType{BEHAVIOR}

A specialized array to represent variable-length lists within a larger array.

Type Parameters:

• INDEX<:IndexBig: Defines a type parameter INDEX which is constrained to subtypes of IndexBig. IndexBig typically refers to integer types capable of holding large indices, such as Int32 or Int64.

• CONTENT<:Content: Defines a type parameter CONTENT which is constrained to subtypes of Content.

• BEHAVIOR: A type parameter for behavior, used to define specialized behaviors or metadata associated with the array.

Inheritance:

• <: ListType{BEHAVIOR}: Indicates that ListOffsetArray is a subtype of ListType.

Fields:

• offsets::INDEX: An array of offsets that indicate the start of each sublist within the content array. The length of this array is one more than the number of sublists, with the last element pointing to the end of the last sublist.

• content::CONTENT: The actual data stored in the array. This can be any kind of array or list of elements.

• parameters::Parameters: A structure to hold additional parameters or metadata associated with the array.

ListOffsetArray{INDEX,CONTENT,BEHAVIOR}(;
    parameters::Parameters = Parameters(),
) where {INDEX<:IndexBig} where {CONTENT<:Content} where {BEHAVIOR}

Constructor of a ListOffsetArray with default parameters, initializing the offsets and content with default values.

ListOffsetArray{INDEX,CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {INDEX<:IndexBig} where {CONTENT<:Content}

Constructor of a ListOffsetArray with default parameters, initializing the offsets, content and behavior with default values.

ListType{BEHAVIOR} <: Content{BEHAVIOR}

Abstract type ListType inherits from Content and is parameterized by BEHAVIOR.

OptionType{BEHAVIOR} <: Content{BEHAVIOR}

Abstract type that serves as a base for other types representing optional or nullable data.

Parameters

Parameters(pairs::Vararg{Pair{String,<:Any}})

Parameters()

PrimitiveArray{ITEM,BUFFER<:AbstractVector{ITEM},BEHAVIOR} <: LeafType{BEHAVIOR}

A specialized array type designed to handle primitive data types with additional parameters and behaviors.

Type Parameters:

• ITEM: Represents the type of the elements stored in the array.

• BUFFER<:AbstractVector{ITEM}: Constrains BUFFER to be a subtype of AbstractVector that holds items of type ITEM.

• BEHAVIOR: A type parameter that can represent different behaviors associated with the array.

Inheritance:

• <: LeafType{BEHAVIOR}: Indicates that PrimitiveArray is a subtype of LeafType parameterized by BEHAVIOR.

Fields:

• data::BUFFER: The main storage for the array, constrained to be an AbstractVector of ITEM.

• parameters::Parameters: Additional parameters associated with the array, presumably defined elsewhere in the code.

Constructor:

• PrimitiveArray(data::BUFFER; parameters::Parameters = Parameters(), behavior::Symbol = :default) where {ITEM,BUFFER<:AbstractVector{ITEM}}: This is the inner constructor for the PrimitiveArray struct. It initializes a new instance of PrimitiveArray with the given data and optional parameters and behavior. The where {ITEM,BUFFER<:AbstractVector{ITEM}} clause ensures that ITEM and BUFFER satisfy the specified constraints.

new{ITEM,BUFFER,behavior}(data, parameters) creates a new instance of PrimitiveArray with the specified type parameters and field values.

PrimitiveArray{ITEM,BUFFER,BEHAVIOR}(;
    parameters::Parameters = Parameters(),
) where {ITEM,BUFFER<:AbstractVector{ITEM},BEHAVIOR}

PrimitiveArray{ITEM,BUFFER}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {ITEM,BUFFER<:AbstractVector{ITEM}}

PrimitiveArray{ITEM}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {ITEM}

Record{FIELDS,CONTENTS<:Base.Tuple{Vararg{Content}},BEHAVIOR}

RecordArray{FIELDS,CONTENTS<:Base.Tuple{Vararg{Content}},BEHAVIOR} <:Content{BEHAVIOR}

RecordArray(
    contents::NamedTuple{FIELDS,CONTENTS};
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {FIELDS,CONTENTS<:Base.Tuple{Vararg{Content}}}

RecordArray{FIELDS,CONTENTS}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {FIELDS,CONTENTS<:Base.Tuple{Vararg{Content}}}

RegularArray{CONTENT<:Content,BEHAVIOR} <: ListType{BEHAVIOR}

A multidimensional array with a fixed size for each dimension, where the overall length of the array is determined by the size of its content and the specified size per dimension.

Type Parameters:

• CONTENT<:Content: Ensures that the type CONTENT is a subtype of Content.
• BEHAVIOR: This parameter can be any type and is used to specify the behavior of the RegularArray.

Fields:

• content::CONTENT: The actual content of the array, which contains the elements.
• size::Int64: The fixed size for each dimension of the array.
• length::Int64: The total length of the array, calculated based on the content length and size.
• parameters::Parameters: Additional parameters that can provide metadata or other information.

Constructor:

The constructor initializes a RegularArray with the given content and size. zeros_length::Int = 0: This sets a default value for the zeros_length parameter if it is not provided. parameters::Parameters = Parameters(): This sets a default value for parameters if it is not provided. behavior::Symbol = :default: This sets a default value for behavior if it is not provided. The length of the array is calculated as zeros_length if size is 0, otherwise it is calculated as the integer division of the length of content by size.

RegularArray{CONTENT}(
    size::Int;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENT<:Content}

Constructor of a RegularArray with default parameters, initializing the behavior and content with default values.

RegularArray{CONTENT,BEHAVIOR}(;
    parameters::Parameters = Parameters(),
) where {CONTENT<:Content,BEHAVIOR}

Constructor of a RegularArray with default parameters, initializing the size and content with default values.

RegularArray{CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENT<:Content}

Constructor of a RegularArray with default parameters, initializing the size, behavior and content with default values.

SlotRecord{CONTENTS<:Base.Tuple{Vararg{Content}},BEHAVIOR}

Specialization{ARRAY<:UnionArray,TAGGED<:Content}

Specialization(layout::UnionArray, tag::Int)

TupleArray{CONTENTS<:Base.Tuple{Vararg{Content}},BEHAVIOR} <:
            Content{BEHAVIOR}

TupleArray(
    contents::CONTENTS;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENTS<:Base.Tuple{Vararg{Content}}}

TupleArray{CONTENTS}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENTS<:Base.Tuple{Vararg{Content}}}

UnionArray{
    TAGS<:Index8,
    INDEX<:IndexBig,
    CONTENTS<:Base.Tuple{Vararg{Content}},
    BEHAVIOR,
} <: Content{BEHAVIOR}

UnionArray{TAGS,INDEX,CONTENTS}(
    contents::CONTENTS;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
)

UnionArray{TAGS,INDEX,CONTENTS}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
)

UnmaskedArray{CONTENT<:Content,BEHAVIOR} <: OptionType{BEHAVIOR}

UnmaskedArray{CONTENT}(;
    parameters::Parameters = Parameters(),
    behavior::Symbol = :default,
) where {CONTENT<:Content}