You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "js8544 (via GitHub)" <gi...@apache.org> on 2023/05/26 16:38:59 UTC
[GitHub] [arrow] js8544 opened a new pull request, #35794: GH-35618: [C++][Doc] Improve doc for Datum
js8544 opened a new pull request, #35794:
URL: https://github.com/apache/arrow/pull/35794
Improve doc for `Datum` to avoid confusion as documented in the coresponding issue.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210615490
##########
cpp/src/arrow/datum.h:
##########
@@ -146,6 +183,8 @@ struct ARROW_EXPORT Datum {
}
}
+ /// \brief Retrieve the stored array as ArrayData, use make_array() if Array is desired
Review Comment:
```suggestion
/// \brief Retrieve the stored array as ArrayData
///
/// Use make_array() if an Array is desired (which is more expensive).
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210619100
##########
cpp/src/arrow/datum.h:
##########
@@ -220,11 +284,13 @@ struct ARROW_EXPORT Datum {
/// \return empty if not arraylike
ArrayVector chunks() const;
+ /// \brief True if the two data are equal
bool Equals(const Datum& other) const;
bool operator==(const Datum& other) const { return Equals(other); }
bool operator!=(const Datum& other) const { return !Equals(other); }
+ /// \brief Print the kind of datum stored
Review Comment:
```suggestion
/// \brief Return a string representation of the kind of datum stored.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] js8544 commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "js8544 (via GitHub)" <gi...@apache.org>.
js8544 commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1211038581
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const RecordBatch& value);
+
+ /// \brief Construct from a Table. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const Table& value);
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
Review Comment:
done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1564650569
* Closes: #35618
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210617389
##########
cpp/src/arrow/datum.h:
##########
@@ -155,49 +194,74 @@ struct ARROW_EXPORT Datum {
/// \see arrow::util::TotalBufferSize for caveats
int64_t TotalBufferSize() const;
+ /// \brief Get the stored ArrayData in mutable form, primarily used in kernel
+ /// implementations
Review Comment:
```suggestion
/// \brief Get the stored ArrayData in mutable form
///
/// For internal use primarily. Keep in mind a shared_ptr<Datum> may have multiple owners.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613957
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const RecordBatch& value);
+
+ /// \brief Construct from a Table. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const Table& value);
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(std::shared_ptr<T> value) // NOLINT implicit conversion
: Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
std::move(value))) {}
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, typename TV = typename std::remove_reference_t<T>,
bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(T&& value) // NOLINT implicit conversion
: Datum(std::make_shared<TV>(std::forward<T>(value))) {}
- // Many Scalars are copyable, let that happen
+ /// \brief Copy from concrete types of Scalar. The scalar type must copyable.
template <typename T, typename = enable_if_t<std::is_base_of_v<Scalar, T>>>
Datum(const T& value) // NOLINT implicit conversion
: Datum(std::make_shared<T>(value)) {}
// Convenience constructors
+ /// \brief A convenience constructor. Stores a bool scalar.
Review Comment:
```suggestion
/// \brief Convenience constructor storing a bool scalar.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612767
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
Review Comment:
(same kind of suggestion here and below)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210614873
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const RecordBatch& value);
+
+ /// \brief Construct from a Table. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const Table& value);
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(std::shared_ptr<T> value) // NOLINT implicit conversion
: Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
std::move(value))) {}
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, typename TV = typename std::remove_reference_t<T>,
bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(T&& value) // NOLINT implicit conversion
: Datum(std::make_shared<TV>(std::forward<T>(value))) {}
- // Many Scalars are copyable, let that happen
+ /// \brief Copy from concrete types of Scalar. The scalar type must copyable.
template <typename T, typename = enable_if_t<std::is_base_of_v<Scalar, T>>>
Datum(const T& value) // NOLINT implicit conversion
: Datum(std::make_shared<T>(value)) {}
// Convenience constructors
+ /// \brief A convenience constructor. Stores a bool scalar.
explicit Datum(bool value);
+ /// \brief A convenience constructor. Stores a int8 scalar.
explicit Datum(int8_t value);
+ /// \brief A convenience constructor. Stores a uint8 scalar.
explicit Datum(uint8_t value);
+ /// \brief A convenience constructor. Stores a int16 scalar.
explicit Datum(int16_t value);
+ /// \brief A convenience constructor. Stores a uint16 scalar.
explicit Datum(uint16_t value);
+ /// \brief A convenience constructor. Stores a int32 scalar.
explicit Datum(int32_t value);
+ /// \brief A convenience constructor. Stores a uint32 scalar.
explicit Datum(uint32_t value);
+ /// \brief A convenience constructor. Stores a int64 scalar.
explicit Datum(int64_t value);
+ /// \brief A convenience constructor. Stores a uint64 scalar.
explicit Datum(uint64_t value);
+ /// \brief A convenience constructor. Stores a float scalar.
explicit Datum(float value);
+ /// \brief A convenience constructor. Stores a double scalar.
explicit Datum(double value);
+ /// \brief A convenience constructor. Stores a string scalar.
explicit Datum(std::string value);
+ /// \brief A convenience constructor. Stores a string scalar.
explicit Datum(const char* value);
- // Forward to convenience constructors for a DurationScalar from std::chrono::duration
+ /// \brief Forward to convenience constructors for a DurationScalar from
+ /// std::chrono::duration
Review Comment:
The fact that it forwards is more of an implementation detail:
```suggestion
/// \brief Convenience constructor for a DurationScalar from std::chrono::duration
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] ursabot commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "ursabot (via GitHub)" <gi...@apache.org>.
ursabot commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1572181016
Benchmark runs are scheduled for baseline = d9c2d5961766d16fa0cae3b0ba9b2335ffd6bdb6 and contender = cbc17a98dfd9fb660523f61ecd361b157d278372. cbc17a98dfd9fb660523f61ecd361b157d278372 is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished :arrow_down:0.0% :arrow_up:0.0%] [ec2-t3-xlarge-us-east-2](https://conbench.ursa.dev/compare/runs/c97af4cac1cb4e3798dfd647e0220e3b...b68f8941916b4d23b32c378db96d226f/)
[Finished :arrow_down:2.33% :arrow_up:0.18%] [test-mac-arm](https://conbench.ursa.dev/compare/runs/1a6be6058ee24142ab813beb36fb8d8a...d6251aea6aa443958773d9df82c8306f/)
[Finished :arrow_down:0.33% :arrow_up:0.0%] [ursa-i9-9960x](https://conbench.ursa.dev/compare/runs/e8ffb3d5748442d796e3f2b607cb5456...b0515c2eead642d591753d5fd90cb299/)
[Finished :arrow_down:0.48% :arrow_up:0.27%] [ursa-thinkcentre-m75q](https://conbench.ursa.dev/compare/runs/09b9966884654197acb47570e2ea84e6...91458747cc1648309bf465c6b9a2af13/)
Buildkite builds:
[Finished] [`cbc17a98` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2960)
[Finished] [`cbc17a98` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2996)
[Finished] [`cbc17a98` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2961)
[Finished] [`cbc17a98` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2986)
[Finished] [`d9c2d596` ec2-t3-xlarge-us-east-2](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ec2-t3-xlarge-us-east-2/builds/2959)
[Finished] [`d9c2d596` test-mac-arm](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-test-mac-arm/builds/2995)
[Finished] [`d9c2d596` ursa-i9-9960x](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-i9-9960x/builds/2960)
[Finished] [`d9c2d596` ursa-thinkcentre-m75q](https://buildkite.com/apache-arrow/arrow-bci-benchmark-on-ursa-thinkcentre-m75q/builds/2985)
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python, R. Runs only benchmarks with cloud = True
test-mac-arm: Supported benchmark langs: C++, Python, R
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613034
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const RecordBatch& value);
+
+ /// \brief Construct from a Table. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const Table& value);
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
Review Comment:
"subtypes" rather than "types"?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612587
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
Review Comment:
```suggestion
/// \brief Construct from a ChunkedArray.
///
/// This can be expensive, prefer the shared_ptr<ChunkedArray> constructor
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1568834471
Thanks for doing this @js8544 ! I posted some small suggestions for style and accuracy.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] github-actions[bot] commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1564650603
:warning: GitHub issue #35618 **has been automatically assigned in GitHub** to PR creator.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] js8544 commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "js8544 (via GitHub)" <gi...@apache.org>.
js8544 commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1569433296
> Thanks for doing this @js8544 ! I posted some small suggestions for style and accuracy.
Thanks for the feedback! I've updated the doc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou merged pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou merged PR #35794:
URL: https://github.com/apache/arrow/pull/35794
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210618414
##########
cpp/src/arrow/datum.h:
##########
@@ -155,49 +194,74 @@ struct ARROW_EXPORT Datum {
/// \see arrow::util::TotalBufferSize for caveats
int64_t TotalBufferSize() const;
+ /// \brief Get the stored ArrayData in mutable form, primarily used in kernel
+ /// implementations
ArrayData* mutable_array() const { return this->array().get(); }
+ /// \brief Retrieve the stored array as Array
+ /// \throws std::bad_variant_access if the datum is not an array
std::shared_ptr<Array> make_array() const;
+ /// \brief Retrieve the chunked array stored
+ /// \throws std::bad_variant_access if the datum is not a chunked array
const std::shared_ptr<ChunkedArray>& chunked_array() const {
return std::get<std::shared_ptr<ChunkedArray>>(this->value);
}
+ /// \brief Retrieve the record batch stored
+ /// \throws std::bad_variant_access if the datum is not a record batch
const std::shared_ptr<RecordBatch>& record_batch() const {
return std::get<std::shared_ptr<RecordBatch>>(this->value);
}
+ /// \brief Retrieve the table stored
+ /// \throws std::bad_variant_access if the datum is not a table
const std::shared_ptr<Table>& table() const {
return std::get<std::shared_ptr<Table>>(this->value);
}
+ /// \brief Retrieve the scalar stored
+ /// \throws std::bad_variant_access if the datum is not a scalar
const std::shared_ptr<Scalar>& scalar() const {
return std::get<std::shared_ptr<Scalar>>(this->value);
}
+ /// \brief Retrieve the datum as its concrete array type
+ /// \throws std::bad_variant_access if the datum is not an array
+ /// \tparam ExactType the expected array type, may cause undefined behavior if it is not
+ /// the type of the stored array
template <typename ExactType>
std::shared_ptr<ExactType> array_as() const {
return internal::checked_pointer_cast<ExactType>(this->make_array());
}
+ /// \brief Retrieve the datum as its concrete scalar type
+ /// \throws std::bad_variant_access if the datum is not a scalar
+ /// \tparam ExactType the expected scalar type, may cause undefined behavior if it is
+ /// not the type of the stored scalar
template <typename ExactType>
const ExactType& scalar_as() const {
return internal::checked_cast<const ExactType&>(*this->scalar());
}
+ /// \brief True if Datum contains an array
bool is_array() const { return this->kind() == Datum::ARRAY; }
+ /// \brief True if Datum contains a chunked array
bool is_chunked_array() const { return this->kind() == Datum::CHUNKED_ARRAY; }
+ /// \brief True if Datum contains an array or a chunked array
bool is_arraylike() const {
return this->kind() == Datum::ARRAY || this->kind() == Datum::CHUNKED_ARRAY;
}
+ /// \brief True if Datum contains a scalar
bool is_scalar() const { return this->kind() == Datum::SCALAR; }
/// \brief True if Datum contains a scalar or array-like data
bool is_value() const { return this->is_arraylike() || this->is_scalar(); }
+ /// \brief Returns the null count. Only valid for scalar and array-like data
Review Comment:
```suggestion
/// \brief Return the null count.
///
/// Only valid for scalar and array-like data.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210613622
##########
cpp/src/arrow/datum.h:
##########
@@ -64,69 +68,102 @@ struct ARROW_EXPORT Datum {
Datum(Datum&& other) = default;
Datum& operator=(Datum&& other) = default;
+ /// \brief Construct from a Scalar
Datum(std::shared_ptr<Scalar> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(std::shared_ptr<ArrayData> value) // NOLINT implicit conversion
: value(std::move(value)) {}
+ /// \brief Construct from an ArrayData
Datum(ArrayData arg) // NOLINT implicit conversion
: value(std::make_shared<ArrayData>(std::move(arg))) {}
- Datum(const Array& value); // NOLINT implicit conversion
+ /// \brief Construct from an Array
+ Datum(const Array& value); // NOLINT implicit conversion
+
+ /// \brief Construct from an Array
Datum(const std::shared_ptr<Array>& value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray
Datum(std::shared_ptr<ChunkedArray> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
- Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
- // Explicit constructors from const-refs. Can be expensive, prefer the
- // shared_ptr constructors
+ /// \brief Construct from a RecordBatch
+ Datum(std::shared_ptr<RecordBatch> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a Table
+ Datum(std::shared_ptr<Table> value); // NOLINT implicit conversion
+
+ /// \brief Construct from a ChunkedArray. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const ChunkedArray& value);
+
+ /// \brief Construct from a RecordBatch. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const RecordBatch& value);
+
+ /// \brief Construct from a Table. Can be expensive, prefer the
+ /// shared_ptr constructor
explicit Datum(const Table& value);
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(std::shared_ptr<T> value) // NOLINT implicit conversion
: Datum(std::shared_ptr<typename std::conditional<IsArray, Array, Scalar>::type>(
std::move(value))) {}
- // Cast from subtypes of Array or Scalar to Datum
+ /// \brief Cast from concrete types of Array or Scalar to Datum
template <typename T, typename TV = typename std::remove_reference_t<T>,
bool IsArray = std::is_base_of_v<Array, T>,
bool IsScalar = std::is_base_of_v<Scalar, T>,
typename = enable_if_t<IsArray || IsScalar>>
Datum(T&& value) // NOLINT implicit conversion
: Datum(std::make_shared<TV>(std::forward<T>(value))) {}
- // Many Scalars are copyable, let that happen
+ /// \brief Copy from concrete types of Scalar. The scalar type must copyable.
Review Comment:
```suggestion
/// \brief Copy from concrete types of Scalar.
///
/// The concrete scalar type must be copyable (not all of them are).
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on a diff in pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #35794:
URL: https://github.com/apache/arrow/pull/35794#discussion_r1210612036
##########
cpp/src/arrow/datum.h:
##########
@@ -43,14 +43,18 @@ class Table;
/// \class Datum
/// \brief Variant type for various Arrow C++ data structures
struct ARROW_EXPORT Datum {
+ /// \brief The kind of datum stored
enum Kind { NONE, SCALAR, ARRAY, CHUNKED_ARRAY, RECORD_BATCH, TABLE };
+ /// \brief A placeholder type to represent empty datum
struct Empty {};
- // Datums variants may have a length. This special value indicate that the
- // current variant does not have a length.
+ /// \brief Datums variants may have a length. This special value indicate that the
+ /// current variant does not have a length.
static constexpr int64_t kUnknownLength = -1;
+ /// \brief Storage of the actual datum. Note: For arrays, it stores ArrayData instead of
+ /// Array for easier data processing
Review Comment:
Let's keep the brief summary brief and move the rest to the longer description section?
```suggestion
/// \brief Storage of the actual datum.
///
/// Note: For arrays, ArrayData is stored instead of Array for easier processing
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [arrow] pitrou commented on pull request #35794: GH-35618: [C++][Doc] Improve doc for Datum
Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on PR #35794:
URL: https://github.com/apache/arrow/pull/35794#issuecomment-1570878842
CI failures are unrelated, will merge.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org