<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libcollection: The COLLECTION interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1>The COLLECTION interface</h1><h3>0.5.0 </h3><p>The collection is a set of items of different types.</p>
<p>To better understand how collections work imagine travel bags. They usually come in different sizes and one can put a bag in a bag when they put away to the shelf in a garage or closet. Collection is such bag except that you can put other bags into each other even if they are not empty.<br/>
When you put items into a bag you do not see the contents of the bag. You just hold the bag. How many other bags inside this bag you do not know. But you might know that you put a "wallet" somewhere there. You ask the bag you hold: "find my wallet and give it to me". get_item function will return you the item that is your "wallet". You can then change something or just get information about the item you retrieved. But in most cases you do not need the wallet itself. You want to get something from the wallet or put something into it. IMO money would be an obvious choice. To do this you use update_xxx_property functions.<br/>
There might be a bag somewhere deep and you might want to add something to it. add_xxx_property_xxx functions allow you to specify sub collection you want the item to be added to. If this sub collection argument is NULL top level collection is assumed.<br/>
The search in the collections uses a "x!y!z" notation to refer to an item (or property). You can search for "wallet" and it will find any first instance of the "wallet" in your luggage. But you might have two wallets. One is yours and another is your significant other's. So you might say find "my!wallet". It will find wallet in your bag (collection) named "my". This collection can be many levels deep inside other collections. You do not need to know the full path to get to it. But if you have the full path you can use the fill path like this "luggage!newbags!my!wallet".<br/>
It is useful to be able to put bags into bags as well as get them out of each other. When the collection is created the header keeps a reference count on how many copies of the collection are known to the world. So one can put a collection into collection and give up its access to it (embed) or still hold to the reference. By embedding the collection the caller effectively gives up its responsibility to destroy the collection after it is used.<br/>
By extracting reference from an internal collection the caller gains access to the collection directly and thus has responsibility to destroy it after use.</p>
<p>Internally collection is implemented as a link list rather than a hash table. This makes it suitable for small (dozens of items) sets of data for which the order is important. Thus the collection properties and sub collections can be used to model objects like a book case. Imagine a book case that consists of multiple shelves. You can perform operations like "add a new
shelf after second shelf" or "put a book on the 4th shelf right before
the book with the red cover."</p>
<p>A bit of terminology:</p>
<ul>
<li><b>collection</b> - an object implemented as a link list that holds properties (attributes).</li>
<li><b>property</b> - a named logical element of the collection.</li>
<li><b>item</b> - physical element of the collection, think about it as a node in the link list.</li>
<li><b>value</b> - data associated with the property.</li>
<li><b>type</b> - type of the data associated with a property.</li>
<li><b>length</b> - length of the data associated with the property.</li>
<li><b>sub collection</b> - collection embedded into another collection. It is a property with the value of a special type. The name of the property that denotes a sub collection can be different from the name of the collection it refers to.</li>
<li><b>traverse</b> - call a function that will internally iterate through a collection and do something with its elements.</li>
<li><b>iterate</b> - step through a collection yourselves.</li>
</ul>
<p>Characters with codes less than space in ASCII table are illegal for property names. Character '!' also illegal in a property or collection name and reserved for "x!y!z" notation.</p>
<p>There is always a header item in any collection that starts the collection. Most of the functions in the interface (unless explicitly stated otherwise) assume that the <a class="el" href="structcollection__item.html" title="Opaque structure that holds one property.">collection_item</a> * argument points to the header element. Passing in elements extracted from the middle of a collection to functions that expect header elements is illegal. There might be not enough checking at the moment but this will be enforced in future versions of the library. </p>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 25 Jun 2011 for libcollection by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
distrib
>
CentOS
>
6
>
i386
>
media
>
updates
>
by-pkgid
>
5d98b2995a46d456a9243853c7259619
>
files
>
39
