From ad904b6cd3906ddf79878003d92b7bc08d7786ae Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Thu, 19 Dec 2019 12:03:35 -0800 Subject: Export of internal Abseil changes -- 24162e64040e89f174531fa78fc0ff43c3a67da4 by Abseil Team : Make ABSL_RETIRED_FLAG behave consistently with ABSL_FLAG. Before the change: ABSL_RETIRED_FLAG does not compile when there are competing ctors in the type, even when ABSL_FLAG does. After the change: ABSL_RETIRED_FLAG compiles when ABSL_FLAG does. PiperOrigin-RevId: 286437395 -- 870d4cb4d114813e9cefe30d26d020b0fdcdc4b4 by Tom Manshreck : Add docs on bind_front PiperOrigin-RevId: 286433540 -- b0c328bd9bb64e0382f942f93b85054229dafeac by Tom Manshreck : Specify the format for LogSeverity flags PiperOrigin-RevId: 286402811 GitOrigin-RevId: 24162e64040e89f174531fa78fc0ff43c3a67da4 Change-Id: I89785145d049fee49c6b9cf3357893ece9a6231c --- absl/base/log_severity.h | 52 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 43 insertions(+), 9 deletions(-) (limited to 'absl/base') diff --git a/absl/base/log_severity.h b/absl/base/log_severity.h index e247c4a..65a3b16 100644 --- a/absl/base/log_severity.h +++ b/absl/base/log_severity.h @@ -24,19 +24,45 @@ namespace absl { ABSL_NAMESPACE_BEGIN -// Four severity levels are defined. Logging APIs should terminate the program +// absl::LogSeverity +// +// Four severity levels are defined. Logging APIs should terminate the program // when a message is logged at severity `kFatal`; the other levels have no // special semantics. // -// Abseil flags may be defined with type `LogSeverity`. Dependency layering -// constraints require that the `AbslParseFlag` overload be declared and defined -// in the flags module rather than here. The `AbslUnparseFlag` overload is -// defined there too for consistency. +// Values other than the four defined levels (e.g. produced by `static_cast`) +// are valid, but their semantics when passed to a function, macro, or flag +// depend on the function, macro, or flag. The usual behavior is to normalize +// such values to a defined severity level, however in some cases values other +// than the defined levels are useful for comparison. +// +// Exmaple: +// +// // Effectively disables all logging: +// SetMinLogLevel(static_cast(100)); +// +// Abseil flags may be defined with type `LogSeverity`. Dependency layering +// constraints require that the `AbslParseFlag()` overload be declared and +// defined in the flags library itself rather than here. The `AbslUnparseFlag()` +// overload is defined there as well for consistency. +// +// absl::LogSeverity Flag String Representation +// +// An `absl::LogSeverity` has a string representation used for parsing +// command-line flags based on the enumerator name (e.g. `kFatal`) or +// its unprefixed name (without the `k`) in any case-insensitive form. (E.g. +// "FATAL", "fatal" or "Fatal" are all valid.) Unparsing such flags produces an +// unprefixed string representation in all caps (e.g. "FATAL") or an integer. // -// The parser accepts arbitrary integers (as if the type were `int`). It also -// accepts each named enumerator, without regard for case, with or without the -// leading 'k'. For example: "kInfo", "INFO", and "info" all parse to the value -// `absl::LogSeverity::kInfo`. +// Additionally, the parser accepts arbitrary integers (as if the type were +// `int`). +// +// Examples: +// +// --my_log_level=kInfo +// --my_log_level=INFO +// --my_log_level=info +// --my_log_level=0 // // Unparsing a flag produces the same result as `absl::LogSeverityName()` for // the standard levels and a base-ten integer otherwise. @@ -47,6 +73,8 @@ enum class LogSeverity : int { kFatal = 3, }; +// LogSeverities() +// // Returns an iterable of all standard `absl::LogSeverity` values, ordered from // least to most severe. constexpr std::array LogSeverities() { @@ -54,6 +82,8 @@ constexpr std::array LogSeverities() { absl::LogSeverity::kError, absl::LogSeverity::kFatal}}; } +// LogSeverityName() +// // Returns the all-caps string representation (e.g. "INFO") of the specified // severity level if it is one of the standard levels and "UNKNOWN" otherwise. constexpr const char* LogSeverityName(absl::LogSeverity s) { @@ -66,6 +96,8 @@ constexpr const char* LogSeverityName(absl::LogSeverity s) { : s == absl::LogSeverity::kFatal ? "FATAL" : "UNKNOWN"; } +// NormalizeLogSeverity() +// // Values less than `kInfo` normalize to `kInfo`; values greater than `kFatal` // normalize to `kError` (**NOT** `kFatal`). constexpr absl::LogSeverity NormalizeLogSeverity(absl::LogSeverity s) { @@ -77,6 +109,8 @@ constexpr absl::LogSeverity NormalizeLogSeverity(int s) { return absl::NormalizeLogSeverity(static_cast(s)); } +// operator<< +// // The exact representation of a streamed `absl::LogSeverity` is deliberately // unspecified; do not rely on it. std::ostream& operator<<(std::ostream& os, absl::LogSeverity s); -- cgit v1.2.3