Changes to comments. In particular, a lengthy comment was added to encode.c

that explains how the encoder algorithm works. (CVS 966)

FossilOrigin-Name: 8b388b2f690dbfd50eefc0fdede1c7785f78afa1

manifest

@@ -1,5 +1,5 @@
-C Removed\snever-used\ssymbol\sSQLITE_ResultDetails.\s(CVS\s965)
+C Changes\sto\scomments.\s\sIn\sparticular,\sa\slengthy\scomment\swas\sadded\sto\sencode.c\r\nthat\sexplains\show\sthe\sencoder\salgorithm\sworks.\s(CVS\s966)
-D 2003-05-10T03:04:34
+D 2003-05-10T03:36:54
 F Makefile.in 004acec253ecdde985c8ecd5b7c9accdb210378f
 F Makefile.linux-gcc b86a99c493a5bfb402d1d9178dcdc4bd4b32f906
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -20,14 +20,14 @@ F spec.template 238f7db425a78dc1bb7682e56e3834c7270a3f5e
 F sqlite.1 83f4a9d37bdf2b7ef079a82d54eaf2e3509ee6ea
 F sqlite.pc.in 30552343140c53304c2a658c080fbe810cd09ca2
 F src/attach.c 7ebc7487de43e357a64226f8abef81f2669f2183
-F src/auth.c 53b8923f17f364af84501fa99dc00c779913a26d
+F src/auth.c c8f50d4507e37779d96ff3c55417bc2b612dfed6
 F src/btree.c 077d75aee4ed63f3628698611ba43c87097d458d
 F src/btree.h 23c50e00709de16a5dce1fcea9c0429cc955ff0e
 F src/btree_rb.c 8e00e40be264716e1929987878672e55d9e0e76d
 F src/build.c e24461d42381a36de88de6af06c03d9f14588705
 F src/copy.c 44b13fd4d2444fb53bff8a5ecee1c5f6f86a8263
 F src/delete.c f9536a75b444a21f11b7a1bc0fb8c876f691b013
-F src/encode.c faf03741efe921755ec371cf4a6984536de00042
+F src/encode.c ed720e54ec4ef4d4de651592f1dd1c74d422bbd2
 F src/expr.c a666ef5220ca90ebcf40c8ccc783966a345a7616
 F src/func.c 882c3ed5a02be18cd904715c7ec62947a34a3605
 F src/hash.c 4fc39feb7b7711f6495ee9f2159559bedb043e1f
@@ -59,7 +59,7 @@ F src/trigger.c 8ee811986080de60d9d883ad96daffea82014f27
 F src/update.c dc3b680b4cf2cb6d839950b68d632850746639b9
 F src/util.c 87635cfdfffa056a8d3147719357aa442374f78c
 F src/vacuum.c 14ac3073203fa021e01ffe33db56968ad79a8344
-F src/vdbe.c 829fa31c2169588db7a041950cb95c6bb75811a6
+F src/vdbe.c e9e560b0c568fb4ffb189d3e0d91628a33d2a367
 F src/vdbe.h 985c24f312d10f9ef8f9a8b8ea62fcdf68e82f21
 F src/where.c ef11773a07cf075740378d7d1cbabf328146fdc9
 F test/all.test 569a92a8ee88f5300c057cc4a8f50fbbc69a3242
@@ -165,7 +165,7 @@ F www/speed.tcl cb4c10a722614aea76d2c51f32ee43400d5951be
 F www/sqlite.tcl 4bd1729e320f5fa9125f0022b281fbe839192125
 F www/tclsqlite.tcl 1db15abeb446aad0caf0b95b8b9579720e4ea331
 F www/vdbe.tcl 2013852c27a02a091d39a766bc87cff329f21218
-P bf558e79524c04339f1174dc935e39d47cb33457
+P 26bd7bb1779e14f19c00e450aaa9529f2aabf131
-R dbcdc1e6ba937154b079e14cdd4eab7b
+R b680c0a504530ce6590f8a3af4ddd816
-U jplyon
+U drh
-Z c717a1a241516bca947b8579016988c0
+Z d87b54e38f0dd3d4af38249efc6d41d2

manifest.uuid

@@ -1 +1 @@
-26bd7bb1779e14f19c00e450aaa9529f2aabf131
+8b388b2f690dbfd50eefc0fdede1c7785f78afa1

src/auth.c

