DeleteTopElement (XmlDoc subroutine) - Revision history

ELowell at 16:37, 1 September 2015

2015-09-01T16:37:46Z

← Older revision		Revision as of 16:37, 1 September 2015
Line 1:		Line 1:
	{{Template:XmlDoc:DeleteTopElement subtitle}}		{{Template:XmlDoc:DeleteTopElement subtitle}}

	This subroutine removes the top [[XmlDoc API#XmlDoc node types\|Element node]] from an <var>XmlDoc</var>, and it		This subroutine removes the top [[XmlDoc API#XmlDoc node types\|Element node]] from an <var>XmlDoc</var>, and it
	makes the deleted <var>Element</var>'s children be the "middle siblings" of its left and right siblings (<var>Comments</var> or <var>PIs</var>).		makes the deleted <var>Element</var>'s children be the "middle siblings" of its left and right siblings (<var>Comments</var> or <var>PIs</var>).

JAL: typo

2014-11-07T20:00:03Z

typo

← Older revision		Revision as of 20:00, 7 November 2014
Line 165:		Line 165:
	==See also==		==See also==
	<ul>		<ul>
	<li><var>[[AddTopElement(XmlDoc function)\|AddTopElement]]</var>		<li><var>[[AddTopElement (XmlDoc function)\|AddTopElement]]</var>

	{{Template:XmlDoc:DeleteTopElement footer}}		{{Template:XmlDoc:DeleteTopElement footer}}

JAL: /* See also */

2014-09-02T21:39:58Z

JAL at 17:24, 3 March 2014

2014-03-03T17:24:24Z

← Older revision		Revision as of 17:24, 3 March 2014
Line 1:		Line 1:
	{{Template:XmlDoc:DeleteTopElement subtitle}}		{{Template:XmlDoc:DeleteTopElement subtitle}}

	This subroutine removes the top ~~<var>~~Element~~</var>~~ from an <var>XmlDoc</var>, and it		This subroutine removes the top [[XmlDoc API#XmlDoc node types\|Element node]] from an <var>XmlDoc</var>, and it
	makes the deleted <var>Element</var>'s children be the ~~“~~middle siblings~~”~~ of its left and right siblings (<var>Comments</var> or <var>PIs</var>).		makes the deleted <var>Element</var>'s children be the "middle siblings" of its left and right siblings (<var>Comments</var> or <var>PIs</var>).
	<ul>		<ul>
	<li>The deleted <var>Element</var> may not have more than one		<li>The deleted <var>Element</var> may not have more than one

JAL2: /* See also */

2012-06-19T21:33:02Z

JAL2 at 19:43, 3 June 2011

2011-06-03T19:43:18Z

← Older revision		Revision as of 19:43, 3 June 2011
Line 163:		Line 163:
	</ul>		</ul>

			==See also==
	{{Template:XmlDoc:DeleteTopElement footer}}		{{Template:XmlDoc:DeleteTopElement footer}}

JAL2 at 19:26, 3 June 2011

2011-06-03T19:26:55Z

← Older revision		Revision as of 19:26, 3 June 2011
Line 2:		Line 2:

	This subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>, and it		This subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>, and it
	makes ~~its~~ children be the “middle siblings” of ~~the~~ left and right siblings (<var>Comments</var> or <var>PIs</var>)		makes the deleted <var>Element</var>'s children be the “middle siblings” of its left and right siblings (<var>Comments</var> or <var>PIs</var>).
	~~of the deleted <var>Element</var>~~.
	<ul>		<ul>
	<li>The deleted ~~element~~ may not have more than one		<li>The deleted <var>Element</var> may not have more than one
	<var>Element</var> child.		<var>Element</var> child.
	<li>The deleted ~~element~~ may not have a <var>Text</var> child.		<li>The deleted <var>Element</var> may not have a <var>Text</var> child.
	</ul>		</ul>
	In common usage, the <var>Element</var> child of the deleted <var>Element</var> will become the		In common usage, the <var>Element</var> child of the deleted <var>Element</var> will become the
	new top <var>Element</var> of the <var>XmlDoc</var>.		new top <var>Element</var> of the <var>XmlDoc</var>.
			__TOC__

	==Syntax==		==Syntax==
Line 24:		Line 24:
	<ul>		<ul>
	<li><var>DeleteTopElement</var> is a convenient, better-performing alternative to using		<li><var>DeleteTopElement</var> is a convenient, better-performing alternative to using
	<var>[[AddSubtree (XmlDoc/XmlNode function)\|AddSubtree]]</var> to copy all but the top Element (or in multiple iterations,		<var>[[AddSubtree (XmlDoc/XmlNode function)\|AddSubtree]]</var> to copy all but the top <var>Element</var> (or in multiple iterations, removing successive top <var>Elements</var>) from an <var>XmlDoc</var>.
	removing successive top Elements) from an <var>XmlDoc</var>.

	For example, you can use it to remove the SOAP wrappers from an <var>XmlDoc</var>.		For example, you can use it to remove the SOAP wrappers from an <var>XmlDoc</var>.
Line 46:		Line 45:
	</data>		</data>
	</nowiki></p>		</nowiki></p>

	<li>~~The remaining considerations for using~~ <var>DeleteTopElement</var>		<div id="wrap2"></div>
	~~concern~~ the occurrence of namespace declarations in the		<li>Using <var>DeleteTopElement</var> requires understanding how it handles
	<var>XmlDoc</var>~~; there are a few details to explain how they are~~		the occurrence of namespace declarations in the
	~~manipulated, and to explain how the performance of~~		<var>XmlDoc</var>. As shown in the “SOAP wrapper removal” example above,
	~~<var>DeleteTopElement</var> is affected~~.
	~~<p>~~
	As shown in the “SOAP wrapper removal” example above,
	<var>DeleteTopElement</var> will remove from the <var>XmlDoc</var> any namespace		<var>DeleteTopElement</var> will remove from the <var>XmlDoc</var> any namespace
	declarations (in this example, <code>xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"</code>)		declarations (in this example, <code>xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"</code>)
	that '''are not''' referenced after removing the top Element.		that '''are not''' referenced after removing the top <var>Element</var>.
	~~Note that~~ a ~~variant on~~ the above example ~~can occur using~~ a		<p>Here is a variation of the above example that uses a
	default namespace declaration:</p>		default namespace declaration:</p>
	<p class="code"><nowiki><Envelope xmlns"http://schemas.xmlsoap.org/soap/envelope/">		<p class="code"><nowiki><Envelope xmlns"http://schemas.xmlsoap.org/soap/envelope/">
Line 80:		Line 76:
	removed, even though, strictly speaking, it is not needed.		removed, even though, strictly speaking, it is not needed.

	In addition, <var>DeleteTopElement</var> will move to the new top Element		In addition, <var>DeleteTopElement</var> will move to the new top <var>Element</var>
	any namespace declarations that '''do''' continue to be		any namespace declarations that '''do''' continue to be
	referenced after the top Element deletion:		referenced after the top <var>Element</var> deletion:
	<p class="code"~~><nowiki~~>%n = %d:AddElement('foo', , 'u:uri')		<p class="code">%n = %d:AddElement('foo', , 'u:uri')
	%n:AddElement('bar', , 'u:uri')		%n:AddElement('bar', , 'u:uri')
	%d:Print		%d:Print
Line 89:		Line 85:
	Print 'After deletion:'		Print 'After deletion:'
	%d:Print		%d:Print
	~~</nowiki>~~</p>		</p>
	The result of the above <var class="product">User Language</var> fragment is:		The result of the above <var class="product">User Language</var> fragment is:
	<p class="output"><nowiki><foo xmlns="u:uri">		<p class="output"><nowiki><foo xmlns="u:uri">
Line 105:		Line 101:
	For a detailed explanation of when the cost of <var>DeleteTopElement</var>		For a detailed explanation of when the cost of <var>DeleteTopElement</var>
	might vary with the size of the <var>XmlDoc</var>,		might vary with the size of the <var>XmlDoc</var>,
	~~there are~~ three reasons that the descendants		consider the three reasons that the descendants
	of the new top Element need to be recursively visited:		of the new top <var>Element</var> need to be recursively visited:
	<ol>		<ol>
	<li>Fixing references to moved namespace declaration		<li>Fixing references to the moved namespace declaration
	<p>		<p>
	As mentioned above, one or more namespace declarations can be moved		As mentioned above, one or more namespace declarations can be moved
Line 114:		Line 110:
	Having done that, any references to the moved namespace must be fixed.		Having done that, any references to the moved namespace must be fixed.
	A count is kept to the total references to moved namespace		A count is kept to the total references to moved namespace
	declarations; when this goes to zero, there is no ~~more~~ need to do this.		declarations; when this goes to zero, there is no further need to do this.
	So, for example:</p>		So, for example:</p>
	<p class="code"><nowiki><p:oldTop xmlns:p="p:uri">		<p class="code"><nowiki><p:oldTop xmlns:p="p:uri">
Line 122:		Line 118:
	</p:oldTop>		</p:oldTop>
	</nowiki></p>		</nowiki></p>
	The <code>p:newTop</code> element needs to have ~~it's~~ namespace reference fixed, but that is the only reference to it, so there is no need to visit <code>child</code>.</li>		The <code>p:newTop</code> element needs to have its namespace reference fixed, but that is the only reference to it, so there is no need to visit <code>child</code>.</li>
	<li>Fixing pointers to a deleted namespace declaration		<li>Fixing pointers to a deleted namespace declaration
	<p>		<p>
	When a namespace declaration is deleted, it may be pointed to by other		When a namespace declaration is deleted, it may be pointed to by other
	namespace declarations (there is a graph of them in the <var>XmlDoc</var>)~~; these~~		namespace declarations (there is a graph of them in the <var>XmlDoc</var>). These
	pointers need to be fixed to point to the first non-deleted		pointers need to be fixed to point to the first non-deleted
	declaration following the deleted one.		declaration following the deleted one.
Line 148:		Line 144:
	namespace declaration to occur on an ancestor.		namespace declaration to occur on an ancestor.
	This state is fixed up if <var>DeleteTopElement</var> deletes a non-null		This state is fixed up if <var>DeleteTopElement</var> deletes a non-null
	namespace declaration (as happens in the second “SOAP wrapper		namespace declaration (as happens in the [[#wrap2\|second “SOAP wrapper
	removal” example above~~, the one using a default namespace~~).		removal” example]] above).
	The need to set this state is eliminated in descendants of an Element		The need to set this state is eliminated in descendants of an <var>Element</var>
	that have a default namespace declaration (either null or not).		that have a default namespace declaration (either null or not).
	So, for example:</p>		So, for example:</p>

JAL2 at 15:59, 3 June 2011

2011-06-03T15:59:00Z

← Older revision		Revision as of 15:59, 3 June 2011
Line 1:		Line 1:
	{{Template:XmlDoc:DeleteTopElement subtitle}}		{{Template:XmlDoc:DeleteTopElement subtitle}}

	This subroutine removes the top Element from an <var>XmlDoc</var>, and it		This subroutine removes the top <var>Element</var> from an <var>XmlDoc</var>, and it
	makes its children be the “middle siblings” of the left and right siblings		makes its children be the “middle siblings” of the left and right siblings (<var>Comments</var> or <var>PIs</var>)
	of the deleted Element.		of the deleted <var>Element</var>.
	<ul>		<ul>
	<li>The deleted element may not have more than one		<li>The deleted element may not have more than one
	Element child.		<var>Element</var> child.
	<li>The deleted element may not have a Text child.		<li>The deleted element may not have a <var>Text</var> child.
	</ul>		</ul>
	In common usage, the Element child of the deleted Element will become the		In common usage, the <var>Element</var> child of the deleted <var>Element</var> will become the
	new top Element of the <var>XmlDoc</var>.		new top <var>Element</var> of the <var>XmlDoc</var>.

	==Syntax==		==Syntax==

JAL2: /* Syntax terms */

2011-06-03T15:31:31Z

Syntax terms

← Older revision		Revision as of 15:31, 3 June 2011
Line 18:		Line 18:
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>doc</th>		<tr><th>doc</th>
	<td>An <var>XmlDoc</var> object.		<td>An <var>XmlDoc</var> object expression.
	</td></tr></table>		</td></tr></table>

	==Usage notes==		==Usage notes==
	<ul>		<ul>

JAL2: Created page with "{{Template:XmlDoc:DeleteTopElement subtitle}} This subroutine removes the top Element from an `XmlDoc`, and it makes its children be the “middle siblings” o..."

2011-06-03T01:09:32Z

Created page with "{{Template:XmlDoc:DeleteTopElement subtitle}} This subroutine removes the top Element from an <var>XmlDoc</var>, and it makes its children be the “middle siblings” o..."

New page

{{Template:XmlDoc:DeleteTopElement subtitle}}

This subroutine removes the top Element from an <var>XmlDoc</var>, and it
makes its children be the “middle siblings” of the left and right siblings
of the deleted Element.
<ul>
<li>The deleted element may not have more than one
Element child.
<li>The deleted element may not have a Text child.
</ul>
In common usage, the Element child of the deleted Element will become the
new top Element of the <var>XmlDoc</var>.

==Syntax==
{{Template:XmlDoc:DeleteTopElement syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>doc</th>
<td>An <var>XmlDoc</var> object.
</td></tr></table>

==Usage notes==
<ul>
<li><var>DeleteTopElement</var> is a convenient, better-performing alternative to using
<var>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</var> to copy all but the top Element (or in multiple iterations,
removing successive top Elements) from an <var>XmlDoc</var>.

For example, you can use it to remove the SOAP wrappers from an <var>XmlDoc</var>.
If the contents of <code>%xdoc</code> are:
<nowiki><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<data>
...
</data>
</soap:Body>
</soap:Envelope>
</nowiki>
Then the following <var class="product">User Language</var> fragment:
<nowiki>%xdoc:DeleteTopElement
%xdoc:DeleteTopElement
</nowiki>
Results in the following contents of <code>%xdoc</code>:
<nowiki><data>
...
</data>
</nowiki>

<li>The remaining considerations for using <var>DeleteTopElement</var>
concern the occurrence of namespace declarations in the
<var>XmlDoc</var>; there are a few details to explain how they are
manipulated, and to explain how the performance of
<var>DeleteTopElement</var> is affected.

As shown in the “SOAP wrapper removal” example above,
<var>DeleteTopElement</var> will remove from the <var>XmlDoc</var> any namespace
declarations (in this example, <code>xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"</code>)
that '''are not''' referenced after removing the top Element.
Note that a variant on the above example can occur using a
default namespace declaration:
<nowiki><Envelope xmlns"http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<data xmlns="">
...
</data>
</Body>
</Envelope>
</nowiki>
Then the following <var class="product">User Language</var> fragment:
<nowiki>%xdoc:DeleteTopElement
%xdoc:DeleteTopElement
</nowiki>
Results in the following contents of <code>%xdoc</code>:
<nowiki><data xmlns="">
...
</data>
</nowiki>

As seen in this example, the null namespace declaration is not
removed, even though, strictly speaking, it is not needed.

In addition, <var>DeleteTopElement</var> will move to the new top Element
any namespace declarations that '''do''' continue to be
referenced after the top Element deletion:
<nowiki>%n = %d:AddElement('foo', , 'u:uri')
%n:AddElement('bar', , 'u:uri')
%d:Print
%d:DeleteTopElement
Print 'After deletion:'
%d:Print
</nowiki>
The result of the above <var class="product">User Language</var> fragment is:
<nowiki><foo xmlns="u:uri">
<bar/>
</foo>
After deletion:
<bar xmlns="u:uri"/>
</nowiki>

<li>The performance of
<var>DeleteTopElement</var> should always be significantly better than an
approach using <var>AddSubtree</var>,
and in many cases, it is constant, regardless of the
size of the <var>XmlDoc</var>.
For a detailed explanation of when the cost of <var>DeleteTopElement</var>
might vary with the size of the <var>XmlDoc</var>,
there are three reasons that the descendants
of the new top Element need to be recursively visited:
<ol>
<li>Fixing references to moved namespace declaration

As mentioned above, one or more namespace declarations can be moved
from the deleted element to the new top element.
Having done that, any references to the moved namespace must be fixed.
A count is kept to the total references to moved namespace
declarations; when this goes to zero, there is no more need to do this.
So, for example:
<nowiki><p:oldTop xmlns:p="p:uri">
<p:newTop>
<child/>
</p:newTop>
</p:oldTop>
</nowiki>
The <code>p:newTop</code> element needs to have it's namespace reference fixed, but that is the only reference to it, so there is no need to visit <code>child</code>.</li>
<li>Fixing pointers to a deleted namespace declaration

When a namespace declaration is deleted, it may be pointed to by other
namespace declarations (there is a graph of them in the <var>XmlDoc</var>); these
pointers need to be fixed to point to the first non-deleted
declaration following the deleted one.
This is not needed by the descendants of any element that has a
namespace declaration (in the original <var>XmlDoc</var>).
So, for example:
<nowiki><p:oldTop xmlns:p="p:uri">
<newTop>
<q:child xmlns:q="q:uri">
<grandchild/>
</q:child>
</newTop>
</p:oldTop>
</nowiki>
Both <code>newTop</code> and <code>q:child</code> need to have their namespace pointers fixed, but since <code>q:child</code> has a namespace declaration, <code>grandchild</code> doesn't need to be fixed, so it does not need to be visited.</li>
<li>Turning off “ancestor may have non-null default namespace
declaration”

In order to make certain namespace operations faster, there is a
"state" maintained at <var>XmlDoc</var> nodes that permits a non-null default
namespace declaration to occur on an ancestor.
This state is fixed up if <var>DeleteTopElement</var> deletes a non-null
namespace declaration (as happens in the second “SOAP wrapper
removal” example above, the one using a default namespace).
The need to set this state is eliminated in descendants of an Element
that have a default namespace declaration (either null or not).
So, for example:
<nowiki><oldTop xmlns="p:uri">
<newTop>
<q:child xmlns="q:uri">
<grandchild/>
</q:child>
</newTop>
</p:oldTop>
</nowiki>
The state needs to be fixed at <code>newTop</code>, but since <code>q:child</code> has
a default namespace declaration, the state at <code>grandchild</code>
does not need to be fixed up, so it does not need to be visited.
</ol>
</ul>

{{Template:XmlDoc:DeleteTopElement footer}}

← Older revision		Revision as of 21:39, 2 September 2014
Line 165:		Line 165:
	==See also==		==See also==
	<ul>		<ul>
	<li><var>[[AddTopElement(XmlDoc ~~subroutine~~)\|AddTopElement]]</var>		<li><var>[[AddTopElement(XmlDoc function)\|AddTopElement]]</var>

	{{Template:XmlDoc:DeleteTopElement footer}}		{{Template:XmlDoc:DeleteTopElement footer}}

← Older revision		Revision as of 21:33, 19 June 2012
Line 164:		Line 164:

	==See also==		==See also==
			<ul>
			<li><var>[[AddTopElement(XmlDoc subroutine)\|AddTopElement]]</var>

	{{Template:XmlDoc:DeleteTopElement footer}}		{{Template:XmlDoc:DeleteTopElement footer}}