Skip to content

Commit

Permalink
Add missing documentation in scalar/ headers (NVIDIA#10861)
Browse files Browse the repository at this point in the history 
fixes part of rapidsai/cudf#9373

Add missing documentation in scalar/ headers to fix doxygen warnings

Authors:
  - Karthikeyan (https://github.com/karthikeyann)

Approvers:
  - Bradley Dice (https://github.com/bdice)
  - Vyas Ramasubramani (https://github.com/vyasr)

URL: rapidsai/cudf#10861
  • Loading branch information
@karthikeyann
karthikeyann authored May 18, 2022
1 parent 851418c commit 7b393a7
Show file tree
Hide file tree
Showing 3 changed files with 226 additions and 32 deletions.
148 changes: 121 additions & 27 deletions cpp/include/cudf/scalar/scalar.hpp
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2019-2021, NVIDIA CORPORATION.
* Copyright (c) 2019-2022, NVIDIA CORPORATION.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -51,6 +51,8 @@ class scalar {

/**
* @brief Returns the scalar's logical value type.
*
* @return The scalar's logical value type
*/
[[nodiscard]] data_type type() const noexcept;

Expand All @@ -69,18 +71,22 @@ class scalar {
* function does a stream synchronization.
*
* @param stream CUDA stream used for device memory operations.
* @return true Value is valid.
* @return false Value is invalid/null.
* @return true Value is valid
* @return false Value is invalid/null
*/
[[nodiscard]] bool is_valid(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;

/**
* @brief Returns a raw pointer to the validity bool in device memory.
*
* @return Raw pointer to the validity bool in device memory
*/
bool* validity_data();

/**
* @brief Returns a const raw pointer to the validity bool in device memory.
* @brief Return a const raw pointer to the validity bool in device memory.
*
* @return Raw pointer to the validity bool in device memory
*/
[[nodiscard]] bool const* validity_data() const;

Expand All @@ -90,6 +96,10 @@ class scalar {

scalar() = delete;

/**
* @brief Move constructor for scalar.
* @param other The other scalar to move from.
*/
scalar(scalar&& other) = default;

/**
Expand Down Expand Up @@ -121,14 +131,24 @@ class scalar {
};

namespace detail {
/**
* @brief An owning class to represent a fixed-width type value in device memory.
*
* @tparam T the data type of the fixed-width type value.
*/
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;
using value_type = T; ///< Type of the value held by the scalar.

~fixed_width_scalar() override = default;

~fixed_width_scalar() override = default;
/**
* @brief Move constructor for fixed_width_scalar.
* @param other The other fixed_width_scalar to move from.
*/
fixed_width_scalar(fixed_width_scalar&& other) = default;

fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
Expand Down Expand Up @@ -162,16 +182,19 @@ class fixed_width_scalar : public scalar {
* @brief Get the value of the scalar.
*
* @param stream CUDA stream used for device memory operations.
* @return Value of the scalar
*/
T value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;

/**
* @brief Returns a raw pointer to the value in device memory.
* @return A raw pointer to the value in device memory
*/
T* data();

/**
* @brief Returns a const raw pointer to the value in device memory.
* @return A const raw pointer to the value in device memory
*/
T const* data() const;

Expand Down Expand Up @@ -219,8 +242,13 @@ class numeric_scalar : public detail::fixed_width_scalar<T> {
static_assert(is_numeric<T>(), "Unexpected non-numeric type.");

public:
numeric_scalar() = delete;
~numeric_scalar() = default;
numeric_scalar() = delete;
~numeric_scalar() = default;

/**
* @brief Move constructor for numeric_scalar.
* @param other The other numeric_scalar to move from.
*/
numeric_scalar(numeric_scalar&& other) = default;

numeric_scalar& operator=(numeric_scalar const& other) = delete;
Expand Down Expand Up @@ -274,11 +302,16 @@ 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;
using rep_type = typename T::rep; ///< The representation type of the fixed_point number.
using value_type = T; ///< The value type of the fixed_point number.

fixed_point_scalar() = delete;
~fixed_point_scalar() override = default;

fixed_point_scalar() = delete;
~fixed_point_scalar() override = default;
/**
* @brief Move constructor for fixed_point_scalar.
* @param other The other fixed_point_scalar to move from.
*/
fixed_point_scalar(fixed_point_scalar&& other) = default;

fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
Expand Down Expand Up @@ -355,13 +388,15 @@ class fixed_point_scalar : public scalar {
* @brief Get the value of the scalar.
*
* @param stream CUDA stream used for device memory operations.
* @return The value of the scalar
*/
rep_type value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;

/**
* @brief Get the decimal32, decimal64 or decimal128.
*
* @param stream CUDA stream used for device memory operations.
* @return The decimal32, decimal64 or decimal128 value
*/
T fixed_point_value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;

Expand All @@ -372,11 +407,13 @@ class fixed_point_scalar : public scalar {

/**
* @brief Returns a raw pointer to the value in device memory.
* @return A raw pointer to the value in device memory
*/
rep_type* data();

/**
* @brief Returns a const raw pointer to the value in device memory.
* @return a const raw pointer to the value in device memory
*/
rep_type const* data() const;

Expand All @@ -389,10 +426,15 @@ class fixed_point_scalar : public scalar {
*/
class string_scalar : public scalar {
public:
using value_type = cudf::string_view;
using value_type = cudf::string_view; ///< The value type of the string scalar.

string_scalar() = delete;
~string_scalar() override = default;

string_scalar() = delete;
~string_scalar() override = default;
/**
* @brief Move constructor for string_scalar.
* @param other The other string_scalar to move from.
*/
string_scalar(string_scalar&& other) = default;

// string_scalar(string_scalar const& other) = delete;
Expand Down Expand Up @@ -478,6 +520,7 @@ class string_scalar : public scalar {
* @brief Get the value of the scalar in a host std::string.
*
* @param stream CUDA stream used for device memory operations.
* @return The value of the scalar in a host std::string
*/
[[nodiscard]] std::string to_string(
rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
Expand All @@ -486,16 +529,19 @@ class string_scalar : public scalar {
* @brief Get the value of the scalar as a string_view.
*
* @param stream CUDA stream used for device memory operations.
* @return The value of the scalar as a string_view
*/
[[nodiscard]] value_type value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;

/**
* @brief Returns the size of the string in bytes.
* @return The size of the string in bytes
*/
[[nodiscard]] size_type size() const;

/**
* @brief Returns a raw pointer to the string in device memory.
* @return a raw pointer to the string in device memory
*/
[[nodiscard]] const char* data() const;

Expand All @@ -514,8 +560,13 @@ class chrono_scalar : public detail::fixed_width_scalar<T> {
static_assert(is_chrono<T>(), "Unexpected non-chrono type");

public:
chrono_scalar() = delete;
~chrono_scalar() = default;
chrono_scalar() = delete;
~chrono_scalar() = default;

/**
* @brief Move constructor for chrono_scalar.
* @param other The other chrono_scalar to move from.
*/
chrono_scalar(chrono_scalar&& other) = default;

chrono_scalar& operator=(chrono_scalar const& other) = delete;
Expand Down Expand Up @@ -559,14 +610,25 @@ class chrono_scalar : public detail::fixed_width_scalar<T> {
rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
};

/**
* @brief An owning class to represent a timestamp value in device memory.
*
* @tparam T the data type of the timestamp value.
* @see cudf/wrappers/timestamps.hpp for a list of allowed types.
*/
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;
using rep_type = typename T::rep; ///< The underlying representation type of the timestamp.

timestamp_scalar() = delete;

timestamp_scalar() = delete;
/**
* @brief Move constructor for timestamp_scalar.
* @param other The other timestamp_scalar to move from.
*/
timestamp_scalar(timestamp_scalar&& other) = default;

/**
Expand Down Expand Up @@ -597,19 +659,31 @@ class timestamp_scalar : public chrono_scalar<T> {
rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());

/**
* @brief Return the duration in number of ticks since the UNIX epoch.
* @brief Returns the duration in number of ticks since the UNIX epoch.
* @return The duration in number of ticks since the UNIX epoch
*/
rep_type ticks_since_epoch();
};

/**
* @brief An owning class to represent a duration value in device memory.
*
* @tparam T the data type of the duration value.
* @see cudf/wrappers/durations.hpp for a list of allowed types.
*/
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;
using rep_type = typename T::rep; ///< The duration's underlying representation type.

duration_scalar() = delete;

duration_scalar() = delete;
/**
* @brief Move constructor for duration_scalar.
* @param other The other duration_scalar to move from.
*/
duration_scalar(duration_scalar&& other) = default;

/**
Expand Down Expand Up @@ -637,7 +711,8 @@ class duration_scalar : public chrono_scalar<T> {
rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());

/**
* @brief Return the duration in number of ticks.
* @brief Returns the duration in number of ticks.
* @return The duration in number of ticks
*/
rep_type count();
};
Expand All @@ -647,8 +722,13 @@ class duration_scalar : public chrono_scalar<T> {
*/
class list_scalar : public scalar {
public:
list_scalar() = delete;
~list_scalar() override = default;
list_scalar() = delete;
~list_scalar() override = default;

/**
* @brief Move constructor for list_scalar.
* @param other The other list_scalar to move from.
*/
list_scalar(list_scalar&& other) = default;

list_scalar& operator=(list_scalar const& other) = delete;
Expand Down Expand Up @@ -695,6 +775,7 @@ class list_scalar : public scalar {

/**
* @brief Returns a non-owning, immutable view to underlying device data.
* @return A non-owning, immutable view to underlying device data
*/
[[nodiscard]] column_view view() const;

Expand All @@ -707,12 +788,24 @@ class list_scalar : public scalar {
*/
class struct_scalar : public scalar {
public:
struct_scalar() = delete;
~struct_scalar() override = default;
struct_scalar() = delete;
~struct_scalar() override = default;

/**
* @brief Move constructor for struct_scalar.
* @param other The other struct_scalar to move from.
*/
struct_scalar(struct_scalar&& other) = default;
struct_scalar& operator=(struct_scalar const& other) = delete;
struct_scalar& operator=(struct_scalar&& other) = delete;

/**
* @brief Construct a new struct scalar object by deep copying another.
*
* @param other The scalar to copy.
* @param stream CUDA stream used for device memory operations.
* @param mr Device memory resource to use for device memory allocation.
*/
struct_scalar(struct_scalar const& other,
rmm::cuda_stream_view stream = rmm::cuda_stream_default,
rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
Expand Down Expand Up @@ -765,6 +858,7 @@ class struct_scalar : public scalar {

/**
* @brief Returns a non-owning, immutable view to underlying device data.
* @return A non-owning, immutable view to underlying device data
*/
[[nodiscard]] table_view view() const;

Expand Down
Loading

0 comments on commit 7b393a7

Please sign in to comment.