bk commit into 5.0 tree (jimw:1.2007)

[Jim Winstead]

Below is the list of changes that have just been committed into a local
5.0 repository of jimw. When jimw does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://dev.mysql.com/doc/mysql/en/installing-source-tree.html

ChangeSet
  1.2007 05/07/05 09:45:32 jimw@stripped +1 -0
  Add documentation to the escape_*() functions in mysys.

  mysys/charset.c
    1.140 05/07/05 09:44:16 jimw@stripped +52 -16
    Add documentation for escape functions
    Minor style cleanup

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	jimw
# Host:	rama.(none)
# Root:	/home/jimw/my/mysql-5.0-10214

--- 1.139/mysys/charset.c	2005-06-23 18:29:50 -07:00
+++ 1.140/mysys/charset.c	2005-07-05 09:44:16 -07:00
@@ -561,11 +561,30 @@
   DBUG_RETURN(cs);
 }
 
+
 /*
+  Escape string with backslashes (\)
+
+  SYNOPSIS
+    escape_string_for_mysql()
+    charset_info        Charset of the strings
+    to                  Buffer for escaped string
+    to_length           Length of destination buffer, or 0
+    from                The string to escape
+    length              The length of the string to escape
+
+  DESCRIPTION
+    This escapes the contents of a string by adding backslashes before special
+    characters, and turning others into specific escape sequences, such as
+    turning newlines into \n and null bytes into \0.
+
   NOTE
-    to keep old C API, to_length may be 0 to mean "big enough"
-  RETURN
-    the length of the escaped string or ~0 if it did not fit.
+    To maintain compatibility with the old C API, to_length may be 0 to mean
+    "big enough"
+
+  RETURN VALUES
+    ~0          The escaped string did not fit in the to buffer
+    >=0         The length of the escaped string
 */
 ulong escape_string_for_mysql(CHARSET_INFO *charset_info,
                               char *to, ulong to_length,
@@ -573,20 +592,20 @@
 {
   const char *to_start= to;
   const char *end, *to_end=to_start + (to_length ? to_length-1 : 2*length);
-  my_bool overflow=0;
+  my_bool overflow= FALSE;
 #ifdef USE_MB
   my_bool use_mb_flag= use_mb(charset_info);
 #endif
   for (end= from + length; from < end; from++)
   {
-    char escape=0;
+    char escape= 0;
 #ifdef USE_MB
     int tmp_length;
     if (use_mb_flag && (tmp_length= my_ismbchar(charset_info, from, end)))
     {
       if (to + tmp_length > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       while (tmp_length--)
@@ -636,7 +655,7 @@
     {
       if (to + 2 > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       *to++= '\\';
@@ -646,7 +665,7 @@
     {
       if (to + 1 > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       *to++= *from;
@@ -658,11 +677,28 @@
 
 
 /*
+  Escape apostrophes by doubling them up
+
+  SYNOPSIS
+    escape_quotes_for_mysql()
+    charset_info        Charset of the strings
+    to                  Buffer for escaped string
+    to_length           Length of destination buffer, or 0
+    from                The string to escape
+    length              The length of the string to escape
+
+  DESCRIPTION
+    This escapes the contents of a string by doubling up any apostrophes that
+    it contains. This is used when the NO_BACKSLASH_ESCAPES SQL_MODE is in
+    effect on the server.
+
   NOTE
-    to be consistent with escape_string_for_mysql(), to_length may be 0 to
+    To be consistent with escape_string_for_mysql(), to_length may be 0 to
     mean "big enough"
-  RETURN
-    the length of the escaped string or ~0 if it did not fit.
+
+  RETURN VALUES
+    ~0          The escaped string did not fit in the to buffer
+    >=0         The length of the escaped string
 */
 ulong escape_quotes_for_mysql(CHARSET_INFO *charset_info,
                               char *to, ulong to_length,
@@ -670,20 +706,20 @@
 {
   const char *to_start= to;
   const char *end, *to_end=to_start + (to_length ? to_length-1 : 2*length);
-  my_bool overflow=0;
+  my_bool overflow= FALSE;
 #ifdef USE_MB
   my_bool use_mb_flag= use_mb(charset_info);
 #endif
   for (end= from + length; from < end; from++)
   {
-    char escape=0;
+    char escape= 0;
 #ifdef USE_MB
     int tmp_length;
     if (use_mb_flag && (tmp_length= my_ismbchar(charset_info, from, end)))
     {
       if (to + tmp_length > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       while (tmp_length--)
@@ -701,7 +737,7 @@
     {
       if (to + 2 > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       *to++= '\'';
@@ -711,7 +747,7 @@
     {
       if (to + 1 > to_end)
       {
-        overflow=1;
+        overflow= TRUE;
         break;
       }
       *to++= *from;