dotnet/src/CommunityToolkit.HighPerformance/Extensions/MemoryExtensions.cs at 89d6647a1f45e91aa0784b5143f184faef6f44cf · CommunityToolkit/dotnet · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

using System;
using System.IO;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using MemoryStream = CommunityToolkit.HighPerformance.Streams.MemoryStream;

namespace CommunityToolkit.HighPerformance;

/// <summary>
/// Helpers for working with the <see cref="Memory{T}"/> type.
/// </summary>
public static class MemoryExtensions
{
#if NETSTANDARD2_1_OR_GREATER
    /// <summary>
    /// Returns a <see cref="Memory2D{T}"/> instance wrapping the underlying data for the given <see cref="Memory{T}"/> instance.
    /// </summary>
    /// <typeparam name="T">The type of items in the input <see cref="Memory{T}"/> instance.</typeparam>
    /// <param name="memory">The input <see cref="Memory{T}"/> instance.</param>
    /// <param name="height">The height of the resulting 2D area.</param>
    /// <param name="width">The width of each row in the resulting 2D area.</param>
    /// <returns>The resulting <see cref="Memory2D{T}"/> instance.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Thrown when one of the input parameters is out of range.
    /// </exception>
    /// <exception cref="ArgumentException">
    /// Thrown when the requested area is outside of bounds for <paramref name="memory"/>.
    /// </exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory2D<T> AsMemory2D<T>(this Memory<T> memory, int height, int width)
    {
        return new(memory, height, width);
    }

    /// <summary>
    /// Returns a <see cref="Memory2D{T}"/> instance wrapping the underlying data for the given <see cref="Memory{T}"/> instance.
    /// </summary>
    /// <typeparam name="T">The type of items in the input <see cref="Memory{T}"/> instance.</typeparam>
    /// <param name="memory">The input <see cref="Memory{T}"/> instance.</param>
    /// <param name="offset">The initial offset within <paramref name="memory"/>.</param>
    /// <param name="height">The height of the resulting 2D area.</param>
    /// <param name="width">The width of each row in the resulting 2D area.</param>
    /// <param name="pitch">The pitch in the resulting 2D area.</param>
    /// <returns>The resulting <see cref="Memory2D{T}"/> instance.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Thrown when one of the input parameters is out of range.
    /// </exception>
    /// <exception cref="ArgumentException">
    /// Thrown when the requested area is outside of bounds for <paramref name="memory"/>.
    /// </exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory2D<T> AsMemory2D<T>(this Memory<T> memory, int offset, int height, int width, int pitch)
    {
        return new(memory, offset, height, width, pitch);
    }

    /// <summary>
    /// Returns a <see cref="Memory3D{T}"/> instance wrapping the underlying data for the given <see cref="Memory{T}"/> instance.
    /// </summary>
    /// <typeparam name="T">The type of items in the input <see cref="Memory{T}"/> instance.</typeparam>
    /// <param name="memory">The input <see cref="Memory{T}"/> instance.</param>
    /// <param name="depth">The depth of the resulting 3D volume.</param>
    /// <param name="height">The height of each slice in the resulting 3D volume.</param>
    /// <param name="width">The width of each row in the resulting 3D volume.</param>
    /// <returns>The resulting <see cref="Memory3D{T}"/> instance.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Thrown when one of the input parameters is out of range.
    /// </exception>
    /// <exception cref="ArgumentException">
    /// Thrown when the requested volume is outside of bounds for <paramref name="memory"/>.
    /// </exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory3D<T> AsMemory3D<T>(this Memory<T> memory, int depth, int height, int width)
    {
        return new(memory, depth, height, width);
    }

