Description:

This purely abstract class provides an interface to store and retrieve "resourced" string data which are organized in a two-level key hierarchy named "resource category" and "resource name". The latter are of narrow string-type.

See also: For detailed documentation on when and how this interface is used, please consult the Programmer's Manual of this module ALib Resources.; Two built-in implementations of this pure abstract interface are provided with LocalResourcePool and ConfigResourcePool. Please consult their reference documentation for further details.

Definition at line 23 of file resources.inl.

Inheritance diagram for alib::resources::ResourcePool:

[legend]

Public Method Index:
virtual	~ResourcePool ()=default
	Virtual destructor.

void	Bootstrap (const NString &category, const NString &name, const String &data)

virtual bool	BootstrapAddOrReplace (const NString &category, const NString &name, const String &data)=0

virtual void	BootstrapBulk (const nchar *category,...)=0

virtual ALIB_DLL std::vector< std::pair< NString, integer > >	DbgGetCategories ()

virtual ALIB_DLL std::vector< std::tuple< NString, NString, String, integer > >	DbgGetList ()

virtual const String &	Get (const NString &category, const NString &name, bool dbgAssert)=0

const String &	Get (const NString &category, const String &name, bool dbgAssert)

Method Details:

◆ Bootstrap()

void alib::resources::ResourcePool::Bootstrap	(	const NString &	category,
		const NString &	name,
		const String &	data )

inline

Simple inline method that invokes virtual method BootstrapAddOrReplace. In debug-compilations, it is asserted that a resource with the given key did not exist already.

The use of this method is preferred over a direct invocation of BootstrapAddOrReplace.

Parameters

category	Category string of the resource to add.
name	Name string of the resource.
data	The resource data.

Definition at line 68 of file resources.inl.

Here is the call graph for this function:

◆ BootstrapAddOrReplace()

virtual bool alib::resources::ResourcePool::BootstrapAddOrReplace	(	const NString &	category,
		const NString &	name,
		const String &	data )

pure virtual

Used to store a resource string.

In the context of ALib Modules, which usually are the only areas where instances of this type are available (used), this method must only be invoked during the process of bootstrapping ALib (and corresponding custom modules).

Attention: The life-cycle of the given string's buffers, have to survive this resource instance. Usually the strings passed here are constant C++ string literals, residing in the data segment of an executable

Note: Usually, the method Bootstrap should be preferred, which asserts in debug-compilations if a resource already existed. The use of this method is for special cases, for example, to replace (patch) resources of dependent modules.

Parameters

category	Category string of the resource to add.
name	Name string of the resource.
data	The resource data.

Returns: true if the resource did exist and was replaced, false if it was an insertion.

Implemented in alib::resources::LocalResourcePool, and alib::variables::ConfigResourcePool.

◆ BootstrapBulk()

virtual void alib::resources::ResourcePool::BootstrapBulk	(	const nchar *	category,
			... )

pure virtual

Same as Bootstrap but accepts an array of name/value pairs to be filled into the given parameter category.

Attention: The given list has to be finished with a final nullptr argument for the next name!

In the context of ALib Modules, which usually are the only areas where instances of this type are available (used), this method must only invoked during the process of bootstrapping ALib (and corresponding custom modules).

Attention: The life-cycle of the given string's buffers, have to survive this resource instance. Usually the strings passed here are constant C++ string literals, residing an the data segment of an executable

Note: The use of variadic C-style arguments "..." in general is not recommended to be used. We still do it here, because this method is usually used with implementations of Camp::Bootstrap to load static default values. This approach saves a lot of otherwise needed single invocations (reduces code size) and allows a clean code for the init methods.
For technical reasons, parameter category is declared as type const nchar*.

Parameters

category	The category of the resources given.
...	A list of pairs of const nchar* and const character* keys and data, including a terminating `nullptr` value.

Implemented in alib::resources::LocalResourcePool, and alib::variables::ConfigResourcePool.

◆ DbgGetCategories()

std::vector< std::pair< NString, integer > > alib::resources::ResourcePool::DbgGetCategories ( )

virtual

Implements abstract method ResourcePool::DbgGetCategories.

Availability: Available only if the compiler-symbol ALIB_DEBUG_RESOURCES is set.

Attention: This method is implemented only with the default pool instance of type LocalResourcePool. Other implementations raise an ALib warning and return an empty vector.

See also: Methods DbgGetList and DbgDump.

Returns: The externalized resource string.

Reimplemented in alib::resources::LocalResourcePool.

Definition at line 142 of file localresourcepool.cpp.

◆ DbgGetList()

std::vector< std::tuple< NString, NString, String, integer > > alib::resources::ResourcePool::DbgGetList ( )

virtual

Returns a vector of tuples for each resourced element. Each tuple contains:

The category name
The resource name
The resource value
The number of requests for the resource performed by a using data.

While being useful to generaly inspect the resources, a high number of requests might indicate a performance penalty for a using software. Such can usually be mitigated in a very simple fashion by "caching" a resource string in a local or global/static string variable.

Availability: Available only if the compiler-symbol ALIB_DEBUG_RESOURCES is set.

Attention: This method is implemented only with the default pool instance of type LocalResourcePool. Other implementations raise an ALib warning and return an empty vector.

See also: Methods DbgGetCategories and DbgDump.

Returns: The externalized resource string.

Reimplemented in alib::resources::LocalResourcePool.

Definition at line 132 of file localresourcepool.cpp.

◆ Get() [1/2]

virtual const String & alib::resources::ResourcePool::Get	(	const NString &	category,
		const NString &	name,
		bool	dbgAssert )

pure virtual

Returns a resource. On failure (resource not found), a nulled string is returned.

Note: Usually resource pools are associated with Camp objects and resources should be loaded using its "shortcut methods" TryResource and GetResource. If used directly, the argument dbgAssert has to be enclosed in macro ALIB_DBG (including the separating comma).

Parameters

category	Category string of the resource.
name	Name string of the resource
dbgAssert	This parameter is available (and to be passed) only in debug mode. If `true`, an error is raised if the resource was not found.

Returns: The resource string, respectively a nulled string on failure.

Implemented in alib::resources::LocalResourcePool, and alib::variables::ConfigResourcePool.

◆ Get() [2/2]

const String & alib::resources::ResourcePool::Get	(	const NString &	category,
		const String &	name,
		bool	dbgAssert )

Convenience inlined method that accepts parameter name as character instead of nchar based string-type. The rationale for this is that often, resource name keys are read from other resourced strings and need conversion if used. This avoids external conversion before invoking this method.

This method is available only when ALib is compiled with type character not being equivalent to nchar.

After the string conversion, this method simply returns the result of virtual method Get(const NString&, const NString&, bool).

Parameters

category	Category string of the resource.
name	Name string of the resource
dbgAssert	This parameter is available (and to be passed) only in debug mode. If `true`, an error is raised if the resource was not found.

Returns: The resource string, respectively a nulled string on failure.

The documentation for this class was generated from the following files:

Description:

Public Method Index:

Method Details:

◆ Bootstrap()

◆ BootstrapAddOrReplace()

◆ BootstrapBulk()

◆ DbgGetCategories()

◆ DbgGetList()

◆ Get() [1/2]

◆ Get() [2/2]