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

Key-value storage kept in a file: the place for data that must be found again at the next start (preferences, a saved session). More...

#include <headers/guillaume/local_storage.hpp>

Inheritance diagram for guillaume::LocalStorage:
Collaboration diagram for guillaume::LocalStorage:

Public Member Functions

 LocalStorage (const std::filesystem::path &storageFilePath=defaultStoragePath()) noexcept(false)
 Open the storage file, creating it and its parent directories when they do not exist.
 ~LocalStorage (void) override
 Close the database. The items stay in the file.
void setItem (const std::string &key, const std::string &value) noexcept(false) 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) noexcept(false) override
 Read the text stored under a key.
void removeItem (const std::string &key) noexcept(false) override
 Delete the item stored under a key. Does nothing when there is none.
void clear (void) noexcept(false) override
 Delete every item of the storage file.
bool isPersistent (void) const noexcept
 Tell whether the items are written to the storage file.
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".
Public Member Functions inherited from guillaume::Storage
virtual ~Storage (void)=default
 Virtual destructor.
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.
template<typename ValueType>
std::optional< ValueType > getItemAs (const std::string &key)
 Read the item stored under a key and convert it to a type.

Static Public Member Functions

static std::filesystem::path defaultStoragePath (void) noexcept(false)
 Get the path used when the constructor is given none.

Detailed Description

Key-value storage kept in a file: the place for data that must be found again at the next start (preferences, a saved session).

The items live in an SQLite database file, by default .guillaume-local-storage.db in the current working directory. Two LocalStorage objects opened on the same path see the same items. The typed overloads of Storage (numbers, booleans, getItemAs) are available.

guillaume::LocalStorage storage("settings.db");
storage.setItem("theme", "dark");
const auto theme = storage.getItem("theme"); // "dark", also after
// a restart
Key-value storage kept in a file: the place for data that must be found again at the next start (pref...
Design tokens: colors, type scale, shapes, elevation, motion and spacing. Read them through guillaume...

Things to watch out for:

  • When the file cannot be opened or created, the storage logs an error and works in memory instead: nothing is saved. Check isPersistent() when that matters.
  • Every operation takes a lock, so one object can be used from several threads. Another process holding the file is waited for, up to five seconds.
  • The class owns a database connection and is not meant to be copied.
See also
Storage
SessionStorage

Definition at line 71 of file local_storage.hpp.

Constructor & Destructor Documentation

◆ LocalStorage()

guillaume::LocalStorage::LocalStorage ( const std::filesystem::path & storageFilePath = defaultStoragePath())
explicit

Open the storage file, creating it and its parent directories when they do not exist.

When the file cannot be opened or created (read-only location, for instance), an error is logged and the storage works on an in-memory database: isPersistent() then returns false.

Parameters
storageFilePathPath of the SQLite database file. Defaults to defaultStoragePath().
Exceptions
std::runtime_errorWhen neither the file nor the in-memory database can be opened, or when the table cannot be created.
Here is the caller graph for this function:

Member Function Documentation

◆ clear()

void guillaume::LocalStorage::clear ( void )
overridevirtual

Delete every item of the storage file.

Exceptions
std::runtime_errorWhen SQLite reports an error.

Implements guillaume::Storage.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ defaultStoragePath()

std::filesystem::path guillaume::LocalStorage::defaultStoragePath ( void )
static

Get the path used when the constructor is given none.

Returns
.guillaume-local-storage.db in the current working directory.
Exceptions
std::filesystem::filesystem_errorWhen the current working directory cannot be determined.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getItem()

std::optional< std::string > guillaume::LocalStorage::getItem ( const std::string & key)
overridevirtual

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.
Exceptions
std::runtime_errorWhen the statement cannot be prepared.

Implements guillaume::Storage.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isPersistent()

bool guillaume::LocalStorage::isPersistent ( void ) const
noexcept

Tell whether the items are written to the storage file.

When the storage file cannot be opened (read-only or missing location), the storage works on an in-memory database so the application keeps running, but nothing survives a restart.

Returns
True when backed by the file, false when in-memory.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeItem()

void guillaume::LocalStorage::removeItem ( const std::string & key)
overridevirtual

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

Parameters
keyThe name of the item.
Exceptions
std::runtime_errorWhen the statement cannot be prepared.

Implements guillaume::Storage.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setItem() [1/4]

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/4]

void guillaume::LocalStorage::setItem ( const std::string & key,
const std::string & value )
overridevirtual

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

The item is written to the file before the call returns.

Parameters
keyThe name of the item.
valueThe text to store. Text after an embedded null character is not stored.
Exceptions
std::runtime_errorWhen the statement cannot be prepared.

Implements guillaume::Storage.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setItem() [3/4]

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/4]

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: