Documentation Source Text

Check-in [fc4a66aa03]
Login

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

Overview
Comment:Reformat the core and aggregate function descriptions in a way that works better on mobile. Use the "output_list" proc for the lists of pragma and aggregate and core functions.
Timelines: family | ancestors | descendants | both | mobile-friendly
Files: files | file ages | folders
SHA1: fc4a66aa03d1ecb6b004b6227d6cd2609f21350c
User & Date: drh 2016-09-01 00:48:22
Context
2016-09-01
00:54
Update the comment on the output_list proc. Use the output_list proc from capi3ref.in to process session.in. check-in: 6f74e2171b user: drh tags: mobile-friendly
00:48
Reformat the core and aggregate function descriptions in a way that works better on mobile. Use the "output_list" proc for the lists of pragma and aggregate and core functions. check-in: fc4a66aa03 user: drh tags: mobile-friendly
2016-08-31
21:38
Limit the width of syntax diagram images to the width of the screen. check-in: 2cbeb114ca user: drh tags: mobile-friendly
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319



320
321
322
323
324
325
326
  hd_putsnl "for(var i=0; i<$vx.length; i++){"
  hd_putsnl "  if( (++j)>nRow ){"
  hd_putsnl "    h += \"</ul></td>\\n<td><ul>\\n\";"
  hd_putsnl "    j = 1;"
  hd_putsnl "  }"
  hd_putsnl "  if($vx\[i\].u==\"\" || $vx\[i\].s==2){"
  hd_putsnl "    h += \"<li>\""
  hd_putsnl "    ea = \"\\n\""
  hd_putsnl "  }else{"
  hd_putsnl "    h += \"<li><a href='\";"
  hd_putsnl "    h += $vx\[i\].u;"
  hd_putsnl "    h += \"'>\";"
  hd_putsnl "    ea = \"</a>\\n\""
  hd_putsnl "  }"
  hd_putsnl "  if($vx\[i\].s==2) h += \"<s>\""
  hd_putsnl "  h += $vx\[i\].x;"
  hd_putsnl "  if($vx\[i\].s==2) h += \"</s>\""
  hd_putsnl "  h += ea"
  hd_putsnl "  if($vx\[i\].s==1) h += \"<small><i>(exp)</i></small>\\n\";"



  hd_putsnl "}"
  hd_putsnl "document.getElementById(\"$tx\").innerHTML = h;"
  hd_putsnl "</script>"
}

hd_open_aux c3ref/intro.html
hd_header Introduction







|




|

|

|


>
>
>







301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
  hd_putsnl "for(var i=0; i<$vx.length; i++){"
  hd_putsnl "  if( (++j)>nRow ){"
  hd_putsnl "    h += \"</ul></td>\\n<td><ul>\\n\";"
  hd_putsnl "    j = 1;"
  hd_putsnl "  }"
  hd_putsnl "  if($vx\[i\].u==\"\" || $vx\[i\].s==2){"
  hd_putsnl "    h += \"<li>\""
  hd_putsnl "    ea = \"\""
  hd_putsnl "  }else{"
  hd_putsnl "    h += \"<li><a href='\";"
  hd_putsnl "    h += $vx\[i\].u;"
  hd_putsnl "    h += \"'>\";"
  hd_putsnl "    ea = \"</a>\""
  hd_putsnl "  }"
  hd_putsnl "  if($vx\[i\].s==2 || $vx\[i\].s==3) h += \"<s>\""
  hd_putsnl "  h += $vx\[i\].x;"
  hd_putsnl "  if($vx\[i\].s==2 || $vx\[i\].s==3) h += \"</s>\""
  hd_putsnl "  h += ea"
  hd_putsnl "  if($vx\[i\].s==1) h += \"<small><i>(exp)</i></small>\\n\";"
  hd_putsnl "  if($vx\[i\].s==3) h += \"&sup1\\n\";"
  hd_putsnl "  if($vx\[i\].s==4) h += \"&sup2\\n\";"
  hd_putsnl "  if($vx\[i\].s==5) h += \"&sup3\\n\";"
  hd_putsnl "}"
  hd_putsnl "document.getElementById(\"$tx\").innerHTML = h;"
  hd_putsnl "</script>"
}

