List:Commits« Previous MessageNext Message »
From:paul Date:January 24 2006 4:25pm
Subject:svn commit - mysqldoc@docsrva: r1020 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-24 17:25:43 +0100 (Tue, 24 Jan 2006)
New Revision: 1020

Log:
 r6637@frost:  paul | 2006-01-24 10:24:21 -0600
 BINARY operator description in charset.xml was incorrect
 (conflicted with description in functions.xml).
 Attempt to clarify effect of BINARY and CHARACTER SET data type attributes.


Modified:
   trunk/
   trunk/refman-4.1/charset.xml
   trunk/refman-5.0/charset.xml
   trunk/refman-5.1/charset.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6634
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2449
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6637
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2449

Modified: trunk/refman-4.1/charset.xml
===================================================================
--- trunk/refman-4.1/charset.xml	2006-01-24 16:25:09 UTC (rev 1019)
+++ trunk/refman-4.1/charset.xml	2006-01-24 16:25:43 UTC (rev 1020)
@@ -1447,46 +1447,79 @@
       <title>&title-charset-binary-op;</title>
 
       <para>
-        The <literal>BINARY</literal> operator is a shorthand for a
-        <literal>COLLATE</literal> clause. <literal>BINARY
-        '<replaceable>x</replaceable>'</literal> is equivalent to
-        <literal>'<replaceable>x</replaceable>' COLLATE
-        <replaceable>y</replaceable></literal>, where
-        <replaceable>y</replaceable> is the name of the binary collation
-        for the character set of '<replaceable>x</replaceable>'. Every
-        character set has a binary collation. For example, the binary
-        collation for the <literal>latin1</literal> character set is
-        <literal>latin1_bin</literal>, so if the column
-        <literal>a</literal> is of character set
-        <literal>latin1</literal>, the following two statements have the
-        same effect:
+        The <literal>BINARY</literal> operator casts the string
+        following it to a binary string. This is an easy way to force a
+        comparison to be done byte by byte rather than character by
+        character. <literal>BINARY</literal> also causes trailing spaces
+        to be significant.
       </para>
 
 <programlisting>
-SELECT * FROM t1 ORDER BY BINARY a;
-SELECT * FROM t1 ORDER BY a COLLATE latin1_bin;
+mysql&gt; <userinput>SELECT 'a' = 'A';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'A';</userinput>
+        -&gt; 0
+mysql&gt; <userinput>SELECT 'a' = 'a ';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'a ';</userinput>
+        -&gt; 0
 </programlisting>
 
       <para>
+        <literal>BINARY <replaceable>str</replaceable></literal> is
+        shorthand for <literal>CAST(<replaceable>str</replaceable> AS
+        BINARY)</literal>.
+      </para>
+
+      <para>
         The <literal>BINARY</literal> attribute in character column
-        definitions has a similar effect. A character column defined
+        definitions has a different effect. A character column defined
         with the <literal>BINARY</literal> attribute is assigned the
-        binary collation of the column's character set.
+        binary collation of the column's character set. Every character
+        set has a binary collation. For example, the binary collation
+        for the <literal>latin1</literal> character set is
+        <literal>latin1_bin</literal>, so if the the table default
+        character set is <literal>latin1</literal>, these two column
+        definitions are equivalent:
       </para>
 
+<programlisting>
+CHAR(10) BINARY
+CHAR(10) CHARACTER SET latin1 COLLATE latin1_bin
+</programlisting>
+
       <para>
-        The effect of <literal>BINARY</literal> in both contexts differs
-        from its effect prior to MySQL 4.1. Formerly,
-        <literal>BINARY</literal> resulted in binary string comparisons
-        or binary string column definitions. A binary string is a string
-        of bytes that has no character set or collation, which differs
-        from a non-binary character string that has a binary collation.
-        For both types of strings, comparisons are based on the numeric
+        The effect of <literal>BINARY</literal> as a column attribute
+        differs from its effect prior to MySQL 4.1. Formerly,
+        <literal>BINARY</literal> resulted in a column that was treated
+        as a binary string. A binary string is a string of bytes that
+        has no character set or collation, which differs from a
+        non-binary character string that has a binary collation. For
+        both types of strings, comparisons are based on the numeric
         values of the string unit, but for non-binary strings the unit
         is the character and some character sets allow multi-byte
         characters. <xref linkend="binary-varbinary"/>.
       </para>
 
