Home Explore Help
Sign In
c
/
troydhan.uthash
mirror of https://github.com/troydhanson/uthash.git
2
0
Fork 0
Files Issues 0 Wiki
Browse Source

Merge branch 'master' of github.com:troydhanson/uthash

Troy D. Hanson 10 years ago
parent
90e6cce757 558fdd5479
commit
01d27678a8
4 changed files with 1723 additions and 0 deletions
Unified View Show Diff Stats
  1. 1 0
      doc/index.html
  2. 1244 0
      doc/utringbuffer.html
  3. 374 0
      doc/utringbuffer.txt
  4. 104 0
      src/utringbuffer.h

+ 1 - 0
doc/index.html
View File 

@@ -29,6 +29,7 @@
 
         <div><a href="userguide.html">uthash</a></div>
 
         <div><a href="userguide.html">uthash</a></div>
 
         <div><a href="utlist.html">utlist</a></div>
 
         <div><a href="utlist.html">utlist</a></div>
 
         <div><a href="utarray.html">utarray</a></div>
 
         <div><a href="utarray.html">utarray</a></div>
 
+        <div><a href="utringbuffer.html">utringbuffer</a></div>
 
         <div><a href="utstring.html">utstring</a></div>
 
         <div><a href="utstring.html">utstring</a></div>
 
 
 
         <h2>activity</h2>
 
         <h2>activity</h2>

+ 1244 - 0
doc/utringbuffer.html
View File 

@@ -0,0 +1,1244 @@
 
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

+    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

+<head>

+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />

+<meta name="generator" content="AsciiDoc 8.6.6" />

+<title>utringbuffer: dynamic ring-buffer macros for C</title>

+<style type="text/css">

+/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

+

+/* Default font. */

+body {

+  font-family: Georgia,serif;

+}

+

+/* Title font. */

+h1, h2, h3, h4, h5, h6,

+div.title, caption.title,

+thead, p.table.header,

+#toctitle,

+#author, #revnumber, #revdate, #revremark,

+#footer {

+  font-family: Arial,Helvetica,sans-serif;

+}

+

+body {

+  margin: 1em 5% 1em 5%;

+}

+

+a {

+  color: blue;

+  text-decoration: underline;

+}

+a:visited {

+  color: fuchsia;

+}

+

+em {

+  font-style: italic;

+  color: navy;

+}

+

+strong {

+  font-weight: bold;

+  color: #083194;

+}

+

+h1, h2, h3, h4, h5, h6 {

+  color: #527bbd;

+  margin-top: 1.2em;

+  margin-bottom: 0.5em;

+  line-height: 1.3;

+}

+

+h1, h2, h3 {

+  border-bottom: 2px solid silver;

+}

+h2 {

+  padding-top: 0.5em;

+}

+h3 {

+  float: left;

+}

+h3 + * {

+  clear: left;

+}

+h5 {

+  font-size: 1.0em;

+}

+

+div.sectionbody {

+  margin-left: 0;

+}

+

+hr {

+  border: 1px solid silver;

+}

+

+p {

+  margin-top: 0.5em;

+  margin-bottom: 0.5em;

+}

+

+ul, ol, li > p {

+  margin-top: 0;

+}

+ul > li     { color: #aaa; }

+ul > li > * { color: black; }

+

+pre {

+  padding: 0;

+  margin: 0;

+}

+

+#author {

+  color: #527bbd;

+  font-weight: bold;

+  font-size: 1.1em;

+}

+#email {

+}

+#revnumber, #revdate, #revremark {

+}

+

+#footer {

+  font-size: small;

+  border-top: 2px solid silver;

+  padding-top: 0.5em;

+  margin-top: 4.0em;

+}

+#footer-text {

+  float: left;

+  padding-bottom: 0.5em;

+}

+#footer-badges {

+  float: right;

+  padding-bottom: 0.5em;

+}

+

+#preamble {

+  margin-top: 1.5em;

+  margin-bottom: 1.5em;

+}

+div.imageblock, div.exampleblock, div.verseblock,

+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,

+div.admonitionblock {

+  margin-top: 1.0em;

+  margin-bottom: 1.5em;

+}

+div.admonitionblock {

+  margin-top: 2.0em;

+  margin-bottom: 2.0em;

+  margin-right: 10%;

+  color: #606060;

+}

+

+div.content { /* Block element content. */

+  padding: 0;

+}

+

+/* Block element titles. */

+div.title, caption.title {

+  color: #527bbd;

+  font-weight: bold;

+  text-align: left;

+  margin-top: 1.0em;

+  margin-bottom: 0.5em;

+}

+div.title + * {

+  margin-top: 0;

+}

+

+td div.title:first-child {

+  margin-top: 0.0em;

+}

+div.content div.title:first-child {

+  margin-top: 0.0em;

+}

+div.content + div.title {

+  margin-top: 0.0em;

+}

+

+div.sidebarblock > div.content {

+  background: #ffffee;

+  border: 1px solid #dddddd;

+  border-left: 4px solid #f0f0f0;

+  padding: 0.5em;

+}

+

+div.listingblock > div.content {

+  border: 1px solid #dddddd;

+  border-left: 5px solid #f0f0f0;

+  background: #f8f8f8;

+  padding: 0.5em;

+}

+

+div.quoteblock, div.verseblock {

+  padding-left: 1.0em;

+  margin-left: 1.0em;

+  margin-right: 10%;

+  border-left: 5px solid #f0f0f0;

+  color: #888;

+}

+

+div.quoteblock > div.attribution {

+  padding-top: 0.5em;

+  text-align: right;

+}

+

+div.verseblock > pre.content {

+  font-family: inherit;

+  font-size: inherit;

+}

+div.verseblock > div.attribution {

+  padding-top: 0.75em;

+  text-align: left;

+}

+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */

+div.verseblock + div.attribution {

+  text-align: left;

+}

+

+div.admonitionblock .icon {

+  vertical-align: top;

+  font-size: 1.1em;

+  font-weight: bold;

+  text-decoration: underline;

+  color: #527bbd;

+  padding-right: 0.5em;

+}

+div.admonitionblock td.content {

+  padding-left: 0.5em;

+  border-left: 3px solid #dddddd;

+}

+

+div.exampleblock > div.content {

+  border-left: 3px solid #dddddd;

+  padding-left: 0.5em;

+}

+

+div.imageblock div.content { padding-left: 0; }

+span.image img { border-style: none; }

+a.image:visited { color: white; }

+

+dl {

+  margin-top: 0.8em;

+  margin-bottom: 0.8em;

+}

+dt {

+  margin-top: 0.5em;

+  margin-bottom: 0;

+  font-style: normal;

+  color: navy;

+}

+dd > *:first-child {

+  margin-top: 0.1em;

+}

+

+ul, ol {

+    list-style-position: outside;

+}

+ol.arabic {

+  list-style-type: decimal;

+}

+ol.loweralpha {

+  list-style-type: lower-alpha;

+}

+ol.upperalpha {

+  list-style-type: upper-alpha;

+}

+ol.lowerroman {

+  list-style-type: lower-roman;

+}

+ol.upperroman {

+  list-style-type: upper-roman;

+}

+

+div.compact ul, div.compact ol,

+div.compact p, div.compact p,

+div.compact div, div.compact div {

+  margin-top: 0.1em;

+  margin-bottom: 0.1em;

+}

+

+tfoot {

+  font-weight: bold;

+}

+td > div.verse {

+  white-space: pre;

+}

+

+div.hdlist {

+  margin-top: 0.8em;

+  margin-bottom: 0.8em;

+}

+div.hdlist tr {

+  padding-bottom: 15px;

+}

+dt.hdlist1.strong, td.hdlist1.strong {

+  font-weight: bold;

+}

