diff options
Diffstat (limited to 'apidocs/icalarray_8h.html')
-rw-r--r-- | apidocs/icalarray_8h.html | 59 |
1 files changed, 26 insertions, 33 deletions
diff --git a/apidocs/icalarray_8h.html b/apidocs/icalarray_8h.html index 08e3c0d9..b699711a 100644 --- a/apidocs/icalarray_8h.html +++ b/apidocs/icalarray_8h.html @@ -1,9 +1,9 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/> -<meta name="generator" content="Doxygen 1.8.14"/> +<meta name="generator" content="Doxygen 1.8.15"/> <meta name="viewport" content="width=device-width, initial-scale=1"/> <title>Libical API Documentation: icalarray.h File Reference</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> @@ -30,7 +30,7 @@ </table> </div> <!-- end header part --> -<!-- Generated by Doxygen 1.8.14 --> +<!-- Generated by Doxygen 1.8.15 --> <script type="text/javascript"> /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ var searchBox = new SearchBox("searchBox", "search",false,'Search'); @@ -98,7 +98,7 @@ Functions</h2></td></tr> <tr class="memdesc:a9a11feb130b619af9dd7f4003d52d242"><td class="mdescLeft"> </td><td class="mdescRight">Appends an element to an array. <a href="#a9a11feb130b619af9dd7f4003d52d242">More...</a><br /></td></tr> <tr class="separator:a9a11feb130b619af9dd7f4003d52d242"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:aa4bcd6fa2682deef8bdfd0d3b59be567"><td class="memItemLeft" align="right" valign="top"><a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="icalarray_8h.html#aa4bcd6fa2682deef8bdfd0d3b59be567">icalarray_copy</a> (<a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> *array)</td></tr> -<tr class="memdesc:aa4bcd6fa2682deef8bdfd0d3b59be567"><td class="mdescLeft"> </td><td class="mdescRight">Copies an existing <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> and it's elements, creating a new one. <a href="#aa4bcd6fa2682deef8bdfd0d3b59be567">More...</a><br /></td></tr> +<tr class="memdesc:aa4bcd6fa2682deef8bdfd0d3b59be567"><td class="mdescLeft"> </td><td class="mdescRight">Copies an existing <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> and it's elements, creating a new one. <a href="#aa4bcd6fa2682deef8bdfd0d3b59be567">More...</a><br /></td></tr> <tr class="separator:aa4bcd6fa2682deef8bdfd0d3b59be567"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a8d76fb1a34690980421b6c82c40d5f9c"><td class="memItemLeft" align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a> (<a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> *array, size_t position)</td></tr> <tr class="memdesc:a8d76fb1a34690980421b6c82c40d5f9c"><td class="mdescLeft"> </td><td class="mdescRight">Access an array element. <a href="#a8d76fb1a34690980421b6c82c40d5f9c">More...</a><br /></td></tr> @@ -107,13 +107,13 @@ Functions</h2></td></tr> <tr class="memdesc:a725724cdff58a12520abc7d6bfdf5e0f"><td class="mdescLeft"> </td><td class="mdescRight">Frees an array object and everything that it contains. <a href="#a725724cdff58a12520abc7d6bfdf5e0f">More...</a><br /></td></tr> <tr class="separator:a725724cdff58a12520abc7d6bfdf5e0f"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a0254b829a5b491bf42d19afa3b2d6f1e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a> (size_t element_size, size_t increment_size)</td></tr> -<tr class="memdesc:a0254b829a5b491bf42d19afa3b2d6f1e"><td class="mdescLeft"> </td><td class="mdescRight">Creates new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object. <a href="#a0254b829a5b491bf42d19afa3b2d6f1e">More...</a><br /></td></tr> +<tr class="memdesc:a0254b829a5b491bf42d19afa3b2d6f1e"><td class="mdescLeft"> </td><td class="mdescRight">Creates new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object. <a href="#a0254b829a5b491bf42d19afa3b2d6f1e">More...</a><br /></td></tr> <tr class="separator:a0254b829a5b491bf42d19afa3b2d6f1e"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:afeff7fd9edc32284b5fb34fb61ec8c0a"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="icalarray_8h.html#afeff7fd9edc32284b5fb34fb61ec8c0a">icalarray_remove_element_at</a> (<a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> *array, size_t position)</td></tr> <tr class="memdesc:afeff7fd9edc32284b5fb34fb61ec8c0a"><td class="mdescLeft"> </td><td class="mdescRight">Removes a given element from an array. <a href="#afeff7fd9edc32284b5fb34fb61ec8c0a">More...</a><br /></td></tr> <tr class="separator:afeff7fd9edc32284b5fb34fb61ec8c0a"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:a7552d72058960fe92eeae36531275913"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="icalarray_8h.html#a7552d72058960fe92eeae36531275913">icalarray_sort</a> (<a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598">icalarray</a> *array, int(*compare)(const void *, const void *))</td></tr> -<tr class="memdesc:a7552d72058960fe92eeae36531275913"><td class="mdescLeft"> </td><td class="mdescRight">Sorts the elements of an <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> using the given comparison function. <a href="#a7552d72058960fe92eeae36531275913">More...</a><br /></td></tr> +<tr class="memdesc:a7552d72058960fe92eeae36531275913"><td class="mdescLeft"> </td><td class="mdescRight">Sorts the elements of an <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> using the given comparison function. <a href="#a7552d72058960fe92eeae36531275913">More...</a><br /></td></tr> <tr class="separator:a7552d72058960fe92eeae36531275913"><td class="memSeparator" colspan="2"> </td></tr> </table> <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> @@ -156,8 +156,7 @@ Functions</h2></td></tr> <p>Appends the given <em>element</em> to the <em>array</em>, reallocating and expanding the array as needed.</p> <dl class="section user"><dt>Error handling</dt><dd>If <em>array</em> or <em>element</em> is <code>NULL</code>, using this function results in undefined behaviour (most likely a segfault).</dd></dl> <dl class="section user"><dt>Ownership</dt><dd>The <em>element</em> does not get consumed by the method, since it creates a copy of it</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// append data to it</span></div><div class="line"><span class="keywordtype">int</span> data = 42;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &data);</div><div class="line"></div><div class="line"><span class="comment">// release array</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> +<p>### Usage </p><div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// append data to it</span></div><div class="line"><span class="keywordtype">int</span> data = 42;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &data);</div><div class="line"></div><div class="line"><span class="comment">// release array</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> </div> </div> <a id="aa4bcd6fa2682deef8bdfd0d3b59be567"></a> @@ -176,7 +175,7 @@ Functions</h2></td></tr> </table> </div><div class="memdoc"> -<p>Copies an existing <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> and it's elements, creating a new one. </p> +<p>Copies an existing <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> and it's elements, creating a new one. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">array</td><td>The array to copy </td></tr> @@ -184,11 +183,10 @@ Functions</h2></td></tr> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>A new array, holding all the elements of <em>array</em> </dd></dl> -<p>Creates a new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object, copying all the existing elements from <em>array</em> as well as it's properties (such as <em>element_size</em> and <em>increment_size</em>) over.</p> -<dl class="section user"><dt>Error handling</dt><dd>If <em>array</em> is <code>NULL</code>, this method will return <code>NULL</code>. If there was an error allocating memory while creating the copy, it will set <a class="el" href="icalerror_8h.html#ad2562706150f5c5a4d9b0ca149d78e37" title="Access the current icalerrno value. ">icalerrno</a> to <a class="el" href="icalerror_8h.html#a601c122fcea522513b1b7732fa23e833a3ed4d866c28acaaaf99348b1ab27cd78">ICAL_ALLOCATION_ERROR</a>.</dd></dl> -<dl class="section user"><dt>Ownership</dt><dd>The created copy is owned by the caller of the function, and needs to be released with <a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains. ">icalarray_free()</a> after it's no longer being used.</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// create copy of array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *copy = <a class="code" href="icalarray_8h.html#aa4bcd6fa2682deef8bdfd0d3b59be567">icalarray_copy</a>(array);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(copy, 0) == a);</div><div class="line"></div><div class="line"><span class="comment">// release arrays</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(copy);</div></div><!-- fragment --> +<p>Creates a new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object, copying all the existing elements from <em>array</em> as well as it's properties (such as <em>element_size</em> and <em>increment_size</em>) over.</p> +<dl class="section user"><dt>Error handling</dt><dd>If <em>array</em> is <code>NULL</code>, this method will return <code>NULL</code>. If there was an error allocating memory while creating the copy, it will set <a class="el" href="icalerror_8h.html#ad2562706150f5c5a4d9b0ca149d78e37" title="Access the current icalerrno value.">icalerrno</a> to <a class="el" href="icalerror_8h.html#a601c122fcea522513b1b7732fa23e833a3ed4d866c28acaaaf99348b1ab27cd78">ICAL_ALLOCATION_ERROR</a>.</dd></dl> +<dl class="section user"><dt>Ownership</dt><dd>The created copy is owned by the caller of the function, and needs to be released with <a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains.">icalarray_free()</a> after it's no longer being used.</dd></dl> +<p>### Usage </p><div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// create copy of array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *copy = <a class="code" href="icalarray_8h.html#aa4bcd6fa2682deef8bdfd0d3b59be567">icalarray_copy</a>(array);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(copy, 0) == a);</div><div class="line"></div><div class="line"><span class="comment">// release arrays</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(copy);</div></div><!-- fragment --> </div> </div> <a id="a8d76fb1a34690980421b6c82c40d5f9c"></a> @@ -228,9 +226,8 @@ Functions</h2></td></tr> <dl class="section return"><dt>Returns</dt><dd>A pointer to the element inside the array</dd></dl> <p>Accesses an array element by returning a pointer to it, given an <em>array</em> and a valid element <em>position</em>.</p> <dl class="section user"><dt>Error handling</dt><dd>If <em>array</em> is <code>NULL</code>, using this function results in undefined behaviour. If <em>position</em> is not a valid position in the array, using this function results in undefined behaviour.</dd></dl> -<dl class="section user"><dt>Ownership</dt><dd>The element is owned by the <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a>, it must not be freed by the user.</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// access array element</span></div><div class="line"><span class="keywordtype">int</span> *element = <a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0);</div><div class="line">assert(element != NULL);</div><div class="line">assert(*element == a);</div><div class="line"></div><div class="line"><span class="comment">// change array element</span></div><div class="line">*element = 14;</div><div class="line">assert(*icalarray_element(array) == 14);</div><div class="line"></div><div class="line"><span class="comment">// release memory</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> +<dl class="section user"><dt>Ownership</dt><dd>The element is owned by the <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a>, it must not be freed by the user.</dd></dl> +<p>### Usage </p><div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// access array element</span></div><div class="line"><span class="keywordtype">int</span> *element = <a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0);</div><div class="line">assert(element != NULL);</div><div class="line">assert(*element == a);</div><div class="line"></div><div class="line"><span class="comment">// change array element</span></div><div class="line">*element = 14;</div><div class="line">assert(*icalarray_element(array) == 14);</div><div class="line"></div><div class="line"><span class="comment">// release memory</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> </div> </div> <a id="a725724cdff58a12520abc7d6bfdf5e0f"></a> @@ -256,8 +253,7 @@ Functions</h2></td></tr> </table> </dd> </dl> -<h3>Example</h3> -<div class="fragment"><div class="line"><span class="comment">// creating an array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// releasing it</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> +<p>### Example </p><div class="fragment"><div class="line"><span class="comment">// creating an array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// releasing it</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> </div> </div> <a id="a0254b829a5b491bf42d19afa3b2d6f1e"></a> @@ -286,7 +282,7 @@ Functions</h2></td></tr> </table> </div><div class="memdoc"> -<p>Creates new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object. </p> +<p>Creates new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">element_size</td><td>The size of the elements to be held by the array </td></tr> @@ -294,13 +290,12 @@ Functions</h2></td></tr> </table> </dd> </dl> -<dl class="section return"><dt>Returns</dt><dd>The new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object </dd></dl> -<dl class="section see"><dt>See also</dt><dd><a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains. ">icalarray_free()</a></dd></dl> -<p>Creates a new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object. The parameter <em>element_size</em> determines the size of the elements that the array will hold (in bytes). The parameter <em>increment_size</em> determines how many extra elements to be allocated when expanding the array for performance reasons (expansions are expensive, since it involves copying all existing elements).</p> -<dl class="section user"><dt>Error handling</dt><dd>If <em>element_size</em> or <em>increment_size</em> is not at least 1, using the <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object results in undefined behaviour. If there is an error while creating the object, it returns <code>NULL</code> and sets <a class="el" href="icalerror_8h.html#ad2562706150f5c5a4d9b0ca149d78e37" title="Access the current icalerrno value. ">icalerrno</a> to <a class="el" href="icalerror_8h.html#a601c122fcea522513b1b7732fa23e833a055394ffaf6701aa12491dc10767f07d">ICAL_NEWFAILED_ERROR</a>.</dd></dl> -<dl class="section user"><dt>Ownership</dt><dd>The returned <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> object is owned by the caller of the function, and needs to be released properly after it's no longer needed with <a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains. ">icalarray_free()</a>.</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// use array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == a);</div><div class="line"></div><div class="line"><span class="comment">// release memory</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> +<dl class="section return"><dt>Returns</dt><dd>The new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object </dd></dl> +<dl class="section see"><dt>See also</dt><dd><a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains.">icalarray_free()</a></dd></dl> +<p>Creates a new <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object. The parameter <em>element_size</em> determines the size of the elements that the array will hold (in bytes). The parameter <em>increment_size</em> determines how many extra elements to be allocated when expanding the array for performance reasons (expansions are expensive, since it involves copying all existing elements).</p> +<dl class="section user"><dt>Error handling</dt><dd>If <em>element_size</em> or <em>increment_size</em> is not at least 1, using the <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object results in undefined behaviour. If there is an error while creating the object, it returns <code>NULL</code> and sets <a class="el" href="icalerror_8h.html#ad2562706150f5c5a4d9b0ca149d78e37" title="Access the current icalerrno value.">icalerrno</a> to <a class="el" href="icalerror_8h.html#a601c122fcea522513b1b7732fa23e833a055394ffaf6701aa12491dc10767f07d">ICAL_NEWFAILED_ERROR</a>.</dd></dl> +<dl class="section user"><dt>Ownership</dt><dd>The returned <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> object is owned by the caller of the function, and needs to be released properly after it's no longer needed with <a class="el" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f" title="Frees an array object and everything that it contains.">icalarray_free()</a>.</dd></dl> +<p>### Usage </p><div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 1);</div><div class="line"></div><div class="line"><span class="comment">// use array</span></div><div class="line"><span class="keywordtype">int</span> a = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == a);</div><div class="line"></div><div class="line"><span class="comment">// release memory</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> </div> </div> <a id="afeff7fd9edc32284b5fb34fb61ec8c0a"></a> @@ -333,8 +328,7 @@ Functions</h2></td></tr> <p>array The array from which to remove the element position The position of the element to remove</p> <p>Removes the element at the given position from the array.</p> <dl class="section user"><dt>Error handling</dt><dd>If <em>array</em> is <code>NULL</code>, using this function results in undefined behaviour. If the array is empty, using this functino results in undefined behaviour. If the <em>position</em> is non-existent, it removes the last element.</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 2);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> data;</div><div class="line">data = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 9;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 7;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 10;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// check array</span></div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == 4);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 1) == 9);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 2) == 7);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 3) == 10);</div><div class="line"></div><div class="line"><span class="comment">// remove the second element</span></div><div class="line"><a class="code" href="icalarray_8h.html#afeff7fd9edc32284b5fb34fb61ec8c0a">icalarray_remove_element_at</a>(array, 1);</div><div class="line"></div><div class="line"><span class="comment">// check array</span></div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == 4);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 1) == 7);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 2) == 10);</div><div class="line"></div><div class="line"><span class="comment">// release array</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> +<p>### Usage </p><div class="fragment"><div class="line"><span class="comment">// create new array</span></div><div class="line"><a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 2);</div><div class="line"></div><div class="line"><span class="comment">// fill array</span></div><div class="line"><span class="keywordtype">int</span> data;</div><div class="line">data = 4;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 9;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 7;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line">data = 10;</div><div class="line"><a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &a);</div><div class="line"></div><div class="line"><span class="comment">// check array</span></div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == 4);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 1) == 9);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 2) == 7);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 3) == 10);</div><div class="line"></div><div class="line"><span class="comment">// remove the second element</span></div><div class="line"><a class="code" href="icalarray_8h.html#afeff7fd9edc32284b5fb34fb61ec8c0a">icalarray_remove_element_at</a>(array, 1);</div><div class="line"></div><div class="line"><span class="comment">// check array</span></div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 0) == 4);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 1) == 7);</div><div class="line">assert(*<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, 2) == 10);</div><div class="line"></div><div class="line"><span class="comment">// release array</span></div><div class="line"><a class="code" href="icalarray_8h.html#a725724cdff58a12520abc7d6bfdf5e0f">icalarray_free</a>(array);</div></div><!-- fragment --> </div> </div> <a id="a7552d72058960fe92eeae36531275913"></a> @@ -363,7 +357,7 @@ Functions</h2></td></tr> </table> </div><div class="memdoc"> -<p>Sorts the elements of an <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object. ">icalarray</a> using the given comparison function. </p> +<p>Sorts the elements of an <a class="el" href="icalarray_8h.html#ad36143942d5ac4709b68fff41615e598" title="A struct representing an icalarray object.">icalarray</a> using the given comparison function. </p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">array</td><td>The array to sort </td></tr> @@ -372,8 +366,7 @@ Functions</h2></td></tr> </dd> </dl> <dl class="section user"><dt>Error handling</dt><dd>Passing <code>NULL</code> as either <em>array</em> or <em>compare</em> results in undefined behaviour.</dd></dl> -<h3>Usage</h3> -<div class="fragment"><div class="line"><span class="keywordtype">int</span> compare_ints(<span class="keyword">const</span> <span class="keywordtype">void</span> *a, <span class="keyword">const</span> <span class="keywordtype">void</span> *b) {</div><div class="line"> <span class="keywordflow">return</span> *((<span class="keywordtype">int</span>*)a) - *((<span class="keywordtype">int</span>*)b);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]) {</div><div class="line"> <span class="keywordtype">int</span> numbers[] = {5, 2, 7, 4, 3, 1, 0, 8, 6, 9};</div><div class="line"></div><div class="line"> <a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 3);</div><div class="line"></div><div class="line"> <span class="comment">// fill array</span></div><div class="line"> <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i < 10; i++) {</div><div class="line"> <a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &numbers[i]);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="comment">// sort array</span></div><div class="line"> <a class="code" href="icalarray_8h.html#a7552d72058960fe92eeae36531275913">icalarray_sort</a>(array, compare_ints);</div><div class="line"></div><div class="line"> <span class="comment">// print numbers</span></div><div class="line"> <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i < 10; i++) {</div><div class="line"> printf(<span class="stringliteral">"%i\n"</span>, *((<span class="keywordtype">int</span>*)<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, i)));</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --> +<p>### Usage </p><div class="fragment"><div class="line"><span class="keywordtype">int</span> compare_ints(<span class="keyword">const</span> <span class="keywordtype">void</span> *a, <span class="keyword">const</span> <span class="keywordtype">void</span> *b) {</div><div class="line"> <span class="keywordflow">return</span> *((<span class="keywordtype">int</span>*)a) - *((<span class="keywordtype">int</span>*)b);</div><div class="line">}</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[]) {</div><div class="line"> <span class="keywordtype">int</span> numbers[] = {5, 2, 7, 4, 3, 1, 0, 8, 6, 9};</div><div class="line"></div><div class="line"> <a class="code" href="struct__icalarray.html">icalarray</a> *array = <a class="code" href="icalarray_8h.html#a0254b829a5b491bf42d19afa3b2d6f1e">icalarray_new</a>(<span class="keyword">sizeof</span>(<span class="keywordtype">int</span>), 3);</div><div class="line"></div><div class="line"> <span class="comment">// fill array</span></div><div class="line"> <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i < 10; i++) {</div><div class="line"> <a class="code" href="icalarray_8h.html#a9a11feb130b619af9dd7f4003d52d242">icalarray_append</a>(array, &numbers[i]);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="comment">// sort array</span></div><div class="line"> <a class="code" href="icalarray_8h.html#a7552d72058960fe92eeae36531275913">icalarray_sort</a>(array, compare_ints);</div><div class="line"></div><div class="line"> <span class="comment">// print numbers</span></div><div class="line"> <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i < 10; i++) {</div><div class="line"> printf(<span class="stringliteral">"%i\n"</span>, *((<span class="keywordtype">int</span>*)<a class="code" href="icalarray_8h.html#a8d76fb1a34690980421b6c82c40d5f9c">icalarray_element_at</a>(array, i)));</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> 0;</div><div class="line">}</div></div><!-- fragment --> </div> </div> </div><!-- contents --> @@ -381,7 +374,7 @@ Functions</h2></td></tr> <hr class="footer"/><address class="footer"><small> Generated by  <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/> -</a> 1.8.14 +</a> 1.8.15 </small></address> </body> </html> |