Skip to content

Start adding docs to Utilities #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rjvs wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Start adding docs to Utilities #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea4267e
Moved NativeMemory into StirlingLabs.Utilities namespace instead of S…
Rjvs Jul 15, 2023
f7fe7c4
upgraded dependencies
Rjvs Jul 15, 2023
ab28265
Added ML-generated doc comments
Rjvs Jul 15, 2023
8adad8b
recommend using builtin NativeMemory if possible
Rjvs Jul 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions StirlingLabs.Utilities.Extensions/StirlingLabs.Utilities.Extensions.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@
</ImportGroup>

<ItemGroup>
<PackageReference Include="Fody" Version="6.6.4" PrivateAssets="all" />
<PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
<PackageReference Include="InlineIL.Fody" Version="1.7.4" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="StirlingLabs.LLVMSharp" Version="14.0.6.44479" />
<PackageReference Include="StirlingLabs.LLVMSharp.Interop" Version="14.0.6.44479" />
<PackageReference Include="StirlingLabs.libLLVM" Version="14.0.6.4" />
Expand Down
4 changes: 2 additions & 2 deletions StirlingLabs.Utilities.Magic/StirlingLabs.Utilities.Magic.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@
</ImportGroup>

<ItemGroup>
<PackageReference Include="Fody" Version="6.6.4" PrivateAssets="all" />
<PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
<PackageReference Include="InlineIL.Fody" Version="1.7.4" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
</ItemGroup>

<ItemGroup Condition="'$(TargetFramework)'=='netstandard2.0'">
Expand Down
2 changes: 1 addition & 1 deletion StirlingLabs.Utilities.NativeLibrary/StirlingLabs.Utilities.NativeLibrary.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
</ItemGroup>

<ImportGroup>
Expand Down
6 changes: 3 additions & 3 deletions StirlingLabs.Utilities.Simple.Tests/StirlingLabs.Utilities.Simple.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@
</ItemGroup>

<ItemGroup>
<PackageReference Include="FluentAssertions" Version="6.10.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="FluentAssertions" Version="6.11.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
<PackageReference Include="StirlingLabs.Tests" Version="23.3.4" />
<PackageReference Include="coverlet.collector" Version="3.2.0" PrivateAssets="All" />
<PackageReference Include="coverlet.collector" Version="6.0.0" PrivateAssets="All" />
</ItemGroup>

<ItemGroup>
Expand Down
12 changes: 6 additions & 6 deletions StirlingLabs.Utilities.Tests/StirlingLabs.Utilities.Tests.Net60.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,16 @@
<ItemGroup>
<PackageReference Include="StirlingLabs.libLLVM" Version="14.0.6.4" />
<PackageReference Include="AutoBogus" Version="2.13.1" />
<PackageReference Include="FluentAssertions" Version="6.10.0" />
<PackageReference Include="FluentAssertions" Version="6.11.0" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="NUnit" Version="3.13.3" />
<PackageReference Include="NUnit3TestAdapter" Version="4.4.2" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
<PackageReference Include="StirlingLabs.BigSpans" Version="23.3.1" />
<PackageReference Include="StirlingLabs.BigSpans.NUnit" Version="23.3.1" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="3.2.0" PrivateAssets="all" />
<PackageReference Include="NuGet.Versioning" Version="6.5.0" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="6.0.0" PrivateAssets="all" />
<PackageReference Include="NuGet.Versioning" Version="6.6.1" />
</ItemGroup>

<Target Name="RIDCheck" BeforeTargets="Build">
Expand Down
12 changes: 6 additions & 6 deletions StirlingLabs.Utilities.Tests/StirlingLabs.Utilities.Tests.Net70.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,16 @@
<ItemGroup>
<PackageReference Include="StirlingLabs.libLLVM" Version="14.0.6.4" />
<PackageReference Include="AutoBogus" Version="2.13.1" />
<PackageReference Include="FluentAssertions" Version="6.10.0" />
<PackageReference Include="FluentAssertions" Version="6.11.0" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="NUnit" Version="3.13.3" />
<PackageReference Include="NUnit3TestAdapter" Version="4.4.2" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
<PackageReference Include="StirlingLabs.BigSpans" Version="23.3.1" />
<PackageReference Include="StirlingLabs.BigSpans.NUnit" Version="23.3.1" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="3.2.0" PrivateAssets="all" />
<PackageReference Include="NuGet.Versioning" Version="6.5.0" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="6.0.0" PrivateAssets="all" />
<PackageReference Include="NuGet.Versioning" Version="6.6.1" />
</ItemGroup>