hd_open_aux c3ref/intro.html
hd_header Introduction

Changes to pages/lang.in.

2318
2319
2320
2321
2322
2323
2324

2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339

2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
....
2709
2710
2711
2712
2713
2714
2715
2716
2717








2718

































2719
2720
2721
2722
2723
2724
2725
....
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
....
3113
3114
3115
3116
3117
3118
3119
3120
3121
















3122

































3123
3124
3125
3126
3127
3128
3129
....
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
function are different.  ^For example, the [agg_max|max()] function with a
single argument is an aggregate and the [max()] function with two or more
arguments is a simple function.

<tcl>
##############################################################################
Section {Core Functions} corefunc {*corefunc}

proc funcdef {syntax keywords desc} {
  hd_puts {<tr>}
  regsub -all {\s+} [string trim $syntax] {<br />} syntax
  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
  regsub -all {,} $syntax {</i>,<i>} syntax
  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
  hd_puts "<td valign=\"top\" align=\"right\" width=\"120\">"
  if {[llength $keywords]==0} {
    regexp {[a-z_]+} $syntax name
    hd_fragment $name *$name "${name}() SQL function"
  } else {
    set fragname [lindex $keywords 0]
    regsub -all {[^a-z]} $fragname {} fragname
    hd_fragment $fragname
    eval hd_keywords [string map {\n { }} $keywords]

  }
  hd_puts "$syntax</td>"
  hd_puts {<td valign="top">}
  hd_resolve $desc
  hd_puts {</td></tr>}
}
</tcl>

<p>The core functions shown below are available by default. 
[datefunc | Date &amp; Time functions],
[aggfunc | aggregate functions], and
[json1 | JSON functions] are documented separately.  An
application may define additional
functions written in C and added to the database engine using
the [sqlite3_create_function()] API.</p>

<table border=0 cellpadding=10>
<tcl>
funcdef {abs(X)} {} {
  ^The abs(X) function returns the absolute value of the numeric
  argument X.  ^Abs(X) returns NULL if X is NULL. 
  ^(Abs(X) returns 0.0 if X is a string or blob
  that cannot be converted to a numeric value.)^  ^If X is the 
  integer -9223372036854775808 then abs(X) throws an integer overflow
  error since there is no equivalent positive 64-bit two complement value.
................................................................................
  SQLite manages these zeroblobs very efficiently.  Zeroblobs can be used to
  reserve space for a BLOB that is later written using 
  [sqlite3_blob_open() | incremental BLOB I/O].
  ^This SQL function is implemented using the [sqlite3_result_zeroblob()]
  routine from the C/C++ interface.
}
</tcl>
</table>









<tcl>

































##############################################################################
Section {Date And Time Functions} datefunc {*datefunc {date and time functions}}
hd_keywords {date() SQL function} {time() SQL function}
hd_keywords {datetime() SQL function} {julianday() SQL function}
hd_keywords {strftime() SQL function}
</tcl>

