builder options and layout builder updates (#1560)

* restore array builder options

* GrowableBuffer and its test updated

* builder options added

* introduce builder options to layout builder

* drop C++17 requirement for cpp-only tests to C++14; work-around missing std::tuple_element_t on all MacOS CI nodes

* fix compilation error and cleanup

* clang format

* remove default parameters from build options

* remove initializer list

* fix bitmasked mask and add builder options test

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* address Jim's comments

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

CMakeLists.txt

@@ -100,6 +100,7 @@ if(BUILD_TESTING)
   addtest_nolibs(test_1494-layout-builder tests-cpp/test_1494-layout-builder.cpp)
   addtest_nolibs(test_1542-growable-buffer tests-cpp/test_1542-growable-buffer.cpp)
   addtest(test_1542-array-builder tests-cpp/test_1542-array-builder.cpp)
+  addtest_nolibs(test_1560-builder-options tests-cpp/test_1560-builder-options.cpp)
 
 endif()
 

include/awkward/builder/ArrayBuilder.h

@@ -9,6 +9,7 @@
 
 #include "awkward/common.h"
 #include "awkward/builder/Builder.h"
+#include "awkward/BuilderOptions.h"
 
 namespace awkward {
   class Builder;
@@ -23,9 +24,9 @@ namespace awkward {
   public:
     /// @brief Creates an ArrayBuilder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
-    ArrayBuilder(const int64_t initial);
+    ArrayBuilder(const BuilderOptions& options);
 
     /// @brief Copy the current snapshot into the BuffersContainer and
     /// return a Form as a std::string (JSON).

include/awkward/builder/BoolBuilder.h

@@ -7,6 +7,7 @@
 #include <string>
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -18,17 +19,17 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL BoolBuilder: public Builder {
   public:
     /// @brief Create an empty BoolBuilder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial);
+      fromempty(const BuilderOptions& options);
 
     /// @brief Create a BoolBuilder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param buffer Contains the accumulated boolean values.
-    BoolBuilder(const int64_t initial,
+    BoolBuilder(const BuilderOptions& options,
                 GrowableBuffer<uint8_t> buffer);
 
     /// @brief User-friendly name of this class: `"BoolBuilder"`.
@@ -98,13 +99,13 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
     const GrowableBuffer<uint8_t>& buffer() const { return buffer_; }
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<uint8_t> buffer_;
   };
 

include/awkward/builder/Complex128Builder.h

@@ -4,6 +4,7 @@
 #define AWKWARD_COMPLEX128BUILDER_H_
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -16,33 +17,33 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL Complex128Builder: public Builder {
   public:
     /// @brief Create an empty Complex128Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial);
+      fromempty(const BuilderOptions& options);
 
     /// @brief Create a Complex128Builder from an existing Int64Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param old The Int64Builder's buffer.
     static const BuilderPtr
-      fromint64(const int64_t initial,
+      fromint64(const BuilderOptions& options,
                 const GrowableBuffer<int64_t>& old);
 
     /// @brief Create a Complex128Builder from an existing Float64Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param old The Float64Builder's buffer.
     static const BuilderPtr
-      fromfloat64(const int64_t initial,
+      fromfloat64(const BuilderOptions& options,
                   const GrowableBuffer<double>& old);
 
     /// @brief Create a Complex128Builder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param buffer Contains the accumulated real numbers.
-    Complex128Builder(const int64_t initial,
+    Complex128Builder(const BuilderOptions& options,
                       GrowableBuffer<std::complex<double>> buffer);
 
     /// @brief User-friendly name of this class: `"Complex128Builder"`.
@@ -112,13 +113,13 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
     const GrowableBuffer<std::complex<double>>& buffer() const { return buffer_; }
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<std::complex<double>> buffer_;
   };
 

include/awkward/builder/DatetimeBuilder.h

@@ -4,6 +4,7 @@
 #define AWKWARD_DATETIMEBUILDER_H_
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -15,17 +16,17 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL DatetimeBuilder: public Builder {
   public:
     /// @brief Create an empty DatetimeBuilder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial, const std::string& units);
+      fromempty(const BuilderOptions& options, const std::string& units);
 
     /// @brief Create an DatetimeBuilder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param buffer Contains the accumulated integers.
-    DatetimeBuilder(const int64_t initial,
+    DatetimeBuilder(const BuilderOptions& options,
                     GrowableBuffer<int64_t> content,
                     const std::string& units);
 
@@ -96,8 +97,8 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
     const std::string&
       units() const;
@@ -107,7 +108,7 @@ namespace awkward {
     const std::string& unit() const { return units_; }
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<int64_t> content_;
     const std::string units_;
   };

include/awkward/builder/Float64Builder.h

@@ -6,6 +6,7 @@
 #include <string>
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -17,25 +18,25 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL Float64Builder: public Builder {
   public:
     /// @brief Create an empty Float64Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial);
+      fromempty(const BuilderOptions& options);
 
     /// @brief Create a Float64Builder from an existing Int64Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param old The Int64Builder's buffer.
     static const BuilderPtr
-      fromint64(const int64_t initial,
+      fromint64(const BuilderOptions& options,
                 const GrowableBuffer<int64_t>& old);
 
     /// @brief Create a Float64Builder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param buffer Contains the accumulated real numbers.
-    Float64Builder(const int64_t initial,
+    Float64Builder(const BuilderOptions& options,
                    GrowableBuffer<double> buffer);
 
     /// @brief Contains the accumulated real numbers (`double`).
@@ -109,11 +110,11 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<double> buffer_;
   };
 

include/awkward/builder/Int64Builder.h

@@ -4,6 +4,7 @@
 #define AWKWARD_INT64BUILDER_H_
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -15,17 +16,17 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL Int64Builder: public Builder {
   public:
     /// @brief Create an empty Int64Builder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial);
+      fromempty(const BuilderOptions& options);
 
     /// @brief Create an Int64Builder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param buffer Contains the accumulated integers.
-    Int64Builder(const int64_t initial,
+    Int64Builder(const BuilderOptions& options,
                  GrowableBuffer<int64_t> buffer);
 
     /// @brief Contains the accumulated integers.
@@ -99,11 +100,11 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<int64_t> buffer_;
   };
 }

include/awkward/builder/ListBuilder.h

@@ -6,6 +6,7 @@
 #include <vector>
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -17,22 +18,22 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL ListBuilder: public Builder {
   public:
     /// @brief Create an empty ListBuilder.
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     static const BuilderPtr
-      fromempty(const int64_t initial);
+      fromempty(const BuilderOptions& options);
 
     /// @brief Create a ListBuilder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param offsets Contains the accumulated offsets (like
     /// {@link ListOffsetArrayOf#offsets ListOffsetArray::offsets}).
     /// @param content Builder for the data in the nested lists.
     /// @param begun If `true`, the ListBuilder is in a state after
     /// #beginlist and before #endlist and is #active; if `false`,
     /// it is not.
-    ListBuilder(const int64_t initial,
+    ListBuilder(const BuilderOptions& options,
                 GrowableBuffer<int64_t> offsets,
                 const BuilderPtr& content,
                 bool begun);
@@ -105,8 +106,8 @@ namespace awkward {
     const BuilderPtr
       endrecord() override;
 
-    const int64_t
-      initial() const { return initial_; }
+    const BuilderOptions&
+      options() const { return options_; }
 
     const GrowableBuffer<int64_t>& buffer() const { return offsets_; }
 
@@ -118,7 +119,7 @@ namespace awkward {
       maybeupdate(const BuilderPtr builder);
 
   private:
-    const int64_t initial_;
+    const BuilderOptions options_;
     GrowableBuffer<int64_t> offsets_;
     BuilderPtr content_;
     bool begun_;

include/awkward/builder/OptionBuilder.h

@@ -6,6 +6,7 @@
 #include <vector>
 
 #include "awkward/common.h"
+#include "awkward/BuilderOptions.h"
 #include "awkward/GrowableBuffer.h"
 #include "awkward/builder/Builder.h"
 
@@ -17,32 +18,32 @@ namespace awkward {
   class LIBAWKWARD_EXPORT_SYMBOL OptionBuilder: public Builder {
   public:
     /// @brief Create an OptionBuilder from a number of nulls (all missing).
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param nullcount Length of the purely missing data to create.
     /// @param content Builder for the non-missing data.
     static const BuilderPtr
-      fromnulls(const int64_t initial,
+      fromnulls(const BuilderOptions& options,
                 int64_t nullcount,
                 const BuilderPtr& content);
 
     /// @brief Create an OptionBuilder from an existing builder (all
     /// non-missing).
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param content Builder for the non-missing data.
     static const BuilderPtr
-      fromvalids(const int64_t initial,
+      fromvalids(const BuilderOptions& options,
                  const BuilderPtr& content);
 
     /// @brief Create a OptionBuilder from a full set of parameters.
     ///
-    /// @param initial Configuration initial for building an array;
+    /// @param options Configuration options for building an array;
     /// these are passed to every Builder's constructor.
     /// @param index Contains the accumulated index (like
     /// {@link IndexedArrayOf#index IndexedOptionArray::index}).
     /// @param content Builder for the non-missing data.
-    OptionBuilder(const int64_t initial,
+    OptionBuilder(const BuilderOptions& options,
                   GrowableBuffer<int64_t> index,
                   const BuilderPtr content);