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 chapter 3. Namespace alib::lang::resources of the Programmer's Manual of module ALib BaseCamp.; 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 43 of file resources.hpp.

#include <resources.hpp>

Inheritance diagram for ResourcePool:

[legend]

Public Static Method Index:
static ALIB_API AString	DbgDump (std::vector< std::tuple< NString, NString, String, integer > > &list, const NString &catFilter=nullptr, const String &format=A_CHAR("({3:}) {1}={2!TAB20!ESC<!Q}\n"))

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_API std::vector< std::pair< NString, integer > >	DbgGetCategories ()

virtual ALIB_API 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 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 88 of file resources.hpp.

Here is the call graph for this function:

◆ BootstrapAddOrReplace()

virtual bool 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 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: Usually, 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 ConfigResourcePool, and LocalResourcePool.

◆ BootstrapBulk()

virtual void 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 ConfigResourcePool, and LocalResourcePool.

◆ DbgDump()

AString DbgDump	(	std::vector< std::tuple< NString, NString, String, integer > > &	list,
		const NString &	catFilter = nullptr,
		const String &	format = A_CHAR("({3:}) {1}={2!TAB20!ESC<!Q}\n") )

static

Writes the list of resources obtainable with DbgGetList to an AString.

Availability: Available only if compiler symbol ALIB_DEBUG_RESOURCES is set and furthermore if module ALib BaseCamp is included in the ALib Distribution.

See also: Methods DbgGetList and DbgGetCategories.

Parameters

list	The list of resources, obtained with DbgGetList.
catFilter	Comma-separated list of names of categories to print. Defaults to nulled string, which includes all caegories.
format	The format of a line. Defaults to "({3:}) {1}={2!TAB20!ESC<!Q}\\n".

Returns: The dump of all resources.

Definition at line 191 of file localresourcepool.cpp.

Here is the call graph for this function:

◆ DbgGetCategories()

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

virtual

Implements abstract method ResourcePool::DbgGetCategories.

Availability: Available only if compiler symbol ALIB_DEBUG_RESOURCES is set.

Attention: This method is implemented only with the default pool instance of type LocalResourcePool is used. Otherwise, an ALib warning is raised and an empty vector is returned.

See also: Methods DbgGetList and DbgDump.

Returns: The externalized resource string.

Reimplemented in LocalResourcePool.

Definition at line 130 of file localresourcepool.cpp.

◆ DbgGetList()

std::vector< std::tuple< NString, NString, String, integer > > 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 penality 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 compiler symbol ALIB_DEBUG_RESOURCES is set.

Attention: This method is implemented only with the default pool instance of type LocalResourcePool is used. Otherwise, an ALib warning is raised and an empty vector is returned.

See also: Methods DbgGetCategories and DbgDump.

Returns: The externalized resource string.

Reimplemented in LocalResourcePool.

Definition at line 119 of file localresourcepool.cpp.

◆ Get() [1/2]

virtual const String & 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, argument dbgAssert has to be enclosed in macro ALIB_DBG (including the separting 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 assertion is raised if the resource was not found.

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

Implemented in ConfigResourcePool, and LocalResourcePool.

◆ Get() [2/2]

const String & 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 string conversion simply returns 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 assertion 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 Static Method Index:

Public Method Index:

Method Details:

◆ Bootstrap()

◆ BootstrapAddOrReplace()

◆ BootstrapBulk()

◆ DbgDump()

◆ DbgGetCategories()

◆ DbgGetList()

◆ Get() [1/2]

◆ Get() [2/2]