| blob | cd63f6a661b61934d26aaa4f286a24d69047e7d7 |
4 <head>
9 /* Debug borders */
11 /*
12 border: 1px solid red;
13 */
14 }
16 body {
18 }
20 a {
23 }
26 }
28 em {
31 }
33 strong {
36 }
38 tt {
40 }
48 }
52 }
53 h2 {
55 }
56 h3 {
58 }
59 h3 + * {
61 }
66 }
68 hr {
70 }
72 p {
75 }
79 }
81 pre {
84 }
86 span#author {
91 }
92 span#email {
93 }
96 }
98 div#footer {
104 }
105 div#footer-text {
108 }
109 div#footer-badges {
112 }
114 div#preamble {
117 }
123 }
127 }
131 }
133 /* Block element titles. */
141 }
144 }
148 }
151 }
154 }
160 }
166 }
171 }
175 }
180 }
183 }
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 }
200 }
204 }
209 }
215 dl {
218 }
219 dt {
224 }
227 }
231 }
234 }
237 }
240 }
243 }
246 }
253 }
257 }
258 thead {
261 }
262 tfoot {
264 }
267 }
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 }
278 }
282 }
288 }
291 }
294 }
300 }
303 }
307 }
311 }
315 }
317 div#toctitle {
324 }
329 }
333 }
337 }
341 }
342 /* Workarounds for IE6's broken and incomplete CSS2. */
348 }
355 }
361 }
366 }
370 }
374 }
379 }
381 /* IE6 sets dynamically generated links as visited. */
383 </style>
384 </head>
385 <body>
388 </div>
391 <div class="paragraph"><p>strbuf’s are meant to be used with all the usual C string and memory
392 APIs. Given that the length of the buffer is known, it’s often better to
393 use the mem* functions than a str* one (memchr vs. strchr e.g.).
394 Though, one has to be careful about the fact that str* functions often
395 stop on NULs and that strbufs may have embedded NULs.</p></div>
397 strbuf API actually relies on the string being free of NULs.</p></div>
398 <div class="paragraph"><p>strbufs has some invariants that are very important to keep in mind:</p></div>
400 <li>
401 <p>
405 </p>
406 <div class="paragraph"><p>Do <strong>not</strong> assume anything on what <tt>buf</tt> really is (e.g. if it is
408 buffer from its strbuf shell in a safe way. That is the sole supported
410 <div class="paragraph"><p>However, it is totally safe to modify anything in the string pointed by
411 the <tt>buf</tt> member, between the indices <tt>0</tt> and <tt>len-1</tt> (inclusive).</p></div>
412 </li>
413 <li>
414 <p>
418 invariant is preserved.
419 </p>
421 <table><tr>
424 </td>
426 way:</td>
427 </tr></table>
428 </div>
433 </div></div>
435 <li>
436 <p>
440 </p>
442 <table><tr>
445 </td>
446 <td class="content"><tt>SOME_OTHER_SIZE</tt> must be smaller or equal to <tt>strbuf_avail(sb)</tt>.</td>
447 </tr></table>
448 </div>
449 <div class="paragraph"><p>Doing so is safe, though if it has to be done in many places, adding the
450 missing API to the strbuf module is the way to go.</p></div>
452 <table><tr>
455 </td>
459 instead.</td>
460 </tr></table>
461 </div>
462 </li>
463 </ol></div>
464 </li>
465 </ol></div>
466 </div>
467 </div>
471 <li>
472 <p>
474 </p>
475 </li>
476 </ul></div>
477 <div class="paragraph"><p>This is the string buffer structure. The <tt>len</tt> member can be used to
479 the string itself.</p></div>
480 </div>
484 <li>
485 <p>
486 Life cycle
487 </p>
491 </dt>
492 <dd>
493 <p>
494 Initialize the structure. The second parameter can be zero or a bigger
495 number to allocate memory, in case you want to prevent further reallocs.
496 </p>
497 </dd>
500 </dt>
501 <dd>
502 <p>
503 Release a string buffer and the memory it used. You should not use the
504 string buffer after using this function, unless you initialize it again.
505 </p>
506 </dd>
509 </dt>
510 <dd>
511 <p>
512 Detach the string from the strbuf and returns it; you now own the
513 storage the string occupies and it is your responsibility from then on
515 </p>
516 </dd>
519 </dt>
520 <dd>
521 <p>
522 Attach a string to a buffer. You should specify the string to attach,
523 the current length of the string and the amount of allocated memory.
524 The amount must be larger than the string length, because the string you
526 malloc()ed, and after attaching, the pointer cannot be relied upon
527 anymore, and neither be free()d directly.
528 </p>
529 </dd>
532 </dt>
533 <dd>
534 <p>
535 Swap the contents of two string buffers.
536 </p>
537 </dd>
538 </dl></div>
539 </li>
540 <li>
541 <p>
542 Related to the size of the buffer
543 </p>
547 </dt>
548 <dd>
549 <p>
550 Determine the amount of allocated but unused memory.
551 </p>
552 </dd>
555 </dt>
556 <dd>
557 <p>
558 Ensure that at least this amount of unused memory is available after
560 and want to avoid repetitive automatic resizing of the underlying buffer.
561 This is never a needed operation, but can be critical for performance in
562 some cases.
563 </p>
564 </dd>
567 </dt>
568 <dd>
569 <p>
573 just meant as a <em>please fix invariants from this strbuf I just messed
574 with</em>.
575 </p>
576 </dd>
579 </dt>
580 <dd>
581 <p>
582 Empty the buffer by setting the size of it to zero.
583 </p>
584 </dd>
585 </dl></div>
586 </li>
587 <li>
588 <p>
589 Related to the contents of the buffer
590 </p>
594 </dt>
595 <dd>
596 <p>
597 Strip whitespace from the end of a string.
598 </p>
599 </dd>
602 </dt>
603 <dd>
604 <p>
605 Compare two buffers. Returns an integer less than, equal to, or greater
606 than zero if the first buffer is found, respectively, to be less than,
607 to match, or be greater than the second buffer.
608 </p>
609 </dd>
610 </dl></div>
611 </li>
612 <li>
613 <p>
614 Adding data to the buffer
615 </p>
616 </li>
617 </ul></div>
619 <table><tr>
622 </td>
624 If they fail for some reason other than memory shortage and the buffer hadn’t
626 then they will free() it.</td>
627 </tr></table>
628 </div>
632 </dt>
633 <dd>
634 <p>
635 Add a single character to the buffer.
636 </p>
637 </dd>
640 </dt>
641 <dd>
642 <p>
643 Insert data to the given position of the buffer. The remaining contents
644 will be shifted, not overwritten.
645 </p>
646 </dd>
649 </dt>
650 <dd>
651 <p>
652 Remove given amount of data from a given position of the buffer.
653 </p>
654 </dd>
657 </dt>
658 <dd>
659 <p>
661 data.
662 </p>
663 </dd>
666 </dt>
667 <dd>
668 <p>
669 Add data of given length to the buffer.
670 </p>
671 </dd>
674 </dt>
675 <dd>
676 <p>
677 Add a NUL-terminated string to the buffer.
678 </p>
680 <table><tr>
683 </td>
684 <td class="content">This function will <strong>always</strong> be implemented as an inline or a macro
685 that expands to:</td>
686 </tr></table>
687 </div>
691 </div></div>
696 </div></div>
697 </dd>
700 </dt>
701 <dd>
702 <p>
703 Copy the contents of an other buffer at the end of the current one.
704 </p>
705 </dd>
708 </dt>
709 <dd>
710 <p>
711 Copy part of the buffer from a given position till a given length to the
712 end of the buffer.
713 </p>
714 </dd>
717 </dt>
718 <dd>
719 <p>
720 This function can be used to expand a format string containing
721 placeholders. To that end, it parses the string and calls the specified
722 function for every percent sign found.
723 </p>
724 <div class="paragraph"><p>The callback function is given a pointer to the character after the <tt>%</tt>
725 and a pointer to the struct strbuf. It is expected to add the expanded
726 version of the placeholder to the strbuf, e.g. to add a newline
729 over it.</p></div>
730 <div class="paragraph"><p>The format <tt>%%</tt> is automatically expanded to a single <tt>%</tt> as a quoting
732 and the callback function will not be invoked for this placeholder.</p></div>
734 verbatim to the strbuf. If the callback returned zero, meaning that the
735 placeholder is unknown, then the percent sign is copied, too.</p></div>
738 which can be used by the programmer of the callback as she sees fit.</p></div>
739 </dd>
742 </dt>
743 <dd>
744 <p>
746 struct strbuf_expand_dict_entry as context, i.e. pairs of
747 placeholder and replacement string. The array needs to be
748 terminated by an entry with placeholder set to NULL.
749 </p>
750 </dd>
753 </dt>
754 <dd>
755 <p>
756 Append the contents of one strbuf to another, quoting any
758 destination. This is useful for literal data to be fed to either
759 strbuf_expand or to the *printf family of functions.
760 </p>
761 </dd>
764 </dt>
765 <dd>
766 <p>
767 Add a formatted string to the buffer.
768 </p>
769 </dd>
772 </dt>
773 <dd>
774 <p>
775 Read a given size of data from a FILE* pointer to the buffer.
776 </p>
778 <table><tr>
781 </td>
785 same behaviour as well.</td>
786 </tr></table>
787 </div>
788 </dd>
791 </dt>
792 <dd>
793 <p>
794 Read the contents of a given file descriptor. The third argument can be
795 used to give a hint about the file size, to avoid reallocs.
796 </p>
797 </dd>
800 </dt>
801 <dd>
802 <p>
803 Read the contents of a file, specified by its path. The third argument
804 can be used to give a hint about the file size, to avoid reallocs.
805 </p>
806 </dd>
809 </dt>
810 <dd>
811 <p>
812 Read the target of a symbolic link, specified by its path. The third
813 argument can be used to give a hint about the size, to avoid reallocs.
814 </p>
815 </dd>
818 </dt>
819 <dd>
820 <p>
821 Read a line from a FILE* pointer. The second argument specifies the line
823 </p>
824 </dd>
827 </dt>
828 <dd>
829 <p>
830 Strip whitespace from a buffer. The second parameter controls if
831 comments are considered contents to be removed or not.
832 </p>
833 </dd>
836 </dt>
837 <dd>
838 <p>
839 Launch the user preferred editor to edit a file and fill the buffer
840 with the file’s contents upon the user completing their editing. The
841 third argument can be used to set the environment which the editor is
842 run in. If the buffer is NULL the editor is launched as usual but the
843 file’s contents are not read into the buffer upon completion.
844 </p>
845 </dd>
846 </dl></div>
847 </div>
851 </div>
852 </div>
853 </body>
854 </html>