+td.hdlist1 {

+  vertical-align: top;

+  font-style: normal;

+  padding-right: 0.8em;

+  color: navy;

+}

+td.hdlist2 {

+  vertical-align: top;

+}

+div.hdlist.compact tr {

+  margin: 0;

+  padding-bottom: 0;

+}

+

+.comment {

+  background: yellow;

+}

+

+.footnote, .footnoteref {

+  font-size: 0.8em;

+}

+

+span.footnote, span.footnoteref {

+  vertical-align: super;

+}

+

+#footnotes {

+  margin: 20px 0 20px 0;

+  padding: 7px 0 0 0;

+}

+

+#footnotes div.footnote {

+  margin: 0 0 5px 0;

+}

+

+#footnotes hr {

+  border: none;

+  border-top: 1px solid silver;

+  height: 1px;

+  text-align: left;

+  margin-left: 0;

+  width: 20%;

+  min-width: 100px;

+}

+

+div.colist td {

+  padding-right: 0.5em;

+  padding-bottom: 0.3em;

+  vertical-align: top;

+}

+div.colist td img {

+  margin-top: 0.3em;

+}

+

+@media print {

+  #footer-badges { display: none; }

+}

+

+#toc {

+  margin-bottom: 2.5em;

+}

+

+#toctitle {

+  color: #527bbd;

+  font-size: 1.1em;

+  font-weight: bold;

+  margin-top: 1.0em;

+  margin-bottom: 0.1em;

+}

+

+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {

+  margin-top: 0;

+  margin-bottom: 0;

+}

+div.toclevel2 {

+  margin-left: 2em;

+  font-size: 0.9em;

+}

+div.toclevel3 {

+  margin-left: 4em;

+  font-size: 0.9em;

+}

+div.toclevel4 {

+  margin-left: 6em;

+  font-size: 0.9em;

+}

+

+span.aqua { color: aqua; }

+span.black { color: black; }

+span.blue { color: blue; }

+span.fuchsia { color: fuchsia; }

+span.gray { color: gray; }

+span.green { color: green; }

+span.lime { color: lime; }

+span.maroon { color: maroon; }

+span.navy { color: navy; }

+span.olive { color: olive; }

+span.purple { color: purple; }

+span.red { color: red; }

+span.silver { color: silver; }

+span.teal { color: teal; }

+span.white { color: white; }

+span.yellow { color: yellow; }

+

+span.aqua-background { background: aqua; }

+span.black-background { background: black; }

+span.blue-background { background: blue; }

+span.fuchsia-background { background: fuchsia; }

+span.gray-background { background: gray; }

+span.green-background { background: green; }

+span.lime-background { background: lime; }

+span.maroon-background { background: maroon; }

+span.navy-background { background: navy; }

+span.olive-background { background: olive; }

+span.purple-background { background: purple; }

+span.red-background { background: red; }

+span.silver-background { background: silver; }

+span.teal-background { background: teal; }

+span.white-background { background: white; }

+span.yellow-background { background: yellow; }

+

+span.big { font-size: 2em; }

+span.small { font-size: 0.6em; }

+

+span.underline { text-decoration: underline; }

+span.overline { text-decoration: overline; }

+span.line-through { text-decoration: line-through; }

+

+

+/*

+ * xhtml11 specific

+ *

+ * */

+

+tt {

+  font-family: monospace;

+  font-size: inherit;

+  color: navy;

+}

+

+div.tableblock {

+  margin-top: 1.0em;

+  margin-bottom: 1.5em;

+}

+div.tableblock > table {

+  border: 3px solid #527bbd;

+}

+thead, p.table.header {

+  font-weight: bold;

+  color: #527bbd;

+}

+p.table {

+  margin-top: 0;

+}

+/* Because the table frame attribute is overriden by CSS in most browsers. */

+div.tableblock > table[frame="void"] {

+  border-style: none;

+}

+div.tableblock > table[frame="hsides"] {

+  border-left-style: none;

+  border-right-style: none;

+}

+div.tableblock > table[frame="vsides"] {

+  border-top-style: none;

+  border-bottom-style: none;

+}

+

+

+/*

+ * html5 specific

+ *

+ * */

+

+.monospaced {

+  font-family: monospace;

+  font-size: inherit;

+  color: navy;

+}

+

+table.tableblock {

+  margin-top: 1.0em;

+  margin-bottom: 1.5em;

+}

+thead, p.tableblock.header {

+  font-weight: bold;

+  color: #527bbd;

+}

+p.tableblock {

+  margin-top: 0;

+}

+table.tableblock {

+  border-width: 3px;

+  border-spacing: 0px;

+  border-style: solid;

+  border-color: #527bbd;

+  border-collapse: collapse;

+}

+th.tableblock, td.tableblock {

+  border-width: 1px;

+  padding: 4px;

+  border-style: solid;

+  border-color: #527bbd;

+}

+

+table.tableblock.frame-topbot {

+  border-left-style: hidden;

+  border-right-style: hidden;

+}

+table.tableblock.frame-sides {

+  border-top-style: hidden;

+  border-bottom-style: hidden;

+}

+table.tableblock.frame-none {

+  border-style: hidden;

+}

+

+th.tableblock.halign-left, td.tableblock.halign-left {

+  text-align: left;

+}

+th.tableblock.halign-center, td.tableblock.halign-center {

+  text-align: center;

+}

+th.tableblock.halign-right, td.tableblock.halign-right {

+  text-align: right;

+}

+

+th.tableblock.valign-top, td.tableblock.valign-top {

+  vertical-align: top;

+}

+th.tableblock.valign-middle, td.tableblock.valign-middle {

+  vertical-align: middle;

+}

+th.tableblock.valign-bottom, td.tableblock.valign-bottom {

+  vertical-align: bottom;

+}

+

+

+/*

+ * manpage specific

+ *

+ * */

+

+body.manpage h1 {

+  padding-top: 0.5em;

+  padding-bottom: 0.5em;

+  border-top: 2px solid silver;

+  border-bottom: 2px solid silver;

+}

+body.manpage h2 {

+  border-style: none;

+}

+body.manpage div.sectionbody {

+  margin-left: 3em;

+}

+

+@media print {

+  body.manpage div#toc { display: none; }

+}

+@media screen {

+  body {

+    max-width: 50em; /* approximately 80 characters wide */

+    margin-left: 16em;

+  }

+

+  #toc {

+    position: fixed;

+    top: 0;

+    left: 0;

+    bottom: 0;

+    width: 13em;

+    padding: 0.5em;

+    padding-bottom: 1.5em;

+    margin: 0;

+    overflow: auto;

+    border-right: 3px solid #f8f8f8;

+    background-color: white;

+  }

+

+  #toc .toclevel1 {

+    margin-top: 0.5em;

+  }

+

+  #toc .toclevel2 {

+    margin-top: 0.25em;

+    display: list-item;

+    color: #aaaaaa;

+  }

+

+  #toctitle {

+    margin-top: 0.5em;

+  }

+}

+</style>

+<script type="text/javascript">

+/*<![CDATA[*/

