Add constexpr to not_null comparison operators (#1208)

* Initial plan for issue

* Add test and plan to make not_null comparison functions constexpr

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Add constexpr to not_null comparison operators

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Fix copyright year in constexpr_notnull_tests.cpp

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Fix constexpr tests for better compiler compatibility

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Remove build artifacts and update .gitignore

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Fix constexpr tests to be compatible with more compilers

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* copilot: Provide more project context for the Copilot coding agent (#1207)

* copilot: create .github/copilot-instructions.md

This file provides additional context and instructions to GitHub
Copilot so it can better understand the codebase and coding conventions.

More can be found about this file at the following links:
 - [Best practices for using Copilot to work on tasks](https://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/best-practices-for-using-copilot-to-work-on-taskshttps://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/best-practices-for-using-copilot-to-work-on-tasks)
 - [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/enterprise-cloud@latest/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=webuihttps://docs.github.com/en/enterprise-cloud@latest/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)

* copilot: add copilot-setup-steps.yml

This new workflow is done when copilot loads into an environment and
enables copilot to be sure it has the proper dependencies before working
on changes. Also included in the change are explicit instructions on
what to do before reporting back "done".

* Initial plan for issue

* Rebase onto main and verify changes meet project guidelines

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Update .gitignore to exclude build-cxx* directories

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Fix newline at end of constexpr_notnull_tests.cpp and update .gitignore

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

* Remove C++14 feature check that is redundant since C++14 is the minimum supported standard

Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: carsonRadtke <10507970+carsonRadtke@users.noreply.github.com>
Co-authored-by: Carson Radtke <carsonradtke@microsoft.com>

.github/copilot-instructions.md

@@ -0,0 +1,84 @@
+# GitHub Copilot Instructions for GSL (Guidelines Support Library)
+
+## Project Overview
+This repository contains the Guidelines Support Library (GSL), a Microsoft implementation of types and functions 
+suggested for use by the C++ Core Guidelines. It's a header-only C++ library with emphasis on safety, 
+correctness, and zero overhead.
+
+## Coding Standards
+
+### General
+- Follow C++ Core Guidelines wherever possible
+- Use meaningful type, function, and template parameter names
+- Keep functions small and focused with clear preconditions/postconditions
+- Include comments for complex code, but prefer self-documenting code
+- Use the Expects() and Ensures() macros for contract verification
+
+### Style Guidelines
+- Use 4 spaces for indentation (not tabs)
+- Maximum line length of 100 characters
+- Follow GSL naming conventions (lowercase with underscores)
+- Keep templates clean and readable with appropriate spacing
+- Use C++14 features since this is the minimum standard supported
+
+### Error Handling
+- Use Expects() for preconditions and Ensures() for postconditions
+- Design for fail-fast semantics (std::terminate) on contract violations
+- Template constraints should use static_assert or SFINAE
+- Don't throw exceptions from basic operations
+
+### Testing
+- Write thorough unit tests for every component using GTest
+- Test for all edge cases and error conditions
+- Ensure cross-platform compatibility in tests
+- Maintain 100% code coverage for changed code
+
+## Project-Specific Conventions
+
+### Architecture
+- All public types must be in the gsl namespace
+- Design for zero overhead abstractions when possible
+- Respect the distinction between Owners and Views
+- Maintain backward compatibility with existing GSL code
+
+### Version Control
+- Link all PRs to related issues
+- Use clear commit messages explaining what and why
+- Follow the contribution guidelines documented in CONTRIBUTING.md
+- PRs should include appropriate tests with 100% coverage for changed code
+
+### Documentation
+- Document all public APIs with clarity on preconditions and postconditions
+- Keep header comments up-to-date
+- Include examples for complex functionality in docs/headers.md
+
+## Technology Stack
+- C++14 (minimum) for core implementation
+- CMake build system (3.14+)
+- Google Test for unit testing
+- Support for multiple compilers (MSVC, GCC, Clang)
+
+## Security Considerations
+- Bounds checking is a core principle - enforce it consistently
+- Design for safety while minimizing overhead
+- Ensure undefined behavior is explicitly detected where possible
+
+## Performance Guidelines
+- Optimize for both safety and performance
+- Constexpr-enable functions wherever possible
+- Avoid hidden allocations
+- Use noexcept appropriately for move operations and other performance-critical functions
+
+## Cross-Platform Support
+- Code must work across:
+  - Windows (MSVC)
+  - Linux (GCC, Clang)
+  - macOS (AppleClang)
+  - Android and iOS where applicable
+
+## Copilot Tasks
+- You can find the CMake artifacts for C++20 in build-cxx20 and C++14 in build-cxx14.
+- Before publishing a PR, verify the following:
+  - There are no compiler warnings or errors when building the test suite.
+  - The test suite passes on all supported platforms and compilers.
+  - The test suite passes for both C++14 and C++20.

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,22 @@
+name: "Copilot Setup Steps"
+
+on: workflow_dispatch
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Build Dependencies
+        run: sudo apt-get update && sudo apt-get install -y clang cmake make
+
+      - name: Configure CMake (C++14)
+        run: cmake -B build-cxx14 . -DGSL_CXX_STANDARD=14 -DGSL_TEST=ON -G "Unix Makefiles"
+
+      - name: Configure CMake (C++20)
+        run: cmake -B build-cxx20 . -DGSL_CXX_STANDARD=20 -DGSL_TEST=ON -G "Unix Makefiles"
+

.gitignore

@@ -1,5 +1,5 @@
 CMakeFiles
-build
+build*/
 tests/CMakeFiles
 tests/Debug
 *.opensdf

docs/headers.md

@@ -412,22 +412,36 @@ The `gsl::span` is based on the standardized version of `std::span` which was ad
 deprecate `gsl::span` when `std::span` finished standardization, however that plan changed when the runtime bounds checking
 was removed from `std::span`'s design.
 
-The only difference between `gsl::span` and `std::span` is that `gsl::span` strictly enforces runtime bounds checking.
-Any violations of the bounds check results in termination of the program.
-Like `gsl::span`, `gsl::span`'s iterators also differ from `std::span`'s iterator in that all access operations are bounds checked.
+The key differences between `gsl::span` and `std::span` are:
+- `gsl::span` strictly enforces runtime bounds checking for all access operations
+- Any violations of the bounds check results in termination of the program
+- `gsl::span`'s iterators also perform bounds checking, unlike `std::span`'s iterators
 
 #### Which version of span should I use?
 
-##### Use `gsl::span` if
+The following table compares the different span implementations to help you choose which one is best for your project:
 
-- you want to guarantee bounds safety in your project.
-  - All data accessing operations use bounds checking to ensure you are only accessing valid memory.
-- your project uses C++14 or C++17.
-  - `std::span` is not available as it was not introduced into the STL until C++20.
+| Feature/Version | `std::span` (C++20/23) | Hardened `std::span` (C++26) | `gsl::span` |
+|-----------------|------------------------|------------------------------|-------------|
+| **C++ Standard** | Requires C++20 or later | Requires C++26 or backported implementation | Works with C++14 or later |
+| **Element Access** | No bounds checking | Bounds checking | Bounds checking |
+| **Iterator Safety** | No bounds checking | Implementation-defined, may depend on vendor | Full bounds checking |
+| **Error Behavior** | Undefined behavior on invalid access | Implementation-defined, may be configurable | Always calls [`std::terminate()`](https://en.cppreference.com/w/cpp/error/terminate) via [gsl::details::terminate()](https://github.com/microsoft/GSL/blob/main/include/gsl/assert#L111-L118) |
+| **Performance** | Fastest (no checking) | Varies by implementation and configuration | May have performance impact from bounds checking |
 
-##### Use `std::span` if
+**Recommendations:**
 
-- your project is C++20 and you need the performance offered by `std::span`.
+- **C++14 & C++17 projects**: Use `gsl::span` as `std::span` is not available.
+- **C++20 & C++23 projects**: 
+  - Use `gsl::span` if safety is your priority.
+  - Use `std::span` if performance is critical and you're confident in your index calculations.
+- **C++26 projects**: 
+  - Use `gsl::span` if you need guaranteed iterator safety across all platforms.
+  - Use hardened `std::span` if you want standard library compliance and acceptable safety.
+
+**Implementation notes for hardened `std::span` in C++26:**
+- For MSVC: See [Microsoft STL Hardening](https://github.com/microsoft/STL/wiki/STL-Hardening)
+- For Clang/LLVM: See [libc++ Hardening](https://libcxx.llvm.org/Hardening.html)
 
 #### Types
 

include/gsl/pointers

@@ -54,7 +54,7 @@ namespace details
     // Copied from cppfront's implementation of the CppCoreGuidelines F.16 (https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-in)
     template<typename T>
     using value_or_reference_return_t = std::conditional_t<
-                                            sizeof(T) < 2*sizeof(void*) && std::is_trivially_copy_constructible<T>::value,
+                                            sizeof(T) <= 2*sizeof(void*) && std::is_trivially_copy_constructible<T>::value,
                                             const T,
                                             const T&>;
 
@@ -173,7 +173,7 @@ std::ostream& operator<<(std::ostream& os, const not_null<T>& val)
 #endif // !defined(GSL_NO_IOSTREAMS)
 
 template <class T, class U>
-auto operator==(const not_null<T>& lhs,
+constexpr auto operator==(const not_null<T>& lhs,
                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() == rhs.get()))
     -> decltype(lhs.get() == rhs.get())
 {
@@ -181,7 +181,7 @@ auto operator==(const not_null<T>& lhs,
 }
 
 template <class T, class U>
-auto operator!=(const not_null<T>& lhs,
+constexpr auto operator!=(const not_null<T>& lhs,
                 const not_null<U>& rhs) noexcept(noexcept(lhs.get() != rhs.get()))
     -> decltype(lhs.get() != rhs.get())
 {
@@ -189,7 +189,7 @@ auto operator!=(const not_null<T>& lhs,
 }
 
 template <class T, class U>
-auto operator<(const not_null<T>& lhs,
+constexpr auto operator<(const not_null<T>& lhs,
                const not_null<U>& rhs) noexcept(noexcept(std::less<>{}(lhs.get(), rhs.get())))
     -> decltype(std::less<>{}(lhs.get(), rhs.get()))
 {
@@ -197,7 +197,7 @@ auto operator<(const not_null<T>& lhs,
 }
 
 template <class T, class U>
-auto operator<=(const not_null<T>& lhs,
+constexpr auto operator<=(const not_null<T>& lhs,
                 const not_null<U>& rhs) noexcept(noexcept(std::less_equal<>{}(lhs.get(), rhs.get())))
     -> decltype(std::less_equal<>{}(lhs.get(), rhs.get()))
 {
@@ -205,7 +205,7 @@ auto operator<=(const not_null<T>& lhs,
 }
 
 template <class T, class U>
-auto operator>(const not_null<T>& lhs,
+constexpr auto operator>(const not_null<T>& lhs,
                const not_null<U>& rhs) noexcept(noexcept(std::greater<>{}(lhs.get(), rhs.get())))
     -> decltype(std::greater<>{}(lhs.get(), rhs.get()))
 {
@@ -213,7 +213,7 @@ auto operator>(const not_null<T>& lhs,
 }
 
 template <class T, class U>
-auto operator>=(const not_null<T>& lhs,
+constexpr auto operator>=(const not_null<T>& lhs,
                 const not_null<U>& rhs) noexcept(noexcept(std::greater_equal<>{}(lhs.get(), rhs.get())))
     -> decltype(std::greater_equal<>{}(lhs.get(), rhs.get()))
 {

tests/CMakeLists.txt

@@ -204,6 +204,7 @@ add_executable(gsl_tests
     assertion_tests.cpp
     at_tests.cpp
     byte_tests.cpp
+    constexpr_notnull_tests.cpp
     notnull_tests.cpp
     owner_tests.cpp
     pointers_tests.cpp

tests/constexpr_notnull_tests.cpp

@@ -0,0 +1,74 @@
+///////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2025 Microsoft Corporation. All rights reserved.
+//
+// This code is licensed under the MIT License (MIT).
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+//
+///////////////////////////////////////////////////////////////////////////////
+
+#include <gsl/pointers> // for not_null
+#include <gtest/gtest.h>
+
+#include <type_traits> // for declval
+
+using namespace gsl;
+
+namespace
+{
+constexpr bool comparison_test(const int* ptr1, const int* ptr2)
+{
+    const not_null<const int*> p1(ptr1);
+    const not_null<const int*> p1_same(ptr1);
+    const not_null<const int*> p2(ptr2);
+    
+    // Testing operator==
+    const bool eq_result = (p1 == p1_same); // Should be true
+    const bool neq_result = (p1 != p2);     // Should be true
+    
+    // Testing operator<= and operator>=
+    const bool le_result = (p1 <= p1_same); // Should be true
+    const bool ge_result = (p1 >= p1_same); // Should be true
+    
+    // The exact comparison results will depend on pointer ordering,
+    // but we can verify that the basic equality checks work as expected
+    return eq_result && neq_result && le_result && ge_result;
+}
+
+constexpr bool workaround_test(const int* ptr1, const int* ptr2)
+{
+    const not_null<const int*> p1(ptr1);
+    const not_null<const int*> p1_same(ptr1);
+    const not_null<const int*> p2(ptr2);
+    
+    // Using .get() to compare
+    const bool eq_result = (p1.get() == p1_same.get()); // Should be true
+    const bool neq_result = (p1.get() != p2.get());     // Should be true
+    
+    return eq_result && neq_result;
+}
+} // namespace
+
+constexpr int test_value1 = 1;
+constexpr int test_value2 = 2;
+
+static_assert(comparison_test(&test_value1, &test_value2), "not_null comparison operators should be constexpr");
+static_assert(workaround_test(&test_value1, &test_value2), "not_null .get() comparison workaround should work");
+
+TEST(notnull_constexpr_tests, TestNotNullConstexprComparison)
+{
+    // This test simply verifies that the constexpr functions compile and run
+    // If we got here, it means the constexpr comparison operators are working
+    static const int value1 = 1;
+    static const int value2 = 2;
+    EXPECT_TRUE(comparison_test(&value1, &value2));
+    EXPECT_TRUE(workaround_test(&value1, &value2));
+}
+