// Licensed to the Apache Software Foundation (ASF) under one // or more contributor license agreements. See the NOTICE file // distributed with this work for additional information // regarding copyright ownership. The ASF licenses this file // to you 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 implied. See the License for the // specific language governing permissions and limitations // under the License. // Object model for scalar (non-Array) values. Not intended for use with large // amounts of data #pragma once #include #include #include #include #include #include #include #include "arrow/compare.h" #include "arrow/extension_type.h" #include "arrow/result.h" #include "arrow/status.h" #include "arrow/type.h" #include "arrow/type_fwd.h" #include "arrow/type_traits.h" #include "arrow/util/compare.h" #include "arrow/util/decimal.h" #include "arrow/util/visibility.h" #include "arrow/visit_type_inline.h" namespace arrow { class Array; /// \brief Base class for scalar values /// /// A Scalar represents a single value with a specific DataType. /// Scalars are useful for passing single value inputs to compute functions, /// or for representing individual array elements (with a non-trivial /// wrapping cost, though). struct ARROW_EXPORT Scalar : public std::enable_shared_from_this, public util::EqualityComparable { virtual ~Scalar() = default; /// \brief The type of the scalar value std::shared_ptr type; /// \brief Whether the value is valid (not null) or not bool is_valid = false; bool Equals(const Scalar& other, const EqualOptions& options = EqualOptions::Defaults()) const; bool ApproxEquals(const Scalar& other, const EqualOptions& options = EqualOptions::Defaults()) const; struct ARROW_EXPORT Hash { size_t operator()(const Scalar& scalar) const { return scalar.hash(); } size_t operator()(const std::shared_ptr& scalar) const { return scalar->hash(); } }; size_t hash() const; std::string ToString() const; /// \brief Perform cheap validation checks /// /// This is O(k) where k is the number of descendents. /// /// \return Status Status Validate() const; /// \brief Perform extensive data validation checks /// /// This is potentially O(k*n) where k is the number of descendents and n /// is the length of descendents (if list scalars are involved). /// /// \return Status Status ValidateFull() const; static Result> Parse(const std::shared_ptr& type, std::string_view repr); // TODO(bkietz) add compute::CastOptions Result> CastTo(std::shared_ptr to) const; /// \brief Apply the ScalarVisitor::Visit() method specialized to the scalar type Status Accept(ScalarVisitor* visitor) const; /// \brief EXPERIMENTAL Enable obtaining shared_ptr from a const /// Scalar& context. std::shared_ptr GetSharedPtr() const { return const_cast(this)->shared_from_this(); } protected: Scalar(std::shared_ptr type, bool is_valid) : type(std::move(type)), is_valid(is_valid) {} }; ARROW_EXPORT void PrintTo(const Scalar& scalar, std::ostream* os); /// \defgroup concrete-scalar-classes Concrete Scalar subclasses /// /// @{ /// \brief A scalar value for NullType. Never valid struct ARROW_EXPORT NullScalar : public Scalar { public: using TypeClass = NullType; NullScalar() : Scalar{null(), false} {} }; /// @} namespace internal { struct ARROW_EXPORT ArraySpanFillFromScalarScratchSpace { // 16 bytes of scratch space to enable ArraySpan to be a view onto any // Scalar- including binary scalars where we need to create a buffer // that looks like two 32-bit or 64-bit offsets. alignas(int64_t) mutable uint8_t scratch_space_[sizeof(int64_t) * 2]; }; struct ARROW_EXPORT PrimitiveScalarBase : public Scalar { explicit PrimitiveScalarBase(std::shared_ptr type) : Scalar(std::move(type), false) {} using Scalar::Scalar; /// \brief Get a const pointer to the value of this scalar. May be null. virtual const void* data() const = 0; /// \brief Get a mutable pointer to the value of this scalar. May be null. virtual void* mutable_data() = 0; /// \brief Get an immutable view of the value of this scalar as bytes. virtual std::string_view view() const = 0; }; template struct ARROW_EXPORT PrimitiveScalar : public PrimitiveScalarBase { using PrimitiveScalarBase::PrimitiveScalarBase; using TypeClass = T; using ValueType = CType; // Non-null constructor. PrimitiveScalar(ValueType value, std::shared_ptr type) : PrimitiveScalarBase(std::move(type), true), value(value) {} explicit PrimitiveScalar(std::shared_ptr type) : PrimitiveScalarBase(std::move(type), false) {} ValueType value{}; const void* data() const override { return &value; } void* mutable_data() override { return &value; } std::string_view view() const override { return std::string_view(reinterpret_cast(&value), sizeof(ValueType)); }; }; } // namespace internal /// \addtogroup concrete-scalar-classes Concrete Scalar subclasses /// /// @{ struct ARROW_EXPORT BooleanScalar : public internal::PrimitiveScalar { using Base = internal::PrimitiveScalar; using Base::Base; explicit BooleanScalar(bool value) : Base(value, boolean()) {} BooleanScalar() : Base(boolean()) {} }; template struct NumericScalar : public internal::PrimitiveScalar { using Base = typename internal::PrimitiveScalar; using Base::Base; using TypeClass = typename Base::TypeClass; using ValueType = typename Base::ValueType; explicit NumericScalar(ValueType value) : Base(value, TypeTraits::type_singleton()) {} NumericScalar() : Base(TypeTraits::type_singleton()) {} }; struct ARROW_EXPORT Int8Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT Int16Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT Int32Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT Int64Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT UInt8Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT UInt16Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT UInt32Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT UInt64Scalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT HalfFloatScalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT FloatScalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT DoubleScalar : public NumericScalar { using NumericScalar::NumericScalar; }; struct ARROW_EXPORT BaseBinaryScalar : public internal::PrimitiveScalarBase, private internal::ArraySpanFillFromScalarScratchSpace { using internal::PrimitiveScalarBase::PrimitiveScalarBase; using ValueType = std::shared_ptr; std::shared_ptr value; const void* data() const override { return value ? reinterpret_cast(value->data()) : NULLPTR; } void* mutable_data() override { return value ? reinterpret_cast(value->mutable_data()) : NULLPTR; } std::string_view view() const override { return value ? std::string_view(*value) : std::string_view(); } BaseBinaryScalar(std::shared_ptr value, std::shared_ptr type) : internal::PrimitiveScalarBase{std::move(type), true}, value(std::move(value)) {} friend ArraySpan; BaseBinaryScalar(std::string s, std::shared_ptr type); }; struct ARROW_EXPORT BinaryScalar : public BaseBinaryScalar { using BaseBinaryScalar::BaseBinaryScalar; using TypeClass = BinaryType; explicit BinaryScalar(std::shared_ptr value) : BinaryScalar(std::move(value), binary()) {} explicit BinaryScalar(std::string s) : BaseBinaryScalar(std::move(s), binary()) {} BinaryScalar() : BinaryScalar(binary()) {} }; struct ARROW_EXPORT StringScalar : public BinaryScalar { using BinaryScalar::BinaryScalar; using TypeClass = StringType; explicit StringScalar(std::shared_ptr value) : StringScalar(std::move(value), utf8()) {} explicit StringScalar(std::string s) : BinaryScalar(std::move(s), utf8()) {} StringScalar() : StringScalar(utf8()) {} }; struct ARROW_EXPORT BinaryViewScalar : public BaseBinaryScalar { using BaseBinaryScalar::BaseBinaryScalar; using TypeClass = BinaryViewType; explicit BinaryViewScalar(std::shared_ptr value) : BinaryViewScalar(std::move(value), binary_view()) {} explicit BinaryViewScalar(std::string s) : BaseBinaryScalar(std::move(s), binary_view()) {} BinaryViewScalar() : BinaryViewScalar(binary_view()) {} std::string_view view() const override { return std::string_view(*this->value); } }; struct ARROW_EXPORT StringViewScalar : public BinaryViewScalar { using BinaryViewScalar::BinaryViewScalar; using TypeClass = StringViewType; explicit StringViewScalar(std::shared_ptr value) : StringViewScalar(std::move(value), utf8_view()) {} explicit StringViewScalar(std::string s) : BinaryViewScalar(std::move(s), utf8_view()) {} StringViewScalar() : StringViewScalar(utf8_view()) {} }; struct ARROW_EXPORT LargeBinaryScalar : public BaseBinaryScalar { using BaseBinaryScalar::BaseBinaryScalar; using TypeClass = LargeBinaryType; LargeBinaryScalar(std::shared_ptr value, std::shared_ptr type) : BaseBinaryScalar(std::move(value), std::move(type)) {} explicit LargeBinaryScalar(std::shared_ptr value) : LargeBinaryScalar(std::move(value), large_binary()) {} explicit LargeBinaryScalar(std::string s) : BaseBinaryScalar(std::move(s), large_binary()) {} LargeBinaryScalar() : LargeBinaryScalar(large_binary()) {} }; struct ARROW_EXPORT LargeStringScalar : public LargeBinaryScalar { using LargeBinaryScalar::LargeBinaryScalar; using TypeClass = LargeStringType; explicit LargeStringScalar(std::shared_ptr value) : LargeStringScalar(std::move(value), large_utf8()) {} explicit LargeStringScalar(std::string s) : LargeBinaryScalar(std::move(s), large_utf8()) {} LargeStringScalar() : LargeStringScalar(large_utf8()) {} }; struct ARROW_EXPORT FixedSizeBinaryScalar : public BinaryScalar { using TypeClass = FixedSizeBinaryType; FixedSizeBinaryScalar(std::shared_ptr value, std::shared_ptr type, bool is_valid = true); explicit FixedSizeBinaryScalar(const std::shared_ptr& value, bool is_valid = true); explicit FixedSizeBinaryScalar(std::string s, bool is_valid = true); }; template struct TemporalScalar : internal::PrimitiveScalar { using internal::PrimitiveScalar::PrimitiveScalar; using ValueType = typename internal::PrimitiveScalar::ValueType; TemporalScalar(ValueType value, std::shared_ptr type) : internal::PrimitiveScalar(std::move(value), type) {} }; template struct DateScalar : public TemporalScalar { using TemporalScalar::TemporalScalar; using ValueType = typename TemporalScalar::ValueType; explicit DateScalar(ValueType value) : TemporalScalar(std::move(value), TypeTraits::type_singleton()) {} DateScalar() : TemporalScalar(TypeTraits::type_singleton()) {} }; struct ARROW_EXPORT Date32Scalar : public DateScalar { using DateScalar::DateScalar; }; struct ARROW_EXPORT Date64Scalar : public DateScalar { using DateScalar::DateScalar; }; template struct ARROW_EXPORT TimeScalar : public TemporalScalar { using TemporalScalar::TemporalScalar; TimeScalar(typename TemporalScalar::ValueType value, TimeUnit::type unit) : TimeScalar(std::move(value), std::make_shared(unit)) {} }; struct ARROW_EXPORT Time32Scalar : public TimeScalar { using TimeScalar::TimeScalar; }; struct ARROW_EXPORT Time64Scalar : public TimeScalar { using TimeScalar::TimeScalar; }; struct ARROW_EXPORT TimestampScalar : public TemporalScalar { using TemporalScalar::TemporalScalar; TimestampScalar(typename TemporalScalar::ValueType value, TimeUnit::type unit, std::string tz = "") : TimestampScalar(std::move(value), timestamp(unit, std::move(tz))) {} static Result FromISO8601(std::string_view iso8601, TimeUnit::type unit); }; template struct IntervalScalar : public TemporalScalar { using TemporalScalar::TemporalScalar; using ValueType = typename TemporalScalar::ValueType; explicit IntervalScalar(ValueType value) : TemporalScalar(value, TypeTraits::type_singleton()) {} IntervalScalar() : TemporalScalar(TypeTraits::type_singleton()) {} }; struct ARROW_EXPORT MonthIntervalScalar : public IntervalScalar { using IntervalScalar::IntervalScalar; }; struct ARROW_EXPORT DayTimeIntervalScalar : public IntervalScalar { using IntervalScalar::IntervalScalar; }; struct ARROW_EXPORT MonthDayNanoIntervalScalar : public IntervalScalar { using IntervalScalar::IntervalScalar; }; struct ARROW_EXPORT DurationScalar : public TemporalScalar { using TemporalScalar::TemporalScalar; DurationScalar(typename TemporalScalar::ValueType value, TimeUnit::type unit) : DurationScalar(std::move(value), duration(unit)) {} // Convenience constructors for a DurationScalar from std::chrono::nanoseconds template