Author: paul
Date: 2007-12-05 03:31:04 +0100 (Wed, 05 Dec 2007)
New Revision: 9114
Log:
r27756@frost: paul | 2007-12-04 20:27:24 -0600
Split pairs of functions so they can be given separate IDs.
Modified:
trunk/dynamic-docs/opsfunctions/opfunctions.xml
trunk/refman-4.1/functions-core.xml
trunk/refman-5.0/functions-core.xml
trunk/refman-5.1/functions-core.xml
trunk/refman-6.0/functions-core.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:33765
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:27755
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:22582
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:33765
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:27756
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:22582
Modified: trunk/dynamic-docs/opsfunctions/opfunctions.xml
===================================================================
--- trunk/dynamic-docs/opsfunctions/opfunctions.xml 2007-12-05 02:30:44 UTC (rev 9113)
+++ trunk/dynamic-docs/opsfunctions/opfunctions.xml 2007-12-05 02:31:04 UTC (rev 9114)
Changed blocks: 2, Lines Added: 57, Lines Deleted: 2; 3318 bytes
@@ -173,9 +173,26 @@
</versions>
</opfunction>
+ <opfunction type="function" id="ceil" class="numeric-mathematical">
+ <display>CEIL()</display>
+ <description lang="en">Return the smallest integer value not less than
+ the argument</description>
+ <arguments>
+ <format><![CDATA[<replaceable>X</replaceable>]]></format>
+ <argument seq="1" name="expr" type="numeric"></argument>
+ </arguments>
+ <return type="numeric"/>
+ <error type="return"/>
+ <versions>
+ <manual version="4.1"/>
+ <manual version="5.0"/>
+ <manual version="5.1"/>
+ <manual version="6.0"/>
+ </versions>
+ </opfunction>
+
<opfunction type="function" id="ceiling" class="numeric-mathematical">
<display>CEILING()</display>
- <display>CEIL()</display>
<description lang="en">Return the smallest integer value not less than
the argument</description>
<arguments>
@@ -3499,9 +3516,47 @@
</versions>
</opfunction>
+ <opfunction type="function" id="substr" class="string">
+ <display>SUBSTR()</display>
+ <description lang="en">Return the substring as specified</description>
+ <arguments>
+ <format><![CDATA[<replaceable>str</replaceable>,<replaceable>pos</replaceable>]]></format>
+ <argument seq="1" name="expr" type="string"></argument>
+ <argument seq="2" name="expr" type="numeric">Start position</argument>
+ </arguments>
+ <arguments>
+ <format><![CDATA[<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable>]]></format>
+ <argument seq="1" name="expr" type="string"></argument>
+ <argument seq="2" name="expr" type="string">Start position</argument>
+ </arguments>
+ <arguments>
+ <format><![CDATA[<replaceable>str</replaceable>,
+ <replaceable>pos</replaceable>,<replaceable>len</replaceable>]]></format>
+ <argument seq="1" name="expr" type="string"></argument>
+ <argument seq="2" name="expr" type="string">Start position</argument>
+ <argument seq="3" name="expr" type="string">Number of characters</argument>
+ </arguments>
+ <arguments>
+ <format><![CDATA[<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable> FOR
+ <replaceable>len</replaceable>]]></format>
+ <argument seq="1" name="expr" type="string"></argument>
+ <argument seq="2" name="expr" type="numeric">Start position</argument>
+ <argument seq="3" name="expr" type="numeric">Number of characters</argument>
+ </arguments>
+ <return type="string"/>
+ <error type="return"/>
+ <versions>
+ <manual version="4.1"/>
+ <manual version="5.0"/>
+ <manual version="5.1"/>
+ <manual version="6.0"/>
+ </versions>
+ </opfunction>
+
<opfunction type="function" id="substring" class="string">
<display>SUBSTRING()</display>
- <display>SUBSTR()</display>
<description lang="en">Return the substring as specified</description>
<arguments>
<format><![CDATA[<replaceable>str</replaceable>,<replaceable>pos</replaceable>]]></format>
Modified: trunk/refman-4.1/functions-core.xml
===================================================================
--- trunk/refman-4.1/functions-core.xml 2007-12-05 02:30:44 UTC (rev 9113)
+++ trunk/refman-4.1/functions-core.xml 2007-12-05 02:31:04 UTC (rev 9114)
Changed blocks: 63, Lines Added: 253, Lines Deleted: 170; 35603 bytes
@@ -1804,11 +1804,12 @@
If <replaceable>expr1</replaceable> is <literal>TRUE</literal>
(<literal><replaceable>expr1</replaceable> <>
0</literal> and <literal><replaceable>expr1</replaceable>
- <> NULL</literal>) then <function role="sql">IF()</function> returns
+ <> NULL</literal>) then
+ <function role="sql">IF()</function> returns
<replaceable>expr2</replaceable>; otherwise it returns
- <replaceable>expr3</replaceable>. <function role="sql">IF()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr3</replaceable>.
+ <function role="sql">IF()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -1857,9 +1858,10 @@
</para>
<para>
- The default return type of <function role="sql">IF()</function> (which may
- matter when it is stored into a temporary table) is calculated
- in MySQL 3.23 as follows:
+ The default return type of
+ <function role="sql">IF()</function> (which may matter when it
+ is stored into a temporary table) is calculated in MySQL 3.23
+ as follows:
</para>
<informaltable>
@@ -1922,11 +1924,12 @@
<para>
If <replaceable>expr1</replaceable> is not
- <literal>NULL</literal>, <function role="sql">IFNULL()</function> returns
+ <literal>NULL</literal>,
+ <function role="sql">IFNULL()</function> returns
<replaceable>expr1</replaceable>; otherwise it returns
- <replaceable>expr2</replaceable>. <function role="sql">IFNULL()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr2</replaceable>.
+ <function role="sql">IFNULL()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -2017,7 +2020,8 @@
</para>
<para>
- <function role="sql">NULLIF()</function> was added in MySQL 3.23.15.
+ <function role="sql">NULLIF()</function> was added in MySQL
+ 3.23.15.
</para>
</listitem>
@@ -2088,7 +2092,8 @@
<literal>0</literal> if <replaceable>str</replaceable> is the
empty string. Returns <literal>NULL</literal> if
<replaceable>str</replaceable> is <literal>NULL</literal>.
- <function role="sql">ASCII()</function> works for 8-bit characters.
+ <function role="sql">ASCII()</function> works for 8-bit
+ characters.
</para>
<remark role="help-description-end"/>
@@ -2201,10 +2206,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">CHAR()</function> interprets each argument
- <replaceable>N</replaceable> as an integer and returns a
- string consisting of the characters given by the code values
- of those integers. <literal>NULL</literal> values are skipped.
+ <function role="sql">CHAR()</function> interprets each
+ argument <replaceable>N</replaceable> as an integer and
+ returns a string consisting of the characters given by the
+ code values of those integers. <literal>NULL</literal> values
+ are skipped.
</para>
<remark role="help-description-end"/>
@@ -2221,8 +2227,8 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">CHAR()</function> returns a string in the connection
- character set. As of MySQL 4.1.16, the optional
+ <function role="sql">CHAR()</function> returns a string in the
+ connection character set. As of MySQL 4.1.16, the optional
<literal>USING</literal> clause may be used to produce a
string in a given character set:
</para>
@@ -2261,9 +2267,9 @@
<replaceable>str</replaceable>, measured in characters. A
multi-byte character counts as a single character. This means
that for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -2505,18 +2511,18 @@
</para>
<para>
- If all arguments to <function role="sql">FIELD()</function> are strings,
- all arguments are compared as strings. If all arguments are
- numbers, they are compared as numbers. Otherwise, the
- arguments are compared as double.
+ If all arguments to <function role="sql">FIELD()</function>
+ are strings, all arguments are compared as strings. If all
+ arguments are numbers, they are compared as numbers.
+ Otherwise, the arguments are compared as double.
</para>
<para>
If <replaceable>str</replaceable> is <literal>NULL</literal>,
the return value is <literal>0</literal> because
<literal>NULL</literal> fails equality comparison with any
- value. <function role="sql">FIELD()</function> is the complement of
- <function role="sql">ELT()</function>.
+ value. <function role="sql">FIELD()</function> is the
+ complement of <function role="sql">ELT()</function>.
</para>
<remark role="help-description-end"/>
@@ -2741,8 +2747,8 @@
Returns the position of the first occurrence of substring
<replaceable>substr</replaceable> in string
<replaceable>str</replaceable>. This is the same as the
- two-argument form of <function role="sql">LOCATE()</function>, except that
- the order of the arguments is reversed.
+ two-argument form of <function role="sql">LOCATE()</function>,
+ except that the order of the arguments is reversed.
</para>
<remark role="help-description-end"/>
@@ -2842,9 +2848,9 @@
<replaceable>str</replaceable>, measured in bytes. A
multi-byte character counts as multiple bytes. This means that
for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -3204,8 +3210,8 @@
<para>
If the leftmost character is not a multi-byte character,
- <function role="sql">ORD()</function> returns the same value as the
- <function role="sql">ASCII()</function> function.
+ <function role="sql">ORD()</function> returns the same value
+ as the <function role="sql">ASCII()</function> function.
</para>
<remark role="help-description-end"/>
@@ -3271,8 +3277,8 @@
<literal>NUL</literal>, and Control-Z preceded by a backslash.
If the argument is <literal>NULL</literal>, the return value
is the word <quote>NULL</quote> without enclosing single
- quotes. The <function role="sql">QUOTE()</function> function was added in
- MySQL 4.0.3.
+ quotes. The <function role="sql">QUOTE()</function> function
+ was added in MySQL 4.0.3.
</para>
<remark role="help-description-end"/>
@@ -3345,8 +3351,9 @@
Returns the string <replaceable>str</replaceable> with all
occurrences of the string <replaceable>from_str</replaceable>
replaced by the string <replaceable>to_str</replaceable>.
- <function role="sql">REPLACE()</function> performs a case-sensitive match
- when searching for <replaceable>from_str</replaceable>.
+ <function role="sql">REPLACE()</function> performs a
+ case-sensitive match when searching for
+ <replaceable>from_str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -3536,11 +3543,11 @@
soundex strings. A standard soundex string is four characters
long, but the <function role="sql">SOUNDEX()</function>
function returns an arbitrarily long string. You can use
- <function role="sql">SUBSTRING()</function> on the result to get a standard
- soundex string. All non-alphabetic characters in
- <replaceable>str</replaceable> are ignored. All international
- alphabetic characters outside the A-Z range are treated as
- vowels.
+ <function role="sql">SUBSTRING()</function> on the result to
+ get a standard soundex string. All non-alphabetic characters
+ in <replaceable>str</replaceable> are ignored. All
+ international alphabetic characters outside the A-Z range are
+ treated as vowels.
</para>
<important>
@@ -3666,9 +3673,10 @@
hexadecimal digits: <literal>'0'</literal> ..
<literal>'9'</literal>, <literal>'A'</literal> ..
<literal>'F'</literal>, <literal>'a'</literal> ..
- <literal>'f'</literal>. If <function role="sql">UNHEX()</function>
- encounters any non-hexadecimal digits in the argument, it
- returns <literal>NULL</literal>:
+ <literal>'f'</literal>. If
+ <function role="sql">UNHEX()</function> encounters any
+ non-hexadecimal digits in the argument, it returns
+ <literal>NULL</literal>:
</para>
<programlisting>
@@ -3682,27 +3690,59 @@
<para>
A <literal>NULL</literal> result can occur if the argument to
- <function role="sql">UNHEX()</function> is a <literal>BINARY</literal>
- column, because values are padded with 0x00 bytes when stored
- but those bytes are not stripped on retrieval. For example
- <literal>'aa'</literal> is stored into a
- <literal>CHAR(3)</literal> column as
+ <function role="sql">UNHEX()</function> is a
+ <literal>BINARY</literal> column, because values are padded
+ with 0x00 bytes when stored but those bytes are not stripped
+ on retrieval. For example <literal>'aa'</literal> is stored
+ into a <literal>CHAR(3)</literal> column as
<literal>'aa '</literal> and retrieved as
<literal>'aa'</literal> (with the trailing pad space
- stripped), so <function role="sql">UNHEX()</function> for the column value
- returns <literal>'A'</literal>. By contrast
+ stripped), so <function role="sql">UNHEX()</function> for the
+ column value returns <literal>'A'</literal>. By contrast
<literal>'aa'</literal> is stored into a
<literal>BINARY(3)</literal> column as
<literal>'aa\0'</literal> and retrieved as
<literal>'aa\0'</literal> (with the trailing pad
<literal>0x00</literal> byte not stripped).
<literal>'\0'</literal> is not a legal hexadecimal digit, so
- <function role="sql">UNHEX()</function> for the column value returns
- <literal>NULL</literal>.
+ <function role="sql">UNHEX()</function> for the column value
+ returns <literal>NULL</literal>.
</para>
</listitem>
<listitem>
+ <remark role="help-topic" condition="SUBSTR"/>
+
+ <remark role="help-syntax-begin"/>
+
+ <para id="function_substr">
+ <indexterm>
+ <primary>SUBSTR()</primary>
+ </indexterm>
+
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable> FOR
+ <replaceable>len</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">SUBSTR()</function> is a synonym for
+ <function role="sql">SUBSTRING()</function>. It was added in
+ MySQL 4.1.1.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
<remark role="help-topic" condition="SUBSTRING"/>
<remark role="help-syntax-begin"/>
@@ -3712,10 +3752,6 @@
<primary>SUBSTRING()</primary>
</indexterm>
- <indexterm>
- <primary>SUBSTR()</primary>
- </indexterm>
-
<literal>SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
<literal>SUBSTRING(<replaceable>str</replaceable> FROM
<replaceable>pos</replaceable>)</literal>,
@@ -3747,9 +3783,10 @@
</para>
<para>
- For all forms of <function role="sql">SUBSTRING()</function>, the position
- of the first character in the string from which the substring
- is to be extracted is reckoned as <literal>1</literal>.
+ For all forms of <function role="sql">SUBSTRING()</function>,
+ the position of the first character in the string from which
+ the substring is to be extracted is reckoned as
+ <literal>1</literal>.
</para>
<remark role="help-description-end"/>
@@ -3779,11 +3816,6 @@
If <replaceable>len</replaceable> is less than 1, the result
is the empty string.
</para>
-
- <para>
- <function role="sql">SUBSTR()</function> is a synonym for
- <function role="sql">SUBSTRING()</function>, added in MySQL 4.1.1.
- </para>
</listitem>
<listitem>
@@ -3955,7 +3987,8 @@
</programlisting>
<para>
- <function role="sql">UNHEX()</function> was added in MySQL 4.1.2.
+ <function role="sql">UNHEX()</function> was added in MySQL
+ 4.1.2.
</para>
</listitem>
@@ -4454,10 +4487,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">STRCMP()</function> returns <literal>0</literal> if
- the strings are the same, <literal>-1</literal> if the first
- argument is smaller than the second according to the current
- sort order, and <literal>1</literal> otherwise.
+ <function role="sql">STRCMP()</function> returns
+ <literal>0</literal> if the strings are the same,
+ <literal>-1</literal> if the first argument is smaller than
+ the second according to the current sort order, and
+ <literal>1</literal> otherwise.
</para>
<remark role="help-description-end"/>
@@ -4474,12 +4508,12 @@
</programlisting>
<para>
- As of MySQL 4.0, <function role="sql">STRCMP()</function> uses the
- current character set when performing comparisons. This
- makes the default comparison behavior case insensitive
+ As of MySQL 4.0, <function role="sql">STRCMP()</function>
+ uses the current character set when performing comparisons.
+ This makes the default comparison behavior case insensitive
unless one or both of the operands are binary strings.
- Before MySQL 4.0, <function role="sql">STRCMP()</function> is case
- sensitive.
+ Before MySQL 4.0, <function role="sql">STRCMP()</function>
+ is case sensitive.
</para>
</listitem>
@@ -5595,8 +5629,9 @@
<remark role="help-description-begin"/>
<para>
- Integer division. Similar to <function role="sql">FLOOR()</function>, but
- is safe with <literal>BIGINT</literal> values.
+ Integer division. Similar to
+ <function role="sql">FLOOR()</function>, but is safe with
+ <literal>BIGINT</literal> values.
</para>
<remark role="help-description-end"/>
@@ -5864,7 +5899,7 @@
</listitem>
<listitem>
- <remark role="help-topic" condition="CEILING"/>
+ <remark role="help-topic" condition="CEIL"/>
<remark role="help-keywords">
CEIL
@@ -5872,13 +5907,42 @@
<remark role="help-syntax-begin"/>
+ <para id="function_ceil">
+ <indexterm>
+ <primary>CEIL()</primary>
+ </indexterm>
+
+ <function role="sql">CEIL(<replaceable>X</replaceable>)</function>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">CEIL()</function> is a synonym for
+ <function role="sql">CEILING()</function>. It was added in
+ MySQL 4.0.6.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
+ <remark role="help-topic" condition="CEILING"/>
+
+ <remark role="help-keywords">
+ CEILING
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
<para id="function_ceiling">
<indexterm>
<primary>CEILING()</primary>
</indexterm>
- <literal>CEILING(<replaceable>X</replaceable>)</literal>,
- <literal>CEIL(<replaceable>X</replaceable>)</literal>
+ <function role="sql">CEILING(<replaceable>X</replaceable>)</function>
</para>
<remark role="help-syntax-end"/>
@@ -5897,7 +5961,7 @@
<programlisting>
mysql> <userinput>SELECT CEILING(1.23);</userinput>
-> 2
-mysql> <userinput>SELECT CEIL(-1.23);</userinput>
+mysql> <userinput>SELECT CEILING(-1.23);</userinput>
-> -1
</programlisting>
@@ -5905,11 +5969,6 @@
Note that the return value is converted to a
<literal>BIGINT</literal>.
</para>
-
- <para>
- The <function role="sql">CEIL()</function> alias was added in MySQL
- 4.0.6.
- </para>
</listitem>
<listitem>
@@ -5944,7 +6003,8 @@
is a negative number, <replaceable>N</replaceable> is
regarded as a signed number. Otherwise,
<replaceable>N</replaceable> is treated as unsigned.
- <function role="sql">CONV()</function> works with 64-bit precision.
+ <function role="sql">CONV()</function> works with 64-bit
+ precision.
</para>
<remark role="help-description-end"/>
@@ -6724,11 +6784,12 @@
</programlisting>
<para>
- You cannot use a column with <function role="sql">RAND()</function>
- values in an <literal>ORDER BY</literal> clause, because
- <literal>ORDER BY</literal> would evaluate the column
- multiple times. However, as of MySQL 3.23, you can retrieve
- rows in random order like this:
+ You cannot use a column with
+ <function role="sql">RAND()</function> values in an
+ <literal>ORDER BY</literal> clause, because <literal>ORDER
+ BY</literal> would evaluate the column multiple times.
+ However, as of MySQL 3.23, you can retrieve rows in random
+ order like this:
</para>
<programlisting>
@@ -6752,10 +6813,11 @@
</para>
<para>
- <function role="sql">RAND()</function> is not meant to be a perfect
- random generator, but instead is a fast way to generate
- <foreignphrase>ad hoc</foreignphrase> random numbers which
- is portable between platforms for the same MySQL version.
+ <function role="sql">RAND()</function> is not meant to be a
+ perfect random generator, but instead is a fast way to
+ generate <foreignphrase>ad hoc</foreignphrase> random
+ numbers which is portable between platforms for the same
+ MySQL version.
</para>
</listitem>
@@ -6814,14 +6876,14 @@
</para>
<para>
- The behavior of <function role="sql">ROUND()</function> when the argument
- is halfway between two integers depends on the C library
- implementation. Different implementations round to the
- nearest even number, always up, always down, or always
+ The behavior of <function role="sql">ROUND()</function> when
+ the argument is halfway between two integers depends on the
+ C library implementation. Different implementations round to
+ the nearest even number, always up, always down, or always
toward zero. If you need one kind of rounding, you should
use a well-defined function such as
- <function role="sql">TRUNCATE()</function> or <function role="sql">FLOOR()</function>
- instead.
+ <function role="sql">TRUNCATE()</function> or
+ <function role="sql">FLOOR()</function> instead.
</para>
</listitem>
@@ -7077,9 +7139,10 @@
Functions that return the current date or time each are evaluated
only once per query at the start of query execution. This means
that multiple references to a function such as
- <function role="sql">NOW()</function> within a single query always produce the
- same result. This principle also applies to
- <function role="sql">CURDATE()</function>, <function role="sql">CURTIME()</function>,
+ <function role="sql">NOW()</function> within a single query always
+ produce the same result. This principle also applies to
+ <function role="sql">CURDATE()</function>,
+ <function role="sql">CURTIME()</function>,
<literal>UTC_DATE()</literal>, <literal>UTC_TIME()</literal>,
<literal>UTC_TIMESTAMP()</literal>, and to any of their synonyms.
</para>
@@ -7147,13 +7210,13 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">ADDDATE()</function> is a synonym for
- <literal>DATE_ADD()</literal>. The related function
- <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">ADDDATE()</function> is
+ a synonym for <literal>DATE_ADD()</literal>. The related
+ function <function role="sql">SUBDATE()</function> is a
+ synonym for <literal>DATE_SUB()</literal>. For information on
+ the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -7223,7 +7286,8 @@
</programlisting>
<para>
- <function role="sql">ADDTIME()</function> was added in MySQL 4.1.1.
+ <function role="sql">ADDTIME()</function> was added in MySQL
+ 4.1.1.
</para>
</listitem>
@@ -7485,7 +7549,8 @@
</programlisting>
<para>
- <function role="sql">DATE()</function> is available as of MySQL 4.1.1.
+ <function role="sql">DATE()</function> is available as of
+ MySQL 4.1.1.
</para>
</listitem>
@@ -7532,7 +7597,8 @@
</programlisting>
<para>
- <function role="sql">DATEDIFF()</function> was added in MySQL 4.1.1.
+ <function role="sql">DATEDIFF()</function> was added in MySQL
+ 4.1.1.
</para>
</listitem>
@@ -8146,8 +8212,8 @@
<para>
<function role="sql">DAY()</function> is a synonym for
- <function role="sql">DAYOFMONTH()</function>. It is available as of MySQL
- 4.1.1.
+ <function role="sql">DAYOFMONTH()</function>. It is available
+ as of MySQL 4.1.1.
</para>
<remark role="help-description-end"/>
@@ -8307,8 +8373,9 @@
<remark role="help-description-begin"/>
<para>
- The <function role="sql">EXTRACT()</function> function uses the same kinds
- of unit specifiers as <literal>DATE_ADD()</literal> or
+ The <function role="sql">EXTRACT()</function> function uses
+ the same kinds of unit specifiers as
+ <literal>DATE_ADD()</literal> or
<literal>DATE_SUB()</literal>, but extracts parts from the
date rather than performing date arithmetic.
</para>
@@ -8330,7 +8397,8 @@
</programlisting>
<para>
- <function role="sql">EXTRACT()</function> was added in MySQL 3.23.0.
+ <function role="sql">EXTRACT()</function> was added in MySQL
+ 3.23.0.
</para>
</listitem>
@@ -8687,7 +8755,8 @@
<primary>LOCALTIME</primary>
</indexterm>
- <literal>LOCALTIME</literal>, <function role="sql">LOCALTIME()</function>
+ <literal>LOCALTIME</literal>,
+ <function role="sql">LOCALTIME()</function>
</para>
<remark role="help-syntax-end"/>
@@ -8723,8 +8792,8 @@
<para>
<literal>LOCALTIMESTAMP</literal> and
- <function role="sql">LOCALTIMESTAMP()</function> are synonyms for
- <function role="sql">NOW()</function>.
+ <function role="sql">LOCALTIMESTAMP()</function> are synonyms
+ for <function role="sql">NOW()</function>.
</para>
<remark role="help-description-end"/>
@@ -8771,7 +8840,8 @@
</programlisting>
<para>
- <function role="sql">MAKEDATE()</function> is available as of MySQL 4.1.1.
+ <function role="sql">MAKEDATE()</function> is available as of
+ MySQL 4.1.1.
</para>
</listitem>
@@ -8809,7 +8879,8 @@
</programlisting>
<para>
- <function role="sql">MAKETIME()</function> is available as of MySQL 4.1.1.
+ <function role="sql">MAKETIME()</function> is available as of
+ MySQL 4.1.1.
</para>
</listitem>
@@ -8848,8 +8919,8 @@
</programlisting>
<para>
- <function role="sql">MICROSECOND()</function> is available as of MySQL
- 4.1.1.
+ <function role="sql">MICROSECOND()</function> is available as
+ of MySQL 4.1.1.
</para>
</listitem>
@@ -9305,11 +9376,11 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">SUBDATE()</function> is
+ a synonym for <literal>DATE_SUB()</literal>. For information
+ on the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -9377,7 +9448,8 @@
</programlisting>
<para>
- <function role="sql">SUBTIME()</function> was added in MySQL 4.1.1.
+ <function role="sql">SUBTIME()</function> was added in MySQL
+ 4.1.1.
</para>
</listitem>
@@ -9448,7 +9520,8 @@
</programlisting>
<para>
- <function role="sql">TIME()</function> is available as of MySQL 4.1.1.
+ <function role="sql">TIME()</function> is available as of
+ MySQL 4.1.1.
</para>
</listitem>
@@ -9496,7 +9569,8 @@
</programlisting>
<para>
- <function role="sql">TIMEDIFF()</function> was added in MySQL 4.1.1.
+ <function role="sql">TIMEDIFF()</function> was added in MySQL
+ 4.1.1.
</para>
</listitem>
@@ -9543,7 +9617,8 @@
</programlisting>
<para>
- <function role="sql">TIMESTAMP()</function> is available as of MySQL 4.1.1.
+ <function role="sql">TIMESTAMP()</function> is available as of
+ MySQL 4.1.1.
</para>
</listitem>
@@ -9928,10 +10003,10 @@
<para>
This function returns the week number for
<replaceable>date</replaceable>. The two-argument form of
- <function role="sql">WEEK()</function> allows you to specify whether the
- week starts on Sunday or Monday and whether the return value
- should be in the range from <literal>0</literal> to
- <literal>53</literal> or from <literal>1</literal> to
+ <function role="sql">WEEK()</function> allows you to specify
+ whether the week starts on Sunday or Monday and whether the
+ return value should be in the range from <literal>0</literal>
+ to <literal>53</literal> or from <literal>1</literal> to
<literal>53</literal>. If the <replaceable>mode</replaceable>
argument is omitted, the value of the
<literal>default_week_format</literal> system variable is used
@@ -10040,8 +10115,8 @@
Note: In MySQL 4.0,
<literal>WEEK(<replaceable>date</replaceable>,0)</literal> was
changed to match the calendar in the USA. Before that,
- <function role="sql">WEEK()</function> was calculated incorrectly for dates
- in the USA. (In effect,
+ <function role="sql">WEEK()</function> was calculated
+ incorrectly for dates in the USA. (In effect,
<literal>WEEK(<replaceable>date</replaceable>)</literal> and
<literal>WEEK(<replaceable>date</replaceable>,0)</literal>
were incorrect for all cases.)
@@ -10062,13 +10137,14 @@
<para>
One might argue that MySQL should return <literal>52</literal>
- for the <function role="sql">WEEK()</function> function, because the given
- date actually occurs in the 52nd week of 1999. We decided to
- return <literal>0</literal> instead because we want the
- function to return <quote>the week number in the given
- year.</quote> This makes use of the <function role="sql">WEEK()</function>
- function reliable when combined with other functions that
- extract a date part from a date.
+ for the <function role="sql">WEEK()</function> function,
+ because the given date actually occurs in the 52nd week of
+ 1999. We decided to return <literal>0</literal> instead
+ because we want the function to return <quote>the week number
+ in the given year.</quote> This makes use of the
+ <function role="sql">WEEK()</function> function reliable when
+ combined with other functions that extract a date part from a
+ date.
</para>
<para>
@@ -10085,7 +10161,8 @@
</programlisting>
<para>
- Alternatively, use the <function role="sql">YEARWEEK()</function> function:
+ Alternatively, use the
+ <function role="sql">YEARWEEK()</function> function:
</para>
<programlisting>
@@ -10151,8 +10228,8 @@
<para>
Returns the calendar week of the date as a number in the range
from <literal>1</literal> to <literal>53</literal>.
- <function role="sql">WEEKOFYEAR()</function> is a compatibility function
- that is equivalent to
+ <function role="sql">WEEKOFYEAR()</function> is a
+ compatibility function that is equivalent to
<literal>WEEK(<replaceable>date</replaceable>,3)</literal>.
</para>
@@ -10166,8 +10243,8 @@
</programlisting>
<para>
- <function role="sql">WEEKOFYEAR()</function> is available as of MySQL
- 4.1.1.
+ <function role="sql">WEEKOFYEAR()</function> is available as
+ of MySQL 4.1.1.
</para>
</listitem>
@@ -10226,9 +10303,9 @@
Returns year and week for a date. The
<replaceable>mode</replaceable> argument works exactly like
the <replaceable>mode</replaceable> argument to
- <function role="sql">WEEK()</function>. The year in the result may be
- different from the year in the date argument for the first and
- the last week of the year.
+ <function role="sql">WEEK()</function>. The year in the result
+ may be different from the year in the date argument for the
+ first and the last week of the year.
</para>
<remark role="help-description-end"/>
@@ -10245,12 +10322,13 @@
<function role="sql">WEEK()</function> function would return
(<literal>0</literal>) for optional arguments
<literal>0</literal> or <literal>1</literal>, as
- <function role="sql">WEEK()</function> then returns the week in the context
- of the given year.
+ <function role="sql">WEEK()</function> then returns the week
+ in the context of the given year.
</para>
<para>
- <function role="sql">YEARWEEK()</function> was added in MySQL 3.23.8.
+ <function role="sql">YEARWEEK()</function> was added in MySQL
+ 3.23.8.
</para>
</listitem>
@@ -12668,9 +12746,10 @@
<listitem>
<para>
- Before MySQL 4.1.1, use the <function role="sql">UPPER()</function>
- function to convert the binary string to uppercase before
- performing the comparison:
+ Before MySQL 4.1.1, use the
+ <function role="sql">UPPER()</function> function to convert
+ the binary string to uppercase before performing the
+ comparison:
</para>
<programlisting>
@@ -14234,7 +14313,8 @@
</programlisting>
<para>
- <function role="sql">CHARSET()</function> was added in MySQL 4.1.0.
+ <function role="sql">CHARSET()</function> was added in MySQL
+ 4.1.0.
</para>
</listitem>
@@ -14367,7 +14447,8 @@
</informaltable>
<para>
- <function role="sql">COERCIBILITY()</function> was added in MySQL 4.1.1.
+ <function role="sql">COERCIBILITY()</function> was added in
+ MySQL 4.1.1.
</para>
</listitem>
@@ -14404,7 +14485,8 @@
</programlisting>
<para>
- <function role="sql">COLLATION()</function> was added in MySQL 4.1.0.
+ <function role="sql">COLLATION()</function> was added in
+ MySQL 4.1.0.
</para>
</listitem>
@@ -15167,7 +15249,8 @@
</programlisting>
<para>
- <function role="sql">DEFAULT()</function> was added in MySQL 4.1.0.
+ <function role="sql">DEFAULT()</function> was added in MySQL
+ 4.1.0.
</para>
</listitem>
Modified: trunk/refman-5.0/functions-core.xml
===================================================================
--- trunk/refman-5.0/functions-core.xml 2007-12-05 02:30:44 UTC (rev 9113)
+++ trunk/refman-5.0/functions-core.xml 2007-12-05 02:31:04 UTC (rev 9114)
Changed blocks: 55, Lines Added: 267, Lines Deleted: 194; 39185 bytes
@@ -1914,11 +1914,12 @@
If <replaceable>expr1</replaceable> is <literal>TRUE</literal>
(<literal><replaceable>expr1</replaceable> <>
0</literal> and <literal><replaceable>expr1</replaceable>
- <> NULL</literal>) then <function role="sql">IF()</function> returns
+ <> NULL</literal>) then
+ <function role="sql">IF()</function> returns
<replaceable>expr2</replaceable>; otherwise it returns
- <replaceable>expr3</replaceable>. <function role="sql">IF()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr3</replaceable>.
+ <function role="sql">IF()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -1938,8 +1939,8 @@
If only one of <replaceable>expr2</replaceable> or
<replaceable>expr3</replaceable> is explicitly
<literal>NULL</literal>, the result type of the
- <function role="sql">IF()</function> function is the type of the
- non-<literal>NULL</literal> expression.
+ <function role="sql">IF()</function> function is the type of
+ the non-<literal>NULL</literal> expression.
</para>
<para>
@@ -1966,9 +1967,9 @@
</para>
<para>
- The default return type of <function role="sql">IF()</function> (which may
- matter when it is stored into a temporary table) is calculated
- as follows:
+ The default return type of
+ <function role="sql">IF()</function> (which may matter when it
+ is stored into a temporary table) is calculated as follows:
</para>
<informaltable>
@@ -2009,8 +2010,9 @@
<para>
There is also an <literal>IF</literal>
<emphasis>statement</emphasis>, which differs from the
- <function role="sql">IF()</function> <emphasis>function</emphasis>
- described here. See <xref linkend="if-statement"/>.
+ <function role="sql">IF()</function>
+ <emphasis>function</emphasis> described here. See
+ <xref linkend="if-statement"/>.
</para>
</note>
</listitem>
@@ -2039,11 +2041,12 @@
<para>
If <replaceable>expr1</replaceable> is not
- <literal>NULL</literal>, <function role="sql">IFNULL()</function> returns
+ <literal>NULL</literal>,
+ <function role="sql">IFNULL()</function> returns
<replaceable>expr1</replaceable>; otherwise it returns
- <replaceable>expr2</replaceable>. <function role="sql">IFNULL()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr2</replaceable>.
+ <function role="sql">IFNULL()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -2068,8 +2071,8 @@
the order <literal>STRING</literal>, <literal>REAL</literal>,
or <literal>INTEGER</literal>. Consider the case of a table
based on expressions or where MySQL must internally store a
- value returned by <function role="sql">IFNULL()</function> in a temporary
- table:
+ value returned by <function role="sql">IFNULL()</function> in
+ a temporary table:
</para>
<programlisting>
@@ -2200,7 +2203,8 @@
<literal>0</literal> if <replaceable>str</replaceable> is the
empty string. Returns <literal>NULL</literal> if
<replaceable>str</replaceable> is <literal>NULL</literal>.
- <function role="sql">ASCII()</function> works for 8-bit characters.
+ <function role="sql">ASCII()</function> works for 8-bit
+ characters.
</para>
<remark role="help-description-end"/>
@@ -2309,10 +2313,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">CHAR()</function> interprets each argument
- <replaceable>N</replaceable> as an integer and returns a
- string consisting of the characters given by the code values
- of those integers. <literal>NULL</literal> values are skipped.
+ <function role="sql">CHAR()</function> interprets each
+ argument <replaceable>N</replaceable> as an integer and
+ returns a string consisting of the characters given by the
+ code values of those integers. <literal>NULL</literal> values
+ are skipped.
</para>
<remark role="help-description-end"/>
@@ -2329,10 +2334,10 @@
<remark role="help-description-begin"/>
<para>
- As of MySQL 5.0.15, <function role="sql">CHAR()</function> arguments larger
- than 255 are converted into multiple result bytes. For
- example, <literal>CHAR(256)</literal> is equivalent to
- <literal>CHAR(1,0)</literal>, and
+ As of MySQL 5.0.15, <function role="sql">CHAR()</function>
+ arguments larger than 255 are converted into multiple result
+ bytes. For example, <literal>CHAR(256)</literal> is equivalent
+ to <literal>CHAR(1,0)</literal>, and
<literal>CHAR(256*256)</literal> is equivalent to
<literal>CHAR(1,0,0)</literal>:
</para>
@@ -2353,9 +2358,9 @@
</programlisting>
<para>
- By default, <function role="sql">CHAR()</function> returns a binary string.
- To produce a string in a given character set, use the optional
- <literal>USING</literal> clause:
+ By default, <function role="sql">CHAR()</function> returns a
+ binary string. To produce a string in a given character set,
+ use the optional <literal>USING</literal> clause:
</para>
<programlisting>
@@ -2371,12 +2376,13 @@
If <literal>USING</literal> is given and the result string is
illegal for the given character set, a warning is issued.
Also, if strict SQL mode is enabled, the result from
- <function role="sql">CHAR()</function> becomes <literal>NULL</literal>.
+ <function role="sql">CHAR()</function> becomes
+ <literal>NULL</literal>.
</para>
<para>
- Before MySQL 5.0.15, <function role="sql">CHAR()</function> returns a
- string in the connection character set and the
+ Before MySQL 5.0.15, <function role="sql">CHAR()</function>
+ returns a string in the connection character set and the
<literal>USING</literal> clause is unavailable. In addition,
each argument is interpreted modulo 256, so
<literal>CHAR(256)</literal> and
@@ -2409,9 +2415,9 @@
<replaceable>str</replaceable>, measured in characters. A
multi-byte character counts as a single character. This means
that for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -2651,18 +2657,18 @@
</para>
<para>
- If all arguments to <function role="sql">FIELD()</function> are strings,
- all arguments are compared as strings. If all arguments are
- numbers, they are compared as numbers. Otherwise, the
- arguments are compared as double.
+ If all arguments to <function role="sql">FIELD()</function>
+ are strings, all arguments are compared as strings. If all
+ arguments are numbers, they are compared as numbers.
+ Otherwise, the arguments are compared as double.
</para>
<para>
If <replaceable>str</replaceable> is <literal>NULL</literal>,
the return value is <literal>0</literal> because
<literal>NULL</literal> fails equality comparison with any
- value. <function role="sql">FIELD()</function> is the complement of
- <function role="sql">ELT()</function>.
+ value. <function role="sql">FIELD()</function> is the
+ complement of <function role="sql">ELT()</function>.
</para>
<remark role="help-description-end"/>
@@ -2887,8 +2893,8 @@
Returns the position of the first occurrence of substring
<replaceable>substr</replaceable> in string
<replaceable>str</replaceable>. This is the same as the
- two-argument form of <function role="sql">LOCATE()</function>, except that
- the order of the arguments is reversed.
+ two-argument form of <function role="sql">LOCATE()</function>,
+ except that the order of the arguments is reversed.
</para>
<remark role="help-description-end"/>
@@ -2989,9 +2995,9 @@
<replaceable>str</replaceable>, measured in bytes. A
multi-byte character counts as multiple bytes. This means that
for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -3385,8 +3391,8 @@
<para>
If the leftmost character is not a multi-byte character,
- <function role="sql">ORD()</function> returns the same value as the
- <function role="sql">ASCII()</function> function.
+ <function role="sql">ORD()</function> returns the same value
+ as the <function role="sql">ASCII()</function> function.
</para>
<remark role="help-description-end"/>
@@ -3525,8 +3531,9 @@
Returns the string <replaceable>str</replaceable> with all
occurrences of the string <replaceable>from_str</replaceable>
replaced by the string <replaceable>to_str</replaceable>.
- <function role="sql">REPLACE()</function> performs a case-sensitive match
- when searching for <replaceable>from_str</replaceable>.
+ <function role="sql">REPLACE()</function> performs a
+ case-sensitive match when searching for
+ <replaceable>from_str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -3718,11 +3725,11 @@
soundex strings. A standard soundex string is four characters
long, but the <function role="sql">SOUNDEX()</function>
function returns an arbitrarily long string. You can use
- <function role="sql">SUBSTRING()</function> on the result to get a standard
- soundex string. All non-alphabetic characters in
- <replaceable>str</replaceable> are ignored. All international
- alphabetic characters outside the A-Z range are treated as
- vowels.
+ <function role="sql">SUBSTRING()</function> on the result to
+ get a standard soundex string. All non-alphabetic characters
+ in <replaceable>str</replaceable> are ignored. All
+ international alphabetic characters outside the A-Z range are
+ treated as vowels.
</para>
<important>
@@ -3844,6 +3851,37 @@
</listitem>
<listitem>
+ <remark role="help-topic" condition="SUBSTR"/>
+
+ <remark role="help-syntax-begin"/>
+
+ <para id="function_substr">
+ <indexterm>
+ <primary>SUBSTR()</primary>
+ </indexterm>
+
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable> FOR
+ <replaceable>len</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">SUBSTR()</function> is a synonym for
+ <function role="sql">SUBSTRING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
<remark role="help-topic" condition="SUBSTRING"/>
<remark role="help-syntax-begin"/>
@@ -3853,10 +3891,6 @@
<primary>SUBSTRING()</primary>
</indexterm>
- <indexterm>
- <primary>SUBSTR()</primary>
- </indexterm>
-
<literal>SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
<literal>SUBSTRING(<replaceable>str</replaceable> FROM
<replaceable>pos</replaceable>)</literal>,
@@ -3888,9 +3922,10 @@
</para>
<para>
- For all forms of <function role="sql">SUBSTRING()</function>, the position
- of the first character in the string from which the substring
- is to be extracted is reckoned as <literal>1</literal>.
+ For all forms of <function role="sql">SUBSTRING()</function>,
+ the position of the first character in the string from which
+ the substring is to be extracted is reckoned as
+ <literal>1</literal>.
</para>
<remark role="help-description-end"/>
@@ -3920,11 +3955,6 @@
If <replaceable>len</replaceable> is less than 1, the result
is the empty string.
</para>
-
- <para>
- <function role="sql">SUBSTR()</function> is a synonym for
- <function role="sql">SUBSTRING()</function>.
- </para>
</listitem>
<listitem>
@@ -4100,9 +4130,10 @@
hexadecimal digits: <literal>'0'</literal> ..
<literal>'9'</literal>, <literal>'A'</literal> ..
<literal>'F'</literal>, <literal>'a'</literal> ..
- <literal>'f'</literal>. If <function role="sql">UNHEX()</function>
- encounters any non-hexadecimal digits in the argument, it
- returns <literal>NULL</literal>:
+ <literal>'f'</literal>. If
+ <function role="sql">UNHEX()</function> encounters any
+ non-hexadecimal digits in the argument, it returns
+ <literal>NULL</literal>:
</para>
<programlisting>
@@ -4116,23 +4147,23 @@
<para>
A <literal>NULL</literal> result can occur if the argument to
- <function role="sql">UNHEX()</function> is a <literal>BINARY</literal>
- column, because values are padded with 0x00 bytes when stored
- but those bytes are not stripped on retrieval. For example
- <literal>'aa'</literal> is stored into a
- <literal>CHAR(3)</literal> column as
+ <function role="sql">UNHEX()</function> is a
+ <literal>BINARY</literal> column, because values are padded
+ with 0x00 bytes when stored but those bytes are not stripped
+ on retrieval. For example <literal>'aa'</literal> is stored
+ into a <literal>CHAR(3)</literal> column as
<literal>'aa '</literal> and retrieved as
<literal>'aa'</literal> (with the trailing pad space
- stripped), so <function role="sql">UNHEX()</function> for the column value
- returns <literal>'A'</literal>. By contrast
+ stripped), so <function role="sql">UNHEX()</function> for the
+ column value returns <literal>'A'</literal>. By contrast
<literal>'aa'</literal> is stored into a
<literal>BINARY(3)</literal> column as
<literal>'aa\0'</literal> and retrieved as
<literal>'aa\0'</literal> (with the trailing pad
<literal>0x00</literal> byte not stripped).
<literal>'\0'</literal> is not a legal hexadecimal digit, so
- <function role="sql">UNHEX()</function> for the column value returns
- <literal>NULL</literal>.
+ <function role="sql">UNHEX()</function> for the column value
+ returns <literal>NULL</literal>.
</para>
</listitem>
@@ -4638,10 +4669,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">STRCMP()</function> returns <literal>0</literal> if
- the strings are the same, <literal>-1</literal> if the first
- argument is smaller than the second according to the current
- sort order, and <literal>1</literal> otherwise.
+ <function role="sql">STRCMP()</function> returns
+ <literal>0</literal> if the strings are the same,
+ <literal>-1</literal> if the first argument is smaller than
+ the second according to the current sort order, and
+ <literal>1</literal> otherwise.
</para>
<remark role="help-description-end"/>
@@ -4658,10 +4690,10 @@
</programlisting>
<para>
- <function role="sql">STRCMP()</function> uses the current character set
- when performing comparisons. This makes the default
- comparison behavior case insensitive unless one or both of
- the operands are binary strings.
+ <function role="sql">STRCMP()</function> uses the current
+ character set when performing comparisons. This makes the
+ default comparison behavior case insensitive unless one or
+ both of the operands are binary strings.
</para>
</listitem>
@@ -5789,8 +5821,9 @@
<remark role="help-description-begin"/>
<para>
- Integer division. Similar to <function role="sql">FLOOR()</function>, but
- is safe with <literal>BIGINT</literal> values.
+ Integer division. Similar to
+ <function role="sql">FLOOR()</function>, but is safe with
+ <literal>BIGINT</literal> values.
</para>
<remark role="help-description-end"/>
@@ -6067,7 +6100,7 @@
</listitem>
<listitem>
- <remark role="help-topic" condition="CEILING"/>
+ <remark role="help-topic" condition="CEIL"/>
<remark role="help-keywords">
CEIL
@@ -6075,13 +6108,41 @@
<remark role="help-syntax-begin"/>
+ <para id="function_ceil">
+ <indexterm>
+ <primary>CEIL()</primary>
+ </indexterm>
+
+ <function role="sql">CEIL(<replaceable>X</replaceable>)</function>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">CEIL()</function> is a synonym for
+ <function role="sql">CEILING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
+ <remark role="help-topic" condition="CEILING"/>
+
+ <remark role="help-keywords">
+ CEILING
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
<para id="function_ceiling">
<indexterm>
<primary>CEILING()</primary>
</indexterm>
- <literal>CEILING(<replaceable>X</replaceable>)</literal>,
- <literal>CEIL(<replaceable>X</replaceable>)</literal>
+ <function role="sql">CEILING(<replaceable>X</replaceable>)</function>
</para>
<remark role="help-syntax-end"/>
@@ -6090,8 +6151,7 @@
<para>
Returns the smallest integer value not less than
- <replaceable>X</replaceable>. <function role="sql">CEILING()</function>
- and <function role="sql">CEIL()</function> are synonymous.
+ <replaceable>X</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -6101,7 +6161,7 @@
<programlisting>
mysql> <userinput>SELECT CEILING(1.23);</userinput>
-> 2
-mysql> <userinput>SELECT CEIL(-1.23);</userinput>
+mysql> <userinput>SELECT CEILING(-1.23);</userinput>
-> -1
</programlisting>
@@ -6144,7 +6204,8 @@
is a negative number, <replaceable>N</replaceable> is
regarded as a signed number. Otherwise,
<replaceable>N</replaceable> is treated as unsigned.
- <function role="sql">CONV()</function> works with 64-bit precision.
+ <function role="sql">CONV()</function> works with 64-bit
+ precision.
</para>
<remark role="help-description-end"/>
@@ -6881,11 +6942,11 @@
</programlisting>
<para>
- You cannot use a column with <function role="sql">RAND()</function>
- values in an <literal>ORDER BY</literal> clause, because
- <literal>ORDER BY</literal> would evaluate the column
- multiple times. However, you can retrieve rows in random
- order like this:
+ You cannot use a column with
+ <function role="sql">RAND()</function> values in an
+ <literal>ORDER BY</literal> clause, because <literal>ORDER
+ BY</literal> would evaluate the column multiple times.
+ However, you can retrieve rows in random order like this:
</para>
<programlisting>
@@ -6909,10 +6970,11 @@
</para>
<para>
- <function role="sql">RAND()</function> is not meant to be a perfect
- random generator, but instead is a fast way to generate
- <foreignphrase>ad hoc</foreignphrase> random numbers which
- is portable between platforms for the same MySQL version.
+ <function role="sql">RAND()</function> is not meant to be a
+ perfect random generator, but instead is a fast way to
+ generate <foreignphrase>ad hoc</foreignphrase> random
+ numbers which is portable between platforms for the same
+ MySQL version.
</para>
</listitem>
@@ -6982,28 +7044,29 @@
<para>
Before MySQL 5.0.3, the behavior of
- <function role="sql">ROUND()</function> when the argument is halfway
- between two integers depends on the C library
+ <function role="sql">ROUND()</function> when the argument is
+ halfway between two integers depends on the C library
implementation. Different implementations round to the
nearest even number, always up, always down, or always
toward zero. If you need one kind of rounding, you should
use a well-defined function such as
- <function role="sql">TRUNCATE()</function> or <function role="sql">FLOOR()</function>
- instead.
+ <function role="sql">TRUNCATE()</function> or
+ <function role="sql">FLOOR()</function> instead.
</para>
<para>
- As of MySQL 5.0.3, <function role="sql">ROUND()</function> uses the
- precision math library for exact-value arguments when the
- first argument is a decimal value:
+ As of MySQL 5.0.3, <function role="sql">ROUND()</function>
+ uses the precision math library for exact-value arguments
+ when the first argument is a decimal value:
</para>
<itemizedlist>
<listitem>
<para>
- For exact-value numbers, <function role="sql">ROUND()</function> uses
- the <quote>round half up</quote> or <quote>round toward
+ For exact-value numbers,
+ <function role="sql">ROUND()</function> uses the
+ <quote>round half up</quote> or <quote>round toward
nearest</quote> rule: A value with a fractional part of
.5 or greater is rounded up to the next integer if
positive or down to the next integer if negative. (In
@@ -7018,9 +7081,9 @@
<para>
For approximate-value numbers, the result depends on the
C library. On many systems, this means that
- <function role="sql">ROUND()</function> uses the "round to nearest
- even" rule: A value with any fractional part is rounded
- to the nearest even integer.
+ <function role="sql">ROUND()</function> uses the "round
+ to nearest even" rule: A value with any fractional part
+ is rounded to the nearest even integer.
</para>
</listitem>
@@ -7296,11 +7359,12 @@
Functions that return the current date or time each are evaluated
only once per query at the start of query execution. This means
that multiple references to a function such as
- <function role="sql">NOW()</function> within a single query always produce the
- same result (for our purposes a single query also includes a call
- to a stored routine or trigger and all sub-routines called by that
- routine/trigger). This principle also applies to
- <function role="sql">CURDATE()</function>, <function role="sql">CURTIME()</function>,
+ <function role="sql">NOW()</function> within a single query always
+ produce the same result (for our purposes a single query also
+ includes a call to a stored routine or trigger and all
+ sub-routines called by that routine/trigger). This principle also
+ applies to <function role="sql">CURDATE()</function>,
+ <function role="sql">CURTIME()</function>,
<literal>UTC_DATE()</literal>, <literal>UTC_TIME()</literal>,
<literal>UTC_TIMESTAMP()</literal>, and to any of their synonyms.
</para>
@@ -7367,13 +7431,13 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">ADDDATE()</function> is a synonym for
- <literal>DATE_ADD()</literal>. The related function
- <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">ADDDATE()</function> is
+ a synonym for <literal>DATE_ADD()</literal>. The related
+ function <function role="sql">SUBDATE()</function> is a
+ synonym for <literal>DATE_SUB()</literal>. For information on
+ the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -8491,8 +8555,9 @@
<remark role="help-description-begin"/>
<para>
- The <function role="sql">EXTRACT()</function> function uses the same kinds
- of unit specifiers as <literal>DATE_ADD()</literal> or
+ The <function role="sql">EXTRACT()</function> function uses
+ the same kinds of unit specifiers as
+ <literal>DATE_ADD()</literal> or
<literal>DATE_SUB()</literal>, but extracts parts from the
date rather than performing date arithmetic.
</para>
@@ -8857,7 +8922,8 @@
<primary>LOCALTIME</primary>
</indexterm>
- <literal>LOCALTIME</literal>, <function role="sql">LOCALTIME()</function>
+ <literal>LOCALTIME</literal>,
+ <function role="sql">LOCALTIME()</function>
</para>
<remark role="help-syntax-end"/>
@@ -8893,8 +8959,8 @@
<para>
<literal>LOCALTIMESTAMP</literal> and
- <function role="sql">LOCALTIMESTAMP()</function> are synonyms for
- <function role="sql">NOW()</function>.
+ <function role="sql">LOCALTIMESTAMP()</function> are synonyms
+ for <function role="sql">NOW()</function>.
</para>
<remark role="help-description-end"/>
@@ -9142,13 +9208,14 @@
</programlisting>
<para>
- <function role="sql">NOW()</function> returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.) This differs from the behavior for
- <function role="sql">SYSDATE()</function>, which returns the exact time at
- which it executes as of MySQL 5.0.13.
+ <function role="sql">NOW()</function> returns a constant time
+ that indicates the time at which the statement began to
+ execute. (Within a stored routine or trigger,
+ <function role="sql">NOW()</function> returns the time at
+ which the routine or triggering statement began to execute.)
+ This differs from the behavior for
+ <function role="sql">SYSDATE()</function>, which returns the
+ exact time at which it executes as of MySQL 5.0.13.
</para>
<programlisting>
@@ -9168,9 +9235,9 @@
</programlisting>
<para>
- See the description for <function role="sql">SYSDATE()</function> for
- additional information about the differences between the two
- functions.
+ See the description for
+ <function role="sql">SYSDATE()</function> for additional
+ information about the differences between the two functions.
</para>
</listitem>
@@ -9483,11 +9550,11 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">SUBDATE()</function> is
+ a synonym for <literal>DATE_SUB()</literal>. For information
+ on the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -9580,13 +9647,14 @@
</para>
<para>
- As of MySQL 5.0.13, <function role="sql">SYSDATE()</function> returns the
- time at which it executes. This differs from the behavior for
- <function role="sql">NOW()</function>, which returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.)
+ As of MySQL 5.0.13, <function role="sql">SYSDATE()</function>
+ returns the time at which it executes. This differs from the
+ behavior for <function role="sql">NOW()</function>, which
+ returns a constant time that indicates the time at which the
+ statement began to execute. (Within a stored routine or
+ trigger, <function role="sql">NOW()</function> returns the
+ time at which the routine or triggering statement began to
+ execute.)
</para>
<programlisting>
@@ -9607,23 +9675,25 @@
<para>
In addition, the <literal>SET TIMESTAMP</literal> statement
- affects the value returned by <function role="sql">NOW()</function> but not
- by <function role="sql">SYSDATE()</function>. This means that timestamp
- settings in the binary log have no effect on invocations of
- <function role="sql">SYSDATE()</function>.
+ affects the value returned by
+ <function role="sql">NOW()</function> but not by
+ <function role="sql">SYSDATE()</function>. This means that
+ timestamp settings in the binary log have no effect on
+ invocations of <function role="sql">SYSDATE()</function>.
</para>
<para>
- Because <function role="sql">SYSDATE()</function> can return different
- values even within the same statement, and is not affected by
- <literal>SET TIMESTAMP</literal>, it is non-deterministic and
- therefore unsafe for replication. If that is a problem, you
- can start the server with the
+ Because <function role="sql">SYSDATE()</function> can return
+ different values even within the same statement, and is not
+ affected by <literal>SET TIMESTAMP</literal>, it is
+ non-deterministic and therefore unsafe for replication. If
+ that is a problem, you can start the server with the
<option>--sysdate-is-now</option> option to cause
<function role="sql">SYSDATE()</function> to be an alias for
- <function role="sql">NOW()</function>. The non-deterministic nature of
- <function role="sql">SYSDATE()</function> also means that indexes cannot be
- used for evaluating expressions that refer to it.
+ <function role="sql">NOW()</function>. The non-deterministic
+ nature of <function role="sql">SYSDATE()</function> also means
+ that indexes cannot be used for evaluating expressions that
+ refer to it.
</para>
<remark role="help-description-end"/>
@@ -9805,8 +9875,8 @@
</programlisting>
<para>
- <function role="sql">TIMESTAMPADD()</function> is available as of MySQL
- 5.0.0.
+ <function role="sql">TIMESTAMPADD()</function> is available as
+ of MySQL 5.0.0.
</para>
</listitem>
@@ -9849,8 +9919,8 @@
</programlisting>
<para>
- <function role="sql">TIMESTAMPDIFF()</function> is available as of MySQL
- 5.0.0.
+ <function role="sql">TIMESTAMPDIFF()</function> is available
+ as of MySQL 5.0.0.
</para>
</listitem>
@@ -10215,10 +10285,10 @@
<para>
This function returns the week number for
<replaceable>date</replaceable>. The two-argument form of
- <function role="sql">WEEK()</function> allows you to specify whether the
- week starts on Sunday or Monday and whether the return value
- should be in the range from <literal>0</literal> to
- <literal>53</literal> or from <literal>1</literal> to
+ <function role="sql">WEEK()</function> allows you to specify
+ whether the week starts on Sunday or Monday and whether the
+ return value should be in the range from <literal>0</literal>
+ to <literal>53</literal> or from <literal>1</literal> to
<literal>53</literal>. If the <replaceable>mode</replaceable>
argument is omitted, the value of the
<literal>default_week_format</literal> system variable is
@@ -10331,13 +10401,14 @@
<para>
One might argue that MySQL should return <literal>52</literal>
- for the <function role="sql">WEEK()</function> function, because the given
- date actually occurs in the 52nd week of 1999. We decided to
- return <literal>0</literal> instead because we want the
- function to return <quote>the week number in the given
- year.</quote> This makes use of the <function role="sql">WEEK()</function>
- function reliable when combined with other functions that
- extract a date part from a date.
+ for the <function role="sql">WEEK()</function> function,
+ because the given date actually occurs in the 52nd week of
+ 1999. We decided to return <literal>0</literal> instead
+ because we want the function to return <quote>the week number
+ in the given year.</quote> This makes use of the
+ <function role="sql">WEEK()</function> function reliable when
+ combined with other functions that extract a date part from a
+ date.
</para>
<para>
@@ -10354,7 +10425,8 @@
</programlisting>
<para>
- Alternatively, use the <function role="sql">YEARWEEK()</function> function:
+ Alternatively, use the
+ <function role="sql">YEARWEEK()</function> function:
</para>
<programlisting>
@@ -10420,8 +10492,8 @@
<para>
Returns the calendar week of the date as a number in the range
from <literal>1</literal> to <literal>53</literal>.
- <function role="sql">WEEKOFYEAR()</function> is a compatibility function
- that is equivalent to
+ <function role="sql">WEEKOFYEAR()</function> is a
+ compatibility function that is equivalent to
<literal>WEEK(<replaceable>date</replaceable>,3)</literal>.
</para>
@@ -10490,9 +10562,9 @@
Returns year and week for a date. The
<replaceable>mode</replaceable> argument works exactly like
the <replaceable>mode</replaceable> argument to
- <function role="sql">WEEK()</function>. The year in the result may be
- different from the year in the date argument for the first and
- the last week of the year.
+ <function role="sql">WEEK()</function>. The year in the result
+ may be different from the year in the date argument for the
+ first and the last week of the year.
</para>
<remark role="help-description-end"/>
@@ -10509,8 +10581,8 @@
<function role="sql">WEEK()</function> function would return
(<literal>0</literal>) for optional arguments
<literal>0</literal> or <literal>1</literal>, as
- <function role="sql">WEEK()</function> then returns the week in the context
- of the given year.
+ <function role="sql">WEEK()</function> then returns the week
+ in the context of the given year.
</para>
</listitem>
@@ -15804,9 +15876,10 @@
<para>
Sleeps (pauses) for the number of seconds given by the
<replaceable>duration</replaceable> argument, then returns
- 0. If <function role="sql">SLEEP()</function> is interrupted, it returns
- 1. The duration may have a fractional part given in
- microseconds. This function was added in MySQL 5.0.12.
+ 0. If <function role="sql">SLEEP()</function> is
+ interrupted, it returns 1. The duration may have a
+ fractional part given in microseconds. This function was
+ added in MySQL 5.0.12.
</para>
<remark role="help-description-end"/>
Modified: trunk/refman-5.1/functions-core.xml
===================================================================
--- trunk/refman-5.1/functions-core.xml 2007-12-05 02:30:44 UTC (rev 9113)
+++ trunk/refman-5.1/functions-core.xml 2007-12-05 02:31:04 UTC (rev 9114)
Changed blocks: 54, Lines Added: 260, Lines Deleted: 188; 38109 bytes
@@ -1893,11 +1893,12 @@
If <replaceable>expr1</replaceable> is <literal>TRUE</literal>
(<literal><replaceable>expr1</replaceable> <>
0</literal> and <literal><replaceable>expr1</replaceable>
- <> NULL</literal>) then <function role="sql">IF()</function> returns
+ <> NULL</literal>) then
+ <function role="sql">IF()</function> returns
<replaceable>expr2</replaceable>; otherwise it returns
- <replaceable>expr3</replaceable>. <function role="sql">IF()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr3</replaceable>.
+ <function role="sql">IF()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -1917,8 +1918,8 @@
If only one of <replaceable>expr2</replaceable> or
<replaceable>expr3</replaceable> is explicitly
<literal>NULL</literal>, the result type of the
- <function role="sql">IF()</function> function is the type of the
- non-<literal>NULL</literal> expression.
+ <function role="sql">IF()</function> function is the type of
+ the non-<literal>NULL</literal> expression.
</para>
<para>
@@ -1945,9 +1946,9 @@
</para>
<para>
- The default return type of <function role="sql">IF()</function> (which may
- matter when it is stored into a temporary table) is calculated
- as follows:
+ The default return type of
+ <function role="sql">IF()</function> (which may matter when it
+ is stored into a temporary table) is calculated as follows:
</para>
<informaltable>
@@ -1988,8 +1989,9 @@
<para>
There is also an <literal>IF</literal>
<emphasis>statement</emphasis>, which differs from the
- <function role="sql">IF()</function> <emphasis>function</emphasis>
- described here. See <xref linkend="if-statement"/>.
+ <function role="sql">IF()</function>
+ <emphasis>function</emphasis> described here. See
+ <xref linkend="if-statement"/>.
</para>
</note>
</listitem>
@@ -2018,11 +2020,12 @@
<para>
If <replaceable>expr1</replaceable> is not
- <literal>NULL</literal>, <function role="sql">IFNULL()</function> returns
+ <literal>NULL</literal>,
+ <function role="sql">IFNULL()</function> returns
<replaceable>expr1</replaceable>; otherwise it returns
- <replaceable>expr2</replaceable>. <function role="sql">IFNULL()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr2</replaceable>.
+ <function role="sql">IFNULL()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -2047,8 +2050,8 @@
the order <literal>STRING</literal>, <literal>REAL</literal>,
or <literal>INTEGER</literal>. Consider the case of a table
based on expressions or where MySQL must internally store a
- value returned by <function role="sql">IFNULL()</function> in a temporary
- table:
+ value returned by <function role="sql">IFNULL()</function> in
+ a temporary table:
</para>
<programlisting>
@@ -2179,7 +2182,8 @@
<literal>0</literal> if <replaceable>str</replaceable> is the
empty string. Returns <literal>NULL</literal> if
<replaceable>str</replaceable> is <literal>NULL</literal>.
- <function role="sql">ASCII()</function> works for 8-bit characters.
+ <function role="sql">ASCII()</function> works for 8-bit
+ characters.
</para>
<remark role="help-description-end"/>
@@ -2288,10 +2292,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">CHAR()</function> interprets each argument
- <replaceable>N</replaceable> as an integer and returns a
- string consisting of the characters given by the code values
- of those integers. <literal>NULL</literal> values are skipped.
+ <function role="sql">CHAR()</function> interprets each
+ argument <replaceable>N</replaceable> as an integer and
+ returns a string consisting of the characters given by the
+ code values of those integers. <literal>NULL</literal> values
+ are skipped.
</para>
<remark role="help-description-end"/>
@@ -2306,8 +2311,8 @@
</programlisting>
<para>
- <function role="sql">CHAR()</function> arguments larger than 255 are
- converted into multiple result bytes. For example,
+ <function role="sql">CHAR()</function> arguments larger than
+ 255 are converted into multiple result bytes. For example,
<literal>CHAR(256)</literal> is equivalent to
<literal>CHAR(1,0)</literal>, and
<literal>CHAR(256*256)</literal> is equivalent to
@@ -2332,9 +2337,9 @@
<remark role="help-description-begin"/>
<para>
- By default, <function role="sql">CHAR()</function> returns a binary string.
- To produce a string in a given character set, use the optional
- <literal>USING</literal> clause:
+ By default, <function role="sql">CHAR()</function> returns a
+ binary string. To produce a string in a given character set,
+ use the optional <literal>USING</literal> clause:
</para>
<programlisting>
@@ -2350,7 +2355,8 @@
If <literal>USING</literal> is given and the result string is
illegal for the given character set, a warning is issued.
Also, if strict SQL mode is enabled, the result from
- <function role="sql">CHAR()</function> becomes <literal>NULL</literal>.
+ <function role="sql">CHAR()</function> becomes
+ <literal>NULL</literal>.
</para>
<remark role="help-description-end"/>
@@ -2378,9 +2384,9 @@
<replaceable>str</replaceable>, measured in characters. A
multi-byte character counts as a single character. This means
that for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -2620,18 +2626,18 @@
</para>
<para>
- If all arguments to <function role="sql">FIELD()</function> are strings,
- all arguments are compared as strings. If all arguments are
- numbers, they are compared as numbers. Otherwise, the
- arguments are compared as double.
+ If all arguments to <function role="sql">FIELD()</function>
+ are strings, all arguments are compared as strings. If all
+ arguments are numbers, they are compared as numbers.
+ Otherwise, the arguments are compared as double.
</para>
<para>
If <replaceable>str</replaceable> is <literal>NULL</literal>,
the return value is <literal>0</literal> because
<literal>NULL</literal> fails equality comparison with any
- value. <function role="sql">FIELD()</function> is the complement of
- <function role="sql">ELT()</function>.
+ value. <function role="sql">FIELD()</function> is the
+ complement of <function role="sql">ELT()</function>.
</para>
<remark role="help-description-end"/>
@@ -2856,8 +2862,8 @@
Returns the position of the first occurrence of substring
<replaceable>substr</replaceable> in string
<replaceable>str</replaceable>. This is the same as the
- two-argument form of <function role="sql">LOCATE()</function>, except that
- the order of the arguments is reversed.
+ two-argument form of <function role="sql">LOCATE()</function>,
+ except that the order of the arguments is reversed.
</para>
<remark role="help-description-end"/>
@@ -2958,9 +2964,9 @@
<replaceable>str</replaceable>, measured in bytes. A
multi-byte character counts as multiple bytes. This means that
for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -3317,8 +3323,8 @@
<para>
If the leftmost character is not a multi-byte character,
- <function role="sql">ORD()</function> returns the same value as the
- <function role="sql">ASCII()</function> function.
+ <function role="sql">ORD()</function> returns the same value
+ as the <function role="sql">ASCII()</function> function.
</para>
<remark role="help-description-end"/>
@@ -3457,8 +3463,9 @@
Returns the string <replaceable>str</replaceable> with all
occurrences of the string <replaceable>from_str</replaceable>
replaced by the string <replaceable>to_str</replaceable>.
- <function role="sql">REPLACE()</function> performs a case-sensitive match
- when searching for <replaceable>from_str</replaceable>.
+ <function role="sql">REPLACE()</function> performs a
+ case-sensitive match when searching for
+ <replaceable>from_str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -3650,11 +3657,11 @@
soundex strings. A standard soundex string is four characters
long, but the <function role="sql">SOUNDEX()</function>
function returns an arbitrarily long string. You can use
- <function role="sql">SUBSTRING()</function> on the result to get a standard
- soundex string. All non-alphabetic characters in
- <replaceable>str</replaceable> are ignored. All international
- alphabetic characters outside the A-Z range are treated as
- vowels.
+ <function role="sql">SUBSTRING()</function> on the result to
+ get a standard soundex string. All non-alphabetic characters
+ in <replaceable>str</replaceable> are ignored. All
+ international alphabetic characters outside the A-Z range are
+ treated as vowels.
</para>
<important>
@@ -3776,6 +3783,37 @@
</listitem>
<listitem>
+ <remark role="help-topic" condition="SUBSTR"/>
+
+ <remark role="help-syntax-begin"/>
+
+ <para id="function_substr">
+ <indexterm>
+ <primary>SUBSTR()</primary>
+ </indexterm>
+
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable> FOR
+ <replaceable>len</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">SUBSTR()</function> is a synonym for
+ <function role="sql">SUBSTRING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
<remark role="help-topic" condition="SUBSTRING"/>
<remark role="help-syntax-begin"/>
@@ -3785,10 +3823,6 @@
<primary>SUBSTRING()</primary>
</indexterm>
- <indexterm>
- <primary>SUBSTR()</primary>
- </indexterm>
-
<literal>SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
<literal>SUBSTRING(<replaceable>str</replaceable> FROM
<replaceable>pos</replaceable>)</literal>,
@@ -3820,9 +3854,10 @@
</para>
<para>
- For all forms of <function role="sql">SUBSTRING()</function>, the position
- of the first character in the string from which the substring
- is to be extracted is reckoned as <literal>1</literal>.
+ For all forms of <function role="sql">SUBSTRING()</function>,
+ the position of the first character in the string from which
+ the substring is to be extracted is reckoned as
+ <literal>1</literal>.
</para>
<remark role="help-description-end"/>
@@ -3852,11 +3887,6 @@
If <replaceable>len</replaceable> is less than 1, the result
is the empty string.
</para>
-
- <para>
- <function role="sql">SUBSTR()</function> is a synonym for
- <function role="sql">SUBSTRING()</function>.
- </para>
</listitem>
<listitem>
@@ -4032,9 +4062,10 @@
hexadecimal digits: <literal>'0'</literal> ..
<literal>'9'</literal>, <literal>'A'</literal> ..
<literal>'F'</literal>, <literal>'a'</literal> ..
- <literal>'f'</literal>. If <function role="sql">UNHEX()</function>
- encounters any non-hexadecimal digits in the argument, it
- returns <literal>NULL</literal>:
+ <literal>'f'</literal>. If
+ <function role="sql">UNHEX()</function> encounters any
+ non-hexadecimal digits in the argument, it returns
+ <literal>NULL</literal>:
</para>
<programlisting>
@@ -4048,23 +4079,23 @@
<para>
A <literal>NULL</literal> result can occur if the argument to
- <function role="sql">UNHEX()</function> is a <literal>BINARY</literal>
- column, because values are padded with 0x00 bytes when stored
- but those bytes are not stripped on retrieval. For example
- <literal>'aa'</literal> is stored into a
- <literal>CHAR(3)</literal> column as
+ <function role="sql">UNHEX()</function> is a
+ <literal>BINARY</literal> column, because values are padded
+ with 0x00 bytes when stored but those bytes are not stripped
+ on retrieval. For example <literal>'aa'</literal> is stored
+ into a <literal>CHAR(3)</literal> column as
<literal>'aa '</literal> and retrieved as
<literal>'aa'</literal> (with the trailing pad space
- stripped), so <function role="sql">UNHEX()</function> for the column value
- returns <literal>'A'</literal>. By contrast
+ stripped), so <function role="sql">UNHEX()</function> for the
+ column value returns <literal>'A'</literal>. By contrast
<literal>'aa'</literal> is stored into a
<literal>BINARY(3)</literal> column as
<literal>'aa\0'</literal> and retrieved as
<literal>'aa\0'</literal> (with the trailing pad
<literal>0x00</literal> byte not stripped).
<literal>'\0'</literal> is not a legal hexadecimal digit, so
- <function role="sql">UNHEX()</function> for the column value returns
- <literal>NULL</literal>.
+ <function role="sql">UNHEX()</function> for the column value
+ returns <literal>NULL</literal>.
</para>
</listitem>
@@ -4570,10 +4601,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">STRCMP()</function> returns <literal>0</literal> if
- the strings are the same, <literal>-1</literal> if the first
- argument is smaller than the second according to the current
- sort order, and <literal>1</literal> otherwise.
+ <function role="sql">STRCMP()</function> returns
+ <literal>0</literal> if the strings are the same,
+ <literal>-1</literal> if the first argument is smaller than
+ the second according to the current sort order, and
+ <literal>1</literal> otherwise.
</para>
<remark role="help-description-end"/>
@@ -4590,10 +4622,10 @@
</programlisting>
<para>
- <function role="sql">STRCMP()</function> uses the current character set
- when performing comparisons. This makes the default
- comparison behavior case insensitive unless one or both of
- the operands are binary strings.
+ <function role="sql">STRCMP()</function> uses the current
+ character set when performing comparisons. This makes the
+ default comparison behavior case insensitive unless one or
+ both of the operands are binary strings.
</para>
</listitem>
@@ -5721,8 +5753,9 @@
<remark role="help-description-begin"/>
<para>
- Integer division. Similar to <function role="sql">FLOOR()</function>, but
- is safe with <literal>BIGINT</literal> values.
+ Integer division. Similar to
+ <function role="sql">FLOOR()</function>, but is safe with
+ <literal>BIGINT</literal> values.
</para>
<remark role="help-description-end"/>
@@ -5999,7 +6032,7 @@
</listitem>
<listitem>
- <remark role="help-topic" condition="CEILING"/>
+ <remark role="help-topic" condition="CEIL"/>
<remark role="help-keywords">
CEIL
@@ -6007,13 +6040,41 @@
<remark role="help-syntax-begin"/>
+ <para id="function_ceil">
+ <indexterm>
+ <primary>CEIL()</primary>
+ </indexterm>
+
+ <function role="sql">CEIL(<replaceable>X</replaceable>)</function>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">CEIL()</function> is a synonym for
+ <function role="sql">CEILING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
+ <remark role="help-topic" condition="CEILING"/>
+
+ <remark role="help-keywords">
+ CEILING
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
<para id="function_ceiling">
<indexterm>
<primary>CEILING()</primary>
</indexterm>
- <literal>CEILING(<replaceable>X</replaceable>)</literal>,
- <literal>CEIL(<replaceable>X</replaceable>)</literal>
+ <function role="sql">CEILING(<replaceable>X</replaceable>)</function>
</para>
<remark role="help-syntax-end"/>
@@ -6022,8 +6083,7 @@
<para>
Returns the smallest integer value not less than
- <replaceable>X</replaceable>. <function role="sql">CEILING()</function>
- and <function role="sql">CEIL()</function> are synonymous.
+ <replaceable>X</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -6033,7 +6093,7 @@
<programlisting>
mysql> <userinput>SELECT CEILING(1.23);</userinput>
-> 2
-mysql> <userinput>SELECT CEIL(-1.23);</userinput>
+mysql> <userinput>SELECT CEILING(-1.23);</userinput>
-> -1
</programlisting>
@@ -6076,7 +6136,8 @@
is a negative number, <replaceable>N</replaceable> is
regarded as a signed number. Otherwise,
<replaceable>N</replaceable> is treated as unsigned.
- <function role="sql">CONV()</function> works with 64-bit precision.
+ <function role="sql">CONV()</function> works with 64-bit
+ precision.
</para>
<remark role="help-description-end"/>
@@ -6832,11 +6893,12 @@
MySQL 5.1.16, if a non-constant initializer (such as a
column name) is used as the argument, the seed is
initialized with the value for each invocation of
- <function role="sql">RAND()</function>. (One implication of this is that
- for equal argument values, <function role="sql">RAND()</function> will
- return the same value each time.) From MySQL 5.1.3 to
- 5.1.15, non-constant arguments are disallowed. Before that,
- the effect of using a non-constant argument is undefined.
+ <function role="sql">RAND()</function>. (One implication of
+ this is that for equal argument values,
+ <function role="sql">RAND()</function> will return the same
+ value each time.) From MySQL 5.1.3 to 5.1.15, non-constant
+ arguments are disallowed. Before that, the effect of using a
+ non-constant argument is undefined.
</para>
<para>
@@ -6858,11 +6920,11 @@
</programlisting>
<para>
- You cannot use a column with <function role="sql">RAND()</function>
- values in an <literal>ORDER BY</literal> clause, because
- <literal>ORDER BY</literal> would evaluate the column
- multiple times. However, you can retrieve rows in random
- order like this:
+ You cannot use a column with
+ <function role="sql">RAND()</function> values in an
+ <literal>ORDER BY</literal> clause, because <literal>ORDER
+ BY</literal> would evaluate the column multiple times.
+ However, you can retrieve rows in random order like this:
</para>
<programlisting>
@@ -6886,10 +6948,11 @@
</para>
<para>
- <function role="sql">RAND()</function> is not meant to be a perfect
- random generator, but instead is a fast way to generate
- <foreignphrase>ad hoc</foreignphrase> random numbers which
- is portable between platforms for the same MySQL version.
+ <function role="sql">RAND()</function> is not meant to be a
+ perfect random generator, but instead is a fast way to
+ generate <foreignphrase>ad hoc</foreignphrase> random
+ numbers which is portable between platforms for the same
+ MySQL version.
</para>
</listitem>
@@ -6958,17 +7021,18 @@
</programlisting>
<para>
- <function role="sql">ROUND()</function> uses the precision math library
- for exact-value arguments when the first argument is a
- decimal value:
+ <function role="sql">ROUND()</function> uses the precision
+ math library for exact-value arguments when the first
+ argument is a decimal value:
</para>
<itemizedlist>
<listitem>
<para>
- For exact-value numbers, <function role="sql">ROUND()</function> uses
- the <quote>round half up</quote> or <quote>round toward
+ For exact-value numbers,
+ <function role="sql">ROUND()</function> uses the
+ <quote>round half up</quote> or <quote>round toward
nearest</quote> rule: A value with a fractional part of
.5 or greater is rounded up to the next integer if
positive or down to the next integer if negative. (In
@@ -6983,9 +7047,9 @@
<para>
For approximate-value numbers, the result depends on the
C library. On many systems, this means that
- <function role="sql">ROUND()</function> uses the "round to nearest
- even" rule: A value with any fractional part is rounded
- to the nearest even integer.
+ <function role="sql">ROUND()</function> uses the "round
+ to nearest even" rule: A value with any fractional part
+ is rounded to the nearest even integer.
</para>
</listitem>
@@ -7261,11 +7325,12 @@
Functions that return the current date or time each are evaluated
only once per query at the start of query execution. This means
that multiple references to a function such as
- <function role="sql">NOW()</function> within a single query always produce the
- same result (for our purposes a single query also includes a call
- to a stored routine or trigger and all sub-routines called by that
- routine/trigger). This principle also applies to
- <function role="sql">CURDATE()</function>, <function role="sql">CURTIME()</function>,
+ <function role="sql">NOW()</function> within a single query always
+ produce the same result (for our purposes a single query also
+ includes a call to a stored routine or trigger and all
+ sub-routines called by that routine/trigger). This principle also
+ applies to <function role="sql">CURDATE()</function>,
+ <function role="sql">CURTIME()</function>,
<literal>UTC_DATE()</literal>, <literal>UTC_TIME()</literal>,
<literal>UTC_TIMESTAMP()</literal>, and to any of their synonyms.
</para>
@@ -7332,13 +7397,13 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">ADDDATE()</function> is a synonym for
- <literal>DATE_ADD()</literal>. The related function
- <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">ADDDATE()</function> is
+ a synonym for <literal>DATE_ADD()</literal>. The related
+ function <function role="sql">SUBDATE()</function> is a
+ synonym for <literal>DATE_SUB()</literal>. For information on
+ the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -8451,8 +8516,9 @@
<remark role="help-description-begin"/>
<para>
- The <function role="sql">EXTRACT()</function> function uses the same kinds
- of unit specifiers as <literal>DATE_ADD()</literal> or
+ The <function role="sql">EXTRACT()</function> function uses
+ the same kinds of unit specifiers as
+ <literal>DATE_ADD()</literal> or
<literal>DATE_SUB()</literal>, but extracts parts from the
date rather than performing date arithmetic.
</para>
@@ -8817,7 +8883,8 @@
<primary>LOCALTIME</primary>
</indexterm>
- <literal>LOCALTIME</literal>, <function role="sql">LOCALTIME()</function>
+ <literal>LOCALTIME</literal>,
+ <function role="sql">LOCALTIME()</function>
</para>
<remark role="help-syntax-end"/>
@@ -8853,8 +8920,8 @@
<para>
<literal>LOCALTIMESTAMP</literal> and
- <function role="sql">LOCALTIMESTAMP()</function> are synonyms for
- <function role="sql">NOW()</function>.
+ <function role="sql">LOCALTIMESTAMP()</function> are synonyms
+ for <function role="sql">NOW()</function>.
</para>
<remark role="help-description-end"/>
@@ -9102,13 +9169,14 @@
</programlisting>
<para>
- <function role="sql">NOW()</function> returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.) This differs from the behavior for
- <function role="sql">SYSDATE()</function>, which returns the exact time at
- which it executes.
+ <function role="sql">NOW()</function> returns a constant time
+ that indicates the time at which the statement began to
+ execute. (Within a stored routine or trigger,
+ <function role="sql">NOW()</function> returns the time at
+ which the routine or triggering statement began to execute.)
+ This differs from the behavior for
+ <function role="sql">SYSDATE()</function>, which returns the
+ exact time at which it executes.
</para>
<programlisting>
@@ -9128,9 +9196,9 @@
</programlisting>
<para>
- See the description for <function role="sql">SYSDATE()</function> for
- additional information about the differences between the two
- functions.
+ See the description for
+ <function role="sql">SYSDATE()</function> for additional
+ information about the differences between the two functions.
</para>
</listitem>
@@ -9443,11 +9511,11 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">SUBDATE()</function> is
+ a synonym for <literal>DATE_SUB()</literal>. For information
+ on the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -9540,13 +9608,13 @@
</para>
<para>
- <function role="sql">SYSDATE()</function> returns the time at which it
- executes. This differs from the behavior for
- <function role="sql">NOW()</function>, which returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.)
+ <function role="sql">SYSDATE()</function> returns the time at
+ which it executes. This differs from the behavior for
+ <function role="sql">NOW()</function>, which returns a
+ constant time that indicates the time at which the statement
+ began to execute. (Within a stored routine or trigger,
+ <function role="sql">NOW()</function> returns the time at
+ which the routine or triggering statement began to execute.)
</para>
<programlisting>
@@ -9567,24 +9635,26 @@
<para>
In addition, the <literal>SET TIMESTAMP</literal> statement
- affects the value returned by <function role="sql">NOW()</function> but not
- by <function role="sql">SYSDATE()</function>. This means that timestamp
- settings in the binary log have no effect on invocations of
- <function role="sql">SYSDATE()</function>.
+ affects the value returned by
+ <function role="sql">NOW()</function> but not by
+ <function role="sql">SYSDATE()</function>. This means that
+ timestamp settings in the binary log have no effect on
+ invocations of <function role="sql">SYSDATE()</function>.
</para>
<para>
- Because <function role="sql">SYSDATE()</function> can return different
- values even within the same statement, and is not affected by
- <literal>SET TIMESTAMP</literal>, it is non-deterministic and
- therefore unsafe for replication if statement-based binary
- logging is used. If that is a problem, you can use row-based
- logging, or start the server with the
+ Because <function role="sql">SYSDATE()</function> can return
+ different values even within the same statement, and is not
+ affected by <literal>SET TIMESTAMP</literal>, it is
+ non-deterministic and therefore unsafe for replication if
+ statement-based binary logging is used. If that is a problem,
+ you can use row-based logging, or start the server with the
<option>--sysdate-is-now</option> option to cause
<function role="sql">SYSDATE()</function> to be an alias for
- <function role="sql">NOW()</function>. The non-deterministic nature of
- <function role="sql">SYSDATE()</function> also means that indexes cannot be
- used for evaluating expressions that refer to it.
+ <function role="sql">NOW()</function>. The non-deterministic
+ nature of <function role="sql">SYSDATE()</function> also means
+ that indexes cannot be used for evaluating expressions that
+ refer to it.
</para>
<remark role="help-description-end"/>
@@ -10166,10 +10236,10 @@
<para>
This function returns the week number for
<replaceable>date</replaceable>. The two-argument form of
- <function role="sql">WEEK()</function> allows you to specify whether the
- week starts on Sunday or Monday and whether the return value
- should be in the range from <literal>0</literal> to
- <literal>53</literal> or from <literal>1</literal> to
+ <function role="sql">WEEK()</function> allows you to specify
+ whether the week starts on Sunday or Monday and whether the
+ return value should be in the range from <literal>0</literal>
+ to <literal>53</literal> or from <literal>1</literal> to
<literal>53</literal>. If the <replaceable>mode</replaceable>
argument is omitted, the value of the
<literal>default_week_format</literal> system variable is
@@ -10282,13 +10352,14 @@
<para>
One might argue that MySQL should return <literal>52</literal>
- for the <function role="sql">WEEK()</function> function, because the given
- date actually occurs in the 52nd week of 1999. We decided to
- return <literal>0</literal> instead because we want the
- function to return <quote>the week number in the given
- year.</quote> This makes use of the <function role="sql">WEEK()</function>
- function reliable when combined with other functions that
- extract a date part from a date.
+ for the <function role="sql">WEEK()</function> function,
+ because the given date actually occurs in the 52nd week of
+ 1999. We decided to return <literal>0</literal> instead
+ because we want the function to return <quote>the week number
+ in the given year.</quote> This makes use of the
+ <function role="sql">WEEK()</function> function reliable when
+ combined with other functions that extract a date part from a
+ date.
</para>
<para>
@@ -10305,7 +10376,8 @@
</programlisting>
<para>
- Alternatively, use the <function role="sql">YEARWEEK()</function> function:
+ Alternatively, use the
+ <function role="sql">YEARWEEK()</function> function:
</para>
<programlisting>
@@ -10371,8 +10443,8 @@
<para>
Returns the calendar week of the date as a number in the range
from <literal>1</literal> to <literal>53</literal>.
- <function role="sql">WEEKOFYEAR()</function> is a compatibility function
- that is equivalent to
+ <function role="sql">WEEKOFYEAR()</function> is a
+ compatibility function that is equivalent to
<literal>WEEK(<replaceable>date</replaceable>,3)</literal>.
</para>
@@ -10441,9 +10513,9 @@
Returns year and week for a date. The
<replaceable>mode</replaceable> argument works exactly like
the <replaceable>mode</replaceable> argument to
- <function role="sql">WEEK()</function>. The year in the result may be
- different from the year in the date argument for the first and
- the last week of the year.
+ <function role="sql">WEEK()</function>. The year in the result
+ may be different from the year in the date argument for the
+ first and the last week of the year.
</para>
<remark role="help-description-end"/>
@@ -10460,8 +10532,8 @@
<function role="sql">WEEK()</function> function would return
(<literal>0</literal>) for optional arguments
<literal>0</literal> or <literal>1</literal>, as
- <function role="sql">WEEK()</function> then returns the week in the context
- of the given year.
+ <function role="sql">WEEK()</function> then returns the week
+ in the context of the given year.
</para>
</listitem>
@@ -16804,9 +16876,9 @@
<para>
Sleeps (pauses) for the number of seconds given by the
<replaceable>duration</replaceable> argument, then returns
- 0. If <function role="sql">SLEEP()</function> is interrupted, it returns
- 1. The duration may have a fractional part given in
- microseconds.
+ 0. If <function role="sql">SLEEP()</function> is
+ interrupted, it returns 1. The duration may have a
+ fractional part given in microseconds.
</para>
<remark role="help-description-end"/>
Modified: trunk/refman-6.0/functions-core.xml
===================================================================
--- trunk/refman-6.0/functions-core.xml 2007-12-05 02:30:44 UTC (rev 9113)
+++ trunk/refman-6.0/functions-core.xml 2007-12-05 02:31:04 UTC (rev 9114)
Changed blocks: 54, Lines Added: 258, Lines Deleted: 187; 37854 bytes
@@ -1893,11 +1893,12 @@
If <replaceable>expr1</replaceable> is <literal>TRUE</literal>
(<literal><replaceable>expr1</replaceable> <>
0</literal> and <literal><replaceable>expr1</replaceable>
- <> NULL</literal>) then <function role="sql">IF()</function> returns
+ <> NULL</literal>) then
+ <function role="sql">IF()</function> returns
<replaceable>expr2</replaceable>; otherwise it returns
- <replaceable>expr3</replaceable>. <function role="sql">IF()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr3</replaceable>.
+ <function role="sql">IF()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -1917,8 +1918,8 @@
If only one of <replaceable>expr2</replaceable> or
<replaceable>expr3</replaceable> is explicitly
<literal>NULL</literal>, the result type of the
- <function role="sql">IF()</function> function is the type of the
- non-<literal>NULL</literal> expression.
+ <function role="sql">IF()</function> function is the type of
+ the non-<literal>NULL</literal> expression.
</para>
<para>
@@ -1945,9 +1946,9 @@
</para>
<para>
- The default return type of <function role="sql">IF()</function> (which may
- matter when it is stored into a temporary table) is calculated
- as follows:
+ The default return type of
+ <function role="sql">IF()</function> (which may matter when it
+ is stored into a temporary table) is calculated as follows:
</para>
<informaltable>
@@ -1988,8 +1989,9 @@
<para>
There is also an <literal>IF</literal>
<emphasis>statement</emphasis>, which differs from the
- <function role="sql">IF()</function> <emphasis>function</emphasis>
- described here. See <xref linkend="if-statement"/>.
+ <function role="sql">IF()</function>
+ <emphasis>function</emphasis> described here. See
+ <xref linkend="if-statement"/>.
</para>
</note>
</listitem>
@@ -2018,11 +2020,12 @@
<para>
If <replaceable>expr1</replaceable> is not
- <literal>NULL</literal>, <function role="sql">IFNULL()</function> returns
+ <literal>NULL</literal>,
+ <function role="sql">IFNULL()</function> returns
<replaceable>expr1</replaceable>; otherwise it returns
- <replaceable>expr2</replaceable>. <function role="sql">IFNULL()</function>
- returns a numeric or string value, depending on the context in
- which it is used.
+ <replaceable>expr2</replaceable>.
+ <function role="sql">IFNULL()</function> returns a numeric or
+ string value, depending on the context in which it is used.
</para>
<remark role="help-description-end"/>
@@ -2047,8 +2050,8 @@
the order <literal>STRING</literal>, <literal>REAL</literal>,
or <literal>INTEGER</literal>. Consider the case of a table
based on expressions or where MySQL must internally store a
- value returned by <function role="sql">IFNULL()</function> in a temporary
- table:
+ value returned by <function role="sql">IFNULL()</function> in
+ a temporary table:
</para>
<programlisting>
@@ -2179,7 +2182,8 @@
<literal>0</literal> if <replaceable>str</replaceable> is the
empty string. Returns <literal>NULL</literal> if
<replaceable>str</replaceable> is <literal>NULL</literal>.
- <function role="sql">ASCII()</function> works for 8-bit characters.
+ <function role="sql">ASCII()</function> works for 8-bit
+ characters.
</para>
<remark role="help-description-end"/>
@@ -2288,10 +2292,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">CHAR()</function> interprets each argument
- <replaceable>N</replaceable> as an integer and returns a
- string consisting of the characters given by the code values
- of those integers. <literal>NULL</literal> values are skipped.
+ <function role="sql">CHAR()</function> interprets each
+ argument <replaceable>N</replaceable> as an integer and
+ returns a string consisting of the characters given by the
+ code values of those integers. <literal>NULL</literal> values
+ are skipped.
</para>
<remark role="help-description-end"/>
@@ -2306,8 +2311,8 @@
</programlisting>
<para>
- <function role="sql">CHAR()</function> arguments larger than 255 are
- converted into multiple result bytes. For example,
+ <function role="sql">CHAR()</function> arguments larger than
+ 255 are converted into multiple result bytes. For example,
<literal>CHAR(256)</literal> is equivalent to
<literal>CHAR(1,0)</literal>, and
<literal>CHAR(256*256)</literal> is equivalent to
@@ -2332,9 +2337,9 @@
<remark role="help-description-begin"/>
<para>
- By default, <function role="sql">CHAR()</function> returns a binary string.
- To produce a string in a given character set, use the optional
- <literal>USING</literal> clause:
+ By default, <function role="sql">CHAR()</function> returns a
+ binary string. To produce a string in a given character set,
+ use the optional <literal>USING</literal> clause:
</para>
<programlisting>
@@ -2350,7 +2355,8 @@
If <literal>USING</literal> is given and the result string is
illegal for the given character set, a warning is issued.
Also, if strict SQL mode is enabled, the result from
- <function role="sql">CHAR()</function> becomes <literal>NULL</literal>.
+ <function role="sql">CHAR()</function> becomes
+ <literal>NULL</literal>.
</para>
<remark role="help-description-end"/>
@@ -2378,9 +2384,9 @@
<replaceable>str</replaceable>, measured in characters. A
multi-byte character counts as a single character. This means
that for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -2620,18 +2626,18 @@
</para>
<para>
- If all arguments to <function role="sql">FIELD()</function> are strings,
- all arguments are compared as strings. If all arguments are
- numbers, they are compared as numbers. Otherwise, the
- arguments are compared as double.
+ If all arguments to <function role="sql">FIELD()</function>
+ are strings, all arguments are compared as strings. If all
+ arguments are numbers, they are compared as numbers.
+ Otherwise, the arguments are compared as double.
</para>
<para>
If <replaceable>str</replaceable> is <literal>NULL</literal>,
the return value is <literal>0</literal> because
<literal>NULL</literal> fails equality comparison with any
- value. <function role="sql">FIELD()</function> is the complement of
- <function role="sql">ELT()</function>.
+ value. <function role="sql">FIELD()</function> is the
+ complement of <function role="sql">ELT()</function>.
</para>
<remark role="help-description-end"/>
@@ -2856,8 +2862,8 @@
Returns the position of the first occurrence of substring
<replaceable>substr</replaceable> in string
<replaceable>str</replaceable>. This is the same as the
- two-argument form of <function role="sql">LOCATE()</function>, except that
- the order of the arguments is reversed.
+ two-argument form of <function role="sql">LOCATE()</function>,
+ except that the order of the arguments is reversed.
</para>
<remark role="help-description-end"/>
@@ -2958,9 +2964,9 @@
<replaceable>str</replaceable>, measured in bytes. A
multi-byte character counts as multiple bytes. This means that
for a string containing five two-byte characters,
- <function role="sql">LENGTH()</function> returns <literal>10</literal>,
- whereas <literal>CHAR_LENGTH()</literal> returns
- <literal>5</literal>.
+ <function role="sql">LENGTH()</function> returns
+ <literal>10</literal>, whereas
+ <literal>CHAR_LENGTH()</literal> returns <literal>5</literal>.
</para>
<remark role="help-description-end"/>
@@ -3316,8 +3322,8 @@
<para>
If the leftmost character is not a multi-byte character,
- <function role="sql">ORD()</function> returns the same value as the
- <function role="sql">ASCII()</function> function.
+ <function role="sql">ORD()</function> returns the same value
+ as the <function role="sql">ASCII()</function> function.
</para>
<remark role="help-description-end"/>
@@ -3456,8 +3462,9 @@
Returns the string <replaceable>str</replaceable> with all
occurrences of the string <replaceable>from_str</replaceable>
replaced by the string <replaceable>to_str</replaceable>.
- <function role="sql">REPLACE()</function> performs a case-sensitive match
- when searching for <replaceable>from_str</replaceable>.
+ <function role="sql">REPLACE()</function> performs a
+ case-sensitive match when searching for
+ <replaceable>from_str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -3649,11 +3656,11 @@
soundex strings. A standard soundex string is four characters
long, but the <function role="sql">SOUNDEX()</function>
function returns an arbitrarily long string. You can use
- <function role="sql">SUBSTRING()</function> on the result to get a standard
- soundex string. All non-alphabetic characters in
- <replaceable>str</replaceable> are ignored. All international
- alphabetic characters outside the A-Z range are treated as
- vowels.
+ <function role="sql">SUBSTRING()</function> on the result to
+ get a standard soundex string. All non-alphabetic characters
+ in <replaceable>str</replaceable> are ignored. All
+ international alphabetic characters outside the A-Z range are
+ treated as vowels.
</para>
<important>
@@ -3775,6 +3782,37 @@
</listitem>
<listitem>
+ <remark role="help-topic" condition="SUBSTR"/>
+
+ <remark role="help-syntax-begin"/>
+
+ <para id="function_substr">
+ <indexterm>
+ <primary>SUBSTR()</primary>
+ </indexterm>
+
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable>,<replaceable>pos</replaceable>,<replaceable>len</replaceable>)</literal>,
+ <literal>SUBSTR(<replaceable>str</replaceable> FROM
+ <replaceable>pos</replaceable> FOR
+ <replaceable>len</replaceable>)</literal>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">SUBSTR()</function> is a synonym for
+ <function role="sql">SUBSTRING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
<remark role="help-topic" condition="SUBSTRING"/>
<remark role="help-syntax-begin"/>
@@ -3784,10 +3822,6 @@
<primary>SUBSTRING()</primary>
</indexterm>
- <indexterm>
- <primary>SUBSTR()</primary>
- </indexterm>
-
<literal>SUBSTRING(<replaceable>str</replaceable>,<replaceable>pos</replaceable>)</literal>,
<literal>SUBSTRING(<replaceable>str</replaceable> FROM
<replaceable>pos</replaceable>)</literal>,
@@ -3819,9 +3853,10 @@
</para>
<para>
- For all forms of <function role="sql">SUBSTRING()</function>, the position
- of the first character in the string from which the substring
- is to be extracted is reckoned as <literal>1</literal>.
+ For all forms of <function role="sql">SUBSTRING()</function>,
+ the position of the first character in the string from which
+ the substring is to be extracted is reckoned as
+ <literal>1</literal>.
</para>
<remark role="help-description-end"/>
@@ -3851,11 +3886,6 @@
If <replaceable>len</replaceable> is less than 1, the result
is the empty string.
</para>
-
- <para>
- <function role="sql">SUBSTR()</function> is a synonym for
- <function role="sql">SUBSTRING()</function>.
- </para>
</listitem>
<listitem>
@@ -4031,9 +4061,10 @@
hexadecimal digits: <literal>'0'</literal> ..
<literal>'9'</literal>, <literal>'A'</literal> ..
<literal>'F'</literal>, <literal>'a'</literal> ..
- <literal>'f'</literal>. If <function role="sql">UNHEX()</function>
- encounters any non-hexadecimal digits in the argument, it
- returns <literal>NULL</literal>:
+ <literal>'f'</literal>. If
+ <function role="sql">UNHEX()</function> encounters any
+ non-hexadecimal digits in the argument, it returns
+ <literal>NULL</literal>:
</para>
<programlisting>
@@ -4047,23 +4078,23 @@
<para>
A <literal>NULL</literal> result can occur if the argument to
- <function role="sql">UNHEX()</function> is a <literal>BINARY</literal>
- column, because values are padded with 0x00 bytes when stored
- but those bytes are not stripped on retrieval. For example
- <literal>'aa'</literal> is stored into a
- <literal>CHAR(3)</literal> column as
+ <function role="sql">UNHEX()</function> is a
+ <literal>BINARY</literal> column, because values are padded
+ with 0x00 bytes when stored but those bytes are not stripped
+ on retrieval. For example <literal>'aa'</literal> is stored
+ into a <literal>CHAR(3)</literal> column as
<literal>'aa '</literal> and retrieved as
<literal>'aa'</literal> (with the trailing pad space
- stripped), so <function role="sql">UNHEX()</function> for the column value
- returns <literal>'A'</literal>. By contrast
+ stripped), so <function role="sql">UNHEX()</function> for the
+ column value returns <literal>'A'</literal>. By contrast
<literal>'aa'</literal> is stored into a
<literal>BINARY(3)</literal> column as
<literal>'aa\0'</literal> and retrieved as
<literal>'aa\0'</literal> (with the trailing pad
<literal>0x00</literal> byte not stripped).
<literal>'\0'</literal> is not a legal hexadecimal digit, so
- <function role="sql">UNHEX()</function> for the column value returns
- <literal>NULL</literal>.
+ <function role="sql">UNHEX()</function> for the column value
+ returns <literal>NULL</literal>.
</para>
</listitem>
@@ -4906,10 +4937,11 @@
<remark role="help-description-begin"/>
<para>
- <function role="sql">STRCMP()</function> returns <literal>0</literal> if
- the strings are the same, <literal>-1</literal> if the first
- argument is smaller than the second according to the current
- sort order, and <literal>1</literal> otherwise.
+ <function role="sql">STRCMP()</function> returns
+ <literal>0</literal> if the strings are the same,
+ <literal>-1</literal> if the first argument is smaller than
+ the second according to the current sort order, and
+ <literal>1</literal> otherwise.
</para>
<remark role="help-description-end"/>
@@ -4926,10 +4958,10 @@
</programlisting>
<para>
- <function role="sql">STRCMP()</function> uses the current character set
- when performing comparisons. This makes the default
- comparison behavior case insensitive unless one or both of
- the operands are binary strings.
+ <function role="sql">STRCMP()</function> uses the current
+ character set when performing comparisons. This makes the
+ default comparison behavior case insensitive unless one or
+ both of the operands are binary strings.
</para>
</listitem>
@@ -6057,8 +6089,9 @@
<remark role="help-description-begin"/>
<para>
- Integer division. Similar to <function role="sql">FLOOR()</function>, but
- is safe with <literal>BIGINT</literal> values.
+ Integer division. Similar to
+ <function role="sql">FLOOR()</function>, but is safe with
+ <literal>BIGINT</literal> values.
</para>
<remark role="help-description-end"/>
@@ -6335,7 +6368,7 @@
</listitem>
<listitem>
- <remark role="help-topic" condition="CEILING"/>
+ <remark role="help-topic" condition="CEIL"/>
<remark role="help-keywords">
CEIL
@@ -6343,13 +6376,41 @@
<remark role="help-syntax-begin"/>
+ <para id="function_ceil">
+ <indexterm>
+ <primary>CEIL()</primary>
+ </indexterm>
+
+ <function role="sql">CEIL(<replaceable>X</replaceable>)</function>
+ </para>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ <function role="sql">CEIL()</function> is a synonym for
+ <function role="sql">CEILING()</function>.
+ </para>
+
+ <remark role="help-description-end"/>
+ </listitem>
+
+ <listitem>
+ <remark role="help-topic" condition="CEILING"/>
+
+ <remark role="help-keywords">
+ CEILING
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
<para id="function_ceiling">
<indexterm>
<primary>CEILING()</primary>
</indexterm>
- <literal>CEILING(<replaceable>X</replaceable>)</literal>,
- <literal>CEIL(<replaceable>X</replaceable>)</literal>
+ <function role="sql">CEILING(<replaceable>X</replaceable>)</function>
</para>
<remark role="help-syntax-end"/>
@@ -6358,8 +6419,7 @@
<para>
Returns the smallest integer value not less than
- <replaceable>X</replaceable>. <function role="sql">CEILING()</function>
- and <function role="sql">CEIL()</function> are synonymous.
+ <replaceable>X</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -6369,7 +6429,7 @@
<programlisting>
mysql> <userinput>SELECT CEILING(1.23);</userinput>
-> 2
-mysql> <userinput>SELECT CEIL(-1.23);</userinput>
+mysql> <userinput>SELECT CEILING(-1.23);</userinput>
-> -1
</programlisting>
@@ -6412,7 +6472,8 @@
is a negative number, <replaceable>N</replaceable> is
regarded as a signed number. Otherwise,
<replaceable>N</replaceable> is treated as unsigned.
- <function role="sql">CONV()</function> works with 64-bit precision.
+ <function role="sql">CONV()</function> works with 64-bit
+ precision.
</para>
<remark role="help-description-end"/>
@@ -7167,10 +7228,10 @@
when the statement is compiled, prior to execution. If a
non-constant initializer (such as a column name) is used as
the argument, the seed is initialized with the value for
- each invocation of <function role="sql">RAND()</function>. (One
- implication of this is that for equal argument values,
- <function role="sql">RAND()</function> will return the same value each
- time.)
+ each invocation of <function role="sql">RAND()</function>.
+ (One implication of this is that for equal argument values,
+ <function role="sql">RAND()</function> will return the same
+ value each time.)
</para>
<para>
@@ -7192,11 +7253,11 @@
</programlisting>
<para>
- You cannot use a column with <function role="sql">RAND()</function>
- values in an <literal>ORDER BY</literal> clause, because
- <literal>ORDER BY</literal> would evaluate the column
- multiple times. However, you can retrieve rows in random
- order like this:
+ You cannot use a column with
+ <function role="sql">RAND()</function> values in an
+ <literal>ORDER BY</literal> clause, because <literal>ORDER
+ BY</literal> would evaluate the column multiple times.
+ However, you can retrieve rows in random order like this:
</para>
<programlisting>
@@ -7220,10 +7281,11 @@
</para>
<para>
- <function role="sql">RAND()</function> is not meant to be a perfect
- random generator, but instead is a fast way to generate
- <foreignphrase>ad hoc</foreignphrase> random numbers which
- is portable between platforms for the same MySQL version.
+ <function role="sql">RAND()</function> is not meant to be a
+ perfect random generator, but instead is a fast way to
+ generate <foreignphrase>ad hoc</foreignphrase> random
+ numbers which is portable between platforms for the same
+ MySQL version.
</para>
</listitem>
@@ -7292,17 +7354,18 @@
</programlisting>
<para>
- <function role="sql">ROUND()</function> uses the precision math library
- for exact-value arguments when the first argument is a
- decimal value:
+ <function role="sql">ROUND()</function> uses the precision
+ math library for exact-value arguments when the first
+ argument is a decimal value:
</para>
<itemizedlist>
<listitem>
<para>
- For exact-value numbers, <function role="sql">ROUND()</function> uses
- the <quote>round half up</quote> or <quote>round toward
+ For exact-value numbers,
+ <function role="sql">ROUND()</function> uses the
+ <quote>round half up</quote> or <quote>round toward
nearest</quote> rule: A value with a fractional part of
.5 or greater is rounded up to the next integer if
positive or down to the next integer if negative. (In
@@ -7317,9 +7380,9 @@
<para>
For approximate-value numbers, the result depends on the
C library. On many systems, this means that
- <function role="sql">ROUND()</function> uses the "round to nearest
- even" rule: A value with any fractional part is rounded
- to the nearest even integer.
+ <function role="sql">ROUND()</function> uses the "round
+ to nearest even" rule: A value with any fractional part
+ is rounded to the nearest even integer.
</para>
</listitem>
@@ -7595,11 +7658,12 @@
Functions that return the current date or time each are evaluated
only once per query at the start of query execution. This means
that multiple references to a function such as
- <function role="sql">NOW()</function> within a single query always produce the
- same result (for our purposes a single query also includes a call
- to a stored routine or trigger and all sub-routines called by that
- routine/trigger). This principle also applies to
- <function role="sql">CURDATE()</function>, <function role="sql">CURTIME()</function>,
+ <function role="sql">NOW()</function> within a single query always
+ produce the same result (for our purposes a single query also
+ includes a call to a stored routine or trigger and all
+ sub-routines called by that routine/trigger). This principle also
+ applies to <function role="sql">CURDATE()</function>,
+ <function role="sql">CURTIME()</function>,
<literal>UTC_DATE()</literal>, <literal>UTC_TIME()</literal>,
<literal>UTC_TIMESTAMP()</literal>, and to any of their synonyms.
</para>
@@ -7666,13 +7730,13 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">ADDDATE()</function> is a synonym for
- <literal>DATE_ADD()</literal>. The related function
- <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">ADDDATE()</function> is
+ a synonym for <literal>DATE_ADD()</literal>. The related
+ function <function role="sql">SUBDATE()</function> is a
+ synonym for <literal>DATE_SUB()</literal>. For information on
+ the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -8776,8 +8840,9 @@
<remark role="help-description-begin"/>
<para>
- The <function role="sql">EXTRACT()</function> function uses the same kinds
- of unit specifiers as <literal>DATE_ADD()</literal> or
+ The <function role="sql">EXTRACT()</function> function uses
+ the same kinds of unit specifiers as
+ <literal>DATE_ADD()</literal> or
<literal>DATE_SUB()</literal>, but extracts parts from the
date rather than performing date arithmetic.
</para>
@@ -9142,7 +9207,8 @@
<primary>LOCALTIME</primary>
</indexterm>
- <literal>LOCALTIME</literal>, <function role="sql">LOCALTIME()</function>
+ <literal>LOCALTIME</literal>,
+ <function role="sql">LOCALTIME()</function>
</para>
<remark role="help-syntax-end"/>
@@ -9178,8 +9244,8 @@
<para>
<literal>LOCALTIMESTAMP</literal> and
- <function role="sql">LOCALTIMESTAMP()</function> are synonyms for
- <function role="sql">NOW()</function>.
+ <function role="sql">LOCALTIMESTAMP()</function> are synonyms
+ for <function role="sql">NOW()</function>.
</para>
<remark role="help-description-end"/>
@@ -9427,13 +9493,14 @@
</programlisting>
<para>
- <function role="sql">NOW()</function> returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.) This differs from the behavior for
- <function role="sql">SYSDATE()</function>, which returns the exact time at
- which it executes.
+ <function role="sql">NOW()</function> returns a constant time
+ that indicates the time at which the statement began to
+ execute. (Within a stored routine or trigger,
+ <function role="sql">NOW()</function> returns the time at
+ which the routine or triggering statement began to execute.)
+ This differs from the behavior for
+ <function role="sql">SYSDATE()</function>, which returns the
+ exact time at which it executes.
</para>
<programlisting>
@@ -9453,9 +9520,9 @@
</programlisting>
<para>
- See the description for <function role="sql">SYSDATE()</function> for
- additional information about the differences between the two
- functions.
+ See the description for
+ <function role="sql">SYSDATE()</function> for additional
+ information about the differences between the two functions.
</para>
</listitem>
@@ -9768,11 +9835,11 @@
<para>
When invoked with the <literal>INTERVAL</literal> form of the
- second argument, <function role="sql">SUBDATE()</function> is a synonym for
- <literal>DATE_SUB()</literal>. For information on the
- <literal>INTERVAL</literal> <replaceable>unit</replaceable>
- argument, see the discussion for
- <literal>DATE_ADD()</literal>.
+ second argument, <function role="sql">SUBDATE()</function> is
+ a synonym for <literal>DATE_SUB()</literal>. For information
+ on the <literal>INTERVAL</literal>
+ <replaceable>unit</replaceable> argument, see the discussion
+ for <literal>DATE_ADD()</literal>.
</para>
<programlisting>
@@ -9865,13 +9932,13 @@
</para>
<para>
- <function role="sql">SYSDATE()</function> returns the time at which it
- executes. This differs from the behavior for
- <function role="sql">NOW()</function>, which returns a constant time that
- indicates the time at which the statement began to execute.
- (Within a stored routine or trigger, <function role="sql">NOW()</function>
- returns the time at which the routine or triggering statement
- began to execute.)
+ <function role="sql">SYSDATE()</function> returns the time at
+ which it executes. This differs from the behavior for
+ <function role="sql">NOW()</function>, which returns a
+ constant time that indicates the time at which the statement
+ began to execute. (Within a stored routine or trigger,
+ <function role="sql">NOW()</function> returns the time at
+ which the routine or triggering statement began to execute.)
</para>
<programlisting>
@@ -9892,24 +9959,26 @@
<para>
In addition, the <literal>SET TIMESTAMP</literal> statement
- affects the value returned by <function role="sql">NOW()</function> but not
- by <function role="sql">SYSDATE()</function>. This means that timestamp
- settings in the binary log have no effect on invocations of
- <function role="sql">SYSDATE()</function>.
+ affects the value returned by
+ <function role="sql">NOW()</function> but not by
+ <function role="sql">SYSDATE()</function>. This means that
+ timestamp settings in the binary log have no effect on
+ invocations of <function role="sql">SYSDATE()</function>.
</para>
<para>
- Because <function role="sql">SYSDATE()</function> can return different
- values even within the same statement, and is not affected by
- <literal>SET TIMESTAMP</literal>, it is non-deterministic and
- therefore unsafe for replication if statement-based binary
- logging is used. If that is a problem, you can use row-based
- logging, or start the server with the
+ Because <function role="sql">SYSDATE()</function> can return
+ different values even within the same statement, and is not
+ affected by <literal>SET TIMESTAMP</literal>, it is
+ non-deterministic and therefore unsafe for replication if
+ statement-based binary logging is used. If that is a problem,
+ you can use row-based logging, or start the server with the
<option>--sysdate-is-now</option> option to cause
<function role="sql">SYSDATE()</function> to be an alias for
- <function role="sql">NOW()</function>. The non-deterministic nature of
- <function role="sql">SYSDATE()</function> also means that indexes cannot be
- used for evaluating expressions that refer to it.
+ <function role="sql">NOW()</function>. The non-deterministic
+ nature of <function role="sql">SYSDATE()</function> also means
+ that indexes cannot be used for evaluating expressions that
+ refer to it.
</para>
<remark role="help-description-end"/>
@@ -10491,10 +10560,10 @@
<para>
This function returns the week number for
<replaceable>date</replaceable>. The two-argument form of
- <function role="sql">WEEK()</function> allows you to specify whether the
- week starts on Sunday or Monday and whether the return value
- should be in the range from <literal>0</literal> to
- <literal>53</literal> or from <literal>1</literal> to
+ <function role="sql">WEEK()</function> allows you to specify
+ whether the week starts on Sunday or Monday and whether the
+ return value should be in the range from <literal>0</literal>
+ to <literal>53</literal> or from <literal>1</literal> to
<literal>53</literal>. If the <replaceable>mode</replaceable>
argument is omitted, the value of the
<literal>default_week_format</literal> system variable is
@@ -10607,13 +10676,14 @@
<para>
One might argue that MySQL should return <literal>52</literal>
- for the <function role="sql">WEEK()</function> function, because the given
- date actually occurs in the 52nd week of 1999. We decided to
- return <literal>0</literal> instead because we want the
- function to return <quote>the week number in the given
- year.</quote> This makes use of the <function role="sql">WEEK()</function>
- function reliable when combined with other functions that
- extract a date part from a date.
+ for the <function role="sql">WEEK()</function> function,
+ because the given date actually occurs in the 52nd week of
+ 1999. We decided to return <literal>0</literal> instead
+ because we want the function to return <quote>the week number
+ in the given year.</quote> This makes use of the
+ <function role="sql">WEEK()</function> function reliable when
+ combined with other functions that extract a date part from a
+ date.
</para>
<para>
@@ -10630,7 +10700,8 @@
</programlisting>
<para>
- Alternatively, use the <function role="sql">YEARWEEK()</function> function:
+ Alternatively, use the
+ <function role="sql">YEARWEEK()</function> function:
</para>
<programlisting>
@@ -10696,8 +10767,8 @@
<para>
Returns the calendar week of the date as a number in the range
from <literal>1</literal> to <literal>53</literal>.
- <function role="sql">WEEKOFYEAR()</function> is a compatibility function
- that is equivalent to
+ <function role="sql">WEEKOFYEAR()</function> is a
+ compatibility function that is equivalent to
<literal>WEEK(<replaceable>date</replaceable>,3)</literal>.
</para>
@@ -10766,9 +10837,9 @@
Returns year and week for a date. The
<replaceable>mode</replaceable> argument works exactly like
the <replaceable>mode</replaceable> argument to
- <function role="sql">WEEK()</function>. The year in the result may be
- different from the year in the date argument for the first and
- the last week of the year.
+ <function role="sql">WEEK()</function>. The year in the result
+ may be different from the year in the date argument for the
+ first and the last week of the year.
</para>
<remark role="help-description-end"/>
@@ -10785,8 +10856,8 @@
<function role="sql">WEEK()</function> function would return
(<literal>0</literal>) for optional arguments
<literal>0</literal> or <literal>1</literal>, as
- <function role="sql">WEEK()</function> then returns the week in the context
- of the given year.
+ <function role="sql">WEEK()</function> then returns the week
+ in the context of the given year.
</para>
</listitem>
@@ -17040,9 +17111,9 @@
<para>
Sleeps (pauses) for the number of seconds given by the
<replaceable>duration</replaceable> argument, then returns
- 0. If <function role="sql">SLEEP()</function> is interrupted, it returns
- 1. The duration may have a fractional part given in
- microseconds.
+ 0. If <function role="sql">SLEEP()</function> is
+ interrupted, it returns 1. The duration may have a
+ fractional part given in microseconds.
</para>
<remark role="help-description-end"/>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r9114 - in trunk: . dynamic-docs/opsfunctions refman-4.1 refman-5.0 refman-5.1 refman-6.0 | paul | 5 Dec |