+var asciidoc = {  // Namespace.

+

+/////////////////////////////////////////////////////////////////////

+// Table Of Contents generator

+/////////////////////////////////////////////////////////////////////

+

+/* Author: Mihai Bazon, September 2002

+ * http://students.infoiasi.ro/~mishoo

+ *

+ * Table Of Content generator

+ * Version: 0.4

+ *

+ * Feel free to use this script under the terms of the GNU General Public

+ * License, as long as you do not remove or alter this notice.

+ */

+

+ /* modified by Troy D. Hanson, September 2006. License: GPL */

+ /* modified by Stuart Rackham, 2006, 2009. License: GPL */

+

+// toclevels = 1..4.

+toc: function (toclevels) {

+

+  function getText(el) {

+    var text = "";

+    for (var i = el.firstChild; i != null; i = i.nextSibling) {

+      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.

+        text += i.data;

+      else if (i.firstChild != null)

+        text += getText(i);

+    }

+    return text;

+  }

+

+  function TocEntry(el, text, toclevel) {

+    this.element = el;

+    this.text = text;

+    this.toclevel = toclevel;

+  }

+

+  function tocEntries(el, toclevels) {

+    var result = new Array;

+    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');

+    // Function that scans the DOM tree for header elements (the DOM2

+    // nodeIterator API would be a better technique but not supported by all

+    // browsers).

+    var iterate = function (el) {

+      for (var i = el.firstChild; i != null; i = i.nextSibling) {

+        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {

+          var mo = re.exec(i.tagName);

+          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {

+            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);

+          }

+          iterate(i);

+        }

+      }

+    }

+    iterate(el);

+    return result;

+  }

+

+  var toc = document.getElementById("toc");

+  if (!toc) {

+    return;

+  }

+

+  // Delete existing TOC entries in case we're reloading the TOC.

+  var tocEntriesToRemove = [];

+  var i;

+  for (i = 0; i < toc.childNodes.length; i++) {

+    var entry = toc.childNodes[i];

+    if (entry.nodeName == 'div'

+     && entry.getAttribute("class")

+     && entry.getAttribute("class").match(/^toclevel/))

+      tocEntriesToRemove.push(entry);

+  }

+  for (i = 0; i < tocEntriesToRemove.length; i++) {

+    toc.removeChild(tocEntriesToRemove[i]);

+  }

+

+  // Rebuild TOC entries.

+  var entries = tocEntries(document.getElementById("content"), toclevels);

+  for (var i = 0; i < entries.length; ++i) {

+    var entry = entries[i];

+    if (entry.element.id == "")

+      entry.element.id = "_toc_" + i;

+    var a = document.createElement("a");

+    a.href = "#" + entry.element.id;

+    a.appendChild(document.createTextNode(entry.text));

+    var div = document.createElement("div");

+    div.appendChild(a);

+    div.className = "toclevel" + entry.toclevel;

+    toc.appendChild(div);

+  }

+  if (entries.length == 0)

+    toc.parentNode.removeChild(toc);

+},

+

+

+/////////////////////////////////////////////////////////////////////

+// Footnotes generator

+/////////////////////////////////////////////////////////////////////

+

+/* Based on footnote generation code from:

+ * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html

+ */

+

+footnotes: function () {

+  // Delete existing footnote entries in case we're reloading the footnodes.

+  var i;

+  var noteholder = document.getElementById("footnotes");

+  if (!noteholder) {

+    return;

+  }

+  var entriesToRemove = [];

+  for (i = 0; i < noteholder.childNodes.length; i++) {

+    var entry = noteholder.childNodes[i];

+    if (entry.nodeName == 'div' && entry.getAttribute("class") == "footnote")

+      entriesToRemove.push(entry);

+  }

+  for (i = 0; i < entriesToRemove.length; i++) {

+    noteholder.removeChild(entriesToRemove[i]);

+  }

+

+  // Rebuild footnote entries.

+  var cont = document.getElementById("content");

+  var spans = cont.getElementsByTagName("span");

+  var refs = {};

+  var n = 0;

+  for (i=0; i<spans.length; i++) {

+    if (spans[i].className == "footnote") {

+      n++;

+      var note = spans[i].getAttribute("data-note");

+      if (!note) {

+        // Use [\s\S] in place of . so multi-line matches work.

+        // Because JavaScript has no s (dotall) regex flag.

+        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];

+        spans[i].innerHTML =

+          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +

+          "' title='View footnote' class='footnote'>" + n + "</a>]";

+        spans[i].setAttribute("data-note", note);

+      }

+      noteholder.innerHTML +=

+        "<div class='footnote' id='_footnote_" + n + "'>" +

+        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +

+        n + "</a>. " + note + "</div>";

+      var id =spans[i].getAttribute("id");

+      if (id != null) refs["#"+id] = n;

+    }

+  }

+  if (n == 0)

+    noteholder.parentNode.removeChild(noteholder);

+  else {

+    // Process footnoterefs.

+    for (i=0; i<spans.length; i++) {

+      if (spans[i].className == "footnoteref") {

+        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");

+        href = href.match(/#.*/)[0];  // Because IE return full URL.

+        n = refs[href];

+        spans[i].innerHTML =

+          "[<a href='#_footnote_" + n +

+          "' title='View footnote' class='footnote'>" + n + "</a>]";

+      }

+    }

+  }

+},

+

+install: function(toclevels) {

+  var timerId;

+

+  function reinstall() {

+    asciidoc.footnotes();

+    if (toclevels) {

+      asciidoc.toc(toclevels);

+    }

+  }

+

+  function reinstallAndRemoveTimer() {

+    clearInterval(timerId);

+    reinstall();

+  }

+

+  timerId = setInterval(reinstall, 500);

+  if (document.addEventListener)

+    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);

+  else

+    window.onload = reinstallAndRemoveTimer;

+}

+

+}

+asciidoc.install(2);

+/*]]>*/

+</script>

+</head>

+<body class="article">

+<div id="header">

+<h1>utringbuffer: dynamic ring-buffer macros for C</h1>

+<span id="author">Arthur O'Dwyer</span><br />

+<span id="email"><tt>&lt;<a href="mailto:[email protected]">[email protected]</a>&gt;</tt></span><br />

+<span id="revnumber">version 0.1,</span>

+<span id="revdate">June 2015</span>

+<div id="toc">
 
+  <div id="toctitle">Table of Contents</div>
 
+  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
 
+</div>

+</div>

+<div id="content">

+<div id="preamble">

+<div class="sectionbody">

+<div class="paragraph"><p>Here&#8217;s a link back to the <a href="https://github.com/troydhanson/uthash">GitHub project page</a>.</p></div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="_introduction">Introduction</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>The functions in <tt>utringbuffer.h</tt> are based on the general-purpose array macros

+provided in <tt>utarray.h</tt>, so before reading this page you should read

+<a href="utarray.html">that page</a> first.</p></div>

+<div class="paragraph"><p>To use these macros in your own C program, copy both <tt>utarray.h</tt> and <tt>utringbuffer.h</tt>

+into your source directory and use <tt>utringbuffer.h</tt> in your program.</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><tt>#include "utringbuffer.h"</tt></pre>

+</div></div>

+<div class="paragraph"><p>The provided <a href="#operations">operations</a> are based loosely on the C++ STL vector methods.

+The ring-buffer data type supports construction (with a specified capacity),

+destruction, iteration, and push, but not pop; once the ring-buffer reaches full

+capacity, pushing a new element automatically pops and destroys the oldest element.

+The elements contained in the ring-buffer can be any simple datatype or structure.</p></div>

+<div class="paragraph"><p>Internally the ring-buffer contains a pre-allocated memory region into which the

+elements are copied, starting at position 0. When the ring-buffer reaches full

+capacity, the next element to be pushed is pushed at position 0, overwriting the

+oldest element, and the internal index representing the "start" of the ring-buffer

+is incremented. A ring-buffer, once full, can never become un-full.</p></div>

+<div class="sect2">

+<h3 id="_download">Download</h3>

+<div class="paragraph"><p>To download the <tt>utringbuffer.h</tt> header file,

+follow the links on <a href="https://github.com/troydhanson/uthash">https://github.com/troydhanson/uthash</a> to clone uthash or get a zip file,

+then look in the src/ sub-directory.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_bsd_licensed">BSD licensed</h3>

