



  

json 0.1.0 documentation

 [json](index.html#document-index) 

 stable

 

Getting Started:

* [Features](index.html#document-features)

* [Build json](index.html#document-build)

	+ [Unix (Autotools):](index.html#unix-autotools)

	+ [Windows (MSBuild):](index.html#windows-msbuild)

	+ [Documentation (Sphinx):](index.html#documentation-sphinx)

* [Getting Started](index.html#document-getting_started)

	+ [Allocations:](index.html#allocations)

	+ [Design and Data Structure:](index.html#design-and-data-structure)

API:

* [API documentation](index.html#document-api)

	+ [parse json](index.html#document-json)

	+ [utils / helpers](index.html#document-util)

	+ [print](index.html#document-print)

[json](index.html#document-index)

* [Docs](index.html#document-index) »

* json 0.1.0 documentation

* [Edit on GitHub](https://github.com/recp/json/blob/2d4b48ae623f1954176422555ac5053e7f4497d5/docs/source/index.rst)

---

json Documentation[¶](#json-documentation "Permalink to this headline")

=======================================================================

**json** is lighweight JSON parser written in C99 (compatible with C89).

Features[¶](#features "Permalink to this headline")

---------------------------------------------------

* header-only or optional compiled library

* option to store members and arrays as reverse order or normal

* doesn’t alloc memory for keys and values only for tokens

* creates DOM-like data structure to make it easy to iterate though

* simple api

* provides some util functions to print json, get int32, int64, float, double…

* very small library

* and other…

Build json[¶](#build-json "Permalink to this headline")

-------------------------------------------------------

**json** library does not have external dependencies.

**NOTE:**

If you only need to inline versions, you don’t need to build **json**, you don’t need to link it to your program.

Just import cglm to your project as dependency / external lib by copy-paste then use it as usual

### Unix (Autotools):[¶](#unix-autotools "Permalink to this headline")

|  |  |

| --- | --- |

| 

```

1

2

3

4

5

```

 | 

```

$ sh autogen.sh

$ ./configure

$ make

$ make check            # run tests (optional)

$ [sudo] make install   # install to system (optional)

```

 |

**make** will build json to **.libs** sub folder in project folder.

If you don’t want to install **json** to your system’s folder you can get static and dynamic libs in this folder.

### Windows (MSBuild):[¶](#windows-msbuild "Permalink to this headline")

Windows related build files, project files are located in win folder,

make sure you are inside in json/win folder.

Code Analysis are enabled, it may take awhile to build.

|  |  |

| --- | --- |

| 

```

1

2

```

 | 

```

$ cd win

$ .\build.bat

```

 |

if *msbuild* is not worked (because of multi versions of Visual Studio)

then try to build with *devenv*:

|  |  |

| --- | --- |

| 

```

1

```

 | 

```

$ devenv json.sln /Build Release

```

 |

Currently tests are not available on Windows.

### Documentation (Sphinx):[¶](#documentation-sphinx "Permalink to this headline")

**json** uses sphinx framework for documentation, it allows lot of formats for documentation. To see all options see sphinx build page:

<https://www.sphinx-doc.org/en/master/man/sphinx-build.html>

Example build:

|  |  |

| --- | --- |

| 

```

1

2

3

4

5

6

7

```

 | 

```

$ cd json/docs

$ sphinx-build source build

or

$ cd json/docs

$ sh ./build-docs.sh

```

 |

Getting Started[¶](#getting-started "Permalink to this headline")

-----------------------------------------------------------------

**json** uses **json\_** prefix for all functions e.g. json\_parse().

There are only a few types which represents json document, json object, json array and json value (as string).

* **json\_doc\_t** represents JSON document. It stores root JSON node and allocated memory.

* **json\_t** represents JSON object. Arrays also are json object.

* **json\_array\_t** represents JSON array. It inherits **json\_t**, so you can cast array to json object.

* **json\_type\_t** represents JSON type.

### Allocations:[¶](#allocations "Permalink to this headline")

*json* doesn’t alloc any memory for JSON contents, keys and values…

It ONLY allocs memory for DOM-tree (json tokens), that’s it.

It creates pointers to actual data, so you must retain JSON data until you have finished to process json.

After you finished to parse JSON, this is the order that you must use to free-ing things:

1. free original JSON data

2. free json\_doc

actually the order doesn’t matter but you must free the json doc which is returned from json\_parse().

### Design and Data Structure:[¶](#design-and-data-structure "Permalink to this headline")

**json** creates a TREE to traverse JSON. Every json object’s child node has **key** pointer. A value of **json\_t** may be one of these:

* Child node

* String contents

you must use **type** member of json object to identify the value type.

If you need to integer, float or boolean values, then you can use util functions to get these values.

These functions will be failed if the value is not string.

**VERY IMPORTANT:**

**key** and **value** ARE JUST POINTERS to original data.

Because of this, you will see that json object has **keySize** and **valueSize** members.

When comparing two keys, you must use *keySize*. Instead of *strcmp()* you could use *strncmp()* and its friends, because it has *size* parameter which is our *keySize*

You can also use built-in helper to compare two keys: **json\_key\_eq()**

Also when copying values you must also use *valueSize*. You could use *json\_string\_dup()* to duplicate strings. It is better to not copy contents as possible as much.

**UTILITIES / HELPERS:**

json library also provides some inline utiliy functions to make things easier while handling json data.

API documentation[¶](#api-documentation "Permalink to this headline")

---------------------------------------------------------------------

### parse json[¶](#parse-json "Permalink to this headline")

Header: json/json.h

#### JSON Document[¶](#json-document "Permalink to this headline")

JSON document is returned when parsing json contents is done. This object stores

root JSON object and allocated memories.

It creates pointers to actual data, so you must retain JSON data until you have finished to process json.

You After you processed the parsed JSON, then you must free this document.

#### Table of contents (click to go):[¶](#table-of-contents-click-to-go "Permalink to this headline")

Functions:

1. [`json\_parse()`](#c.json_parse "json_parse")

2. [`json\_free()`](#c.json_free "json_free")

3. [`json\_get()`](#c.json_get "json_get")

4. [`json\_array()`](#c.json_array "json_array")

#### Functions documentation[¶](#functions-documentation "Permalink to this headline")

json\_doc\_t\* `json_parse`(const char \* \_\_restrict*contents*)[¶](#c.json_parse "Permalink to this definition")

parse json string

this function parses JSON string and retuns a document which contains:

* JSON object

* allocated memory

after JSON is processed, the object must be freed with json\_free()

this library doesn’t alloc any memory for JSON itsef and doesn’t copy JSON

contents into a data structure. It only allocs memory for tokens.

So don’t free ‘contents’ parameter until you finished to process JSON.

Desired order:

1. Read JSON file

2. Pass the contents to json\_parse()

3. Process/Handle JSON

4. free JSON document with json\_free()

5. free contents

Parameters:

*[in]* **contents** JSON string

Returns:

json document which contains json object as root object

void `json_free`(json\_doc\_t \* \_\_restrict*jsondoc*)[¶](#c.json_free "Permalink to this definition")

frees json document and its allocated memory

Parameters:

*[in]* **jsondoc** JSON document

const json\_t\* `json_get`(const json\_t \* \_\_restrict*object*, const char \* \_\_restrict*key*)[¶](#c.json_get "Permalink to this definition")

gets value for key

You should only use this for DEBUG or if you only need to only specific key.

Desired usage is iterative way:

> 

> You must iterate through json’s next and value links.

Parameters:

*[in]* **object** json object

*[in]* **key** key to find value

Returns:

value found for the key or NULL

const json\_array\_t\* `json_array`(const json\_t \* \_\_restrict*object*)[¶](#c.json_array "Permalink to this definition")

contenient function to cast object’s child/value to array

Parameters:

*[in]* **object** json object

Returns:

json array or NULL

### utils / helpers[¶](#utils-helpers "Permalink to this headline")

Header: json/util.h

Inline helpers to make things easier while process JSON.

Most of uitl functions expects default value, so if it fails to convert string to a number or boolean then that default value will be returned.

#### Table of contents (click to go):[¶](#table-of-contents-click-to-go "Permalink to this headline")

Functions:

1. [`json\_int32()`](#c.json_int32 "json_int32")

2. [`json\_uint32()`](#c.json_uint32 "json_uint32")

3. [`json\_int64()`](#c.json_int64 "json_int64")

4. [`json\_uint64()`](#c.json_uint64 "json_uint64")

5. [`json\_float()`](#c.json_float "json_float")

6. [`json\_double()`](#c.json_double "json_double")

7. [`json\_bool()`](#c.json_bool "json_bool")

8. [`json\_string()`](#c.json_string "json_string")

9. [`json\_string\_dup()`](#c.json_string_dup "json_string_dup")

10. [`json\_key\_eq()`](#c.json_key_eq "json_key_eq")

#### Functions documentation[¶](#functions-documentation "Permalink to this headline")

int32\_t `json_int32`(const json\_t \* \_\_restrict*object*, int32\_t*defaultValue*)[¶](#c.json_int32 "Permalink to this definition")

creates number (int32) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

uint32\_t `json_uint32`(const json\_t \* \_\_restrict*object*, uint32\_t*defaultValue*)[¶](#c.json_uint32 "Permalink to this definition")

creates number (uint32) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

int64\_t `json_int64`(const json\_t \* \_\_restrict*object*, int64\_t*defaultValue*)[¶](#c.json_int64 "Permalink to this definition")

creates number (int64) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

int64\_t `json_uint64`(const json\_t \* \_\_restrict*object*, uint64\_t*defaultValue*)[¶](#c.json_uint64 "Permalink to this definition")

creates number (uint64) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

float `json_float`(const json\_t \* \_\_restrict*object*, float*defaultValue*)[¶](#c.json_float "Permalink to this definition")

creates number (float) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

double `json_double`(const json\_t \* \_\_restrict*object*, double*defaultValue*)[¶](#c.json_double "Permalink to this definition")

creates number (double) from string value

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

number

int `json_bool`(const json\_t \* \_\_restrict*object*, int*defaultValue*)[¶](#c.json_bool "Permalink to this definition")

creates boolean from string value

it returns integer to separate default value from true or false

Parameters:

*[in]* **object** json object

*[in]* **defaultValue** default value if operation fails

Returns:

boolean values as integer: 1 true, 0 false, error: defaultValue

const char\* `json_string`(const json\_t \* \_\_restrict*object*)[¶](#c.json_string "Permalink to this definition")

return non-NULL terminated string value

you must use object->valSize to copy, compare … string

Parameters:

*[in]* **object** json object

Returns:

non-NULL terminated string value (pointer only)

char\* `json_string_dup`(const json\_t \* \_\_restrict*object*)[¶](#c.json_string_dup "Permalink to this definition")

return non-NULL terminated string value

you must use object->valSize to copy, compare … string

Parameters:

*[in]* **object** json object

Returns:

NULL terminated duplicated string value

bool `json_key_eq`(const json\_t \* \_\_restrict*obj*, const char \* \_\_restrict*str*)[¶](#c.json_key_eq "Permalink to this definition")

compares json key with a string|

Parameters:

*[in]* **obj** json object

*[in]* **str** string to compare

Returns:

true if str is equals to json’s key

### print[¶](#print "Permalink to this headline")

Header: json/print.h

Print functions

#### Table of contents (click to go):[¶](#table-of-contents-click-to-go "Permalink to this headline")

Functions:

1. [`json\_print()`](#c.json_print "json_print")

2. [`json\_print\_pad()`](#c.json_print_pad "json_print_pad")

#### Functions documentation[¶](#functions-documentation "Permalink to this headline")

void `json_print`(const json\_t \* \_\_restrict*json*)[¶](#c.json_print "Permalink to this definition")

print json

Parameters:

*[in]* **json** json object with title and zero padding

void `json_print_pad`(const json\_t \* \_\_restrict*json*, int*pad*)[¶](#c.json_print_pad "Permalink to this definition")

print json

Parameters:

*[in]* **json** json object

*[in]* **pad** padding

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

