Dictionary

Functions
LIBYANG_API_DECL LY_ERR	lydict_dup (const struct ly_ctx *ctx, const char *value, const char **str_p)
	Duplicate string in dictionary. Only a reference counter is incremented. More...
LIBYANG_API_DECL LY_ERR	lydict_insert (const struct ly_ctx *ctx, const char *value, size_t len, const char **str_p)
	Insert string into dictionary. If the string is already present, only a reference counter is incremented and no memory allocation is performed. More...
LIBYANG_API_DECL LY_ERR	lydict_insert_zc (const struct ly_ctx *ctx, char *value, const char **str_p)
	Insert string into dictionary - zerocopy version. If the string is already present, only a reference counter is incremented and no memory allocation is performed. This insert function variant avoids duplication of specified value - it is inserted into the dictionary directly. More...
LIBYANG_API_DECL LY_ERR	lydict_remove (const struct ly_ctx *ctx, const char *value)
	Remove specified string from the dictionary. It decrement reference counter for the string and if it is zero, the string itself is freed. More...

Detailed Description

Publicly visible functions and values of the libyang dictionary. They provide access to the strings stored in the libyang context. More detailed information can be found at Context Dictionary page.

Function Documentation

LIBYANG_API_DECL LY_ERR lydict_dup	(	const struct ly_ctx *	ctx,
		const char *	value,
		const char **	str_p
	)

Duplicate string in dictionary. Only a reference counter is incremented.

Parameters

[in]	ctx	libyang context handler
[in]	value	NULL-terminated string to be duplicated in the dictionary (reference counter is incremented).
[out]	str_p	Optional parameter to get pointer to the string corresponding to the value and stored in dictionary.

Returns

LY_SUCCESS in case the string already exists in the dictionary.

LY_ENOTFOUND in case the string was not found.

LY_ERR on other errors

LIBYANG_API_DECL LY_ERR lydict_insert	(	const struct ly_ctx *	ctx,
		const char *	value,
		size_t	len,
		const char **	str_p
	)

Insert string into dictionary. If the string is already present, only a reference counter is incremented and no memory allocation is performed.

Parameters

[in]	ctx	libyang context handler
[in]	value	String to be stored in the dictionary. If NULL, function does nothing.
[in]	len	Number of bytes to store. The value is not required to be NULL terminated string, the len parameter says number of bytes stored in dictionary. The specified number of bytes is duplicated and terminating NULL byte is added automatically. If len is 0, it is count automatically using strlen().
[out]	str_p	Optional parameter to get pointer to the string corresponding to the value and stored in dictionary.

Returns

LY_SUCCESS in case of successful insertion into dictionary, note that the function does not return LY_EEXIST.

LY_EINVAL in case of invalid input parameters.

LY_EMEM in case of memory allocation failure.

LIBYANG_API_DECL LY_ERR lydict_insert_zc	(	const struct ly_ctx *	ctx,
		char *	value,
		const char **	str_p
	)

Insert string into dictionary - zerocopy version. If the string is already present, only a reference counter is incremented and no memory allocation is performed. This insert function variant avoids duplication of specified value - it is inserted into the dictionary directly.

Parameters

[in]	ctx	libyang context handler
[in]	value	NULL-terminated string to be stored in the dictionary. If the string is not present in dictionary, the pointer is directly used by the dictionary. Otherwise, the reference counter is incremented and the value is freed. So, after calling the function, caller is supposed to not use the value address anymore. If NULL, function does nothing.
[out]	str_p	Optional parameter to get pointer to the string corresponding to the value and stored in dictionary.

Returns

LY_SUCCESS in case of successful insertion into dictionary, note that the function does not return LY_EEXIST.

LY_EINVAL in case of invalid input parameters.

LY_EMEM in case of memory allocation failure.

LIBYANG_API_DECL LY_ERR lydict_remove	(	const struct ly_ctx *	ctx,
		const char *	value
	)

Remove specified string from the dictionary. It decrement reference counter for the string and if it is zero, the string itself is freed.

Parameters

[in]	ctx	libyang context handler
[in]	value	String to be freed. Note, that not only the string itself must match the stored value, but also the address is being compared and the counter is decremented only if it matches. If NULL, function does nothing.

Returns

LY_SUCCESS if the value was found and removed (or refcount decreased).

LY_ENOTFOUND if the value was not found.

LY_ERR on other errors.