+<div class="paragraph"><p>This software is made available under the

+<a href="license.html">revised BSD license</a>.

+It is free and open source.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_platforms">Platforms</h3>

+<div class="paragraph"><p>The <em>utringbuffer</em> macros have been tested on:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+Linux,

+</p>

+</li>

+<li>

+<p>

+Mac OS X,

+</p>

+</li>

+<li>

+<p>

+Windows, using Visual Studio 2008 and Visual Studio 2010

+</p>

+</li>

+</ul></div>

+</div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="_usage">Usage</h2>

+<div class="sectionbody">

+<div class="sect2">

+<h3 id="_declaration">Declaration</h3>

+<div class="paragraph"><p>The ring-buffer itself has the data type <tt>UT_ringbuffer</tt>, regardless of the type of

+elements to be stored in it. It is declared like,</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><tt>UT_ringbuffer *history;</tt></pre>

+</div></div>

+</div>

+<div class="sect2">

+<h3 id="_new_and_free">New and free</h3>

+<div class="paragraph"><p>The next step is to create the ring-buffer using <tt>utringbuffer_new</tt>. Later when you&#8217;re

+done with the ring-buffer, <tt>utringbuffer_free</tt> will free it and all its elements.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_push_etc">Push, etc</h3>

+<div class="paragraph"><p>The central features of the ring-buffer involve putting elements into it

+and iterating over them. There are several <a href="#operations">operations</a>

+that deal with either single elements or ranges of elements at a

+time. In the examples below we will use only the push operation to insert

+elements.</p></div>

+</div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="_elements">Elements</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>Support for dynamic arrays of integers or strings is especially easy. These are

+best shown by example:</p></div>

+<div class="sect2">

+<h3 id="_integers">Integers</h3>

+<div class="paragraph"><p>This example makes a ring-buffer of integers, pushes 0-9 into it, then prints it

+two different ways. Lastly it frees it.</p></div>

+<div class="listingblock">

+<div class="title">Integer elements</div>

+<div class="content">

+<pre><tt>#include &lt;stdio.h&gt;

+#include "utringbuffer.h"

+

+int main() {

+  UT_ringbuffer *history;

+  int i, *p;

+

+  utringbuffer_new(history, 7, &amp;ut_int_icd);

+  for(i=0; i &lt; 10; i++) utringbuffer_push_back(history, &amp;i);

+

+  for (p = (int*)utringbuffer_front(history);

+       p != NULL;

+       p = (int*)utringbuffer_next(history, p)) {

+    printf("%d\n", *p);  /* prints "3 4 5 6 7 8 9" */

+  }

+

+  for (i=0; i &lt; utringbuffer_len(history); i++) {

+    p = utringbuffer_eltptr(history, i);

+    printf("%d\n", *p);  /* prints "3 4 5 6 7 8 9" */

+  }

+

+  utringbuffer_free(history);

+

+  return 0;

+}</tt></pre>

+</div></div>

+<div class="paragraph"><p>The second argument to <tt>utringbuffer_push_back</tt> is always a <em>pointer</em> to the type

+(so a literal cannot be used). So for integers, it is an <tt>int*</tt>.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_strings">Strings</h3>

+<div class="paragraph"><p>In this example we make a ring-buffer of strings, push two strings into it, print

+it and free it.</p></div>

+<div class="listingblock">

+<div class="title">String elements</div>

+<div class="content">

+<pre><tt>#include &lt;stdio.h&gt;

+#include "utringbuffer.h"

+

+int main() {

+  UT_ringbuffer *strs;

+  char *s, **p;

+

+  utringbuffer_new(strs, 7, &amp;ut_str_icd);

+

+  s = "hello"; utringbuffer_push_back(strs, &amp;s);

+  s = "world"; utringbuffer_push_back(strs, &amp;s);

+  p = NULL;

+  while ( (p=(char**)utringbuffer_next(strs,p))) {

+    printf("%s\n",*p);

+  }

+

+  utringbuffer_free(strs);

+

+  return 0;

+}</tt></pre>

+</div></div>

+<div class="paragraph"><p>In this example, since the element is a <tt>char*</tt>, we pass a pointer to it

+(<tt>char**</tt>) as the second argument to <tt>utringbuffer_push_back</tt>. Note that "push" makes

+a copy of the source string and pushes that copy into the array.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_about_ut_icd">About UT_icd</h3>

+<div class="paragraph"><p>Arrays can be made of any type of element, not just integers and strings. The

+elements can be basic types or structures. Unless you&#8217;re dealing with integers

+and strings (which use pre-defined <tt>ut_int_icd</tt> and <tt>ut_str_icd</tt>), you&#8217;ll need

+to define a <tt>UT_icd</tt> helper structure. This structure contains everything that

+utringbuffer (or utarray) needs to initialize, copy or destruct elements.</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><tt>typedef struct {

+    size_t sz;

+    init_f *init;

+    ctor_f *copy;

+    dtor_f *dtor;

+} UT_icd;</tt></pre>

+</div></div>

+<div class="paragraph"><p>The three function pointers <tt>init</tt>, <tt>copy</tt>, and <tt>dtor</tt> have these prototypes:</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><tt>typedef void (ctor_f)(void *dst, const void *src);

+typedef void (dtor_f)(void *elt);

+typedef void (init_f)(void *elt);</tt></pre>

+</div></div>

+<div class="paragraph"><p>The <tt>sz</tt> is just the size of the element being stored in the array.</p></div>

+<div class="paragraph"><p>The <tt>init</tt> function is used by utarray but is never used by utringbuffer;

+you may safely set it to any value you want.</p></div>

+<div class="paragraph"><p>The <tt>copy</tt> function is used whenever an element is copied into the buffer.

+It is invoked during <tt>utringbuffer_push_back</tt>.

+If <tt>copy</tt> is <tt>NULL</tt>, it defaults to a bitwise copy using memcpy.</p></div>

+<div class="paragraph"><p>The <tt>dtor</tt> function is used to clean up an element that is being removed from

+the buffer. It may be invoked due to <tt>utringbuffer_push_back</tt> (on the oldest

+element in the buffer), <tt>utringbuffer_clear</tt>, <tt>utringbuffer_done</tt>, or

+<tt>utringbuffer_free</tt>.

+If the elements need no cleanup upon destruction, <tt>dtor</tt> may be <tt>NULL</tt>.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_scalar_types">Scalar types</h3>

+<div class="paragraph"><p>The next example uses <tt>UT_icd</tt> with all its defaults to make a ring-buffer of

+<tt>long</tt> elements. This example pushes two longs into a buffer of capacity 1,

+prints the contents of the buffer (which is to say, the most recent value

+pushed), and then frees the buffer.</p></div>

+<div class="listingblock">

+<div class="title">long elements</div>

+<div class="content">

+<pre><tt>#include &lt;stdio.h&gt;

+#include "utringbuffer.h"

+

+UT_icd long_icd = {sizeof(long), NULL, NULL, NULL };

+

+int main() {

+  UT_ringbuffer *nums;

+  long l, *p;

+  utringbuffer_new(nums, 1, &amp;long_icd);

+

+  l=1; utringbuffer_push_back(nums, &amp;l);

+  l=2; utringbuffer_push_back(nums, &amp;l);

+

+  p=NULL;

+  while((p = (long*)utringbuffer_next(nums,p))) printf("%ld\n", *p);

+

+  utringbuffer_free(nums);

+  return 0;

+}</tt></pre>

+</div></div>

+</div>

+<div class="sect2">

+<h3 id="_structures">Structures</h3>

+<div class="paragraph"><p>Structures can be used as utringbuffer elements. If the structure requires no

