1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.4.5" />
7 <title>string-list API
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
245 list-style-type: upper-roman
;
248 div
.compact ul
, div
.compact ol
,
249 div
.compact p
, div
.compact p
,
250 div
.compact div
, div
.compact div
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
275 div
.tableblock
> table
[frame
="hsides"] {
276 border-left-style: none
;
277 border-right-style: none
;
279 div
.tableblock
> table
[frame
="vsides"] {
280 border-top-style: none
;
281 border-bottom-style: none
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Workarounds for IE6's broken and incomplete CSS2. */
344 div
.sidebar-content
{
346 border: 1px solid silver
;
349 div
.sidebar-title
, div
.image-title
{
351 font-family: sans-serif
;
354 margin-bottom: 0.5em;
357 div
.listingblock div
.content
{
358 border: 1px solid silver
;
363 div
.quoteblock-attribution
{
368 div
.verseblock-content
{
371 div
.verseblock-attribution
{
376 div
.exampleblock-content
{
377 border-left: 2px solid silver
;
381 /* IE6 sets dynamically generated links as visited. */
382 div#toc
a:visited
{ color: blue
; }
387 <h1>string-list API
</h1>
390 <div class=
"sectionbody">
391 <div class=
"paragraph"><p>The string_list API offers a data structure and functions to handle sorted
392 and unsorted string lists.
</p></div>
393 <div class=
"paragraph"><p>The
<em>string_list
</em> struct used to be called
<em>path_list
</em>, but was renamed
394 because it is not specific to paths.
</p></div>
395 <div class=
"paragraph"><p>The caller:
</p></div>
396 <div class=
"olist arabic"><ol class=
"arabic">
399 Allocates and clears a
<tt>struct string_list
</tt> variable.
404 Initializes the members. You might want to set the flag
<tt>strdup_strings
</tt>
405 if the strings should be strdup()ed. For example, this is necessary
406 when you add something like git_path(
"…"), since that function returns
407 a static buffer that will change with the next call to git_path().
409 <div class=
"paragraph"><p>If you need something advanced, you can manually malloc() the
<tt>items
</tt>
410 member (you need this if you add things later) and you should set the
411 <tt>nr
</tt> and
<tt>alloc
</tt> members in that case, too.
</p></div>
415 Adds new items to the list, using
<tt>string_list_append
</tt> or
416 <tt>string_list_insert
</tt>.
421 Can check if a string is in the list using
<tt>string_list_has_string
</tt> or
422 <tt>unsorted_string_list_has_string
</tt> and get it from the list using
423 <tt>string_list_lookup
</tt> for sorted lists.
428 Can sort an unsorted list using
<tt>sort_string_list
</tt>.
433 Finally it should free the list using
<tt>string_list_clear
</tt>.
437 <div class=
"paragraph"><p>Example:
</p></div>
438 <div class=
"listingblock">
439 <div class=
"content">
440 <pre><tt>struct string_list list;
443 memset(
&list,
0, sizeof(struct string_list));
444 string_list_append(
&list,
"foo");
445 string_list_append(
&list,
"bar");
446 for (i =
0; i
< list.nr; i++)
447 printf(
"%s\n", list.items[i].string)
</tt></pre>
449 <div class=
"admonitionblock">
452 <div class=
"title">Note
</div>
454 <td class=
"content">It is more efficient to build an unsorted list and sort it
455 afterwards, instead of building a sorted list (
<tt>O(n log n)
</tt> instead of
456 <tt>O(n^
2)
</tt>).
</td>
459 <div class=
"paragraph"><p>+
460 However, if you use the list to check if a certain string was added
461 already, you should not do that (using unsorted_string_list_has_string()),
462 because the complexity would be quadratic again (but with a worse factor).
</p></div>
465 <h2 id=
"_functions">Functions
</h2>
466 <div class=
"sectionbody">
467 <div class=
"ulist"><ul>
470 General ones (works with sorted and unsorted lists as well)
472 <div class=
"dlist"><dl>
474 <tt>print_string_list
</tt>
478 Dump a string_list to stdout, useful mainly for debugging purposes. It
479 can take an optional header argument and it writes out the
480 string-pointer pairs of the string_list, each one in its own line.
484 <tt>string_list_clear
</tt>
488 Free a string_list. The
<tt>string
</tt> pointer of the items will be freed in
489 case the
<tt>strdup_strings
</tt> member of the string_list is set. The second
490 parameter controls if the
<tt>util
</tt> pointer of the items should be freed
498 Functions for sorted lists only
500 <div class=
"dlist"><dl>
502 <tt>string_list_has_string
</tt>
506 Determine if the string_list has a given string or not.
510 <tt>string_list_insert
</tt>
514 Insert a new element to the string_list. The returned pointer can be
515 handy if you want to write something to the
<tt>util
</tt> pointer of the
516 string_list_item containing the just added string.
518 <div class=
"paragraph"><p>Since this function uses xrealloc() (which die()s if it fails) if the
519 list needs to grow, it is safe not to check the pointer. I.e. you may
520 write
<tt>string_list_insert(
…)
→util =
…;
</tt>.
</p></div>
523 <tt>string_list_lookup
</tt>
527 Look up a given string in the string_list, returning the containing
528 string_list_item. If the string is not found, NULL is returned.
535 Functions for unsorted lists only
537 <div class=
"dlist"><dl>
539 <tt>string_list_append
</tt>
543 Append a new string to the end of the string_list.
547 <tt>sort_string_list
</tt>
551 Make an unsorted list sorted.
555 <tt>unsorted_string_list_has_string
</tt>
559 It
’s like
<tt>string_list_has_string()
</tt> but for unsorted lists.
563 <tt>unsorted_string_list_lookup
</tt>
567 It
’s like
<tt>string_list_lookup()
</tt> but for unsorted lists.
569 <div class=
"paragraph"><p>The above two functions need to look through all items, as opposed to their
570 counterpart for sorted lists, which performs a binary search.
</p></div>
576 <h2 id=
"_data_structures">Data structures
</h2>
577 <div class=
"sectionbody">
578 <div class=
"ulist"><ul>
581 <tt>struct string_list_item
</tt>
585 <div class=
"paragraph"><p>Represents an item of the list. The
<tt>string
</tt> member is a pointer to the
586 string, and you may use the
<tt>util
</tt> member for any purpose, if you want.
</p></div>
587 <div class=
"ulist"><ul>
590 <tt>struct string_list
</tt>
594 <div class=
"paragraph"><p>Represents the list itself.
</p></div>
595 <div class=
"olist arabic"><ol class=
"arabic">
598 The array of items are available via the
<tt>items
</tt> member.
603 The
<tt>nr
</tt> member contains the number of items stored in the list.
608 The
<tt>alloc
</tt> member is used to avoid reallocating at every insertion.
609 You should not tamper with it.
614 Setting the
<tt>strdup_strings
</tt> member to
1 will strdup() the strings
615 before adding them, see above.
621 <div id=
"footer-text">
622 Last updated
2010-
07-
01 00:
08:
13 UTC