xtd::configuration::file_settings Class Reference

Inheritance diagram for xtd::configuration::file_settings:

Definition

Represents an object for storing and retrieving configuration information using text files in INI format.

Header

#include <xtd/configuration/file_settings>

Namespace

xtd

Library

xtd.core

Remarks

An INI file is a configuration file that consists of a text-based content with a structure and syntax comprising key–value pairs for properties, and sections that organize the properties.

Examples

The following code example demonstrates the use of xtd::configuration::file_settings class.

#include <xtd/xtd>
 
auto write_file_settings() {
  auto file = configuration::file_settings {"example.ini"};
  file.top_file_comment("Settings file used by file_settings example.\nCopyright (c) 2024 Gammasoft. All rights reserved.");
  file.write("auto_close", true);
  file.write("caption", "file_settings example");
  file.write("Thread \"Process\"", "timeout", 100_ms);
  file.save();
}
 
auto reset_file_settings() {
  auto file = configuration::file_settings {"example.ini"};
  file.reset();
}
 
auto read_file_settings() {
  auto file = configuration::file_settings {"example.ini"};
  console::write_line("----------------------------------------");
  console::write_line("\"exemple.ini\" file content :");
  console::write_line(file.to_string());
  console::write_line("----------------------------------------");
  console::write_line("read keys :");
  console::write_line("auto_close = {}", file.read("auto_close", false));
  console::write_line("caption = {}", file.read("caption", "example"));
  console::write_line("Thread \"Process\"", "time_out = {}", file.read("timeout", 50_ms));
  console::write_line("----------------------------------------");
}
 
auto main() -> int {
  write_file_settings();
  // Uncomment the following line to see what happens if the "example.ini" file doesn't exist.
  //reset_file_settings();
  read_file_settings();
}
 
// This code produces the following output :
//
// ----------------------------------------
// "exemple.ini" file content :
// # Settings file used by file_settings example.
// # Copyright (c) 2024 Gammasoft. All rights reserved.
//
// auto_close = true
// caption = file_settings example
//
// [Thread "Process"]
// timeout = 00:00:00.1000000
//
// ----------------------------------------
// read keys :
// auto_close = true
// caption = file_settings example
// Thread "Process"
// ----------------------------------------

Protected Member Functions
virtual auto	convert_comment_to_text (const xtd::string &text) const noexcept -> xtd::string
virtual auto	convert_text_to_comment (const xtd::string &text) const noexcept -> xtd::string

Public Aliass
using	string_dictionary
	Represents a xtd::collections::generic::sorted_dictionary with the key and the value strongly typed to be strings.
using	string_collection
	Represents a collection of strings.

Public Constructors
	file_settings () noexcept=default
	Initialize an xtd::configuration::file_settings without loading a file.
	file_settings (const xtd::string &file_path)
	Initialize an xtd::configuration::file_settings with file path to load and save.
	file_settings (std::iostream &stream)
	Initialize an xtd::configuration::file_settings with a stream to load and save.

Public Properties
auto	auto_save () const noexcept -> bool
	Gets whether save should be called on the xtd::configuration::file_settings destructor.
auto	auto_save (bool value) noexcept -> void
	Sets whether save should be called on the xtd::configuration::file_settings destructor.
auto	bottom_file_comment () const noexcept -> xtd::string
	Gets bottom file comment text.
auto	bottom_file_comment (const xtd::string &value) noexcept -> file_settings &
	Sets bottom file comment text.
auto	file_path () const noexcept -> const xtd::string &
	Gets the file path of the current instance.
auto	key_values () const noexcept -> string_dictionary
	Gets all key-value pairs from global section.
auto	key_values (const xtd::string &section) const noexcept -> string_dictionary
	Gets all key-value pairs from a specified section.
auto	keys () const noexcept -> string_collection
	Gets all keys from global section.
auto	keys (const xtd::string &section) const noexcept -> string_collection
	Gets all keys from a specified section.
auto	sections () const noexcept -> string_collection
	Gets all sections.