+special effort to initialize, copy or destruct, we can use <tt>UT_icd</tt> with all

+its defaults. This example shows a structure that consists of two integers. Here

+we push two values, print them and free the buffer.</p></div>

+<div class="listingblock">

+<div class="title">Structure (simple)</div>

+<div class="content">

+<pre><tt>#include &lt;stdio.h&gt;

+#include "utringbuffer.h"

+

+typedef struct {

+    int a;

+    int b;

+} intpair_t;

+

+UT_icd intpair_icd = {sizeof(intpair_t), NULL, NULL, NULL};

+

+int main() {

+

+  UT_ringbuffer *pairs;

+  intpair_t ip, *p;

+  utringbuffer_new(pairs, 7, &amp;intpair_icd);

+

+  ip.a=1;  ip.b=2;  utringbuffer_push_back(pairs, &amp;ip);

+  ip.a=10; ip.b=20; utringbuffer_push_back(pairs, &amp;ip);

+

+  for(p=(intpair_t*)utringbuffer_front(pairs);

+      p!=NULL;

+      p=(intpair_t*)utringbuffer_next(pairs,p)) {

+    printf("%d %d\n", p-&gt;a, p-&gt;b);

+  }

+

+  utringbuffer_free(pairs);

+  return 0;

+}</tt></pre>

+</div></div>

+<div class="paragraph"><p>The real utility of <tt>UT_icd</tt> is apparent when the elements stored in the

+ring-buffer are structures that require special work to initialize, copy or

+destruct.</p></div>

+<div class="paragraph"><p>For example, when a structure contains pointers to related memory areas that

+need to be copied when the structure is copied (and freed when the structure is

+freed), we can use custom <tt>init</tt>, <tt>copy</tt>, and <tt>dtor</tt> members in the <tt>UT_icd</tt>.</p></div>

+<div class="paragraph"><p>Here we take an example of a structure that contains an integer and a string.

+When this element is copied (such as when an element is pushed),

+we want to "deep copy" the <tt>s</tt> pointer (so the original element and the new

+element point to their own copies of <tt>s</tt>). When an element is destructed, we

+want to "deep free" its copy of <tt>s</tt>. Lastly, this example is written to work

+even if <tt>s</tt> has the value <tt>NULL</tt>.</p></div>

+<div class="listingblock">

+<div class="title">Structure (complex)</div>

+<div class="content">

+<pre><tt>#include &lt;stdio.h&gt;

+#include &lt;stdlib.h&gt;

+#include "utringbuffer.h"

+

+typedef struct {

+    int a;

+    char *s;

+} intchar_t;

+

+void intchar_copy(void *_dst, const void *_src) {

+  intchar_t *dst = (intchar_t*)_dst, *src = (intchar_t*)_src;

+  dst-&gt;a = src-&gt;a;

+  dst-&gt;s = src-&gt;s ? strdup(src-&gt;s) : NULL;

+}

+

+void intchar_dtor(void *_elt) {

+  intchar_t *elt = (intchar_t*)_elt;

+  free(elt-&gt;s);

+}

+

+UT_icd intchar_icd = {sizeof(intchar_t), NULL, intchar_copy, intchar_dtor};

+

+int main() {

+  UT_ringbuffer *intchars;

+  intchar_t ic, *p;

+  utringbuffer_new(intchars, 2, &amp;intchar_icd);

+

+  ic.a=1; ic.s="hello"; utringbuffer_push_back(intchars, &amp;ic);

+  ic.a=2; ic.s="world"; utringbuffer_push_back(intchars, &amp;ic);

+  ic.a=3; ic.s="peace"; utringbuffer_push_back(intchars, &amp;ic);

+

+  p=NULL;

+  while( (p=(intchar_t*)utringbuffer_next(intchars,p))) {

+    printf("%d %s\n", p-&gt;a, (p-&gt;s ? p-&gt;s : "null"));

+    /* prints "2 world 3 peace" */

+  }

+

+  utringbuffer_free(intchars);

+  return 0;

+}</tt></pre>

+</div></div>

+</div>

+</div>

+</div>

+<div class="sect1">

+<h2 id="operations">Reference</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>This table lists all the utringbuffer operations. These are loosely based on the C++

+vector class.</p></div>

+<div class="sect2">

+<h3 id="_operations">Operations</h3>

+<div class="tableblock">

+<table rules="none"

+width="100%"

+frame="border"

+cellspacing="0" cellpadding="4">

+<col width="55%" />

+<col width="44%" />

+<tbody>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_new(UT_ringbuffer *a, int n, UT_icd *icd)</tt></p></td>

