1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Define New Collating Sequences</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Define New Collating Sequences</h2><blockquote><pre>int sqlite3_create_collation(
125
int(*xCompare)(void*,int,const void*,int,const void*)
127
int sqlite3_create_collation_v2(
132
int(*xCompare)(void*,int,const void*,int,const void*),
133
void(*xDestroy)(void*)
135
int sqlite3_create_collation16(
140
int(*xCompare)(void*,int,const void*,int,const void*)
142
</pre></blockquote><p>
143
These functions add, remove, or modify a <a href="../datatype3.html#collation">collation</a> associated
144
with the <a href="../c3ref/sqlite3.html">database connection</a> specified as the first argument.</p>
146
<p>The name of the collation is a UTF-8 string
147
for sqlite3_create_collation() and sqlite3_create_collation_v2()
148
and a UTF-16 string in native byte order for sqlite3_create_collation16().
149
Collation names that compare equal according to <a href="../c3ref/stricmp.html">sqlite3_strnicmp()</a> are
150
considered to be the same name.</p>
152
<p>The third argument (eTextRep) must be one of the constants:
154
<li> <a href="../c3ref/c_any.html">SQLITE_UTF8</a>,
155
<li> <a href="../c3ref/c_any.html">SQLITE_UTF16LE</a>,
156
<li> <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>,
157
<li> <a href="../c3ref/c_any.html">SQLITE_UTF16</a>, or
158
<li> <a href="../c3ref/c_any.html">SQLITE_UTF16_ALIGNED</a>.
160
The eTextRep argument determines the encoding of strings passed
161
to the collating function callback, xCallback.
162
The <a href="../c3ref/c_any.html">SQLITE_UTF16</a> and <a href="../c3ref/c_any.html">SQLITE_UTF16_ALIGNED</a> values for eTextRep
163
force strings to be UTF16 with native byte order.
164
The <a href="../c3ref/c_any.html">SQLITE_UTF16_ALIGNED</a> value for eTextRep forces strings to begin
165
on an even byte address.</p>
167
<p>The fourth argument, pArg, is an application data pointer that is passed
168
through as the first argument to the collating function callback.</p>
170
<p>The fifth argument, xCallback, is a pointer to the collating function.
171
Multiple collating functions can be registered using the same name but
172
with different eTextRep parameters and SQLite will use whichever
173
function requires the least amount of data transformation.
174
If the xCallback argument is NULL then the collating function is
175
deleted. When all collating functions having the same name are deleted,
176
that collation is no longer usable.</p>
178
<p>The collating function callback is invoked with a copy of the pArg
179
application data pointer and with two strings in the encoding specified
180
by the eTextRep argument. The collating function must return an
181
integer that is negative, zero, or positive
182
if the first string is less than, equal to, or greater than the second,
183
respectively. A collating function must always return the same answer
184
given the same inputs. If two or more collating functions are registered
185
to the same collation name (using different eTextRep values) then all
186
must give an equivalent answer when invoked with equivalent strings.
187
The collating function must obey the following properties for all
188
strings A, B, and C:</p>
191
<li> If A==B then B==A.
192
<li> If A==B and B==C then A==C.
193
<li> If A<B THEN B>A.
194
<li> If A<B and B<C then A<C.
197
<p>If a collating function fails any of the above constraints and that
198
collating function is registered and used, then the behavior of SQLite
201
<p>The sqlite3_create_collation_v2() works like sqlite3_create_collation()
202
with the addition that the xDestroy callback is invoked on pArg when
203
the collating function is deleted.
204
Collating functions are deleted when they are overridden by later
205
calls to the collation creation functions or when the
206
<a href="../c3ref/sqlite3.html">database connection</a> is closed using <a href="../c3ref/close.html">sqlite3_close()</a>.</p>
208
<p>The xDestroy callback is <u>not</u> called if the
209
sqlite3_create_collation_v2() function fails. Applications that invoke
210
sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
211
check the return code and dispose of the application data pointer
212
themselves rather than expecting SQLite to deal with it for them.
213
This is different from every other SQLite interface. The inconsistency
214
is unfortunate but cannot be changed without breaking backwards
217
<p>See also: <a href="../c3ref/collation_needed.html">sqlite3_collation_needed()</a> and <a href="../c3ref/collation_needed.html">sqlite3_collation_needed16()</a>.
218
</p><p>See also lists of
219
<a href="objlist.html">Objects</a>,
220
<a href="constlist.html">Constants</a>, and
221
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/create_collation.html