auto	stream () const noexcept -> std::optional< xtd::ref< std::iostream > >
	Gets the stream of the current instance.
auto	top_file_comment () const noexcept -> xtd::string
	Gets top file comment text.
auto	top_file_comment (const xtd::string &value) noexcept -> file_settings &
	Sets top file comment text.

Public Methods
auto	equals (const xtd::object &obj) const noexcept -> bool override
	Indicates whether the current object is equal to another object of the same type.
auto	equals (const file_settings &other) const noexcept -> bool override
	Indicates whether the current object is equal to another object of the same type.
virtual auto	from_string (const xtd::string &text) -> void
	Sets the current settings with parsing the xtd::string in INI format.
auto	load (const xtd::string &file_path) -> void
	Loads settings from specified file.
auto	load (std::istream &stream) -> void
	Loads settings from specified stream.
auto	read (const xtd::string &key, const xtd::string &default_value) noexcept -> xtd::string
	Reads a value for specified key in the global section. If not found default value is used.
template<class type_t>
auto	read (const xtd::string &key, const type_t &default_value) -> type_t
	Reads a value for specified key in the global section. If not found default value is used.
auto	read (const xtd::string &section, const xtd::string &key, const xtd::string &default_value) noexcept -> xtd::string
	Reads a value for specified key in the specified section. If not found default value is used.
template<class type_t>
auto	read (const xtd::string &section, const xtd::string &key, const type_t &default_value) -> type_t
	Reads a value for specified key in the specified section. If not found default value is used.
auto	remove (const xtd::string &key) noexcept -> void
	Removes the specified key from the global section.
auto	remove (const xtd::string &section, const xtd::string &key) noexcept -> void
	Removes the specified key from the specified section.
auto	remove_all_keys () noexcept -> void
	Removes all keys from the global section.
auto	remove_all_keys (const xtd::string &section) noexcept -> void
	Removes all key from the specified section.
auto	reset () -> void
	Reset current settings.
auto	save () -> void
	Save current settings.
auto	save_as (const xtd::string &file_path) -> void
	Save current settings in the specified file path.
auto	save_as (std::ostream &stream) -> void
	Save current settings in the specified stream.
auto	to_string () const noexcept -> xtd::string override
	Returns a xtd::string that represents the current setting in INI format.
auto	write (const xtd::string &key, const xtd::string &value) noexcept -> void
	Writes a specified value for specified key in the global section.
template<class type_t>
auto	write (const xtd::string &key, type_t &&value) -> void
	Writes a specified value for specified key in the global section.
auto	write (const xtd::string &section, const xtd::string &key, const xtd::string &value) noexcept -> void
	Writes a specified value for specified key in the specified section.
template<class type_t>
auto	write (const xtd::string &section, const xtd::string &key, type_t &&value) -> void
	Writes a specified value for specified key in the specified section.

Public Operators
auto	operator[] (const xtd::string &section) const noexcept -> const string_dictionary &
	Gets key-value pairs of the specified section.
