Merge branch 'master' into patch-1

abseil · Sep 10, 2022 · 2e29de1 · 2e29de1
2 parents 3cffac3 + 073cc77
commit 2e29de1
Show file tree

Hide file tree

Showing 12 changed files with 150 additions and 90 deletions.
diff --git a/about/intro.md b/about/intro.md
@@ -8,7 +8,7 @@ type: markdown
 # Introduction to Abseil
 
 Welcome to Abseil! Abseil is an open-source collection of C++ code (compliant to
-C++11) designed to augment the C++ standard library. This document introduces
+C++14) designed to augment the C++ standard library. This document introduces
 Abseil and provides an overview of the code we're providing.
 
 ## Table of Contents
@@ -21,46 +21,48 @@ Abseil and provides an overview of the code we're providing.
 
 The Abseil codebase consists of the following C++ library components:
 
-* [`base`](https://github.com/abseil/abseil-cpp/tree/master/absl/base) Abseil
-  Fundamentals<br /> The `base` library contains initialization code and other
-  code which all other Abseil code depends on. Code within `base` may not depend
-  on any other code (other than the C++ standard library).
-* [`algorithm`](https://github.com/abseil/abseil-cpp/tree/master/absl/algorithm)
-  <br /> The `algorithm` library contains additions to the C++ `<algorithm>`
-  library and container-based versions of such algorithms.
-* [`container`](https://github.com/abseil/abseil-cpp/tree/master/absl/container)
-  <br /> The `container` library contains additional STL-style containers.
-* [`debugging`](https://github.com/abseil/abseil-cpp/tree/master/absl/debugging)
-  <br /> The `debugging` library contains code useful for enabling leak
-  checks, and stacktrace and symbolization utilities.
-* [`hash`](https://github.com/abseil/abseil-cpp/tree/master/absl/hash)
-  <br /> The `hash` library contains the hashing framework and default hash
-  functor implementations for hashable types in Abseil.
-* [`memory`](https://github.com/abseil/abseil-cpp/tree/master/absl/memory)
-  <br /> The `memory` library contains C++11-compatible versions of
-  `std::make_unique()` and related memory management facilities.
-* [`meta`](https://github.com/abseil/abseil-cpp/tree/master/absl/meta)
-  <br /> The `meta` library contains C++11-compatible versions of type checks
-  available within C++14 and C++17 versions of the C++ `<type_traits>` library.
-* [`numeric`](https://github.com/abseil/abseil-cpp/tree/master/absl/numeric)
-  <br /> The `numeric` library contains C++11-compatible 128-bit integers.
-* [`strings`](https://github.com/abseil/abseil-cpp/tree/master/absl/strings)
-  <br /> The `strings` library contains a variety of strings routines and
-  utilities, including a C++11-compatible version of the C++17
-  `std::string_view` type.
-* [`synchronization`](https://github.com/abseil/abseil-cpp/tree/master/absl/synchronization)
-  <br /> The `synchronization` library contains concurrency primitives (Abseil's
-  `absl::Mutex` class, an alternative to `std::mutex`) and a variety of
-  synchronization abstractions.
-* [`time`](https://github.com/abseil/abseil-cpp/tree/master/absl/time)
-  <br /> The `time` library contains abstractions for computing with absolute
-  points in time, durations of time, and formatting and parsing time within
-  time zones.
-* [`types`](https://github.com/abseil/abseil-cpp/tree/master/absl/types)
-  <br /> The `types` library contains non-container utility types, like a
-  C++11-compatible version of `absl::optional`.
-* [`utility`](https://github.com/abseil/abseil-cpp/tree/master/absl/utility)
-  <br /> The `utility` library contains utility and helper code.
+*   [`base`](https://github.com/abseil/abseil-cpp/tree/master/absl/base) Abseil
+    Fundamentals<br /> The `base` library contains initialization code and other
+    code which all other Abseil code depends on. Code within `base` may not depend
+    on any other code (other than the C++ standard library).
+*   [`algorithm`](https://github.com/abseil/abseil-cpp/tree/master/absl/algorithm)
+    <br /> The `algorithm` library contains additions to the C++ `<algorithm>`
+    library and container-based versions of such algorithms.
+*   [`container`](https://github.com/abseil/abseil-cpp/tree/master/absl/container)
+    <br /> The `container` library contains additional STL-style containers.
+*   [`debugging`](https://github.com/abseil/abseil-cpp/tree/master/absl/debugging)
+    <br /> The `debugging` library contains code useful for enabling leak
+    checks, and stacktrace and symbolization utilities.
+*   [`hash`](https://github.com/abseil/abseil-cpp/tree/master/absl/hash)
+    <br /> The `hash` library contains the hashing framework and default hash
+    functor implementations for hashable types in Abseil.
+*   [`memory`](https://github.com/abseil/abseil-cpp/tree/master/absl/memory)
+    <br /> The `memory` library contains memory management facilities that
+    augment C++'s `<memory>` library.
+*   [`meta`](https://github.com/abseil/abseil-cpp/tree/master/absl/meta)
+    <br /> The `meta` library contains compatible versions of type checks
+    available within C++14 and C++17 versions of the C++ `<type_traits>`
+    library.
+*   [`numeric`](https://github.com/abseil/abseil-cpp/tree/master/absl/numeric)
+    <br /> The `numeric` library contains 128-bit integer types as well as
+    implementations of C++20's bitwise math functions.
+*   [`strings`](https://github.com/abseil/abseil-cpp/tree/master/absl/strings)
+    <br /> The `strings` library contains a variety of strings routines and
+    utilities, including a C++14-compatible version of the C++17
+    `std::string_view` type.
+*   [`synchronization`](https://github.com/abseil/abseil-cpp/tree/master/absl/synchronization)
+    <br /> The `synchronization` library contains concurrency primitives (Abseil's
+    `absl::Mutex` class, an alternative to `std::mutex`) and a variety of
+    synchronization abstractions.
+*   [`time`](https://github.com/abseil/abseil-cpp/tree/master/absl/time)
+    <br /> The `time` library contains abstractions for computing with absolute
+    points in time, durations of time, and formatting and parsing time within
+    time zones.
+*   [`types`](https://github.com/abseil/abseil-cpp/tree/master/absl/types)
+    <br /> The `types` library contains non-container utility types, like a
+    C++14-compatible version of `absl::optional`.
+*   [`utility`](https://github.com/abseil/abseil-cpp/tree/master/absl/utility)
+    <br /> The `utility` library contains utility and helper code.
 
 ## License
 

diff --git a/docs/cpp/guides/flags.md b/docs/cpp/guides/flags.md
@@ -40,7 +40,7 @@ In the command:
 $ fgrep -l -f /var/tmp/foo johannes brahms
 ```
 
-*   `-l` are `-f` are *command-line flags*.
+*   `-l` and `-f` are *command-line flags*.
 *   The `-f` flag contains one argument, `/var/tmp/foo` which is its
     *command-line flag argument*.
 *   The `johannes` and `brahms` arguments, which are not associated with any
@@ -125,6 +125,8 @@ ABSL_FLAG(std::vector<std::string>, languages,
           std::vector<std::string>({"english", "french", "german"}),
           "comma-separated list of languages to offer in the 'lang' menu");
 ABSL_FLAG(absl::Duration, timeout, absl::Seconds(30), "Default RPC deadline");
+ABSL_FLAG(std::optional<std::string>, image_file, std::nullopt,
+          "Sets the image input from a file.");
 ```
 
 Flags defined with `ABSL_FLAG` will create global variables named
@@ -136,18 +138,19 @@ text will be displayed using the `--help` usage argument, if invoked. See
 
 Out of the box, the Abseil flags library supports the following types:
 
-* `bool`
-* `int16_t`
-* `uint16_t`
-* `int32_t`
-* `uint32_t`
-* `int64_t`
-* `uint64_t`
-* `float`
-* `double`
-* `std::string`
-* `std::vector<std::string>`
-* `absl::LogSeverity` (provided natively for layering reasons)
+*   `bool`
+*   `int16_t`
+*   `uint16_t`
+*   `int32_t`
+*   `uint32_t`
+*   `int64_t`
+*   `uint64_t`
+*   `float`
+*   `double`
+*   `std::string`
+*   `std::vector<std::string>`
+*   `std::optional<T>` (see "Optional Flags" below)
+*   `absl::LogSeverity` (provided natively for layering reasons)
 
 NOTE: support for integral types is implemented using overloads for
 variable-width fundamental types (`short`, `int`, `long`, etc.). However, you
@@ -188,6 +191,42 @@ linker will report an error. If you want to access a flag in more than one
 source file, define it in a `.cc` file, and [declare](#declaring_flags) it in
 the corresponding header file.
 
+### Optional Flags
+
+The Abseil flags library supports flags of type `std::optional<T>` where `T` is
+a type of one of the supported flags. We refer to this flag type as an
+"optional flag." An optional flag is either "valueless", holding no value of
+type `T` (indicating that the flag has not been set) or a value of type `T`. The
+valueless state in C++ code is represented by a value of `std::nullopt` for the
+optional flag.
+
+Using `std::nullopt` as an optional flag's default value allows you to check
+whether such a flag was ever specified on the command line:
+
+```cpp
+if (absl::GetFlag(FLAGS_foo).has_value()) {
+  // flag was set on command line
+} else {
+  // flag was not passed on command line
+}
+```
+
+Using `std::optional<T>` in this manner avoids common workarounds for indicating
+such an unset flag (such as using sentinel values to indicate this state).
+
+An optional flag also allows a developer to pass a flag in an "unset" valueless
+state on the command line, allowing the flag to later be set in binary logic. An
+optional flag's valueless state is indicated by the special notation of passing
+the value as an empty string through the syntax `--flag=` or `--flag ""`.
+
+```sh
+$ binary_with_optional --flag_in_unset_state=
+$ binary_with_optional --flag_in_unset_state ""
+```
+
+NOTE: as a result of the above syntax requirements, an optional flag cannot be
+set to a `T` of any value which unparses to the empty string.
+
 ## Accessing Flags
 
 A flag defined via `ABSL_FLAG` is available as a variable of an unspecified
@@ -353,6 +392,18 @@ Despite this flexibility, we recommend using only a single form:
 `--variable=value` for non-boolean flags, and `--variable/--novariable` for
 boolean flags. This consistency will make your code more readable.
 
+Setting a flag of type `std::optional<T>` on the command line to show the
+"unset" state requires a way to refer to this uninitialized value. For Abseil
+flags, this value is specified using the empty string.
+
+```sh
+binary_with_optional --flag_in_unset_state=
+binary_with_optional --flag_in_unset_state ""
+```
+
+NOTE: this usage prevents an optional flag from having a *value* of the empty
+string in practice.
+
 It is a fatal error to specify a flag on the command-line that has not been
 defined somewhere in the executable. If you need that functionality for some
 reason -- say you want to use the same set of flags for several executables, but

diff --git a/docs/cpp/guides/format.md b/docs/cpp/guides/format.md
@@ -357,7 +357,7 @@ Example:
 std::cout << absl::StreamFormat("name: %-20.4s: quota: %7.3f", name, quota);
 
 // Stream to a file
-if (FILE* file_handle = fopen("myfile.txt","w"; file_handle != nullptr) {
+if (FILE* file_handle = fopen("myfile.txt", "w"); file_handle != nullptr) {
   int result =
       absl::FPrintF(file_handle, "%s", "C:\\Windows\\System32\\");
   return result;

diff --git a/docs/cpp/guides/hash.md b/docs/cpp/guides/hash.md
@@ -108,8 +108,8 @@ Of course, this works only if `MyKey` is hashable by `absl::Hash`, i.e.
 `absl::Hash` supports the `MyKey` type.
 
 NOTE: the hash codes computed by `absl::Hash` are not guaranteed to be stable
-across different runs of your program. In fact, in the usual case it randomly
-seeds itself at program startup.
+across different runs of your program, or across different dynamically loaded
+libraries in your program.
 
 ### Intrinsic Type Support
 
@@ -330,7 +330,7 @@ In case of errors, `absl::VerifyTypeImplementsAbslHashCorrectly()` will print
 diagnostics indicating which two elements violated these requirements.
 
 `absl::VerifyTypeImplementsAbslHashCorrectly()` also supports testing
-heterogenous lookup and custom equality operators. In this case, we would use a
+heterogeneous lookup and custom equality operators. In this case, we would use a
 tuple to pass mixed types.
 
 ```c++

diff --git a/docs/cpp/guides/random.md b/docs/cpp/guides/random.md
@@ -71,7 +71,7 @@ biased sampling.
 // as other values.
 uint32_t die_roll = 1 + (bitgen() % 6);
 
-// Instead, use a distribution function instead:
+// Use a distribution function instead:
 uint32_t die_roll = absl::Uniform(absl::IntervalClosed, gen, 1, 6);
 ```
 

diff --git a/docs/cpp/guides/status.md b/docs/cpp/guides/status.md
@@ -22,13 +22,13 @@ Within Google, `absl::Status` is the primary mechanism to gracefully handle
 errors across API boundaries (and in particular across RPC boundaries). Some of
 these errors may be recoverable, but others may not. Most functions which can
 produce a recoverable error should be designed to return either an
-`absl::Status` (or the similar `absl::StatusOr<T>`, which holds either an object
-of type `T` or an error).
+`absl::Status` or the similar `absl::StatusOr<T>`, which holds either an object
+of type `T` or an error.
 
 Example:
 
 ```c++
-absl::Status myFunction(absl::string_view filename, ...) {
+absl::Status MyFunction(absl::string_view filename, ...) {
   ...
   // encounter error
   if (error condition) {
@@ -70,7 +70,7 @@ absl::Status Open(absl::string_view filename, absl::string_view mode, ...) {
   absl::Status result;  // Default constructor creates an OK value as well.
   if (...) {
     // Short-hand for result = absl::Status(absl::StatusCode::kNotFound, ...)
-    result = absl::NotFoundError(absl::StrCat(fname, " is missing"));
+    result = absl::NotFoundError(absl::StrCat(filename, " is missing"));
   } else {
     ...
   }
@@ -158,7 +158,7 @@ if (!s.ok()) {  // Either Open or Create failed
 }
 ```
 
-### Returning a Status or a Value
+## Returning a Status or a Value
 
 Suppose a function needs to return a value on success or, alternatively, a
 `Status` on error. The Abseil Status library provides an `absl::StatusOr<T>`
@@ -210,7 +210,7 @@ if (!result.ok()) {
 }
 ```
 
-### Ignoring Status Results
+## Ignoring Status Results
 
 Our compilers produce errors if a `Status` value returned by a function is
 ignored. In some cases, ignoring the result is the correct thing to do, which
@@ -226,7 +226,7 @@ prefer to actually handle the return value: perhaps you can verify that the
 result matches the error you are expecting, or perhaps you can export it for
 monitoring.
 
-### Keeping Track of the First Error Encountered
+## Keeping Track of the First Error Encountered
 
 Use `Status::Update()` to keep track of the first non-ok status encountered in a
 sequence. `Update()` will overwrite an existing "OK" status, but will not

diff --git a/docs/cpp/guides/strings.md b/docs/cpp/guides/strings.md
@@ -240,7 +240,8 @@ whether or not a resultant element is included in the result set. A filtering
 predicate may be passed as an *optional* third argument to the `StrSplit()`
 function.
 
-The predicates must be unary functions (or functors) that take a single
+The predicates must be unary functions (or function objects such as
+[lambdas](https://en.cppreference.com/w/cpp/language/lambda)) that take a single
 `absl::string_view` argument and return a bool indicating whether the argument
 should be included (`true`) or excluded (`false`).
 
@@ -273,6 +274,12 @@ std::vector<std::string> v = absl::StrSplit(",a, ,b,", ',', absl::SkipEmpty());
 std::vector<std::string> v = absl::StrSplit(",a, ,b,", ',',
                                             absl::SkipWhitespace());
 // v[0] == "a", v[1] == "b"
+
+// Passes a lambda as the predicate to keep only the lines that don't start
+// with a `#`.
+std::vector<std::string> non_comment_lines = absl::StrSplit(
+    file_content, '\n',
+    [](absl::string_view line) { return !absl::StartsWith(line, "#"); });
 ```
 
 ## `absl::StrCat()` and `absl::StrAppend()` for String Concatenation

diff --git a/docs/cpp/guides/time.md b/docs/cpp/guides/time.md
@@ -242,7 +242,7 @@ int64_t min = dur / absl::Minutes(1);      // min == 0
 ```
 
 Additionally, the Abseil time library provides helper functions for converting
-duration values into integers or `double` values:
+duration values into `int64_t` or `double` values:
 
 * `ToInt64Nanoseconds()` and `ToDoubleNanoseconds()`
 * `ToInt64Microseconds()` and `ToDoubleMicroseconds()`

diff --git a/docs/cpp/platforms/platforms.md b/docs/cpp/platforms/platforms.md
@@ -33,18 +33,18 @@ Any other platform that is not explicitly mentioned as **Supported** or
 platforms, and we will only accept patches that in our judgement do not
 complicate the code.
 
-## C++11 and Above
+## C++14 and Above
 
-Abseil requires a code base that at least supports C++11 and our code is
-C++11-compliant. Often, we include C++11 versions of standard library
-functionality available in a later version (e.g C++14 through C++20). Many of
-these C++11 utlities will silently revert to their official standard library
-functionality when compiled on C++14 or newer platforms. That is, we guarantee
+Abseil requires a code base that at least supports C++14 and our code is
+C++14-compliant. Often, we include C++14 versions of standard library
+functionality available in a later version (e.g C++17 through C++20). Many of
+these C++14 utlities will silently revert to their official standard library
+functionality when compiled on C++17 or newer platforms. That is, we guarantee
 that our code will compile under any of the following compilation flags:
 
-* GCC: `-std=c++11`, `-std=c++14`, `-std=c++17`, `-std=c++20`
-* Clang: `-std=c++11`, `-std=c++14`, `-std=c++17`, `-std=c++20`
-* MSVC: `/std:c++14`, `/std:c++17`
+*   GCC: `-std=c++14`, `-std=c++17`, `-std=c++20`
+*   Clang: `-std=c++14`, `-std=c++17`, `-std=c++20`
+*   MSVC: `/std:c++14`, `/std:c++17`
 
 ## Supported Platforms
 

diff --git a/docs/cpp/quickstart-cmake.md b/docs/cpp/quickstart-cmake.md
@@ -20,7 +20,7 @@ Running the Abseil code within this tutorial requires:
 *   A compatible platform (e.g. Windows, macOS, Linux, etc.). Most platforms are
     fully supported. Consult the [Platforms Guide](platforms/platforms) for more
     information.
-*   A compatible C++ compiler *supporting at least C++11*. Most major compilers
+*   A compatible C++ compiler *supporting at least C++14*. Most major compilers
     are supported.
 *   [Git](https://git-scm.com/) for interacting with the Abseil source code
     repository, which is contained on [GitHub](http://github.com). To install
@@ -51,14 +51,14 @@ Navigate into this directory and run all tests:
 ```
 $ cd abseil-cpp
 $ mkdir build && cd build
-$ cmake -DABSL_BUILD_TESTING=ON -DABSL_USE_GOOGLETEST_HEAD=ON -DCMAKE_CXX_STANDARD=11 ..
+$ cmake -DABSL_BUILD_TESTING=ON -DABSL_USE_GOOGLETEST_HEAD=ON -DCMAKE_CXX_STANDARD=14 ..
 ...
 -- Configuring done
 -- Generating done
 -- Build files have been written to: ${PWD}
 ```
 
-`CMAKE_CXX_STANDARD=11` instructs CMake to build using the C++11 standard, which
+`CMAKE_CXX_STANDARD=14` instructs CMake to build using the C++14 standard, which
 is our minimum language level of support.
 
 Now you can build the CMake target tests:
@@ -144,8 +144,8 @@ cmake_minimum_required(VERSION 3.5)
 
 project(my_project)
 
-# Abseil requires C++11
-set(CMAKE_CXX_STANDARD 11)
+# Abseil requires C++14
+set(CMAKE_CXX_STANDARD 14)
 
 # Process Abseil's CMake build system
 add_subdirectory(abseil-cpp)