................................................................................
[http://en.wikipedia.org/wiki/Gregorian_calendar | Gregorian calendar]
system.  It is also assumed that every
day is exactly 86400 seconds in duration.</p>

<tcl>
##############################################################################
Section {Aggregate Functions} aggfunc {*aggfunc}
</tcl>

<p>
The aggregate functions shown below are available by default.  Additional
aggregate functions written in C may be added using the 
[sqlite3_create_function()]</a>
API.</p>

<p>
^In any aggregate function that takes a single argument, that argument
can be preceded by the keyword DISTINCT.  ^In such cases, duplicate
elements are filtered before being passed into the aggregate function.
^For example, the function "count(distinct X)" will return the number
of distinct values of column X instead of the total number of non-null
values in column X.
</p>

<table border=0 cellpadding=10>
<tcl>
funcdef {avg(X)} {*avg {avg() aggregate function}} {
  ^The avg() function
  returns the average value of all non-NULL <i>X</i> within a
  group.  ^String and BLOB values that do not look like numbers are
  interpreted as 0.
  ^The result of avg() is always a floating point value as long as
  at there is at least one non-NULL input even if all
................................................................................

  <p>^Sum() will throw an "integer overflow" exception if all inputs
  are integers or NULL
  and an integer overflow occurs at any point during the computation.
  ^Total() never throws an integer overflow.
}
</tcl>
</table>

















<tcl>

































##############################################################################
Section INSERT insert {INSERT *INSERTs}

RecursiveBubbleDiagram insert-stmt
</tcl>

<p>The INSERT statement comes in three basic forms.  
................................................................................
</p>

<tcl>
set lx {}
foreach word $keyword_list {
  lappend lx [list {} $word 0]
}
output_list {} 180 $lx
</tcl>
<blockquote>
<table width="100%"><tr>
<td align="left" valign="top" width="20%">
<tcl>







>

<
|
<
<
<
<
<
|
<
<
<
<
<
<
>
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<

>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|





2318
2319
2320
2321
2322
2323
2324
2325
2326

2327





2328






2329
2330

















2331
2332
2333
2334
2335
2336
2337
....
2682
2683
2684
2685
2686
2687
2688

2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
....
3032
3033
3034
3035
3036
3037
3038
3039
3040

















3041
3042
3043
3044
3045
3046
3047
....
3109
3110
3111
3112
3113
3114
3115

3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
....
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
function are different.  ^For example, the [agg_max|max()] function with a
single argument is an aggregate and the [max()] function with two or more
arguments is a simple function.

<tcl>
##############################################################################
Section {Core Functions} corefunc {*corefunc}
unset -nocomplain corefuncset
proc funcdef {syntax keywords desc} {

  global corefuncset





  regexp {^[a-z_]+} $syntax basesyntax






  set corefuncset($basesyntax) [list $syntax $keywords $desc]
}

















funcdef {abs(X)} {} {
  ^The abs(X) function returns the absolute value of the numeric
  argument X.  ^Abs(X) returns NULL if X is NULL. 
  ^(Abs(X) returns 0.0 if X is a string or blob
  that cannot be converted to a numeric value.)^  ^If X is the 
  integer -9223372036854775808 then abs(X) throws an integer overflow
  error since there is no equivalent positive 64-bit two complement value.
................................................................................
  SQLite manages these zeroblobs very efficiently.  Zeroblobs can be used to
  reserve space for a BLOB that is later written using 
  [sqlite3_blob_open() | incremental BLOB I/O].
  ^This SQL function is implemented using the [sqlite3_result_zeroblob()]
  routine from the C/C++ interface.
}
</tcl>


<p>The core functions shown below are available by default. 
[datefunc | Date &amp; Time functions],
[aggfunc | aggregate functions], and
[json1 | JSON functions] are documented separately.  An
application may define additional
functions written in C and added to the database engine using
the [sqlite3_create_function()] API.</p>

<tcl>
set lx {}
foreach basesyntax [array names corefuncset] {
  foreach {syntax keywords desc} $corefuncset($basesyntax) break
  regexp {^[a-z_]+} $basesyntax fragment
  foreach coresyntax $syntax {
    lappend lx [list $fragment $coresyntax 0]
  }
}
output_list {} 225 [lsort -index 1 $lx]

hd_putsnl "<hr class='xhr'>"
hd_putsnl "<dl>"
foreach basesyntax [lsort [array names corefuncset]] {
  foreach {syntax keywords desc} $corefuncset($basesyntax) break
  regsub -all {\s+} [string trim $syntax] {<br />} syntax
  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
  regsub -all {,} $syntax {</i>,<i>} syntax
  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
  regexp {^[a-z]+} $basesyntax fragment
  if {[llength $keywords]==0} {
    regexp {[a-z_]+} $syntax name
    hd_fragment $name *$name "${name}() SQL function"
  } else {
    set fragname [lindex $keywords 0]
    regsub -all {[^a-z]} $fragname {} fragname
    hd_fragment $fragname
    eval hd_keywords [string map {\n { }} $keywords]
  }
  hd_puts "<dt><p><b>$syntax</b></dt>"
  hd_resolve "<dd><p>$desc</dd>\n"
}
hd_putsnl "</dl>"

##############################################################################
Section {Date And Time Functions} datefunc {*datefunc {date and time functions}}
hd_keywords {date() SQL function} {time() SQL function}
hd_keywords {datetime() SQL function} {julianday() SQL function}
hd_keywords {strftime() SQL function}
</tcl>

................................................................................
[http://en.wikipedia.org/wiki/Gregorian_calendar | Gregorian calendar]
system.  It is also assumed that every
day is exactly 86400 seconds in duration.</p>

<tcl>
##############################################################################
Section {Aggregate Functions} aggfunc {*aggfunc}
unset -nocomplain corefuncset


















funcdef {avg(X)} {*avg {avg() aggregate function}} {
  ^The avg() function
  returns the average value of all non-NULL <i>X</i> within a
  group.  ^String and BLOB values that do not look like numbers are
  interpreted as 0.
  ^The result of avg() is always a floating point value as long as
  at there is at least one non-NULL input even if all
................................................................................

  <p>^Sum() will throw an "integer overflow" exception if all inputs
  are integers or NULL
  and an integer overflow occurs at any point during the computation.
  ^Total() never throws an integer overflow.
}
</tcl>



<p>
The aggregate functions shown below are available by default.  Additional
aggregate functions written in C may be added using the 
[sqlite3_create_function()]</a>
API.</p>

<p>
^In any aggregate function that takes a single argument, that argument
can be preceded by the keyword DISTINCT.  ^In such cases, duplicate
elements are filtered before being passed into the aggregate function.
^For example, the function "count(distinct X)" will return the number
of distinct values of column X instead of the total number of non-null
values in column X.
</p>

<tcl>
set lx {}
foreach basesyntax [array names corefuncset] {
  foreach {syntax keywords desc} $corefuncset($basesyntax) break
  regexp {^[a-z_]+} $basesyntax fragment
  foreach coresyntax $syntax {
    lappend lx [list $fragment $coresyntax 0]
  }
}
output_list {} 225 [lsort -index 1 $lx]

hd_putsnl "<hr class='xhr'>"
hd_putsnl "<dl>"
foreach basesyntax [lsort [array names corefuncset]] {
  foreach {syntax keywords desc} $corefuncset($basesyntax) break
  regsub -all {\s+} [string trim $syntax] {<br />} syntax
  regsub -all {\(([^*)]+)\)} $syntax {(<i>\1</i>)} syntax
  regsub -all {,} $syntax {</i>,<i>} syntax
  regsub -all {<i>\.\.\.</i>} $syntax {...} syntax
  regexp {^[a-z]+} $basesyntax fragment
  if {[llength $keywords]==0} {
    regexp {[a-z_]+} $syntax name
    hd_fragment $name *$name "${name}() SQL function"
  } else {
    set fragname [lindex $keywords 0]
    regsub -all {[^a-z]} $fragname {} fragname
    hd_fragment $fragname
    eval hd_keywords [string map {\n { }} $keywords]
  }
  hd_puts "<dt><p><b>$syntax</b></dt>"
  hd_resolve "<dd><p>$desc</dd>\n"
}
hd_putsnl "</dl>"

##############################################################################
Section INSERT insert {INSERT *INSERTs}

RecursiveBubbleDiagram insert-stmt
</tcl>

<p>The INSERT statement comes in three basic forms.  
................................................................................
</p>

<tcl>
set lx {}
foreach word $keyword_list {
  lappend lx [list {} $word 0]
}
output_list {} 200 $lx
</tcl>
<blockquote>
<table width="100%"><tr>
<td align="left" valign="top" width="20%">
<tcl>

Changes to pages/pragma.in.

1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560

1561
1562

1563
1564

1565
1566

1567
1568
1569
1570
1571

1572
1573
1574
1575
1576
1577

1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
    <p>When this pragma is on, the SQLITE_MASTER tables in which database
    can be changed using ordinary [UPDATE], [INSERT], and [DELETE]
    statements.)^  ^Warning:  misuse of this pragma can easily result in
    a corrupt database file.</p>
}

