Author: jstephens
Date: 2006-01-13 05:10:07 +0100 (Fri, 13 Jan 2006)
New Revision: 798
Log:
Documenting new XPath functions ExtractValue() and UpdateXML() in 5.1.5
(Thanks, Bar!)
Modified:
trunk/refman-5.1/functions.xml
trunk/refman-common/news-5.1.xml
trunk/refman-common/titles.en.ent
Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml 2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-5.1/functions.xml 2006-01-13 04:10:07 UTC (rev 798)
@@ -13653,7 +13653,265 @@
</itemizedlist>
</section>
+
+ <section id="xml-functions">
+ <title>&title-xml-functions;</title>
+
+ <para>
+ Beginning with MySQL 5.1.5, two functions providing basic XPath
+ (XML Path Language) capabilities are available.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <remark role="help-topic" condition="VALUES"/>
+ <remark role="help-syntax-begin"/>
+
+ <para>
+ <indexterm type="function">
+ <primary>ExtractValue()</primary>
+ </indexterm>
+
+ <literal>ExtractValue(<replaceable>xml_frag</replaceable>,
+ <replaceable>xpath_expr</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ This function takes two string arguments, a fragment of XML
+ markup <replaceable>xml_frag</replaceable> and an XPath
+ expression <replaceable>xpath_expr</replaceable>, and returns
+ the value matched by <replaceable>xpath_expr</replaceable>.
+ If no match for <replaceable>xpath_expr</replaceable> is
+ found, this function returns an empty string.
+ </para>
+
+ <remark role="help-description-end"/>
+
+ <remark role="help-example"/>
+
+<programlisting>
+mysql> <userinput>SELECT</userinput>
+ -> <userinput>ExtractValue('<a>ccc<b>ddd</b></a>', '/a') AS val1,</userinput>
+ -> <userinput>ExtractValue('<a>ccc<b>ddd</b></a>', '/a/b') AS val2,</userinput>
+ -> <userinput>ExtractValue('<a>ccc<b>ddd</b></a>', '//b') AS val3,</userinput>
+ -> <userinput>ExtractValue('<a>ccc<b>ddd</b></a>', '/b') AS val4;</userinput>
+
++------+------+------+------+
+| val1 | val2 | val3 | val4 |
++------+------+------+------+
+| ccc | ddd | ddd | |
++------+------+------+------+
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <remark role="help-topic" condition="VALUES"/>
+
+ <remark role="help-syntax-begin"/>
+
+ <para>
+ <indexterm type="function">
+ <primary>UpdateXML()</primary>
+ </indexterm>
+
+ <literal>UpdateXML(<replaceable>xml_target</replaceable>,
+ <replaceable>xpath_expr</replaceable>,
+ <replaceable>new_xml</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ This function replaces a portion of a given fragment of XML
+ markup <replaceable>xml_target</replaceable> with a new XML
+ fragment <replaceable>new_xml</replaceable> and then returns
+ the changed XML. The portion of
+ <replaceable>xml_target</replaceable> that is replaced
+ matches an XPath expression
+ <replaceable>xpath_expr</replaceable> supplied by the user.
+ If no expression matching
+ <replaceable>xpath_expr</replaceable> is found, then the
+ function returns the original
+ <replaceable>xml_target</replaceable> XML fragment. All
+ three arguments must be strings.
+ </para>
+
+ <remark role="help-description-end"/>
+
+ <remark role="help-example"/>
+
+<programlisting>
+mysql> <userinput>SELECT</userinput>
+ -> <userinput>UpdateXML('<a><b>ccc</b><d></d></a>', '/a', '<e>fff</e>') AS val1,</userinput>
+ -> <userinput>UpdateXML('<a><b>ccc</b><d></d></a>', '/b', '<e>fff</e>') AS val2,</userinput>
+ -> <userinput>UpdateXML('<a><b>ccc</b><d></d></a>', '//b', '<e>fff</e>') AS val3,</userinput>
+ -> <userinput>UpdateXML('<a><b>ccc</b><d></d></a>', '/a/d', '<e>fff</e>') AS val4</userinput>
+ -> <userinput>\G</userinput>
+
+*************************** 1. row ***************************
+val1: <e>fff</e>
+val2: <a><b>ccc</b><d></d></a>
+val3: <a><e>fff</e><d></d></a>
+val4: <a><b>ccc</b><e>fff</e></a>
+</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The XPath syntax supported by these functions is currently
+ subject to the following limitations:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Nodeset-to-nodeset comparison (such as
+ <literal>'/a/b[@c=@d]'</literal>) is not supported. Only
+ '/a/b[@c=<replaceable>"const"</replaceable>]' is currently
+ possible.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The following XPath functions are not supported:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>id()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>lang()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>last()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>local-name()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>name()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>namespace-uri()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>normalize-space()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>starts-with()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>string()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>substring-after()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>substring-before()</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>translate()</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ The following axes are not supported:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>following-sibling</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>following</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>preceding-sibling</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>preceding</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ We continue to develop and improve these and other aspects of
+ XML/XPath functionality in MySQL 5.1 and onwards.
+ </para>
+
+ <para>
+ A discussion in depth of XPath syntax and usage are beyond the
+ scope of this Manual. Please see the
+ <ulink url="http://www.w3.org/TR/xpath">XML Path Language
+ (XPath) 1.0 standard</ulink> for definitive information. A
+ useful resource for those new to XPath or wishing a refresher in
+ the basics is the
+ <ulink url="http://www.zvon.org/xxl/XPathTutorial/">Zvon.org
+ XPath Tutorial</ulink>, which is available in several
+ languages.
+ </para>
+ </section>
+
+
</section>
<section id="group-by-functions-and-modifiers">
Modified: trunk/refman-common/news-5.1.xml
===================================================================
--- trunk/refman-common/news-5.1.xml 2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-common/news-5.1.xml 2006-01-13 04:10:07 UTC (rev 798)
@@ -99,6 +99,19 @@
</para>
<itemizedlist>
+
+ <listitem>
+ <para>
+ Added the XML functions <literal>ExtractValue()</literal> and
+ <literal>UpdateXML()</literal>.
+ <literal>ExtractValue()</literal> returns the content of a
+ fragment of XML matching a given XPath expression.
+ <literal>UpdateXML()</literal> replaces the element selected
+ from a fragment of XML by an XPath expression supplied by the
+ user with a second XML fragment (also user-supplied), and
+ returns the modified XML. See <xref linkend="xml-functions"/>.
+ </para>
+ </listitem>
<listitem>
<para>
Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent 2006-01-13 04:00:46 UTC (rev 797)
+++ trunk/refman-common/titles.en.ent 2006-01-13 04:10:07 UTC (rev 798)
@@ -1715,6 +1715,7 @@
<!ENTITY title-xa-restrictions "Restrictions on XA Transactions">
<!ENTITY title-xa-statements "XA Transaction SQL Syntax">
<!ENTITY title-xa-states "XA Transaction States">
+<!ENTITY title-xml-functions "XML Functions">
<!ENTITY title-y2k-issues "Y2K Issues and Date Types">
<!ENTITY title-year "The <literal>YEAR</literal> Type">
<!ENTITY title-year-2000-compliance "Year 2000 Compliance">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r798 - in trunk: refman-5.1 refman-common | jon | 13 Jan |
