Debian Codegraph @

www/c3ref/create_collation.html

raw
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>Define New Collating Sequences</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 <!-- keywords: sqlite3_create_collation sqlite3_create_collation16 sqlite3_create_collation_v2 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Define New Collating Sequences</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_create_collation(
125 sqlite3*,
126 const char *zName,
127 int eTextRep,
128 void *pArg,
129 int(*xCompare)(void*,int,const void*,int,const void*)
130 );
131 int sqlite3_create_collation_v2(
132 sqlite3*,
133 const char *zName,
134 int eTextRep,
135 void *pArg,
136 int(*xCompare)(void*,int,const void*,int,const void*),
137 void(*xDestroy)(void*)
138 );
139 int sqlite3_create_collation16(
140 sqlite3*,
141 const void *zName,
142 int eTextRep,
143 void *pArg,
144 int(*xCompare)(void*,int,const void*,int,const void*)
145 );
146 </pre></blockquote>
147 <p>
148 These functions add, remove, or modify a <a href="../datatype3.html#collation">collation</a> associated
149 with the <a href="../c3ref/sqlite3.html">database connection</a> specified as the first argument.</p>
150
151 <p>The name of the collation is a UTF-8 string
152 for sqlite3_create_collation() and sqlite3_create_collation_v2()
153 and a UTF-16 string in native byte order for sqlite3_create_collation16().
154 Collation names that compare equal according to <a href="../c3ref/stricmp.html">sqlite3_strnicmp()</a> are
155 considered to be the same name.</p>
156
157 <p>The third argument (eTextRep) must be one of the constants:
158 <ul>
159 <li> <a href="../c3ref/c_any.html#sqliteutf8">SQLITE_UTF8</a>,
160 <li> <a href="../c3ref/c_any.html#sqliteutf16le">SQLITE_UTF16LE</a>,
161 <li> <a href="../c3ref/c_any.html#sqliteutf16be">SQLITE_UTF16BE</a>,
162 <li> <a href="../c3ref/c_any.html#sqliteutf16">SQLITE_UTF16</a>, or
163 <li> <a href="../c3ref/c_any.html#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a>.
164 </ul>
165 The eTextRep argument determines the encoding of strings passed
166 to the collating function callback, xCompare.
167 The <a href="../c3ref/c_any.html#sqliteutf16">SQLITE_UTF16</a> and <a href="../c3ref/c_any.html#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a> values for eTextRep
168 force strings to be UTF16 with native byte order.
169 The <a href="../c3ref/c_any.html#sqliteutf16aligned">SQLITE_UTF16_ALIGNED</a> value for eTextRep forces strings to begin
170 on an even byte address.</p>
171
172 <p>The fourth argument, pArg, is an application data pointer that is passed
173 through as the first argument to the collating function callback.</p>
174
175 <p>The fifth argument, xCompare, is a pointer to the collating function.
176 Multiple collating functions can be registered using the same name but
177 with different eTextRep parameters and SQLite will use whichever
178 function requires the least amount of data transformation.
179 If the xCompare argument is NULL then the collating function is
180 deleted. When all collating functions having the same name are deleted,
181 that collation is no longer usable.</p>
182
183 <p>The collating function callback is invoked with a copy of the pArg
184 application data pointer and with two strings in the encoding specified
185 by the eTextRep argument. The two integer parameters to the collating
186 function callback are the length of the two strings, in bytes. The collating
187 function must return an integer that is negative, zero, or positive
188 if the first string is less than, equal to, or greater than the second,
189 respectively. A collating function must always return the same answer
190 given the same inputs. If two or more collating functions are registered
191 to the same collation name (using different eTextRep values) then all
192 must give an equivalent answer when invoked with equivalent strings.
193 The collating function must obey the following properties for all
194 strings A, B, and C:</p>
195
196 <p><ol>
197 <li> If A==B then B==A.
198 <li> If A==B and B==C then A==C.
199 <li> If A&lt;B THEN B&gt;A.
200 <li> If A&lt;B and B&lt;C then A&lt;C.
201 </ol></p>
202
203 <p>If a collating function fails any of the above constraints and that
204 collating function is registered and used, then the behavior of SQLite
205 is undefined.</p>
206
207 <p>The sqlite3_create_collation_v2() works like sqlite3_create_collation()
208 with the addition that the xDestroy callback is invoked on pArg when
209 the collating function is deleted.
210 Collating functions are deleted when they are overridden by later
211 calls to the collation creation functions or when the
212 <a href="../c3ref/sqlite3.html">database connection</a> is closed using <a href="../c3ref/close.html">sqlite3_close()</a>.</p>
213
214 <p>The xDestroy callback is <u>not</u> called if the
215 sqlite3_create_collation_v2() function fails. Applications that invoke
216 sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
217 check the return code and dispose of the application data pointer
218 themselves rather than expecting SQLite to deal with it for them.
219 This is different from every other SQLite interface. The inconsistency
220 is unfortunate but cannot be changed without breaking backwards
221 compatibility.</p>
222
223 <p>See also: <a href="../c3ref/collation_needed.html">sqlite3_collation_needed()</a> and <a href="../c3ref/collation_needed.html">sqlite3_collation_needed16()</a>.
224 </p><p>See also lists of
225 <a href="../c3ref/objlist.html">Objects</a>,
226 <a href="../c3ref/constlist.html">Constants</a>, and
227 <a href="../c3ref/funclist.html">Functions</a>.</p>
228