diff --git a/cpp/include/cudf/scalar/scalar.hpp b/cpp/include/cudf/scalar/scalar.hpp index 0db729aec28..24c356f1fd7 100644 --- a/cpp/include/cudf/scalar/scalar.hpp +++ b/cpp/include/cudf/scalar/scalar.hpp @@ -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. @@ -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; @@ -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; @@ -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; /** @@ -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 class fixed_width_scalar : public scalar { static_assert(is_fixed_width(), "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; @@ -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; @@ -219,8 +242,13 @@ class numeric_scalar : public detail::fixed_width_scalar { static_assert(is_numeric(), "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; @@ -274,11 +302,16 @@ class fixed_point_scalar : public scalar { static_assert(is_fixed_point(), "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; @@ -355,6 +388,7 @@ 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; @@ -362,6 +396,7 @@ class fixed_point_scalar : public scalar { * @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; @@ -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; @@ -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; @@ -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; @@ -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; @@ -514,8 +560,13 @@ class chrono_scalar : public detail::fixed_width_scalar { static_assert(is_chrono(), "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; @@ -559,14 +610,25 @@ class chrono_scalar : public detail::fixed_width_scalar { 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 class timestamp_scalar : public chrono_scalar { public: static_assert(is_timestamp(), "Unexpected non-timestamp type"); using chrono_scalar::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; /** @@ -597,19 +659,31 @@ class timestamp_scalar : public chrono_scalar { 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 class duration_scalar : public chrono_scalar { public: static_assert(is_duration(), "Unexpected non-duration type"); using chrono_scalar::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; /** @@ -637,7 +711,8 @@ class duration_scalar : public chrono_scalar { 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(); }; @@ -647,8 +722,13 @@ class duration_scalar : public chrono_scalar { */ 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; @@ -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; @@ -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()); @@ -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; diff --git a/cpp/include/cudf/scalar/scalar_device_view.cuh b/cpp/include/cudf/scalar/scalar_device_view.cuh index ae658da9f9b..b298b462a4f 100644 --- a/cpp/include/cudf/scalar/scalar_device_view.cuh +++ b/cpp/include/cudf/scalar/scalar_device_view.cuh @@ -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. @@ -36,6 +36,7 @@ class scalar_device_view_base { /** * @brief Returns the value type + * @returns The value type */ [[nodiscard]] __host__ __device__ data_type type() const noexcept { return _type; } @@ -59,6 +60,14 @@ class scalar_device_view_base { bool* _is_valid{}; ///< Pointer to device memory containing ///< boolean representing validity of the value. + /** + * @brief Construct a new scalar device view base object from a device pointer + * and a validity boolean. + * + * @param type The data type of the scalar + * @param is_valid Pointer to device memory containing boolean representing + * validity of the scalar. + */ scalar_device_view_base(data_type type, bool* is_valid) : _type(type), _is_valid(is_valid) {} scalar_device_view_base() = default; @@ -73,6 +82,7 @@ class fixed_width_scalar_device_view_base : public detail::scalar_device_view_ba * @brief Returns reference to stored value. * * @tparam T The desired type + * @returns Reference to stored value */ template __device__ T& value() noexcept @@ -84,6 +94,7 @@ class fixed_width_scalar_device_view_base : public detail::scalar_device_view_ba * @brief Returns const reference to stored value. * * @tparam T The desired type + * @returns Const reference to stored value */ template __device__ T const& value() const noexcept @@ -107,16 +118,19 @@ class fixed_width_scalar_device_view_base : public detail::scalar_device_view_ba * @brief Returns a raw pointer to the value in device memory * * @tparam T The desired type + * @returns Raw pointer to the value in device memory */ template __device__ T* data() noexcept { return static_cast(_data); } + /** * @brief Returns a const raw pointer to the value in device memory * * @tparam T The desired type + * @returns Const raw pointer to the value in device memory */ template __device__ T const* data() const noexcept @@ -150,15 +164,19 @@ class fixed_width_scalar_device_view_base : public detail::scalar_device_view_ba template class fixed_width_scalar_device_view : public detail::fixed_width_scalar_device_view_base { public: - using value_type = T; + using value_type = T; ///< The value type of the scalar /** * @brief Returns reference to stored value. + * + * @returns Reference to stored value */ __device__ T& value() noexcept { return fixed_width_scalar_device_view_base::value(); } /** * @brief Returns const reference to stored value. + * + * @returns Const reference to stored value */ __device__ T const& value() const noexcept { @@ -174,10 +192,15 @@ class fixed_width_scalar_device_view : public detail::fixed_width_scalar_device_ /** * @brief Returns a raw pointer to the value in device memory + * + * @returns Raw pointer to the value in device memory */ __device__ T* data() noexcept { return fixed_width_scalar_device_view_base::data(); } + /** * @brief Returns a const raw pointer to the value in device memory + * + * @returns Const raw pointer to the value in device memory */ __device__ T const* data() const noexcept { @@ -210,6 +233,14 @@ class fixed_width_scalar_device_view : public detail::fixed_width_scalar_device_ template class numeric_scalar_device_view : public detail::fixed_width_scalar_device_view { public: + /** + * @brief Construct a new numeric scalar device view object from data and validity pointers. + * + * @param type The data type of the value + * @param data The pointer to the data in device memory + * @param is_valid The pointer to the bool in device memory that indicates the + * validity of the stored value + */ numeric_scalar_device_view(data_type type, T* data, bool* is_valid) : detail::fixed_width_scalar_device_view(type, data, is_valid) { @@ -222,8 +253,16 @@ class numeric_scalar_device_view : public detail::fixed_width_scalar_device_view template class fixed_point_scalar_device_view : public detail::scalar_device_view_base { public: - using rep_type = typename T::rep; + using rep_type = typename T::rep; ///< The representation type of the fixed_point value + /** + * @brief Construct a new fixed point scalar device view object from data and validity pointers. + * + * @param type The data type of the value + * @param data The pointer to the data in device memory + * @param is_valid The pointer to the bool in device memory that indicates the + * validity of the stored value + */ fixed_point_scalar_device_view(data_type type, rep_type* data, bool* is_valid) : detail::scalar_device_view_base(type, is_valid), _data(data) { @@ -238,6 +277,8 @@ class fixed_point_scalar_device_view : public detail::scalar_device_view_base { /** * @brief Get the value of the scalar, as a `rep_type`. + * + * @returns The value of the scalar, as a `rep_type` */ __device__ rep_type const& rep() const noexcept { return *_data; } @@ -250,8 +291,18 @@ class fixed_point_scalar_device_view : public detail::scalar_device_view_base { */ class string_scalar_device_view : public detail::scalar_device_view_base { public: - using ValueType = cudf::string_view; + using ValueType = cudf::string_view; ///< The value type of the string scalar + /** + * @brief Construct a new string scalar device view object from string data, size and validity + * pointers. + * + * @param type The data type of the value + * @param data The pointer to the string data in device memory + * @param is_valid The pointer to the bool in device memory that indicates the + * validity of the stored value + * @param size The pointer to the size of the string in device memory + */ string_scalar_device_view(data_type type, const char* data, bool* is_valid, size_type size) : detail::scalar_device_view_base(type, is_valid), _data(data), _size(size) { @@ -259,6 +310,8 @@ class string_scalar_device_view : public detail::scalar_device_view_base { /** * @brief Returns string_view of the value of this scalar. + * + * @returns string_view of the value of this scalar */ [[nodiscard]] __device__ ValueType value() const noexcept { @@ -267,6 +320,8 @@ class string_scalar_device_view : public detail::scalar_device_view_base { /** * @brief Returns a raw pointer to the value in device memory + * + * @returns Raw pointer to the value in device memory */ [[nodiscard]] __device__ char const* data() const noexcept { @@ -275,6 +330,8 @@ class string_scalar_device_view : public detail::scalar_device_view_base { /** * @brief Returns the size of the string in bytes. + * + * @returns The size of the string in bytes */ [[nodiscard]] __device__ size_type size() const noexcept { return _size; } @@ -289,6 +346,14 @@ class string_scalar_device_view : public detail::scalar_device_view_base { template class timestamp_scalar_device_view : public detail::fixed_width_scalar_device_view { public: + /** + * @brief Construct a new timestamp scalar device view object + * + * @param type The data type of the value + * @param data The pointer to the data in device memory + * @param is_valid The pointer to the bool in device memory that indicates the + * validity of the stored value + */ timestamp_scalar_device_view(data_type type, T* data, bool* is_valid) : detail::fixed_width_scalar_device_view(type, data, is_valid) { @@ -301,6 +366,14 @@ class timestamp_scalar_device_view : public detail::fixed_width_scalar_device_vi template class duration_scalar_device_view : public detail::fixed_width_scalar_device_view { public: + /** + * @brief Construct a new duration scalar device view object from data and validity pointers. + * + * @param type The data type of the value + * @param data The pointer to the data in device memory + * @param is_valid The pointer to the bool in device memory that indicates the + * validity of the stored value + */ duration_scalar_device_view(data_type type, T* data, bool* is_valid) : detail::fixed_width_scalar_device_view(type, data, is_valid) { @@ -309,6 +382,9 @@ class duration_scalar_device_view : public detail::fixed_width_scalar_device_vie /** * @brief Get the device view of a numeric_scalar + * + * @param s The numeric_scalar to get the device view of + * @return A device view of a numeric_scalar */ template auto get_scalar_device_view(numeric_scalar& s) @@ -318,6 +394,9 @@ auto get_scalar_device_view(numeric_scalar& s) /** * @brief Get the device view of a string_scalar + * + * @param s The string_scalar to get the device view of + * @return A device view of a string_scalar */ inline auto get_scalar_device_view(string_scalar& s) { @@ -326,6 +405,9 @@ inline auto get_scalar_device_view(string_scalar& s) /** * @brief Get the device view of a timestamp_scalar + * + * @param s The timestamp_scalar to get the device view of + * @return A device view of a timestamp_scalar */ template auto get_scalar_device_view(timestamp_scalar& s) @@ -335,6 +417,9 @@ auto get_scalar_device_view(timestamp_scalar& s) /** * @brief Get the device view of a duration_scalar + * + * @param s The duration_scalar to get the device view of + * @return A device view of a duration_scalar */ template auto get_scalar_device_view(duration_scalar& s) @@ -344,6 +429,9 @@ auto get_scalar_device_view(duration_scalar& s) /** * @brief Get the device view of a fixed_point_scalar + * + * @param s The fixed_point_scalar to get the device view of + * @return The device view of the fixed_point_scalar */ template auto get_scalar_device_view(fixed_point_scalar& s) diff --git a/cpp/include/cudf/scalar/scalar_factories.hpp b/cpp/include/cudf/scalar/scalar_factories.hpp index aa63fa7ffd4..305732d6b0b 100644 --- a/cpp/include/cudf/scalar/scalar_factories.hpp +++ b/cpp/include/cudf/scalar/scalar_factories.hpp @@ -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. @@ -37,6 +37,7 @@ namespace cudf { * @param type The desired numeric element type * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns An uninitialized numeric scalar */ std::unique_ptr make_numeric_scalar( data_type type, @@ -53,6 +54,7 @@ std::unique_ptr make_numeric_scalar( * @param type The desired timestamp element type * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @return An uninitialized timestamp scalar */ std::unique_ptr make_timestamp_scalar( data_type type, @@ -69,6 +71,7 @@ std::unique_ptr make_timestamp_scalar( * @param type The desired duration element type * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @return An uninitialized duration scalar */ std::unique_ptr make_duration_scalar( data_type type, @@ -85,6 +88,7 @@ std::unique_ptr make_duration_scalar( * @param type The desired fixed-width element type * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @return An uninitialized fixed-width scalar */ std::unique_ptr make_fixed_width_scalar( data_type type, @@ -101,6 +105,7 @@ std::unique_ptr make_fixed_width_scalar( * @param string The `std::string` to copy to device * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A string scalar with the contents of `string` */ std::unique_ptr make_string_scalar( std::string const& string, @@ -115,6 +120,7 @@ std::unique_ptr make_string_scalar( * @param type The desired element type * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A scalar of type `type` */ std::unique_ptr make_default_constructed_scalar( data_type type, @@ -129,6 +135,7 @@ std::unique_ptr make_default_constructed_scalar( * @param input Immutable view of input column to emulate * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A scalar of type of `input` column */ std::unique_ptr make_empty_scalar_like( column_view const& input, @@ -142,6 +149,7 @@ std::unique_ptr make_empty_scalar_like( * @param value The value to store in the scalar object * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A scalar of type `T` */ template std::unique_ptr make_fixed_width_scalar( @@ -160,6 +168,7 @@ std::unique_ptr make_fixed_width_scalar( * @param scale The scale of the fixed point value * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A scalar of type `T` */ template std::unique_ptr make_fixed_point_scalar( @@ -177,6 +186,7 @@ std::unique_ptr make_fixed_point_scalar( * @param elements Elements of the list * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A list scalar */ std::unique_ptr make_list_scalar( column_view elements, @@ -191,6 +201,7 @@ std::unique_ptr make_list_scalar( * @param data The columnar data to store in the scalar object * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A struct scalar */ std::unique_ptr make_struct_scalar( table_view const& data, @@ -205,6 +216,7 @@ std::unique_ptr make_struct_scalar( * @param data The columnar data to store in the scalar object * @param stream CUDA stream used for device memory operations. * @param mr Device memory resource used to allocate the scalar's `data` and `is_valid` bool. + * @returns A struct scalar */ std::unique_ptr make_struct_scalar( host_span data,