#include <resources.hpp>

Inheritance diagram for ResourcePool:

Class 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: Please consult the Programmer's Manual of module ALib Resources for detailed documentation on when and how this interface is used.; 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 55 of file resources.hpp.

Public Static Methods
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 Methods
virtual	~ResourcePool ()

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)

Constructor & Destructor Documentation

◆ ~ResourcePool()

virtual ~ResourcePool ( )

inlinevirtual

Virtual destructor.

Definition at line 60 of file resources.hpp.

Member Function Documentation

◆ 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 101 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 LocalResourcePool, and ConfigResourcePool.

◆ 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 Module::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 LocalResourcePool, and ConfigResourcePool.

◆ 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 ALib Text 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 206 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 143 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: 0. 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 132 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 Module 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 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 LocalResourcePool, and ConfigResourcePool.

◆ 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 prior to 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 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:

Class Description

Public Static Methods

Public Methods

Constructor & Destructor Documentation

◆ ~ResourcePool()

Member Function Documentation

◆ Bootstrap()

◆ BootstrapAddOrReplace()

◆ BootstrapBulk()

◆ DbgDump()

Availability

◆ DbgGetCategories()

Availability

◆ DbgGetList()

Availability

◆ Get() [1/2]

◆ Get() [2/2]