Previous (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:XmlNode:Previous subtitle}}
{{Template:XmlNode:Previous subtitle}}
 
<var>Previous</var> returns the previous <var>XmlNode</var> that has the same parent as the method object.
This function returns the previous <var>XmlNode</var> with the same parent as the method object.
<ul>
<ul>
<li>If the method object is a non-Attribute node, the previous <var>XmlNode</var> is
<li>If the method object is a non-<var>Attribute</var> node, the previous <var>XmlNode</var> is the previous sibling (in document order) of the method object. This is exactly the same as the node returned by <var>[[SelectSingleNode_(XmlDoc/XmlNode_function)|SelectSingleNode]]</var> with <code>'preceding-sibling::node()[1]'</code> as its [[XPath]] argument. This is demonstrated below in [[#PreviousEx1|example 1]] .
the previous sibling (in document order) of the method object.
<li>If the method object is an <var>Attribute</var> node, the previous <var>XmlNode</var> is the preceding <var>Attribute</var> node produced if the <var>Element</var> containing the method object were serialized in "normal" (that is, ''not'' <var>ExclCanonical</var>) order.
This is exactly the same as the node returned by SelectSingleNode
<li>If no "previous" node exists, the <var>Previous</var> method returns a <var>Null</var>.
with <tt>'preceding-sibling::node()[1]'</tt> as its XPath argument.
This is demonstrated below in item [[??]] refid=nonatt page=no.
in [[??]] refid=egprev..
<li>If the method object is an Attribute node, the previous <var>XmlNode</var> is the
preceding Attribute
node produced if the Element containing the method object
were serialized in "normal" (that is, ''not'' ExclCanonical) order.
<li>If no "previous" node exists, the <var>Previous</var> method returns a Null.
</ul>
</ul>


The <var>Previous</var> function is new as of version 7.0 of the <var class="product">Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:XmlNode:Previous syntax}}
{{Template:XmlNode:Previous syntax}}
Line 22: Line 12:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outNod</th>
<tr><th>%outNod</th>
<td>An <var>XmlNode</var>, which will be set to point to the returned node. </td></tr>
<td>An <var>XmlNode</var>, which will be set to point to the returned node.</td></tr>
<tr><th>nod</th>
<tr><th>nod</th>
<td>An <var>XmlNode</var> expression.</td></tr>
<td>An <var>XmlNode</var> expression.</td></tr>
Line 29: Line 19:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The XPath recommendation specifies that
<li>The XPath recommendation specifies that the following-sibling and preceding-sibling axes are the empty nodeSet if the context node is an <var>Attribute</var> node. The <var>[[Next_(XmlNode_function)|Next]]</var> and <var>Previous</var> methods are available if you want to traverse the <var>Attribute</var> nodes of an <var>Element</var>, as a better approach than using the following-sibling and preceding-sibling axes in an XPath argument to a <var>[[SelectNodes_(XmlDoc/XmlNode_function)|SelectNodes]]</var> or <var>SelectSingleNode</var> method. See [[#PreviousEx2|example 2]] below.
the following-sibling and preceding-sibling axes are the empty nodeSet if
the context node is an Attribute node.
The Next ([[??]] reftxt="Next function" refid=nexmeth.) and <var>Previous</var> methods
are available if you want to traverse the Attribute nodes of an Element, as
a better approach than using the following&amp;hyph.sibling and preceding&amp;hyph.sibling
axes in an XPath argument to a SelectNodes or SelectSingleNode method.
See example [[??]] refid=attprev..
</ul>
</ul>


==Examples==
==Examples==
<ol>
<ol><li><div id="PreviousEx1"></div>Given the following document:
<li>Given the following document:
<p class="code"><top>
<p class="code"><top>
  <a/>
  <a/>
Line 50: Line 32:
</top>
</top>
</p>
</p>
 
To select the node that precedes <var>Element</var> <code>c</code>, you can use a sequence of statements like the following:
To select the node that precedes Element <tt>c</tt>, you can use
<p class="code">%n1 is object XmlNode
a sequence of statements like the following:
%n1 = %doc:selectSingleNode('/*/*[3]')
<p class="code">%n1 is object <var>XmlNode</var>
print 'Here is node 3:'
%n1 = %doc:SelectSingleNode('/*/*[3]')
%n1:[[Print_(XmlDoc/XmlNode_subroutine)|print]]
Print 'Here is node 3:'
%n2 = %n1:previous
%n1:Print
print 'Here is the node previous to 3:'
%n2 = %n1:<var>Previous</var>
%n2:print
Print 'Here is the node previous to 3:'
%n2:Print
</p>
</p>
The result is:
The result is:
<p class="output">Here is node 3:
<p class="output">Here is node 3:
Line 68: Line 47:
<b/>
<b/>
</p>
</p>
 
<blockquote class="note">
'''Note:'''
<p>'''Note:''' You might expect a statement sequence like this next one to also obtain the <code>b</code> node as above: </p>
You might expect a statement sequence like
<p class="code">%n2 = %n1:selectSingleNode('preceding-sibling::node()')
this next one to also obtain the <tt>b</tt> node as above:
print 'Here is the preceding-sib to 3:'
<p class="code">%n2 = %n1:SelectSingleNode('preceding-sibling::node()')
%n2:print
Print 'Here is the preceding-sib to 3:'
%n2:Print
</p>
</p>
However, this is the result:
However, this is the result:
<p class="code">Here is the preceding-sib to 3:
<p class="code">Here is the preceding-sib to 3:
<a/>
<a/>
</p>
</p>
 
The preceding-sibling axis generates resultant nodes in reverse document order (in this case, <code>b</code>, then <code>a</code>), which is probably what you intuitively expect. However, the <var>SelectSingleNode</var> statement selects the first of these two generated nodes <i>in document order</i>. To use <var>SelectSingleNode</var> to select the adjacent preceding sibling node,
The preceding-sibling axis generates resultant nodes in reverse document
order (in this case, <tt>b</tt>, then <tt>a</tt>), which is probably what
you intuitively expect.
However, the SelectSingleNode statement selects the first of these two
generated nodes :hp3.in document order:ehp3..
To use SelectSingleNode to select the adjacent preceding sibling node,
use a predicate so the XPath argument selects the (only) node you want:
use a predicate so the XPath argument selects the (only) node you want:
<p class="code">%n2 = %n1:SelectSingleNode('preceding-sibling::node()[1]')
<p class="code">%n2 = %n1:selectSingleNode('preceding-sibling::node()[1]')
</p>
</p>
<li>Given the following document:
</blockquote>
 
<li><div id="PreviousEx2"></div>
Given the following document:
<p class="code"><top>
<p class="code"><top>
  <F b1="b1" b2="b2" b3="b3" b4="b4"/>
  <F b1="b1" b2="b2" b3="b3" b4="b4"/>
</top>
</top>
</p>
</p>
 
To select the <var>Attribute</var> node that precedes <var>Attribute</var> <code>b3</code>, you can use a sequence of statements like the following:
To select the Attribute node that precedes Attribute <tt>b3</tt>, you can use
<p class="code">%n1 = %doc:selectSingleNode('/*/F/@b3'):<var>Previous</var>
a sequence of statements like the following:
print 'Here is attribute previous to b3:'
<p class="code">%n1 = %doc:SelectSingleNode('/*/F/@b3'):<var>Previous</var>
%n1:print
Print 'Here is attribute previous to b3:'
%n1:Print
</p>
</p>
The result is:
The result is:
<p class="output">Here is attribute previous to b3:
<p class="output">Here is attribute previous to b3:
b2="b2"
b2="b2"
</p>
</p>
 
<blockquote class="note">
'''Note:'''
<p>'''Note:'''
The preceding-sibling axis does ''not'' locate
The preceding-sibling axis does ''not'' locate <var>Attribute</var> nodes. The following statement causes a request cancellation:
''Attribute'' nodes.
<p class="code">%n2 = %n1:selectSingleNode('preceding-sibling::node()[1]')
The following statement causes a request cancellation:
<p class="code">%n2 = %n1:SelectSingleNode('preceding-sibling::node()[1]')
</p>
</p>
</blockquote>
</ol>
</ol>
==See also==
==See also==
{{Template:XmlNode:Previous footer}}
{{Template:XmlNode:Previous footer}}

Latest revision as of 20:59, 3 March 2014

Get node previous to this node (XmlNode class)

Previous returns the previous XmlNode that has the same parent as the method object.

  • If the method object is a non-Attribute node, the previous XmlNode is the previous sibling (in document order) of the method object. This is exactly the same as the node returned by SelectSingleNode with 'preceding-sibling::node()[1]' as its XPath argument. This is demonstrated below in example 1 .
  • If the method object is an Attribute node, the previous XmlNode is the preceding Attribute node produced if the Element containing the method object were serialized in "normal" (that is, not ExclCanonical) order.
  • If no "previous" node exists, the Previous method returns a Null.

Syntax

%outNod = nod:Previous

Syntax terms

%outNod An XmlNode, which will be set to point to the returned node.
nod An XmlNode expression.

Usage notes

  • The XPath recommendation specifies that the following-sibling and preceding-sibling axes are the empty nodeSet if the context node is an Attribute node. The Next and Previous methods are available if you want to traverse the Attribute nodes of an Element, as a better approach than using the following-sibling and preceding-sibling axes in an XPath argument to a SelectNodes or SelectSingleNode method. See example 2 below.

Examples

  1. Given the following document:

    <top> <a/> <c/> <d/> <e/> </top>

    To select the node that precedes Element c, you can use a sequence of statements like the following:

    %n1 is object XmlNode %n1 = %doc:selectSingleNode('/*/*[3]') print 'Here is node 3:' %n1:print %n2 = %n1:previous print 'Here is the node previous to 3:' %n2:print

    The result is:

    Here is node 3: <c/> Here is the node previous to 3:

    Note: You might expect a statement sequence like this next one to also obtain the b node as above:

    %n2 = %n1:selectSingleNode('preceding-sibling::node()') print 'Here is the preceding-sib to 3:' %n2:print

    However, this is the result:

    Here is the preceding-sib to 3: <a/>

    The preceding-sibling axis generates resultant nodes in reverse document order (in this case, b, then a), which is probably what you intuitively expect. However, the SelectSingleNode statement selects the first of these two generated nodes in document order. To use SelectSingleNode to select the adjacent preceding sibling node, use a predicate so the XPath argument selects the (only) node you want:

    %n2 = %n1:selectSingleNode('preceding-sibling::node()[1]')

  2. Given the following document:

    <top> <F b1="b1" b2="b2" b3="b3" b4="b4"/> </top>

    To select the Attribute node that precedes Attribute b3, you can use a sequence of statements like the following:

    %n1 = %doc:selectSingleNode('/*/F/@b3'):Previous print 'Here is attribute previous to b3:' %n1:print

    The result is:

    Here is attribute previous to b3: b2="b2"

    Note: The preceding-sibling axis does not locate Attribute nodes. The following statement causes a request cancellation:

    %n2 = %n1:selectSingleNode('preceding-sibling::node()[1]')

See also