new divide-decimals function

michaelhkay · Jan 1, 2025 · 1c00c95 · 1c00c95
1 parent 4eaeba1
commit 1c00c95
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 0 deletions.
diff --git a/specifications/xpath-functions-40/src/function-catalog.xml b/specifications/xpath-functions-40/src/function-catalog.xml
@@ -2359,6 +2359,97 @@ compare($N * $arg2, 0) eq compare($arg1, 0).</eg>
          </fos:example>
       </fos:examples>
    </fos:function>
+
+
+   <fos:function name="divide-decimals" prefix="fn">
+      <fos:signatures>
+         <fos:proto name="divide-decimals" return-type="record(quotient as xs:decimal, remainder as xs:decimal)">
+            <fos:arg name="value" type="xs:decimal"/>
+            <fos:arg name="divisor" type="xs:decimal"/>
+            <fos:arg name="precision" type="xs:integer?" default="0"/>
+         </fos:proto>
+      </fos:signatures>
+      <fos:properties>
+         <fos:property>deterministic</fos:property>
+         <fos:property>context-independent</fos:property>
+         <fos:property>focus-independent</fos:property>
+      </fos:properties>
+      <fos:summary>
+         <p>Divides one <code>xs:decimal</code> by another to a defined precision, returning
+            both the quotient and the remainder.</p>
+      </fos:summary>
+      <fos:rules>
+         <p>The function returns a record with two fields:</p>
+         <olist>
+            <item>
+               <p><code>quotient</code> is the <code>xs:decimal</code> value 
+                  furthest from zero such that:</p>
+               <olist>
+                  <item><p><code>quotient</code> is an exact multiple of ten to the power
+                  of minus <code>$precision</code>, and</p></item>
+                  <item><p>the absolute value of <code>quotient</code> 
+                     multipled by <code>$divisor</code> is less than or equal to the absolute
+                  value of <code>$value</code>.</p></item>
+               </olist>
+            </item>
+            <item>
+               <p><code>remainder</code> is the exact result of subtracting <code>quotient</code>
+               multiplied by <code>$divisor</code> from <code>$value</code>.</p>
+            </item>
+         </olist>
+
+         <p>If <code>$precision</code> exceeds the maximum precision for <code>xs:decimal</code>
+         values supported by the implementation, then the maximum available precision is
+         used in its place.</p>
+
+      </fos:rules>
+
+      <fos:examples>
+         <fos:example>
+            <fos:test>
+               <fos:expression>divide-decimals(120.6, 60.3, 4)</fos:expression>
+               <fos:result>{ "quotient": 2, "remainder": 0 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(10, 3)</fos:expression>
+               <fos:result>{ "quotient": 3, "remainder": 1 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(10, -3)</fos:expression>
+               <fos:result>{ "quotient": -3, "remainder": 1 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(-10, 3)</fos:expression>
+               <fos:result>{ "quotient": -3, "remainder": -1 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(-10, -3)</fos:expression>
+               <fos:result>{ "quotient": 3, "remainder": -1 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(10, 3, 6)</fos:expression>
+               <fos:result>{ "quotient": 3.333333, "remainder": 0.000001 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(100, 30)</fos:expression>
+               <fos:result>{ "quotient": 3, "remainder": 10 }</fos:result>
+            </fos:test>
+            <fos:test>
+               <fos:expression>divide-decimals(150_862, 7, -3)</fos:expression>
+               <fos:result>{ "quotient": 21_000, "remainder": 3_862 }</fos:result>
+            </fos:test>
+
+         </fos:example>
+      </fos:examples>
+      <fos:changes>
+         <fos:change issue="1261" date="2025-01-01">
+            <p>New in 4.0.</p>
+         </fos:change>
+      </fos:changes>
+   </fos:function>
+
+
+
    <fos:function name="format-integer" prefix="fn">
       <fos:signatures>
          <fos:proto name="format-integer" return-type="xs:string">

diff --git a/specifications/xpath-functions-40/src/xpath-functions.xml b/specifications/xpath-functions-40/src/xpath-functions.xml
@@ -1951,6 +1951,9 @@ This differs from <bibref ref="xmlschema-2"/>, which defines
             <div3 id="func-round-half-to-even">
                <head><?function fn:round-half-to-even?></head>
             </div3>
+            <div3 id="func-divide-decimals">
+               <head><?function fn:divide-decimals?></head>
+            </div3>
             <div3 id="func-is-NaN" diff="add" at="A">
                <head><?function fn:is-NaN?></head>
             </div3>