+      <para>
+        The use of <literal>CHARACTER SET binary</literal> in the
+        definition of a <literal>CHAR</literal>,
+        <literal>VARCHAR</literal>, or <literal>TEXT</literal> column
+        causes the column to be treated as a binary data type. For
+        example, the following pairs of definitions are equivalent:
+      </para>
+
+<programlisting>
+CHAR(10) CHARACTER SET binary
+BINARY(10)
+
+VARCHAR(10) CHARACTER SET binary
+VARBINARY(10)
+
+TEXT CHARACTER SET binary
+BLOB
+</programlisting>
+
     </section>
 
     <section id="charset-collate-tricky">

Modified: trunk/refman-5.0/charset.xml
===================================================================
--- trunk/refman-5.0/charset.xml	2006-01-24 16:25:09 UTC (rev 1019)
+++ trunk/refman-5.0/charset.xml	2006-01-24 16:25:43 UTC (rev 1020)
@@ -1439,46 +1439,79 @@
       <title>&title-charset-binary-op;</title>
 
       <para>
-        The <literal>BINARY</literal> operator is a shorthand for a
-        <literal>COLLATE</literal> clause. <literal>BINARY
-        '<replaceable>x</replaceable>'</literal> is equivalent to
-        <literal>'<replaceable>x</replaceable>' COLLATE
-        <replaceable>y</replaceable></literal>, where
-        <replaceable>y</replaceable> is the name of the binary collation
-        for the character set of '<replaceable>x</replaceable>'. Every
-        character set has a binary collation. For example, the binary
-        collation for the <literal>latin1</literal> character set is
-        <literal>latin1_bin</literal>, so if the column
-        <literal>a</literal> is of character set
-        <literal>latin1</literal>, the following two statements have the
-        same effect:
+        The <literal>BINARY</literal> operator casts the string
+        following it to a binary string. This is an easy way to force a
+        comparison to be done byte by byte rather than character by
+        character. <literal>BINARY</literal> also causes trailing spaces
+        to be significant.
       </para>
 
 <programlisting>
-SELECT * FROM t1 ORDER BY BINARY a;
-SELECT * FROM t1 ORDER BY a COLLATE latin1_bin;
+mysql&gt; <userinput>SELECT 'a' = 'A';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'A';</userinput>
+        -&gt; 0
+mysql&gt; <userinput>SELECT 'a' = 'a ';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'a ';</userinput>
+        -&gt; 0
 </programlisting>
 
       <para>
+        <literal>BINARY <replaceable>str</replaceable></literal> is
+        shorthand for <literal>CAST(<replaceable>str</replaceable> AS
+        BINARY)</literal>.
+      </para>
+
+      <para>
         The <literal>BINARY</literal> attribute in character column
-        definitions has a similar effect. A character column defined
+        definitions has a different effect. A character column defined
         with the <literal>BINARY</literal> attribute is assigned the
-        binary collation of the column's character set.
+        binary collation of the column's character set. Every character
+        set has a binary collation. For example, the binary collation
+        for the <literal>latin1</literal> character set is
+        <literal>latin1_bin</literal>, so if the the table default
+        character set is <literal>latin1</literal>, these two column
+        definitions are equivalent:
       </para>
 
+<programlisting>
+CHAR(10) BINARY
+CHAR(10) CHARACTER SET latin1 COLLATE latin1_bin
+</programlisting>
+
       <para>
-        The effect of <literal>BINARY</literal> in both contexts differs
-        from its effect prior to MySQL 4.1. Formerly,
-        <literal>BINARY</literal> resulted in binary string comparisons
-        or binary string column definitions. A binary string is a string
-        of bytes that has no character set or collation, which differs
-        from a non-binary character string that has a binary collation.
-        For both types of strings, comparisons are based on the numeric
+        The effect of <literal>BINARY</literal> as a column attribute
+        differs from its effect prior to MySQL 4.1. Formerly,
+        <literal>BINARY</literal> resulted in a column that was treated
+        as a binary string. A binary string is a string of bytes that
+        has no character set or collation, which differs from a
+        non-binary character string that has a binary collation. For
+        both types of strings, comparisons are based on the numeric
         values of the string unit, but for non-binary strings the unit
         is the character and some character sets allow multi-byte
         characters. <xref linkend="binary-varbinary"/>.
       </para>
 
+      <para>
+        The use of <literal>CHARACTER SET binary</literal> in the
+        definition of a <literal>CHAR</literal>,
+        <literal>VARCHAR</literal>, or <literal>TEXT</literal> column
+        causes the column to be treated as a binary data type. For
+        example, the following pairs of definitions are equivalent:
+      </para>
+
+<programlisting>
+CHAR(10) CHARACTER SET binary
+BINARY(10)
+
+VARCHAR(10) CHARACTER SET binary
+VARBINARY(10)
+
+TEXT CHARACTER SET binary
+BLOB
+</programlisting>
+
     </section>
 
     <section id="charset-collate-tricky">

