From 09d2231fc008aa4b54061394d5192ca9e2ff003a Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Thu, 4 Dec 2014 02:15:22 -0500
Subject: [PATCH] `f:length' added

This is aggressively tested in every instance where it could be affected,
since any mishandling of this value would be incredibly dangerous (best
case, it would blow up and abort; worst case, data are interchanged between
refs).
---
 src/apply/ref.xsl    | 29 ++++++++++++++++++++++++-
 test/apply/ref.xspec | 51 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/src/apply/ref.xsl b/src/apply/ref.xsl
index c1a7be4..32b92ff 100644
--- a/src/apply/ref.xsl
+++ b/src/apply/ref.xsl
@@ -66,7 +66,7 @@
   <variable name="ns"
             select="namespace-uri-from-QName( $name )" />
 
-  <f:ref arity="{$arity}">
+  <f:ref arity="{$arity}" length="1">
     <element name="{$name}"
              namespace="{$ns}" />
   </f:ref>
@@ -200,6 +200,9 @@
     <attribute name="arity"
                select="$target-arity - count( $args )" />
 
+    <attribute name="length"
+               select="count( $args ) + 1" />
+
     <sequence select="$desc/*" />
   </f:ref>
 
@@ -234,4 +237,28 @@
                                ($args, f:args( $fnref )) )" />
 </function>
 
+
+<!--
+  Retrieve length of @var{fnref} as a number of sequence items
+
+  While the reference is intended to be opaque, it is no secret that
+  the data are stored as a sequence.  The length is therefore
+  important for stepping through that sequence of data, similar to how
+  data/struct length are required for pointer arithmetic when dealing
+  with memory in C.
+
+  So, this doesn't break encapsulation: it just tells us how big we
+  are, which is an external quality that can be easily discovered
+  without our help; we just cache it for both performance and
+  convenience.  Aren't we nice?
+-->
+<function name="f:length" as="xs:double">
+  <param name="fnref" as="item()+" />
+
+  <variable name="desc" as="element( f:ref )"
+            select="$fnref[ 1 ]" />
+
+  <sequence select="number( $desc/@length )" />
+</function>
+
 </stylesheet>
diff --git a/test/apply/ref.xspec b/test/apply/ref.xspec
index 86d0b2a..cc67ffe 100644
--- a/test/apply/ref.xspec
+++ b/test/apply/ref.xspec
@@ -68,6 +68,13 @@
 
       <expect label="produces reference to expected QName"
               test="f:QName( $x:result ) = $qname" />
+
+      <!-- this isn't breaking encapsulation: we know that a sequence
+           is returned and we must know how to delimit the references
+           within it -->
+      <expect label="produces length equal to length of returned
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -281,6 +288,10 @@
 
       <expect label="retains target arity"
               test="f:arity( $x:result ) = f:arity( $test-fn )" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -296,6 +307,10 @@
       <!-- the function is now partially applied -->
       <expect label="reduces arity by number of arguments"
               test="f:arity( $x:result ) = f:arity( $test-fn ) - 2" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -313,6 +328,10 @@
       <!-- the function is no longer partially applied -->
       <expect label="restores target function arity"
               test="f:arity( $x:result ) = f:arity( $test-fn )" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -330,6 +349,10 @@
       <!-- the function is no longer partially applied -->
       <expect label="reduces arity by number of argments"
               test="f:arity( $x:result ) = f:arity( $test-fn ) - 3" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -347,6 +370,10 @@
       <!-- the function is no longer partially applied -->
       <expect label="increases arity by difference in argument count"
               test="f:arity( $x:result ) = f:arity( $test-fn ) - 1" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
   </scenario>
 
@@ -419,6 +446,10 @@
       <expect label="sets arguments by reference"
               test="f:args( $x:result )[ 1 ] is $args/foo:a
                     and f:args( $x:result )[ 2 ] is $args/foo:b" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -448,6 +479,10 @@
       <expect label="pushes new arguments by reference"
               test="f:args( $x:result )[ 3 ] is $args/foo:c
                     and f:args( $x:result )[ 4 ] is $args/foo:d" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -470,6 +505,10 @@
       <expect label="retains previous arguments by reference"
               test="f:args( $x:result )[ 1 ] is $args/foo:a
                     and f:args( $x:result )[ 2 ] is $args/foo:b" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
   </scenario>
 
@@ -494,6 +533,10 @@
       <expect label="sets arguments by reference"
               test="f:args( $x:result )[ 1 ] is $args/foo:a
                     and f:args( $x:result )[ 2 ] is $args/foo:b" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -523,6 +566,10 @@
       <expect label="unshifts new arguments by reference"
               test="f:args( $x:result )[ 1 ] is $args/foo:c
                     and f:args( $x:result )[ 2 ] is $args/foo:d" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
 
 
@@ -545,6 +592,10 @@
       <expect label="retains previous arguments by reference"
               test="f:args( $x:result )[ 1 ] is $args/foo:a
                     and f:args( $x:result )[ 2 ] is $args/foo:b" />
+
+      <expect label="produces length equal to length of constructed
+                     sequence"
+              test="f:length( $x:result ) = count( $x:result )" />
     </scenario>
   </scenario>
 </description>