Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2025-08-28 08:26:54

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017 
0018 // Array accessor classes for List, LargeList, ListView, LargeListView, FixedSizeList,
0019 // Map, Struct, and Union
0020 
0021 #pragma once
0022 
0023 #include <cstdint>
0024 #include <memory>
0025 #include <string>
0026 #include <utility>
0027 #include <vector>
0028 
0029 #include "arrow/array/array_base.h"
0030 #include "arrow/array/data.h"
0031 #include "arrow/result.h"
0032 #include "arrow/status.h"
0033 #include "arrow/type.h"
0034 #include "arrow/type_fwd.h"
0035 #include "arrow/util/checked_cast.h"
0036 #include "arrow/util/macros.h"
0037 #include "arrow/util/visibility.h"
0038 
0039 namespace arrow {
0040 
0041 /// \addtogroup nested-arrays
0042 ///
0043 /// @{
0044 
0045 // ----------------------------------------------------------------------
0046 // VarLengthListLikeArray
0047 
0048 template <typename TYPE>
0049 class VarLengthListLikeArray;
0050 
0051 namespace internal {
0052 
0053 // Private helper for [Large]List[View]Array::SetData.
0054 // Unfortunately, trying to define VarLengthListLikeArray::SetData outside of this header
0055 // doesn't play well with MSVC.
0056 template <typename TYPE>
0057 void SetListData(VarLengthListLikeArray<TYPE>* self,
0058                  const std::shared_ptr<ArrayData>& data,
0059                  Type::type expected_type_id = TYPE::type_id);
0060 
0061 /// \brief A version of Flatten that keeps recursively flattening until an array of
0062 /// non-list values is reached.
0063 ///
0064 /// Array types considered to be lists by this function:
0065 ///  - list
0066 ///  - large_list
0067 ///  - list_view
0068 ///  - large_list_view
0069 ///  - fixed_size_list
0070 ///
0071 /// \see ListArray::Flatten
0072 ARROW_EXPORT Result<std::shared_ptr<Array>> FlattenLogicalListRecursively(
0073     const Array& in_array, MemoryPool* memory_pool);
0074 
0075 }  // namespace internal
0076 
0077 /// Base class for variable-sized list and list-view arrays, regardless of offset size.
0078 template <typename TYPE>
0079 class VarLengthListLikeArray : public Array {
0080  public:
0081   using TypeClass = TYPE;
0082   using offset_type = typename TypeClass::offset_type;
0083 
0084   const TypeClass* var_length_list_like_type() const { return this->list_type_; }
0085 
0086   /// \brief Return array object containing the list's values
0087   ///
0088   /// Note that this buffer does not account for any slice offset or length.
0089   const std::shared_ptr<Array>& values() const { return values_; }
0090 
0091   /// Note that this buffer does not account for any slice offset or length.
0092   const std::shared_ptr<Buffer>& value_offsets() const { return data_->buffers[1]; }
0093 
0094   const std::shared_ptr<DataType>& value_type() const { return list_type_->value_type(); }
0095 
0096   /// Return pointer to raw value offsets accounting for any slice offset
0097   const offset_type* raw_value_offsets() const { return raw_value_offsets_; }
0098 
0099   // The following functions will not perform boundschecking
0100 
0101   offset_type value_offset(int64_t i) const { return raw_value_offsets_[i]; }
0102 
0103   /// \brief Return the size of the value at a particular index
0104   ///
0105   /// Since non-empty null lists and list-views are possible, avoid calling this
0106   /// function when the list at slot i is null.
0107   ///
0108   /// \pre IsValid(i)
0109   virtual offset_type value_length(int64_t i) const = 0;
0110 
0111   /// \pre IsValid(i)
0112   std::shared_ptr<Array> value_slice(int64_t i) const {
0113     return values_->Slice(value_offset(i), value_length(i));
0114   }
0115 
0116   /// \brief Flatten all level recursively until reach a non-list type, and return
0117   /// a non-list type Array.
0118   ///
0119   /// \see internal::FlattenLogicalListRecursively
0120   Result<std::shared_ptr<Array>> FlattenRecursively(
0121       MemoryPool* memory_pool = default_memory_pool()) const {
0122     return internal::FlattenLogicalListRecursively(*this, memory_pool);
0123   }
0124 
0125  protected:
0126   friend void internal::SetListData<TYPE>(VarLengthListLikeArray<TYPE>* self,
0127                                           const std::shared_ptr<ArrayData>& data,
0128                                           Type::type expected_type_id);
0129 
0130   const TypeClass* list_type_ = NULLPTR;
0131   std::shared_ptr<Array> values_;
0132   const offset_type* raw_value_offsets_ = NULLPTR;
0133 };
0134 
0135 // ----------------------------------------------------------------------
0136 // ListArray / LargeListArray
0137 
0138 template <typename TYPE>
0139 class BaseListArray : public VarLengthListLikeArray<TYPE> {
0140  public:
0141   using TypeClass = TYPE;
0142   using offset_type = typename TYPE::offset_type;
0143 
0144   const TypeClass* list_type() const { return this->var_length_list_like_type(); }
0145 
0146   /// \brief Return the size of the value at a particular index
0147   ///
0148   /// Since non-empty null lists are possible, avoid calling this
0149   /// function when the list at slot i is null.
0150   ///
0151   /// \pre IsValid(i)
0152   offset_type value_length(int64_t i) const final {
0153     return this->raw_value_offsets_[i + 1] - this->raw_value_offsets_[i];
0154   }
0155 };
0156 
0157 /// Concrete Array class for list data
0158 class ARROW_EXPORT ListArray : public BaseListArray<ListType> {
0159  public:
0160   explicit ListArray(std::shared_ptr<ArrayData> data);
0161 
0162   ListArray(std::shared_ptr<DataType> type, int64_t length,
0163             std::shared_ptr<Buffer> value_offsets, std::shared_ptr<Array> values,
0164             std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0165             int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0166 
0167   /// \brief Construct ListArray from array of offsets and child value array
0168   ///
0169   /// This function does the bare minimum of validation of the offsets and
0170   /// input types, and will allocate a new offsets array if necessary (i.e. if
0171   /// the offsets contain any nulls). If the offsets do not have nulls, they
0172   /// are assumed to be well-formed.
0173   ///
0174   /// If a null_bitmap is not provided, the nulls will be inferred from the offsets'
0175   /// null bitmap. But if a null_bitmap is provided, the offsets array can't have nulls.
0176   ///
0177   /// And when a null_bitmap is provided, the offsets array cannot be a slice (i.e. an
0178   /// array with offset() > 0).
0179   ///
0180   /// \param[in] offsets Array containing n + 1 offsets encoding length and
0181   /// size. Must be of int32 type
0182   /// \param[in] values Array containing list values
0183   /// \param[in] pool MemoryPool in case new offsets array needs to be
0184   /// allocated because of null values
0185   /// \param[in] null_bitmap Optional validity bitmap
0186   /// \param[in] null_count Optional null count in null_bitmap
0187   static Result<std::shared_ptr<ListArray>> FromArrays(
0188       const Array& offsets, const Array& values, MemoryPool* pool = default_memory_pool(),
0189       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0190       int64_t null_count = kUnknownNullCount);
0191 
0192   static Result<std::shared_ptr<ListArray>> FromArrays(
0193       std::shared_ptr<DataType> type, const Array& offsets, const Array& values,
0194       MemoryPool* pool = default_memory_pool(),
0195       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0196       int64_t null_count = kUnknownNullCount);
0197 
0198   /// \brief Build a ListArray from a ListViewArray
0199   static Result<std::shared_ptr<ListArray>> FromListView(const ListViewArray& source,
0200                                                          MemoryPool* pool);
0201 
0202   /// \brief Return an Array that is a concatenation of the lists in this array.
0203   ///
0204   /// Note that it's different from `values()` in that it takes into
0205   /// consideration of this array's offsets as well as null elements backed
0206   /// by non-empty lists (they are skipped, thus copying may be needed).
0207   Result<std::shared_ptr<Array>> Flatten(
0208       MemoryPool* memory_pool = default_memory_pool()) const;
0209 
0210   /// \brief Return list offsets as an Int32Array
0211   ///
0212   /// The returned array will not have a validity bitmap, so you cannot expect
0213   /// to pass it to ListArray::FromArrays() and get back the same list array
0214   /// if the original one has nulls.
0215   std::shared_ptr<Array> offsets() const;
0216 
0217  protected:
0218   // This constructor defers SetData to a derived array class
0219   ListArray() = default;
0220 
0221   void SetData(const std::shared_ptr<ArrayData>& data);
0222 };
0223 
0224 /// Concrete Array class for large list data (with 64-bit offsets)
0225 class ARROW_EXPORT LargeListArray : public BaseListArray<LargeListType> {
0226  public:
0227   explicit LargeListArray(const std::shared_ptr<ArrayData>& data);
0228 
0229   LargeListArray(const std::shared_ptr<DataType>& type, int64_t length,
0230                  const std::shared_ptr<Buffer>& value_offsets,
0231                  const std::shared_ptr<Array>& values,
0232                  const std::shared_ptr<Buffer>& null_bitmap = NULLPTR,
0233                  int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0234 
0235   /// \brief Construct LargeListArray from array of offsets and child value array
0236   ///
0237   /// This function does the bare minimum of validation of the offsets and
0238   /// input types, and will allocate a new offsets array if necessary (i.e. if
0239   /// the offsets contain any nulls). If the offsets do not have nulls, they
0240   /// are assumed to be well-formed.
0241   ///
0242   /// If a null_bitmap is not provided, the nulls will be inferred from the offsets'
0243   /// null bitmap. But if a null_bitmap is provided, the offsets array can't have nulls.
0244   ///
0245   /// And when a null_bitmap is provided, the offsets array cannot be a slice (i.e. an
0246   /// array with offset() > 0).
0247   ///
0248   /// \param[in] offsets Array containing n + 1 offsets encoding length and
0249   /// size. Must be of int64 type
0250   /// \param[in] values Array containing list values
0251   /// \param[in] pool MemoryPool in case new offsets array needs to be
0252   /// allocated because of null values
0253   /// \param[in] null_bitmap Optional validity bitmap
0254   /// \param[in] null_count Optional null count in null_bitmap
0255   static Result<std::shared_ptr<LargeListArray>> FromArrays(
0256       const Array& offsets, const Array& values, MemoryPool* pool = default_memory_pool(),
0257       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0258       int64_t null_count = kUnknownNullCount);
0259 
0260   static Result<std::shared_ptr<LargeListArray>> FromArrays(
0261       std::shared_ptr<DataType> type, const Array& offsets, const Array& values,
0262       MemoryPool* pool = default_memory_pool(),
0263       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0264       int64_t null_count = kUnknownNullCount);
0265 
0266   /// \brief Build a LargeListArray from a LargeListViewArray
0267   static Result<std::shared_ptr<LargeListArray>> FromListView(
0268       const LargeListViewArray& source, MemoryPool* pool);
0269 
0270   /// \brief Return an Array that is a concatenation of the lists in this array.
0271   ///
0272   /// Note that it's different from `values()` in that it takes into
0273   /// consideration of this array's offsets as well as null elements backed
0274   /// by non-empty lists (they are skipped, thus copying may be needed).
0275   Result<std::shared_ptr<Array>> Flatten(
0276       MemoryPool* memory_pool = default_memory_pool()) const;
0277 
0278   /// \brief Return list offsets as an Int64Array
0279   std::shared_ptr<Array> offsets() const;
0280 
0281  protected:
0282   void SetData(const std::shared_ptr<ArrayData>& data);
0283 };
0284 
0285 // ----------------------------------------------------------------------
0286 // ListViewArray / LargeListViewArray
0287 
0288 template <typename TYPE>
0289 class BaseListViewArray : public VarLengthListLikeArray<TYPE> {
0290  public:
0291   using TypeClass = TYPE;
0292   using offset_type = typename TYPE::offset_type;
0293 
0294   const TypeClass* list_view_type() const { return this->var_length_list_like_type(); }
0295 
0296   /// \brief Note that this buffer does not account for any slice offset or length.
0297   const std::shared_ptr<Buffer>& value_sizes() const { return this->data_->buffers[2]; }
0298 
0299   /// \brief Return pointer to raw value offsets accounting for any slice offset
0300   const offset_type* raw_value_sizes() const { return raw_value_sizes_; }
0301 
0302   /// \brief Return the size of the value at a particular index
0303   ///
0304   /// This should not be called if the list-view at slot i is null.
0305   /// The returned size in those cases could be any value from 0 to the
0306   /// length of the child values array.
0307   ///
0308   /// \pre IsValid(i)
0309   offset_type value_length(int64_t i) const final { return this->raw_value_sizes_[i]; }
0310 
0311  protected:
0312   const offset_type* raw_value_sizes_ = NULLPTR;
0313 };
0314 
0315 /// \brief Concrete Array class for list-view data
0316 class ARROW_EXPORT ListViewArray : public BaseListViewArray<ListViewType> {
0317  public:
0318   explicit ListViewArray(std::shared_ptr<ArrayData> data);
0319 
0320   ListViewArray(std::shared_ptr<DataType> type, int64_t length,
0321                 std::shared_ptr<Buffer> value_offsets,
0322                 std::shared_ptr<Buffer> value_sizes, std::shared_ptr<Array> values,
0323                 std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0324                 int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0325 
0326   /// \brief Construct ListViewArray from array of offsets, sizes, and child
0327   /// value array
0328   ///
0329   /// Construct a ListViewArray using buffers from offsets and sizes arrays
0330   /// that project views into the child values array.
0331   ///
0332   /// This function does the bare minimum of validation of the offsets/sizes and
0333   /// input types. The offset and length of the offsets and sizes arrays must
0334   /// match and that will be checked, but their contents will be assumed to be
0335   /// well-formed.
0336   ///
0337   /// If a null_bitmap is not provided, the nulls will be inferred from the
0338   /// offsets's null bitmap. But if a null_bitmap is provided, the offsets array
0339   /// can't have nulls.
0340   ///
0341   /// And when a null_bitmap is provided, neither the offsets or sizes array can be a
0342   /// slice (i.e. an array with offset() > 0).
0343   ///
0344   /// \param[in] offsets An array of int32 offsets into the values array. NULL values are
0345   /// supported if the corresponding values in sizes is NULL or 0.
0346   /// \param[in] sizes An array containing the int32 sizes of every view. NULL values are
0347   /// taken to represent a NULL list-view in the array being created.
0348   /// \param[in] values Array containing list values
0349   /// \param[in] pool MemoryPool
0350   /// \param[in] null_bitmap Optional validity bitmap
0351   /// \param[in] null_count Optional null count in null_bitmap
0352   static Result<std::shared_ptr<ListViewArray>> FromArrays(
0353       const Array& offsets, const Array& sizes, const Array& values,
0354       MemoryPool* pool = default_memory_pool(),
0355       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0356       int64_t null_count = kUnknownNullCount);
0357 
0358   static Result<std::shared_ptr<ListViewArray>> FromArrays(
0359       std::shared_ptr<DataType> type, const Array& offsets, const Array& sizes,
0360       const Array& values, MemoryPool* pool = default_memory_pool(),
0361       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0362       int64_t null_count = kUnknownNullCount);
0363 
0364   /// \brief Build a ListViewArray from a ListArray
0365   static Result<std::shared_ptr<ListViewArray>> FromList(const ListArray& list_array,
0366                                                          MemoryPool* pool);
0367 
0368   /// \brief Return an Array that is a concatenation of the list-views in this array.
0369   ///
0370   /// Note that it's different from `values()` in that it takes into
0371   /// consideration this array's offsets (which can be in any order)
0372   /// and sizes. Nulls are skipped.
0373   ///
0374   /// This function invokes Concatenate() if list-views are non-contiguous. It
0375   /// will try to minimize the number of array slices passed to Concatenate() by
0376   /// maximizing the size of each slice (containing as many contiguous
0377   /// list-views as possible).
0378   Result<std::shared_ptr<Array>> Flatten(
0379       MemoryPool* memory_pool = default_memory_pool()) const;
0380 
0381   /// \brief Return list-view offsets as an Int32Array
0382   ///
0383   /// The returned array will not have a validity bitmap, so you cannot expect
0384   /// to pass it to ListArray::FromArrays() and get back the same list array
0385   /// if the original one has nulls.
0386   std::shared_ptr<Array> offsets() const;
0387 
0388   /// \brief Return list-view sizes as an Int32Array
0389   ///
0390   /// The returned array will not have a validity bitmap, so you cannot expect
0391   /// to pass it to ListViewArray::FromArrays() and get back the same list
0392   /// array if the original one has nulls.
0393   std::shared_ptr<Array> sizes() const;
0394 
0395  protected:
0396   // This constructor defers SetData to a derived array class
0397   ListViewArray() = default;
0398 
0399   void SetData(const std::shared_ptr<ArrayData>& data);
0400 };
0401 
0402 /// \brief Concrete Array class for large list-view data (with 64-bit offsets
0403 /// and sizes)
0404 class ARROW_EXPORT LargeListViewArray : public BaseListViewArray<LargeListViewType> {
0405  public:
0406   explicit LargeListViewArray(std::shared_ptr<ArrayData> data);
0407 
0408   LargeListViewArray(std::shared_ptr<DataType> type, int64_t length,
0409                      std::shared_ptr<Buffer> value_offsets,
0410                      std::shared_ptr<Buffer> value_sizes, std::shared_ptr<Array> values,
0411                      std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0412                      int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0413 
0414   /// \brief Construct LargeListViewArray from array of offsets, sizes, and child
0415   /// value array
0416   ///
0417   /// Construct an LargeListViewArray using buffers from offsets and sizes arrays
0418   /// that project views into the values array.
0419   ///
0420   /// This function does the bare minimum of validation of the offsets/sizes and
0421   /// input types. The offset and length of the offsets and sizes arrays must
0422   /// match and that will be checked, but their contents will be assumed to be
0423   /// well-formed.
0424   ///
0425   /// If a null_bitmap is not provided, the nulls will be inferred from the offsets' or
0426   /// sizes' null bitmap. Only one of these two is allowed to have a null bitmap. But if a
0427   /// null_bitmap is provided, the offsets array and the sizes array can't have nulls.
0428   ///
0429   /// And when a null_bitmap is provided, neither the offsets or sizes array can be a
0430   /// slice (i.e. an array with offset() > 0).
0431   ///
0432   /// \param[in] offsets An array of int64 offsets into the values array. NULL values are
0433   /// supported if the corresponding values in sizes is NULL or 0.
0434   /// \param[in] sizes An array containing the int64 sizes of every view. NULL values are
0435   /// taken to represent a NULL list-view in the array being created.
0436   /// \param[in] values Array containing list values
0437   /// \param[in] pool MemoryPool
0438   /// \param[in] null_bitmap Optional validity bitmap
0439   /// \param[in] null_count Optional null count in null_bitmap
0440   static Result<std::shared_ptr<LargeListViewArray>> FromArrays(
0441       const Array& offsets, const Array& sizes, const Array& values,
0442       MemoryPool* pool = default_memory_pool(),
0443       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0444       int64_t null_count = kUnknownNullCount);
0445 
0446   static Result<std::shared_ptr<LargeListViewArray>> FromArrays(
0447       std::shared_ptr<DataType> type, const Array& offsets, const Array& sizes,
0448       const Array& values, MemoryPool* pool = default_memory_pool(),
0449       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0450       int64_t null_count = kUnknownNullCount);
0451 
0452   /// \brief Build a LargeListViewArray from a LargeListArray
0453   static Result<std::shared_ptr<LargeListViewArray>> FromList(
0454       const LargeListArray& list_array, MemoryPool* pool);
0455 
0456   /// \brief Return an Array that is a concatenation of the large list-views in this
0457   /// array.
0458   ///
0459   /// Note that it's different from `values()` in that it takes into
0460   /// consideration this array's offsets (which can be in any order)
0461   /// and sizes. Nulls are skipped.
0462   Result<std::shared_ptr<Array>> Flatten(
0463       MemoryPool* memory_pool = default_memory_pool()) const;
0464 
0465   /// \brief Return list-view offsets as an Int64Array
0466   ///
0467   /// The returned array will not have a validity bitmap, so you cannot expect
0468   /// to pass it to LargeListArray::FromArrays() and get back the same list array
0469   /// if the original one has nulls.
0470   std::shared_ptr<Array> offsets() const;
0471 
0472   /// \brief Return list-view sizes as an Int64Array
0473   ///
0474   /// The returned array will not have a validity bitmap, so you cannot expect
0475   /// to pass it to LargeListViewArray::FromArrays() and get back the same list
0476   /// array if the original one has nulls.
0477   std::shared_ptr<Array> sizes() const;
0478 
0479  protected:
0480   // This constructor defers SetData to a derived array class
0481   LargeListViewArray() = default;
0482 
0483   void SetData(const std::shared_ptr<ArrayData>& data);
0484 };
0485 
0486 // ----------------------------------------------------------------------
0487 // MapArray
0488 
0489 /// Concrete Array class for map data
0490 ///
0491 /// NB: "value" in this context refers to a pair of a key and the corresponding item
0492 class ARROW_EXPORT MapArray : public ListArray {
0493  public:
0494   using TypeClass = MapType;
0495 
0496   explicit MapArray(const std::shared_ptr<ArrayData>& data);
0497 
0498   MapArray(const std::shared_ptr<DataType>& type, int64_t length,
0499            const std::shared_ptr<Buffer>& value_offsets,
0500            const std::shared_ptr<Array>& keys, const std::shared_ptr<Array>& items,
0501            const std::shared_ptr<Buffer>& null_bitmap = NULLPTR,
0502            int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0503 
0504   MapArray(const std::shared_ptr<DataType>& type, int64_t length, BufferVector buffers,
0505            const std::shared_ptr<Array>& keys, const std::shared_ptr<Array>& items,
0506            int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0507 
0508   MapArray(const std::shared_ptr<DataType>& type, int64_t length,
0509            const std::shared_ptr<Buffer>& value_offsets,
0510            const std::shared_ptr<Array>& values,
0511            const std::shared_ptr<Buffer>& null_bitmap = NULLPTR,
0512            int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0513 
0514   /// \brief Construct MapArray from array of offsets and child key, item arrays
0515   ///
0516   /// This function does the bare minimum of validation of the offsets and
0517   /// input types, and will allocate a new offsets array if necessary (i.e. if
0518   /// the offsets contain any nulls). If the offsets do not have nulls, they
0519   /// are assumed to be well-formed
0520   ///
0521   /// \param[in] offsets Array containing n + 1 offsets encoding length and
0522   /// size. Must be of int32 type
0523   /// \param[in] keys Array containing key values
0524   /// \param[in] items Array containing item values
0525   /// \param[in] pool MemoryPool in case new offsets array needs to be
0526   /// \param[in] null_bitmap Optional validity bitmap
0527   /// allocated because of null values
0528   static Result<std::shared_ptr<Array>> FromArrays(
0529       const std::shared_ptr<Array>& offsets, const std::shared_ptr<Array>& keys,
0530       const std::shared_ptr<Array>& items, MemoryPool* pool = default_memory_pool(),
0531       std::shared_ptr<Buffer> null_bitmap = NULLPTR);
0532 
0533   static Result<std::shared_ptr<Array>> FromArrays(
0534       std::shared_ptr<DataType> type, const std::shared_ptr<Array>& offsets,
0535       const std::shared_ptr<Array>& keys, const std::shared_ptr<Array>& items,
0536       MemoryPool* pool = default_memory_pool(),
0537       std::shared_ptr<Buffer> null_bitmap = NULLPTR);
0538 
0539   const MapType* map_type() const { return map_type_; }
0540 
0541   /// \brief Return array object containing all map keys
0542   const std::shared_ptr<Array>& keys() const { return keys_; }
0543 
0544   /// \brief Return array object containing all mapped items
0545   const std::shared_ptr<Array>& items() const { return items_; }
0546 
0547   /// Validate child data before constructing the actual MapArray.
0548   static Status ValidateChildData(
0549       const std::vector<std::shared_ptr<ArrayData>>& child_data);
0550 
0551  protected:
0552   void SetData(const std::shared_ptr<ArrayData>& data);
0553 
0554   static Result<std::shared_ptr<Array>> FromArraysInternal(
0555       std::shared_ptr<DataType> type, const std::shared_ptr<Array>& offsets,
0556       const std::shared_ptr<Array>& keys, const std::shared_ptr<Array>& items,
0557       MemoryPool* pool, std::shared_ptr<Buffer> null_bitmap = NULLPTR);
0558 
0559  private:
0560   const MapType* map_type_;
0561   std::shared_ptr<Array> keys_, items_;
0562 };
0563 
0564 // ----------------------------------------------------------------------
0565 // FixedSizeListArray
0566 
0567 /// Concrete Array class for fixed size list data
0568 class ARROW_EXPORT FixedSizeListArray : public Array {
0569  public:
0570   using TypeClass = FixedSizeListType;
0571   using offset_type = TypeClass::offset_type;
0572 
0573   explicit FixedSizeListArray(const std::shared_ptr<ArrayData>& data);
0574 
0575   FixedSizeListArray(const std::shared_ptr<DataType>& type, int64_t length,
0576                      const std::shared_ptr<Array>& values,
0577                      const std::shared_ptr<Buffer>& null_bitmap = NULLPTR,
0578                      int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0579 
0580   const FixedSizeListType* list_type() const;
0581 
0582   /// \brief Return array object containing the list's values
0583   const std::shared_ptr<Array>& values() const;
0584 
0585   const std::shared_ptr<DataType>& value_type() const;
0586 
0587   // The following functions will not perform boundschecking
0588   int64_t value_offset(int64_t i) const {
0589     i += data_->offset;
0590     return list_size_ * i;
0591   }
0592   /// \brief Return the fixed-size of the values
0593   ///
0594   /// No matter the value of the index parameter, the result is the same.
0595   /// So even when the value at slot i is null, this function will return a
0596   /// non-zero size.
0597   ///
0598   /// \pre IsValid(i)
0599   int32_t value_length(int64_t i = 0) const {
0600     ARROW_UNUSED(i);
0601     return list_size_;
0602   }
0603   /// \pre IsValid(i)
0604   std::shared_ptr<Array> value_slice(int64_t i) const {
0605     return values_->Slice(value_offset(i), value_length(i));
0606   }
0607 
0608   /// \brief Return an Array that is a concatenation of the lists in this array.
0609   ///
0610   /// Note that it's different from `values()` in that it takes into
0611   /// consideration null elements (they are skipped, thus copying may be needed).
0612   Result<std::shared_ptr<Array>> Flatten(
0613       MemoryPool* memory_pool = default_memory_pool()) const;
0614 
0615   /// \brief Flatten all level recursively until reach a non-list type, and return
0616   /// a non-list type Array.
0617   ///
0618   /// \see internal::FlattenLogicalListRecursively
0619   Result<std::shared_ptr<Array>> FlattenRecursively(
0620       MemoryPool* memory_pool = default_memory_pool()) const {
0621     return internal::FlattenLogicalListRecursively(*this, memory_pool);
0622   }
0623 
0624   /// \brief Construct FixedSizeListArray from child value array and value_length
0625   ///
0626   /// \param[in] values Array containing list values
0627   /// \param[in] list_size The fixed length of each list
0628   /// \param[in] null_bitmap Optional validity bitmap
0629   /// \param[in] null_count Optional null count in null_bitmap
0630   /// \return Will have length equal to values.length() / list_size
0631   static Result<std::shared_ptr<Array>> FromArrays(
0632       const std::shared_ptr<Array>& values, int32_t list_size,
0633       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0634       int64_t null_count = kUnknownNullCount);
0635 
0636   /// \brief Construct FixedSizeListArray from child value array and type
0637   ///
0638   /// \param[in] values Array containing list values
0639   /// \param[in] type The fixed sized list type
0640   /// \param[in] null_bitmap Optional validity bitmap
0641   /// \param[in] null_count Optional null count in null_bitmap
0642   /// \return Will have length equal to values.length() / type.list_size()
0643   static Result<std::shared_ptr<Array>> FromArrays(
0644       const std::shared_ptr<Array>& values, std::shared_ptr<DataType> type,
0645       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0646       int64_t null_count = kUnknownNullCount);
0647 
0648  protected:
0649   void SetData(const std::shared_ptr<ArrayData>& data);
0650   int32_t list_size_;
0651 
0652  private:
0653   std::shared_ptr<Array> values_;
0654 };
0655 
0656 // ----------------------------------------------------------------------
0657 // Struct
0658 
0659 /// Concrete Array class for struct data
0660 class ARROW_EXPORT StructArray : public Array {
0661  public:
0662   using TypeClass = StructType;
0663 
0664   explicit StructArray(const std::shared_ptr<ArrayData>& data);
0665 
0666   StructArray(const std::shared_ptr<DataType>& type, int64_t length,
0667               const std::vector<std::shared_ptr<Array>>& children,
0668               std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0669               int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0670 
0671   /// \brief Return a StructArray from child arrays and field names.
0672   ///
0673   /// The length and data type are automatically inferred from the arguments.
0674   /// There should be at least one child array.
0675   static Result<std::shared_ptr<StructArray>> Make(
0676       const ArrayVector& children, const std::vector<std::string>& field_names,
0677       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0678       int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0679 
0680   /// \brief Return a StructArray from child arrays and fields.
0681   ///
0682   /// The length is automatically inferred from the arguments.
0683   /// There should be at least one child array.  This method does not
0684   /// check that field types and child array types are consistent.
0685   static Result<std::shared_ptr<StructArray>> Make(
0686       const ArrayVector& children, const FieldVector& fields,
0687       std::shared_ptr<Buffer> null_bitmap = NULLPTR,
0688       int64_t null_count = kUnknownNullCount, int64_t offset = 0);
0689 
0690   const StructType* struct_type() const;
0691 
0692   // Return a shared pointer in case the requestor desires to share ownership
0693   // with this array.  The returned array has its offset, length and null
0694   // count adjusted.
0695   const std::shared_ptr<Array>& field(int pos) const;
0696 
0697   const ArrayVector& fields() const;
0698 
0699   /// Returns null if name not found
0700   std::shared_ptr<Array> GetFieldByName(const std::string& name) const;
0701 
0702   /// Indicate if field named `name` can be found unambiguously in the struct.
0703   Status CanReferenceFieldByName(const std::string& name) const;
0704 
0705   /// Indicate if fields named `names` can be found unambiguously in the struct.
0706   Status CanReferenceFieldsByNames(const std::vector<std::string>& names) const;
0707 
0708   /// \brief Flatten this array as a vector of arrays, one for each field
0709   ///
0710   /// \param[in] pool The pool to allocate null bitmaps from, if necessary
0711   Result<ArrayVector> Flatten(MemoryPool* pool = default_memory_pool()) const;
0712 
0713   /// \brief Get one of the child arrays, combining its null bitmap
0714   /// with the parent struct array's bitmap.
0715   ///
0716   /// \param[in] index Which child array to get
0717   /// \param[in] pool The pool to allocate null bitmaps from, if necessary
0718   Result<std::shared_ptr<Array>> GetFlattenedField(
0719       int index, MemoryPool* pool = default_memory_pool()) const;
0720 
0721  private:
0722   // For caching boxed child data
0723   // XXX This is not handled in a thread-safe manner.
0724   mutable ArrayVector boxed_fields_;
0725 };
0726 
0727 // ----------------------------------------------------------------------
0728 // Union
0729 
0730 /// Base class for SparseUnionArray and DenseUnionArray
0731 class ARROW_EXPORT UnionArray : public Array {
0732  public:
0733   using type_code_t = int8_t;
0734 
0735   /// Note that this buffer does not account for any slice offset
0736   const std::shared_ptr<Buffer>& type_codes() const { return data_->buffers[1]; }
0737 
0738   const type_code_t* raw_type_codes() const { return raw_type_codes_; }
0739 
0740   /// The logical type code of the value at index.
0741   type_code_t type_code(int64_t i) const { return raw_type_codes_[i]; }
0742 
0743   /// The physical child id containing value at index.
0744   int child_id(int64_t i) const { return union_type_->child_ids()[raw_type_codes_[i]]; }
0745 
0746   const UnionType* union_type() const { return union_type_; }
0747 
0748   UnionMode::type mode() const { return union_type_->mode(); }
0749 
0750   /// \brief Return the given field as an individual array.
0751   ///
0752   /// For sparse unions, the returned array has its offset, length and null
0753   /// count adjusted.
0754   std::shared_ptr<Array> field(int pos) const;
0755 
0756  protected:
0757   void SetData(std::shared_ptr<ArrayData> data);
0758 
0759   const type_code_t* raw_type_codes_;
0760   const UnionType* union_type_;
0761 
0762   // For caching boxed child data
0763   mutable std::vector<std::shared_ptr<Array>> boxed_fields_;
0764 };
0765 
0766 /// Concrete Array class for sparse union data
0767 class ARROW_EXPORT SparseUnionArray : public UnionArray {
0768  public:
0769   using TypeClass = SparseUnionType;
0770 
0771   explicit SparseUnionArray(std::shared_ptr<ArrayData> data);
0772 
0773   SparseUnionArray(std::shared_ptr<DataType> type, int64_t length, ArrayVector children,
0774                    std::shared_ptr<Buffer> type_ids, int64_t offset = 0);
0775 
0776   /// \brief Construct SparseUnionArray from type_ids and children
0777   ///
0778   /// This function does the bare minimum of validation of the input types.
0779   ///
0780   /// \param[in] type_ids An array of logical type ids for the union type
0781   /// \param[in] children Vector of children Arrays containing the data for each type.
0782   /// \param[in] type_codes Vector of type codes.
0783   static Result<std::shared_ptr<Array>> Make(const Array& type_ids, ArrayVector children,
0784                                              std::vector<type_code_t> type_codes) {
0785     return Make(std::move(type_ids), std::move(children), std::vector<std::string>{},
0786                 std::move(type_codes));
0787   }
0788 
0789   /// \brief Construct SparseUnionArray with custom field names from type_ids and children
0790   ///
0791   /// This function does the bare minimum of validation of the input types.
0792   ///
0793   /// \param[in] type_ids An array of logical type ids for the union type
0794   /// \param[in] children Vector of children Arrays containing the data for each type.
0795   /// \param[in] field_names Vector of strings containing the name of each field.
0796   /// \param[in] type_codes Vector of type codes.
0797   static Result<std::shared_ptr<Array>> Make(const Array& type_ids, ArrayVector children,
0798                                              std::vector<std::string> field_names = {},
0799                                              std::vector<type_code_t> type_codes = {});
0800 
0801   const SparseUnionType* union_type() const {
0802     return internal::checked_cast<const SparseUnionType*>(union_type_);
0803   }
0804 
0805   /// \brief Get one of the child arrays, adjusting its null bitmap
0806   /// where the union array type code does not match.
0807   ///
0808   /// \param[in] index Which child array to get (i.e. the physical index, not the type
0809   /// code) \param[in] pool The pool to allocate null bitmaps from, if necessary
0810   Result<std::shared_ptr<Array>> GetFlattenedField(
0811       int index, MemoryPool* pool = default_memory_pool()) const;
0812 
0813  protected:
0814   void SetData(std::shared_ptr<ArrayData> data);
0815 };
0816 
0817 /// \brief Concrete Array class for dense union data
0818 ///
0819 /// Note that union types do not have a validity bitmap
0820 class ARROW_EXPORT DenseUnionArray : public UnionArray {
0821  public:
0822   using TypeClass = DenseUnionType;
0823 
0824   explicit DenseUnionArray(const std::shared_ptr<ArrayData>& data);
0825 
0826   DenseUnionArray(std::shared_ptr<DataType> type, int64_t length, ArrayVector children,
0827                   std::shared_ptr<Buffer> type_ids,
0828                   std::shared_ptr<Buffer> value_offsets = NULLPTR, int64_t offset = 0);
0829 
0830   /// \brief Construct DenseUnionArray from type_ids, value_offsets, and children
0831   ///
0832   /// This function does the bare minimum of validation of the offsets and
0833   /// input types.
0834   ///
0835   /// \param[in] type_ids An array of logical type ids for the union type
0836   /// \param[in] value_offsets An array of signed int32 values indicating the
0837   /// relative offset into the respective child array for the type in a given slot.
0838   /// The respective offsets for each child value array must be in order / increasing.
0839   /// \param[in] children Vector of children Arrays containing the data for each type.
0840   /// \param[in] type_codes Vector of type codes.
0841   static Result<std::shared_ptr<Array>> Make(const Array& type_ids,
0842                                              const Array& value_offsets,
0843                                              ArrayVector children,
0844                                              std::vector<type_code_t> type_codes) {
0845     return Make(type_ids, value_offsets, std::move(children), std::vector<std::string>{},
0846                 std::move(type_codes));
0847   }
0848 
0849   /// \brief Construct DenseUnionArray with custom field names from type_ids,
0850   /// value_offsets, and children
0851   ///
0852   /// This function does the bare minimum of validation of the offsets and
0853   /// input types.
0854   ///
0855   /// \param[in] type_ids An array of logical type ids for the union type
0856   /// \param[in] value_offsets An array of signed int32 values indicating the
0857   /// relative offset into the respective child array for the type in a given slot.
0858   /// The respective offsets for each child value array must be in order / increasing.
0859   /// \param[in] children Vector of children Arrays containing the data for each type.
0860   /// \param[in] field_names Vector of strings containing the name of each field.
0861   /// \param[in] type_codes Vector of type codes.
0862   static Result<std::shared_ptr<Array>> Make(const Array& type_ids,
0863                                              const Array& value_offsets,
0864                                              ArrayVector children,
0865                                              std::vector<std::string> field_names = {},
0866                                              std::vector<type_code_t> type_codes = {});
0867 
0868   const DenseUnionType* union_type() const {
0869     return internal::checked_cast<const DenseUnionType*>(union_type_);
0870   }
0871 
0872   /// Note that this buffer does not account for any slice offset
0873   const std::shared_ptr<Buffer>& value_offsets() const { return data_->buffers[2]; }
0874 
0875   int32_t value_offset(int64_t i) const { return raw_value_offsets_[i]; }
0876 
0877   const int32_t* raw_value_offsets() const { return raw_value_offsets_; }
0878 
0879  protected:
0880   const int32_t* raw_value_offsets_;
0881 
0882   void SetData(const std::shared_ptr<ArrayData>& data);
0883 };
0884 
0885 /// @}
0886 
0887 }  // namespace arrow