@@ -14,7 +14,7 @@
 ** systems that do not need this facility may omit it by recompiling
 ** the library with -DSQLITE_OMIT_AUTHORIZATION=1
 **
-** $Id: auth.c,v 1.9 2003/05/02 14:32:13 drh Exp $
+** $Id: auth.c,v 1.10 2003/05/10 03:36:54 drh Exp $
 */
 #include "sqliteInt.h"
 
@@ -28,15 +28,35 @@
 ** Set or clear the access authorization function.
 **
 ** The access authorization function is be called during the compilation
-** phase to verify that the user has read and/or write access permission
+** phase to verify that the user has read and/or write access permission on
 ** various fields of the database.  The first argument to the auth function
 ** is a copy of the 3rd argument to this routine.  The second argument
 ** to the auth function is one of these constants:
 **
-**        SQLITE_READ_COLUMN
+**       SQLITE_COPY
-**        SQLITE_WRITE_COLUMN
+**       SQLITE_CREATE_INDEX
-**        SQLITE_DELETE_ROW
+**       SQLITE_CREATE_TABLE
-**        SQLITE_INSERT_ROW
+**       SQLITE_CREATE_TEMP_INDEX
+**       SQLITE_CREATE_TEMP_TABLE
+**       SQLITE_CREATE_TEMP_TRIGGER
+**       SQLITE_CREATE_TEMP_VIEW
+**       SQLITE_CREATE_TRIGGER
+**       SQLITE_CREATE_VIEW
+**       SQLITE_DELETE
+**       SQLITE_DROP_INDEX
+**       SQLITE_DROP_TABLE
+**       SQLITE_DROP_TEMP_INDEX
+**       SQLITE_DROP_TEMP_TABLE
+**       SQLITE_DROP_TEMP_TRIGGER
+**       SQLITE_DROP_TEMP_VIEW
+**       SQLITE_DROP_TRIGGER
+**       SQLITE_DROP_VIEW
+**       SQLITE_INSERT
+**       SQLITE_PRAGMA
+**       SQLITE_READ
+**       SQLITE_SELECT
+**       SQLITE_TRANSACTION
+**       SQLITE_UPDATE
 **
 ** The third and fourth arguments to the auth function are the name of
 ** the table and the column that are being accessed.  The auth function

src/encode.c

@@ -15,10 +15,90 @@
 ** data in an SQLite database.  The code in this file is not used by any other
 ** part of the SQLite library.
 **
-** $Id: encode.c,v 1.5 2003/01/19 03:59:46 drh Exp $
+** $Id: encode.c,v 1.6 2003/05/10 03:36:54 drh Exp $
 */
 #include <string.h>
 
