fdl_collection_helpers.h File Reference

Template helpers for collection traversal (count, at, find_by_field). More...

#include "fdl_doc.h"
#include <cstdint>
#include <memory>
#include <string_view>

Go to the source code of this file.

Functions
uint32_t	fdl::detail::root_collection_count (fdl_doc_t *doc, const char *key)
	Count elements in a root-level collection array.
template<typename HandleT , typename MakeHandleFn , typename GetCacheFn >
HandleT *	fdl::detail::root_collection_at (fdl_doc_t *doc, const char *key, uint32_t index, MakeHandleFn make_handle, GetCacheFn get_cache)
	Access an element by index in a root-level collection, with handle deduplication.
template<typename HandleT , typename MakeHandleFn , typename GetCacheFn >
HandleT *	fdl::detail::root_collection_find (fdl_doc_t *doc, const char *array_key, const char *field_key, const char *target, MakeHandleFn make_handle, GetCacheFn get_cache)
	Find an element by a string field in a root-level collection.
uint32_t	fdl::detail::child_collection_count (const jsoncons::ojson *parent_node, const char *key)
	Count elements in a child collection accessed via a parent node.
template<typename HandleT , typename KeyT , typename MakeHandleFn , typename GetCacheFn >
HandleT *	fdl::detail::child_collection_at (const jsoncons::ojson *parent_node, const char *key, uint32_t index, KeyT dedup_key, MakeHandleFn make_handle, GetCacheFn get_cache)
	Access an element by index in a child collection, with handle deduplication.
template<typename HandleT , typename MakeKeyFn , typename MakeHandleFn , typename GetCacheFn >
HandleT *	fdl::detail::child_collection_find (const jsoncons::ojson *parent_node, const char *array_key, const char *field_key, const char *target, MakeKeyFn make_key, MakeHandleFn make_handle, GetCacheFn get_cache)
	Find an element by a string field in a child collection.

Detailed Description

Template helpers for collection traversal (count, at, find_by_field).

These templates eliminate duplication across the 5 collection types (framing_intents, contexts, canvas_templates, canvases, framing_decisions). Each template is parameterized by:

• HandleT: the handle struct type
• MakeHandleFn: callable(doc, index) -> unique_ptr<HandleT>
• GetCacheFn: callable(doc) -> pair<ownership_vec&, dedup_map&>

The doc_lock must already be held by the caller.

Function Documentation

root_collection_count()

uint32_t fdl::detail::root_collection_count ( fdl_doc_t *  doc, const char *  key  )

inline

Count elements in a root-level collection array.

Caller must hold the document lock.

Parameters

doc	Document handle.
key	JSON key for the root-level array (e.g., "contexts").

Returns

Number of elements, or 0 if absent.

root_collection_at()

template<typename HandleT , typename MakeHandleFn , typename GetCacheFn >

HandleT * fdl::detail::root_collection_at	(	fdl_doc_t *	doc,
		const char *	key,
		uint32_t	index,
		MakeHandleFn	make_handle,
		GetCacheFn	get_cache
	)

Access an element by index in a root-level collection, with handle deduplication.

Caller must hold the document lock.

Template Parameters

HandleT	Handle struct type.
MakeHandleFn	Callable: (fdl_doc_t*, uint32_t) -> std::unique_ptr<HandleT>.
GetCacheFn	Callable: (fdl_doc_t*) -> std::pair<vector<unique_ptr<HandleT>>&, map<KeyT,HandleT*>&>.

Parameters

doc	Document handle.
key	JSON key for the root-level array.
index	Element index.
make_handle	Factory for creating new handles.
get_cache	Accessor for ownership vector and dedup map.

Returns

Handle pointer, or nullptr if out of bounds.

root_collection_find()

template<typename HandleT , typename MakeHandleFn , typename GetCacheFn >

HandleT * fdl::detail::root_collection_find	(	fdl_doc_t *	doc,
		const char *	array_key,
		const char *	field_key,
		const char *	target,
		MakeHandleFn	make_handle,
		GetCacheFn	get_cache
	)

Find an element by a string field in a root-level collection.

Performs a linear scan of the array, matching on the given field. Caller must hold the document lock.

Template Parameters

HandleT	Handle struct type.
MakeHandleFn	Callable: (fdl_doc_t*, uint32_t) -> std::unique_ptr<HandleT>.
GetCacheFn	Callable: (fdl_doc_t*) -> std::pair<vector<unique_ptr<HandleT>>&, map<KeyT,HandleT*>&>.

Parameters

doc	Document handle.
array_key	JSON key for the root-level array.
field_key	JSON key within each element to match against.
target	Value to search for.
make_handle	Factory for creating new handles.
get_cache	Accessor for ownership vector and dedup map.

Returns

Handle pointer, or nullptr if not found.

child_collection_count()

uint32_t fdl::detail::child_collection_count ( const jsoncons::ojson *  parent_node, const char *  key  )

inline

Count elements in a child collection accessed via a parent node.

Caller must hold the document lock.

Parameters

parent_node	Resolved parent JSON node (e.g., context node).
key	JSON key for the child array (e.g., "canvases").

Returns

Number of elements, or 0 if absent.

child_collection_at()

template<typename HandleT , typename KeyT , typename MakeHandleFn , typename GetCacheFn >

HandleT * fdl::detail::child_collection_at	(	const jsoncons::ojson *	parent_node,
		const char *	key,
		uint32_t	index,
		KeyT	dedup_key,
		MakeHandleFn	make_handle,
		GetCacheFn	get_cache
	)

Access an element by index in a child collection, with handle deduplication.

Caller must hold the document lock.

Template Parameters

HandleT	Handle struct type.
KeyT	Dedup map key type (uint64_t for packed keys).
MakeHandleFn	Callable: (uint32_t) -> std::unique_ptr<HandleT>.
GetCacheFn	Callable: () -> std::pair<vector<unique_ptr<HandleT>>&, map<KeyT,HandleT*>&>.

Parameters

parent_node	Resolved parent JSON node.
key	JSON key for the child array.
index	Element index.
dedup_key	Packed key for dedup map lookup.
make_handle	Factory for creating new handles.
get_cache	Accessor for ownership vector and dedup map.

Returns

Handle pointer, or nullptr if out of bounds.

child_collection_find()

template<typename HandleT , typename MakeKeyFn , typename MakeHandleFn , typename GetCacheFn >

HandleT * fdl::detail::child_collection_find	(	const jsoncons::ojson *	parent_node,
		const char *	array_key,
		const char *	field_key,
		const char *	target,
		MakeKeyFn	make_key,
		MakeHandleFn	make_handle,
		GetCacheFn	get_cache
	)

Find an element by a string field in a child collection.

Caller must hold the document lock.

Template Parameters

HandleT	Handle struct type.
MakeKeyFn	Callable: (uint32_t) -> KeyT. Computes dedup key from index.
MakeHandleFn	Callable: (uint32_t) -> std::unique_ptr<HandleT>.
GetCacheFn	Callable: () -> std::pair<vector<unique_ptr<HandleT>>&, map<KeyT,HandleT*>&>.

Parameters

parent_node	Resolved parent JSON node.
array_key	JSON key for the child array.
field_key	JSON key within each element to match against.
target	Value to search for.
make_key	Key factory for dedup map.
make_handle	Handle factory.
get_cache	Accessor for ownership vector and dedup map.

Returns

Handle pointer, or nullptr if not found.