<Target Name="RIDCheck" BeforeTargets="Build">
Expand Down
12 changes: 6 additions & 6 deletions StirlingLabs.Utilities.Tests/StirlingLabs.Utilities.Tests.Netstandard20.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,17 +48,17 @@
<ItemGroup>
<PackageReference Include="StirlingLabs.libLLVM" Version="14.0.6.4" />
<PackageReference Include="AutoBogus" Version="2.13.1" />
<PackageReference Include="FluentAssertions" Version="6.10.0" />
<PackageReference Include="FluentAssertions" Version="6.11.0" />
<PackageReference Include="NUnit" Version="3.13.3" />
<PackageReference Include="NUnit3TestAdapter" Version="4.4.2" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
<PackageReference Include="StirlingLabs.BigSpans" Version="23.3.1" />
<PackageReference Include="StirlingLabs.BigSpans.NUnit" Version="23.3.1" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="3.2.0" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="6.0.0" PrivateAssets="all" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
<PackageReference Include="NuGet.Versioning" Version="6.5.0" />
<PackageReference Include="NuGet.Versioning" Version="6.6.1" />
</ItemGroup>

<Target Name="RIDCheck" BeforeTargets="Build">
Expand Down
12 changes: 6 additions & 6 deletions StirlingLabs.Utilities.Tests/StirlingLabs.Utilities.Tests.Netstandard21.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,17 +48,17 @@
<ItemGroup>
<PackageReference Include="StirlingLabs.libLLVM" Version="14.0.6.4" />
<PackageReference Include="AutoBogus" Version="2.13.1" />
<PackageReference Include="FluentAssertions" Version="6.10.0" />
<PackageReference Include="FluentAssertions" Version="6.11.0" />
<PackageReference Include="NUnit" Version="3.13.3" />
<PackageReference Include="NUnit3TestAdapter" Version="4.4.2" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
<PackageReference Include="StirlingLabs.BigSpans" Version="23.3.1" />
<PackageReference Include="StirlingLabs.BigSpans.NUnit" Version="23.3.1" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="3.2.0" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="coverlet.collector" Version="6.0.0" PrivateAssets="all" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
<PackageReference Include="NuGet.Versioning" Version="6.5.0" />
<PackageReference Include="NuGet.Versioning" Version="6.6.1" />
</ItemGroup>

<Target Name="RIDCheck" BeforeTargets="Build">
Expand Down
1 change: 0 additions & 1 deletion StirlingLabs.Utilities.Tests/UtilitiesTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
using System.Runtime.CompilerServices;
using FluentAssertions;
using NUnit.Framework;
using StirlingLabs.Native;
using StirlingLabs.Utilities;

namespace StirlingLabs.Utilities.Tests;
Expand Down
1 change: 0 additions & 1 deletion StirlingLabs.Utilities.Text/ICU4X.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
using System.Text;
using System.Text.RegularExpressions;
using JetBrains.Annotations;
using NativeMemory = StirlingLabs.Native.NativeMemory;

namespace StirlingLabs.Utilities.Text;

Expand Down
2 changes: 1 addition & 1 deletion StirlingLabs.Utilities.Text/StirlingLabs.Utilities.Text.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
</ImportGroup>

<ItemGroup>
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="StirlingLabs.icu4x.runtime.linux-x64" Version="1.2.0" />
<PackageReference Include="StirlingLabs.icu4x.runtime.osx" Version="1.2.0" />
<PackageReference Include="StirlingLabs.icu4x.runtime.win-x64" Version="1.2.0" />
Expand Down
4 changes: 2 additions & 2 deletions StirlingLabs.Utilities.Yaml/StirlingLabs.Utilities.Yaml.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@
</ImportGroup>

<ItemGroup>
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="YamlDotNet" Version="13.1.0" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="YamlDotNet" Version="13.1.1" />
</ItemGroup>

<ItemGroup>
Expand Down
60 changes: 59 additions & 1 deletion StirlingLabs.Utilities/NativeMemory.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,13 @@
using JetBrains.Annotations;
using StirlingLabs.Utilities;

namespace StirlingLabs.Native;
namespace StirlingLabs.Utilities;

/// <summary>
/// A static utility class for interacting with unmanaged memory. Provides methods for allocating, deallocating, and manipulating memory.
/// It is recommended to use <see cref="System.Runtime.InteropServices.NativeMemory"/> instead of this class if you don't require compatibility
/// all the way back to .Net Standard.
/// </summary>
[PublicAPI]
[SuppressMessage("ReSharper", "InconsistentNaming")]
[SuppressMessage("ReSharper", "IdentifierTypo")]
Expand Down Expand Up @@ -39,9 +44,20 @@ static unsafe NativeMemory()
}
}

/// <summary>
/// Allocates unmanaged memory without initializing it.
/// </summary>
/// <param name="size">The size of the memory to allocate.</param>
/// <returns>A span of bytes representing the allocated memory.</returns>
public static unsafe Span<byte> AllocUnsafe(nuint size)
=> new(New(size), (int)size);

/// <summary>
/// Allocates unmanaged memory and initializes it to zero.
/// </summary>
/// <param name="count">The number of elements to allocate.</param>
/// <param name="size">The size of each element.</param>
/// <returns>A span of bytes representing the allocated memory.</returns>
public static unsafe Span<byte> Alloc(nuint count, nuint size)
=> new(New(count, size), (int)(count * size));

