array_api.hpp

Go to the documentation of this file.

// Copyright 2024 Man Group Operations Limited
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or mplied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
#pragma once
 
#include <iterator>
#include <ranges>
#include <stdexcept>
 
#include "sparrow/array_iterator.hpp"
#include "sparrow/c_interface.hpp"
#include "sparrow/config/config.hpp"
#include "sparrow/layout/array_access.hpp"
#include "sparrow/layout/array_wrapper.hpp"
#include "sparrow/layout/layout_concept.hpp"
#include "sparrow/layout/list_value.hpp"
#include "sparrow/layout/map_value.hpp"
#include "sparrow/layout/struct_value.hpp"
#include "sparrow/null_array.hpp"
#include "sparrow/types/data_traits.hpp"
#include "sparrow/utils/contracts.hpp"
#include "sparrow/utils/iterator.hpp"
#include "sparrow/utils/memory.hpp"
 
namespace sparrow
{
    class array
    {
    public:
 
        using size_type = std::size_t;
        using value_type = array_traits::value_type;
        using const_reference = array_traits::const_reference;
 
        using const_iterator = array_const_iterator;
        using iterator = const_iterator;

        array() = default;

        template <layout A>
            requires(not std::is_lvalue_reference_v<A>)
        constexpr explicit array(A&& a);

        template <layout A>
        constexpr explicit array(A* a);

        template <layout A>
        constexpr explicit array(std::shared_ptr<A> a);

        SPARROW_API array(ArrowArray&& array, ArrowSchema&& schema);

        SPARROW_API array(ArrowArray&& array, ArrowSchema* schema);

        SPARROW_API array(ArrowArray* array, ArrowSchema* schema);

        constexpr array(const array& rhs) = default;

        array& operator=(const array& rhs) = default;

        array(array&& rhs) = default;

        array& operator=(array&& rhs) = default;

        [[nodiscard]] SPARROW_API enum data_type data_type() const;

        [[nodiscard]] SPARROW_API std::optional<array> dictionary() const;

        [[nodiscard]] auto children() const
        {
            return get_arrow_proxy().children()
                   | std::views::transform(
                       [](const arrow_proxy& child)
                       {
                           return array{child.view()};
                       }
                   );
        }

        [[nodiscard]] SPARROW_API std::optional<std::string_view> name() const;

        SPARROW_API void set_name(std::optional<std::string_view> name);

        [[nodiscard]] SPARROW_API std::optional<key_value_view> metadata() const;

        template <input_metadata_container R = std::vector<metadata_pair>>
        constexpr void set_metadata(std::optional<R> metadata);

        [[nodiscard]] SPARROW_API bool empty() const;

        [[nodiscard]] SPARROW_API size_type size() const;

        [[nodiscard]] SPARROW_API size_type offset() const;

        [[nodiscard]] SPARROW_API std::int64_t null_count() const;

        [[nodiscard]] SPARROW_API const_reference at(size_type index) const;

        SPARROW_API const_reference operator[](size_type index) const;

        [[nodiscard]] SPARROW_API const_reference front() const;

        [[nodiscard]] SPARROW_API const_reference back() const;

        [[nodiscard]] SPARROW_API iterator begin() const;

        [[nodiscard]] SPARROW_API iterator end() const;

        [[nodiscard]] SPARROW_API const_iterator cbegin() const;

        [[nodiscard]] SPARROW_API const_iterator cend() const;
 
        template <class F>
        using visit_result_t = std::invoke_result_t<F, null_array>;

        template <class F>
        constexpr visit_result_t<F> visit(F&& func) const;

        [[nodiscard]] SPARROW_API array view() const;

        [[nodiscard]] SPARROW_API bool is_view() const;

        [[nodiscard]] SPARROW_API bool is_dictionary() const;

        [[nodiscard]] SPARROW_API array slice(size_type start, size_type end) const;

        [[nodiscard]] SPARROW_API array slice_view(size_type start, size_type end) const;

        SPARROW_API void slice_inplace(size_type start, size_type end);

        SPARROW_API iterator insert(const_iterator pos, const_iterator first, const_iterator last);

        SPARROW_API
        iterator insert(const_iterator pos, const_iterator first, const_iterator last, size_type count);

        SPARROW_API iterator erase(const_iterator pos);

        SPARROW_API iterator erase(const_iterator first, const_iterator last);
 
 
    private:

        SPARROW_API array(arrow_proxy&& proxy);

        [[nodiscard]] SPARROW_API arrow_proxy& get_arrow_proxy();

        [[nodiscard]] SPARROW_API const arrow_proxy& get_arrow_proxy() const;
 
        cloning_ptr<array_wrapper> p_array = nullptr;
 
        friend class detail::array_access;
    };

    SPARROW_API
    bool operator==(const array& lhs, const array& rhs);
 
    template <class A>
    concept layout_or_array = layout<A> or std::same_as<A, array>;

    template <layout_or_array A>
    bool owns_arrow_array(const A& a);

    template <layout_or_array A>
    bool owns_arrow_schema(const A& a);

    template <layout_or_array A>
    ArrowArray* get_arrow_array(A& a);

    template <layout_or_array A>
    const ArrowArray* get_arrow_array(const A& a);

    template <layout_or_array A>
    ArrowSchema* get_arrow_schema(A& a);

    template <layout_or_array A>
    const ArrowSchema* get_arrow_schema(const A& a);

    template <layout_or_array A>
    std::pair<ArrowArray*, ArrowSchema*> get_arrow_structures(A& a);

    template <layout_or_array A>
    std::pair<const ArrowArray*, const ArrowSchema*> get_arrow_structures(const A& a);

    template <layout_or_array A>
    ArrowArray extract_arrow_array(A&& a);

    template <layout_or_array A>
    ArrowSchema extract_arrow_schema(A&& a);

    template <layout_or_array A>
    std::pair<ArrowArray, ArrowSchema> extract_arrow_structures(A&& a);
 
    // Implementation
 
    template <input_metadata_container R>
    constexpr void array::set_metadata(std::optional<R> metadata)
    {
        get_arrow_proxy().set_metadata(metadata);
    }
}