Difference between revisions of "Update Module"
Jump to navigation
Jump to search
(14 intermediate revisions by 3 users not shown) | |||
Line 8: | Line 8: | ||
=Updates= | =Updates= | ||
+ | |||
+ | ==update:apply== | ||
+ | |||
+ | {| | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|update:apply|$function as function(*), $arguments as array(*)|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |The updating variant of [[XQuery 3.1#fn:apply|fn:apply]] applies the specified updating <code>$function</code> to the specified <code>$arguments</code>. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * Creates a new database with an initial document and adds a document to an existing database. | ||
+ | <pre class="brush:xquery"> | ||
+ | declare %updating function local:update( | ||
+ | $database as xs:string, | ||
+ | $path as xs:string, | ||
+ | $function as %updating function(item(), xs:string) as empty-sequence() | ||
+ | ) as empty-sequence() { | ||
+ | update:apply($function, [ $database, $path ]) | ||
+ | }; | ||
+ | local:update('new-db', 'doc.xml', db:create#2), | ||
+ | local:update('existing-db', 'doc.xml', db:add#2) | ||
+ | </pre> | ||
+ | |} | ||
==update:for-each== | ==update:for-each== | ||
Line 14: | Line 40: | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|update:for-each|$seq as item()*, $function as function(item()) as item()* | + | |{{Func|update:for-each|$seq as item()*, $function as function(item()) as item()*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 33: | Line 59: | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|update:for-each-pair|$seq1 as item()*, $function as function(item()) as item()* | + | |{{Func|update:for-each-pair|$seq1 as item()*, $function as function(item()) as item()*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 40: | Line 66: | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * Renames nodes in an XML snippets: |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
copy $xml := <xml><a/><b/></xml> | copy $xml := <xml><a/><b/></xml> | ||
Line 53: | Line 79: | ||
return $xml | return $xml | ||
</pre> | </pre> | ||
+ | |} | ||
+ | |||
+ | ==update:map-for-each== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|update:map-for-each|$map as map(*), $function as function(xs:anyAtomicType, item()*) as item()*|item()*}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |The updating variant of {{Function|Map|map:for-each}} applies the specified {{Code|$function}} to every key/value pair of the supplied {{Code|$map}} and returns the results as a sequence. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * Inserts attributes into a document: | ||
+ | <pre class="brush:xquery"> | ||
+ | copy $doc := <xml/> | ||
+ | modify update:map-for-each( | ||
+ | map { | ||
+ | 'id': 'id0', | ||
+ | 'value': 456 | ||
+ | }, | ||
+ | function($key, $value) { | ||
+ | insert node attribute { $key } { $value } into $doc | ||
+ | } | ||
+ | ) | ||
+ | return $doc</pre> | ||
|} | |} | ||
Line 58: | Line 110: | ||
==update:output== | ==update:output== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|update:output|$ | + | |{{Func|update:output|$items as item()*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |This function is | + | |This function can be used if {{Option|MIXUPDATES}} is not enabled, and if values need to returned within an updating expression: The supplied {{Code|$items}} will be cached and returned at the very end, i.e., after all updates on the ''pending update list'' have been processed. If one of the supplied items is affected by an update, a copy will be created and cached instead. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 74: | Line 124: | ||
|} | |} | ||
− | ==update: | + | ==update:cache== |
− | {{Mark|Updated with Version 9. | + | {{Mark|Updated with Version 9.3}}: {{code|$reset}} option added. |
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|update: | + | |{{Func|update:cache||item()*}}<br/>{{Func|update:cache|$reset as xs:boolean|item()*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the items that have been cached by | + | |Returns the items that have been cached by {{Function|Update|update:output}}. The output cache can optionally be {{Code|$reset}}. The function can be used to check which items will eventually be returned as result of an updating function.<br/>This function is ''non-deterministic'': It will return different results before and after items have been cached. It is e. g. useful when writing [[Unit Module|unit tests]]. |
|} | |} | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.3 | ||
+ | |||
+ | * [[#update:cache|update:cache]]: {{code|$reset}} parameter added. | ||
+ | |||
+ | ;Version 9.1 | ||
+ | |||
+ | * [[#update:output|update:output]]: Maps and arrays can be cached if they contain no persistent database nodes or function items. | ||
+ | |||
+ | ;Version 9.0 | ||
+ | |||
+ | * Updated: db:output renamed to {{Function|Update|update:output}}, db:output-cache renamed to {{Function|Update|update:cache}} | ||
This module was introduced with Version 9.0. | This module was introduced with Version 9.0. |
Revision as of 14:40, 18 July 2019
This XQuery Module provides additional functions for performing updates and returning results in updating expressions.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/update
namespace, which is statically bound to the update
prefix.
Except for update:output-cache, all functions are updating and thus comply to the XQuery Update constraints.
Updates
update:apply
Signatures | update:apply($function as function(*), $arguments as array(*)) as empty-sequence()
|
Summary | The updating variant of fn:apply applies the specified updating $function to the specified $arguments .
|
Examples |
declare %updating function local:update( $database as xs:string, $path as xs:string, $function as %updating function(item(), xs:string) as empty-sequence() ) as empty-sequence() { update:apply($function, [ $database, $path ]) }; local:update('new-db', 'doc.xml', db:create#2), local:update('existing-db', 'doc.xml', db:add#2) |
update:for-each
Signatures | update:for-each($seq as item()*, $function as function(item()) as item()*) as empty-sequence()
|
Summary | The updating variant of fn:for-each applies the specified updating $function to every item of $seq .
|
Examples |
let $names := ('db1', 'db2') return update:for-each($names, db:create#1) |
update:for-each-pair
Signatures | update:for-each-pair($seq1 as item()*, $function as function(item()) as item()*) as empty-sequence()
|
Summary | The updating variant of fn:for-each-pair applies the specified updating $function to the successive pairs of items of $seq1 and $seq2 . Evaluation is stopped if one sequence yields no more items.
|
Examples |
copy $xml := <xml><a/><b/></xml> modify update:for-each-pair( ('a', 'b'), ('d', 'e'), function($source, $target) { for $e in $xml/*[name() = $source] return rename node $e as $target } ) return $xml |
update:map-for-each
Signatures | update:map-for-each($map as map(*), $function as function(xs:anyAtomicType, item()*) as item()*) as item()*
|
Summary | The updating variant of map:for-each applies the specified $function to every key/value pair of the supplied $map and returns the results as a sequence.
|
Examples |
copy $doc := <xml/> modify update:map-for-each( map { 'id': 'id0', 'value': 456 }, function($key, $value) { insert node attribute { $key } { $value } into $doc } ) return $doc |
Output
update:output
Signatures | update:output($items as item()*) as empty-sequence()
|
Summary | This function can be used if MIXUPDATES is not enabled, and if values need to returned within an updating expression: The supplied $items will be cached and returned at the very end, i.e., after all updates on the pending update list have been processed. If one of the supplied items is affected by an update, a copy will be created and cached instead.
|
Examples |
|
update:cache
Template:Mark: $reset
option added.
Signatures | update:cache() as item()* update:cache($reset as xs:boolean) as item()*
|
Summary | Returns the items that have been cached by update:output . The output cache can optionally be $reset . The function can be used to check which items will eventually be returned as result of an updating function.This function is non-deterministic: It will return different results before and after items have been cached. It is e. g. useful when writing unit tests. |
Changelog
- Version 9.3
- update:cache:
$reset
parameter added.
- Version 9.1
- update:output: Maps and arrays can be cached if they contain no persistent database nodes or function items.
- Version 9.0
- Updated: db:output renamed to
update:output
, db:output-cache renamed toupdate:cache
This module was introduced with Version 9.0.