From 4accc29984b28f6acb0c7290cbd1c94223890040 Mon Sep 17 00:00:00 2001 From: ToruNiina Date: Thu, 14 Feb 2019 16:47:15 +0900 Subject: [PATCH] chore: update README --- PROPOSAL.md | 59 ----------------------------- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 59 deletions(-) delete mode 100644 PROPOSAL.md diff --git a/PROPOSAL.md b/PROPOSAL.md deleted file mode 100644 index bbdc424..0000000 --- a/PROPOSAL.md +++ /dev/null @@ -1,59 +0,0 @@ - -### encoding user's data - -You can encode your data to toml format. - -```cpp -const toml::value integer(1); -const toml::value array{3.1, 3.14, 3.141, 3.1415}; -const toml::value table{{"answer", 42}, {"pi", 3.14}, {"string", "foobar"}}; - -std::cout << toml::format("integer", integer) << std::endl; -std::cout << toml::format("array", array) << std::endl; -std::cout << toml::format("table", table) << std::endl; -``` - -this program will output as below. - -```toml -integer = 1 -array = [3.1, 3.14, 3.141, 3.1415] -[table] -answer = 42 -pi = 3.14 -string = "foobar" -``` - -Without key name, you can make string formatted as toml. - -```cpp -const std::string integer_ = toml::format(integer); // "1" -const std::string array_ = toml::format(array); // "[3.1, 3.14, 3.141, 3.1415]" -const std::string table_ = toml::format(table); // "answer = 42\npi=3.14\nstring=foobar" -``` - -### inlinize - -You can make `toml::Table` inline. - -```cpp -const toml::value table{{"answer", 42}, {"pi", 3.14}, {"string", "foobar"}}; -// if the inline-table format length is less than 80, the table will be inlined -std::cout << toml::format("table", table, toml::make_inline(80)) << std::endl; -// In any case, the table will be inlined. -std::cout << toml::format("table", table, toml::forceinline) << std::endl; -``` - -```toml -table = {answer = 42, pi = 3.14, string = "foobar"} -``` - -And there are some stream manipulators for toml format. - -```cpp -const toml::value table{{"answer", 42}, {"pi", 3.14}, {"string", "foobar"}}; -// if the inline-table format length is less than 80, the table will be inlined -std::cout << toml::make_inline(80) << table << std::endl; -// In any case, the table will be inlined. -std::cout << toml::forceinline << table << std::endl; -``` diff --git a/README.md b/README.md index ab950b6..d26cc2e 100644 --- a/README.md +++ b/README.md @@ -423,6 +423,22 @@ int i = 0; toml::from_toml(i, data.at("something")); ``` +### visiting toml::value + +TOML v2.1.0+ provides `toml::visit` to apply a function to `toml::value` in the +same way as `std::variant`. + +```cpp +const toml::value v(3.14); +toml::visit([](const auto& val) -> void { + std::cout << val << std::endl; + }, v); +``` + +The function object that would be passed to `toml::visit` must be able to +recieve all the possible TOML types. Also, the result types should be the same +each other. + ### Sanitizing UTF-8 codepoints toml11 shows warning if a value of an escape sequence used @@ -498,6 +514,97 @@ you will get an error message like this. | ~~ maximum number here ``` +### Serializing TOML data + +toml11 v2.1.0 enables you to serialize data into toml format. + +```cpp +const auto data = toml::table{{"foo", 42}, {"bar", "baz"}}; + +const std::string serial = toml::format(data); +assert(serial == "bar = \"baz\"\nfoo = 42"); + +std::cout << data << std::endl; +// bar = "baz" +// foo = 42 +``` + +toml11 automatically makes a tiny table and array inline. +You can specify the width to make them inline by `std::setw` for streams. + +```cpp +const auto data = toml::table{ + {"qux", toml::table{{"foo", 42}, {"bar", "baz"}}}, + {"quux", toml::array{"small", "array", "of", "strings"}}, + {"foobar", toml::array{"this", "array", "of", "strings", "is", "too", "long", + "to", "print", "into", "single", "line", "isn't", "it?"}}, +}; + +// the threshold becomes 80. +std::cout << std::setw(80) << data << std::endl; +// foobar = [ +// "this","array","of","strings","is","too","long","to","print","into", +// "single","line","isn't","it?", +// ] +// quux = ["small","array","of","strings"] +// qux = {bar="baz",foo=42} + + +// the width is 0. nothing become inline. +std::cout << std::setw(0) << data << std::endl; +// foobar = [ +// "this", +// ... (snip) +// "it?", +// ] +// quux = [ +// "small", +// "array", +// "of", +// "strings", +// ] +// [qux] +// bar = "baz" +// foo = 42 +``` + +It is recommended to set width before printing data. Some I/O functions changes +width to 0, and it makes all the stuff (including `toml::array`) multiline. +The resulting files becomes too long. + +`toml::format` receives optional second argument to set the width. +By default, it is 80. + +```cpp +const auto data = toml::table{ + {"qux", toml::table{{"foo", 42}, {"bar", "baz"}}} +}; + +const std::string serial = toml::format(data, /*width = */ 0); +// [qux] +// bar = "baz" +// foo = 42 +``` + +To control the precision of floating point numbers, you need to pass +`std::setprecision` to stream or pass `int` to the optional third argument of +`toml::format` (by default, it is `std::numeric_limits::max_digit10`). + +```cpp +const auto data = toml::table{ + {"pi", 3.141592653589793}, + {"e", 2.718281828459045} +}; +std::cout << std::setprecision(17) << data << std::endl; +// e = 2.7182818284590451 +// pi = 3.1415926535897931 +std::cout << std::setprecision( 7) << data << std::endl; +// e = 2.718282 +// pi = 3.141593 + +const std::string serial = toml::format(data, /*width = */ 0, /*prec = */ 17); +``` + ## Underlying types The toml types (can be used as `toml::*` in this library) and corresponding `enum` names are listed in the table below.