diff --git a/docs/src/functions.md b/docs/src/functions.md index e7a175d..37d5aad 100644 --- a/docs/src/functions.md +++ b/docs/src/functions.md @@ -1,7 +1,14 @@ ```@meta CurrentModule = AwkwardArray ``` -## List of [`Content`](@ref) functions + +# Functions + +```@contents +Pages = ["functions.md"] +``` + +## Built-in functions Every [`Content`](@ref) subclass has the following built-in functions: @@ -15,7 +22,24 @@ Every [`Content`](@ref) subclass has the following built-in functions: * [`Base.append!`](@ref) * [`Base.show`](@ref) -They also have the following functions for manipulating and checking structure: +```@docs +Base.length +Base.size +Base.firstindex +Base.lastindex +Base.getindex +Base.iterate +Base.eltype +Base.:(==) +Base.push! +Base.append! +Base.show +Base.keys +``` + +## Manipulating and checking structure + +Every [`Content`](@ref) subclass has the following functions for manipulating and checking structure: * [`AwkwardArray.parameters_of`](@ref) gets all parameters * [`AwkwardArray.has_parameter`](@ref) returns true if a parameter exists @@ -24,24 +48,52 @@ They also have the following functions for manipulating and checking structure: * [`AwkwardArray.copy`](@ref) shallow-copy of the array, allowing properties to be replaced * [`AwkwardArray.is_valid`](@ref) verifies that the structure adheres to Awkward Array's protocol -They have the following functions for filling an array: +```@docs +parameters_of +has_parameter +get_parameter +with_parameter +copy +is_valid +``` + +## Filling an array + +Every [`Content`](@ref) subclass has the following functions for filling an array: * [`AwkwardArray.end_list!`](@ref): closes off a [`ListType`](@ref) array ([`ListOffsetArray`](@ref), [`ListArray`](@ref), or [`RegularArray`](@ref)) in the manner of Python's [ak.ArrayBuilder](https://awkward-array.org/doc/main/reference/generated/ak.ArrayBuilder.html) (no `begin_list` is necessary) * [`AwkwardArray.end_record!`](@ref) closes off a [`RecordArray`](@ref) * [`AwkwardArray.end_tuple!`](@ref) closes off a [`TupleArray`](@ref) -* [`AwkwardArray.push_null!`](@ref) pushes a missing value onto [`OptionType`](@ref) arrays (`IndexedOptionArray`](@ref) [`ByteMaskedArray`](@ref) [`BitMaskedArray`](@ref) or [`UnmaskedArray`](@ref)) +* [`AwkwardArray.push_null!`](@ref) pushes a missing value onto [`OptionType`](@ref) arrays ([`IndexedOptionArray`](@ref) [`ByteMaskedArray`](@ref) [`BitMaskedArray`](@ref) or [`UnmaskedArray`](@ref)) * [`AwkwardArray.push_dummy!`](@ref) pushes an unspecified value onto the array (used by [`ByteMaskedArray`](@ref) and [`BitMaskedArray`](@ref) which need to have a placeholder in memory behind each `missing` value) +```@docs +end_list! +end_record! +end_tuple! +push_null! +push_dummy! +``` +## Selecting fields + [`RecordArray`](@ref)and [`TupleArray`](@ref) have the following for selecting fields (as opposed to rows): * [`AwkwardArray.slot`](@ref) gets a [`RecordArray`](@ref)or [`TupleArray`](@ref) field, to avoid conflicts with [`Base.getindex`](@ref) for `TupleArrays` (both use integers to select a field) * [`AwkwardArray.Record`](@ref) scalar representation of an item from a [`RecordArray`](@ref) * [`AwkwardArray.SlotRecord`](@ref) scalar representation of an item from a [`TupleArray`](@ref)(note: not the same as `Base.Tuple`) +```@docs +AwkwardArray.slot +``` + +## Specializations + [`UnionArray`](@ref)has the following for dealing with specializations: * [`AwkwardArray.Specialization`](@ref) selects a [`UnionArray`](@ref)specialization for [`push!`](@ref) [`append!`](@ref) etc. +## Convertion + Finally, all [`Content`](@ref)subclasses can be converted with the following: * [`AwkwardArray.layout_for`](@ref) returns an appropriately-nested [`Content`](@ref)type for a given Julia type (`DataType`) @@ -50,13 +102,46 @@ Finally, all [`Content`](@ref)subclasses can be converted with the following: * [`AwkwardArray.from_buffers`](@ref) constructs an Awkward Array from a Form (JSON), length, and buffers for zero-copy passing from Python * [`AwkwardArray.to_buffers`](@ref) deconstructs an Awkward Array into a Form (JSON), length, and buffers for zero-copy passing to Python +```@docs +AwkwardArray.layout_for +AwkwardArray.from_iter +AwkwardArray.to_vector +AwkwardArray.to_vector_or_scalar +AwkwardArray.from_buffers +AwkwardArray.to_buffers +``` -## Array functions +## Arrays of Stings + +```@docs +ByteStringOffsetArray +ByteStringArray +ByteStringRegularArray +StringArray +StringOffsetArray +StringRegularArray +``` + +## Utilities + +```@docs +AwkwardArray.isprimitive +AwkwardArray.default_buffer_key +AwkwardArray.compatible +AwkwardArray.check_primitive_type +``` -```@autodocs -Modules = [AwkwardArray] -Public = true -Order = [:function] +## Private functions + +```@docs +AwkwardArray._alternate +AwkwardArray._get_buffer +AwkwardArray._get_index +AwkwardArray._horizontal +AwkwardArray._to_buffers! +AwkwardArray._to_buffers_index +AwkwardArray._to_buffers_parameters +AwkwardArray._vertical ``` # Index diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index 5efc673..1e4ee50 100644 --- a/docs/src/getting_started.md +++ b/docs/src/getting_started.md @@ -6,6 +6,13 @@ Let's assume that both Python and Julia are installed. It is recommended to use [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) virtul environment. +!!! note + If Julia is not install it is recomended to install it from a conda-forge channel: + + ```python + conda install -c conda-forge julia + ``` + ## Using Julia Awkward Arrays from Python - To install [Awkward Array](https://github.com/scikit-hep/awkward) Python package: diff --git a/src/all_implementations.jl b/src/all_implementations.jl index 922c4ed..8b3f09e 100644 --- a/src/all_implementations.jl +++ b/src/all_implementations.jl @@ -984,7 +984,7 @@ end parameters::Parameters = Parameters(), ) where {INDEX<:IndexBig} where {CONTENT<:Content} where {BEHAVIOR} -Constructor of a [`ListArray`](@ref) with default parameters, initializing the starts, stops and content with default values. +Constructor of a `ListArray` with default parameters, initializing the starts, stops and content with default values. """ ListArray{INDEX,CONTENT,BEHAVIOR}(; parameters::Parameters = Parameters(), @@ -997,7 +997,7 @@ ListArray{INDEX,CONTENT,BEHAVIOR}(; behavior::Symbol = :default, ) where {INDEX<:IndexBig} where {CONTENT<:Content} -Constructor of a [`ListArray`](@ref) with default parameters, initializing the starts, stops, content and behavior with default values. +Constructor of a `ListArray` with default parameters, initializing the starts, stops, content and behavior with default values. """ ListArray{INDEX,CONTENT}(; parameters::Parameters = Parameters(), @@ -1015,7 +1015,7 @@ ListArray{INDEX,CONTENT}(; behavior::Union{Unset,Symbol} = Unset(), ) where {INDEX1<:IndexBig,INDEX2<:IndexBig,CONTENT1<:Content,CONTENT2<:Content,BEHAVIOR} -Copy of a [`ListArray`](@ref). +Copy of a `ListArray`. """ function copy( layout::ListArray{INDEX1,CONTENT1,BEHAVIOR}; @@ -1695,7 +1695,16 @@ end byte_parameters::Parameters = Parameters(), ) where {INDEX<:IndexBig} -[`ListType`](@ref) with `behavior` = `:bytestring`. +The function that constructs a specialized array type for handling byte strings with specific offsets. + + - `offsets`: This is an array of indices (`INDEX`) which determines where each string starts within the byte array. + - `data`: This is a vector of `UInt8` (unsigned 8-bit integers), representing the raw bytes of the strings. + - `parameters`: Optional parameters for configuring the `ListOffsetArray`. + - `byte_parameters`: Optional parameters specifically for the `PrimitiveArray` holding the byte data. + - `INDEX<:` Ensures that offsets is a subtype of `IndexBig`, which typically implies a larger indexing type suitable for big data. + +!!! note + It is a [`ListType`](@ref) with `behavior` = `:bytestring`. """ ByteStringOffsetArray( offsets::INDEX, @@ -1714,6 +1723,8 @@ ByteStringOffsetArray( parameters::Parameters = Parameters(), byte_parameters::Parameters = Parameters(), ) + +A default constructor that initializes an empty `ByteStringOffsetArray`. """ ByteStringOffsetArray(; parameters::Parameters = Parameters(), @@ -1733,6 +1744,8 @@ ByteStringOffsetArray(; parameters::Parameters = Parameters(), byte_parameters::Parameters = Parameters(), ) where {INDEX<:IndexBig} + +The `ByteStringArray` function constructs a specialized array type for handling byte strings, similar to `ByteStringOffsetArray`, but it uses separate `starts` and `stops` indices rather than a single `offsets` array. """ ByteStringArray( starts::INDEX, @@ -1753,6 +1766,8 @@ ByteStringArray( parameters::Parameters = Parameters(), byte_parameters::Parameters = Parameters(), ) + +A default constructor that initializes an empty `ByteStringArray`. """ ByteStringArray(; parameters::Parameters = Parameters(), @@ -2854,7 +2869,7 @@ IndexedOptionArray{INDEX,CONTENT}(; BEHAVIOR, } -Copy of an [`IndexedOptionArray`](@ref), potentially with some modifications to its fields. +Copy of an `IndexedOptionArray`, potentially with some modifications to its fields. """ function copy( layout::IndexedOptionArray{INDEX1,CONTENT1,BEHAVIOR};