svn commit: r523912 - /db/derby/docs/trunk/src/ref/rrefsqlj61998.dita

[bp...@apache.org]

Author: bpendleton
Date: Thu Mar 29 19:21:40 2007
New Revision: 523912

URL: http://svn.apache.org/viewvc?view=rev&rev=523912
Log:
DERBY-1949: Locate function documentation is confusing

The documentation for the LOCATE function is overly brief and confusing.
It was not clear which CharacterExpression was which in the documentation,
which caused users to be confused about how the function was behaving.
Also, there is a special case situation which arises when the string
which is being searched *for* is an empty string; in this case, the
LOCATE function always returns the value of the third parameter, no matter
what string is passed in the second parameter.

This change updates the documentation to make the usage of the arguments
more explict. It also adds additional examples to the documentation, and
calls out the special case of the empty string both in the text and in
the example.


Modified:
    db/derby/docs/trunk/src/ref/rrefsqlj61998.dita

Modified: db/derby/docs/trunk/src/ref/rrefsqlj61998.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj61998.dita?view=diff&rev=523912&r1=523911&r2=523912
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj61998.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj61998.dita Thu Mar 29 19:21:40 2007
@@ -24,17 +24,51 @@
 <keywords><indexterm>LOCATE function</indexterm></keywords>
 </metadata></prolog>
 <refbody>
-<section> <p>If a specified substring is found within a specified search string,
-LOCATE returns the index at which the substring is found within the search
-string. If the substring is not found, LOCATE returns 0. </p></section>
-<refsyn><title>Syntax</title> <codeblock id="i1195050"><b>LOCATE(<i>CharacterExpression</i>, <i>CharacterExpression</i> [, <i>StartPosition</i>] ) </b
-></codeblock> <p>The second CharacterExpression is the search string and is
-searched from the beginning, unless <i>startPosition</i> is specified, in
-which case the search begins from position there; the index starts with 1.
-It returns 0 if the string is not found.</p> <p>The return type for LOCATE
-is an integer.</p> </refsyn>
-<example> <codeblock><b><ph>-- returns 2</ph>
-VALUES LOCATE('love', 'clover')</b></codeblock> </example>
+    <section>
+        <p>The LOCATE function is used to search for a string within
+            another string. If the desired string is found,
+LOCATE returns the index at which it is found.
+If the desired string is not found, LOCATE returns 0. </p></section>
+<refsyn><title>Syntax</title> <codeblock id="i1195050"><b>LOCATE(<i>CharacterExpression</i>, <i>CharacterExpression</i> [, <i>StartPosition</i>] ) </b>
+        </codeblock>
+        <p>There are two required arguments to the LOCATE function,
+        and a third optional argument.
+        <ul>
+            <li>The first CharacterExpression specifies the string to
+                search <b>for</b>.</li>
+            <li>The second CharacterExpression specifies
+                the string <b>in which</b> to search.</li>
+            <li>The third argument is the startPosition, and specifies
+                the position in the second argument at which the search is
+                to start. If the third argument is not provided, the LOCATE
+                function starts its search at the beginning of the second
+                argument.</li>
+    </ul></p>
+    <p>The return type for LOCATE is an integer. The LOCATE function
+        returns an integer indicating the index position within the
+        second argument at which the first argument was first located. Index
+        positions start with 1.
+        If the first argument is not found in the second argument, LOCATE
+        returns 0. If the first argument is an empty string (''), LOCATE
+        returns the value of the third argument (or 1 if it was not provided),
+        even if the second argument is also an empty string. If a NULL
+        value is passed for either of the CharacterExpression arguments,
+        NULL is returned.</p>
+</refsyn>
+<example>
+    <codeblock><b><ph>-- returns 2, since 'love' is found at index position 2:</ph>
+            VALUES LOCATE('love', 'clover')</b></codeblock>
+    <codeblock><b><ph>-- returns 0, since 'stove' is not found in 'clover':</ph>
+            VALUES LOCATE('stove', 'clover')</b></codeblock>
+    <codeblock><b><ph>-- returns 5 (note the start position is 4):</ph>
+            VALUES LOCATE('iss', 'Mississippi', 4)</b></codeblock>
+    <codeblock><b><ph>-- returns 1, because the empty string is a special case:</ph>
+            VALUES LOCATE('', 'ABC')</b></codeblock>
+    <codeblock><b><ph>-- returns 0, because 'AAA' is not found in '':</ph>
+            VALUES LOCATE('AAA', '')</b></codeblock>
+    <codeblock><b><ph>-- returns 3</ph>
+            VALUES LOCATE('', '', 3)</b></codeblock>
+</example>
 </refbody>
 </reference>