Merge branch 'main' into v4_1_0

docs/content.en/docs/features/parsing_files.md

@@ -42,10 +42,18 @@ int main()
 }
 ```
 
+#### Specifying a File with `std::filesystem::path`
+
+[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can accept a `std::filesystem::path`.
+
+This requires C++17 or later, as it relies on the `<filesystem>` support.
+
 #### Specifying an Input Stream with `std::istream`
 
 [`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept an `std::istream`.
 
+Open a stream in binary mode by passing `std::ios::binary` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
 Without the filename information, error messages will display `"unknown file"`. To avoid this, you can pass the filename as a `std::string` in the second argument when using `std::istream`.
 
 You can use streams other than `std::ifstream`, such as `std::istringstream`. Note that the entire content is readable at the time of the call.
@@ -64,16 +72,12 @@ int main()
 }
 ```
 
-#### Specifying a File with `std::filesystem::path`
-
-[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can accept a `std::filesystem::path`.
-
-This requires C++17 or later, as it relies on the `<filesystem>` support.
-
 #### Specifying a File with `FILE*`
 
 [`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept a `FILE*`.
 
+Open a stream in binary mode by passing `"rb"` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
 As with `std::istream`, you need to provide the filename as a string in the second argument.
 
 When passing a `FILE*`, if the file read fails, `errno` will be reported.

docs/content.en/docs/installation/_index.md

@@ -54,6 +54,14 @@ By defining `-DTOML11_PRECOMPILE=ON` when running cmake, you can precompile some
 $ cmake -B ./build/ -DTOML11_PRECOMPILE=ON
 ```
 
+When linking the library, use `target_link_libraries` in CMake
+
+```cmake
+target_link_libraries(your_target PUBLIC toml11::toml11)
+```
+
+or pass `-DTOML11_COMPILE_SOURCES` to the compiler to suppress header-only features.
+
 However, since toml11 supports multiple C++ versions and may switch types based on the value of `__cplusplus`,
 there is a possibility of link failures if the version used during build differs from the version used during usage.
 If you encounter issues, set the required version using `CMAKE_CXX_STANDARD` during compilation.

docs/content.en/docs/reference/parser.md

@@ -17,23 +17,6 @@ In case of failure, `toml::syntax_error` is thrown.
 
 The type information of `basic_value` is provided by a `template`, and the TOML language version is specified by `toml::spec`.
 
-### `parse(std::istream&, std::string filename, toml::spec)`
-
-```cpp
-namespace toml
-{
-template<typename TC = type_config>
-basic_value<TC>
-parse(std::istream& is,
-      std::string fname = "unknown file",
-      spec s = spec::default_version());
-}
-```
-
-Parses the content of the given `std::istream&`.
-
-The filename information is taken as the third argument. If the filename is not provided, it defaults to `"unknown file"`.
-
 ### `parse(std::string filename, toml::spec)`
 
 ```cpp
@@ -90,6 +73,25 @@ If reading the file fails, `toml::file_io_error` is thrown.
 
 If parsing fails, `toml::syntax_error` is thrown.
 
+### `parse(std::istream&, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+basic_value<TC>
+parse(std::istream& is,
+      std::string fname = "unknown file",
+      spec s = spec::default_version());
+}
+```
+
+Parses the content of the given `std::istream&`.
+
+Open a stream in binary mode by passing `std::ios::binary` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
+The filename information is taken as the third argument. If the filename is not provided, it defaults to `"unknown file"`.
+
 ### `parse(FILE*, std::string filename, toml::spec)`
 
 ```cpp
@@ -105,6 +107,8 @@ parse(FILE* fp,
 
 Parses the content of the file pointed to by `FILE*`.
 
+Open a stream in binary mode by passing `"rb"` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
 If reading the file fails, `file_io_error` containing `errno` is thrown.
 
 If parsing fails, `syntax_error` is thrown.
@@ -166,27 +170,6 @@ For instance, errors occurring internally within `std::ifstream` or memory exhau
 
 {{< /hint >}}
 
-### `try_parse(std::istream&, std::string filename, toml::spec)`
-
-```cpp
-namespace toml
-{
-template<typename TC = type_config>
-result<basic_value<TC>, std::vector<error_info>>
-try_parse(std::istream& is,
-          std::string fname = "unknown file",
-          spec s = spec::default_version());
-}
-```
-
-Takes a `std::istream&` and parses its content.
-
-The file name information is taken as the second argument. If a file name is not provided, it defaults to `"unknown file"`.
-
-If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
-
-If successful, a `result` holding a `basic_value` is returned.
-
 ### `try_parse(std::string filename, toml::spec)`
 
 ```cpp
@@ -241,6 +224,29 @@ If parsing fails, a `result` holding the error type `std::vector<error_info>` is
 
 If successful, a `result` holding a `basic_value` is returned.
 
+### `try_parse(std::istream&, std::string filename, toml::spec)`
+
+```cpp
+namespace toml
+{
+template<typename TC = type_config>
+result<basic_value<TC>, std::vector<error_info>>
+try_parse(std::istream& is,
+          std::string fname = "unknown file",
+          spec s = spec::default_version());
+}
+```
+
+Takes a `std::istream&` and parses its content.
+
+Open a stream in binary mode by passing `std::ios::binary` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
+The file name information is taken as the second argument. If a file name is not provided, it defaults to `"unknown file"`.
+
+If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
+
+If successful, a `result` holding a `basic_value` is returned.
+
 ### `try_parse(FILE*, std::string filename, toml::spec)`
 
 ```cpp
@@ -256,6 +262,8 @@ try_parse(FILE* fp,
 
 Takes a `FILE*` and parses its content.
 
+Open a stream in binary mode by passing `"rb"` to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.
+
 If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
 
 If successful, a `result` holding a `basic_value` is returned.