diff --git a/ChangeLog.rst b/ChangeLog.rst index 0dcc66d2..0e5cc631 100644 --- a/ChangeLog.rst +++ b/ChangeLog.rst @@ -1,6 +1,61 @@ 9.0.0 - TBD ----------- +* Switched to the internal floating point formatter for all decimal formats. + In particular this results in consistent rounding on all platforms and + removing the ``s[n]printf`` fallback for decimal FP formatting. + +* Improved the implementation of + `Dragonbox `_, the algorithm used for + the default floating-point formatting + (`#2713 `_, + `#2750 `_). + Thanks `@jk-jeon (Junekey Jeon) `_. + +* Disabled automatic ``std::ostream`` insertion operator (``operator<<``) + discovery when ``fmt/ostream.h`` is included to prevent ODR violations. + You can get the old behavior by defining ``FMT_DEPRECATED_OSTREAM`` but this + will be removed in the next major release. You can use ``fmt::streamed`` or + ``fmt::ostream_formatter`` to enable formatting via ``std::ostream``. + +* Added ``ostream_formatter`` that can be used to write ``formatter`` + specializations that perform formatting via ``std::ostream``. + For example (`godbolt `__): + + .. code:: c++ + + #include + + struct date { + int year, month, day; + + friend std::ostream& operator<<(std::ostream& os, const date& d) { + return os << d.year << '-' << d.month << '-' << d.day; + } + }; + + template <> struct fmt::formatter : ostream_formatter {}; + + std::string s = fmt::format("The date is {}", date{2012, 12, 9}); + // s == "The date is 2012-12-9" + +* Added the ``fmt::streamed`` function that takes an object and formats it + via ``std::ostream``. + For example (`godbolt `__): + + .. code:: c++ + + #include + #include + + int main() { + fmt::print("Current thread id: {}\n", + fmt::streamed(std::this_thread::get_id())); + } + + Note that ``fmt/std.h`` provides a ``formatter`` specialization for + ``std::thread::id`` so you don't need to format it via ``std::ostream``. + * Added experimental ``std::filesystem::path`` formatting support (`#2865 `_, `#2902 `_, @@ -65,17 +120,6 @@ `#2701 `_). Thanks `@AlexGuteniev (Alex Guteniev) `_. -* Switched to an internal floating point formatter for all decimal formats. - In particular this results in consistent rounding on all platforms and - removing the ``s[n]printf`` fallback for decimal FP formatting. - -* Improved the implementation of - `Dragonbox `_, the algorithm used for - the default floating-point formatting - (`#2713 `_, - `#2750 `_). - Thanks `@jk-jeon (Junekey Jeon) `_. - * Implemented escaping of wide strings in ranges (`#2904 `_). Thanks `@phprus (Vladislav Shchapov) `_. diff --git a/doc/api.rst b/doc/api.rst index 02aa994d..9ac28724 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -503,21 +503,21 @@ In order to make a type formattable via ``std::ostream`` you should provide a #include - class date { - int year_, month_, day_; - public: - date(int year, int month, int day): year_(year), month_(month), day_(day) {} + struct date { + int year, month, day; friend std::ostream& operator<<(std::ostream& os, const date& d) { - return os << d.year_ << '-' << d.month_ << '-' << d.day_; + return os << d.year << '-' << d.month << '-' << d.day; } }; template <> struct fmt::formatter : ostream_formatter {}; - std::string s = fmt::format("The date is {}", date(2012, 12, 9)); + std::string s = fmt::format("The date is {}", date{2012, 12, 9}); // s == "The date is 2012-12-9" +.. doxygenfunction:: streamed(const T &) + .. doxygenfunction:: print(std::ostream &os, format_string fmt, T&&... args) .. _printf-api: diff --git a/include/fmt/ostream.h b/include/fmt/ostream.h index 3292b0ed..394d947c 100644 --- a/include/fmt/ostream.h +++ b/include/fmt/ostream.h @@ -151,6 +151,16 @@ struct formatter> : ostream_formatter { } }; +/** + \rst + Returns a view that formats `value` via an ostream ``operator<<``. + + **Example**:: + + fmt::print("Current thread id: {}\n", + fmt::streamed(std::this_thread::get_id())); + \endrst + */ template auto streamed(const T& value) -> detail::streamed_view { return {value};