+/*
+** How This Encoder Works
+**
+** The output is allowed to contain any character except 0x27 (') and
+** 0x00.  This is accomplished by using an escape character to encode
+** 0x27 and 0x00 as a two-byte sequence.  The escape character is always
+** 0x01.  An 0x00 is encoded as the two byte sequence 0x01 0x01.  The
+** 0x27 character is encoded as the two byte sequence 0x01 0x03.  Finally,
+** the escape character itself is encoded as the two-character sequence
+** 0x01 0x02.
+**
+** To summarize, the encoder works by using an escape sequences as follows:
+**
+**       0x00  ->  0x01 0x01
+**       0x01  ->  0x01 0x02
+**       0x27  ->  0x01 0x03
+**
+** If that were all the encoder did, it would work, but in certain cases
+** it could double the size of the encoded string.  For example, to
+** encode a string of 100 0x27 character would require 100 instances of
+** the 0x01 0x03 escape sequence resulting in a 200-character output.
+** We would prefer to keep the size of the encoded string smaller than
+** this.
+**
+** To minimize the encoding size, we first add a fixed offset value to each 
+** byte in the sequence.  The addition is module 256.  (That is to say, if
+** the sum of the original character value and the offset exceeds 256, then
+** the higher order bits are truncated.)  The offset is chosen to minimize
+** the number of characters in the string that need to be escaped.  For
+** example, in the case above where the string was composed of 100 0x27
+** characters, the offset might be 0x01.  Each of the 0x27 characters would
+** then be converted into an 0x28 character which would not need to be
+** escaped at all and so the 100 character input string would be converted
+** into just 100 characters of output.  Actually 101 characters of output - 
+** we have to record the offset used as the first byte in the sequence so
+** that the string can be decoded.  Since the offset value is stored as
+** part of the output string and the output string is not allowed to contain
+** characters 0x00 or 0x27, the offset cannot be 0x00 or 0x27.
+**
+** Here, then, are the encoding steps:
+**
+**     (1)   Choose an offset value and make it the first character of
+**           output.
+**
+**     (2)   Copy each input character into the output buffer, one by
+**           one, adding the offset value as you copy.
+**
+**     (3)   If the value of an input character plus offset is 0x00, replace
+**           that one character by the two-character sequence 0x01 0x01.
+**           If the sum is 0x01, replace it with 0x01 0x02.  If the sum
+**           is 0x27, replace it with 0x01 0x03.
+**
+**     (4)   Put a 0x00 terminator at the end of the output.
+**
+** Decoding is obvious:
+**
+**     (5)   Copy encoded characters except the first into the decode 
+**           buffer.  Set the first encoded character aside for use as
+**           the offset in step 7 below.
+**
+**     (6)   Convert each 0x01 0x01 sequence into a single character 0x00.
+**           Convert 0x01 0x02 into 0x01.  Convert 0x01 0x03 into 0x27.
+**
+**     (7)   Subtract the offset value that was the first character of
+**           the encoded buffer from all characters in the output buffer.
+**
+** The only tricky part is step (1) - how to compute an offset value to
+** minimize the size of the output buffer.  This is accomplished to testing
+** all offset values and picking the one that results in the fewest number
+** of escapes.  To do that, we first scan the entire input and count the
+** number of occurances of each character value in the input.  Suppose
+** the number of 0x00 characters is N(0), the number of occurances of 0x01
+** is N(1), and so forth up to the number of occurances of 0xff is N(256).
+** An offset of 0 is not allowed so we don't have to test it.  The number
+** of escapes required for an offset of 1 is N(1)+N(2)+N(40).  The number
+** of escapes required for an offset of 2 is N(2)+N(3)+N(41).  And so forth.
+** In this way we find the offset that gives the minimum number of escapes,
+** and thus minimizes the length of the output string.
+*/
+
 /*
 ** Encode a binary buffer "in" of size n bytes so that it contains
 ** no instances of characters '\'' or '\000'.  The output is 

src/vdbe.c

@@ -36,7 +36,7 @@
 ** in this file for details.  If in doubt, do not deviate from existing
 ** commenting and indentation practices when changing or adding code.
 **
-** $Id: vdbe.c,v 1.221 2003/05/02 14:32:14 drh Exp $
+** $Id: vdbe.c,v 1.222 2003/05/10 03:36:54 drh Exp $
 */
 #include "sqliteInt.h"
 #include <ctype.h>
@@ -3453,10 +3453,10 @@ case OP_OpenWrite: {
 
 /* Opcode: OpenTemp P1 P2 *
 **
-** Open a new cursor that points to a table or index in a temporary
+** Open a new cursor to a transient table.
-** database file.  The temporary file is opened read/write even if 
+** The transient cursor is always opened read/write even if 
-** the main database is read-only.  The temporary file is deleted
+** the main database is read-only.  The transient table is deleted
-** when the cursor is closed.
+** automatically when the cursor is closed.
 **
 ** The cursor points to a BTree table if P2==0 and to a BTree index
 ** if P2==1.  A BTree table must have an integer key and can have arbitrary
@@ -3464,7 +3464,7 @@ case OP_OpenWrite: {
 **
 ** This opcode is used for tables that exist for the duration of a single
 ** SQL statement only.  Tables created using CREATE TEMPORARY TABLE
-** are opened using OP_OpenAux or OP_OpenWrAux.  "Temporary" in the
+** are opened using OP_OpenRead or OP_OpenWrite.  "Temporary" in the
 ** context of this opcode means for the duration of a single SQL statement
 ** whereas "Temporary" in the context of CREATE TABLE means for the duration
 ** of the connection to the database.  Same word; different meanings.
@@ -3997,8 +3997,8 @@ case OP_Delete: {
 /* Opcode: KeyAsData P1 P2 *
 **
 ** Turn the key-as-data mode for cursor P1 either on (if P2==1) or
-** off (if P2==0).  In key-as-data mode, the Field opcode pulls
+** off (if P2==0).  In key-as-data mode, the OP_Column opcode pulls
-** data off of the key rather than the data.  This is useful for
+** data off of the key rather than the data.  This is used for
 ** processing compound selects.
 */
 case OP_KeyAsData: {