[GitHub] [arrow] lidavidm commented on a change in pull request #12717: ARROW-15975: [C++] Document type traits and inline visitors

[GitBox <gi...@apache.org>]

lidavidm commented on a change in pull request #12717:
URL: https://github.com/apache/arrow/pull/12717#discussion_r835613351



##########
File path: docs/source/cpp/datatypes.rst
##########
@@ -66,3 +66,138 @@ To instantiate data types, it is recommended to call the provided
    type = arrow::timestamp(arrow::TimeUnit::MICRO);
    // A list type of single-precision floating-point values
    type = arrow::list(arrow::float32());
+
+
+
+Type Traits
+-----------
+
+Writing code that can handle concrete :class:`arrow::DataType` subclasses would 
+be verbose, if it weren't for type traits. They are empty structs with type 
+declarations that map the Arrow data types to the specialized array, scalar, 
+builder, and other associated types. For example, boolean type has traits:

Review comment:
       ```suggestion
   builder, and other associated types. For example, the Boolean type has traits:
   ```

##########
File path: docs/source/cpp/datatypes.rst
##########
@@ -66,3 +66,138 @@ To instantiate data types, it is recommended to call the provided
    type = arrow::timestamp(arrow::TimeUnit::MICRO);
    // A list type of single-precision floating-point values
    type = arrow::list(arrow::float32());
+
+
+
+Type Traits
+-----------
+
+Writing code that can handle concrete :class:`arrow::DataType` subclasses would 
+be verbose, if it weren't for type traits. They are empty structs with type 

Review comment:
       Note that type traits are a general C++ concept, it may be worth linking this concept to `<type_traits>`

##########
File path: docs/source/cpp/datatypes.rst
##########
@@ -66,3 +66,138 @@ To instantiate data types, it is recommended to call the provided
    type = arrow::timestamp(arrow::TimeUnit::MICRO);
    // A list type of single-precision floating-point values
    type = arrow::list(arrow::float32());
+
+
+
+Type Traits
+-----------
+
+Writing code that can handle concrete :class:`arrow::DataType` subclasses would 
+be verbose, if it weren't for type traits. They are empty structs with type 
+declarations that map the Arrow data types to the specialized array, scalar, 
+builder, and other associated types. For example, boolean type has traits:
+
+.. code-block:: cpp
+
+   template <>
+   struct TypeTraits<BooleanType> {
+     using ArrayType = BooleanArray;
+     using BuilderType = BooleanBuilder;
+     using ScalarType = BooleanScalar;
+     using CType = bool;
+
+     static constexpr int64_t bytes_required(int64_t elements) {
+       return bit_util::BytesForBits(elements);
+     }
+     constexpr static bool is_parameter_free = true;
+     static inline std::shared_ptr<DataType> type_singleton() { return boolean(); }
+   };
+
+See the :ref:`type-traits` for an explanation of each of these fields.
+
+Using type traits, one can write template functions that can handle a variety
+of Arrow types. For example, to write a function that creates an array of 
+fibonacci values:
+
+.. code-block:: cpp
+
+   template <typename DataType,
+             typename BuilderType = typename arrow::TypeTraits<DataType>::BuilderType,
+             typename ArrayType = typename arrow::TypeTraits<DataType>::ArrayType,
+             typename CType = typename arrow::TypeTraits<DataType>::CType>
+   arrow::Result<std::shared_ptr<ArrayType>> make_fibonacci(int32_t n) {

Review comment:
       nit, but maybe try to follow the Arrow naming conventions still here (MakeFibonacci, SumArray)?

##########
File path: docs/source/cpp/api/utilities.rst
##########
@@ -56,3 +56,133 @@ Compression
 
 .. doxygenclass:: arrow::util::Decompressor
    :members:
+
+Visitors
+========
+
+.. doxygenfunction:: arrow::VisitTypeInline
+   :project: arrow_cpp
+
+.. doxygenfunction:: arrow::VisitTypeIdInline
+   :project: arrow_cpp
+
+.. doxygenfunction:: arrow::VisitScalarInline
+   :project: arrow_cpp
+
+.. doxygenfunction:: arrow::VisitArrayInline
+   :project: arrow_cpp
+
+
+.. _type-traits:
+
+Type Traits
+===========
+
+These types provide relationships between Arrow types at compile time. :cpp:type:`TypeTraits`
+maps Arrow DataTypes to other types, and :cpp:type:`CTypeTraits ` maps C types to
+Arrow types.
+
+TypeTraits
+----------
+
+Each specialized type defines the following associated types:
+
+.. cpp:type:: TypeTraits::ArrayType
+
+  Corresponding :doc:`Arrow array type </cpp/api/array.rst>`
+
+.. cpp:type:: TypeTraits::BuilderType
+
+  Corresponding :doc:`array builder type </cpp/api/builders.rst>`
+
+.. cpp:type:: TypeTraits::ScalarType
+
+  Corresponding :doc:`Arrow scalar type </cpp/api/scalar.rst>`
+
+.. cpp:var:: TypeTraits::is_parameter_free
+
+  Whether the type has any type parameters, such as field types in nested types
+  or scale and precision in decimal types.
+
+
+In addition, the following are defined for many but not all of the types:
+
+.. cpp:type:: TypeTraits::CType
+
+  Corresponding C type. For example, ``int64_t`` for ``Int64Array``.
+
+.. cpp:type:: TypeTraits::TensorType
+
+  Corresponding :doc:`Arrow tensor type </cpp/api/tensor.rst>`
+
+.. cpp:function:: static inline constexpr int64_t bytes_required(int64_t elements)
+
+  Return the number of bytes required for given number of elements. Defined for 
+  types with a fixed size.
+
+.. cpp:function:: static inline std::shared_ptr<DataType> TypeTraits::type_singleton()
+
+  For types where is_parameter_free is true, returns a pointer to the type
+  singleton.

Review comment:
       something like "Returns an instance of the DataType"?

##########
File path: docs/source/cpp/datatypes.rst
##########
@@ -66,3 +66,138 @@ To instantiate data types, it is recommended to call the provided
    type = arrow::timestamp(arrow::TimeUnit::MICRO);
    // A list type of single-precision floating-point values
    type = arrow::list(arrow::float32());
+
+
+
+Type Traits
+-----------
+
+Writing code that can handle concrete :class:`arrow::DataType` subclasses would 
+be verbose, if it weren't for type traits. They are empty structs with type 
+declarations that map the Arrow data types to the specialized array, scalar, 
+builder, and other associated types. For example, boolean type has traits:
+
+.. code-block:: cpp
+
+   template <>
+   struct TypeTraits<BooleanType> {
+     using ArrayType = BooleanArray;
+     using BuilderType = BooleanBuilder;
+     using ScalarType = BooleanScalar;
+     using CType = bool;
+
+     static constexpr int64_t bytes_required(int64_t elements) {
+       return bit_util::BytesForBits(elements);
+     }
+     constexpr static bool is_parameter_free = true;
+     static inline std::shared_ptr<DataType> type_singleton() { return boolean(); }
+   };
+
+See the :ref:`type-traits` for an explanation of each of these fields.
+
+Using type traits, one can write template functions that can handle a variety
+of Arrow types. For example, to write a function that creates an array of 
+fibonacci values:

Review comment:
       ```suggestion
   Fibonacci values for any Arrow numeric type:
   ```




-- 
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