+<td align="left" valign="top"><p class="table">allocate a new ringbuffer</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_free(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">free an allocated ringbuffer</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_init(UT_ringbuffer *a, int n, UT_icd *icd)</tt></p></td>

+<td align="left" valign="top"><p class="table">init a ringbuffer (non-alloc)</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_done(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">dispose of a ringbuffer (non-alloc)</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_clear(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">clear all elements from a, making it empty</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_push_back(UT_ringbuffer *a, element *p)</tt></p></td>

+<td align="left" valign="top"><p class="table">push element p onto a</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_len(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">get length of a</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_empty(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">get whether a is empty</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_full(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">get whether a is full</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_eltptr(UT_ringbuffer *a, int j)</tt></p></td>

+<td align="left" valign="top"><p class="table">get pointer of element from index</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_eltidx(UT_ringbuffer *a, element *e)</tt></p></td>

+<td align="left" valign="top"><p class="table">get index of element from pointer</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_front(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">get oldest element of a</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_next(UT_ringbuffer *a, element *e)</tt></p></td>

+<td align="left" valign="top"><p class="table">get element of a following e (front if e is NULL)</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_prev(UT_ringbuffer *a, element *e)</tt></p></td>

+<td align="left" valign="top"><p class="table">get element of a before e (back if e is NULL)</p></td>

+</tr>

+<tr>

+<td align="left" valign="top"><p class="table"><tt>utringbuffer_back(UT_ringbuffer *a)</tt></p></td>

+<td align="left" valign="top"><p class="table">get newest element of a</p></td>

+</tr>

+</tbody>

+</table>

+</div>

+</div>

+<div class="sect2">

+<h3 id="_notes">Notes</h3>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+<tt>utringbuffer_new</tt> and <tt>utringbuffer_free</tt> are used to allocate a new ring-buffer

+   and to free it,

+   while <tt>utringbuffer_init</tt> and <tt>utringbuffer_done</tt> can be used if the UT_ringbuffer

+   is already allocated and just needs to be initialized or have its internal resources

+   freed.

+</p>

+</li>

+<li>

+<p>

+Both <tt>utringbuffer_new</tt> and <tt>utringbuffer_init</tt> take a second parameter <tt>n</tt> indicating

+   the capacity of the ring-buffer, that is, the size at which the ring-buffer is considered

+   "full" and begins to overwrite old elements with newly pushed ones.

+</p>

+</li>

+<li>

+<p>

+Once a ring-buffer has become full, it will never again become un-full except by

+   means of <tt>utringbuffer_clear</tt>. There is no way to "pop" a single old item from the

+   front of the ring-buffer. You can simulate this ability by maintaining a separate

+   integer count of the number of "logically popped elements", and starting your iteration

+   with <tt>utringbuffer_eltptr(a, popped_count)</tt> instead of with <tt>utringbuffer_front(a)</tt>.

+</p>

+</li>

+<li>

+<p>

+Pointers to elements (obtained using <tt>utringbuffer_eltptr</tt>, <tt>utringbuffer_front</tt>,

+   <tt>utringbuffer_next</tt>, etc.) are not generally invalidated by <tt>utringbuffer_push_back</tt>,

+   because utringbuffer does not perform reallocation; however, a pointer to the oldest

+   element may suddenly turn into a pointer to the <em>newest</em> element if

+   <tt>utringbuffer_push_back</tt> is called while the buffer is full.

+</p>

+</li>

+<li>

+<p>

+The elements of a ring-buffer are stored in contiguous memory, but once the ring-buffer

+   has become full, it is no longer true that the elements are contiguously in order from

+   oldest to newest; i.e., <tt>(element *)utringbuffer_front(a) + utringbuffer_len(a)-1</tt> is

+   not generally equal to <tt>(element *)utringbuffer_back(a)</tt>.

+</p>

+</li>

+</ol></div>

+</div>

+</div>

+</div>

+</div>

+<div id="footnotes"><hr /></div>

+<div id="footer">

+<div id="footer-text">

+Version 0.1<br />

+Last updated 2015-06-26 05:55:39 UTC

+</div>

+</div>

+</body>

+</html>

+ 374 - 0
doc/utringbuffer.txt
View File 

@@ -0,0 +1,374 @@
 
+utringbuffer: dynamic ring-buffer macros for C 
+==============================================
 
+Arthur O'Dwyer <[email protected]>
 
+v0.1, June 2015
 
+
 
+Here's a link back to the https://github.com/troydhanson/uthash[GitHub project page].
 
+
 
+Introduction
 
+------------
 
+The functions in `utringbuffer.h` are based on the general-purpose array macros
 
+provided in `utarray.h`, so before reading this page you should read
 
+link:utarray.html[that page] first.
 
+
 
+To use these macros in your own C program, copy both `utarray.h` and `utringbuffer.h`
 
+into your source directory and use `utringbuffer.h` in your program.
 
+
 
+  #include "utringbuffer.h"
 
+
 
+The provided <<operations,operations>> are based loosely on the C++ STL vector methods.
 
+The ring-buffer data type supports construction (with a specified capacity),
 
+destruction, iteration, and push, but not pop; once the ring-buffer reaches full
 
+capacity, pushing a new element automatically pops and destroys the oldest element.
 
+The elements contained in the ring-buffer can be any simple datatype or structure.
 
+
 
+Internally the ring-buffer contains a pre-allocated memory region into which the
 
+elements are copied, starting at position 0. When the ring-buffer reaches full
 
+capacity, the next element to be pushed is pushed at position 0, overwriting the
 
+oldest element, and the internal index representing the "start" of the ring-buffer
 
+is incremented. A ring-buffer, once full, can never become un-full.
 
+
 
+
 
+Download
 
+~~~~~~~~
 
+To download the `utringbuffer.h` header file, 
+follow the links on https://github.com/troydhanson/uthash to clone uthash or get a zip file, 
+then look in the src/ sub-directory.
 
+
 
+BSD licensed
 
+~~~~~~~~~~~~
 
+This software is made available under the 
+link:license.html[revised BSD license]. 
+It is free and open source. 
+
 
+Platforms
 
+~~~~~~~~~
 
+The 'utringbuffer' macros have been tested on:
 
+
 
+ * Linux, 
+ * Mac OS X, 
+ * Windows, using Visual Studio 2008 and Visual Studio 2010
 
+
 
+Usage 
+-----
 
+
 
+Declaration
 
+~~~~~~~~~~~
 
+
 
+The ring-buffer itself has the data type `UT_ringbuffer`, regardless of the type of
 
+elements to be stored in it. It is declared like,
 
+
 
+  UT_ringbuffer *history;
 
+
 
+New and free
 
+~~~~~~~~~~~~
 
+The next step is to create the ring-buffer using `utringbuffer_new`. Later when you're
 
+done with the ring-buffer, `utringbuffer_free` will free it and all its elements. 
+
 
+Push, etc
 
+~~~~~~~~~
 
+The central features of the ring-buffer involve putting elements into it
 
+and iterating over them. There are several <<operations,operations>>
 
+that deal with either single elements or ranges of elements at a
 
+time. In the examples below we will use only the push operation to insert
 
+elements. 
+
 
+Elements
 
+--------
 
+
 
+Support for dynamic arrays of integers or strings is especially easy. These are
 
+best shown by example:
 
+
 
+Integers
 
+~~~~~~~~
 
+This example makes a ring-buffer of integers, pushes 0-9 into it, then prints it
 
+two different ways. Lastly it frees it.
 
+
 
+.Integer elements
 
+-------------------------------------------------------------------------------
 
+#include <stdio.h>
 
+#include "utringbuffer.h"
 
+
 
+int main() {
 
+  UT_ringbuffer *history;
 
+  int i, *p;
 
+
 
+  utringbuffer_new(history, 7, &ut_int_icd);
 
+  for(i=0; i < 10; i++) utringbuffer_push_back(history, &i);
 
+
 
+  for (p = (int*)utringbuffer_front(history);
 
+       p != NULL;
 
+       p = (int*)utringbuffer_next(history, p)) {
 
+    printf("%d\n", *p);  /* prints "3 4 5 6 7 8 9" */
 
+  }
 
+
 
+  for (i=0; i < utringbuffer_len(history); i++) {
 
+    p = utringbuffer_eltptr(history, i);
 
+    printf("%d\n", *p);  /* prints "3 4 5 6 7 8 9" */
 
+  }
 
+
 
+  utringbuffer_free(history);
 
+
 
+  return 0;
 
+}
 
+-------------------------------------------------------------------------------
 
+
 
+The second argument to `utringbuffer_push_back` is always a 'pointer' to the type
 
+(so a literal cannot be used). So for integers, it is an `int*`.
 
+
 
+Strings
 
+~~~~~~~
 
+In this example we make a ring-buffer of strings, push two strings into it, print
 
+it and free it.
 
+
 
+.String elements
 
+-------------------------------------------------------------------------------
 
+#include <stdio.h>
 
+#include "utringbuffer.h"
 
+
 
+int main() {
 
+  UT_ringbuffer *strs;
 
+  char *s, **p;
 
+
 
+  utringbuffer_new(strs, 7, &ut_str_icd);
 
+
 
+  s = "hello"; utringbuffer_push_back(strs, &s);
 
+  s = "world"; utringbuffer_push_back(strs, &s);
 
+  p = NULL;
 
+  while ( (p=(char**)utringbuffer_next(strs,p))) {
 
+    printf("%s\n",*p);
 
+  }
 
+
 
+  utringbuffer_free(strs);
 
+
 
+  return 0;
 
+}
 
+-------------------------------------------------------------------------------
 
+
 
+In this example, since the element is a `char*`, we pass a pointer to it
 
+(`char**`) as the second argument to `utringbuffer_push_back`. Note that "push" makes
 
+a copy of the source string and pushes that copy into the array.
 
+
 
+About UT_icd
 
+~~~~~~~~~~~~
 
+
 
+Arrays can be made of any type of element, not just integers and strings. The
 
+elements can be basic types or structures. Unless you're dealing with integers
 
+and strings (which use pre-defined `ut_int_icd` and `ut_str_icd`), you'll need
 
+to define a `UT_icd` helper structure. This structure contains everything that
 
+utringbuffer (or utarray) needs to initialize, copy or destruct elements.
 
+
 
+  typedef struct {
 
+      size_t sz;
 
+      init_f *init;
 
+      ctor_f *copy;
 
+      dtor_f *dtor;
 
+  } UT_icd;
 
+
 
+The three function pointers `init`, `copy`, and `dtor` have these prototypes:
 
+
 
+  typedef void (ctor_f)(void *dst, const void *src);
 
+  typedef void (dtor_f)(void *elt);
 
+  typedef void (init_f)(void *elt);
 
+
 
+The `sz` is just the size of the element being stored in the array.
 
+
 
+The `init` function is used by utarray but is never used by utringbuffer;
 
+you may safely set it to any value you want.
 
+
 
+The `copy` function is used whenever an element is copied into the buffer.
 
+It is invoked during `utringbuffer_push_back`.
 
+If `copy` is `NULL`, it defaults to a bitwise copy using memcpy.
 
+
 
+The `dtor` function is used to clean up an element that is being removed from
 
+the buffer. It may be invoked due to `utringbuffer_push_back` (on the oldest
 
+element in the buffer), `utringbuffer_clear`, `utringbuffer_done`, or
 
+`utringbuffer_free`.
 
+If the elements need no cleanup upon destruction, `dtor` may be `NULL`.
 
+
 
+Scalar types
 
+~~~~~~~~~~~~
 
+
 
+The next example uses `UT_icd` with all its defaults to make a ring-buffer of
 
+`long` elements. This example pushes two longs into a buffer of capacity 1,
 
+prints the contents of the buffer (which is to say, the most recent value
 
+pushed), and then frees the buffer.
 
+
 
+.long elements
 
+-------------------------------------------------------------------------------
 
+#include <stdio.h>
 
+#include "utringbuffer.h"
 
+
 
+UT_icd long_icd = {sizeof(long), NULL, NULL, NULL };
 
+
 
+int main() {
 
+  UT_ringbuffer *nums;
 
+  long l, *p;
 
+  utringbuffer_new(nums, 1, &long_icd);
 
+
 
+  l=1; utringbuffer_push_back(nums, &l);
 
+  l=2; utringbuffer_push_back(nums, &l);
 
+
 
+  p=NULL;
 
+  while((p = (long*)utringbuffer_next(nums,p))) printf("%ld\n", *p);
 
+
 
+  utringbuffer_free(nums);
 
+  return 0;
 
+}
 
+-------------------------------------------------------------------------------
 
+
 
+Structures
 
+~~~~~~~~~~
 
+
 
+Structures can be used as utringbuffer elements. If the structure requires no
 
+special effort to initialize, copy or destruct, we can use `UT_icd` with all
 
+its defaults. This example shows a structure that consists of two integers. Here
 
+we push two values, print them and free the buffer.
 
+
 
+.Structure (simple)
 
+-------------------------------------------------------------------------------
 
+#include <stdio.h>
 
+#include "utringbuffer.h"
 
+
 
+typedef struct {
 
+    int a;
 
+    int b;
 
+} intpair_t;
 
+
 
+UT_icd intpair_icd = {sizeof(intpair_t), NULL, NULL, NULL};
 
+
 
+int main() {
 
+
 
+  UT_ringbuffer *pairs;
 
+  intpair_t ip, *p;
 
+  utringbuffer_new(pairs, 7, &intpair_icd);
 
+
 
+  ip.a=1;  ip.b=2;  utringbuffer_push_back(pairs, &ip);
 
+  ip.a=10; ip.b=20; utringbuffer_push_back(pairs, &ip);
 
+
 
+  for(p=(intpair_t*)utringbuffer_front(pairs);
 
+      p!=NULL;
 
+      p=(intpair_t*)utringbuffer_next(pairs,p)) {
 
+    printf("%d %d\n", p->a, p->b);
 
+  }
 
+
 
+  utringbuffer_free(pairs);
 
+  return 0;
 
+}
 
+-------------------------------------------------------------------------------
 
+
 
+The real utility of `UT_icd` is apparent when the elements stored in the
 
+ring-buffer are structures that require special work to initialize, copy or
 
+destruct. 
+
 
+For example, when a structure contains pointers to related memory areas that
 
+need to be copied when the structure is copied (and freed when the structure is
 
+freed), we can use custom `init`, `copy`, and `dtor` members in the `UT_icd`.
 
+
 
+Here we take an example of a structure that contains an integer and a string.
 
+When this element is copied (such as when an element is pushed),
 
+we want to "deep copy" the `s` pointer (so the original element and the new
 
+element point to their own copies of `s`). When an element is destructed, we
 
+want to "deep free" its copy of `s`. Lastly, this example is written to work
 
+even if `s` has the value `NULL`.
 
+
 
+.Structure (complex)
 
+-------------------------------------------------------------------------------
 
+#include <stdio.h>
 
+#include <stdlib.h>
 
+#include "utringbuffer.h"
 
+
 
+typedef struct {
 
+    int a;
 
+    char *s;
 
+} intchar_t;
 
+
 
+void intchar_copy(void *_dst, const void *_src) {
 
+  intchar_t *dst = (intchar_t*)_dst, *src = (intchar_t*)_src;
 
+  dst->a = src->a;
 
+  dst->s = src->s ? strdup(src->s) : NULL;
 
+}
 
+
 
+void intchar_dtor(void *_elt) {
 
+  intchar_t *elt = (intchar_t*)_elt;
 
+  free(elt->s);
 
+}
 
+
 
+UT_icd intchar_icd = {sizeof(intchar_t), NULL, intchar_copy, intchar_dtor};
 
+
 
+int main() {
 
+  UT_ringbuffer *intchars;
 
+  intchar_t ic, *p;
 
+  utringbuffer_new(intchars, 2, &intchar_icd);
 
+
 
+  ic.a=1; ic.s="hello"; utringbuffer_push_back(intchars, &ic);
 
+  ic.a=2; ic.s="world"; utringbuffer_push_back(intchars, &ic);
 
+  ic.a=3; ic.s="peace"; utringbuffer_push_back(intchars, &ic);
 
+
 
+  p=NULL;
 
+  while( (p=(intchar_t*)utringbuffer_next(intchars,p))) {
 
+    printf("%d %s\n", p->a, (p->s ? p->s : "null"));
 
+    /* prints "2 world 3 peace" */
 
+  }
 
+
 
+  utringbuffer_free(intchars);
 
+  return 0;
 
+}
 
+
 
+-------------------------------------------------------------------------------
 
+
 
+[[operations]]
 
+Reference
 
+---------
 
+This table lists all the utringbuffer operations. These are loosely based on the C++
 
+vector class.
 
+
 
+Operations
 
+~~~~~~~~~~
 
+
 
+[width="100%",cols="50<m,40<",grid="none",options="none"]
 
+|===============================================================================
 
+| utringbuffer_new(UT_ringbuffer *a, int n, UT_icd *icd)  | allocate a new ringbuffer 
+| utringbuffer_free(UT_ringbuffer *a)                     | free an allocated ringbuffer
 
+| utringbuffer_init(UT_ringbuffer *a, int n, UT_icd *icd) | init a ringbuffer (non-alloc)
 
+| utringbuffer_done(UT_ringbuffer *a)                     | dispose of a ringbuffer (non-alloc)
 
+| utringbuffer_clear(UT_ringbuffer *a)                    | clear all elements from a, making it empty
 
+| utringbuffer_push_back(UT_ringbuffer *a, element *p)    | push element p onto a
 
+| utringbuffer_len(UT_ringbuffer *a)                      | get length of a
 
+| utringbuffer_empty(UT_ringbuffer *a)                    | get whether a is empty
 
+| utringbuffer_full(UT_ringbuffer *a)                     | get whether a is full
 
+| utringbuffer_eltptr(UT_ringbuffer *a, int j)            | get pointer of element from index 
+| utringbuffer_eltidx(UT_ringbuffer *a, element *e)       | get index of element from pointer
 
+| utringbuffer_front(UT_ringbuffer *a)                    | get oldest element of a
 
+| utringbuffer_next(UT_ringbuffer *a, element *e)         | get element of a following e (front if e is NULL)
 
+| utringbuffer_prev(UT_ringbuffer *a, element *e)         | get element of a before e (back if e is NULL)
 
+| utringbuffer_back(UT_ringbuffer *a)                     | get newest element of a
 
+|===============================================================================
 
+
 
+Notes
 
+~~~~~
 
+
 
+1. `utringbuffer_new` and `utringbuffer_free` are used to allocate a new ring-buffer
 
+   and to free it,
 
+   while `utringbuffer_init` and `utringbuffer_done` can be used if the UT_ringbuffer
 
+   is already allocated and just needs to be initialized or have its internal resources
 
+   freed.
 
+2. Both `utringbuffer_new` and `utringbuffer_init` take a second parameter `n` indicating
 
+   the capacity of the ring-buffer, that is, the size at which the ring-buffer is considered
 
+   "full" and begins to overwrite old elements with newly pushed ones.
 
+3. Once a ring-buffer has become full, it will never again become un-full except by
 
+   means of `utringbuffer_clear`. There is no way to "pop" a single old item from the
 
+   front of the ring-buffer. You can simulate this ability by maintaining a separate
 
+   integer count of the number of "logically popped elements", and starting your iteration
 
+   with `utringbuffer_eltptr(a, popped_count)` instead of with `utringbuffer_front(a)`.
 
+4. Pointers to elements (obtained using `utringbuffer_eltptr`, `utringbuffer_front`,
 
+   `utringbuffer_next`, etc.) are not generally invalidated by `utringbuffer_push_back`,
 
+   because utringbuffer does not perform reallocation; however, a pointer to the oldest
 
+   element may suddenly turn into a pointer to the 'newest' element if
 
+   `utringbuffer_push_back` is called while the buffer is full.
 
+5. The elements of a ring-buffer are stored in contiguous memory, but once the ring-buffer
 
+   has become full, it is no longer true that the elements are contiguously in order from
 
+   oldest to newest; i.e., `(element *)utringbuffer_front(a) + utringbuffer_len(a)-1` is
 
+   not generally equal to `(element *)utringbuffer_back(a)`.
 
+
 
+// vim: set nowrap syntax=asciidoc:

+ 104 - 0
src/utringbuffer.h
View File 

@@ -0,0 +1,104 @@
 
+/*
 
+Copyright (c) 2008-2014, Troy D. Hanson   http://troydhanson.github.com/uthash/
 
+All rights reserved.
 
+
 
+Redistribution and use in source and binary forms, with or without
 
+modification, are permitted provided that the following conditions are met:
 
+
 
+    * Redistributions of source code must retain the above copyright
 
+      notice, this list of conditions and the following disclaimer.
 
+
 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
 
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+*/
 
+
 
+/* a ring-buffer implementation using macros
 
+ */
 
+#ifndef UTRINGBUFFER_H
 
+#define UTRINGBUFFER_H
 
+ 
+#include <stdlib.h>
 
+#include <string.h>
 
+#include "utarray.h"  // for "UT_icd"
 
+ 
+typedef struct {
 
+    unsigned i;       /* index of next available slot; wraps at n */
 
+    unsigned n;       /* capacity */
 
+    unsigned char f;  /* full */
 
+    UT_icd icd;       /* initializer, copy and destructor functions */
 
+    char *d;          /* n slots of size icd->sz */
 
+} UT_ringbuffer;
 
+ 
+#define utringbuffer_init(a, _n, _icd) do {                               \
 
+  memset(a, 0, sizeof(UT_ringbuffer));                                    \
 
+  (a)->icd = *(_icd);                                                     \
 
+  (a)->n = (_n);                                                          \
 
+  if ((a)->n) { (a)->d = malloc((a)->n * (_icd)->sz); }                   \
 
+} while(0)
 
+ 
+#define utringbuffer_clear(a) do {                                        \
 
+  if ((a)->icd.dtor) {                                                    \
 
+    if ((a)->f) {                                                         \
 
+      for (unsigned _ut_i=0; _ut_i < (a)->n; _ut_i++) {                   \
 
+        (a)->icd.dtor(utringbuffer_eltptr(a, _ut_i));                     \
 
+      }                                                                   \
 
+    } else {                                                              \
 
+      for (unsigned _ut_i=0; _ut_i < (a)->i; _ut_i++) {                   \
 
+        (a)->icd.dtor(utringbuffer_eltptr(a, _ut_i));                     \
 
+      }                                                                   \
 
+    }                                                                     \
 
+  }                                                                       \
 
+  (a)->i = 0;                                                             \
 
+  (a)->f = 0;                                                             \
 
+} while(0)
 
+ 
+#define utringbuffer_done(a) do {                                         \
 
+  utringbuffer_clear(a);                                                  \
 
+  free((a)->d); (a)->d = NULL;                                            \
 
+  (a)->n = 0;                                                             \
 
+} while(0)
 
+ 
+#define utringbuffer_new(a,n,_icd) do {                                   \
 
+  a = (UT_ringbuffer*)malloc(sizeof(UT_ringbuffer));                      \
 
+  utringbuffer_init(a, n, _icd);                                          \
 
+} while(0)
 
+ 
+#define utringbuffer_free(a) do {                                         \
 
+  utringbuffer_done(a);                                                   \
 
+  free(a);                                                                \
 
+} while(0)
 
