feat: IArray interface

Author: sritchie

src/gen/array.cljc

@@ -0,0 +1,29 @@
+(ns gen.array
+  "Protocol and API methods for converting types to and from an array of values.
+
+  These functions are useful for converting nested, hierarchical data structures
+  into ordered vectors without structure and recovering them back."
+  (:refer-clojure :exclude [to-array]))
+
+(defprotocol IArray
+  (to-array [x] "Returns a flat vector representation of `x`.")
+  (-from-array [x a start-idx]
+    "Given some `x`, an input vector `a` and a starting index `start-idx`,
+    returns a pair of
+
+  - the number of elements read off of the vector
+  - an instance of the same type and shape as `x`, with its leaves populated by
+    values from `a` beginning at `start-idx`."))
+
+(defn from-array
+  "Given some structured input `m` and an input vector `xs`, returns an instance
+  of the same type and shape as `m`, with its leaves populated by values from
+  `xs`.
+
+  Throws an exception if the count of `xs` doesn't match the number of leaves in
+  `m`."
+  [m xs]
+  (let [[n ret] (-from-array m xs 0)]
+    (if (= n (count xs))
+      ret
+      (throw (ex-info "Dimension mismatch: " {:xs xs :n n})))))

test/gen/array_test.cljc

@@ -0,0 +1,32 @@
+(ns gen.array-test
+  "Tests for the [[gen.array]] namespace and the various base implementations
+  that live there."
+  (:require [clojure.test :refer [deftest is]]
+            [clojure.test.check.generators :as gen]
+            [com.gfredericks.test.chuck.clojure-test :refer [checking]]
+            [gen.array :as arr]))
+
+(defn array-round-trip [m]
+  (is (= m
+         (->> (arr/to-array m)
+              (arr/from-array m)))
+      "entry round-trips through array."))
+
+;; Wrapper for a non-collection, single element for testing.
+(defrecord Element [v]
+  arr/IArray
+  (to-array [_] [v])
+  (-from-array [_ xs idx]
+    [1 (Element. (nth xs idx))]))
+
+(deftest from-array-test
+  (checking "Element round-trips through array" 100
+            [elem (gen/fmap ->Element gen/any-equatable)]
+            (array-round-trip elem))
+
+  (checking "failure on incorrect array source" 100
+            [elem (gen/fmap ->Element gen/any-equatable)]
+            (is (thrown?
+                 #?(:clj clojure.lang.ExceptionInfo :cljs js/Error)
+                 (arr/from-array elem [1 2 3]))
+                "input array is too big!")))