Skip to content

Commit

Permalink
fn:intersperse → fn:join, array:join($arrays, $separator). Closes #868
Browse files Browse the repository at this point in the history
  • Loading branch information
@ChristianGruen
ChristianGruen committed Oct 24, 2024
1 parent 75f1197 commit 3a1b71e
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 49 deletions.
105 changes: 59 additions & 46 deletions specifications/xpath-functions-40/src/function-catalog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4857,7 +4857,7 @@ return normalize-unicode(concat($v1, $v2))</eg>
<fos:signatures>
<fos:proto name="string-join" return-type="xs:string">
<fos:arg name="values" type="xs:anyAtomicType*"/>
<fos:arg name="separator" type="xs:string?" default='""'/>
<fos:arg name="separator" type="xs:string*" default='()'/>
</fos:proto>
</fos:signatures>
<fos:properties>
Expand All @@ -4866,22 +4866,18 @@ return normalize-unicode(concat($v1, $v2))</eg>
<fos:property>focus-independent</fos:property>
</fos:properties>
<fos:summary>
<p>Returns a string created by concatenating the items in a sequence, with a defined
separator between adjacent items.</p>
<p>Returns a string created by concatenating the items in a sequence,
with an optional separator between adjacent items.</p>
</fos:summary>
<fos:rules>
<p>If the second argument is omitted or an empty sequence, the effect is the same as
calling the two-argument version with <code>$separator</code> set to a zero-length
string.</p>
<p>The coercion rules ensure that the supplied <code>$values</code> argument is first converted to
a sequence of atomic items by applying atomization.</p>
<p>The coercion rules ensure that the supplied <code>$values</code> argument is first
converted to a sequence of atomic items by applying atomization.</p>
<p>The function then returns an <code>xs:string</code> created by casting each item
in the atomized sequence to an <code>xs:string</code>,
and then concatenating the result strings in order,
using the value of <code>$separator</code> as a
separator between adjacent strings. If <code>$separator</code> is the zero-length
string, then the items in <code>$values</code> are concatenated without a separator.</p>

in the atomized sequence to an <code>xs:string</code>, and then concatenating the
result strings in order, using the string values of <code>$separator</code> as a
separator between adjacent strings. If <code>$separator</code> is an empty sequence or
a single zero-length string, then the items in <code>$values</code> are concatenated
without a separator.</p>
</fos:rules>
<fos:notes>
<p>If <code>$values</code> is the empty sequence, the function returns the
Expand All @@ -4896,8 +4892,8 @@ return normalize-unicode(concat($v1, $v2))</eg>
</fos:example>
<fos:example>
<fos:test>
<fos:expression>string-join(('Now', 'is', 'the', 'time', '...'), ' ')</fos:expression>
<fos:result>"Now is the time ..."</fos:result>
<fos:expression>string-join(('Now', 'is', 'the', 'time'), ('?', '!'))</fos:expression>
<fos:result>"Now?!is?!the?!time"</fos:result>
</fos:test>
</fos:example>
<fos:example>
Expand All @@ -4923,11 +4919,7 @@ return normalize-unicode(concat($v1, $v2))</eg>
</fos:example>

<fos:variable name="doc" id="v-string-join-doc"
>&lt;doc&gt;
&lt;chap&gt;
&lt;section xml:id="xyz"/&gt;
&lt;/chap&gt;
&lt;/doc&gt;</fos:variable>
>&lt;doc&gt;&lt;chap&gt;&lt;section xml:id="xyz"/&gt;&lt;/chap&gt;&lt;/doc&gt;</fos:variable>
<fos:example>
<fos:test use="v-string-join-doc" spec="XQuery">
<fos:expression><eg>$doc//@xml:id
Expand All @@ -4943,6 +4935,11 @@ return normalize-unicode(concat($v1, $v2))</eg>
</fos:test>
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="868" date="2024-10-16">
<p>The second argument can now be a sequence.</p>
</fos:change>
</fos:changes>
</fos:function>
<fos:function name="substring" prefix="fn">
<fos:signatures>
Expand Down Expand Up @@ -14442,11 +14439,11 @@ filter($input, fn($item, $pos) { $pos gt 1 })
</fos:changes>
</fos:function>

