diff options
author | Phoebe Liang <phoebeliang@google.com> | 2022-11-02 15:27:54 -0700 |
---|---|---|
committer | Copybara-Service <copybara-worker@google.com> | 2022-11-02 15:28:46 -0700 |
commit | e6044634dd7caec2d79a13aecc9e765023768757 (patch) | |
tree | 3ffe2c00f4b5e49da4f4e7d9e50c64999f318408 /absl/log/log.h | |
parent | 1649c037c556bdaca7241bc0113275506bdb9638 (diff) |
Support logging of user-defined types that implement `AbslStringify()`
If a user-defined type has `AbslStringify()` defined, it will always be used for logging over `operator<<`.
`HasAbslStringify` now uses the empty class `UnimplementedSink` for its checks instead of `StringifySink` in order to make it work in cases involving other sinks.
PiperOrigin-RevId: 485710377
Change-Id: Ibdd916151c7abc3269c35fbe79b772867f3d25e1
Diffstat (limited to 'absl/log/log.h')
-rw-r--r-- | absl/log/log.h | 37 |
1 files changed, 36 insertions, 1 deletions
diff --git a/absl/log/log.h b/absl/log/log.h index 5331fdbf..4cd52041 100644 --- a/absl/log/log.h +++ b/absl/log/log.h @@ -132,10 +132,45 @@ // as they would be if streamed into a `std::ostream`, however it should be // noted that their actual type is unspecified. // -// To implement a custom formatting operator for a type you own, define +// To implement a custom formatting operator for a type you own, there are two +// options: `AbslStringify()` or `std::ostream& operator<<(std::ostream&, ...)`. +// It is recommended that users make their types loggable through +// `AbslStringify()` as it is a universal stringification extension that also +// enables `absl::StrFormat` and `absl::StrCat` support. If both +// `AbslStringify()` and `std::ostream& operator<<(std::ostream&, ...)` are +// defined, `AbslStringify()` will be used. +// +// To use the `AbslStringify()` API, define a friend function template in your +// type's namespace with the following signature: +// +// template <typename Sink> +// void AbslStringify(Sink& sink, const UserDefinedType& value); +// +// `Sink` has the same interface as `absl::FormatSink`, but without +// `PutPaddedString()`. +// +// Example: +// +// struct Point { +// template <typename Sink> +// friend void AbslStringify(Sink& sink, const Point& p) { +// absl::Format(&sink, "(%v, %v)", p.x, p.y); +// } +// +// int x; +// int y; +// }; +// +// To use `std::ostream& operator<<(std::ostream&, ...)`, define // `std::ostream& operator<<(std::ostream&, ...)` in your type's namespace (for // ADL) just as you would to stream it to `std::cout`. // +// Currently `AbslStringify()` ignores output manipulators but this is not +// guaranteed behavior and may be subject to change in the future. If you would +// like guaranteed behavior regarding output manipulators, please use +// `std::ostream& operator<<(std::ostream&, ...)` to make custom types loggable +// instead. +// // Those macros that support streaming honor output manipulators and `fmtflag` // changes that output data (e.g. `std::ends`) or control formatting of data // (e.g. `std::hex` and `std::fixed`), however flushing such a stream is |