| <!DOCTYPE html><html><head><meta charset="utf-8" /><meta content="IE=edge" http-equiv="X-UA-Compatible" /><meta content="width=device-width, initial-scale=1, maximum-scale=2.0, user-scalable=yes, minimal-ui=yes" name="viewport" /><title>facil.io - FIOBJ String API</title><meta content="facil.io - FIOBJ String API" name="description" /><link href="https://fonts.googleapis.com/css?family=Montserrat|Quicksand|Karla" rel="stylesheet" type="text/css" /><script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script><link href="/assets/styles/main.css" rel="stylesheet" type="text/css" /><script type="application/ld+json">{"@context":"http://schema.org","@type":"WebSite","url":"http://facil.io","name":"facil.io","description":"facil.io - a light web application framework in C, with support for HTTP, WebSockets and Pub/Sub out of the box.","keywords":"C, web, framework, websockets, websocket, realtime, real-time, easy","image":"http://facil.io/website/logo/facil-io.svg","author":[{"@type":"Person","name":"Bo (Myst)","url":"http://stackoverflow.com/users/4025095/myst","email":"bo(at)facil.io"}],"sourceOrganization":{"@context":"http://schema.org","@type":"Organization","name":"Plezi","url":"http://facil.io","description":"facil.io - a light web application framework in C, with support for HTTP, WebSockets and Pub/Sub out of the box.","logo":"http://facil.io/website/logo/facil-io.svg","image":"http://facil.io/website/logo/facil-io.svg","email":"bo(at)facil.io","member":[{"@type":"Person","name":"Bo (Myst)","url":"http://stackoverflow.com/users/4025095/myst","email":"bo(at)facil.io"}]}}</script><meta content="facil.io" name="apple-mobile-web-app-title" /><meta content="facil.io - the C Web Application Framework" name="application-name" /><meta content="#b91d47" name="msapplication-TileColor" /><meta content="/mstile-144x144.png" name="msapplication-TileImage" /><meta content="#ffffff" name="theme-color" /></head><body><a href="/" id="logo"></a><input id="show_nav" type="checkbox" /><nav id="top_nav"><ul><li><a href="/0.7.x/index">Latest Docs</a></li><li><a href="https://github.com/boazsegev/facil.io" target="_blank">Source Code</a></li><li><a href="javascript: change_themes();" id="theme">Night Theme</a></li></ul></nav><input id="show_sidebar" type="checkbox" /><nav id="side_bar"><h2 id="version-0-7-x"><a href="/0.7.x/index">Version 0.7.x</a></h2> |
| |
| <h3 id="core-library"><a href="/0.7.x/fio">Core Library</a></h3> |
| |
| <ul> |
| <li><a href="/0.7.x/fio#connection-protocol-management">Protocol Management</a></li> |
| <li><a href="/0.7.x/fio#running-facil-io">Running the IO reactor</a></li> |
| <li><a href="/0.7.x/fio#socket-connection-functions">Connection Functions</a></li> |
| <li><a href="/0.7.x/fio#event-task-scheduling">Event / Task Scheduling</a></li> |
| <li><a href="/0.7.x/fio#pub-sub-services">Pub/Sub Services</a></li> |
| <li><a href="/0.7.x/fio#the-custom-memory-allocator">Memory Allocation</a></li> |
| <li><a href="/0.7.x/fio#general-helpers">General Helpers</a></li> |
| <li><a href="/0.7.x/fio#linked-lists">Linked Lists</a></li> |
| <li><a href="/0.7.x/fio#string-helpers">String Helpers</a></li> |
| <li><a href="/0.7.x/fio#hash-maps-sets">Hash Maps / Sets</a></li> |
| <li><a href="/0.7.x/fio#version-and-compilation-related-macros">Compilation Macros</a></li> |
| <li><a href="/0.7.x/fio#weak-functions">Weak Functions</a></li> |
| </ul> |
| |
| <h3 id="extensions"><a href="/0.7.x/extensions">Extensions</a></h3> |
| |
| <ul> |
| <li><a href="/0.7.x/http">HTTP / WebSockets</a></li> |
| <li><a href="/0.7.x/redis">Redis (client)</a></li> |
| <li><a href="/0.7.x/fio_cli">CLI (command line)</a></li> |
| </ul> |
| |
| <h3 id="the-fiobj-types"><a href="/0.7.x/fiobj">The FIOBJ types</a></h3> |
| |
| <ul> |
| <li><a href="/0.7.x/fiobj_core">Core Functions</a></li> |
| <li><a href="/0.7.x/fiobj_primitives">Primitives</a></li> |
| <li><a href="/0.7.x/fiobj_numbers">Numbers</a></li> |
| <li><a href="/0.7.x/fiobj_str">Strings</a></li> |
| <li><a href="/0.7.x/fiobj_ary">Array</a></li> |
| <li><a href="/0.7.x/fiobj_hash">HashMap</a></li> |
| <li><a href="/0.7.x/fiobj_data">Data Streams</a></li> |
| <li><a href="/0.7.x/fiobj_json">JSON</a></li> |
| </ul> |
| </nav><div id="md_container"><div class='toc'><ul> |
| <li> |
| <a href="#facil-io-fiobj-string-api">facil.io - FIOBJ String API</a> |
| <ul> |
| <li> |
| <ul> |
| <li> |
| <a href="#fiobj-string-initialization">FIOBJ String Initialization</a> |
| <ul> |
| <li> |
| <a href="#fiobj_str_new"><code>fiobj_str_new</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_buf"><code>fiobj_str_buf</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_copy"><code>fiobj_str_copy</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_move"><code>fiobj_str_move</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_tmp"><code>fiobj_str_tmp</code></a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#string-manipulation-and-data">String Manipulation and Data</a> |
| <ul> |
| <li> |
| <ul> |
| <li> |
| <a href="#fiobj_str_freeze"><code>fiobj_str_freeze</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_capa_assert"><code>fiobj_str_capa_assert</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_capa"><code>fiobj_str_capa</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_resize"><code>fiobj_str_resize</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_compact"><code>fiobj_str_compact</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_compact"><code>fiobj_str_compact</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_clear"><code>fiobj_str_clear</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_write"><code>fiobj_str_write</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_write_i"><code>fiobj_str_write_i</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_printf"><code>fiobj_str_printf</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_vprintf"><code>fiobj_str_vprintf</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_concat"><code>fiobj_str_concat</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_join"><code>fiobj_str_join</code></a> |
| </li> |
| <li> |
| <a href="#fiobj_str_readfile"><code>fiobj_str_readfile</code></a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#hashing">Hashing</a> |
| <ul> |
| <li> |
| <a href="#fiobj_str_hash"><code>fiobj_str_hash</code></a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div><h1 id="facil-io-fiobj-string-api">facil.io - FIOBJ String API</h1> |
| |
| <p>See the <a href="%60fiobj_core%60">core FIOBJ functions</a> for accessing the String data (<a href="fiobj_core#fiobj_obj2cstr"><code>fiobj_obj2cstr</code></a>) and freeing the String object (<a href="fiobj_core#fiobj_free"><code>fiobj_free</code></a>).</p> |
| |
| <h3 id="fiobj-string-initialization">FIOBJ String Initialization</h3> |
| |
| <h4 id="fiobj_str_new"><code>fiobj_str_new</code></h4> |
| <pre><code class='highlight'><span class="n">FIOBJ</span> <span class="n">fiobj_str_new</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span> |
| </code></pre> |
| <p>Creates a String object. Remember to use <code>fiobj_free</code>.</p> |
| |
| <h4 id="fiobj_str_buf"><code>fiobj_str_buf</code></h4> |
| <pre><code class='highlight'><span class="n">FIOBJ</span> <span class="n">fiobj_str_buf</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">capa</span><span class="p">);</span> |
| </code></pre> |
| <p>Creates a String object with pre-allocation for Strings up to <code>capa</code> long.</p> |
| |
| <p>If <code>capa</code> is zero, <strong>a whole memory page</strong> will be allocated.</p> |
| |
| <p>Remember to use <code>fiobj_free</code>.</p> |
| |
| <h4 id="fiobj_str_copy"><code>fiobj_str_copy</code></h4> |
| <pre><code class='highlight'><span class="k">static</span> <span class="kr">inline</span> <span class="n">FIOBJ</span> <span class="n">fiobj_str_copy</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">src</span><span class="p">);</span> |
| </code></pre> |
| <p>Creates a copy from an existing String. Remember to use <code>fiobj_free</code>.</p> |
| |
| <p>Implemented as:</p> |
| <pre><code class='highlight'><span class="k">static</span> <span class="kr">inline</span> <span class="n">FIOBJ</span> <span class="nf">fiobj_str_copy</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">src</span><span class="p">)</span> <span class="p">{</span> |
| <span class="n">fio_str_info_s</span> <span class="n">s</span> <span class="o">=</span> <span class="n">fiobj_obj2cstr</span><span class="p">(</span><span class="n">src</span><span class="p">);</span> |
| <span class="k">return</span> <span class="n">fiobj_str_new</span><span class="p">(</span><span class="n">s</span><span class="p">.</span><span class="n">data</span><span class="p">,</span> <span class="n">s</span><span class="p">.</span><span class="n">len</span><span class="p">);</span> |
| <span class="p">}</span> |
| </code></pre> |
| <h4 id="fiobj_str_move"><code>fiobj_str_move</code></h4> |
| <pre><code class='highlight'><span class="n">FIOBJ</span> <span class="n">fiobj_str_move</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">capacity</span><span class="p">);</span> |
| </code></pre> |
| <p>Creates a String object. Remember to use <code>fiobj_free</code>.</p> |
| |
| <p>It's possible to wrap a previosly allocated memory block in a FIOBJ String object, as long as it was allocated using <code>fio_malloc</code>.</p> |
| |
| <p>The ownership of the memory indicated by <code>str</code> will "move" to the object and will be freed (using <code>fio_free</code>) once the object's reference count drops to zero.</p> |
| |
| <p>Note: The original memory MUST be allocated using <code>fio_malloc</code> (NOT the system's <code>malloc</code>) and it will be freed using <code>fio_free</code>.</p> |
| |
| <h4 id="fiobj_str_tmp"><code>fiobj_str_tmp</code></h4> |
| <pre><code class='highlight'><span class="n">FIOBJ</span> <span class="n">fiobj_str_tmp</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> |
| </code></pre> |
| <p>Returns a thread-static temporary string. Avoid calling <code>fiobj_dup</code> or <code>fiobj_free</code>.</p> |
| |
| <h2 id="string-manipulation-and-data">String Manipulation and Data</h2> |
| |
| <h4 id="fiobj_str_freeze"><code>fiobj_str_freeze</code></h4> |
| <pre><code class='highlight'><span class="kt">void</span> <span class="n">fiobj_str_freeze</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">);</span> |
| </code></pre> |
| <p>Prevents the String object from being changed.</p> |
| |
| <p>When a String is used as a key for a Hash, it is automatically frozen to prevent the Hash from becoming broken.</p> |
| |
| <h4 id="fiobj_str_capa_assert"><code>fiobj_str_capa_assert</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_capa_assert</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span> |
| </code></pre> |
| <p>Confirms the requested capacity is available and allocates as required.</p> |
| |
| <p>Returns updated capacity.</p> |
| |
| <h4 id="fiobj_str_capa"><code>fiobj_str_capa</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_capa</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">);</span> |
| </code></pre> |
| <p>Returns a String's capacity, if any. This should include the NUL byte.</p> |
| |
| <h4 id="fiobj_str_resize"><code>fiobj_str_resize</code></h4> |
| <pre><code class='highlight'><span class="kt">void</span> <span class="n">fiobj_str_resize</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span> |
| </code></pre> |
| <p>Resizes a String object, allocating more memory if required.</p> |
| |
| <h4 id="fiobj_str_compact"><code>fiobj_str_compact</code></h4> |
| <pre><code class='highlight'><span class="kt">void</span> <span class="n">fiobj_str_compact</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">);</span> |
| </code></pre> |
| <p>Performs a best attempt at minimizing memory consumption.</p> |
| |
| <p>Actual effects depend on the underlying memory allocator and it's implementation. Not all allocators will free any memory.</p> |
| |
| <h4 id="fiobj_str_compact"><code>fiobj_str_compact</code></h4> |
| <pre><code class='highlight'><span class="cp">#define fiobj_str_minimize(str) fiobj_str_compact((str)) |
| </span></code></pre> |
| <p>Alias for <code>fiobj_str_compact</code>.</p> |
| |
| <h4 id="fiobj_str_clear"><code>fiobj_str_clear</code></h4> |
| <pre><code class='highlight'><span class="kt">void</span> <span class="n">fiobj_str_clear</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">str</span><span class="p">);</span> |
| </code></pre> |
| <p>Empties a String's data, but keeps the memory used for that data available.</p> |
| |
| <h4 id="fiobj_str_write"><code>fiobj_str_write</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_write</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">data</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span> |
| </code></pre> |
| <p>Writes data at the end of the string, resizing the string as required.</p> |
| |
| <p>Returns the new length of the String.</p> |
| |
| <h4 id="fiobj_str_write_i"><code>fiobj_str_write_i</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_write_i</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="kt">int64_t</span> <span class="n">num</span><span class="p">)</span> |
| </code></pre> |
| <p>Writes a number at the end of the String using normal base 10 notation.</p> |
| |
| <p>Returns the new length of the String</p> |
| |
| <h4 id="fiobj_str_printf"><code>fiobj_str_printf</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_printf</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">format</span><span class="p">,</span> <span class="p">...);</span> |
| </code></pre> |
| <p>Writes data at the end of the string using a <code>printf</code> like interface, resizing the string as required.</p> |
| |
| <p>Returns the new length of the String</p> |
| |
| <h4 id="fiobj_str_vprintf"><code>fiobj_str_vprintf</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_vprintf</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">format</span><span class="p">,</span> <span class="kt">va_list</span> <span class="n">argv</span><span class="p">);</span> |
| </code></pre> |
| <p>Writes data at the end of the string using a <code>vprintf</code> like interface, resizing the string as required.</p> |
| |
| <p>Returns the new length of the String.</p> |
| |
| <h4 id="fiobj_str_concat"><code>fiobj_str_concat</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_concat</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="n">FIOBJ</span> <span class="n">source</span><span class="p">);</span> |
| </code></pre> |
| <p>Writes data at the end of the string, resizing the string as required.</p> |
| |
| <p>Remember to call <code>fiobj_free</code> to free the source (when done with it).</p> |
| |
| <p>Returns the new length of the String.</p> |
| |
| <h4 id="fiobj_str_join"><code>fiobj_str_join</code></h4> |
| <pre><code class='highlight'><span class="cp">#define fiobj_str_join(dest, src) fiobj_str_concat((dest), (src)) |
| </span></code></pre> |
| <p>Alias for <a href="#fiobj_str_concat"><code>fiobj_str_concat</code></a>.</p> |
| |
| <h4 id="fiobj_str_readfile"><code>fiobj_str_readfile</code></h4> |
| <pre><code class='highlight'><span class="kt">size_t</span> <span class="n">fiobj_str_readfile</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">filename</span><span class="p">,</span> <span class="kt">intptr_t</span> <span class="n">start_at</span><span class="p">,</span> |
| <span class="kt">intptr_t</span> <span class="n">limit</span><span class="p">);</span> |
| </code></pre> |
| <p>Dumps the contents of <code>filename</code> at the end of the String.</p> |
| |
| <p>If <code>limit == 0</code>, than the data will be read until EOF.</p> |
| |
| <p>If the file can't be located, opened or read, or if <code>start_at</code> is out of bounds (i.e., beyond the EOF position), FIOBJ_INVALID is returned.</p> |
| |
| <p>If <code>start_at</code> is negative, it will be computed from the end of the file.</p> |
| |
| <p>Remember to use <code>fiobj_free</code>.</p> |
| |
| <p>NOTE: Requires a POSIX system, or might silently fail.</p> |
| |
| <h3 id="hashing">Hashing</h3> |
| |
| <h4 id="fiobj_str_hash"><code>fiobj_str_hash</code></h4> |
| <pre><code class='highlight'><span class="kt">uint64_t</span> <span class="n">fiobj_str_hash</span><span class="p">(</span><span class="n">FIOBJ</span> <span class="n">o</span><span class="p">);</span> |
| </code></pre> |
| <p>Calculates a String's SipHash value for possible use as a Hash Map key.</p> |
| </div><a href="/" id="sign"></a><div class="hidden" id="notice"><a class="notice_close" onclick="hide_notice()">X</a><div id="notice_text"></div></div><script>function change_themes() { |
| if(localStorage.getItem("theme") == 'dark') { |
| localStorage.setItem("theme", "light"); |
| } else { |
| localStorage.setItem("theme", "dark"); |
| } |
| $('body')[0].className = localStorage.getItem("theme"); |
| set_theme_link(); |
| $('#show_nav').attr('checked', false); |
| return false; |
| }; |
| function sidebar_name() { return window.location.pathname.slice(0, window.location.pathname.lastIndexOf("/")); } |
| function on_sidebar_link(e) { |
| sessionStorage.setItem("sidebar.expect", sidebar_name()); |
| sessionStorage.setItem("sidebar.pos", document.getElementById("side_bar").scrollTop); |
| } |
| function load_sidebar_pos() { |
| var e = document.getElementById("side_bar"); |
| if(!e) { |
| console.warn("No sidebar detected"); |
| return; |
| } |
| var expect = sidebar_name(); |
| if(sessionStorage.getItem("sidebar.expect") == expect) { |
| e.scrollTo(0, parseInt(sessionStorage.getItem("sidebar.pos"))); |
| } else { |
| sessionStorage.setItem("sidebar.expect", false); |
| sessionStorage.setItem("sidebar.pos", 0); |
| } |
| if(e) { |
| // add link callbacks |
| var links = document.links; |
| var count = links.length; |
| for (var i = 0; i < count; i++) { |
| var href = links[i].href; |
| if(href.startsWith(document.location.origin)) { |
| href = href.slice(document.location.origin.length); |
| } |
| if(href.startsWith(expect)) { |
| /* add link event */ |
| links[i].addEventListener("click", on_sidebar_link); |
| } |
| } |
| } |
| |
| }; |
| load_sidebar_pos(); |
| function set_theme_link() { |
| $("#theme").html( ( (localStorage.getItem("theme") == 'dark') ? "Day" : "Night") + " Theme" ); |
| } |
| $('body')[0].className = (localStorage.getItem("theme") == 'dark') ? "dark" : "light"; |
| set_theme_link(); |
| function show_notice() { document.getElementById("notice").classList.remove('hidden'); }; |
| function hide_notice() { document.getElementById("notice").classList.add('hidden'); }; |
| $('#toc').on("touchstart", function (e) { return true; } ); |
| $('#toc').on("hover", function (e) { return true; } ); |
| // hljs.initHighlighting(); |
| // Google Analytics |
| // if(location.hostname != "localhost") { |
| // (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| // (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| // m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| // })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| // ga('create', 'UA-69931401-1', 'auto'); |
| // ga('send', 'pageview'); |
| // }</script></body></html> |