diff --git a/docs/content.en/docs/features/parsing_files.md b/docs/content.en/docs/features/parsing_files.md index 9239cb9..77a9be4 100644 --- a/docs/content.en/docs/features/parsing_files.md +++ b/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 `` 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 `` 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. diff --git a/docs/content.en/docs/reference/parser.md b/docs/content.en/docs/reference/parser.md index 3b83564..1736139 100644 --- a/docs/content.en/docs/reference/parser.md +++ b/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 -basic_value -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 +basic_value +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 -result, std::vector> -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` 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` is If successful, a `result` holding a `basic_value` is returned. +### `try_parse(std::istream&, std::string filename, toml::spec)` + +```cpp +namespace toml +{ +template +result, std::vector> +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` 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` is returned. If successful, a `result` holding a `basic_value` is returned. diff --git a/docs/content.ja/docs/features/parsing_files.md b/docs/content.ja/docs/features/parsing_files.md index d917f6c..0308bd3 100644 --- a/docs/content.ja/docs/features/parsing_files.md +++ b/docs/content.ja/docs/features/parsing_files.md @@ -44,11 +44,21 @@ int main() } ``` +#### `std::filesystem::path`でファイルを指定する + +[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) +には、`std::filesystem::path`を渡すことも可能です。 + +当然ですが、``がサポートされるC++17以降でなければ使用できません。 + #### `std::istream`で入力ストリームを指定する [`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) には、`std::istream`を渡すことも可能です。 +標準ライブラリが改行文字を自動変換することによるファイルサイズと文字数との不整合を避けるため、 +`std::ios::binary`を使ってバイナリモードで開いてください。 + その際、ファイル名の情報がなくなるため、エラーメッセージ中では `"unknown file"` となります。 これを避けるため、 `std::istream` を取る場合は第二引数に `std::string` でファイル名を取ることもできます。 @@ -70,18 +80,14 @@ int main() } ``` -#### `std::filesystem::path`でファイルを指定する - -[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) -には、`std::filesystem::path`を渡すことも可能です。 - -当然ですが、``がサポートされるC++17以降でなければ使用できません。 - #### `FILE*`でファイルを指定する [`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) には、`FILE*`を渡すことも可能です。 +標準ライブラリによる改行文字の自動変換によるファイルサイズと文字数との不整合を避けるため、 +`fopen("example.toml", "rb")`のようにしてバイナリモードで開いてください。 + この場合も、`std::istream`のときと同様に、第二引数に文字列でファイル名を与える必要があります。 `FILE*`を渡した場合、ファイルの読み込みに失敗した際には`errno`が報告されます。 diff --git a/docs/content.ja/docs/reference/parser.md b/docs/content.ja/docs/reference/parser.md index e9465a8..d9cdc99 100644 --- a/docs/content.ja/docs/reference/parser.md +++ b/docs/content.ja/docs/reference/parser.md @@ -17,23 +17,6 @@ type = "docs" `basic_value`の持つ型情報は`template`で、TOML言語のバージョンは`toml::spec`で指定します。 -### `parse(std::istream&, std::string filename, toml::spec)` - -```cpp -namespace toml -{ -template -basic_value -parse(std::istream& is, - std::string fname = "unknown file", - spec s = spec::default_version()); -} -``` - -`std::istream&`を受け取ってその内容をパースします。 - -ファイル名の情報は第三引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。 - ### `parse(std::string filename, toml::spec)` ```cpp @@ -90,6 +73,25 @@ parse(const std::filesystem::path& fpath, パースに失敗した場合、`syntax_error`が送出されます。 +### `parse(std::istream&, std::string filename, toml::spec)` + +```cpp +namespace toml +{ +template +basic_value +parse(std::istream& is, + std::string fname = "unknown file", + spec s = spec::default_version()); +} +``` + +`std::istream&`を受け取ってその内容をパースします。 + +標準ライブラリが改行文字を自動変換することによるファイルサイズと文字数との不整合を避けるため、 +`std::ios::binary`を使ってバイナリモードで開いてください。 + +ファイル名の情報は第三引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。 ### `parse(FILE*, std::string filename, toml::spec)` @@ -106,6 +108,9 @@ parse(FILE* fp, `FILE*`が指すファイルを読み込んでパースします。 +標準ライブラリが改行文字を自動変換することによるファイルサイズと文字数との不整合を避けるため、 +`fopen`には`"rb"`などを渡してバイナリモードで開いてください。 + ファイルの読み込みに失敗した場合、`errno`が含まれた`file_io_error`が送出されます。 パースに失敗した場合、`syntax_error`が送出されます。 @@ -167,28 +172,6 @@ parse_str(std::string content, {{< /hint >}} - -### `try_parse(std::istream&, std::string filename, toml::spec)` - -```cpp -namespace toml -{ -template -result, std::vector> -try_parse(std::istream& is, - std::string fname = "unknown file", - spec s = spec::default_version()); -} -``` - -`std::istream&`を受け取ってその内容をパースします。 - -ファイル名の情報は第二引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。 - -パースに失敗した場合、エラー型である`std::vector`を持つ`result`が返されます。 - -成功した場合、`basic_value`を持つ`result`が返されます。 - ### `try_parse(std::string filename, toml::spec)` ```cpp @@ -244,6 +227,30 @@ try_parse(const std::filesystem::path& fpath, 成功した場合、`basic_value`を持つ`result`が返されます。 +### `try_parse(std::istream&, std::string filename, toml::spec)` + +```cpp +namespace toml +{ +template +result, std::vector> +try_parse(std::istream& is, + std::string fname = "unknown file", + spec s = spec::default_version()); +} +``` + +`std::istream&`を受け取ってその内容をパースします。 + +標準ライブラリが改行文字を自動変換することによるファイルサイズと文字数との不整合を避けるため、 +`std::ios::binary`を使ってバイナリモードで開いてください。 + +ファイル名の情報は第二引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。 + +パースに失敗した場合、エラー型である`std::vector`を持つ`result`が返されます。 + +成功した場合、`basic_value`を持つ`result`が返されます。 + ### `try_parse(FILE*, std::string filename, toml::spec)` ```cpp @@ -259,6 +266,9 @@ try_parse(FILE* fp, `FILE*`を受け取って、そのファイルの内容をパースします。 +標準ライブラリが改行文字を自動変換することによるファイルサイズと文字数との不整合を避けるため、 +`fopen`には`"rb"`などを渡してバイナリモードで開いてください。 + パースに失敗した場合、エラー型である`std::vector`を持つ`result`が返されます。 成功した場合、`basic_value`を持つ`result`が返されます。