ARROW-15952: [C++] Document Visitors and finish Scalar::Accept

wjones127 · pitrou · commit 91f65857c41d · 2022-03-17T10:45:32.000+01:00
Closes apache#12651 from wjones127/ARROW-15952-document-visitor Authored-by: Will Jones <willjones127@gmail.com> Signed-off-by: Antoine Pitrou <antoine@python.org>
diff --git a/cpp/src/arrow/array/array_base.h b/cpp/src/arrow/array/array_base.h
@@ -133,6 +133,7 @@ class ARROW_EXPORT Array {
                    int64_t end_idx, int64_t other_start_idx,
                    const EqualOptions& = EqualOptions::Defaults()) const;
 
+  /// \brief Apply the ArrayVisitor::Visit() method specialized to the array type
   Status Accept(ArrayVisitor* visitor) const;
 
   /// Construct a zero-copy view of this array with the given type.
diff --git a/cpp/src/arrow/scalar.cc b/cpp/src/arrow/scalar.cc
@@ -52,6 +52,10 @@ bool Scalar::ApproxEquals(const Scalar& other, const EqualOptions& options) cons
   return ScalarApproxEquals(*this, other, options);
 }
 
+Status Scalar::Accept(ScalarVisitor* visitor) const {
+  return VisitScalarInline(*this, visitor);
+}
+
 namespace {
 
 // Implementation of Scalar::hash()
diff --git a/cpp/src/arrow/scalar.h b/cpp/src/arrow/scalar.h
@@ -103,6 +103,9 @@ struct ARROW_EXPORT Scalar : public util::EqualityComparable<Scalar> {
 
   ARROW_EXPORT friend void PrintTo(const Scalar& scalar, std::ostream* os);
 
+  /// \brief Apply the ScalarVisitor::Visit() method specialized to the scalar type
+  Status Accept(ScalarVisitor* visitor) const;
+
  protected:
   Scalar(std::shared_ptr<DataType> type, bool is_valid)
       : type(std::move(type)), is_valid(is_valid) {}
diff --git a/cpp/src/arrow/type.h b/cpp/src/arrow/type.h
@@ -149,6 +149,7 @@ class ARROW_EXPORT DataType : public detail::Fingerprintable {
   /// \brief Return the number of children fields associated with this type.
   int num_fields() const { return static_cast<int>(children_.size()); }
 
+  /// \brief Apply the TypeVisitor::Visit() method specialized to the data type
   Status Accept(TypeVisitor* visitor) const;
 
   /// \brief A string representation of the type, including any children
diff --git a/cpp/src/arrow/visitor.cc b/cpp/src/arrow/visitor.cc
@@ -166,6 +166,9 @@ SCALAR_VISITOR_DEFAULT(MapScalar)
 SCALAR_VISITOR_DEFAULT(FixedSizeListScalar)
 SCALAR_VISITOR_DEFAULT(StructScalar)
 SCALAR_VISITOR_DEFAULT(DictionaryScalar)
+SCALAR_VISITOR_DEFAULT(SparseUnionScalar)
+SCALAR_VISITOR_DEFAULT(DenseUnionScalar)
+SCALAR_VISITOR_DEFAULT(ExtensionScalar)
 
 #undef SCALAR_VISITOR_DEFAULT
 
diff --git a/cpp/src/arrow/visitor.h b/cpp/src/arrow/visitor.h
@@ -23,6 +23,10 @@
 
 namespace arrow {
 
+/// \brief Abstract array visitor class
+///
+/// Subclass this to create a visitor that can be used with the Array::Accept()
+/// method.
 class ARROW_EXPORT ArrayVisitor {
  public:
   virtual ~ArrayVisitor() = default;
@@ -67,6 +71,10 @@ class ARROW_EXPORT ArrayVisitor {
   virtual Status Visit(const ExtensionArray& array);
 };
 
+/// \brief Abstract type visitor class
+///
+/// Subclass this to create a visitor that can be used with the DataType::Accept()
+/// method.
 class ARROW_EXPORT TypeVisitor {
  public:
   virtual ~TypeVisitor() = default;
@@ -111,6 +119,10 @@ class ARROW_EXPORT TypeVisitor {
   virtual Status Visit(const ExtensionType& type);
 };
 
+/// \brief Abstract scalar visitor class
+///
+/// Subclass this to create a visitor that can be used with the Scalar::Accept()
+/// method.
 class ARROW_EXPORT ScalarVisitor {
  public:
   virtual ~ScalarVisitor() = default;
@@ -150,6 +162,9 @@ class ARROW_EXPORT ScalarVisitor {
   virtual Status Visit(const FixedSizeListScalar& scalar);
   virtual Status Visit(const StructScalar& scalar);
   virtual Status Visit(const DictionaryScalar& scalar);
+  virtual Status Visit(const SparseUnionScalar& scalar);
+  virtual Status Visit(const DenseUnionScalar& scalar);
+  virtual Status Visit(const ExtensionScalar& scalar);
 };
 
 }  // namespace arrow
diff --git a/docs/source/cpp/api/array.rst b/docs/source/cpp/api/array.rst
@@ -78,3 +78,12 @@ Chunked Arrays
 .. doxygenclass:: arrow::ChunkedArray
    :project: arrow_cpp
    :members:
+
+
+Utilities
+=========
+
+.. doxygenclass:: arrow::ArrayVisitor
+   :project: arrow_cpp
+   :members:
+   :undoc-members:
diff --git a/docs/source/cpp/api/datatype.rst b/docs/source/cpp/api/datatype.rst
@@ -109,3 +109,12 @@ Helpers for looking up fields
 
 .. doxygenclass:: arrow::FieldRef
    :members:
+
+
+Utilities
+=========
+
+.. doxygenclass:: arrow::TypeVisitor
+   :project: arrow_cpp
+   :members:
+   :undoc-members:
diff --git a/docs/source/cpp/api/scalar.rst b/docs/source/cpp/api/scalar.rst
@@ -36,3 +36,12 @@ Concrete scalar subclasses
    :content-only:
    :members:
    :undoc-members:
+
+
+Utilities
+=========
+
+.. doxygenclass:: arrow::ScalarVisitor
+   :project: arrow_cpp
+   :members:
+   :undoc-members:
diff --git a/docs/source/cpp/conventions.rst b/docs/source/cpp/conventions.rst
@@ -105,3 +105,18 @@ For example::
 
 .. seealso::
    :doc:`API reference for error reporting <api/support>`
+
+Visitor Pattern
+---------------
+
+Several types, including :class:`arrow::DataType`, :class:`arrow::Scalar`, and
+:class:`arrow::Array`, have sub-types specialized to their corresponding Arrow
+types. For example, for the Arrow boolean type there is :class:`arrow::BooleanType`,
+:class:`arrow::BooleanScalar`, and :class:`arrow::BooleanArray`. In order to 
+process these entities, you may need to write write logic that specializes based 
+on the particular Arrow type. In these cases, use the
+`visitor pattern <https://en.wikipedia.org/wiki/Visitor_pattern>`_.
+
+Arrow provides abstract visitor classes (:class:`arrow::TypeVisitor`,
+:class:`arrow::ScalarVisitor`, :class:`arrow::ArrayVisitor`) and an ``Accept()``
+method on each of the corresponding base types (e.g. :func:`arrow::Array::Accept`).

Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,10 @@ bool Scalar::ApproxEquals(const Scalar& other, const EqualOptions& options) cons`
`52`	`52`	`return ScalarApproxEquals(*this, other, options);`
`53`	`53`	`}`
`54`	`54`
	`55`	`+Status Scalar::Accept(ScalarVisitor* visitor) const {`
	`56`	`+ return VisitScalarInline(*this, visitor);`
	`57`	`+}`
	`58`	`+`
`55`	`59`	`namespace {`
`56`	`60`
`57`	`61`	`// Implementation of Scalar::hash()`