Section {List Of PRAGMAs} {toc} {{pragma list}}
</tcl>
<table border=0 width="100%" cellpadding=10>
<tr><td valign="top" align="left"><ul>
<tcl>
set allprag [lsort [array names PragmaRef]]
set nprag [llength $allprag]
set nrow [expr {($nprag+2)/3}]
for {set i 0} {$i<$nprag} {incr i} {
  set prag [lindex $allprag $i]
  set ref $PragmaRef($prag)
  if {[info exists PragmaLegacy($prag)]} {
    hd_puts "<li><a href=\"#pragma_$ref\"><s>$prag</s></a>&sup1;\n"

  } elseif {[info exists PragmaDebug($prag)]} {
    hd_puts "<li><a href=\"#pragma_$ref\"><i>$prag</i></a>&sup2;\n"

  } elseif {[info exists PragmaTest($prag)]} {
    hd_puts "<li><a href=\"#pragma_$ref\"><i>$prag</i></a>&sup3;\n"

  } else {
    hd_puts "<li><a href=\"#pragma_$ref\">$prag</a>\n"

  }
  if {$i%$nrow==($nrow-1) && $i+1<$nprag} {
    hd_puts "</ul></td><td valign=\"top\" align=\"left\"><ul>\n"
  }
}

</tcl>
</ul></td></tr></table>
<p>Notes:
<ol>
<li>Pragmas whose names are marked through in the list above
are deprecated.  They are not maintained.  They continue to exist

