StringTreeNamesDynamic< TChar, TLocalCapacity > Struct Template Reference

Description:

template<typename TChar = character, integer TLocalCapacity = 32>
struct alib::containers::StringTreeNamesDynamic< TChar, TLocalCapacity >

This struct is the default type for template parameter TNodeHandler of class StringTree.

Besides defining the character type as given with template parameter TChar, the node name string-type is exposed with NameStringType. The string-type depends on the template parameter TLocalCapacity:

• If this is 0, the type evaluates to a simple string with no internal storage.
• If this is greater than zero, the type evaluates to a LocalString of given capacity.

This design allows allocating a fixed-size string buffer with each node, and only if a node's name exceeds this capacity, a dynamic allocation for storing the node name is performed. As a consequence, some overhead of wasted memory will occur, as this capacity is allocated with every node, regardless of its name's length. To investigate into the percentage of overflows to evaluate a reasonable value for template parameter TLocalCapacity, simple global debug counters DBG_STATS_STRINGTREE_NAMES and DBG_STATS_STRINGTREE_NAME_OVERFLOWS can be used.

Method InitializeNode is invoked after insertion of a new element (aka "node") into the container and FreeNode is invoked before the destruction of a node. When InitializeNode is invoked, the custom object of template type T (of the StringTree) is already default constructed and the key of the node in union (field detail::StringTreeBase::NodeKey::name) is set to what was provided as a child name or path string. (In the latter case, it is set to a substring of the given path.). If template parameter TLocalCapacity is greater than 0, the method copies the key to field storage of the union (which is still accessible with the base string-type of union-field key). If 0 is given, the node name is replaced by a copy of the string which is dynamically allocated.

Custom Implementations

A custom implementation has to provide all four entities that this type provides in a compatible fashion.

The main purpose of the node handler types is to ensure that the name strings of inserted nodes are duly allocated, copied and freed as needed: When a new element is (or a whole path of new elements are) created, then the initial name of the nodes are taken from the string passed to the corresponding interface method of class StringTree (and inner types). The challenge is that these string's life-cycle might be only short term. Therefore, right after the creation of an element, method InitializeNode is invoked, allowing to create a safe copy of the name.
To free any allocated space, method FreeNode is invoked.

Besides this, custom implementation may tweak the given node on their own discretion. Especially a custom implementation may create and recycle other portions of the stored objects, to establish weak monotonic allocation rules. A sample of such more complex behavior is found with ALib type FTree.

See also

Two other built-in implementations of this type to be used with StringTree instantiations are provided with this ALib Module:

• StringTreeNamesStatic.
• StringTreeNamesAlloc.

Further information can be found in chapter 4. Node and Node Name String Allocation of the reference documentation of class StringTree.

Template Parameters

TChar	The character type of the key strings. This type is used with any interface method of StringTree that accepts a node name or path string. Defaults to type character.
TLocalCapacity	The capacity of the LocalString to place in the StringTree's node. If 0 is given, a normal String is used for the name, and the buffer is copied to an dynamically allocated array. Defaults to 32.

Definition at line 110 of file stringtree.hpp.

#include <stringtree.hpp>

Public Type Index:
using	CharacterType = TChar
	The character type that the StringTree uses for child name and path strings.
using	NameStringType
	The string-type of a node's name.

Public Static Method Index:
template<typename TTree >
static void	FreeNode (TTree &tree, typename TTree::Node &node)
template<typename TTree >
static void	InitializeNode (TTree &tree, typename TTree::Node &node)

Type Definition Details:

CharacterType

template<typename TChar = character, integer TLocalCapacity = 32>

using CharacterType = TChar

The character type that the StringTree uses for child name and path strings.

Definition at line 113 of file stringtree.hpp.

NameStringType

template<typename TChar = character, integer TLocalCapacity = 32>

using NameStringType

Initial value:

 ATMP_IF_T_F ( (TLocalCapacity > 0),
                                         strings::TLocalString<           TChar
                                                               ALIB_COMMA TLocalCapacity
                                                               ALIB_COMMA lang::HeapAllocator>,
                                         strings::TString     <TChar>  )

The string-type of a node's name.

Definition at line 116 of file stringtree.hpp.

Method Details:

FreeNode()

template<typename TChar = character, integer TLocalCapacity = 32>

template<typename TTree >

static void FreeNode ( TTree & tree, typename TTree::Node & node )

inlinestatic

This implementation frees the dynamically allocated memory of the node's name.

See also

See class description for further information.

Parameters

tree	The instance of struct detail::StringTreeBase that invokes this method. Any member may be accessed, including nodeTable which contains the allocator that the tree uses for the allocation of nodes.
node	The node that is to be removed. Allows access to the key and custom value data. While the parent and sibling nodes are likewise accessible, it is strictly forbidden to modify those.

Template Parameters

TTree

The type of the templated instantiation of struct detail::StringTreeBase that this method is invoked by. (Deduced by the compiler.)

Definition at line 178 of file stringtree.hpp.

InitializeNode()

template<typename TChar = character, integer TLocalCapacity = 32>

template<typename TTree >

static void InitializeNode ( TTree & tree, typename TTree::Node & node )

inlinestatic

This implementation copies the node's name to a dynamically allocated piece of heap memory.

See also

See class description for further information.

Parameters

tree	The instance of struct detail::StringTreeBase that invokes this method. Any member may be accessed, including nodeTable which contains the allocator that the tree uses for the allocation of nodes.
node	The node that was just created. Allows access to the key and custom value data. While the parent and sibling nodes are likewise accessible, it is strictly forbidden to modify those.

Template Parameters

TTree

The type of the templated instantiation of struct detail::StringTreeBase that this method is invoked by. (Deduced by the compiler.)

Definition at line 138 of file stringtree.hpp.

---

The documentation for this struct was generated from the following file:

• stringtree.hpp