https://github.com/simulation-tree/unmanaged
The building blocks of native C# projects
https://github.com/simulation-tree/unmanaged
csharp dotnet nativeaot
Last synced: 5 months ago
JSON representation
The building blocks of native C# projects
- Host: GitHub
- URL: https://github.com/simulation-tree/unmanaged
- Owner: simulation-tree
- License: mit
- Created: 2024-04-09T21:41:49.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-24T03:03:09.000Z (9 months ago)
- Last Synced: 2025-09-24T04:24:04.983Z (9 months ago)
- Topics: csharp, dotnet, nativeaot
- Language: C#
- Homepage:
- Size: 810 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Unmanaged
[](https://github.com/simulation-tree/unmanaged/actions/workflows/test.yml)
Library containing primitives for working with native C#.
### Installation
Install it by cloning it, or referencing through the NuGet package through GitHub's registry ([authentication info](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#authenticating-to-github-packages)).
For installing as a Unity package, use this git url to add it:
```
https://github.com/simulation-tree/unmanaged.git?path=core#unity
```
### Memory Addresses
`MemoryAddress` instances can point to either heap or stack memory. They can be
allocated using static methods, in which case they must also be disposed:
```cs
//an allocation that is 10 bytes in size
using (MemoryAddress allocation = MemoryAddress.Allocate(sizeof(char) * 5))
{
allocation.Write("Hello".AsSpan());
Span text = allocation.AsSpan();
}
//an allocation containing a float
using (MemoryAddress allocation = MemoryAddress.Create(3.14f))
{
ref float floatValue = ref allocation.Read();
floatValue *= 2;
}
```
### ASCII Text
The types prefixed with `ASCIIText` store extended ASCII `char` values.
Useful for when text is known to be short, until a list/array is needed:
```cs
ASCIIText16 text = new("Hello there");
Span textBuffer = stackalloc char[text.Length];
text.CopyTo(textBuffer);
//get utf8 bytes from the text
Span utf8bytes = stackalloc char[ASCIIText16.Capacity];
uint bytesCopied = text.CopyTo(utf8bytes);
//get text from utf8 bytes using System.Text.Encoding
ASCIIText1024 textFromBytes = new(utf8bytes.Slice(0, bytesCopied));
string systemString = Encoding.UTF8.GetString(textBuffer.Slice(0, length));
Assert.That(textFromBytes.ToString(), Is.EqualTo(systemString));
//casting to a smaller type
ASCIIText32 textFromBytesButSmaller = textFromBytes;
Assert.That(textFromBytesButSmaller.ToString(), Is.EqualTo(systemString));
```
### Text
Accompanying the above is the disposable `Text` type, which is a reference to an arbitrary amount of `char`s values.
And behaves like a `string`:
```cs
using Text builder = new();
builder.Append("Hello");
builder.Append(" there");
ReadOnlySpan text = builder.AsSpan();
Console.WriteLine(text.ToString());
```
### Random Generator
Can generate random data and values using the XORshift technique:
```cs
using RandomGenerator random = new();
int fairDiceRoll = random.NextInt(0, 6);
```
> The default random seed is based on process ID, current time, and instance index.
### Safety
When working with `MemoryAddress` values, there are checks available to ensure
that the memory is not accessed after it has been disposed, or accessed out of bounds.
This only occurs in debug mode, or with the `#TRACK` directive defined, and only on
heap allocated memory through the `MemoryAddress` methods.
Ultimately, it is the programmer's responsibility for how memory should be managed. Including
when allocations should be disposed, and how they should be accessed.
### Included `default` analyzer
Included is an analyzer that emits errors where a disposable struct type is
being created, but then initialized to `default`. Because disposable types
imply they have a way to properly initialize them:
```cs
Allocation allocation = default; //U0001 error
```
There is no analysis for `new()` however, because a default constructor with
value types can be by design. Though if not, they can be declared with an
`[Obsolete("", true)]` attribute with the parameter `true` to disallow it.
### Contributing and direction
This library is made to provide building blocks for working with native code in C#.
For minimizing runtime cost and to expose the efficiency that was always there.
Commonly putting the author in a position where they need to exercise more control.
> _with great power, comes great responsibility_
Contributions that fit this are welcome.