API

この文書には、yyjsonライブラリのすべてのAPIの使い方と例を収録しています。

APIの設計

APIの接頭辞

公開関数と構造体にはすべてyyjson_の接頭辞が付き、定数にはすべてYYJSON_の接頭辞が付きます。

不変・可変データ用のAPI

ライブラリには、不変と可変の2種類のデータ構造があります。

	不変	可変
ドキュメント	yyjson_doc	yyjson_mut_doc
値	yyjson_val	yyjson_mut_val

JSONを読み込むと、yyjsonは不変のドキュメントと値を返します。
JSONを構築すると、yyjsonは可変のドキュメントと値を作ります。
ドキュメントは、自身に属するすべてのJSON値と文字列のメモリを保持します。

不変データ用APIの大半は、yyjson_の後にmutを加えるだけで可変データ用の版になります。次に例を示します。

char *yyjson_write(yyjson_doc *doc, ...);
char *yyjson_mut_write(yyjson_mut_doc *doc, ...);

bool yyjson_is_str(const yyjson_val *val);
bool yyjson_mut_is_str(const yyjson_mut_val *val);

ライブラリは、不変と可変の間で値を変換する関数も提供しています。

// doc -> mut_doc
yyjson_mut_doc *yyjson_doc_mut_copy(const yyjson_doc *doc, ...);
// val -> mut_val
yyjson_mut_val *yyjson_val_mut_copy(const yyjson_val *val, ...);

// mut_doc -> doc
yyjson_doc *yyjson_mut_doc_imut_copy(const yyjson_mut_doc *doc, ...);
// mut_val -> val
yyjson_doc *yyjson_mut_val_imut_copy(const yyjson_mut_val *val, ...);

文字列用のAPI

ライブラリは、NUL終端（\0）のある文字列とない文字列の両方に対応します。
NUL終端のない文字列を使う場合や、文字列の長さが明確に分かっている場合は、末尾がnの関数を使えます。次に例を示します。

// null-terminator is required
bool yyjson_equals_str(const yyjson_val *val, const char *str);
// null-terminator is optional
bool yyjson_equals_strn(const yyjson_val *val, const char *str, size_t len);

JSONの作成時、yyjsonは性能を高めるために文字列を定数として扱います。ただし、文字列を後で変更する場合は、cpyを含む関数でドキュメントに文字列をコピーする必要があります。次に例を示します。

// reference only, null-terminated is required
yyjson_mut_val *yyjson_mut_str(yyjson_mut_doc *doc, const char *str);
// reference only, null-terminator is optional
yyjson_mut_val *yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len);

// copied, null-terminated is required
yyjson_mut_val *yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str);
// copied, null-terminator is optional
yyjson_mut_val *yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len);