svn commit - mysqldoc@docsrva: r2128 - trunk/refman-5.1

[jon]

Author: jstephens
Date: 2006-05-19 07:39:06 +0200 (Fri, 19 May 2006)
New Revision: 2128

Log:

ExtractValue() doesn't distinguish between a match on an empty element and no 
match at all; example showing how to find out which is the case. (PeterG/Bar)

Fixes Docs Bug #18134.



Modified:
   trunk/refman-5.1/functions.xml

Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml	2006-05-18 20:21:53 UTC (rev 2127)
+++ trunk/refman-5.1/functions.xml	2006-05-19 05:39:06 UTC (rev 2128)
@@ -11496,38 +11496,105 @@
         <remark role="help-syntax-end"/>
 
         <remark role="help-description-begin"/>
+        
+        <para>
+          <literal>ExtractValue()</literal>  takes two string arguments,
+          a fragment of XML markup <replaceable>xml_frag</replaceable>
+          and an XPath expression <replaceable>xpath_expr</replaceable>
+          (also known as a <firstterm>locator</firstterm>); it returns
+          the text (<literal>CDATA</literal>) of the first text node
+          which is a child of the element(s) matched by the XPath
+          expression. It is the equivalent of performing a match using
+          the <replaceable>xpath_expr</replaceable> after appending
+          <literal>/text()</literal>. In other words,
+         
<literal>ExtractValue('&lt;a&gt;&lt;b&gt;Sakila&lt;/b&gt;&lt;/a&gt;',
+            '/a/b')</literal> and
+         
<literal>ExtractValue('&lt;a&gt;&lt;b&gt;Sakila&lt;/b&gt;&lt;/a&gt;',
+            '/a/b/text()')</literal> produce the same result.  
+        </para> 
+        
+        <para>
+          If multiple matches are found, then the content of the first
+          child text node of each matching element is returned
+          (in the order matched) as a single, space-delimited string.
+        </para>
 
         <para>
-          This function takes two string arguments, a fragment of XML
-          markup <replaceable>xml_frag</replaceable> and an XPath
-          expression <replaceable>xpath_expr</replaceable> (also known
-          as a <firstterm>locator</firstterm>), and returns the value
-          matched by <replaceable>xpath_expr</replaceable>. Note that
-          <literal>ExtractValue()</literal> returns only the
-          <literal>CDATA</literal> that is contained directly by the tag
-          matching <replaceable>xpath_expr</replaceable>, and does not
-          return any tags that might be contained within the matching
-          tag, nor any of their content (see the result returned as
-          <literal>val1</literal> in the following example).
+          If no matching text node is found for the (augmented)
+          expression &mdash; for whatever reason, as long as
+          <replaceable>xpth_expr</replaceable> is valid, and
+          <replaceable>xml_frag</replaceable> is well-formed &mdash; an
+          empty string is returned. No distinction is made between a
+          match on an empty element and no match at all. This is by
+          design.
         </para>
 
         <para>
-          If no match for <replaceable>xpath_expr</replaceable> is
-          found, this function returns an empty string.
+          If you need to determine whether no matching element was found
+          in <replaceable>xml_frag</replaceable> or such an element was
+          found but contained no child text nodes, you should test the
+          result of an expression that uses the XPath
+          <literal>count()</literal> function. For example, both of
+          these statements return an empty string, as shown here: 
+        </para>
+        
+<programlisting>
+mysql&gt; <userinput>SELECT
ExtractValue('&lt;a&gt;&lt;b/&gt;&lt;/a&gt;',
'/a/b');</userinput>
++-------------------------------------+
+| ExtractValue('&gt;a&lt;&gt;b/&lt;&gt;/a&lt;', '/a/b') |
++-------------------------------------+
+|                                     |
++-------------------------------------+
+1 row in set (0.00 sec)
 
+mysql&gt; <userinput>SELECT
ExtractValue('&lt;a&gt;&lt;c/&gt;&lt;/a&gt;',
'/a/b');</userinput>
++-------------------------------------+
+| ExtractValue('&lt;a&gt;&lt;c/&gt;&lt;/a&gt;', '/a/b') |
++-------------------------------------+
+|                                     |
++-------------------------------------+
+1 row in set (0.00 sec)
+</programlisting>
+
+        <para>
+          However, you can determine whether there was actually a
+          matching element using the following:
+        </para>
+        
+<programlisting>
+mysql&gt; <userinput>SELECT
ExtractValue('&lt;a&gt;&lt;b/&gt;&lt;/a&gt;',
'count(/a/b)');</userinput>
++-------------------------------------+
+| ExtractValue('&lt;a&gt;&lt;b/&gt;&lt;/a&gt;', 'count(/a/b)') |
++-------------------------------------+
+| 1                                   |
++-------------------------------------+
+1 row in set (0.00 sec)
+
+mysql&gt; <userinput>SELECT
ExtractValue('&lt;a&gt;&lt;c/&gt;&lt;/a&gt;',
'count(/a/b)');</userinput>
++-------------------------------------+
+| ExtractValue('&lt;a&gt;&lt;c/&gt;&lt;/a&gt;', 'count(/a/b)') |
++-------------------------------------+
+| 0                                   |
++-------------------------------------+
+1 row in set (0.01 sec)
+</programlisting>
+        
+        <para>
+          Note that <literal>ExtractValue()</literal> returns only
+          <literal>CDATA</literal>, and does not return any tags that
+          might be contained within a matching tag, nor any of their
+          content (see the result returned as <literal>val1</literal> in
+          the following example).
+        </para>
+
+        <para>
           <remark role="todo">
             [js] Waiting on resolution of Bug #18201:
           </remark>
-
-<!-- 
+          <!-- 
             An empty string is also returned if
             <replaceable>xml_frag</replaceable> is not valid XML.
           -->
-
-          If <replaceable>xpath_expr</replaceable> is not a valid XPath
-          expression, then MySQL returns an error. If multiple matches
-          are found, the contents of all matching elements are returned
-          (in the order matched) as a single, space-delimited string.
         </para>
 
         <remark role="help-description-end"/>