<!-- HTML header for doxygen 1.9.4-->
<!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=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>yyjson: Data Structures</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
<link href="yyjson-style.css" rel="stylesheet" type="text/css"/>
<!-- css awesome -->
<script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
DoxygenAwesomeDarkModeToggle.init()
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname"><a href="index.html">yyjson</a><span id="projectnumber"> 0.10.0</span>
</div>
<div id="projectbrief">A high performance C JSON library.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(document).ready(function(){initNavTree('md_doc__data_structure.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Data Structures </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p >yyjson consists of two types of data structures: immutable and mutable.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone"></th><th class="markdownTableHeadNone">Immutable </th><th class="markdownTableHeadNone">Mutable </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">Document </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__doc">yyjson_doc</a> </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__mut__doc">yyjson_mut_doc</a> </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">Value </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a> </td><td class="markdownTableBodyNone"><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a> </td></tr>
</table>
<ul>
<li>Immutable data structures are returned when reading a JSON document. They cannot be modified.</li>
<li>Mutable data structures are created when building a JSON document. They can be modified.</li>
<li>yyjson also provides some functions to convert between these two types of data structures.</li>
</ul>
<p >Please note that the data structures described in this document are considered private, and it is recommended to use the public API to access them.</p>
<hr />
<h1><a class="anchor" id="autotoc_md83"></a>
Immutable Value</h1>
<p >Each JSON value is stored in an immutable <code><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a></code> struct: </p><div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="yyjson_8h.html#structyyjson__val">yyjson_val</a> {</div>
<div class="line"> uint64_t <a class="code hl_variable" href="yyjson_8h.html#ab589c80e05e4e65fa28e23acc1ee8255">tag</a>;</div>
<div class="line"> <span class="keyword">union </span>{</div>
<div class="line"> uint64_t u64;</div>
<div class="line"> int64_t i64;</div>
<div class="line"> <span class="keywordtype">double</span> f64;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *str;</div>
<div class="line"> <span class="keywordtype">void</span> *ptr;</div>
<div class="line"> <span class="keywordtype">size_t</span> ofs;</div>
<div class="line"> } <a class="code hl_variable" href="yyjson_8h.html#a3a07ac3ac97c66ae9b23efeab600d013">uni</a>;</div>
<div class="line">}</div>
<div class="ttc" id="ayyjson_8h_html_a3a07ac3ac97c66ae9b23efeab600d013"><div class="ttname"><a href="yyjson_8h.html#a3a07ac3ac97c66ae9b23efeab600d013">yyjson_val::uni</a></div><div class="ttdeci">yyjson_val_uni uni</div><div class="ttdef"><b>Definition:</b> yyjson.h:4516</div></div>
<div class="ttc" id="ayyjson_8h_html_ab589c80e05e4e65fa28e23acc1ee8255"><div class="ttname"><a href="yyjson_8h.html#ab589c80e05e4e65fa28e23acc1ee8255">yyjson_val::tag</a></div><div class="ttdeci">uint64_t tag</div><div class="ttdef"><b>Definition:</b> yyjson.h:4515</div></div>
<div class="ttc" id="ayyjson_8h_html_structyyjson__val"><div class="ttname"><a href="yyjson_8h.html#structyyjson__val">yyjson_val</a></div><div class="ttdef"><b>Definition:</b> yyjson.h:4514</div></div>
</div><!-- fragment --><p> <img src="struct_ival.svg" alt="" style="pointer-events: none;" class="inline" title="yyjson_val"/> </p>
<p >The type of the value is stored in the lower 8 bits of the <code>tag</code>.<br />
The size of the value, such as string length, object size, or array size, is stored in the higher 56 bits of the <code>tag</code>.</p>
<p >Modern 64-bit processors are typically limited to supporting fewer than 64 bits for RAM addresses (<a href="https://en.wikipedia.org/wiki/RAM_limit">Wikipedia</a>). For example, Intel64, AMD64, and ARMv8 have a 52-bit (4PB) physical address limit. Therefore, it is safe to store the type and size information within the 64-bit <code>tag</code>.</p>
<h1><a class="anchor" id="autotoc_md84"></a>
Immutable Document</h1>
<p >A JSON document stores all strings in a <b>contiguous</b> memory area.<br />
Each string is unescaped in-place and ended with a null-terminator.<br />
For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_idoc1.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_doc</div></div>
<p >A JSON document stores all values in another <b>contiguous</b> memory area.<br />
The <code>object</code> and <code>array</code> containers store their own memory usage, allowing easy traversal of the child values.<br />
For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_idoc2.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_doc</div></div>
<hr />
<h1><a class="anchor" id="autotoc_md86"></a>
Mutable Value</h1>
<p >Each mutable JSON value is stored in an <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code> struct: </p><div class="fragment"><div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a> {</div>
<div class="line"> uint64_t <a class="code hl_variable" href="yyjson_8h.html#a5fd1ae5bada624c9687acce330eef7aa">tag</a>;</div>
<div class="line"> <span class="keyword">union </span>{</div>
<div class="line"> uint64_t u64;</div>
<div class="line"> int64_t i64;</div>
<div class="line"> <span class="keywordtype">double</span> f64;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *str;</div>
<div class="line"> <span class="keywordtype">void</span> *ptr;</div>
<div class="line"> <span class="keywordtype">size_t</span> ofs;</div>
<div class="line"> } <a class="code hl_variable" href="yyjson_8h.html#a2f30e3958bf136b4e8453a0e78b43d0f">uni</a>;</div>
<div class="line"> <a class="code hl_struct" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a> *<a class="code hl_variable" href="yyjson_8h.html#a172090776a18e45190c933fb3294c07c">next</a>;</div>
<div class="line">}</div>
<div class="ttc" id="ayyjson_8h_html_a172090776a18e45190c933fb3294c07c"><div class="ttname"><a href="yyjson_8h.html#a172090776a18e45190c933fb3294c07c">yyjson_mut_val::next</a></div><div class="ttdeci">yyjson_mut_val * next</div><div class="ttdef"><b>Definition:</b> yyjson.h:5284</div></div>
<div class="ttc" id="ayyjson_8h_html_a2f30e3958bf136b4e8453a0e78b43d0f"><div class="ttname"><a href="yyjson_8h.html#a2f30e3958bf136b4e8453a0e78b43d0f">yyjson_mut_val::uni</a></div><div class="ttdeci">yyjson_val_uni uni</div><div class="ttdef"><b>Definition:</b> yyjson.h:5283</div></div>
<div class="ttc" id="ayyjson_8h_html_a5fd1ae5bada624c9687acce330eef7aa"><div class="ttname"><a href="yyjson_8h.html#a5fd1ae5bada624c9687acce330eef7aa">yyjson_mut_val::tag</a></div><div class="ttdeci">uint64_t tag</div><div class="ttdef"><b>Definition:</b> yyjson.h:5282</div></div>
<div class="ttc" id="ayyjson_8h_html_structyyjson__mut__val"><div class="ttname"><a href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></div><div class="ttdef"><b>Definition:</b> yyjson.h:5281</div></div>
</div><!-- fragment --><p> <img src="struct_mval.svg" alt="" style="pointer-events: none;" class="inline" title="yyjson_mut_val"/> </p>
<p >The <code>tag</code> and <code>uni</code> fields are the same as the immutable value, and the <code>next</code> field is used to build a linked list.</p>
<h1><a class="anchor" id="autotoc_md87"></a>
Mutable Document</h1>
<p >A mutable JSON document is composed of multiple <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code>.</p>
<p >The child values of an <code>object</code> or <code>array</code> are linked as a cycle,<br />
the parent holds the <b>tail</b> of the circular linked list, enabling yyjson to perform operations <code>append</code>, <code>prepend</code> and <code>remove_first</code> in constant time.</p>
<p >For example:</p>
<div class="image">
<object type="image/svg+xml" data="struct_mdoc.svg" style="pointer-events: none;"></object>
<div class="caption">
yyjson_mut_doc</div></div>
<hr />
<h1><a class="anchor" id="autotoc_md89"></a>
Memory Management</h1>
<p >A JSON document (<code><a class="el" href="yyjson_8h.html#structyyjson__doc">yyjson_doc</a></code>, <code><a class="el" href="yyjson_8h.html#structyyjson__mut__doc">yyjson_mut_doc</a></code>) is responsible for managing the memory of all its JSON values and strings. When a document it is no longer needed, it is important for the user to call <code><a class="el" href="yyjson_8h.html#adad98bd766cf52d99f2c54dcb120786d">yyjson_doc_free()</a></code> or <code><a class="el" href="yyjson_8h.html#a7a5f504993031f912d06777b8a7b5aff">yyjson_mut_doc_free()</a></code> to free the memory associated with it.</p>
<p >A JSON value (<code><a class="el" href="yyjson_8h.html#structyyjson__val">yyjson_val</a></code>, <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code>) has the same lifetime as its document. The memory is managed by its document and and cannot be freed independently.</p>
<p >For more information, refer to the <a class="el" href="md_doc__a_p_i.html">API documentation</a>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.4-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Documentation for <a href="https://github.com/ibireme/yyjson" target="_blank">yyjson</a>, generated by <a href="https://www.doxygen.org/index.html" target="_blank">doxygen</a> 1.9.4 </li>
</ul>
</div>
</body>
</html>
