Add UInt24 readonly struct with .NET 10 generic math interfaces

.github/workflows/release.yml

@@ -26,3 +26,28 @@ jobs:
           directory: src
           nuget-api-key: ${{ secrets.NUGET_API_KEY }}
           version: ${{ inputs.version }}
+
+      - name: Build
+        uses: MrKWatkins/dotnet-build@main
+        with:
+          name: MrKWatkins.BinaryPrimitives
+          directory: src
+
+      - name: Restore .NET tools
+        run: dotnet tool restore
+
+      - name: Install Sesharp
+        run: dotnet tool install MrKWatkins.Sesharp.Tool
+
+      - name: Make API Docs Directory
+        run: mkdir doc/docs/API
+
+      - name: Generate API Docs
+        run: dotnet sesharp src/MrKWatkins.BinaryPrimitives/bin/Release/net10.0/MrKWatkins.BinaryPrimitives.dll doc/docs/API
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: doc/mkdocs.yml
+          REQUIREMENTS: doc/requirements.txt

ReadMe.md

@@ -8,6 +8,92 @@
 
 The name is based on the [BinaryPrimitives](https://learn.microsoft.com/en-us/dotnet/api/system.buffers.binary.binaryprimitives) class in the .NET Framework which provides similar methods.
 
+Full documentation is available at [mrkwatkins.github.io/BinaryPrimitives](https://mrkwatkins.github.io/BinaryPrimitives/). Source code and issue tracking are on [GitHub](https://github.com/MrKWatkins/BinaryPrimitives).
+
+## Installation
+
+```
+dotnet add package MrKWatkins.BinaryPrimitives
+```
+
+## Usage
+
+### Reading and Writing
+
+Read and write multi-byte integers from `byte[]`, `Span<byte>`, `Stream`, and other byte
+container types. All methods support an optional `Endian` parameter (defaulting to
+`Endian.Little`):
+
+```csharp
+byte[] data = new byte[8];
+data.SetInt32(0, 42);
+data.SetUInt16(4, 1000, Endian.Big);
+
+int    a = data.GetInt32(0);              // 42
+ushort b = data.GetUInt16(4, Endian.Big); // 1000
+```
+
+Collections can have values appended directly:
+
+```csharp
+var buffer = new List<byte>();
+buffer.AddUInt32(0xDEADBEEF);
+buffer.AddInt16(-1, Endian.Big);
+```
+
+Streams support typed reading and writing, with async overloads for all methods:
+
+```csharp
+stream.WriteInt32(42);
+int value = stream.ReadInt32OrThrow();
+```
+
+### Bit Operations
+
+Get, set, and clear individual bits or ranges of bits on `byte`, `ushort`, `int`, `uint`,
+`long`, and `ulong`:
+
+```csharp
+byte b = 0b00001010;
+bool set   = b.GetBit(1);     // true
+byte with0 = b.SetBit(0);     // 0b00001011
+byte clear = b.ResetBit(1);   // 0b00001000
+byte range = b.GetBits(1, 3); // bits 1..3, shifted to position 0
+```
+
+`byte` also provides nibble access, parity, and CPU flag detection:
+
+```csharp
+byte high = b.HighNibble(); // bits 4-7
+bool even = b.Parity();     // true if an even number of bits are set
+```
+
+All supported integer types can be formatted as a binary string:
+
+```csharp
+string s = ((byte)0x5A).ToBinaryString(); // "0b01011010"
+```
+
+### Streams
+
+`ReadOnlyListStream` wraps an `IReadOnlyList<byte>` as a seekable, read-only `Stream`:
+
+```csharp
+IReadOnlyList<byte> bytes = LoadBytes();
+using var stream = new ReadOnlyListStream(bytes);
+```
+
+`PeekableStream` wraps any readable `Stream` to add one-byte lookahead without consuming the
+byte:
+
+```csharp
+using var stream = new PeekableStream(inner);
+if (stream.Peek() == 0xFF)
+{
+    stream.ReadByteOrThrow(); // consume it
+}
+```
+
 ## Licencing
 
 Licensed under GPL v3.0.

doc/.gitignore

@@ -0,0 +1,171 @@
+copilot.data.*.xml
+data/
+node_modules/
+docs/assets/javascripts/
+docs/assets/vocabulary/categories.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+logs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+test_results.xml
+test-results.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/