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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