for historical compatibility only.
Do not use the deprecated pragmas in new applications.
Remove deprecated pragmas
from existing applications at your earliest opportunity.</blockquote>
<li>These pragmas are used for debugging SQLite and
are only available when SQLite is compiled using [SQLITE_DEBUG].
<li>These pragmas are used for testing SQLite and are not recommended
for use in application programs.</ol></p>
<tcl>
foreach prag [lsort [array names PragmaBody]] {
  hd_fragment pragma_$prag







|
<
<
<
|
<
<
<
<


<
>

<
>

<
>

<
>

<
<
|
<
>

<


|
<
>
|
<
<
<







1542
1543
1544
1545
1546
1547
1548
1549



1550




1551
1552

1553
1554

1555
1556

1557
1558

1559
1560


1561

1562
1563

1564
1565
1566

1567
1568



1569
1570
1571
1572
1573
1574
1575
    <p>When this pragma is on, the SQLITE_MASTER tables in which database
    can be changed using ordinary [UPDATE], [INSERT], and [DELETE]
    statements.)^  ^Warning:  misuse of this pragma can easily result in
    a corrupt database file.</p>
}

Section {List Of PRAGMAs} {toc} {{pragma list}}
set lx {}



foreach prag [array names PragmaRef] {




  set ref $PragmaRef($prag)
  if {[info exists PragmaLegacy($prag)]} {

    lappend lx [list "PRAGMA $ref" $prag 3]
  } elseif {[info exists PragmaDebug($prag)]} {

    lappend lx [list "PRAGMA $ref" $prag 4]
  } elseif {[info exists PragmaTest($prag)]} {

    lappend lx [list "PRAGMA $ref" $prag 5]
  } else {

    lappend lx [list "PRAGMA $ref" $prag 0]
  }


}

output_list {} 250 [lsort -index 1 $lx]
</tcl>

<p>Notes:
<ol>
<li>Pragmas whose names are <s>struck through</s>

are deprecated. Do not use them. They exist
for historical compatibility.



<li>These pragmas are used for debugging SQLite and
are only available when SQLite is compiled using [SQLITE_DEBUG].
<li>These pragmas are used for testing SQLite and are not recommended
for use in application programs.</ol></p>
<tcl>
foreach prag [lsort [array names PragmaBody]] {
  hd_fragment pragma_$prag