arrow/array/util.h

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 #pragma once
0019
0020 #include <cstdint>
0021 #include <memory>
0022 #include <vector>
0023
0024 #include "arrow/array/data.h"
0025 #include "arrow/compare.h"
0026 #include "arrow/result.h"
0027 #include "arrow/status.h"
0028 #include "arrow/type.h"
0029 #include "arrow/util/macros.h"
0030 #include "arrow/util/visibility.h"
0031
0032 namespace arrow {
0033
0034 /// \defgroup array-factories Array factory functions
0035 ///
0036 /// @{
0037
0038 /// \brief Create a strongly-typed Array instance from generic ArrayData
0039 /// \param[in] data the array contents
0040 /// \return the resulting Array instance
0041 ARROW_EXPORT
0042 std::shared_ptr<Array> MakeArray(const std::shared_ptr<ArrayData>& data);
0043
0044 /// \brief Create a strongly-typed Array instance with all elements null
0045 /// \param[in] type the array type
0046 /// \param[in] length the array length
0047 /// \param[in] pool the memory pool to allocate memory from
0048 ARROW_EXPORT
0049 Result<std::shared_ptr<Array>> MakeArrayOfNull(const std::shared_ptr<DataType>& type,
0050                                                int64_t length,
0051                                                MemoryPool* pool = default_memory_pool());
0052
0053 /// \brief Create an Array instance whose slots are the given scalar
0054 /// \param[in] scalar the value with which to fill the array
0055 /// \param[in] length the array length
0056 /// \param[in] pool the memory pool to allocate memory from
0057 ARROW_EXPORT
0058 Result<std::shared_ptr<Array>> MakeArrayFromScalar(
0059     const Scalar& scalar, int64_t length, MemoryPool* pool = default_memory_pool());
0060
0061 /// \brief Create an empty Array of a given type
0062 ///
0063 /// The output Array will be of the given type.
0064 ///
0065 /// \param[in] type the data type of the empty Array
0066 /// \param[in] pool the memory pool to allocate memory from
0067 /// \return the resulting Array
0068 ARROW_EXPORT
0069 Result<std::shared_ptr<Array>> MakeEmptyArray(std::shared_ptr<DataType> type,
0070                                               MemoryPool* pool = default_memory_pool());
0071
0072 /// @}
0073
0074 namespace internal {
0075
0076 /// \brief Swap endian of each element in a generic ArrayData
0077 ///
0078 /// As dictionaries are often shared between different arrays, dictionaries
0079 /// are not swapped by this function and should be handled separately.
0080 ///
0081 /// \param[in] data the array contents
0082 /// \param[in] pool the memory pool to allocate memory from
0083 /// \return the resulting ArrayData whose elements were swapped
0084 ARROW_EXPORT
0085 Result<std::shared_ptr<ArrayData>> SwapEndianArrayData(
0086     const std::shared_ptr<ArrayData>& data, MemoryPool* pool = default_memory_pool());
0087
0088 /// Given a number of ArrayVectors, treat each ArrayVector as the
0089 /// chunks of a chunked array.  Then rechunk each ArrayVector such that
0090 /// all ArrayVectors are chunked identically.  It is mandatory that
0091 /// all ArrayVectors contain the same total number of elements.
0092 ARROW_EXPORT
0093 std::vector<ArrayVector> RechunkArraysConsistently(const std::vector<ArrayVector>&);
0094
0095 }  // namespace internal
0096 }  // namespace arrow