Documentation Source Text

Check-in [dc4eae98aa]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for unlikely(), likelihood() and the soft_heap_limit pragma.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: dc4eae98aa016c4758a0c745ed4dc27d56c9d019
User & Date: drh 2013-09-13 22:03:41
Context
2013-09-14
16:09
Merge the 3.8.0 branch changes into trunk. check-in: 18c0f01b0c user: drh tags: trunk
2013-09-13
22:03
Add documentation for unlikely(), likelihood() and the soft_heap_limit pragma. check-in: dc4eae98aa user: drh tags: trunk
14:52
Add documentation for the fts4 unicode61 "tokenchars" and "separators" options. check-in: 00c7833d65 user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

    15     15   proc chng {date desc {options {}}} {
    16     16     global nChng aChng
    17     17     set aChng($nChng) [list $date $desc $options]
    18     18     incr nChng
    19     19   }
    20     20   
    21     21   chng {2013-10-?? (3.8.1)} {
    22         -<li>Add support for SQLITE_ENABLE_STAT4
    23         -<li>Add the [SQLITE_MINIMUM_FILE_DESCRIPTOR] compile-time option
    24         -<li>Add the win32-longpath VFS on windows.
           22  +<li>Added the [unlikely()] and [likelihood()] SQL functions to be used
           23  +    as hints to the query planner.
           24  +<li>Added the [soft_heap_limit pragma].
           25  +<li>Tweaked the query planner to take into account WHERE clause terms
           26  +    that cannot be used with indices.
           27  +<li>Added support for SQLITE_ENABLE_STAT4
           28  +<li>Added the [SQLITE_MINIMUM_FILE_DESCRIPTOR] compile-time option
           29  +<li>Added the win32-longpath VFS on windows.
    25     30   }
    26     31   
    27     32   chng {2013-08-29 (3.8.0.1)} {
    28     33   <li>Fix an off-by-one error that caused quoted empty string at the end of a 
    29     34   CRNL-terminated line of CSV input to be misread by the command-line shell.
    30     35   <li>Fix a query planner bug involving a LEFT JOIN with a BETWEEN or LIKE/GLOB
    31     36   constraint and then another INNER JOIN to the right that involves an OR constraint.

Changes to pages/lang.in.

  2141   2141     [LIKE] operator.  When overriding the like() function, it may be important
  2142   2142     to override both the two and three argument versions of the like() 
  2143   2143     function. Otherwise, different code may be called to implement the
  2144   2144     [LIKE] operator depending on whether or not an ESCAPE clause was 
  2145   2145     specified.
  2146   2146   }
  2147   2147   
         2148  +
         2149  +funcdef {likelihood(X,Y)} {} {
         2150  +  ^The likelihood(X,Y) function returns argument X unchanged.
         2151  +  ^The value Y in likelihood(X,Y) must be a floating point constant
         2152  +  between 0.0 and 1.0, inclusive.
         2153  +  ^The likelihood(X) function is a no-op that the code generator
         2154  +  optimizes away so that it consumes no CPU cycles at run-time.
         2155  +  ^The purpose of the likelihood(X,Y) function is to provide a hint
         2156  +  to the query planner that the argument X is a boolean that is
         2157  +  true with a probability of approximately Y.
         2158  +  ^The likelihood(X, 0.0625) function is equivalent to [unlikely](X).
         2159  +}
         2160  +
  2148   2161   funcdef {load_extension(X) load_extension(X,Y)} {} {
  2149   2162     ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  2150   2163     library file named X using the entry point Y.  ^The result of load_extension()
  2151   2164     is always a NULL.  ^If Y is omitted then the default entry point name is used.
  2152   2165     ^The load_extension() function raises an exception if the extension fails to
  2153   2166     load or initialize correctly.
  2154   2167   
................................................................................
  2331   2344     ^If the Y argument is omitted, trim(X) removes spaces from both ends of X.
  2332   2345   }
  2333   2346   
  2334   2347   funcdef {typeof(X)} {} {
  2335   2348     ^The typeof(X) function returns a string that indicates the [datatype] of
  2336   2349     the expression X: "null", "integer", "real", "text", or "blob".
  2337   2350   }
         2351  +
         2352  +funcdef {unlikely(X)} {} {
         2353  +  ^The unlikely(X) function returns the argument X unchanged.
         2354  +  ^The unlikely(X) function is a no-op that the code generator
         2355  +  optimizes away so that it consumes no CPU cycles at run-time.
         2356  +  ^The purpose of the unlikely(X) function is to provide a hint
         2357  +  to the query planner that the argument X is a boolean value
         2358  +  that is usually not true. ^The unlikely(X) function is equivalent
         2359  +  to [likelihood](X, 0.0625).
         2360  +}
  2338   2361   
  2339   2362   funcdef {unicode(X)} {} {
  2340   2363     ^The unicode(X) function returns the numeric unicode code point corresponding to
  2341   2364     the first character of the string X.  ^If the argument to unicode(X) is not a string
  2342   2365     then the result is undefined.
  2343   2366   }
  2344   2367   

Changes to pages/pragma.in.

   874    874       <p><b>PRAGMA shrink_memory</b></p>
   875    875   
   876    876       <p>^This pragma causes the database connection on which it is invoked
   877    877       to free up as much memory as it can, by calling
   878    878       [sqlite3_db_release_memory()].
   879    879       </p>
   880    880   }
          881  +
          882  +Pragma soft_heap_limit {
          883  +    <p><b>PRAGMA soft_heap_limit<br>
          884  +          PRAGMA soft_heap_limit=</b><i>N</i></p>
          885  +
          886  +    <p>^This pragma invokes the [sqlite3_soft_heap_limit64()] interface with
          887  +    the argument N, if N is specified and is a non-negative integer.
          888  +    ^The soft_heap_limit pragma always returns the same integer
          889  +    that would be returned by the [sqlite3_soft_heap_limit64](-1) C-language
          890  +    function.
          891  +    </p>
          892  +}
   881    893   
   882    894   Pragma synchronous {
   883    895       <p>^(<b>PRAGMA synchronous;
   884    896          <br>PRAGMA synchronous = </b>
   885    897             <i>0 | OFF | 1 | NORMAL | 2 | FULL</i><b>;</b></p>
   886    898   
   887    899       <p>Query or change the setting of the "synchronous" flag.)^