Add some documentation for recent additions to libcu++ (#1594)

* Add some documentation for recent additions to libcu++

* Add information about ranges, concepts too

Author: miscco

libcudacxx/docs/standard_api.md

@@ -27,16 +27,26 @@ Feature availability:
   - `void_t`
   - Trait operations: `conjunction`,`negation`,`disjunction`
   - `invoke_result`
+- C++17 `<optional>` is available in C++14
+  - all features are available in C++14 and at compile time if the payload type permits it
+- C++17 `<variant>` is available in C++14
+  - all features are available in C++14 and at compile time if the payload types permit it
 - C++17/20 constexpr `<array>` is available in C++14.
   - all operation on array are made constexpr in C++14 with exception of `{c}rbegin` and `{c}rend`, which requires C++17.
 - C++20 constexpr `<complex>` is available in C++14.
   - all operation on complex are made constexpr if `is_constant_evaluated` is supported.
 - C++20 `<concepts>` are available in C++14.
   - all standard concepts are available in C++14 and C++17. However, they need to be used similar to type traits as language concepts are not available.
+- C++20 `<ranges>` are available in C++17.
+  - all `<ranges>` concepts are available in C++17. However, they need to be used similar to type traits as language concepts are not available.
+  - range algorithms are not implemented.
+  - views are not implemented.
 - C++20 `<span>` is mostly available in C++14.
   - With the exception of the range based constructors all features are available in C++14 and C++17. The range based constructors are emulated but not 100% equivalent.
 - C++20 features of `<functional>` have been partially ported to C++17.
   - `bind_front` is available in C++17.
+- C++23 `<expected>` is available in C++14.
+  - all features are available in C++14
 - C++23 `<mdspan>` is available in C++17.
   - mdspan is feature complete in C++17 onwards.
   - mdspan on msvc is only supported in C++20 and onwards.

libcudacxx/docs/standard_api/concepts_library.md

@@ -0,0 +1,5 @@
+## Concepts Library
+
+| [`<cuda/std/concepts>`]* | Fundamental library concepts (see also: [libcu++ Specifics]({{ "standard_api/concepts_library/concepts.html" | relative_url }})). <br/><br/> 2.3.0 / CUDA 12.4 |
+
+[`<cuda/std/concepts>`]: https://en.cppreference.com/w/cpp/header/concepts

libcudacxx/docs/standard_api/concepts_library/concepts.md

@@ -0,0 +1,27 @@
+---
+grand_parent: Standard API
+parent: Concepts Library
+nav_order: 0
+---
+
+# `<cuda/std/concepts>`
+
+## Extensions
+
+* All library features are available from C++14 onwards. The concepts can be used like type traits prior to C++20.
+
+```c++
+template<cuda::std::integral Integer>
+void do_something_with_integers_in_cpp20(Integer&& i) {...}
+
+template<class Integer, cuda::std::enable_if_t<cuda::std::integral<Integer>, int> = 0>
+void do_something_with_integers_in_cpp17(Integer&& i) {...}
+
+template<class Integer, cuda::std::enable_if_t<cuda::std::integral<Integer>, int> = 0>
+void do_something_with_integers_in_cpp14(Integer&& i) {...}
+```
+
+## Restrictions
+
+* Subsumption does not work prior to C++20
+* Subsumption is only partially implemented in the compiler until nvcc 12.4

libcudacxx/docs/standard_api/ranges_library.md

@@ -0,0 +1,5 @@
+## Concepts Library
+
+| [`<cuda/std/ranges>`]* | Range based algorithms and concepts (see also: [libcu++ Specifics]({{ "standard_api/ranges_library/ranges.html" | relative_url }})). <br/><br/> 2.3.0 / CUDA 12.4 |
+
+[`<cuda/std/ranges>`]: https://en.cppreference.com/w/cpp/header/ranges

libcudacxx/docs/standard_api/ranges_library/ranges.md

@@ -0,0 +1,32 @@
+---
+grand_parent: Standard API
+parent: Ranges Library
+nav_order: 0
+---
+
+# `<cuda/std/ranges>`
+
+## Omissions
+
+* Iterator related concepts and machinery such as `cuda::std::forward_iterator` has been implemented in 2.3.0
+* Range related concepts and machinery such as `cuda::std::ranges::forward_range` and `cuda::std::ranges::subrange` has been implemented in 2.4.0
+
+* Range based algorithms have *not* been implemented
+* Views have *not* been implemented
+
+## Extensions
+
+* All library features are available from C++17 onwards. The concepts can be used like type traits prior to C++20.
+
+```c++
+template<cuda::std::contiguos_range Range>
+void do_something_with_ranges_in_cpp20(Range&& range) {...}
+
+template<class Range, cuda::std::enable_if_t<cuda::std::contiguos_range<Range>, int> = 0>
+void do_something_with_ranges_in_cpp17(Range&& range) {...}
+```
+
+## Restrictions
+
+* Subsumption does not work prior to C++20
+* Subsumption is only partially implemented in the compiler until nvcc 12.4

libcudacxx/docs/standard_api/utility_library.md

@@ -10,10 +10,15 @@ libcu++ Specifics for details.
 | [`<cuda/std/functional>`]* | Function objects and function wrappers (see also: [libcu++ Specifics]({{ "standard_api/utility_library/functional.html" | relative_url }})). <br/><br/> 1.1.0 / CUDA 11.0 (Function Objects) |
 | [`<cuda/std/utility>`]*    | Various utility components (see also: [libcu++ Specifics]({{ "standard_api/utility_library/utility.html" | relative_url }})).                <br/><br/> 1.3.0 / CUDA 11.2 (`pair`) |
 | [`<cuda/std/version>`]     | Compile-time version information (see also: [libcu++ Specifics]({{ "standard_api/utility_library/version.html" | relative_url }})).          <br/><br/> 1.2.0 / CUDA 11.1 |
-
+| [`<cuda/std/optional>`]*   | Optional value (see also: [libcu++ Specifics]({{ "standard_api/utility_library/optional.html" | relative_url }})).                <br/><br/> 2.3.0 / CUDA 12.4 |
+| [`<cuda/std/variant>`]*    | Type safe union type (see also: [libcu++ Specifics]({{ "standard_api/utility_library/variant.html" | relative_url }})).        <br/><br/> 2.3.0 / CUDA 12.4 |
+| [`<cuda/std/expected>`]*   | Optional value with error channel (see also: [libcu++ Specifics]({{ "standard_api/utility_library/expected.html" | relative_url }})).        <br/><br/> 2.3.0 / CUDA 12.4 |
 
 [`<cuda/std/type_traits>`]: https://en.cppreference.com/w/cpp/header/type_traits
 [`<cuda/std/tuple>`]: https://en.cppreference.com/w/cpp/header/tuple
 [`<cuda/std/functional>`]: https://en.cppreference.com/w/cpp/header/functional
 [`<cuda/std/utility>`]: https://en.cppreference.com/w/cpp/header/utility
 [`<cuda/std/version>`]: https://en.cppreference.com/w/cpp/header/version
+[`<cuda/std/optional>`]: https://en.cppreference.com/w/cpp/header/optional
+[`<cuda/std/variant>`]: https://en.cppreference.com/w/cpp/header/variant
+[`<cuda/std/expected>`]: https://en.cppreference.com/w/cpp/header/expected

libcudacxx/docs/standard_api/utility_library/expected.md

@@ -0,0 +1,15 @@
+---
+grand_parent: Standard API
+parent: Utility Library
+nav_order: 5
+---
+
+# `<cuda/std/expected>`
+
+## Extensions
+
+* All features are available from C++14 onwards.
+
+## Restrictions
+
+* On device no exceptions are thrown in case of a bad access.

libcudacxx/docs/standard_api/utility_library/functional.md

@@ -13,7 +13,6 @@ The following facilities in section [functional.syn] of ISO/IEC IS 14882 (the
 
 - [`std::function`] - Polymorphic function object wrapper.
 - [`std::bind`] - Generic function object binder / lambda facility.
-- [`std::reference_wrapper`] - Reference wrapper type.
 - [`std::hash`] - Hash function object.
 
 ### `std::function`
@@ -45,32 +44,12 @@ That implementation might be different from the default that the upstream
 Further research and investigation is required before we can provide this
   feature.
 
-### `std::reference_wrapper`
-
-[`std::reference_wrapper`] is a [*CopyConstructible*] and
-  [*CopyAssignable*] wrapper around a reference to an object or function of
-  type `T`.
-There is nothing that makes this facility difficult to implement heterogeneously
-  today.
-It is a value type that does not allocate memory, hold
-  pointers, have virtual functions, or make calls to platform specific APIs.
-
-No design or functional changes were required to port the upstream libc++
-  implementations of this facility.
-We just had to add execution space specifiers to port it.
-
-However, this feature failed tests involving function pointers with some of the
-  compilers we support.
-So, we've omitted this feature for now.
-
-
 [functional.syn]: https://eel.is/c++draft/functional.syn
 
 [*CopyConstructible*]: https://eel.is/c++draft/utility.arg.requirements#:requirements,Cpp17CopyConstructible
 [*CopyAssignable*]: https://eel.is/c++draft/utility.arg.requirements#:requirements,Cpp17CopyAssignable
 
 [`std::function`]: https://en.cppreference.com/w/cpp/utility/functional/function
 [`std::bind`]: https://en.cppreference.com/w/cpp/utility/functional/bind
-[`std::reference_wrapper`]: https://en.cppreference.com/w/cpp/utility/functional/reference_wrapper
 [`std::hash`]: https://en.cppreference.com/w/cpp/utility/hash
 

libcudacxx/docs/standard_api/utility_library/optional.md

@@ -0,0 +1,16 @@
+---
+grand_parent: Standard API
+parent: Utility Library
+nav_order: 3
+---
+
+# `<cuda/std/optional>`
+
+## Extensions
+
+* All features are available from C++14 onwards.
+* All features are available at compile time if the value type supports it.
+
+## Restrictions
+
+* On device no exceptions are thrown in case of a bad access.

libcudacxx/docs/standard_api/utility_library/tuple.md

@@ -11,8 +11,7 @@ nav_order: 0
 Before version 1.4.0, `tuple` is not available when using NVCC with MSVC as a
   host compiler, due to compiler bugs.
 
-Internal compiler errors may be encountered when using `tuple` with
+Before version 2.3.0 internal compiler errors may be encountered when using `tuple` with
   older updates of MSVC 2017 and MSVC 2019.
 For MSVC 2017, please use version 15.8 or later (`_MSC_VER >= 1915`).
 For MSVC 2019, please use version 16.6 or later (`_MSC_VER >= 1926`).
-