scalar.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2019-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */
#pragma once
 
#include <cudf/column/column.hpp>
#include <cudf/detail/device_scalar.hpp>
#include <cudf/table/table.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/default_stream.hpp>
#include <cudf/utilities/memory_resource.hpp>
#include <cudf/utilities/traits.hpp>
 
#include <rmm/device_buffer.hpp>
#include <rmm/device_scalar.hpp>
 
#include <cuda/stream>
 
#include <span>
#include <string_view>
 
namespace CUDF_EXPORT cudf {
class scalar {
 public:
  scalar()                               = delete;
  virtual ~scalar()                      = default;
  scalar& operator=(scalar const& other) = delete;
  scalar& operator=(scalar&& other)      = delete;
 
  [[nodiscard]] data_type type() const noexcept;
 
  void set_valid_async(bool is_valid, cuda::stream_ref stream = cudf::get_default_stream());
 
  [[nodiscard]] bool is_valid(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  bool* validity_data();
 
  [[nodiscard]] bool const* validity_data() const;
 
 protected:
  data_type _type{type_id::EMPTY};              
  cudf::detail::device_scalar<bool> _is_valid;  
 
  scalar(scalar&& other) = default;
 
  scalar(scalar const& other,
         cuda::stream_ref stream           = cudf::get_default_stream(),
         rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  scalar(data_type type,
         bool is_valid                     = false,
         cuda::stream_ref stream           = cudf::get_default_stream(),
         rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
};
 
namespace detail {
template <typename T>
class fixed_width_scalar : public scalar {
  static_assert(is_fixed_width<T>(), "Unexpected non-fixed-width type.");
 
 public:
  using value_type = T;  
 
  fixed_width_scalar()           = delete;
  ~fixed_width_scalar() override = default;
 
  fixed_width_scalar(fixed_width_scalar&& other) = default;
 
  fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
  fixed_width_scalar& operator=(fixed_width_scalar&& other)      = delete;
 
  fixed_width_scalar(fixed_width_scalar const& other,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  void set_value(T value, cuda::stream_ref stream = cudf::get_default_stream());
 
  [[nodiscard]] T value(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  T* data();
 
  [[nodiscard]] T const* data() const;
 
 protected:
  cudf::detail::device_scalar<T> _data;  
 
  fixed_width_scalar(T value,
                     bool is_valid                     = true,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  fixed_width_scalar(cudf::detail::device_scalar<T>&& data,
                     bool is_valid                     = true,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
};
 
}  // namespace detail
 
template <typename T>
class numeric_scalar : public detail::fixed_width_scalar<T> {
  static_assert(is_numeric<T>(), "Unexpected non-numeric type.");
 
 public:
  numeric_scalar()           = delete;
  ~numeric_scalar() override = default;
 
  numeric_scalar(numeric_scalar&& other) = default;
 
  numeric_scalar& operator=(numeric_scalar const& other) = delete;
  numeric_scalar& operator=(numeric_scalar&& other)      = delete;
 
  numeric_scalar(numeric_scalar const& other,
                 cuda::stream_ref stream           = cudf::get_default_stream(),
                 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  numeric_scalar(T value,
                 bool is_valid                     = true,
                 cuda::stream_ref stream           = cudf::get_default_stream(),
                 rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit numeric_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[deprecated("Use the cudf::scalar constructor instead.")]] numeric_scalar(
    rmm::device_scalar<T>&& data,
    bool is_valid                     = true,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
};
 
template <typename T>
class fixed_point_scalar : public scalar {
  static_assert(is_fixed_point<T>(), "Unexpected non-fixed_point type.");
 
 public:
  using rep_type   = typename T::rep;  
  using value_type = T;                
 
  fixed_point_scalar()           = delete;
  ~fixed_point_scalar() override = default;
 
  fixed_point_scalar(fixed_point_scalar&& other) = default;
 
  fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
  fixed_point_scalar& operator=(fixed_point_scalar&& other)      = delete;
 
  fixed_point_scalar(fixed_point_scalar const& other,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  fixed_point_scalar(rep_type value,
                     numeric::scale_type scale,
                     bool is_valid                     = true,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  fixed_point_scalar(rep_type value,
                     bool is_valid                     = true,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  fixed_point_scalar(T value,
                     bool is_valid                     = true,
                     cuda::stream_ref stream           = cudf::get_default_stream(),
                     rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit fixed_point_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[deprecated("Use the cudf::scalar constructor instead.")]] fixed_point_scalar(
    rmm::device_scalar<rep_type>&& data,
    numeric::scale_type scale,
    bool is_valid                     = true,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[nodiscard]] rep_type value(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  [[nodiscard]] T fixed_point_value(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  rep_type* data();
 
  [[nodiscard]] rep_type const* data() const;
 
 protected:
  cudf::detail::device_scalar<rep_type> _data;  
};
 
class string_scalar : public scalar {
 public:
  using value_type = cudf::string_view;  
 
  string_scalar()           = delete;
  ~string_scalar() override = default;
 
  string_scalar(string_scalar&& other) = default;
 
  // string_scalar(string_scalar const& other) = delete;
  string_scalar& operator=(string_scalar const& other) = delete;
  string_scalar& operator=(string_scalar&& other)      = delete;
 
  string_scalar(string_scalar const& other,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  string_scalar(std::string_view string,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  string_scalar(value_type const& source,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit string_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[deprecated("Use the cudf::scalar constructor instead.")]] string_scalar(
    rmm::device_scalar<value_type>& data,
    bool is_valid                     = true,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  string_scalar(rmm::device_buffer&& data,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[nodiscard]] std::string to_string(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  [[nodiscard]] value_type value(cuda::stream_ref stream = cudf::get_default_stream()) const;
 
  [[nodiscard]] size_type size() const;
 
  [[nodiscard]] char const* data() const;
 
 protected:
  rmm::device_buffer _data{};  
};
 
template <typename T>
class chrono_scalar : public detail::fixed_width_scalar<T> {
  static_assert(is_chrono<T>(), "Unexpected non-chrono type");
 
 public:
  chrono_scalar()           = delete;
  ~chrono_scalar() override = default;
 
  chrono_scalar(chrono_scalar&& other) = default;
 
  chrono_scalar& operator=(chrono_scalar const& other) = delete;
  chrono_scalar& operator=(chrono_scalar&& other)      = delete;
 
  chrono_scalar(chrono_scalar const& other,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  chrono_scalar(T value,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit chrono_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[deprecated("Use the cudf::scalar constructor instead.")]] chrono_scalar(
    rmm::device_scalar<T>&& data,
    bool is_valid                     = true,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
};
 
template <typename T>
class timestamp_scalar : public chrono_scalar<T> {
 public:
  static_assert(is_timestamp<T>(), "Unexpected non-timestamp type");
  using chrono_scalar<T>::chrono_scalar;
  using rep_type = typename T::rep;  
 
  timestamp_scalar() = delete;
 
  timestamp_scalar(timestamp_scalar&& other) = default;
 
  timestamp_scalar(timestamp_scalar const& other,
                   cuda::stream_ref stream           = cudf::get_default_stream(),
                   rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit timestamp_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())
    : chrono_scalar<T>(data, stream, mr)
  {
  }
 
  template <typename Duration2>
  timestamp_scalar(Duration2 const& value,
                   bool is_valid,
                   cuda::stream_ref stream           = cudf::get_default_stream(),
                   rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  rep_type ticks_since_epoch(cuda::stream_ref stream);
};
 
template <typename T>
class duration_scalar : public chrono_scalar<T> {
 public:
  static_assert(is_duration<T>(), "Unexpected non-duration type");
  using chrono_scalar<T>::chrono_scalar;
  using rep_type = typename T::rep;  
 
  duration_scalar() = delete;
 
  duration_scalar(duration_scalar&& other) = default;
 
  duration_scalar(duration_scalar const& other,
                  cuda::stream_ref stream           = cudf::get_default_stream(),
                  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  explicit duration_scalar(
    scalar const& data,
    cuda::stream_ref stream           = cudf::get_default_stream(),
    rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())
    : chrono_scalar<T>(data, stream, mr)
  {
  }
 
  duration_scalar(rep_type value,
                  bool is_valid,
                  cuda::stream_ref stream           = cudf::get_default_stream(),
                  rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  rep_type count(cuda::stream_ref stream);
};
 
class list_scalar : public scalar {
 public:
  list_scalar()           = delete;
  ~list_scalar() override = default;
 
  list_scalar(list_scalar&& other) = default;
 
  list_scalar& operator=(list_scalar const& other) = delete;
  list_scalar& operator=(list_scalar&& other)      = delete;
 
  list_scalar(list_scalar const& other,
              cuda::stream_ref stream           = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  list_scalar(cudf::column_view const& data,
              bool is_valid                     = true,
              cuda::stream_ref stream           = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  list_scalar(cudf::column&& data,
              bool is_valid                     = true,
              cuda::stream_ref stream           = cudf::get_default_stream(),
              rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[nodiscard]] column_view view() const;
 
 private:
  cudf::column _data;
};
 
class struct_scalar : public scalar {
 public:
  struct_scalar()           = delete;
  ~struct_scalar() override = default;
 
  struct_scalar(struct_scalar&& other)                 = default;
  struct_scalar& operator=(struct_scalar const& other) = delete;
  struct_scalar& operator=(struct_scalar&& other)      = delete;
 
  struct_scalar(struct_scalar const& other,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  struct_scalar(table_view const& data,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  struct_scalar(std::span<column_view const> data,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  struct_scalar(table&& data,
                bool is_valid                     = true,
                cuda::stream_ref stream           = cudf::get_default_stream(),
                rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref());
 
  [[nodiscard]] table_view view() const;
 
 private:
  table _data;
 
  void assert_valid_size();
 
  static table init_data(table&& data,
                         bool is_valid,
                         cuda::stream_ref stream,
                         rmm::device_async_resource_ref mr);
};
  // end of group
}  // namespace CUDF_EXPORT cudf