| 1 |
<!DOCTYPE html> |
| 2 |
<html><head> |
| 3 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 4 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 5 |
<link href="sqlite.css" rel="stylesheet"> |
| 6 |
<title>SQLite's Built-in printf()</title> |
| 7 |
<!-- path= --> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
<div class=nosearch> |
| 11 |
<a href="index.html"> |
| 12 |
<img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0"> |
| 13 |
</a> |
| 14 |
<div><!-- IE hack to prevent disappearing logo --></div> |
| 15 |
<div class="tagline desktoponly"> |
| 16 |
Small. Fast. Reliable.<br>Choose any three. |
| 17 |
</div> |
| 18 |
<div class="menu mainmenu"> |
| 19 |
<ul> |
| 20 |
<li><a href="index.html">Home</a> |
| 21 |
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> |
| 22 |
<li class='wideonly'><a href='about.html'>About</a> |
| 23 |
<li class='desktoponly'><a href="docs.html">Documentation</a> |
| 24 |
<li class='desktoponly'><a href="download.html">Download</a> |
| 25 |
<li class='wideonly'><a href='copyright.html'>License</a> |
| 26 |
<li class='desktoponly'><a href="support.html">Support</a> |
| 27 |
<li class='desktoponly'><a href="prosupport.html">Purchase</a> |
| 28 |
<li class='search' id='search_menubutton'> |
| 29 |
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> |
| 30 |
</ul> |
| 31 |
</div> |
| 32 |
<div class="menu submenu" id="submenu"> |
| 33 |
<ul> |
| 34 |
<li><a href='about.html'>About</a> |
| 35 |
<li><a href='docs.html'>Documentation</a> |
| 36 |
<li><a href='download.html'>Download</a> |
| 37 |
<li><a href='support.html'>Support</a> |
| 38 |
<li><a href='prosupport.html'>Purchase</a> |
| 39 |
</ul> |
| 40 |
</div> |
| 41 |
<div class="searchmenu" id="searchmenu"> |
| 42 |
<form method="GET" action="search"> |
| 43 |
<select name="s" id="searchtype"> |
| 44 |
<option value="d">Search Documentation</option> |
| 45 |
<option value="c">Search Changelog</option> |
| 46 |
</select> |
| 47 |
<input type="text" name="q" id="searchbox" value=""> |
| 48 |
<input type="submit" value="Go"> |
| 49 |
</form> |
| 50 |
</div> |
| 51 |
</div> |
| 52 |
<script> |
| 53 |
function toggle_div(nm) { |
| 54 |
var w = document.getElementById(nm); |
| 55 |
if( w.style.display=="block" ){ |
| 56 |
w.style.display = "none"; |
| 57 |
}else{ |
| 58 |
w.style.display = "block"; |
| 59 |
} |
| 60 |
} |
| 61 |
function toggle_search() { |
| 62 |
var w = document.getElementById("searchmenu"); |
| 63 |
if( w.style.display=="block" ){ |
| 64 |
w.style.display = "none"; |
| 65 |
} else { |
| 66 |
w.style.display = "block"; |
| 67 |
setTimeout(function(){ |
| 68 |
document.getElementById("searchbox").focus() |
| 69 |
}, 30); |
| 70 |
} |
| 71 |
} |
| 72 |
function div_off(nm){document.getElementById(nm).style.display="none";} |
| 73 |
window.onbeforeunload = function(e){div_off("submenu");} |
| 74 |
/* Disable the Search feature if we are not operating from CGI, since */ |
| 75 |
/* Search is accomplished using CGI and will not work without it. */ |
| 76 |
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ |
| 77 |
document.getElementById("search_menubutton").style.display = "none"; |
| 78 |
} |
| 79 |
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ |
| 80 |
function hideorshow(btn,obj){ |
| 81 |
var x = document.getElementById(obj); |
| 82 |
var b = document.getElementById(btn); |
| 83 |
if( x.style.display!='none' ){ |
| 84 |
x.style.display = 'none'; |
| 85 |
b.innerHTML='show'; |
| 86 |
}else{ |
| 87 |
x.style.display = ''; |
| 88 |
b.innerHTML='hide'; |
| 89 |
} |
| 90 |
return false; |
| 91 |
} |
| 92 |
var antiRobot = 0; |
| 93 |
function antiRobotGo(){ |
| 94 |
if( antiRobot!=3 ) return; |
| 95 |
antiRobot = 7; |
| 96 |
var j = document.getElementById("mtimelink"); |
| 97 |
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); |
| 98 |
} |
| 99 |
function antiRobotDefense(){ |
| 100 |
document.body.onmousedown=function(){ |
| 101 |
antiRobot |= 2; |
| 102 |
antiRobotGo(); |
| 103 |
document.body.onmousedown=null; |
| 104 |
} |
| 105 |
document.body.onmousemove=function(){ |
| 106 |
antiRobot |= 2; |
| 107 |
antiRobotGo(); |
| 108 |
document.body.onmousemove=null; |
| 109 |
} |
| 110 |
setTimeout(function(){ |
| 111 |
antiRobot |= 1; |
| 112 |
antiRobotGo(); |
| 113 |
}, 100) |
| 114 |
antiRobotGo(); |
| 115 |
} |
| 116 |
antiRobotDefense(); |
| 117 |
</script> |
| 118 |
<div class=fancy> |
| 119 |
<div class=nosearch> |
| 120 |
<div class="fancy_title"> |
| 121 |
SQLite's Built-in printf() |
| 122 |
</div> |
| 123 |
<details class="fancy_toc"> |
| 124 |
<summary>Table Of Contents</summary> |
| 125 |
<div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div> |
| 126 |
<div class="fancy-toc2"><a href="#advantages">1.1. Advantages</a></div> |
| 127 |
<div class="fancy-toc2"><a href="#disadvantages">1.2. Disadvantages</a></div> |
| 128 |
<div class="fancy-toc1"><a href="#formatting_details">2. Formatting Details</a></div> |
| 129 |
<div class="fancy-toc2"><a href="#substitution_types">2.1. Substitution Types</a></div> |
| 130 |
<div class="fancy-toc2"><a href="#the_optional_length_field">2.2. The Optional Length Field</a></div> |
| 131 |
<div class="fancy-toc2"><a href="#the_optional_width_field">2.3. The Optional Width Field</a></div> |
| 132 |
<div class="fancy-toc2"><a href="#the_optional_precision_field">2.4. The Optional Precision Field</a></div> |
| 133 |
<div class="fancy-toc2"><a href="#the_options_flags_field">2.5. The Options Flags Field</a></div> |
| 134 |
<div class="fancy-toc1"><a href="#implementation_and_history">3. Implementation And History</a></div> |
| 135 |
</div> |
| 136 |
</details> |
| 137 |
</div> |
| 138 |
|
| 139 |
|
| 140 |
|
| 141 |
|
| 142 |
<h1 id="overview"><span>1. </span>Overview</h1> |
| 143 |
|
| 144 |
<p>SQLite contains its own implementation of the string formatting routine "printf()", |
| 145 |
accessible via the following interfaces: |
| 146 |
|
| 147 |
</p><ul> |
| 148 |
<li> <a href="lang_corefunc.html#format">format()</a> → an SQL function returning the formatted string |
| 149 |
</li><li> <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> → Store the formatted string in memory obtained |
| 150 |
from <a href="c3ref/free.html">sqlite3_malloc64()</a>. |
| 151 |
</li><li> <a href="c3ref/mprintf.html">sqlite3_snprintf()</a> → Store the formatted string in a static buffer |
| 152 |
</li><li> <a href="c3ref/str_append.html">sqlite3_str_appendf()</a> → Append formatted text to a dynamic string |
| 153 |
</li><li> <a href="c3ref/mprintf.html">sqlite3_vmprintf()</a> → Varargs version of sqlite3_mprintf() |
| 154 |
</li><li> <a href="c3ref/mprintf.html">sqlite3_vsnprintf()</a> → Varargs version of sqlite3_snprintf() |
| 155 |
</li><li> <a href="c3ref/str_append.html">sqlite3_str_vappendf()</a> → Varargs version of sqlite3_str_appendf() |
| 156 |
</li></ul> |
| 157 |
|
| 158 |
<p>The same core string formatter is also used internally by SQLite. |
| 159 |
|
| 160 |
</p><h2 id="advantages"><span>1.1. </span>Advantages</h2> |
| 161 |
|
| 162 |
<p>Why does SQLite have its own private built-in printf() implementation? |
| 163 |
Why not use the printf() implementation from the standard C library? |
| 164 |
Several reasons: |
| 165 |
|
| 166 |
</p><p> |
| 167 |
</p><ol> |
| 168 |
<li><p> |
| 169 |
By using its own built-in implementation, SQLite guarantees that the |
| 170 |
output will be the same on all platforms and in all LOCALEs. |
| 171 |
This is important for consistency and for testing. It would be problematic |
| 172 |
if one machine gave an answer of "5.25e+08" and another gave an answer |
| 173 |
of "5.250e+008". Both answers are correct, but it is better when SQLite |
| 174 |
always gives the same answer. |
| 175 |
|
| 176 |
</p></li><li><p> |
| 177 |
We know of no way to use the standard library printf() C interface to |
| 178 |
implement the <a href="lang_corefunc.html#format">format() SQL function</a> feature of SQLite. The built-in |
| 179 |
printf() implementation can be easily adapted to that task, however. |
| 180 |
|
| 181 |
</p></li><li><p> |
| 182 |
The printf() in SQLite supports new non-standard substitution |
| 183 |
types (<a href="printf.html#percentq">%q</a>, <a href="printf.html#percentq">%Q</a>, <a href="printf.html#percentw">%w</a>, and <a href="printf.html#percentz">%z</a>), and enhanced substitution |
| 184 |
behavior (%s and <a href="printf.html#percentz">%z</a>) that are useful both internally to SQLite |
| 185 |
and to applications using SQLite. |
| 186 |
Standard library printf()s cannot normally be extended in this way. |
| 187 |
|
| 188 |
</p></li><li><p> |
| 189 |
Via the <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> and <a href="c3ref/mprintf.html">sqlite3_vmprintf()</a> interfaces, |
| 190 |
the built-in printf() implementation supports the ability to render an |
| 191 |
arbitrary-length string into a memory buffer obtained from <a href="c3ref/free.html">sqlite3_malloc64()</a>. |
| 192 |
This is safer and less error prone than trying to precompute an upper size |
| 193 |
limit on the result string, allocate an appropriately sized buffer, and |
| 194 |
then calling snprintf(). |
| 195 |
|
| 196 |
</p></li><li><p> |
| 197 |
The SQLite-specific printf() supports a new flag (!) called the |
| 198 |
"alternate-form-2" flag. The alternate-form-2 flag changes the processing |
| 199 |
of floating-point conversions in subtle ways so that the output is always |
| 200 |
an SQL-compatible text representation of a floating-point number - something |
| 201 |
that is not possible to achieve with standard-library printf(). For |
| 202 |
string substitutions, the alternate-form-2 flag causes the width and |
| 203 |
precision to be measured in characters instead of bytes, which simplifies |
| 204 |
processing of strings containing multi-byte UTF8 characters. |
| 205 |
|
| 206 |
</p></li><li><p> |
| 207 |
The built-in SQLite has compile-time options such as |
| 208 |
SQLITE_PRINTF_PRECISION_LIMIT that provide defense against |
| 209 |
denial-of-service attacks for applications that expose the |
| 210 |
printf() functionality to untrusted users. |
| 211 |
|
| 212 |
</p></li><li><p> |
| 213 |
Using a built-in printf() implementation means that SQLite has one |
| 214 |
fewer dependency on the host environment, making it more portable. |
| 215 |
</p></li></ol> |
| 216 |
|
| 217 |
<h2 id="disadvantages"><span>1.2. </span>Disadvantages</h2> |
| 218 |
|
| 219 |
<p> |
| 220 |
In fairness, having a built-in implementation of printf() also comes with |
| 221 |
some disadvantages. To wit: |
| 222 |
|
| 223 |
</p><ol> |
| 224 |
<li><p> |
| 225 |
The built-in printf() implementation uses extra code space |
| 226 |
(about 7800 bytes on GCC 5.4 with -Os). |
| 227 |
|
| 228 |
</p></li><li><p> |
| 229 |
The floating-point to text conversion subfunction for the built-in printf() |
| 230 |
is limited in precision to 16 significant digits or 26 significant digits |
| 231 |
if the "!" alternate-form-2 flag is used. |
| 232 |
Every IEEE-754 double can be represented <i>exactly</i> as a decimal |
| 233 |
value, but for many doubles the exact decimal representation requires |
| 234 |
more than 16 or 26 significant digits. |
| 235 |
The SQLite printf() function only renders the first 16 or 26 significant digits |
| 236 |
because that can be done efficiently and because 16 decimal digits suffice |
| 237 |
to distinguish every possible double value. Use the <a href="floatingpoint.html#decext">decimal extension</a> to get |
| 238 |
the exact decimal equivalent of double value for the rare cases where that is |
| 239 |
required. |
| 240 |
|
| 241 |
</p></li><li><p> |
| 242 |
The order of the buffer pointer and buffer size parameters in the built-in |
| 243 |
snprintf() implementation is reversed from the order used in standard-library |
| 244 |
implementations. |
| 245 |
|
| 246 |
</p></li><li><p> |
| 247 |
The built-in printf() implementation does not handle posix positional referencing |
| 248 |
modifiers that allow the order of arguments to printf() to be different from the |
| 249 |
order of the %-substitutions. In the built-in printf(), the order of the arguments |
| 250 |
must exactly match the order of the %-substitutions. |
| 251 |
</p></li></ol> |
| 252 |
|
| 253 |
<p> |
| 254 |
In spite of the disadvantages, the developers believe that having a built-in |
| 255 |
printf() implementation inside of SQLite is a net positive. |
| 256 |
|
| 257 |
</p><h1 id="formatting_details"><span>2. </span>Formatting Details</h1> |
| 258 |
|
| 259 |
<p>The format string for printf() is a template for the generated |
| 260 |
string. Substitutions are made whenever a "%" character appears in |
| 261 |
the format string. The "%" is followed by one or more additional |
| 262 |
characters that describe the substitution. Each substitution has |
| 263 |
the following format: |
| 264 |
|
| 265 |
</p><blockquote> |
| 266 |
<b>%</b><i>[flags][width][</i><b>.</b><i>precision][length]type</i> |
| 267 |
</blockquote> |
| 268 |
|
| 269 |
<p>All substitutions begin with a single "%" and end with a single type character. |
| 270 |
The other elements of the substitution are optional. |
| 271 |
|
| 272 |
</p><p>To include a single "%" character in the output, put two consecutive |
| 273 |
"%" characters in the template. |
| 274 |
|
| 275 |
</p><h2 id="substitution_types"><span>2.1. </span>Substitution Types</h2> |
| 276 |
|
| 277 |
<p>The following chart shows the substitution types supported by SQLite: |
| 278 |
|
| 279 |
</p><center> |
| 280 |
<table border="1" cellpadding="10" width="80%"> |
| 281 |
<tr> |
| 282 |
<th>Substitution Type</th><th>Meaning |
| 283 |
</th></tr><tr> |
| 284 |
<td>% |
| 285 |
</td><td>Two "%" characters in a row are translated into a single "%" in the output, |
| 286 |
without substituting any values. |
| 287 |
</td></tr><tr> |
| 288 |
<td>d, i |
| 289 |
</td><td>The argument is a signed integer which is displayed in decimal. |
| 290 |
</td></tr><tr> |
| 291 |
<td>u |
| 292 |
</td><td>The argument is an unsigned integer which is displayed in decimal. |
| 293 |
</td></tr><tr> |
| 294 |
<td>f |
| 295 |
</td><td>The argument is a double which is displayed in decimal. |
| 296 |
</td></tr><tr> |
| 297 |
<td>e, E |
| 298 |
</td><td>The argument is a double which is displayed in exponential notation. |
| 299 |
The exponent character is 'e' or 'E' depending on the type. |
| 300 |
</td></tr><tr> |
| 301 |
<td>g, G |
| 302 |
</td><td>The argument is a double which is displayed in either normal decimal |
| 303 |
notation or if the exponent is not close to zero, in exponential |
| 304 |
notation. |
| 305 |
</td></tr><tr> |
| 306 |
<td>x, X |
| 307 |
</td><td>The argument is an integer which is displayed in hexadecimal. |
| 308 |
Lower-case hexadecimal is used for %x and upper-case is used |
| 309 |
for %X |
| 310 |
</td></tr><tr> |
| 311 |
<td>o |
| 312 |
</td><td>The argument is an integer which is displayed in octal. |
| 313 |
</td></tr><tr> |
| 314 |
<td>s, z |
| 315 |
</td><td> |
| 316 |
<a name="percentz"></a> |
| 317 |
|
| 318 |
The argument is either a zero-terminated string that is displayed, |
| 319 |
or a null pointer which is treated as an empty string. For |
| 320 |
the %z type in C-language interfaces, <a href="c3ref/free.html">sqlite3_free()</a> is invoked |
| 321 |
on the string after it has been copied into the output. The %s and %z |
| 322 |
substitutions are identical for the SQL printf() function, with |
| 323 |
a NULL argument treated as an empty string.<br><br> |
| 324 |
The %s substitution is universal among printf functions, but |
| 325 |
the %z substitution and safe treatment of null pointers |
| 326 |
are SQLite enhancements, not found in other |
| 327 |
printf() implementations. |
| 328 |
Caution: Recent versions of GNU printf use %z to render size_t |
| 329 |
integer values. This is incompatible with SQLite's use of %z. |
| 330 |
</td></tr><tr> |
| 331 |
<td>c |
| 332 |
</td><td>For the C-language interfaces, the argument is an integer which |
| 333 |
is interpreted as a character. For the <a href="lang_corefunc.html#format">format() SQL function</a> the |
| 334 |
argument is a string from which the first character is extracted and |
| 335 |
displayed. |
| 336 |
</td></tr><tr> |
| 337 |
<td>p |
| 338 |
</td><td>The argument is a pointer which is displayed as a hexadecimal address. |
| 339 |
Since the SQL language has no concept of a pointer, the %p substitution |
| 340 |
for the <a href="lang_corefunc.html#format">format() SQL function</a> works like %x. |
| 341 |
</td></tr><tr> |
| 342 |
<td>n |
| 343 |
</td><td>The argument is a pointer to an integer. Nothing is displayed for |
| 344 |
this substitution type. Instead, the integer to which the argument |
| 345 |
points is overwritten with the number of characters in the generated |
| 346 |
string that result from all format symbols to the left of the %n. |
| 347 |
</td></tr><tr> |
| 348 |
<td>q, Q |
| 349 |
</td><td><a name="percentq"></a> |
| 350 |
|
| 351 |
The argument is a zero-terminated string. The string is printed with |
| 352 |
all single quote (') characters doubled so that the string can safely |
| 353 |
appear inside an SQL string literal. The %Q substitution type also |
| 354 |
puts single-quotes on both ends of the substituted string. |
| 355 |
<br><br>If the argument |
| 356 |
to %Q is a null pointer then the output is an unquoted "NULL". In other |
| 357 |
words, a null pointer generates an SQL NULL, and a non-null pointer generates |
| 358 |
a valid SQL string literal. If the argument to %q is a null pointer |
| 359 |
then no output is generated. Thus a null-pointer to %q is the same as |
| 360 |
an empty string. |
| 361 |
<br><br>If the <a href="printf.html#alt1">alternate-form-1 flag</a> ("#") is added to %Q (ex: "%#Q") |
| 362 |
then control codes in the range of U+0001 through U+001f are escaped |
| 363 |
using JSON-style backslash escapes and the entire output is enclosed |
| 364 |
in "<tt>unistr('</tt>...<tt>')</tt>". The resulting output is thus safe |
| 365 |
for display on devices that interpret |
| 366 |
<a href="https://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape sequences</a>. |
| 367 |
The "%#q" conversion escapes control characters likewise but does not |
| 368 |
add the <a href="lang_corefunc.html#unistr">unistr()</a> function wrapper. |
| 369 |
<br><br>For these substitutions, the precision is the number of bytes or |
| 370 |
characters taken from the argument, not the number of bytes or characters that |
| 371 |
are written into the output. |
| 372 |
<br><br> |
| 373 |
The %q and %Q substitutions are SQLite enhancements, not found in |
| 374 |
most other printf() implementations. |
| 375 |
</td></tr><tr> |
| 376 |
<td>w |
| 377 |
</td><td><a name="percentw"></a> |
| 378 |
|
| 379 |
This substitution works like %q except that it doubles all double-quote |
| 380 |
characters (") instead of single-quotes, making the result suitable for |
| 381 |
using with a double-quoted identifier name in an SQL statement. |
| 382 |
<br><br> |
| 383 |
The %w substitution is an SQLite enhancements, not found in |
| 384 |
most other printf() implementations. |
| 385 |
</td></tr></table> |
| 386 |
</center> |
| 387 |
|
| 388 |
<h2 id="the_optional_length_field"><span>2.2. </span>The Optional Length Field</h2> |
| 389 |
|
| 390 |
<p>The length of the argument value can be specified by one or more letters |
| 391 |
that occur just prior to the substitution type letter. In SQLite, the |
| 392 |
length only matter for integer types. The length is ignored for the |
| 393 |
<a href="lang_corefunc.html#format">format() SQL function</a> which always uses 64-bit values. The following |
| 394 |
table shows the length specifiers allowed by SQLite: |
| 395 |
|
| 396 |
</p><center> |
| 397 |
<table border="1" cellpadding="10" width="80%"> |
| 398 |
<tr> |
| 399 |
<th>Length Specifier |
| 400 |
</th><th>Meaning |
| 401 |
</th></tr><tr> |
| 402 |
<td><i>(default)</i> |
| 403 |
</td><td>An "int" or "unsigned int". 32-bits on all modern systems. |
| 404 |
</td></tr><tr> |
| 405 |
<td>l |
| 406 |
</td><td>A "long int" or "long unsigned int". Also 32-bits on all modern systems. |
| 407 |
</td></tr><tr> |
| 408 |
<td>ll |
| 409 |
</td><td>A "long long int" or "long long unsigned" or an "sqlite3_int64" or |
| 410 |
"sqlite3_uint64" value. These are 64-bit integers on all modern systems. |
| 411 |
</td></tr></table> |
| 412 |
</center> |
| 413 |
|
| 414 |
<p>Only the "ll" length modifier ever makes a difference for SQLite. And |
| 415 |
it only makes a difference when using the C-language interfaces. |
| 416 |
|
| 417 |
</p><h2 id="the_optional_width_field"><span>2.3. </span>The Optional Width Field</h2> |
| 418 |
|
| 419 |
<p>The width field specifies the minimum width of the substituted value in |
| 420 |
the output. If the string or number that is written into the output is shorter |
| 421 |
than the width, then the value is padded. Padding is on the left (the |
| 422 |
value is right-justified) by default. If the "-" flag is used, then the |
| 423 |
padding is on the right and the value is left-justified. |
| 424 |
|
| 425 |
</p><p>The width is measured in bytes by default. However, if the "!" flag is |
| 426 |
present then the width is in characters. This only makes a difference for |
| 427 |
multi-byte utf-8 characters, and those only occur on string substitutions. |
| 428 |
|
| 429 |
</p><p>If the width is a single "*" character instead of a number, then the |
| 430 |
actual width value is read as an integer from the argument list. If the |
| 431 |
value read is negative, then the absolute value is used for the width and |
| 432 |
the value is left-justified as if the "-" flag were present. |
| 433 |
|
| 434 |
</p><p>If the value being substituted is larger than the width, then full value |
| 435 |
is added to the output. In other words, the width is the minimum width of |
| 436 |
the value as it is rendered in the output. |
| 437 |
|
| 438 |
</p><h2 id="the_optional_precision_field"><span>2.4. </span>The Optional Precision Field</h2> |
| 439 |
|
| 440 |
<p>The precision field, if it is present, must follow the width separated |
| 441 |
by a single "." character. If there is no width, then the "." that introduces |
| 442 |
the precision immediately follows either the flags (if there are any) or |
| 443 |
the initial "%". |
| 444 |
|
| 445 |
</p><p>For string substitutions %s, %z, %q, %Q, or %w the precision is the number |
| 446 |
of bytes or characters used from the argument. The number is bytes by default |
| 447 |
but is characters if the "!" flag is present. If there is no precision, then the |
| 448 |
entire string is substituted. Examples: "%.3s" substitutes the first 3 bytes |
| 449 |
of the argument string. "%!.3s" substitutes the first three characters of the |
| 450 |
argument string. |
| 451 |
|
| 452 |
</p><p>For integer substitutions %d, %i, %x, %X, %o, and %p the precision specifies |
| 453 |
a minimum number of digits to display. Leading zeros are added if necessary, |
| 454 |
to expand the output to the minimum number of digits. |
| 455 |
|
| 456 |
</p><p>For floating-point substitutions %e, %E, and %f the precision specifies |
| 457 |
the number of digits to display to the right of the decimal point. With |
| 458 |
the %g and %G, the precision is the total number of significant digits, rounded |
| 459 |
up to 1 if the specified precision is 0. |
| 460 |
|
| 461 |
</p><p>For the character substitution %c a precision N greater than 1 causes the |
| 462 |
character to be repeated N times. This is a non-standard extension found only |
| 463 |
in SQLite. |
| 464 |
|
| 465 |
</p><p>If the precision is a single "*" character instead of a number, then the |
| 466 |
actual precision value is read as an integer from the argument list. |
| 467 |
|
| 468 |
</p><h2 id="the_options_flags_field"><span>2.5. </span>The Options Flags Field</h2> |
| 469 |
|
| 470 |
<p>Flags consist of zero or more characters that immediately follow the |
| 471 |
"%" that introduces the substitution. The various flags and their meanings |
| 472 |
are as follows: |
| 473 |
|
| 474 |
</p><center> |
| 475 |
<table border="1" cellpadding="10" width="80%"> |
| 476 |
<tr> |
| 477 |
<th>Flag |
| 478 |
</th><th>Meaning |
| 479 |
</th></tr><tr> |
| 480 |
<td><b>-</b> |
| 481 |
</td><td>Left-justify the value in the output. The default is to right-justify. |
| 482 |
If the width is zero or is otherwise less than the length of the value being |
| 483 |
substituted, then there is no padding and the "-" flag is a no-op. |
| 484 |
</td></tr><tr> |
| 485 |
<td><b>+</b> |
| 486 |
</td><td>For signed numeric substitutions, include a "+" sign before positive numbers. |
| 487 |
A "-" sign always appears before negative numbers regardless of flag settings. |
| 488 |
</td></tr><tr> |
| 489 |
<td><i>(space)</i> |
| 490 |
</td><td>For signed numeric substitutions, prepend a single space before positive |
| 491 |
numbers. |
| 492 |
</td></tr><tr> |
| 493 |
<td><b>0</b> |
| 494 |
</td><td>(The zero-padding option) |
| 495 |
Prepend as many "0" characters to numeric substitutions as necessary to |
| 496 |
expand the value out to the specified width. If the width field is omitted, |
| 497 |
then this flag is a no-op. |
| 498 |
Infinity and NaN (Not-A-Number) floating point values are normally rendered |
| 499 |
as "Inf" and "NaN", respectively, but with the zero-padding option enabled |
| 500 |
they are rendered as "9.0e+999" and "null". In other words, with the zero-padding |
| 501 |
option, floating-point Infinity and NaN are rendered as valid SQL and JSON literals. |
| 502 |
</td></tr><tr> |
| 503 |
<td><b>#</b> |
| 504 |
</td><td><a name="alt1"></a> |
| 505 |
|
| 506 |
This is the "alternate-form-1" flag. Its meaning depends on the specific |
| 507 |
conversion. |
| 508 |
<ul> |
| 509 |
<li> For %#g and %#G substitutions, this causes trailing zeros to be removed. |
| 510 |
</li><li> For the %#f substitution, minus signs are suppressed if the '+' flag is omitted |
| 511 |
and if all displayed digits are zero. Thus, for example, '%#.2f' renders |
| 512 |
the value -0.004 as "0.00" instead of "-0.00". |
| 513 |
</li><li> This flag forces a decimal point to appear for all floating-point substitutions. |
| 514 |
</li><li> For %#o, %#x, and %#X substitutions, the alternate-form-1 flag causes the |
| 515 |
value to be prepended with "0", "0x", or "0X", respectively. |
| 516 |
</li><li> For %#Q, the alternate-form-1 flag causes a string that contains C0 control codes |
| 517 |
(ASCII characters 0x01 through 0x1f) to be rendered as |
| 518 |
a call to the <a href="lang_corefunc.html#unistr">unistr() SQL function</a> with a string literal argument |
| 519 |
that contains JSON-style backslash-escapes to code those control codes and for the |
| 520 |
"\" character itself. |
| 521 |
</li><li> For %#q, the generated text adds backslash-escapes for any control codes and for |
| 522 |
the '\' character, but does not add the <tt>unistr('...')</tt> wrapper because |
| 523 |
%q is intended for use within a larger string literal and it does not control the |
| 524 |
boundary markers. |
| 525 |
</li></ul> |
| 526 |
</td></tr><tr> |
| 527 |
<a name="comma"></a> |
| 528 |
|
| 529 |
<td><b>,</b> |
| 530 |
</td><td>The comma option causes comma separators to be added to the output of numeric |
| 531 |
substitutions (%d, %f, and similar) before every 3rd digits to the left of |
| 532 |
the decimal point. No commas are added for digits to the right of the decimal point. |
| 533 |
This can help humans to more easily discern the magnitude of large integer values. |
| 534 |
For example, |
| 535 |
the value 2147483647 would be rendered as "2147483647" using "%d" but would |
| 536 |
appear as "2,147,483,647" with "%,d". This flag is a non-standard extension. |
| 537 |
</td></tr><tr> |
| 538 |
<td><b>!</b> |
| 539 |
</td><td>This is the "alternate-form-2 flag. |
| 540 |
For string substitutions, this flag causes the width and precision to be |
| 541 |
understood in terms of characters rather than bytes. |
| 542 |
For floating point substitutions, the alternate-form-2 flag increases the |
| 543 |
maximum number of significant digits displayed from 16 to 26, |
| 544 |
forces the display of the decimal point and causes at least one digit |
| 545 |
to appear after the decimal point.<br><br> |
| 546 |
The alternate-form-2 flag is a non-standard extension that appears in no |
| 547 |
other printf() implementations, as far as we know. |
| 548 |
</td></tr></table> |
| 549 |
</center> |
| 550 |
|
| 551 |
<h1 id="implementation_and_history"><span>3. </span>Implementation And History</h1> |
| 552 |
|
| 553 |
<p> |
| 554 |
The core string formatting routine is the sqlite3VXPrintf() function found in the |
| 555 |
<a href="https://sqlite.org/src/file/src/printf.c">printf.c</a> source file. All the |
| 556 |
various interfaces invoke (sometimes indirectly) this one core function. |
| 557 |
The sqlite3VXPrintf() function began as code written by the first author |
| 558 |
of SQLite (<a href="crew.html">Hipp</a>) when he was a graduate student at Duke University in the |
| 559 |
late 1980s. Hipp kept this printf() implementation in his personal toolbox until |
| 560 |
he started working on SQLite in 2000. The code was incorporated into the |
| 561 |
SQLite source tree on <a href="https://sqlite.org/src/timeline?c=f9372072a6">2000-10-08</a> |
| 562 |
for SQLite version 1.0.9. |
| 563 |
|
| 564 |
</p><p> |
| 565 |
The <a href="https://www.fossil-scm.org/">Fossil Version Control System</a> uses its own |
| 566 |
printf() implementation that is derived from an early version of the SQLite |
| 567 |
printf() implementation, but those two implementations have since diverged. |
| 568 |
|
| 569 |
</p><p> |
| 570 |
The <a href="c3ref/mprintf.html">sqlite3_snprintf()</a> function has its buffer pointer and buffer size |
| 571 |
arguments reversed from what is found in the standard C library snprintf() |
| 572 |
routine. This is because there was no snprintf() routine in the |
| 573 |
standard C library |
| 574 |
when Hipp was first implementing his version, and he chose a different order |
| 575 |
than the designers of the standard C library. |
| 576 |
</p><p align="center"><small><i>This page was last updated on 2026-05-07 15:07:22Z </small></i></p> |
| 577 |
|