Merge C++20 bit operations support and modernization by Aki Kuri Chan

Author: akikurichan

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+*   Demonstrating empathy and kindness toward other people
+*   Being respectful of differing opinions, viewpoints, and experiences
+*   Giving and gracefully accepting constructive feedback
+*   Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+*   Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+*   The use of sexualized language or imagery, and sexual attention or advances of any kind
+*   Trolling, insulting or derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or email address, without their explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [INSERT CONTACT METHOD, e.g., email or create a private issue].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.

docs/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+The license for this work does not require you to share changes you make
+in your own version of the code.  Contributions are welcome, however.
+
+## License
+
+This work is licensed under either of
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE.txt) or http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT.txt) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+## Contribution Policy
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in this work by you, as defined in the
+Apache-2.0 license, shall be dual licensed as above, without any
+additional terms or conditions.

docs/CREDITS.md

@@ -0,0 +1,78 @@
+# Credits and Attributions
+
+This modernized fork of `pcg-cpp` by **Total-Random** integrates several critical fixes and improvements from the community. Below is a list of changes and their original sources.
+
+---
+
+## Community Fixes
+
+### 1. Optimized `unxorshift`
+
+- **Origin:** [imneme/pcg-cpp PR #82](https://github.com/imneme/pcg-cpp/pull/82)
+- **Author:** [LRFLEW](https://github.com/LRFLEW)
+- **Description:** Implements a more efficient inverse xorshift operation.
+
+### 2. Empty Base Class Optimization (EBCO) for MSVC
+
+- **Origin:** [imneme/pcg-cpp PR #66](https://github.com/imneme/pcg-cpp/pull/66)
+- **Author:** [melak47](https://github.com/melak47)
+- **Description:** Enables `__declspec(empty_bases)` on MSVC to optimize the memory footprint of RNG objects.
+
+### 3. Public `result_type` in `seed_seq_from`
+
+- **Origin:** [imneme/pcg-cpp PR #83](https://github.com/imneme/pcg-cpp/pull/83)
+- **Author:** [timo-eichhorn](https://github.com/timo-eichhorn)
+- **Description:** Makes `result_type` public to comply with the C++ `SeedSequence` concept.
+
+### 4. GCC Warning Fixes
+
+- **Origin:** [SupercriticalSynthesizers/pcg-cpp PR fix-gcc-warnings](https://github.com/SupercriticalSynthesizers/pcg-cpp/tree/fix-gcc-warnings)
+- **Author:** [Timo Alho](https://github.com/tialho)
+- **Description:** Resolves various GCC warnings (clz/ctz truncation) when building with `-Wall`.
+
+### 5. Native Windows ARM64 Support
+
+- **Origin:** [imneme/pcg-cpp PR #99](https://github.com/imneme/pcg-cpp/pull/99)
+- **Author:** [Demonese](https://github.com/Demonese)
+- **Description:** Added native support for ARM64 on MSVC using `__umulh` for efficient 128-bit multiplication.
+
+### 6. Sample and Include Cleanups
+
+- **Author:** [brt-v](https://github.com/brt-v)
+- **Description:** Simplified header includes in sample programs and added `basic_usage.cpp` sample.
+
+---
+
+## Total-Random Improvements
+
+### 7. Modern CMake Build System
+
+- **Author:** [JkarVN](https://github.com/JkarVN)
+- **Description:** Comprehensive CMake integration with automated testing via `ctest`.
+
+### 8. MSVC Compatibility Fixes
+
+- **Author:** [JkarVN](https://github.com/JkarVN)
+- **Description:** Resolved several MSVC-specific issues (C2678, C4458, C1090, C4127).
+
+### 9. Modern C++ Best Practices
+
+- **Author:** [Antigravity AI](https://github.com/google-deepmind)
+- **Description:**
+  - Implementation of `PCG_NODISCARD` and modernize using `using` syntax.
+
+### 10. C++20 Bit Infrastructure Integration
+
+- **Author:** **Aki Kuri** ([@akikurichan](https://github.com/akikurichan))
+- **Description:**
+  - Integration of C++20 `<bit>` header support for `rotl`, `rotr`, `flog2`, and `trailingzeros`.
+  - Introduction of the `PCG_USE_BIT_HEADER` macro toggle for explicit bit operation control.
+  - Merged from pcg-next
+
+---
+
+## Special Thanks
+
+- **Melissa O'Neill** for the original PCG library.
+- **Ben Haller** ([bhaller](https://github.com/bhaller)) for early support.
+- **Robert Roessler** ([robertroessler](https://github.com/robertroessler)) for suggesting C++20 bit functions, implemented by **Aki Kuri**.

docs/GOVERNANCE.md

@@ -0,0 +1,49 @@
+# Project Governance
+
+The **pcg-cpp** project (under the **Total-Random** organization) is a community-driven open-source project. Our goal is to maintain and modernize the PCG random number generator library for C++, ensuring it remains accessible, stable, and performant for everyone.
+
+We believe that the best way to ensure the longevity of this project is to empower the community to take ownership.
+
+## 1. Principles
+
+*   **Openness:** All decision-making happens in public (GitHub Issues/Discussions).
+*   **Meritocracy:** Influence is earned through active contribution and commitment to the project.
+*   **Consensus:** We strive for consensus in all technical and governance decisions.
+
+## 2. Roles
+
+### Contributors
+Anyone who contributes to the project is a Contributor. Contributions include:
+*   Submitting Pull Requests (code, documentation, tests).
+*   Reporting issues and reproduction steps.
+*   Helping others in discussions.
+
+### Maintainers
+Maintainers are Contributors who have demonstrated a long-term commitment to the project's success. They have write access to the repository.
+
+**Responsibilities:**
+*   Reviewing and merging Pull Requests.
+*   Triaging and managing Issues.
+*   Ensuring code quality, CI stability, and release management.
+*   Mentoring new contributors.
+
+### Admins (Total-Random)
+Currently, the **Total-Random** organization holds administrative access. However, our intent is to facilitate the technical leadership of the Maintainers. Admins will intervene only in critical situations (e.g., security, code of conduct violations).
+
+## 3. Decision Making
+
+Process for making changes:
+1.  **Discussion:** Open an Issue or Pull Request to propose a change.
+2.  **Review:** At least one Maintainer must review and approve the change.
+3.  **Consensus:** For major changes (API breaking, governance), we seek lazy consensus (wait 72 hours for objections).
+
+## 4. Becoming a Maintainer
+
+We actively welcome new Maintainers. To become a Maintainer:
+1.  Demonstrate consistent contributions (PRs, reviews, helpful comments).
+2.  Express interest in helping maintain the project.
+3.  Existing Maintainers will vote/agree.
+
+## 5. Code of Conduct
+
+All participants must adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) to ensure a safe and welcoming environment.

include/pcg_extras.hpp

@@ -44,6 +44,12 @@
 #include <utility>
 #include <locale>
 #include <iterator>
+#include <limits>
+
+#if __cplusplus >= 202002L || (defined(_MSVC_LANG) && _MSVC_LANG >= 202002L) || defined(PCG_USE_BIT_HEADER)
+    #include <bit>
+    #define PCG_BIT_SUPPORT 1
+#endif
 
 #ifdef __GNUC__
     #include <cxxabi.h>
@@ -287,6 +293,11 @@ inline itype unxorshift(itype x, bitcount_t bits, bitcount_t shift)
 template <typename itype>
 inline itype rotl(itype value, bitcount_t rot)
 {
+#if PCG_BIT_SUPPORT
+    if constexpr (std::is_integral_v<itype> && std::is_unsigned_v<itype>) {
+        return std::rotl(value, (int)rot);
+    }
+#endif
     constexpr bitcount_t bits = sizeof(itype) * 8;
     constexpr bitcount_t mask = bits - 1;
 #if PCG_USE_ZEROCHECK_ROTATE_IDIOM
@@ -299,6 +310,11 @@ inline itype rotl(itype value, bitcount_t rot)
 template <typename itype>
 inline itype rotr(itype value, bitcount_t rot)
 {
+#if PCG_BIT_SUPPORT
+    if constexpr (std::is_integral_v<itype> && std::is_unsigned_v<itype>) {
+        return std::rotr(value, (int)rot);
+    }
+#endif
     constexpr bitcount_t bits = sizeof(itype) * 8;
     constexpr bitcount_t mask = bits - 1;
 #if PCG_USE_ZEROCHECK_ROTATE_IDIOM

include/pcg_uint128.hpp

@@ -40,6 +40,14 @@
 #include <cstdio>
 #include <cassert>
 #include <climits>
+
+#if __cplusplus >= 202002L || (defined(_MSVC_LANG) && _MSVC_LANG >= 202002L) || defined(PCG_USE_BIT_HEADER)
+    #include <bit>
+    #ifndef PCG_BIT_SUPPORT
+        #define PCG_BIT_SUPPORT 1
+    #endif
+#endif
+#include <cassert>
 #include <utility>
 #include <initializer_list>
 #include <type_traits>
@@ -100,7 +108,29 @@ namespace pcg_extras {
  *      * trailingzeros         number of trailing zero bits
  */
 
-#if defined(__GNUC__)   // Any GNU-compatible compiler supporting C++11 has
+#if PCG_BIT_SUPPORT
+
+inline bitcount_t flog2(uint32_t v)
+{
+    return bitcount_t(std::bit_width(v) - 1);
+}
+
+inline bitcount_t trailingzeros(uint32_t v)
+{
+    return bitcount_t(std::countr_zero(v));
+}
+
+inline bitcount_t flog2(uint64_t v)
+{
+    return bitcount_t(std::bit_width(v) - 1);
+}
+
+inline bitcount_t trailingzeros(uint64_t v)
+{
+    return bitcount_t(std::countr_zero(v));
+}
+
+#elif defined(__GNUC__)   // Any GNU-compatible compiler supporting C++11 has
                         // some useful intrinsics we can use.
                         // These bitcount_t casts are from SupercriticalSynthesizers/pcg-cpp PR fix-gcc-warnings
 

test_seed_1234.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <vector>
+#include <cstdint>
+#include "include/pcg_random.hpp"
+
+using namespace std;
+
+int main() {
+    // Both C library and this C++ library default stream might differ if not specified.
+    // Let's test with just seed = 1234u, and if needed, specific seq. 
+    pcg32 rng(1234u, 54u); // Try with standard sequence 54 provided in samples
+    pcg32 rng_default(1234u); // Default sequence
+
+    vector<uint32_t> expected = {
+        2653504168,
+        209608674,
+        1195720523,
+        3249742110,
+        76957682,
+        3144134622,
+        2510553852,
+        2126586030,
+        2110775405,
+        2940631255
+    };
+
+    cout << "Testing with pcg32(1234u):" << endl;
+    for (int i = 0; i < 10; ++i) {
+        cout << rng_default() << endl;
+    }
+    
+    return 0;
+}