An FLKeyPath Describes a location in a Fleece object tree, as a path from the root that follows dictionary properties and array elements. More...

Typedefs
typedef struct _FLKeyPath *	FLKeyPath
	A reference to a key path.

Functions
NODISCARD FLEECE_PUBLIC FLKeyPath FL_NULLABLE	FLKeyPath_New (FLSlice specifier, FLError *FL_NULLABLE outError)
	Creates a new FLKeyPath object by compiling a path specifier string.

FLEECE_PUBLIC void	FLKeyPath_Free (FLKeyPath FL_NULLABLE)
	Frees a compiled FLKeyPath object.

NODISCARD FLEECE_PUBLIC FLValue FL_NULLABLE	FLKeyPath_Eval (FLKeyPath, FLValue root)
	Evaluates a compiled key-path for a given Fleece root object.

NODISCARD FLEECE_PUBLIC FLValue FL_NULLABLE	FLKeyPath_EvalOnce (FLSlice specifier, FLValue root, FLError *FL_NULLABLE outError)
	Evaluates a key-path from a specifier string, for a given Fleece root object.

NODISCARD FLEECE_PUBLIC FLStringResult	FLKeyPath_ToString (FLKeyPath path)
	Returns a path in string form.

FLEECE_PUBLIC bool	FLKeyPath_Equals (FLKeyPath path1, FLKeyPath path2)
	Equality test.

FLEECE_PUBLIC size_t	FLKeyPath_GetCount (FLKeyPath)
	The number of path components.

FLEECE_PUBLIC bool	FLKeyPath_GetElement (FLKeyPath path, size_t i, FLSlice outDictKey, int32_t outArrayIndex)
	Returns an element of a path, either a key or an array index.

NODISCARD FLEECE_PUBLIC FLKeyPath FL_NULLABLE	FLKeyPath_NewEmpty (void)
	Creates a new empty FLKeyPath, for the purpose of adding components to it.

FLEECE_PUBLIC void	FLKeyPath_AddProperty (FLKeyPath, FLString property)
	Appends a single property/key component to a path.

FLEECE_PUBLIC void	FLKeyPath_AddIndex (FLKeyPath, int index)
	Appends a single array index component to a path.

NODISCARD FLEECE_PUBLIC bool	FLKeyPath_AddComponents (FLKeyPath, FLString specifier, FLError *FL_NULLABLE outError)
	Appends one or more components, encoded as a specifier like the one passed to FLKeyPath_New.

FLEECE_PUBLIC void	FLKeyPath_DropComponents (FLKeyPath, size_t n)
	Removes the first `n` components.

Detailed Description

An FLKeyPath Describes a location in a Fleece object tree, as a path from the root that follows dictionary properties and array elements.

It's similar to a JSONPointer or an Objective-C KeyPath, but simpler (so far.) The path is compiled into an efficient form that can be traversed quickly.

It looks like foo.bar[2][-3].baz – that is, properties prefixed with a ., and array indexes in brackets. (Negative indexes count from the end of the array.)

A leading JSONPath-like $. is allowed but ignored.

A '\' can be used to escape a special character ('.', '[' or '$').

Typedef Documentation

◆ FLKeyPath

typedef struct _FLKeyPath* FLKeyPath

A reference to a key path.

Function Documentation

◆ FLKeyPath_AddComponents()

NODISCARD FLEECE_PUBLIC bool FLKeyPath_AddComponents	(	FLKeyPath	,
		FLString	specifier,
		FLError *FL_NULLABLE	outError )

Appends one or more components, encoded as a specifier like the one passed to FLKeyPath_New.

◆ FLKeyPath_AddIndex()

FLEECE_PUBLIC void FLKeyPath_AddIndex	(	FLKeyPath	,
		int	index )

Appends a single array index component to a path.

◆ FLKeyPath_AddProperty()

FLEECE_PUBLIC void FLKeyPath_AddProperty	(	FLKeyPath	,
		FLString	property )

Appends a single property/key component to a path.

The string should not be escaped.

◆ FLKeyPath_DropComponents()

FLEECE_PUBLIC void FLKeyPath_DropComponents	(	FLKeyPath	,
		size_t	n )

Removes the first n components.

◆ FLKeyPath_Equals()

FLEECE_PUBLIC bool FLKeyPath_Equals	(	FLKeyPath	path1,
		FLKeyPath	path2 )

Equality test.

◆ FLKeyPath_Eval()

NODISCARD FLEECE_PUBLIC FLValue FL_NULLABLE FLKeyPath_Eval	(	FLKeyPath	,
		FLValue	root )

Evaluates a compiled key-path for a given Fleece root object.

◆ FLKeyPath_EvalOnce()

NODISCARD FLEECE_PUBLIC FLValue FL_NULLABLE FLKeyPath_EvalOnce	(	FLSlice	specifier,
		FLValue	root,
		FLError *FL_NULLABLE	outError )

Evaluates a key-path from a specifier string, for a given Fleece root object.

If you only need to evaluate the path once, this is a bit faster than creating an FLKeyPath object, evaluating, then freeing it.

◆ FLKeyPath_Free()

FLEECE_PUBLIC void FLKeyPath_Free ( FLKeyPath FL_NULLABLE )

Frees a compiled FLKeyPath object.

(It's ok to pass NULL.)

◆ FLKeyPath_GetCount()

FLEECE_PUBLIC size_t FLKeyPath_GetCount ( FLKeyPath )

The number of path components.

◆ FLKeyPath_GetElement()

FLEECE_PUBLIC bool FLKeyPath_GetElement	(	FLKeyPath	path,
		size_t	i,
		FLSlice *	outDictKey,
		int32_t *	outArrayIndex )

Returns an element of a path, either a key or an array index.

Parameters

path	The path to examine.
i	The index of the component to examine.
outDictKey	On return this will be the property name, or a null slice if this component is an array index.
outArrayIndex	On return this will be the array index, or 0 if this component is a property.

Returns: True on success, false if there is no such component.

◆ FLKeyPath_New()

NODISCARD FLEECE_PUBLIC FLKeyPath FL_NULLABLE FLKeyPath_New	(	FLSlice	specifier,
		FLError *FL_NULLABLE	outError )

Creates a new FLKeyPath object by compiling a path specifier string.

◆ FLKeyPath_NewEmpty()

NODISCARD FLEECE_PUBLIC FLKeyPath FL_NULLABLE FLKeyPath_NewEmpty ( void )

Creates a new empty FLKeyPath, for the purpose of adding components to it.

◆ FLKeyPath_ToString()

NODISCARD FLEECE_PUBLIC FLStringResult FLKeyPath_ToString ( FLKeyPath path )

Returns a path in string form.

Typedefs

Functions