|
2 | 2 | // The .NET Foundation licenses this file to you under the MIT license. |
3 | 3 |
|
4 | 4 | using System.Buffers; |
5 | | -using System.Collections.Generic; |
6 | 5 | using System.Diagnostics.CodeAnalysis; |
7 | 6 |
|
8 | 7 | namespace System.Numerics.Tensors |
9 | 8 | { |
10 | | - |
11 | | - /// <summary> |
12 | | - /// Represents a read-only tensor. |
13 | | - /// </summary> |
| 9 | + /// <summary>Represents a read-only tensor.</summary> |
14 | 10 | [Experimental(Experimentals.TensorTDiagId, UrlFormat = Experimentals.SharedUrlFormat)] |
15 | 11 | public interface IReadOnlyTensor |
16 | 12 | { |
17 | | - /// <summary> |
18 | | - /// Gets a value that indicates whether the collection is currently empty. |
19 | | - /// </summary> |
| 13 | + /// <summary>Gets the specified element of the tensor.</summary> |
| 14 | + /// <param name="indexes">The index of the element for which to get.</param> |
| 15 | + /// <returns>The element that exists at <paramref name="indexes" />.</returns> |
| 16 | + /// <exception cref="ArgumentOutOfRangeException"> |
| 17 | + /// Thrown when one of the following conditions is met: |
| 18 | + /// * <paramref name="indexes" /> does not contain <see cref="Rank" /> elements |
| 19 | + /// * <paramref name="indexes" /> contains an element that is negative or greater than or equal to the corresponding dimension length |
| 20 | + /// </exception> |
| 21 | + object? this[params scoped ReadOnlySpan<nint> indexes] { get; } |
| 22 | + |
| 23 | + /// <inheritdoc cref="this[ReadOnlySpan{nint}]" /> |
| 24 | + object? this[params scoped ReadOnlySpan<NIndex> indexes] { get; } |
| 25 | + |
| 26 | + /// <summary>Gets the total number of items in the tensor.</summary> |
| 27 | + nint FlattenedLength { get; } |
| 28 | + |
| 29 | + /// <summary>Gets a value indicating whether this tensor is empty.</summary> |
| 30 | + /// <value><see langword="true"/> if this tensor is empty; otherwise, <see langword="false"/>.</value> |
20 | 31 | bool IsEmpty { get; } |
21 | 32 |
|
22 | | - /// <summary> |
23 | | - /// Gets a value that indicates whether the underlying buffer is pinned. |
24 | | - /// </summary> |
| 33 | + /// <summary>Gets a value that indicates whether the underlying buffer is pinned.</summary> |
25 | 34 | bool IsPinned { get; } |
26 | 35 |
|
27 | | - /// <summary> |
28 | | - /// Gets the number of elements in the tensor. |
29 | | - /// </summary> |
30 | | - nint FlattenedLength { get; } |
31 | | - |
32 | | - /// <summary> |
33 | | - /// Gets the number of dimensions in the tensor. |
34 | | - /// </summary> |
35 | | - int Rank { get; } |
36 | | - |
37 | | - /// <summary> |
38 | | - /// Gets the length of each dimension in the tensor. |
39 | | - /// </summary> |
| 36 | + /// <summary>Gets the length of each dimension in the tensor.</summary> |
40 | 37 | [UnscopedRef] |
41 | 38 | ReadOnlySpan<nint> Lengths { get; } |
42 | 39 |
|
43 | | - /// <summary> |
44 | | - /// Gets the stride of each dimension in the tensor. |
45 | | - /// </summary> |
| 40 | + /// <summary>Gets the rank, or number of dimensions, in the tensor.</summary> |
| 41 | + int Rank { get; } |
| 42 | + |
| 43 | + /// <summary>Gets the stride of each dimension in the tensor.</summary> |
46 | 44 | [UnscopedRef] |
47 | 45 | ReadOnlySpan<nint> Strides { get; } |
48 | 46 |
|
49 | | - /// <summary> |
50 | | - /// Gets the value at the specified indexes. |
51 | | - /// </summary> |
52 | | - /// <param name="indexes">The indexes to be used.</param> |
53 | | - object this[params scoped ReadOnlySpan<nint> indexes] { get; } |
54 | | - |
55 | | - /// <summary> |
56 | | - /// Gets the value at the specified indexes. |
57 | | - /// </summary> |
58 | | - /// <param name="indexes">The indexes to be used.</param> |
59 | | - object this[params scoped ReadOnlySpan<NIndex> indexes] { get; } |
60 | | - |
61 | | - /// <summary> |
62 | | - /// Pins and gets a <see cref="MemoryHandle"/> to the backing memory. |
63 | | - /// </summary> |
| 47 | + /// <summary>Pins and gets a <see cref="MemoryHandle"/> to the backing memory.</summary> |
64 | 48 | /// <returns><see cref="MemoryHandle"/></returns> |
65 | 49 | MemoryHandle GetPinnedHandle(); |
66 | 50 | } |
67 | | - |
68 | | - /// <summary> |
69 | | - /// Represents a read-only tensor. |
70 | | - /// </summary> |
71 | | - /// <typeparam name="TSelf">The type that implements this interface.</typeparam> |
72 | | - /// <typeparam name="T">The element type.</typeparam> |
73 | | - [Experimental(Experimentals.TensorTDiagId, UrlFormat = Experimentals.SharedUrlFormat)] |
74 | | - public interface IReadOnlyTensor<TSelf, T> : IReadOnlyTensor, IEnumerable<T> |
75 | | - where TSelf : IReadOnlyTensor<TSelf, T> |
76 | | - { |
77 | | - /// <summary> |
78 | | - /// Gets an empty tensor. |
79 | | - /// </summary> |
80 | | - static abstract TSelf? Empty { get; } |
81 | | - |
82 | | - /// <summary> |
83 | | - /// Gets the value at the specified indexes. |
84 | | - /// </summary> |
85 | | - /// <param name="indexes">The indexes to be used.</param> |
86 | | - new T this[params scoped ReadOnlySpan<nint> indexes] { get; } |
87 | | - |
88 | | - /// <summary> |
89 | | - /// Gets the value at the specified indexes. |
90 | | - /// </summary> |
91 | | - /// <param name="indexes">The indexes to be used.</param> |
92 | | - new T this[params scoped ReadOnlySpan<NIndex> indexes] { get; } |
93 | | - |
94 | | - /// <summary> |
95 | | - /// Gets the values at the specified ranges. |
96 | | - /// </summary> |
97 | | - /// <param name="ranges">The ranges to be used.</param> |
98 | | - TSelf this[params scoped ReadOnlySpan<NRange> ranges] { get; } |
99 | | - |
100 | | - /// <summary> |
101 | | - /// Creates a read-only tensor span for the entire underlying buffer. |
102 | | - /// </summary> |
103 | | - /// <returns>The converted <see cref="ReadOnlyTensorSpan{T}"/>.</returns> |
104 | | - ReadOnlyTensorSpan<T> AsReadOnlyTensorSpan(); |
105 | | - |
106 | | - /// <summary> |
107 | | - /// Creates a read-only tensor span for the specified start indexes. |
108 | | - /// </summary> |
109 | | - /// <param name="start">The start locations to be used.</param> |
110 | | - /// <returns>The converted <see cref="ReadOnlyTensorSpan{T}"/>.</returns> |
111 | | - ReadOnlyTensorSpan<T> AsReadOnlyTensorSpan(params scoped ReadOnlySpan<nint> start); |
112 | | - |
113 | | - /// <summary> |
114 | | - /// Creates a read-only tensor span for the specified start indexes. |
115 | | - /// </summary> |
116 | | - /// <param name="startIndex">The started indexes to be used.</param> |
117 | | - /// <returns>The converted <see cref="ReadOnlyTensorSpan{T}"/>.</returns> |
118 | | - ReadOnlyTensorSpan<T> AsReadOnlyTensorSpan(params scoped ReadOnlySpan<NIndex> startIndex); |
119 | | - |
120 | | - /// <summary> |
121 | | - /// Creates a read-only tensor span for the specified ranges. |
122 | | - /// </summary> |
123 | | - /// <param name="range">The ranges to be used.</param> |
124 | | - /// <returns>The converted <see cref="ReadOnlyTensorSpan{T}"/>.</returns> |
125 | | - ReadOnlyTensorSpan<T> AsReadOnlyTensorSpan(params scoped ReadOnlySpan<NRange> range); |
126 | | - |
127 | | - /// <summary> |
128 | | - /// Copies the tensor to the specified destination. The destination tensor must be equal to or larger than the source tensor. |
129 | | - /// </summary> |
130 | | - /// <param name="destination">The destination span where the data should be copied to.</param> |
131 | | - void CopyTo(scoped TensorSpan<T> destination); |
132 | | - |
133 | | - /// <summary> |
134 | | - /// Flattens the tensor to the specified destination. The destination span must be equal to or larger than the number of elements in the source tensor. |
135 | | - /// </summary> |
136 | | - /// <param name="destination">The destination span where the data should be flattened to.</param> |
137 | | - void FlattenTo(scoped Span<T> destination); |
138 | | - |
139 | | - /// <summary> |
140 | | - /// Returns a reference to the 0th element of the tensor. If the tensor is empty, returns <see langword="null"/>. |
141 | | - /// </summary> |
142 | | - /// <remarks> |
143 | | - /// This method can be used for pinning and is required to support the use of the tensor within a fixed statement. |
144 | | - /// </remarks> |
145 | | - ref readonly T GetPinnableReference(); |
146 | | - |
147 | | - /// <summary> |
148 | | - /// Slices the tensor using the specified start indexes. |
149 | | - /// </summary> |
150 | | - /// <param name="start">The start locations to be used.</param> |
151 | | - /// <returns>The sliced tensor.</returns> |
152 | | - TSelf Slice(params scoped ReadOnlySpan<nint> start); |
153 | | - |
154 | | - /// <summary> |
155 | | - /// Slices the tensor using the specified start indexes. |
156 | | - /// </summary> |
157 | | - /// <param name="startIndex">The start indexes to be used.</param> |
158 | | - /// <returns>The sliced tensor.</returns> |
159 | | - TSelf Slice(params scoped ReadOnlySpan<NIndex> startIndex); |
160 | | - |
161 | | - /// <summary> |
162 | | - /// Slices the tensor using the specified ranges. |
163 | | - /// </summary> |
164 | | - /// <param name="range">The ranges to be used.</param> |
165 | | - /// <returns>The sliced tensor.</returns> |
166 | | - TSelf Slice(params scoped ReadOnlySpan<NRange> range); |
167 | | - |
168 | | - /// <summary> |
169 | | - /// Tries to copy the tensor to the specified destination. The destination tensor must be equal to or larger than the source tensor. |
170 | | - /// </summary> |
171 | | - /// <param name="destination">The destination span where the data should be copied to.</param> |
172 | | - /// <returns><see langword="true" /> if the copy succeeded, <see langword="false" /> otherwise.</returns> |
173 | | - bool TryCopyTo(scoped TensorSpan<T> destination); |
174 | | - |
175 | | - /// <summary> |
176 | | - /// Tries to flatten the tensor to the specified destination. The destination span must be equal to or larger than the number of elements in the source tensor. |
177 | | - /// </summary> |
178 | | - /// <param name="destination">The destination span where the data should be flattened to.</param> |
179 | | - /// <returns><see langword="true" /> if the flatten succeeded, <see langword="false" /> otherwise.</returns> |
180 | | - bool TryFlattenTo(scoped Span<T> destination); |
181 | | - } |
182 | 51 | } |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments