Serializable, thread-safe settings data. More...

#include <SettingsData.h>

Public Member Functions
	SettingsData (const IsoString &identifier)

virtual	~SettingsData ()

bool	Add (const IsoString &key, const Variant &value)

IsoStringList	AllKeys () const

void	Clear ()

unsigned	CompressionThreshold () const

void	DisableBlockCompression (bool disable=true)

void	DisableMinifiedXML (bool disable=true)

void	EnableBlockCompression (bool enable=true)

void	EnableMinifiedXML (bool enable=true)

fsize_type	FileSize () const

bool	IsBlockCompressionEnabled () const

bool	IsEmpty () const

bool	IsMinifiedXMLEnabled () const

bool	IsModified () const

IsoStringList	Keys (const IsoString &key) const

virtual void	Load ()

int	ModifiedCount () const

virtual void	Purge ()

bool	Remove (const IsoString &key)

virtual void	Save () const

Variant	Search (const IsoString &key) const

void	SetCompressionThreshold (unsigned threshold)

Detailed Description

This class implements a specialized dictionary for fast indexed access to key/value pairs with persistent storage in special per-instance XML files.

The main access functions provided by this class to add, get and find settings values, as well as to clear, load and save the settings and query object properties, are implemented as thread-safe routines. This supports applications performing parallel settings access and disk I/O operations, as well as multiple application instances running concurrently.

Settings files are generated and managed transparently on platform-dependent configuration directories.

Definition at line 86 of file SettingsData.h.

Constructor & Destructor Documentation

◆ SettingsData()

pcl::SettingsData::SettingsData ( const IsoString & identifier )

Constructs a new settings data structure.

Parameters

identifier A valid identifier (see IsoString::IsValidIdentifier()) that will be used to construct the unique name of a special settings file where all key/value pairs in this object will be stored persistently for the running core application instance.

◆ ~SettingsData()

virtual pcl::SettingsData::~SettingsData ( )

virtual

Virtual destructor.

Destroys and deallocates all settings data items and internal structures associated with this object. Note that this refers to data currently stored in memory, not to persistent storage in a settings file. To destroy data stored persistently, the Purge() member function must be called explicitly.

Member Function Documentation

◆ Add()

bool pcl::SettingsData::Add	(	const IsoString &	key,
		const Variant &	value
	)

Adds the specified key with the specified value to this object.

If an item with the specified key already exists in this object, it will be updated with the specified value only if it is different from the current one. Otherwise, a new key/value pair will be created.

Returns true iff the specified key was added, or if an existing value was modified.

The key/value pair will be stored in internal memory data structures, not in persistent settings files. To store settings persistently, the Save() member function must be called for this object.

Note: This function is thread-safe.

◆ AllKeys()

IsoStringList pcl::SettingsData::AllKeys ( ) const

Returns a list with all keys stored in this object.

Note: This function is thread-safe.

See also: Keys()

◆ Clear()

void pcl::SettingsData::Clear ( )

Destroys and removes all key/value pairs currently stored in this object.

Only items stored in internal memory data structures are removed by this function. Persistent storage is not altered.

Note: This function is thread-safe.

◆ CompressionThreshold()

unsigned pcl::SettingsData::CompressionThreshold ( ) const

inline

Returns the current compression threshold in bytes.

This value is the minimum length of a String or ByteArray property value that triggers block compression for serialization as XML files.

The default compression threshold is 4 KiB (4096 bytes).

See also: IsBlockCompressionEnabled()

Definition at line 298 of file SettingsData.h.

◆ DisableBlockCompression()

void pcl::SettingsData::DisableBlockCompression ( bool disable = true )

inline

Disables block compression.

See also: IsBlockCompressionEnabled()

Definition at line 283 of file SettingsData.h.

◆ DisableMinifiedXML()

void pcl::SettingsData::DisableMinifiedXML ( bool disable = true )

inline

Disables XML source code minification.

See also: IsMinifiedXMLEnabled()

Definition at line 244 of file SettingsData.h.

◆ EnableBlockCompression()

void pcl::SettingsData::EnableBlockCompression ( bool enable = true )

inline

Enables block compression.

See also: IsBlockCompressionEnabled()

Definition at line 273 of file SettingsData.h.

◆ EnableMinifiedXML()

void pcl::SettingsData::EnableMinifiedXML ( bool enable = true )

inline

Enables XML source code minification.

See also: IsMinifiedXMLEnabled()

Definition at line 234 of file SettingsData.h.

◆ FileSize()

fsize_type pcl::SettingsData::FileSize ( ) const

Returns the current size in bytes of the settings file generated by this object. Returns zero if no settings file has been generated yet.

◆ IsBlockCompressionEnabled()

bool pcl::SettingsData::IsBlockCompressionEnabled ( ) const

inline

Returns true iff block compression is currently enabled.

