Merge pull request #18 from neatudarius/P3168R1-iterator

P3168R1: use a non-pointer iterator type

Author: neatudarius

CMakeLists.txt

@@ -1,3 +1,6 @@
+# /CMakeLists.txt -*-makefile-*-
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
 cmake_minimum_required(VERSION 3.10)
 
 project(beman_optional26 VERSION 0.0.0 LANGUAGES CXX)

Makefile

@@ -1,5 +1,6 @@
 #! /usr/bin/make -f
-# -*-makefile-*-
+# /Makefile -*-makefile-*-
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 INSTALL_PREFIX?=.install/
 PROJECT?=$(shell basename $(CURDIR))

README.md

@@ -1,11 +1,16 @@
 # Beman.Optional26: C++26 Extensions for std::optional
 
+<!--
+SPDX-License-Identifier: 2.0 license with LLVM exceptions
+-->
+
 This implementation incorporates the C++26 extensions added for `std::optional`. The `Beman.Optional26` library aims to evaluate the stability, the usability, and the performance of these proposed changes before they are officially adopted by WG21 into the C++ Working Draft. Additionally, it allows developers to use these new features before they are implemented in major standard library compilers.
 
 **Implements**:
+* [Give *std::optional* Range Support (P3168R1)](https://wg21.link/P3168R1)
 * [`std::optional<T&>` (P2988R5)](https://wg21.link/P2988R5)
-* [Give *std::optional* Range Support (P3168R1)](https://wg21.link/P3168R1).
 
+## License
 
 Source is licensed with the Apache 2.0 license with LLVM exceptions
 
@@ -21,8 +26,74 @@ The README itself is licesed with CC0 1.0 Universal. Copy the contents and incor
 
 // SPDX-License-Identifier: CC0-1.0
 
+## Examples
+
+Full runable examples can be found in `examples/` - please check [./examples/README.md](./examples/README.md).
+
+### range_loop
+
+The next code snippet shows optional range support added in [Give *std::optional* Range Support (P3168R1)](https://wg21.link/P3168R1):
+
+```cpp
+#include <Beman/Optional26/optional.hpp>
+...
+
+// Example from P3168R1: basic range loop over C++26 optional.
+
+beman::optional26::optional<int> empty_opt{};
+for ([[maybe_unused]] const auto& i : empty_opt) {
+    // Should not see this in console.
+    std::cout << "\"for each loop\" over C++26 optional: empty_opt\n";
+}
+
+beman::optional26::optional<int> opt{26};
+for (const auto& i : opt) {
+    // Should see this in console.
+    std::cout << "\"for each loop\" over C++26 optional: opt = " << i << "\n";
+}
+```
+
+Full code can be found in [./examples/range_loop.cpp](./examples/range_loop.cpp). Build and run instructions in [./examples/README.md](./examples/README.md).
+
+### optional_ref
+
+The next code snippet shows optional reference support added in [`std::optional<T&>` (P2988R5)](https://wg21.link/P2988R5):
+
+```cpp
+#include <Beman/Optional26/optional.hpp>
+...
+
+{
+    // Empty optional example.
+    std::optional<int>             std_empty_opt;
+    beman::optional26::optional<int> beman_empty_opt;
+    assert(!std_empty_opt.has_value() &&
+            !beman_empty_opt.has_value()); // or assert(!std_empty_opt && !beman_empty_opt);
+    std::cout << "std_vs_beman: .has_value() matches?: "
+              << (std_empty_opt.has_value() == beman_empty_opt.has_value() ? "yes" : "no") << "\n";
+}
+
+{
+    // Optional with value example.
+    std::optional<int>             std_opt   = 26;
+    beman::optional26::optional<int> beman_opt = 26;
+    assert(std_opt.has_value() && beman_opt.has_value()); // or assert(std_opt && beman_opt);
+    assert(std_opt.value() == beman_opt.value());         // or assert(*std_opt == *beman_opt);
+    std::cout << "std_vs_beman: .value() matches?: " << (std_opt.value() == beman_opt.value() ? "yes" : "no")
+              << "\n";
+}
+```
+
+Full code can be found in [./examples/optional_ref.cpp](./examples/optional_ref.cpp). Build and run instructions in [./examples/README.md](./examples/README.md).
+
 ## How to Build
 
+### Compiler Support
+
+This is a modern C++ project which can be compiled with the latest C++ standards (**C++20 or later**).
+
+Default build: `C++23`. Please check `etc/${compiler}-flags.cmake`.
+
 ### Dependencies
 
 This project is mainly tested on `Ubuntu 22.04` and `Ubuntu 24.04`, but it should be as portable as CMake is. This project has zero C or C++ dependencies.
@@ -52,6 +123,8 @@ This project strives to be as normal and simple a CMake project as possible. Thi
 
 ```shell
 cmake --workflow --preset gcc-14
+cmake --workflow --preset clang-18
+cmake --workflow --preset systems # uses c++ set tool
 ```
 
 This should build and run the tests with GCC 14 with the address and undefined behavior sanitizers enabled.
@@ -69,6 +142,14 @@ The makefile will use your system compiler, `c++`, if no toolchain name is provi
 ## Papers
 
 Latest revision(s) of the papers can be built / found at:
-* [./papers/P2988/README.md](./papers/P2988/README.md) for `std::optional<T&> (P2988)`.
 * [give-std-optional-range-support](https://github.com/neatudarius/give-std-optional-range-support/) for `Give *std::optional* Range Support (P3168)`
-
+    * issue: [#1831](https://github.com/cplusplus/papers/issues/1831)
+  * LEWG:
+    * Reviewed in Tokyo 2024.
+    * Forwarded by LEWG April electronic poll to LWG.
+  * LWG:
+    * To be reviewed in Saint Louis 2024.
+* [./papers/P2988/README.md](./papers/P2988/README.md) for `std::optional<T&> (P2988)`.
+    * issue: [#1661](https://github.com/cplusplus/papers/issues/1661)
+    * LEWG:
+      * Reviewed in Tokyo 2024.

cmake/Config.cmake.in

@@ -1,3 +1,6 @@
+# cmake/Config.cmake.in -*-makefile-*-
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
 @PACKAGE_INIT@
 
 include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")

etc/gcc-flags.cmake

@@ -3,7 +3,7 @@ include_guard(GLOBAL)
 set(CMAKE_CXX_STANDARD 23)
 
 set(CMAKE_CXX_FLAGS
-   "-Wall -Wextra "
+   "-std=c++23 -Wall -Wextra "
 CACHE STRING "CXX_FLAGS" FORCE)
 
 set(CMAKE_CXX_FLAGS_DEBUG "-O0 -fno-inline -g3" CACHE STRING "C++ DEBUG Flags" FORCE)

examples/CMakeLists.txt

@@ -1,12 +1,17 @@
+# examples/CMakeLists.txt -*-makefile-*-
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
 set(BEMAN_OPTIONAL26_LIBRARY "beman_optional26")
 
 include(GNUInstallDirs)
 
 # List of all buildable examples.
 set(EXAMPLES
-  sample
-  range_loop
   optional_ref
+  pythagorean_triples
+  range_loop
+  sample
+  std_vs_beman
 )
 
 foreach(EXAMPLE ${EXAMPLES})

examples/README.md

@@ -1,7 +1,26 @@
 # Beman.Optional26 Examples
 
+<!--
+SPDX-License-Identifier: 2.0 license with LLVM exceptions
+-->
+
 List of usage examples for `Beman.Optional26`.
 
+## License
+Source is licensed with the Apache 2.0 license with LLVM exceptions
+
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+Documentation and associated papers are licensed with the Creative Commons Attribution 4.0 International license.
+
+// SPDX-License-Identifier: CC-BY-4.0
+
+The intent is that the source and documentation are available for use by people implementing their own optional types as well as people using the optional presented here as-is.
+
+The README itself is licesed with CC0 1.0 Universal. Copy the contents and incorporate in your own work as you see fit.
+
+// SPDX-License-Identifier: CC0-1.0
+
 ## Sample
 
 Check [sample](sample.cpp) for basic `Beman.Optional26` library usage.
@@ -11,32 +30,62 @@ Build and run instructions:
 # build
 $ cmake --workflow --preset gcc-14
 
-# run sample
+# run sample.cpp
 $ .build/gcc-14/examples/RelWithDebInfo/sample
 empty_opt is empty!
 opt = 26
+
+# run std_vs_beman.cpp
+$ .build/gcc-14/examples/RelWithDebInfo/std_vs_beman
+std_vs_beman: .has_value() matches?: yes
+std_vs_beman: .value() matches?: yes
 ```
 
 ## Range Support (P3168R1)
 
 Range support added in [*Give std::optional Range Support* (P3168R1)](https://wg21.link/P3168R1) examples:
 * [./range_loop.cpp](./range_loop.cpp)
+* [./pythagorean_triples.cpp](./pythagorean_triples.cpp)
 
 
 Build and run instructions:
 
 ```shell
-# build
-$ cmake --workflow --preset gcc-14
 
-# run range_loop
+
+# run range_loop.cpp
 $ .build/gcc-14/examples/RelWithDebInfo/range_loop
                                                # note: 1st log (empty_opt) is missing from console!
 "for each loop" over C++26 optional: opt = 26  # 2nd log (non empty opt)
+
+# run pythagorean_triples.cpp
+$ .build/gcc-14/examples/RelWithDebInfo/pythagorean_triples
+First 10 Pythagorean triples:
+(3, 4, 5)
+(6, 8, 10)
+(5, 12, 13)
+(9, 12, 15)
+(8, 15, 17)
+(12, 16, 20)
+(7, 24, 25)
+(15, 20, 25)
+(10, 24, 26)
+(20, 21, 29)
+100th Pythagorean triple (x, y, z <= 200): (26, 168, 170)
 ```
 
 ## Optional Reference (P2988R5)
 
 Reference support added in [*std::optional<T&>*(P2988R5)](https://wg21.link/P2988R5) examples:
 
 * [./optional_ref.cpp](./optional_ref.cpp)
+
+Build and run instructions:
+
+```shell
+# build
+$ cmake --workflow --preset gcc-14
+
+# run optional_ref.cpp
+$ .build/gcc-14/examples/RelWithDebInfo/optional_ref
+```

examples/optional_ref.cpp

@@ -1,34 +1,59 @@
+// examples/optional_ref.cpp -*-C++-*-
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
 #include <Beman/Optional26/optional.hpp>
 
 #include <string>
 
-using beman::optional::optional;
-
 struct Cat {
     int catalog_index{0};
 };
 
-auto find_cat_old(std::string) -> Cat* { return nullptr; }
+namespace std17 {
+
+// Prior to C++26, the code would look like this.
+// Using raw pointers to represent optional references.
+// Note: Using smart pointers would also be a choice, but it involves ownership semantics.
 
-auto find_cat_new(std::string) -> optional<Cat&> { return optional<Cat&>{}; }
+Cat* find_cat(std::string) { return nullptr; }
 
-Cat*           doit_old(Cat& cat) { return &cat; }
-optional<Cat&> doit(Cat& cat) { return optional<Cat&>{cat}; }
+Cat* do_it(Cat& cat) { return &cat; }
 
-Cat* before1() {
-    Cat* cat = find_cat_old("Fido");
+Cat* api() {
+    Cat* cat = find_cat("Fido");
     if (cat != nullptr) {
-        return doit_old(*cat);
+        return do_it(*cat);
     }
     return nullptr;
 }
 
-optional<Cat&> after1() {
-    optional<Cat&> cat = find_cat_new("Fido");
-    return cat.and_then(doit);
+} // namespace std17
+
+namespace std26 {
+// After C++26 with P2988R5, the code would look like this.
+// Using directly optional to represent optional references.
+
+beman::optional26::optional<Cat&> find_cat(std::string) { return {}; }
+
+beman::optional26::optional<Cat&> do_it(Cat& cat) { return {cat}; }
+
+beman::optional26::optional<Cat&> api() {
+    beman::optional26::optional<Cat&> cat = find_cat("Fido");
+    return cat.and_then(do_it);
 }
 
+} // namespace std26
+
 int main() {
-    Cat*           cat_p = before1();
-    optional<Cat&> cat_r = after1();
+    // Example from P2988R5: optional reference.
+    [[maybe_unused]] Cat*                              old_cat = std17::api();
+    [[maybe_unused]] beman::optional26::optional<Cat&> new_cat = std26::api();
+
+    return 0;
 }
+
+// # build example:
+// $ cmake --workflow --preset gcc-14
+//
+// # run example:
+// $ .build/gcc-14/examples/RelWithDebInfo/optional_ref