arrow/compute/cast.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 <memory>
0021 #include <string>
0022 #include <vector>
0023
0024 #include "arrow/compute/function.h"
0025 #include "arrow/compute/function_options.h"
0026 #include "arrow/compute/type_fwd.h"
0027 #include "arrow/result.h"
0028 #include "arrow/status.h"
0029 #include "arrow/type.h"
0030 #include "arrow/util/macros.h"
0031 #include "arrow/util/visibility.h"
0032
0033 namespace arrow {
0034
0035 class Array;
0036
0037 namespace compute {
0038
0039 class ExecContext;
0040
0041 /// \addtogroup compute-concrete-options
0042 /// @{
0043
0044 class ARROW_EXPORT CastOptions : public FunctionOptions {
0045  public:
0046   explicit CastOptions(bool safe = true);
0047
0048   static constexpr char const kTypeName[] = "CastOptions";
0049   static CastOptions Safe(TypeHolder to_type = {}) {
0050     CastOptions safe(true);
0051     safe.to_type = std::move(to_type);
0052     return safe;
0053   }
0054
0055   static CastOptions Unsafe(TypeHolder to_type = {}) {
0056     CastOptions unsafe(false);
0057     unsafe.to_type = std::move(to_type);
0058     return unsafe;
0059   }
0060
0061   // Type being casted to. May be passed separate to eager function
0062   // compute::Cast
0063   TypeHolder to_type;
0064
0065   bool allow_int_overflow;
0066   bool allow_time_truncate;
0067   bool allow_time_overflow;
0068   bool allow_decimal_truncate;
0069   bool allow_float_truncate;
0070   // Indicate if conversions from Binary/FixedSizeBinary to string must
0071   // validate the utf8 payload.
0072   bool allow_invalid_utf8;
0073
0074   /// true if the safety options all match CastOptions::Safe
0075   ///
0076   /// Note, if this returns false it does not mean is_unsafe will return true
0077   bool is_safe() const;
0078   /// true if the safety options all match CastOptions::Unsafe
0079   ///
0080   /// Note, if this returns false it does not mean is_safe will return true
0081   bool is_unsafe() const;
0082 };
0083
0084 /// @}
0085
0086 /// \brief Return true if a cast function is defined
0087 ARROW_EXPORT
0088 bool CanCast(const DataType& from_type, const DataType& to_type);
0089
0090 // ----------------------------------------------------------------------
0091 // Convenience invocation APIs for a number of kernels
0092
0093 /// \brief Cast from one array type to another
0094 /// \param[in] value array to cast
0095 /// \param[in] to_type type to cast to
0096 /// \param[in] options casting options
0097 /// \param[in] ctx the function execution context, optional
0098 /// \return the resulting array
0099 ///
0100 /// \since 1.0.0
0101 /// \note API not yet finalized
0102 ARROW_EXPORT
0103 Result<std::shared_ptr<Array>> Cast(const Array& value, const TypeHolder& to_type,
0104                                     const CastOptions& options = CastOptions::Safe(),
0105                                     ExecContext* ctx = NULLPTR);
0106
0107 /// \brief Cast from one array type to another
0108 /// \param[in] value array to cast
0109 /// \param[in] options casting options. The "to_type" field must be populated
0110 /// \param[in] ctx the function execution context, optional
0111 /// \return the resulting array
0112 ///
0113 /// \since 1.0.0
0114 /// \note API not yet finalized
0115 ARROW_EXPORT
0116 Result<Datum> Cast(const Datum& value, const CastOptions& options,
0117                    ExecContext* ctx = NULLPTR);
0118
0119 /// \brief Cast from one value to another
0120 /// \param[in] value datum to cast
0121 /// \param[in] to_type type to cast to
0122 /// \param[in] options casting options
0123 /// \param[in] ctx the function execution context, optional
0124 /// \return the resulting datum
0125 ///
0126 /// \since 1.0.0
0127 /// \note API not yet finalized
0128 ARROW_EXPORT
0129 Result<Datum> Cast(const Datum& value, const TypeHolder& to_type,
0130                    const CastOptions& options = CastOptions::Safe(),
0131                    ExecContext* ctx = NULLPTR);
0132
0133 }  // namespace compute
0134 }  // namespace arrow