When block compression is enabled, String and ByteArray property values are serialized with compression in XML files when their sizes are greater than or equal to the current compression threshold (see CompressionThreshold()). The Zstandard compression codec is used in current versions of PCL.

Block compression is enabled by default.

See also: EnableBlockCompression(), DisableBlockCompression(), CompressionThreshold()

Definition at line 263 of file SettingsData.h.

◆ IsEmpty()

bool pcl::SettingsData::IsEmpty ( ) const

Returns true iff this settings data object is empty, i.e. if there are no key/value pairs stored in this object.

The returned value corresponds to the items currently stored in internal memory data structures. This does not necessarily equals the total number of items currently stored in persistent settings files.

Note: This function is thread-safe.

◆ IsMinifiedXMLEnabled()

bool pcl::SettingsData::IsMinifiedXMLEnabled ( ) const

inline

Returns true iff XML source code minification is currently enabled.

When minification is enabled, XML source code will be generated without superfluous whitespace and newline characters, making it smaller and marginally more efficient for encoding/decoding operations. With minification disabled, XML tags will be separated with newline characters and indented with three spaces, making the source code readable and easily editable.

XML minification is enabled by default.

See also: EnableMinifiedXML(), DisableMinifiedXML()

Definition at line 224 of file SettingsData.h.

◆ IsModified()

bool pcl::SettingsData::IsModified ( ) const

inline

Returns true iff this settings object has been modified.

See also: ModifiedCount()

Definition at line 336 of file SettingsData.h.

◆ Keys()

IsoStringList pcl::SettingsData::Keys ( const IsoString & key ) const

Returns a list with all existing keys rooted at the specified key.

Note: This function is thread-safe.

See also: AllKeys()

◆ Load()

virtual void pcl::SettingsData::Load ( )

virtual

Loads existing valid settings data from persistent storage.

All previously existing settings items stored in internal memory structures will be destroyed and deallocated before loading new data.

Note: This function is thread-safe.; Overriding implementations of this function must call the base class implementation.

◆ ModifiedCount()

int pcl::SettingsData::ModifiedCount ( ) const

inline

Returns the number of modifications performed since the last file load operation.

Modifications happen each time a new key/value pair is added or the value associated with an existing key is modified. The modification count is reset to zero when the settings are cleared, when a settings file is loaded, and when the settings data are saved to a disk file.

See also: IsModified()

Definition at line 326 of file SettingsData.h.

◆ Purge()

virtual void pcl::SettingsData::Purge ( )

virtual

Destroys and deallocates all existing settings items, including all items currently in internal memory data structures as well as all items stored in persistent storage. This yields an empty settings file associated with this object.

Note: This function is thread-safe.; Overriding implementations of this function must call the base class implementation.

◆ Remove()

bool pcl::SettingsData::Remove ( const IsoString & key )

Removes a key/value pair or a subtree of key/value pairs.

This function can be used to remove an existing key/value pair or a subtree rooted at the specified key. No action will be taken if key is not found.

Returns true iff the specified key was found and removed.

Calling this function with key equal to the root specifier "/" will cause no effect and false will be returned. Clear() must be used to remove the entire set of key/value pairs stored in this object in a single operation.

The key will be removed from internal memory data structures, not from persistent settings files. To store settings persistently, the Save() member function must be called for this object.

Note: This function is thread-safe.

◆ Save()

virtual void pcl::SettingsData::Save ( ) const

virtual

Writes all settings key/value pairs stored in this object to persistent file storage.

Note: This function is thread-safe.; Overriding implementations of this function must call the base class implementation.

◆ Search()

Variant pcl::SettingsData::Search ( const IsoString & key ) const

Returns the current value associated with the specified key.

If a key/value pair with the specified key is currently stored in this object, the corresponding value will be returned. If key is not found, or if it corresponds to a structural key (i.e. the root of a subtree of key/value pairs) this function returns an invalid Variant object.

Note: This function is thread-safe.

◆ SetCompressionThreshold()

void pcl::SettingsData::SetCompressionThreshold ( unsigned threshold )

inline

Sets the compression threshold in bytes.

The valid range is from 256 to 65536 bytes.

See also: CompressionThreshold(), IsBlockCompressionEnabled()

Definition at line 310 of file SettingsData.h.

References pcl::Range().

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

SettingsData.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SettingsData()

◆ ~SettingsData()

Member Function Documentation

◆ Add()

◆ AllKeys()

◆ Clear()

◆ CompressionThreshold()

◆ DisableBlockCompression()

◆ DisableMinifiedXML()

◆ EnableBlockCompression()

◆ EnableMinifiedXML()

◆ FileSize()

◆ IsBlockCompressionEnabled()

◆ IsEmpty()

◆ IsMinifiedXMLEnabled()

◆ IsModified()

◆ Keys()

◆ Load()

◆ ModifiedCount()

◆ Purge()

◆ Remove()

◆ Save()

◆ Search()

◆ SetCompressionThreshold()