    /// <summary>
    /// Returns a <see cref="Memory3D{T}"/> instance wrapping the underlying data for the given <see cref="Memory{T}"/> instance.
    /// </summary>
    /// <typeparam name="T">The type of items in the input <see cref="Memory{T}"/> instance.</typeparam>
    /// <param name="memory">The input <see cref="Memory{T}"/> instance.</param>
    /// <param name="offset">The initial offset within <paramref name="memory"/>.</param>
    /// <param name="depth">The depth of the resulting 3D volume.</param>
    /// <param name="height">The height of each slice in the resulting 3D volume.</param>
    /// <param name="width">The width of each row in the resulting 3D volume.</param>
    /// <param name="slicePitch">The pitch of each slice in the resulting 3D volume (distance between slices).</param>
    /// <param name="rowPitch">The pitch of each row in the resulting 3D volume (distance between rows).</param>
    /// <returns>The resulting <see cref="Memory3D{T}"/> instance.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Thrown when one of the input parameters is out of range.
    /// </exception>
    /// <exception cref="ArgumentException">
    /// Thrown when the requested volume is outside of bounds for <paramref name="memory"/>.
    /// </exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory3D<T> AsMemory3D<T>(this Memory<T> memory, int offset, int depth, int height, int width, int slicePitch, int rowPitch)
    {
        return new(memory, offset, depth, height, width, slicePitch, rowPitch);
    }
#endif

    /// <summary>
    /// Casts a <see cref="Memory{T}"/> of one primitive type <typeparamref name="T"/> to <see cref="Memory{T}"/> of bytes.
    /// </summary>
    /// <typeparam name="T">The type if items in the source <see cref="Memory{T}"/>.</typeparam>
    /// <param name="memory">The source <see cref="Memory{T}"/>, of type <typeparamref name="T"/>.</param>
    /// <returns>A <see cref="Memory{T}"/> of bytes.</returns>
    /// <exception cref="OverflowException">
    /// Thrown if the <see cref="Memory{T}.Length"/> property of the new <see cref="Memory{T}"/> would exceed <see cref="int.MaxValue"/>.
    /// </exception>
    /// <exception cref="ArgumentException">Thrown when the data store of <paramref name="memory"/> is not supported.</exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory<byte> AsBytes<T>(this Memory<T> memory)
        where T : unmanaged
    {
        return MemoryMarshal.AsMemory(((ReadOnlyMemory<T>)memory).Cast<T, byte>());
    }

    /// <summary>
    /// Casts a <see cref="Memory{T}"/> of one primitive type <typeparamref name="TFrom"/> to another primitive type <typeparamref name="TTo"/>.
    /// </summary>
    /// <typeparam name="TFrom">The type of items in the source <see cref="Memory{T}"/>.</typeparam>
    /// <typeparam name="TTo">The type of items in the destination <see cref="Memory{T}"/>.</typeparam>
    /// <param name="memory">The source <see cref="Memory{T}"/>, of type <typeparamref name="TFrom"/>.</param>
    /// <returns>A <see cref="Memory{T}"/> of type <typeparamref name="TTo"/></returns>
    /// <exception cref="ArgumentException">Thrown when the data store of <paramref name="memory"/> is not supported.</exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Memory<TTo> Cast<TFrom, TTo>(this Memory<TFrom> memory)
        where TFrom : unmanaged
        where TTo : unmanaged
    {
        return MemoryMarshal.AsMemory(((ReadOnlyMemory<TFrom>)memory).Cast<TFrom, TTo>());
    }

    /// <summary>
    /// Returns a <see cref="Stream"/> wrapping the contents of the given <see cref="Memory{T}"/> of <see cref="byte"/> instance.
    /// </summary>
    /// <param name="memory">The input <see cref="Memory{T}"/> of <see cref="byte"/> instance.</param>
    /// <returns>A <see cref="Stream"/> wrapping the data within <paramref name="memory"/>.</returns>
    /// <remarks>
    /// Since this method only receives a <see cref="Memory{T}"/> instance, which does not track
    /// the lifetime of its underlying buffer, it is responsibility of the caller to manage that.
    /// In particular, the caller must ensure that the target buffer is not disposed as long
    /// as the returned <see cref="Stream"/> is in use, to avoid unexpected issues.
    /// </remarks>
    /// <exception cref="ArgumentException">Thrown when <paramref name="memory"/> has an invalid data store.</exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public static Stream AsStream(this Memory<byte> memory)
    {
        return MemoryStream.Create(memory, false);
    }
}