+ 
+#define utringbuffer_push_back(a,p) do {                                                \
 
+  if ((a)->icd.dtor && (a)->f) { (a)->icd.dtor(_utringbuffer_internalptr(a,(a)->i)); }  \
 
+  if ((a)->icd.copy) { (a)->icd.copy( _utringbuffer_internalptr(a,(a)->i), p); }        \
 
+  else { memcpy(_utringbuffer_internalptr(a,(a)->i), p, (a)->icd.sz); };                \
 
+  if (++(a)->i == (a)->n) { (a)->i = 0; (a)->f = 1; }                                   \
 
+} while(0)
 
+ 
+#define utringbuffer_len(a) ((a)->f ? (a)->n : (a)->i)
 
+#define utringbuffer_empty(a) ((a)->i == 0 && !(a)->f)
 
+#define utringbuffer_full(a) ((a)->f != 0)
 
+ 
+#define _utringbuffer_real_idx(a,j) ((a)->f ? ((j) + (a)->i) % (a)->n : (j))
 
+#define _utringbuffer_internalptr(a,j) ((void*)((char*)((a)->d + ((a)->icd.sz * (j)))))
 
+#define utringbuffer_eltptr(a,j) ((0 <= (j) && (j) < utringbuffer_len(a)) ? _utringbuffer_internalptr(a,_utringbuffer_real_idx(a,j)) : NULL)
 
+ 
+#define _utringbuffer_fake_idx(a,j) ((a)->f ? ((j) + (a)->n - (a)->i) % (a)->n : (j))
 
+#define _utringbuffer_internalidx(a,e) (((char*)(e) >= (char*)(a)->d) ? (((char*)(e) - (char*)(a)->d)/(size_t)(a)->icd.sz) : -1)
 
+#define utringbuffer_eltidx(a,e) _utringbuffer_fake_idx(a, _utringbuffer_internalidx(a,e))
 
+ 
+#define utringbuffer_front(a) utringbuffer_eltptr(a,0)
 
+#define utringbuffer_next(a,e) ((e)==NULL ? utringbuffer_front(a) : utringbuffer_eltptr(a, utringbuffer_eltidx(a,e)+1))
 
+#define utringbuffer_prev(a,e) ((e)==NULL ? utringbuffer_back(a) : utringbuffer_eltptr(a, utringbuffer_eltidx(a,e)-1))
 
+#define utringbuffer_back(a) (utringbuffer_empty(a) ? NULL : utringbuffer_eltptr(a, utringbuffer_len(a) - 1))
 
+
 
+#endif /* UTRINGBUFFER_H */