📄 create_collation.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Define New Collating Sequences</title><style type="text/css">body { margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px;}.toolbar { font-variant: small-caps; text-align: center; line-height: 1.6em; margin: 0; padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw { background: url(../images/sw.png) 0% 100% no-repeat }.ne { background: url(../images/ne.png) 100% 0% no-repeat }.nw { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td> <div class="se"><div class="sw"><div class="ne"><div class="nw"> <div class="toolbar"> <a href="../about.html">About</a> <a href="../sitemap.html">Sitemap</a> <a href="../docs.html">Documentation</a> <a href="../download.html">Download</a> <a href="../copyright.html">License</a> <a href="../news.html">News</a> <a href="http://www.sqlite.org/cvstrac/index">Developers</a> <a href="../support.html">Support</a> </div></div></div></div></div></td></tr></table> <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Define New Collating Sequences</h2><blockquote><pre>int sqlite3_create_collation( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*));int sqlite3_create_collation_v2( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*), void(*xDestroy)(void*));int sqlite3_create_collation16( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*));</pre></blockquote><p>These functions are used to add new collation sequences to the<a href="../c3ref/sqlite3.html">sqlite3*</a> handle specified as the first argument.</p><p>The name of the new collation sequence is specified as a UTF-8 stringfor sqlite3_create_collation() and sqlite3_create_collation_v2()and a UTF-16 string for sqlite3_create_collation16(). In all casesthe name is passed as the second function argument.</p><p>The third argument may be one of the constants <a href="../c3ref/c_any.html">SQLITE_UTF8</a>,<a href="../c3ref/c_any.html">SQLITE_UTF16LE</a> or <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>, indicating that the user-suppliedroutine expects to be passed pointers to strings encoded using UTF-8,UTF-16 little-endian or UTF-16 big-endian respectively. Thethird argument might also be <a href="../c3ref/c_any.html">SQLITE_UTF16_ALIGNED</a> to indicate thatthe routine expects pointers to 16-bit word aligned stringsof UTF16 in the native byte order of the host computer.</p><p>A pointer to the user supplied routine must be passed as the fifthargument. If it is NULL, this is the same as deleting the collationsequence (so that SQLite cannot call it anymore).Each time the applicationsupplied function is invoked, it is passed a copy of the void* passed asthe fourth argument to sqlite3_create_collation() orsqlite3_create_collation16() as its first parameter.</p><p>The remaining arguments to the application-supplied routine are two strings,each represented by a (length, data) pair and encoded in the encodingthat was passed as the third argument when the collation sequence wasregistered. The application defined collation routine shouldreturn negative, zero or positive ifthe first string is less than, equal to, or greater than the secondstring. i.e. (STRING1 - STRING2).</p><p>The sqlite3_create_collation_v2() works like sqlite3_create_collation()excapt that it takes an extra argument which is a destructor forthe collation. The destructor is called when the collation isdestroyed and is passed a copy of the fourth parameter void* pointerof the sqlite3_create_collation_v2().Collations are destroyed whenthey are overridden by later calls to the collation creation functionsor when the <a href="../c3ref/sqlite3.html">sqlite3*</a> database handle is closed using <a href="../c3ref/close.html">sqlite3_close()</a>.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F16603</td> <td valign="top">A successful call to the<a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a> interfaceregisters function F as the comparison function used toimplement collation X on <a href="../c3ref/sqlite3.html">database connection</a> B fordatabases having encoding E.</td></tr><tr><td valign="top">F16604</td> <td valign="top">SQLite understands the X parameter to<a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a> as a zero-terminatedUTF-8 string in which case is ignored for ASCII characters andis significant for non-ASCII characters.</td></tr><tr><td valign="top">F16606</td> <td valign="top">Successive calls to <a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a>with the same values for B, X, and E, override prior valuesof P, F, and D.</td></tr><tr><td valign="top">F16609</td> <td valign="top">The destructor D in <a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a>is not NULL then it is called with argument P when thecollating function is dropped by SQLite.</td></tr><tr><td valign="top">F16612</td> <td valign="top">A collating function is dropped when it is overloaded.</td></tr><tr><td valign="top">F16615</td> <td valign="top">A collating function is dropped when the database connectionis closed using <a href="../c3ref/close.html">sqlite3_close()</a>.</td></tr><tr><td valign="top">F16618</td> <td valign="top">The pointer P in <a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a>is passed through as the first parameter to the comparisonfunction F for all subsequent invocations of F.</td></tr><tr><td valign="top">F16621</td> <td valign="top">A call to <a href="../c3ref/create_collation.html">sqlite3_create_collation(B,X,E,P,F)</a> is exactlythe same as a call to <a href="../c3ref/create_collation.html">sqlite3_create_collation_v2()</a> withthe same parameters and a NULL destructor.</td></tr><tr><td valign="top">F16624</td> <td valign="top">Following a <a href="../c3ref/create_collation.html">sqlite3_create_collation_v2(B,X,E,P,F,D)</a>,SQLite uses the comparison function F for all text comparisonoperations on <a href="../c3ref/sqlite3.html">database connection</a> B on text values thatuse the collating sequence name X.</td></tr><tr><td valign="top">F16627</td> <td valign="top">The <a href="../c3ref/create_collation.html">sqlite3_create_collation16(B,X,E,P,F)</a> works the sameas <a href="../c3ref/create_collation.html">sqlite3_create_collation(B,X,E,P,F)</a> except that thecollation name X is understood as UTF-16 in native byte orderinstead of UTF-8.</td></tr><tr><td valign="top">F16630</td> <td valign="top">When multiple comparison functions are available for the samecollating sequence, SQLite chooses the one whose text encodingrequires the least amount of conversion from the defaulttext encoding of the database.</td></tr></table></p><p>See also lists of <a href="objlist.html">Objects</a>, <a href="constlist.html">Constants</a>, and <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/05/12 13:08:44 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -