_unfold-vector-grouped_: New template.

* test/core/suite.xml: Import new fold test package.
* test/core/vector/fold.xml: New test package.
* vector/fold.xml: New package.  Adds `_unfold-vector-grouped_'.

core/test/core/suite.xml

@@ -26,9 +26,11 @@
   <import package="../../base" />
   <import package="../spec" />
 
-  <import package="numeric/round" />
   <import package="numeric/convert" />
   <import package="numeric/percent" />
+  <import package="numeric/round" />
+
+  <import package="vector/fold" />
   <import package="vector/interpolate" />
   <import package="vector/length" />
   <import package="vector/stub" />

core/test/core/vector/fold.xml

@@ -0,0 +1,115 @@
+<?xml version="1.0"?>
+<!--
+  Copyright (C) 2018 R-T Specialty, LLC.
+
+  This file is part of tame-core.
+
+  tame-core is free software: you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as
+  published by the Free Software Foundation, either version 3 of the
+  License, or (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+-->
+<package xmlns="http://www.lovullo.com/rater"
+  xmlns:c="http://www.lovullo.com/calc"
+  xmlns:t="http://www.lovullo.com/rater/apply-template"
+  desc="Vector Folding and Unfolding Specs">
+
+  <import package="../../spec" />
+
+  <import package="../../../base" />
+  <import package="../../../vector/fold" />
+  <import package="../../../vector/stub" />
+
+
+  <const name="UNFOLD_VEC_MID_EMPTY" type="integer"
+         desc="3-vector with middle unset">
+    <item value="1" desc="Set" />
+    <item value="0" desc="Unset" />
+    <item value="1" desc="Set" />
+  </const>
+
+  <t:vector-to-class name="UNFOLD_VEC_MID_EMPTY" as="unfold-mid-empty" />
+
+  <const name="UNFOLD_VEC_3GROUP" type="integer"
+         desc="3-grouping for test case"
+         values="1,0,2,2,1,2" />
+
+  <!-- given the sequence [0 1 2 3 4 5] -->
+  <const name="UNFOLD_VEC_3GROUP_EXPECTED" type="integer"
+         desc="Expected result"
+         values="1; 0,4; 2,3,5" />
+
+
+  <const name="UNFOLD_3VEC_ONE_EACH" type="integer"
+         desc="3-vector with one in each group">
+  </const>
+
+
+  <t:describe name="_unfold-vector-grouped_">
+    <t:it desc="yields a vector whose length is that of the class">
+      <t:unfold-vector-grouped class="nclass3"
+                               generates="unfoldVecGroupedLenClass"
+                               src="NVEC1"
+                               grouping="NVEC1" />
+
+      <t:given>
+        <c:length-of>
+          <c:value-of name="unfoldVecGroupedLenClass" />
+        </c:length-of>
+      </t:given>
+
+      <t:expect>
+        <t:match-result eq="3" />
+      </t:expect>
+    </t:it>
+
+
+    <t:it desc="uses grouping vector for grouping">
+      <t:unfold-vector-grouped class="nclass3"
+                               generates="unfoldVecGrouped"
+                               src="NVEC6_SEQ"
+                               grouping="UNFOLD_VEC_3GROUP" />
+
+      <!-- TODO: matrix classification matches -->
+    </t:it>
+
+
+    <t:it desc="does not include non-matching groups">
+      <t:unfold-vector-grouped class="unfold-mid-empty"
+                               generates="unfoldVecGroupedNonClassMatch"
+                               src="NVEC3_SEQ"
+                               grouping="NVEC3_SEQ" />
+
+      <t:given>
+        <c:sum>
+          <c:length-of>
+            <c:value-of name="unfoldVecGroupedNonClassMatch" index="#0" />
+          </c:length-of>
+          <c:length-of>
+            <c:value-of name="unfoldVecGroupedNonClassMatch" index="#1" />
+          </c:length-of>
+          <c:length-of>
+            <c:value-of name="unfoldVecGroupedNonClassMatch" index="#2" />
+          </c:length-of>
+
+          <!-- sum a second time to make sure it's 0 -->
+          <c:length-of>
+            <c:value-of name="unfoldVecGroupedNonClassMatch" index="#1" />
+          </c:length-of>
+        </c:sum>
+      </t:given>
+
+      <t:expect>
+        <t:match-result eq="2" />
+      </t:expect>
+    </t:it>
+  </t:describe>
+</package>

core/vector/fold.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0"?>
+<!--
+  Copyright (C) 2018 R-T Specialty, LLC.
+
+  This file is part of tame-core.
+
+  tame-core is free software: you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as
+  published by the Free Software Foundation, either version 3 of the
+  License, or (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+-->
+<package xmlns="http://www.lovullo.com/rater"
+         xmlns:c="http://www.lovullo.com/calc"
+         xmlns:t="http://www.lovullo.com/rater/apply-template"
+         core="true"
+         desc="Folding and Unfolding of Vectors">
+
+  <import package="../base" />
+  <import package="filter" export="true" />
+
+
+  The term ``fold'' is also referred to as ``reduce''---%
+    they are synonymous.
+  Unless otherwise specified,
+    folding occurs left-to-right.
+
+  \emph{Unfolding} is the opposite of a reduction---%
+    it \emph{generates} values from existing values.
+
+
+  <section title="Matrix Generation">
+    \ref{_unfold-vector-grouped_} generates a matrix from a vector---%
+      that is, it generates vectors within a vector---%
+      by grouping values.
+
+    The \tt{@class@} is used both as a predicate and as a determination of
+      the resulting vector's length
+        (the~number of rows in the resulting matrix).
+    If non-matching,
+      no columns will be produced for that respective row.
+
+    \tt{@src@} is the vector to be unfolded,
+      containing the raw values to be grouped.
+
+    \tt{@grouping@} \should be the same length as~\ref{@src@} and determines
+      the group~(row) in which the respective value should appear.
+
+    \ref{@generates@} names the resulting matrix and~\ref{@desc@} provides
+      its description.
+
+    <template name="_unfold-vector-grouped_"
+              desc="Unfold vector into a matrix by grouping">
+      <param name="@class@"     desc="Iteration vector of desired length" />
+      <param name="@src@"       desc="Source vector" />
+      <param name="@grouping@"  desc="Grouping vector" />
+      <param name="@generates@" desc="Generator name (to yield)" />
+
+      <param name="@desc@" desc="Generator description">
+        <text>Unfolded vector </text>
+        <param-value name="@src@" />
+        <text> grouped by </text>
+        <param-value name="@grouping@" />
+      </param>
+
+      <param name="@lengthv@" desc="Length vector (of desired length)">
+        <param-class-to-yields name="@class@" />
+      </param>
+
+
+      <rate yields="_{@generates@}">
+        <c:sum of="@lengthv@" dim="matrix"
+               generates="@generates@" index="k"
+               desc="@desc@">
+          <c:cases>
+            <c:case label="Unfold on class vector match">
+              <c:when name="@lengthv@" index="k" />
+              <c:apply name="vfilter_lookup"
+                       vector_pred="@grouping@" vector_src="@src@"
+                       value="k"
+                       start_index="#0" />
+            </c:case>
+
+            <c:otherwise label="Ignore on class vector non-match">
+              <c:set />
+            </c:otherwise>
+          </c:cases>
+        </c:sum>
+      </rate>
+    </template>
+  </section>
+</package>