Expand Down Expand Up @@ -83,6 +99,11 @@ public static Span<byte> Alloc(nuint size)
initializer(p);
return p;
}

/// <summary>
/// Deallocates the specified memory.
/// </summary>
/// <param name="ptr">A pointer to the memory to deallocate.</param>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static unsafe void Free(void* ptr)
=> free(ptr);
Expand All @@ -99,13 +120,31 @@ public static unsafe void Free<T>(T* ptr) where T : unmanaged
public static unsafe nuint SizeOf<T>() where T : unmanaged
=> (nuint)sizeof(T);

/// <summary>
/// Copies memory from one location to another.
/// </summary>
/// <param name="from">A pointer to the source memory.</param>
/// <param name="to">A pointer to the destination memory.</param>
/// <param name="size">The size of the memory to copy.</param>
/// <returns>A pointer to the destination memory.</returns>
public static unsafe void* Copy(void* from, void* to, nuint size)
=> memmove(to, from, size);
}

/// <summary>
/// A static utility class for interacting with unmanaged memory for a specific type. Provides methods for allocating, reallocating, and manipulating memory.
/// It is recommended to use <see cref="System.Runtime.InteropServices.NativeMemory"/> instead of this class if you don't require compatibility
/// all the way back to .Net Standard.
/// </summary>
/// <typeparam name="T">The type of the elements in the memory.</typeparam>
[PublicAPI]
public static class NativeMemory<T> where T : unmanaged
{
/// <summary>
/// Allocates memory for a specific number of items of type T.
/// </summary>
/// <param name="count">The number of items to allocate (default is 1).</param>
/// <returns>A span representing the allocated memory.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static unsafe Span<T> New(nuint count = 1)
=> new(NativeMemory.New(count, SizeOf()), (int)count);
Expand All @@ -126,6 +165,12 @@ private static unsafe nuint MaxSizeOf<TNew>() where TNew : unmanaged
private static unsafe nuint MinSizeOf<TNew>() where TNew : unmanaged
=> (nuint)(sizeof(T) > sizeof(TNew) ? sizeof(TNew) : sizeof(T));

/// <summary>
/// Reallocates memory for a different type and/or size.
/// </summary>
/// <typeparam name="TNew">The type of the new elements in the memory.</typeparam>
/// <param name="ptr">A pointer to the memory to reallocate.</param>
/// <returns>A pointer to the reallocated memory.</returns>
public static unsafe TNew* ReAlloc<TNew>(T* ptr) where TNew : unmanaged
=> (TNew*)NativeMemory.realloc(ptr, (nuint)sizeof(TNew));

Expand All @@ -135,12 +180,25 @@ public static unsafe Span<TNew> ReAlloc<TNew>(Span<T> span, nuint count) where T
return new(NativeMemory.realloc(p, count * (nuint)sizeof(TNew)), (int)count);
}

/// <summary>
/// Resizes the allocated memory for a span.
/// </summary>
/// <param name="span">The span to resize.</param>
/// <param name="count">The new size for the span.</param>
/// <returns>A span representing the resized memory.</returns>
public static unsafe Span<T> Resize(Span<T> span, nuint count)
{
var p = Unsafe.AsPointer(ref span.GetPinnableReference());
return new(NativeMemory.realloc(p, count * (nuint)sizeof(T)), (int)count);
}

/// <summary>
/// Copies memory from one location to another, potentially changing the type of the data.
/// </summary>
/// <typeparam name="TNew">The type of the new elements in the memory.</typeparam>
/// <param name="from">A pointer to the source memory.</param>
/// <param name="to">A pointer to the destination memory.</param>
/// <returns>A pointer to the destination memory.</returns>
public static unsafe TNew* Copy<TNew>(T* from, TNew* to) where TNew : unmanaged
=> (TNew*)NativeMemory.memmove(to, from, MinSizeOf<TNew>());
}
4 changes: 2 additions & 2 deletions StirlingLabs.Utilities/StirlingLabs.Utilities.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@
</ImportGroup>

<ItemGroup>
<PackageReference Include="Fody" Version="6.6.4" PrivateAssets="all" />
<PackageReference Include="Fody" Version="6.8.0" PrivateAssets="all" />
<PackageReference Include="InlineIL.Fody" Version="1.7.4" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2022.3.1" PrivateAssets="all" />
<PackageReference Include="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all" />
<PackageReference Include="MedallionPriorityQueue.Inline" Version="1.1.0" PrivateAssets="all" />
<PackageReference Include="StirlingLabs.BigSpans" Version="23.3.1" />
<PackageReference Include="System.Reflection.Emit.Lightweight" Version="4.7.0" />
Expand Down
1 change: 0 additions & 1 deletion StirlingLabs.Utilities/Utf8String.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
using System.Text;
using System.Threading;
using JetBrains.Annotations;
using NativeMemory = StirlingLabs.Native.NativeMemory;
#if NET5_0_OR_GREATER
#endif

Expand Down