auto	operator[] (const xtd::string &section) noexcept -> string_dictionary &
	Gets key-value pairs of the specified section.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual bool	equals (const file_settings &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Member Typedef Documentation

string_dictionary

using xtd::configuration::file_settings::string_dictionary

Represents a xtd::collections::generic::sorted_dictionary with the key and the value strongly typed to be strings.

string_collection

using xtd::configuration::file_settings::string_collection

Represents a collection of strings.

Constructor & Destructor Documentation

file_settings() [1/3]

xtd::configuration::file_settings::file_settings ( )

defaultnoexcept

Initialize an xtd::configuration::file_settings without loading a file.

Remarks

The xtd::configuration::file_settings::save method has no effect.

This is equivalent to using the xtd::configuration::file_settings constructor with an empty string as the file path.

file_settings() [2/3]

xtd::configuration::file_settings::file_settings ( const xtd::string & file_path )

explicit

Initialize an xtd::configuration::file_settings with file path to load and save.

Parameters

file_path

the file path to load and save.

Remarks

If the xtd::configuration::file_settings::auto_save is true the xtd::configuration::file_settings::save is called on the xtd::configuration::file_settings destructor; otherwise not, The xtd::configuration::file_settings::save method must be called manually.

xtd::configuration::file_settings::auto_save is false by default.

If the file path is empty, this is equivalent to using the xtd::configuration::file_settings constructor with no parameters.

file_settings() [3/3]

xtd::configuration::file_settings::file_settings ( std::iostream & stream )

explicit

Initialize an xtd::configuration::file_settings with a stream to load and save.

Parameters

stream

the stream to load and save.

Remarks

If the xtd::configuration::file_settings::auto_save is true the xtd::configuration::file_settings::save is called on the xtd::configuration::file_settings destructor; otherwise not, The xtd::configuration::file_settings::save method must be called manually.

xtd::configuration::file_settings::auto_save is false by default.

If the stream is empty, this is equivalent to using the xtd::configuration::file_settings constructor with no parameters.

Member Function Documentation

auto_save() [1/2]

auto xtd::configuration::file_settings::auto_save ( ) const -> bool

nodiscardnoexcept

Gets whether save should be called on the xtd::configuration::file_settings destructor.

Returns

true if xtd::configuration::file_settings::save is called on the xtd::configuration::file_settings destructor; otherwise, false.

Remarks

The default is false.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::auto_save property, xtd::configuration::file_settings::write methods.

auto file = file_settings {"my_app.ini"};
file.auto_save(true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

auto_save() [2/2]

auto xtd::configuration::file_settings::auto_save ( bool value ) -> void

noexcept

Sets whether save should be called on the xtd::configuration::file_settings destructor.

Parameters

value

true if xtd::configuration::file_settings::save is called on the xtd::configuration::file_settings destructor; otherwise, false.

Remarks

The default is false.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::auto_save property, xtd::configuration::file_settings::write methods.

auto file = file_settings {"my_app.ini"};
file.auto_save(true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

bottom_file_comment() [1/2]

auto xtd::configuration::file_settings::bottom_file_comment ( ) const -> xtd::string

nodiscardnoexcept

Gets bottom file comment text.

Returns

Bottom file comment text.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::bottom_file_comment property, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.bottom_file_comment("Modifications must be made with care, as they may result in incorrect behavior.");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini")

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png
 
# Modifications must be made with care, as they may result in incorrect behavior.

bottom_file_comment() [2/2]

auto xtd::configuration::file_settings::bottom_file_comment ( const xtd::string & value ) -> file_settings &

noexcept

Sets bottom file comment text.

Parameters

value

Bottom file comment text.

Returns

This current instance.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::bottom_file_comment property, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.bottom_file_comment("Modifications must be made with care, as they may result in incorrect behavior.");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini");

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png
 
# Modifications must be made with care, as they may result in incorrect behavior.

file_path()

auto xtd::configuration::file_settings::file_path ( ) const -> const xtd::string &

nodiscardnoexcept

Gets the file path of the current instance.

Returns

The file path of the current instance.

Remarks

If no file the property can be return xtd::string::empty_string.

Warning

Don't manipulate the file yourself, otherwise the expected result may be undefined.

key_values() [1/2]

auto xtd::configuration::file_settings::key_values ( ) const -> string_dictionary

nodiscardnoexcept

Gets all key-value pairs from global section.

Returns

The key-value pairs map.

Remarks

This method is equivalent to call xtd::configuration::file_settings::key_values (const xtd::string& section) with xtd::string::empty_string paramreter.

key_values() [2/2]

auto xtd::configuration::file_settings::key_values ( const xtd::string & section ) const -> string_dictionary

nodiscardnoexcept

Gets all key-value pairs from a specified section.

Parameters

section

The section to get key-value pairs.

Returns

The key-value pairs map from the specified section.

Remarks

Use xtd::string::empty_string paramreter to get key-value pairs of the global section.

keys() [1/2]

auto xtd::configuration::file_settings::keys ( ) const -> string_collection

nodiscardnoexcept

Gets all keys from global section.

Returns

The keys colection.

Remarks

This method is equivalent to call xtd::configuration::file_settings::keys (const xtd::string& section) with xtd::string::empty_string paramreter.

keys() [2/2]

auto xtd::configuration::file_settings::keys ( const xtd::string & section ) const -> string_collection

nodiscardnoexcept

Gets all keys from a specified section.

Parameters

section

The section to get keys.

Returns

The keys collection from the specified section.

Remarks

Use xtd::string::empty_string paramreter to get keys of the global section.

sections()

auto xtd::configuration::file_settings::sections ( ) const -> string_collection

nodiscardnoexcept

Gets all sections.

Returns

The sections colection.

stream()

auto xtd::configuration::file_settings::stream ( ) const -> std::optional< xtd::ref< std::iostream > >

nodiscardnoexcept

Gets the stream of the current instance.

Returns

The stream of the current instance.

Warning

Don't manipulate the stream yourself, otherwise the expected result may be undefined.

top_file_comment() [1/2]

auto xtd::configuration::file_settings::top_file_comment ( ) const -> xtd::string

nodiscardnoexcept

Gets top file comment text.

Returns

Top file comment textr.

Remarks

Generally used to read descriptions of the xtd::configuration::file_settings : authors, copyright, version, etc.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::top_file_comment property, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.top_file_comment("Contains settings for my_app application.\nCopyright, (c) 2026 MyCompany. All rights reserved.");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini");

my_app.ini:

# Contains settings for my_app application.
# Copyright, (c) 2026 MyCompany. All rights reserved.
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

top_file_comment() [2/2]

auto xtd::configuration::file_settings::top_file_comment ( const xtd::string & value ) -> file_settings &

noexcept

Sets top file comment text.

Parameters

value

Top file comment textr.

Returns

This current instance.

Remarks

Generally used to write descriptions of the xtd::configuration::file_settings : authors, copyright, version, etc.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::top_file_comment property, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.top_file_comment("Contains settings for my_app application.\nCopyright, (c) 2026 MyCompany. All rights reserved.");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini");

my_app.ini:

# Contains settings for my_app application.
# Copyright, (c) 2026 MyCompany. All rights reserved.
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

equals() [1/2]

auto xtd::configuration::file_settings::equals ( const xtd::object & obj ) const -> bool

nodiscardoverridevirtualnoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters

obj	An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

Reimplemented from xtd::object.

equals() [2/2]

auto xtd::configuration::file_settings::equals ( const file_settings & other ) const -> bool

nodiscardoverridenoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters

other

An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

from_string()

virtual auto xtd::configuration::file_settings::from_string ( const xtd::string & text ) -> void

virtual

Sets the current settings with parsing the xtd::string in INI format.

Parameters

text	A text to set the current setting.

Notes to inheritors

To create your own file_settings with another format, you just need to override the xtd::configuration::file_settings::from_string and xtd::configuration::file_settings::to_string methods.

load() [1/2]

auto xtd::configuration::file_settings::load

(

const xtd::string &

file_path

)

-> void

Loads settings from specified file.

Parameters

file_path

The file path to load settings.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::load, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.load("my_app.ini");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini");

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

load() [2/2]

auto xtd::configuration::file_settings::load

(

std::istream &

stream

)

-> void

Loads settings from specified stream.

Parameters

stream

The stream to load settings.

read() [1/4]

auto xtd::configuration::file_settings::read ( const xtd::string & key, const xtd::string & default_value ) -> xtd::string

nodiscardnoexcept

Reads a value for specified key in the global section. If not found default value is used.

Parameters

key	The key used to read a value.
default_value	A string used if value not found.

Returns

A string that represent the value associate to the key.

Remarks

Use xtd::string::empty_string for section paramreter to read keys of the global section.

This method is equivalent to call xtd::configuration::file_settings::read (const xtd::string& section, const xtd::string& key, const xtd::string& default_value) with xtd::string::empty_string paramreter as section parameter.

read() [2/4]

template<class type_t>

auto xtd::configuration::file_settings::read ( const xtd::string & key, const type_t & default_value ) -> type_t

inlinenodiscard

Reads a value for specified key in the global section. If not found default value is used.

Parameters

key	The key used to read a value.
default_value	A string used if value not found.

Returns

A string that represent the value associate to the key.

Remarks

Use xtd::string::empty_string for section paramreter to read keys of the global section.

This method is equivalent to call xtd::configuration::file_settings::read (const xtd::string& section, const xtd::string& key, const xtd::string& default_value) with xtd::string::empty_string paramreter as section parameter.

read() [3/4]

auto xtd::configuration::file_settings::read ( const xtd::string & section, const xtd::string & key, const xtd::string & default_value ) -> xtd::string

nodiscardnoexcept

Reads a value for specified key in the specified section. If not found default value is used.

Parameters

section	The section where the key is read.
key	The key used to read a value.
default_value	A string used if value not found.

Returns

A string that represent the value associate to the key.

Remarks

Use xtd::string::empty_string for section paramreter to read keys of the global section.

read() [4/4]

template<class type_t>

auto xtd::configuration::file_settings::read ( const xtd::string & section, const xtd::string & key, const type_t & default_value ) -> type_t

inlinenodiscard

Reads a value for specified key in the specified section. If not found default value is used.

Parameters

section	The section where the key is read.
key	The key used to read a value.
default_value	A string used if value not found.

Returns

A string that represent the value associate to the key.

Remarks

Use xtd::string::empty_string for section paramreter to read keys of the global section.

remove() [1/2]

auto xtd::configuration::file_settings::remove ( const xtd::string & key ) -> void

noexcept

Removes the specified key from the global section.

Parameters

key	The key to remove from the global section.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

This method is equivalent to call xtd::configuration::file_settings::remove (const xtd::string& section) with xtd::string::empty_string paramreter.

Removes the specified key from the specified section.

Parameters

section	The section where the key is removed.
key	The key to remove from the specified section.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Use xtd::string::empty_string paramreter to remove key of the global section.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write, xtd::configuration::file_settings::remove and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write(quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.remove("quit_application_on_main_form_closed");
file.save();

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

remove() [2/2]

auto xtd::configuration::file_settings::remove ( const xtd::string & section, const xtd::string & key ) -> void

noexcept

Removes the specified key from the specified section.

Parameters

section	The section where the key is removed.
key	The key to remove from the specified section.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Use xtd::string::empty_string paramreter to remove key of the global section.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write, xtd::configuration::file_settings::remove and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.remove("main", "quit_application_on_main_form_closed");
file.save();

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

remove_all_keys() [1/2]

auto xtd::configuration::file_settings::remove_all_keys ( ) -> void

noexcept

Removes all keys from the global section.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

This method is equivalent to call xtd::configuration::file_settings::remove_all_keys (const xtd::string& section) with xtd::string::empty_string paramreter.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write, xtd::configuration::file_settings::remove_all_keys and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.remove_all_keys();
file.save();

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

remove_all_keys() [2/2]

auto xtd::configuration::file_settings::remove_all_keys ( const xtd::string & section ) -> void

noexcept

Removes all key from the specified section.

Parameters

section

The section where all keys are removed.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Use xtd::string::empty_string paramreter to remove all keys of the global section.

Use xtd::string::empty_string paramreter to remove key of the global section.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write, xtd::configuration::file_settings::remove_all_keys and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.remove_all_keys("pictures \"Menu\"");
file.save()

my_app.ini:

[main]
quit_application_on_main_form_closed = true

reset()

auto xtd::configuration::file_settings::reset

(

)

-> void

Reset current settings.

Remarks

The settings are cleared and the settings file is removed.

To write permanently use the xtd::configuration::settings::save method.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

[main]
quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

save()

auto xtd::configuration::file_settings::save

(

)

-> void

Save current settings.

Remarks

The settings are saved in the settings file.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

[main]
quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

save_as() [1/2]

auto xtd::configuration::file_settings::save_as

(

const xtd::string &

file_path

)

-> void

Save current settings in the specified file path.

Parameters

file_path

The file to save the current settings.

Remarks

The settings are saved in the specified settings file.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::write and xtd::configuration::file_settings::save_as methods.

auto file = file_settings {};
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save_as("my_app.ini")

my_app.ini:

[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

save_as() [2/2]

auto xtd::configuration::file_settings::save_as

(

std::ostream &

stream

)

-> void

Save current settings in the specified stream.

Parameters

stream

The stream to save the current settings.

Remarks

The settings are saved in the specified settings stream.

to_string()

auto xtd::configuration::file_settings::to_string ( ) const -> xtd::string

nodiscardoverridevirtualnoexcept

Returns a xtd::string that represents the current setting in INI format.

Returns

A string that represents the current setting.

Notes to inheritors

To create your own file_settings with another format, you just need to override the xtd::configuration::file_settings::from_string and xtd::configuration::file_settings::to_string methods.

Reimplemented from xtd::object.

write() [1/4]

auto xtd::configuration::file_settings::write ( const xtd::string & key, const xtd::string & value ) -> void

noexcept

Writes a specified value for specified key in the global section.

Parameters

key	The key used to write a value.
value	A string to write.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("quit_application_on_main_form_closed", "true");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

write() [2/4]

template<class type_t>

auto xtd::configuration::file_settings::write ( const xtd::string & key, type_t && value ) -> void

inline

Writes a specified value for specified key in the global section.

Parameters

key	The key used to write a value.
value	A string to write.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

write() [3/4]

auto xtd::configuration::file_settings::write ( const xtd::string & section, const xtd::string & key, const xtd::string & value ) -> void

noexcept

Writes a specified value for specified key in the specified section.

Parameters

section	The section where the key is write.
key	The key used to write a value.
value	A string to write.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("quit_application_on_main_form_closed", "true");
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png");
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

write() [4/4]

template<class type_t>

auto xtd::configuration::file_settings::write ( const xtd::string & section, const xtd::string & key, type_t && value ) -> void

inline

Writes a specified value for specified key in the specified section.

Parameters

section	The section where the key is write.
key	The key used to write a value.
value	A string to write.

Remarks

To write permanently use the xtd::configuration::file_settings::save method.

Examples

The following example shows how to create xtd::configuration::file_settings and use xtd::configuration::file_settings::reset, xtd::configuration::file_settings::write and xtd::configuration::file_settings::save methods.

auto file = file_settings {"my_app.ini"};
file.reset();
file.write("main", "quit_application_on_main_form_closed", true);
file.write("pictures \"Menu\"", "file_open", "resources/symbolic_open.png")
file.write("pictures \"Menu\"", "file_save", "resources/symbolic_save.png");
file.save();

my_app.ini:

[main]
quit_application_on_main_form_closed = true
 
[pictures "Menu"]
file_open = resources/symbolic_open.png
file_save = resources/symbolic_save.png

operator[]() [1/2]

auto xtd::configuration::file_settings::operator[] ( const xtd::string & section ) const -> const string_dictionary &

noexcept

Gets key-value pairs of the specified section.

Parameters

secion

The section to get the key-value pairs

Returns

The key-value pairs of the section.

Examples

Use this operator to read value from section like xtd::configuration::file_settings::read method.

auto fs = file_settings {"my_file.ini"};
auto v1 = fs["section1"]["key1"];
// Is equivalent to call :
// auto v1 = fs.read("section1", "key1", string::empty_string);

operator[]() [2/2]

auto xtd::configuration::file_settings::operator[] ( const xtd::string & section ) -> string_dictionary &

noexcept

Gets key-value pairs of the specified section.

Parameters

secion

The section to get the key-value pairs

Returns

The key-value pairs of the section.

Examples

Use this operator to write value to section like xtd::configuration::file_settings::write method.

auto fs = file_settings {"my_file.ini"};
fs["section1"]["key1"] = "value1";
// Is equivalent to call :
// fs.write("section1", "key1", "value1");

---

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

• xtd.core/include/xtd/configuration/file_settings.hpp