<fos:function name="intersperse" prefix="fn">
<fos:function name="join" prefix="fn">
<fos:signatures>
<fos:proto name="intersperse" return-type="item()*">
<fos:proto name="join" return-type="item()*">
<fos:arg name="input" type="item()*" usage="navigation"/>
<fos:arg name="separator" type="item()*" usage="navigation"/>
<fos:arg name="separator" type="item()*" default="()" usage="navigation"/>
</fos:proto>
</fos:signatures>
<fos:properties>
Expand All @@ -14458,47 +14455,46 @@ filter($input, fn($item, $pos) { $pos gt 1 })
<p>Inserts a separator between adjacent items in a sequence.</p>
</fos:summary>
<fos:rules>
<p>The function returns the value of <code>head($input), tail($input) ! ($separator, .)</code>.</p>
<p>The function inserts a separator between adjacent items in a sequence.
The input is returned unchanged if <code>$separator</code> is the empty sequence
or if <code>$input</code> contains less than two items.</p>
</fos:rules>
<fos:equivalent style="xpath-expression">
for-each($input, fn($item, $pos) {
if ($pos eq 1)
then $item
else ($separator, $item)
if ($pos gt 1) { $separator },
$item
})
</fos:equivalent>
<fos:notes>
<p>If <code>$input</code> contains less than two items then it is returned unchanged.</p>
<p>If <code>$separator</code> is the empty sequence then <code>$input</code> is returned unchanged.</p>
<p>For example, in XQuery, <code>fn:intersperse(para, &lt;hr/>)</code> would insert
an empty <code>hr</code> element between adjacent paragraphs.</p>
</fos:notes>
<fos:examples>
<fos:example>
<fos:test>
<fos:expression>intersperse(1 to 5, "|")</fos:expression>
<fos:expression>join(1 to 5, "|")</fos:expression>
<fos:result>(1, "|", 2, "|" , 3, "|", 4, "|", 5)</fos:result>
</fos:test>
<fos:test>
<fos:expression>intersperse((), "|")</fos:expression>
<fos:expression>join((), "|")</fos:expression>
<fos:result>()</fos:result>
</fos:test>
<fos:test>
<fos:expression>intersperse("A", "|")</fos:expression>
<fos:expression>join("A", "|")</fos:expression>
<fos:result>"A"</fos:result>
</fos:test>
<fos:test>
<fos:expression>intersperse(1 to 5, ())</fos:expression>
<fos:expression>join(1 to 5, ())</fos:expression>
<fos:result>(1, 2, 3, 4, 5)</fos:result>
</fos:test>
<fos:test>
<fos:expression>intersperse(1 to 3, ("⅓", "⅔"))</fos:expression>
<fos:expression>join(1 to 3, ("⅓", "⅔"))</fos:expression>
<fos:result>(1, "⅓", "⅔", 2, "⅓", "⅔", 3)</fos:result>
</fos:test>
</fos:example>
<fos:example>
<p>Insert an empty <code>hr</code> element between adjacent paragraphs:</p>
<eg><![CDATA[join(./para, <hr/>)]]></eg>
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="2" date="2022-09-27"><p>New in 4.0</p></fos:change>
<fos:change issue="2 868" date="2022-09-27"><p>New in 4.0</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -27080,6 +27076,7 @@ $array
<fos:signatures>
<fos:proto name="join" return-type="array(*)">
<fos:arg name="arrays" type="array(*)*" usage="inspection"/>
<fos:arg name="separator" type="array(*)?" default="[]" usage="navigation"/>
</fos:proto>
</fos:signatures>
<fos:properties>
Expand All @@ -27088,16 +27085,22 @@ $array
<fos:property>focus-independent</fos:property>
</fos:properties>
<fos:summary>
<p>Concatenates the contents of several arrays into a single array.</p>
<p>Concatenates the contents of several arrays into a single array, with an optional
separator between adjacent members.</p>
</fos:summary>
<fos:rules>
<p>Informally, the function concatenates the members of several arrays into a single array.</p>
<!--<p diff="chg" at="A">More formally, the function returns the result of
<code>array:of-members($arrays ! array:members(.))</code>.</p>-->
<p>Informally, the function concatenates the members of several arrays into a single array.
If a separator is supplied, its members are inserted before the members of the second
and the following arrays.</p>
</fos:rules>
<fos:equivalent style="xpath-expression"><![CDATA[
array:of-members($arrays ! array:members(.))
]]></fos:equivalent>
array:of-members(
for-each($arrays, fn($array, $pos) {
if ($pos gt 1) { array:members($separator) },
array:members($array)
})
)
]]></fos:equivalent>
<fos:examples>
<fos:example>
<fos:test>
Expand All @@ -27120,6 +27123,16 @@ $array
<fos:expression>array:join(([ "a", "b" ], [ [ "c", "d" ] ]))</fos:expression>
<fos:result>[ "a", "b", [ "c", "d" ] ]</fos:result>
</fos:test>
<fos:test>
<fos:expression>array:join(([ 1 ], [ 2, (3, 4) ]), [ 7, (8, 9) ])</fos:expression>
<fos:result>[ 1, 7, (8, 9), 2, (3, 4) ]</fos:result>
</fos:test>
<fos:test>
<fos:expression><eg>array { 1 to 3 }
=> array:split()
=> array:join([ () ])</eg></fos:expression>
<fos:result>[ 1, (), 2, (), 3 ]</fos:result>
</fos:test>
</fos:example>
</fos:examples>
</fos:function>
Expand Down
6 changes: 3 additions & 3 deletions specifications/xpath-functions-40/src/xpath-functions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5514,12 +5514,12 @@ correctly in all browsers, depending on the system configuration.</emph></p>-->
<div3 id="func-insert-before">
<head><?function fn:insert-before?></head>
</div3>
<div3 id="func-intersperse" diff="add" at="A">
<head><?function fn:intersperse?></head>
</div3>
<div3 id="func-items-at" diff="add" at="2022-11-16">
<head><?function fn:items-at?></head>
</div3>
<div3 id="func-join" diff="add" at="A">
<head><?function fn:join?></head>
</div3>
<div3 id="func-remove">
<head><?function fn:remove?></head>
</div3>
Expand Down

0 comments on commit 3a1b71e

Please sign in to comment.