Modified: trunk/refman-5.1/charset.xml
===================================================================
--- trunk/refman-5.1/charset.xml	2006-01-24 16:25:09 UTC (rev 1019)
+++ trunk/refman-5.1/charset.xml	2006-01-24 16:25:43 UTC (rev 1020)
@@ -1439,46 +1439,79 @@
       <title>&title-charset-binary-op;</title>
 
       <para>
-        The <literal>BINARY</literal> operator is a shorthand for a
-        <literal>COLLATE</literal> clause. <literal>BINARY
-        '<replaceable>x</replaceable>'</literal> is equivalent to
-        <literal>'<replaceable>x</replaceable>' COLLATE
-        <replaceable>y</replaceable></literal>, where
-        <replaceable>y</replaceable> is the name of the binary collation
-        for the character set of '<replaceable>x</replaceable>'. Every
-        character set has a binary collation. For example, the binary
-        collation for the <literal>latin1</literal> character set is
-        <literal>latin1_bin</literal>, so if the column
-        <literal>a</literal> is of character set
-        <literal>latin1</literal>, the following two statements have the
-        same effect:
+        The <literal>BINARY</literal> operator casts the string
+        following it to a binary string. This is an easy way to force a
+        comparison to be done byte by byte rather than character by
+        character. <literal>BINARY</literal> also causes trailing spaces
+        to be significant.
       </para>
 
 <programlisting>
-SELECT * FROM t1 ORDER BY BINARY a;
-SELECT * FROM t1 ORDER BY a COLLATE latin1_bin;
+mysql&gt; <userinput>SELECT 'a' = 'A';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'A';</userinput>
+        -&gt; 0
+mysql&gt; <userinput>SELECT 'a' = 'a ';</userinput>
+        -&gt; 1
+mysql&gt; <userinput>SELECT BINARY 'a' = 'a ';</userinput>
+        -&gt; 0
 </programlisting>
 
       <para>
+        <literal>BINARY <replaceable>str</replaceable></literal> is
+        shorthand for <literal>CAST(<replaceable>str</replaceable> AS
+        BINARY)</literal>.
+      </para>
+
+      <para>
         The <literal>BINARY</literal> attribute in character column
-        definitions has a similar effect. A character column defined
+        definitions has a different effect. A character column defined
         with the <literal>BINARY</literal> attribute is assigned the
-        binary collation of the column's character set.
+        binary collation of the column's character set. Every character
+        set has a binary collation. For example, the binary collation
+        for the <literal>latin1</literal> character set is
+        <literal>latin1_bin</literal>, so if the the table default
+        character set is <literal>latin1</literal>, these two column
+        definitions are equivalent:
       </para>
 
+<programlisting>
+CHAR(10) BINARY
+CHAR(10) CHARACTER SET latin1 COLLATE latin1_bin
+</programlisting>
+
       <para>
-        The effect of <literal>BINARY</literal> in both contexts differs
-        from its effect prior to MySQL 4.1. Formerly,
-        <literal>BINARY</literal> resulted in binary string comparisons
-        or binary string column definitions. A binary string is a string
-        of bytes that has no character set or collation, which differs
-        from a non-binary character string that has a binary collation.
-        For both types of strings, comparisons are based on the numeric
+        The effect of <literal>BINARY</literal> as a column attribute
+        differs from its effect prior to MySQL 4.1. Formerly,
+        <literal>BINARY</literal> resulted in a column that was treated
+        as a binary string. A binary string is a string of bytes that
+        has no character set or collation, which differs from a
+        non-binary character string that has a binary collation. For
+        both types of strings, comparisons are based on the numeric
         values of the string unit, but for non-binary strings the unit
         is the character and some character sets allow multi-byte
         characters. <xref linkend="binary-varbinary"/>.
       </para>
 
+      <para>
+        The use of <literal>CHARACTER SET binary</literal> in the
+        definition of a <literal>CHAR</literal>,
+        <literal>VARCHAR</literal>, or <literal>TEXT</literal> column
+        causes the column to be treated as a binary data type. For
+        example, the following pairs of definitions are equivalent:
+      </para>
+
+<programlisting>
+CHAR(10) CHARACTER SET binary
+BINARY(10)
+
+VARCHAR(10) CHARACTER SET binary
+VARBINARY(10)
+
+TEXT CHARACTER SET binary
+BLOB
+</programlisting>
+
     </section>
 
     <section id="charset-collate-tricky">

Thread
svn commit - mysqldoc@docsrva: r1020 - in trunk: . refman-4.1 refman-5.0 refman-5.1paul24 Jan