Revision 5b94fd2c12712e04345d4b130358afbb352f6436 authored by vthierry on 28 October 2025, 18:54:37 UTC, committed by vthierry on 28 October 2025, 18:54:37 UTC
1 parent 4ad30c1
Value.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Value - Documentation</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
<script src="scripts/nav.js" defer></script>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
<div class="navicon"></div>
</label>
<label for="nav-trigger" class="overlay"></label>
<nav >
<input type="text" id="nav-search" placeholder="Search" />
<h2><a href="index.html">Home</a></h2><h3>Objects</h3><ul><li><a href="FValue.html">FValue</a><ul class='members'></ul><ul class='methods'><li data-type='method' style='display: none;'><a href="FValue.html#set">set</a></li></ul></li><li><a href="LValue.html">LValue</a><ul class='members'></ul><ul class='methods'><li data-type='method' style='display: none;'><a href="LValue.html#getTurtoise">getTurtoise</a></li><li data-type='method' style='display: none;'><a href="LValue.html#setTurtoise">setTurtoise</a></li><li data-type='method' style='display: none;'><a href="LValue.html#deduce">deduce</a></li><li data-type='method' style='display: none;'><a href="LValue.html#.readTriples">readTriples</a></li></ul></li><li><a href="Value.html">Value</a><ul class='members'><li data-type='member' style='display: none;'><a href="Value.html#.EMPTY">EMPTY</a></li></ul><ul class='methods'><li data-type='method' style='display: none;'><a href="Value.html#asString">asString</a></li><li data-type='method' style='display: none;'><a href="Value.html#isEmpty">isEmpty</a></li><li data-type='method' style='display: none;'><a href="Value.html#isRecord">isRecord</a></li><li data-type='method' style='display: none;'><a href="Value.html#isArray">isArray</a></li><li data-type='method' style='display: none;'><a href="Value.html#isMember">isMember</a></li><li data-type='method' style='display: none;'><a href="Value.html#length">length</a></li><li data-type='method' style='display: none;'><a href="Value.html#count">count</a></li><li data-type='method' style='display: none;'><a href="Value.html#getNames">getNames</a></li><li data-type='method' style='display: none;'><a href="Value.html#size">size</a></li><li data-type='method' style='display: none;'><a href="Value.html#get">get</a></li><li data-type='method' style='display: none;'><a href="Value.html#at">at</a></li><li data-type='method' style='display: none;'><a href="Value.html#aget">aget</a></li><li data-type='method' style='display: none;'><a href="Value.html#set">set</a></li><li data-type='method' style='display: none;'><a href="Value.html#add">add</a></li><li data-type='method' style='display: none;'><a href="Value.html#copy">copy</a></li><li data-type='method' style='display: none;'><a href="Value.html#erase">erase</a></li><li data-type='method' style='display: none;'><a href="Value.html#rename">rename</a></li><li data-type='method' style='display: none;'><a href="Value.html#clear">clear</a></li><li data-type='method' style='display: none;'><a href="Value.html#sort">sort</a></li><li data-type='method' style='display: none;'><a href="Value.html#sortNames">sortNames</a></li><li data-type='method' style='display: none;'><a href="Value.html#equals">equals</a></li></ul></li><li><a href="WJSONReader.html">WJSONReader</a><ul class='members'></ul><ul class='methods'><li data-type='method' style='display: none;'><a href="WJSONReader.html#.read">read</a></li></ul></li><li><a href="WJSONWriter.html">WJSONWriter</a><ul class='members'></ul><ul class='methods'><li data-type='method' style='display: none;'><a href="WJSONWriter.html#.write">write</a></li></ul></li><li><a href="wJSON.html">wJSON</a><ul class='methods'><li data-type='method' style='display: none;'><a href="wJSON.html#.parse">parse</a></li><li data-type='method' style='display: none;'><a href="wJSON.html#.stringify">stringify</a></li><li data-type='method' style='display: none;'><a href="wJSON.html#.wjson2json">wjson2json</a></li><li data-type='method' style='display: none;'><a href="wJSON.html#.wjson2wjson">wjson2wjson</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#quote">quote</a></li><li><a href="global.html#string2json">string2json</a></li><li><a href="global.html#array2vector">array2vector</a></li><li><a href="global.html#run_protege">run_protege</a></li><li><a href="global.html#ttl2n3">ttl2n3</a></li><li><a href="global.html#wjson2html">wjson2html</a></li><li><a href="global.html#wjson2json">wjson2json</a></li><li><a href="global.html#wjson2wjson">wjson2wjson</a></li></ul>
</nav>
<div id="main">
<h1 class="page-title">Value</h1>
<section>
<header>
<h2>
Value
</h2>
</header>
<article>
<div class="container-overview">
<h4 class="name" id="Value"><span class="type-signature"></span>new Value<span class="signature">(value<span class="signature-attributes">opt</span>, parse<span class="signature-attributes">opt</span>, sort_names<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Implements a minimal C/C++ <a href="https://www.json.org">JSON</a> data structure with weak-syntax reader/writer.</p>
<ul>
<li>Such a value is either
<ul>
<li>an atomic string
<ul>
<li>including string parsable as numeric or boolean value, or</li>
</ul>
</li>
<li>a <a href="https://en.wikipedia.org/wiki/Record_%28computer_science%29">record</a>, i.e., a recursive construct of,
<ul>
<li>an unordered set of value accessed by label, while</li>
<li>an array is a record {\tt { 0: a 1: b ...}} indexed by consecutive non negative integer.</li>
</ul>
</li>
</ul>
</li>
<li>Value functions
<ul>
<li>Element access:
<ul>
<li><a href="#isMember"><code>value.isMember(name)</code></a> allows to check if a value is defined,</li>
<li><a href="#at"><code>value.at(name)</code></a> allows to access a value as a record,
<ul>
<li>the at()` is virtual, i.e, can be overloaded allowing to define non-memorized dynamic calculated values.</li>
</ul>
</li>
<li><a href="#get"><code>value.get(name, default_typed_value)</code></a> allows to access an atomic value.</li>
</ul>
</li>
<li>Modifiers:
<ul>
<li><a href="#set"><code>value.set(name, value)</code></a> allows to write a value,</li>
<li><a href="#erase"><code>value.erase(name)</code></a> allows to erase a value,</li>
<li><a href="#clear"><code>value.clear()</code></a> allows to empty the value.</li>
</ul>
</li>
<li>Capacity and property:
<ul>
<li><a href="#isEmpty"><code>value.isEmpty()</code></a> allows to check if the value is empty,</li>
<li><a href="#isRecord"><code>value.isRecord()</code></a> allows to check if the value is a record,</li>
<li><a href="#isArray"><code>value.isArray()</code></a> allows to check if the value is an array,</li>
<li><a href="#getNames"><code>value.getNames()</code></a> returns all the record field names, allowing to iterate on the fields,</li>
<li><a href="#size"><code>value.size()</code></a> returns the number of records,</li>
<li><a href="#length"><code>value.length()</code></a> returns the length of the value as an array, allowing to iterate on the array elements.</li>
</ul>
</li>
<li>Other operations:
<ul>
<li><a href="#asString"><code>value.asString()</code></a> returns this value as a string,</li>
<li><a href="#equal"><code>value.equal(another_value)</code></a> checks if two values are equal,</li>
<li><a href="#sortNames"><code>value.sortNames()</code></a> allows to sort the record field names in alphabetic order,</li>
<li><a href="#sort"><code>value.sort(before)</code></a> allows to sort an array,</li>
</ul>
</li>
</ul>
</li>
<li>Note: The Value is equipped with a equal and less operators and a hash function in order to be used in containers such as <code>std::unordered_map<wjson::Value, T></code> or <code>std::map<wjson::Value, T></code>; however in the latter case the order is simply the lexical order of the string representation which is likely semantically biased. A correct semantic order depends on the data type as defined in the <a href="https://line.gitlabpages.inria.fr/aide-group/symboling/Type.html">symboling package</a>.</li>
<li>Note: <code>JSON</code> is a read-only reference, i.e. an alias of <code>const wjson::Value&</code> for readability convenience.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">bool</span>
|
<span class="param-type">int</span>
|
<span class="param-type">uint</span>
|
<span class="param-type">double</span>
|
<span class="param-type">float</span>
|
<span class="param-type">JSON</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last"><p>The initial value.</p></td>
</tr>
<tr>
<td class="name"><code>parse</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>For a string value, if true parses the string, else only copy it.</p></td>
</tr>
<tr>
<td class="name"><code>sort_names</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>For a parsed string value, if true sorts the names in alphabetic order, as performed by sortNames().</p>
<p><strong>Note</strong>: The <a href="https://gitlab.inria.fr/line/aide-group/wjson/-/raw/master/src/cpp2wjson.tpp">ccp2wjson</a> factory defines a wrapper between C++ and wjson data structures.</p></td>
</tr>
</tbody>
</table>
</div>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id=".EMPTY"><span class="type-signature type-signature-static">(static) </span>EMPTY<span class="type-signature"> :<a href="Value.html">Value</a></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>The <code>wjson::Value::EMPTY</code> is a generic read-only empty value.</p></li></ul></dd>
</dl>
<div class="description usertext">
<p>The <code>wjson::Value::EMPTY</code> is a generic read-only empty value.</p>
</div>
<h5 class="h5-types">Type:</h5>
<ul>
<li>
<span class="param-type"><a href="Value.html">Value</a></span>
</li>
</ul>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="asString"><span class="type-signature"></span>asString<span class="signature">(pretty<span class="signature-attributes">opt</span>, strict<span class="signature-attributes">opt</span>, fast<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {string}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the data structure as a string.</p>
<ul>
<li>This allows to check if two data structures are equal for the modified semantic:
<ul>
<li>Two literal values are equal if and only the literal string value <code>asString()</code> are equal, see equals().</li>
<li>Two data structures are equal if and only each item are inserted in the same order and equal.</li>
</ul>
</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>pretty</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>If true properly format in 2D, else returns a minimal raw format.</p></td>
</tr>
<tr>
<td class="name"><code>strict</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>If true <a href="https://www.json.org/json-en.html">strict JSON</a> syntax, else produces a <a href="./wJSON.html#.parse">weak JSON</a> syntax.</p></td>
</tr>
<tr>
<td class="name"><code>fast</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>If fast serializes the data as fast as possible (quoting all words without any lexical analysis).</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The value as a string.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
</dd>
</dl>
<h4 class="name" id="isEmpty"><span class="type-signature"></span>isEmpty<span class="signature">()</span><span class="type-signature"> → {bool}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns true if this structure is empty, i.e., without any field not literal value.</p>
<ul>
<li>As a literal, the empty value casts to the empty string <code>""</code>, the boolean <code>false</code> value, the integral number <code>0</code>, or the floating point number <code>NAN</code>.</li>
<li>An empty record corresponds to parsing <code>{}</code> and an empty array to parsing <code>[]</code>.</li>
<li>The <code>clear()</code> methods allows to clear all value content.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The check result.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">bool</span>
</dd>
</dl>
<h4 class="name" id="isRecord"><span class="type-signature"></span>isRecord<span class="signature">()</span><span class="type-signature"> → {bool}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns true if this structure is a non empty record, false otherwise.</p>
<ul>
<li>A value is a record as soon as a field as been defined using the subscript <code>[]</code> operator.</li>
<li>By contract an array corresponds to a record with numerical keys. It is thus a record.</li>
<li>An object is atomic if and only if it is not a record.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The check result.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">bool</span>
</dd>
</dl>
<h4 class="name" id="isArray"><span class="type-signature"></span>isArray<span class="signature">()</span><span class="type-signature"> → {bool}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns true if this structure is an array, false otherwise.</p></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>Returns true if it is a record with only consecutive non negative integral numerical keys of syntax <code>(0|[1-9][0-9]*)</code>.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">bool</span>
</dd>
</dl>
<h4 class="name" id="isMember"><span class="type-signature"></span>isMember<span class="signature">(name)</span><span class="type-signature"> → {bool}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns true if this structure has the given field defined, false otherwise.</p></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">uint</span>
</td>
<td class="description last"><p>The field key name or numerical index.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>Returns true of defined.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">bool</span>
</dd>
</dl>
<h4 class="name" id="length"><span class="type-signature"></span>length<span class="signature">()</span><span class="type-signature"> → {uint}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the number of numerically indexed fields.</p>
<ul>
<li>The size of the record, i.e., the number of fields is returned by <code>size()</code>.</li>
</ul>
<pre class="prettyprint source"><code>// Given a Value array the indexed field iterator writes:
for(unsigned int i = 0; i < value.length(); i++) {
const Value& field_value = value.at(i);
Value& field_value = value[i];
../..
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The numerical indexed field count.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">uint</span>
</dd>
</dl>
<h4 class="name" id="count"><span class="type-signature"></span>count<span class="signature">()</span><span class="type-signature"> → {uint}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the number of all attributes of the value and sub-values.</p></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The numerical indexed field count.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">uint</span>
</dd>
</dl>
<h4 class="name" id="getNames"><span class="type-signature"></span>getNames<span class="signature">()</span><span class="type-signature"> → {Array.<string>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the field names in the insertion order.</p>
<pre class="prettyprint source"><code>// Given a Value record the structure field names iterator writes:
for(auto it = value.getNames().cbegin(); it != value.getNames().cend(); ++it) {
std::string field_name = *it;
const Value& field_value = value.at(field_name);
Value& field_value = value[field_name];
../..
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>A <code>std::vector<std::string></code> with the field key names or index in insertion order.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">Array.<string></span>
</dd>
</dl>
<h4 class="name" id="size"><span class="type-signature"></span>size<span class="signature">()</span><span class="type-signature"> → {uint}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the number of fields with either literal or numerical index.</p>
<ul>
<li>If the record is an array, its length, i.e., the number of fields with numerical indexes is returned by <code>length()</code>.</li>
<li>This is a simple shortcut for ``getNames().size()`.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The numerical indexed field count.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">uint</span>
</dd>
</dl>
<h4 class="name" id="get"><span class="type-signature"></span>get<span class="signature">(name<span class="signature-attributes">opt</span>, default_value)</span><span class="type-signature"> → {string|bool|int|double|double|float|char|<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns the literal value of a given field of this structure.</p>
<pre class="prettyprint source"><code> wjson::Value value("{ number: 3.1416, no: FaLsE }", true);
double v1 = value.get("number", NAN); // Returns 3.1416 up to the machine precision, since the value is parsable as a double.
double v2 = value.get("no", NAN); // Returns the default value NAN, since the value is not parsable as a double.
float v3 = value.get("number", 0.0f); // Returns 3.1416 up to the machine precision, since the value is parsable as a float.
float v4 = value.get("no", 0.0f); // Returns 0.0, since the value is not parsable as a float.
int v5 = value.get("number", 0); // Returns 3 since the value is numerically parsable and rounds to the integer value 3.
bool v6 = value.get("no", true); // Returns false since the value parses as a boolean.
bool v7 = value.get("number", true); // Returns the default value true since the value is not parsable as a boolean.
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">uint</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"><p>The field key name or numerical index.</p>
<ul>
<li>If the field key is omitted, returns the literal value of this value.</li>
</ul></td>
</tr>
<tr>
<td class="name"><code>default_value</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">bool</span>
|
<span class="param-type">int</span>
|
<span class="param-type">uint</span>
|
<span class="param-type">double</span>
|
<span class="param-type">float</span>
|
<span class="param-type">char</span>
|
<span class="param-type"><a href="Value.html">Value</a></span>
</td>
<td class="attributes">
</td>
<td class="description last"><p>A default value, defining also the field type.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The value with the type corresponding to the default value.</p>
<ul>
<li>If the field is undefined, unparsable or out of range, the default value is returned.</li>
<li>A numeric value is parsed as a double and rounded if returned as an integer.</li>
<li>If the type is <code>bool</code> the string is converted to lower-case and valid if equal to "true" or "false".</li>
<li>If the type is <code>char</code> the first char of the string value is considered.</li>
</ul>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
|
<span class="param-type">bool</span>
|
<span class="param-type">int</span>
|
<span class="param-type">double</span>
|
<span class="param-type">double</span>
|
<span class="param-type">float</span>
|
<span class="param-type">char</span>
|
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="at"><span class="type-signature"></span>at<span class="signature">(name)</span><span class="type-signature"> → {<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns a given field of this structure.</p>
<pre class="prettyprint source"><code> Value value = jsonValue.at(name_or_index); // Allows to get a read-only version of a field value.
Value value = jsonValue[name_or_index]; // Allows to get a field value, and create if not yet defined.
</code></pre>
<ul>
<li>This method is virtual, it thus can be overloaded to define non-memorized dynamic calculated values.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">uint</span>
</td>
<td class="description last"><p>The field key name or numerical index.</p>
<ul>
<li>The recursive construct <code>field-name/sub-field-name</code> allows to directly access sub-field values.
<ul>
<li>Name of the form of an URL, e.g., <code>http://...</code> are escaped, because:
<ul>
<li>The <code>//</code> or <code>:/</code> patterns are escaped.</li>
<li>The <code>/</code> char at the first or last location is escaped.</li>
</ul>
</li>
</ul>
</li>
</ul></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The field value as a read-only structured value. If undefined, returns an empty data structure.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="aget"><span class="type-signature"></span>aget<span class="signature">(id, value)</span><span class="type-signature"> → {<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns an indexed record in a array.</p>
<ul>
<li>In an array of the form <code>[ { id: value ... } ... ]</code> returns the first record which id has the given value.</li>
<li>If such a record does not exist appends it. Thus, if not an array inserts the <code>{ id: value ... }</code> at index 0.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>id</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The identificator name.</p></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type"><a href="Value.html">Value</a></span>
</td>
<td class="description last"><p>The value to equa.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>The record which id has the given value.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="set"><span class="type-signature"></span>set<span class="signature">(name, value)</span><span class="type-signature"> → {<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Sets a given field of this structure.</p>
<ul>
<li>Setting a value:</li>
</ul>
<pre class="prettyprint source"><code> jsonValue.set(name_or_index, value); // Allows to set a non-empty field value.
jsonValue[name_or_index] = value; // Allows to set a non-empty or empty field value.
</code></pre>
<ul>
<li>Unsetting a value:
<ul>
<li>Note the semantic difference between the <code>set()</code> method and the <code>[]</code> operator</li>
</ul>
</li>
</ul>
<pre class="prettyprint source"><code> jsonValue.erase(name_or_index); // Allows to unset a field value.
jsonValue.set(name_or_index, EMPTY); // Allows to unset a field value.
jsonValue[name_or_index] = EMPTY; // Allows to explicitly set a field to the EMPTY value.
</code></pre>
<ul>
<li>Appending a value to an array:</li>
</ul>
<pre class="prettyprint source"><code> jsonValue[jsonValue.length()] = value; // Allows to append a field value to the jsonValue array.
jsonValue.add(value); // Allows to append a field value to the jsonValue array.
</code></pre>
<p>while the add() method allows also to insert/delete value in an array.
A construct of the following form allows to set a field value on a temporary clone of a read-only value, thus not modifying the value.</p>
<pre class="prettyprint source"><code> Value& otherValue = jsonValue.clone().set(name_or_index, value);
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">uint</span>
</td>
<td class="description last"><p>The field key name or numerical index.</p></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type"><a href="Value.html">Value</a></span>
</td>
<td class="description last"><p>The field value. The value is copied.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>A reference to this value, allowing to chain set methods:</p>
<pre class="prettyprint source"><code> value.set(name_or_index, value).set(another_name_or_index, another_value);
</code></pre>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="add"><span class="type-signature"></span>add<span class="signature">(index, value)</span><span class="type-signature"> → {<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Adds, inserts or deletes a value in this data structure viewed as a list.</p>
<ul>
<li>Setting a value:</li>
</ul>
<pre class="prettyprint source"><code> jsonValue.add(index, value); // Allows to insert a value at this index, shifting all sub-sequence values to the right.
jsonValue.add(index, EMPTY); // Allows to delete a value at this index, shifting all sub-sequence values to the left.
jsonValue.add(value); // Allows to append a value
</code></pre>
<p>A construct of the following form allows to set a field value on a temporary clone of a read-only value, thus not modifying the value.</p>
<pre class="prettyprint source"><code> Value& otherValue = jsonValue.clone().add(name_or_index, value);
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>index</code></td>
<td class="type">
<span class="param-type">uint</span>
</td>
<td class="description last"><p>The numerical index.</p></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type"><a href="Value.html">Value</a></span>
</td>
<td class="description last"><p>The field value. The value is copied.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>A reference to this value, allowing to chain set methods:</p>
<pre class="prettyprint source"><code> value.add(value).set(another_name_or_index, another_value);
</code></pre>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="copy"><span class="type-signature"></span>copy<span class="signature">(value)</span><span class="type-signature"> → {<a href="Value.html">Value</a>}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Copies all fields of a record or array.</p></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type"><a href="Value.html">Value</a></span>
</td>
<td class="description last"><p>The record or array field value. The value is copied.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>A reference to this value, allowing to chain set methods.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="Value.html">Value</a></span>
</dd>
</dl>
<h4 class="name" id="erase"><span class="type-signature"></span>erase<span class="signature">(name<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Erases a given field.</p>
<ul>
<li>When erased the corresponding value is an empty data structure.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">uint</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"><p>The field key name or numerical index.</p></td>
</tr>
</tbody>
</table>
<h4 class="name" id="rename"><span class="type-signature"></span>rename<span class="signature">(old_name, new_name)</span><span class="type-signature"> → {bool}</span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Renames a given field without changing the field order.</p></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>old_name</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The old field key name.</p></td>
</tr>
<tr>
<td class="name"><code>new_name</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The new field key name.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>True if the old name has been found, false otherwise.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">bool</span>
</dd>
</dl>
<h4 class="name" id="clear"><span class="type-signature"></span>clear<span class="signature">(preserveType<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Erases all fields and literal content of this value.</p></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>preserveType</code></td>
<td class="type">
<span class="param-type">bool</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><ul>
<li>If true a record becomes an empty record <code>{}</code> and an array an empty array <code>[]</code>.</li>
<li>Otherwise the object becomes atomic.</li>
</ul></td>
</tr>
</tbody>
</table>
<h4 class="name" id="sort"><span class="type-signature"></span>sort<span class="signature">(before)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Sorts the numerically indexed values according to the comparison function.</p>
<ul>
<li>Only applies on numerically indexed values: Key order, and named value are not affected.</li>
</ul>
<pre class="prettyprint source"><code>struct Before {
// Sorts in numerical order considering values as unsigned int
static bool before(JSON lhs, JSON rhs) {
return lhs.get(0u) < rhs.get(0u);
}
};
jsonValue.sort(Before::before);
</code></pre></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>before</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="description last"><p>A <code>static bool before(JSON lhs, JSON rhs)</code></p>
<ul>
<li>which returns <code>true</code> if the first argument is less than (i.e., is ordered before) the second.</li>
</ul></td>
</tr>
</tbody>
</table>
<h4 class="name" id="sortNames"><span class="type-signature"></span>sortNames<span class="signature">()</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Sorts the names and indexes in alphabetic order.</p>
<ul>
<li>This allows two values with the same field's value to be syntactically equal.</li>
<li>Numerical indexes are sorted in numerical order and non numerical indexes in alphabetic orders, and sorted after the numerical indexes.</li>
<li>This applies recursively on sub-values.</li>
</ul></li></ul></dd>
</dl>
<h4 class="name" id="equals"><span class="type-signature"></span>equals<span class="signature">(value)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-description">Description:</dt>
<dd class="tag-description"><ul class="dummy"><li><p>Returns true if this date equals the given value.</p>
<ul>
<li>Two literal values are equal if and only the literal string value are equal, see equals().</li>
<li>Also available using the <code>==</code> or <code>!=</code> operator syntax.</li>
</ul></li></ul></dd>
</dl>
<h5 class="h5-parameters">Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
</td>
<td class="description last"><p>The value to compare with.</p></td>
</tr>
</tbody>
</table>
<h5 class="h5-returns">Returns:</h5>
<div class="param-desc">
<p>True if both values are equal.</p>
</div>
</article>
</section>
</div>
<br class="clear">
<footer>
<div style='float: right;font-style: italic;'>2025-10-28 version.</div>
</footer>
<script>prettyPrint();</script>
<script src="scripts/polyfill.js"></script>
<script src="scripts/linenumber.js"></script>
<script src="scripts/search.js" defer></script>
<script src="scripts/collapse.js" defer></script>
</body>
</html>
Computing file changes ...
