guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::Storage Class Referenceabstract

A key-value store of strings, modelled on the web Storage API (setItem, getItem, removeItem, clear). More...

#include <headers/guillaume/storage.hpp>

Inheritance diagram for guillaume::Storage:

Public Member Functions

virtual ~Storage (void)=default
 Virtual destructor.
virtual void setItem (const std::string &key, const std::string &value)=0
 Store a string under a key, replacing the item already stored under that key, if any.
void setItem (const std::string &key, std::string_view value)
 Store a copy of a string view under a key.
void setItem (const std::string &key, const char *value)
 Store a copy of a C string under a key.
template<typename ValueType>
requires (std::is_same_v<std::remove_cvref_t<ValueType>, bool>)
void setItem (const std::string &key, ValueType value)
 Store a boolean under a key, as the text "true" or "false".
template<typename ValueType>
requires (std::is_arithmetic_v<ValueType> && !std::is_same_v<ValueType, bool>)
void setItem (const std::string &key, ValueType value)
 Store a number under a key, as its decimal text.
virtual std::optional< std::string > getItem (const std::string &key)=0
 Read the text stored under a key.
template<typename ValueType>
std::optional< ValueType > getItemAs (const std::string &key)
 Read the item stored under a key and convert it to a type.
virtual void removeItem (const std::string &key)=0
 Delete the item stored under a key. Does nothing when there is none.
virtual void clear (void)=0
 Delete every item of the storage.

Detailed Description

A key-value store of strings, modelled on the web Storage API (setItem, getItem, removeItem, clear).

Two implementations exist: LocalStorage keeps the items in a file and finds them again at the next start; SessionStorage keeps them in memory until the process ends. Everything is stored as text: the typed setItem() overloads convert to a string and getItemAs() converts back.

storage.setItem("volume", 0.8f); // stored as "0.800000"
storage.setItem("muted", false); // stored as "false"
storage.setItem("user", "ada");
const float volume =
storage.getItemAs<float>("volume").value_or(1.0f);
if (!storage.getItem("token")) {
// no item under that key
}
Key-value storage that lasts as long as the process: the place for data shared between scenes that ne...
void setItem(const std::string &key, const std::string &value) override
Store a string under a key, replacing the item already stored under that key, if any.
std::optional< std::string > getItem(const std::string &key) override
Read the text stored under a key.
std::optional< ValueType > getItemAs(const std::string &key)
Read the item stored under a key and convert it to a type.
Note
A class that implements the interface adds using Storage::setItem;, otherwise its own setItem() hides the typed overloads.
See also
LocalStorage
SessionStorage

Definition at line 66 of file storage.hpp.

Member Function Documentation

◆ clear()

virtual void guillaume::Storage::clear ( void )
pure virtual

Delete every item of the storage.

Implemented in guillaume::LocalStorage, and guillaume::SessionStorage.

◆ getItem()

virtual std::optional< std::string > guillaume::Storage::getItem ( const std::string & key)
pure virtual

Read the text stored under a key.

Parameters
keyThe name of the item.
Returns
The stored text, or std::nullopt when no item has that key. An item holding an empty string is returned as an empty string, not as std::nullopt.

Implemented in guillaume::LocalStorage, and guillaume::SessionStorage.

◆ getItemAs()

template<typename ValueType>
std::optional< ValueType > guillaume::Storage::getItemAs ( const std::string & key)

Read the item stored under a key and convert it to a type.

  • std::string: the text as stored.
  • bool: "true" or "1" gives true, "false" or "0" gives false.
  • integer types: the whole text must be a number that fits the type.
  • floating-point types: the whole text must be a number in range, as read by std::strtold. An empty text reads as 0.
Template Parameters
ValueTypeThe type to convert to: std::string, bool, an integer type or a floating-point type. Any other type does not compile.
Parameters
keyThe name of the item.
Returns
The converted value, or std::nullopt when no item has that key or when its text cannot be converted to ValueType.

◆ removeItem()

virtual void guillaume::Storage::removeItem ( const std::string & key)
pure virtual

Delete the item stored under a key. Does nothing when there is none.

Parameters
keyThe name of the item.

Implemented in guillaume::LocalStorage, and guillaume::SessionStorage.

◆ setItem() [1/5]

void guillaume::Storage::setItem ( const std::string & key,
const char * value )

Store a copy of a C string under a key.

Parameters
keyThe name of the item.
valueThe null-terminated text to store. A null pointer stores an empty string.

◆ setItem() [2/5]

virtual void guillaume::Storage::setItem ( const std::string & key,
const std::string & value )
pure virtual

Store a string under a key, replacing the item already stored under that key, if any.

Implemented by each storage; the other overloads end up here.

Parameters
keyThe name of the item.
valueThe text to store. It may be empty.

Implemented in guillaume::LocalStorage, and guillaume::SessionStorage.

◆ setItem() [3/5]

void guillaume::Storage::setItem ( const std::string & key,
std::string_view value )

Store a copy of a string view under a key.

Parameters
keyThe name of the item.
valueThe text to store.

◆ setItem() [4/5]

template<typename ValueType>
requires (std::is_arithmetic_v<ValueType> && !std::is_same_v<ValueType, bool>)
void guillaume::Storage::setItem ( const std::string & key,
ValueType value )

Store a number under a key, as its decimal text.

The text is produced by std::to_string: a floating-point value keeps six digits after the decimal point, and a char is stored as its numeric code.

Template Parameters
ValueTypeAn integer or floating-point type other than bool.
Parameters
keyThe name of the item.
valueThe number to store.

◆ setItem() [5/5]

template<typename ValueType>
requires (std::is_same_v<std::remove_cvref_t<ValueType>, bool>)
void guillaume::Storage::setItem ( const std::string & key,
ValueType value )

Store a boolean under a key, as the text "true" or "false".

Template Parameters
ValueTypebool (possibly const or a reference).
Parameters
keyThe name of the item.
valueThe boolean to store.

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