-
Notifications
You must be signed in to change notification settings - Fork 4.5k
/
ReadOnlyTensorSpan.cs
769 lines (683 loc) · 36.6 KB
/
ReadOnlyTensorSpan.cs
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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System.Buffers;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Linq;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.Runtime.InteropServices.Marshalling;
using System.Runtime.Versioning;
using System.Text;
using EditorBrowsableAttribute = System.ComponentModel.EditorBrowsableAttribute;
using EditorBrowsableState = System.ComponentModel.EditorBrowsableState;
#pragma warning disable 0809 //warning CS0809: Obsolete member 'ReadOnlyTensorSpan<T>.Equals(object)' overrides non-obsolete member 'object.Equals(object)'
#pragma warning disable 8500 // address / sizeof of managed types
namespace System.Numerics.Tensors
{
/// <summary>
/// ReadOnlyTensorSpan represents a contiguous region of arbitrary memory. Unlike arrays, it can point to either managed
/// or native memory, or to memory allocated on the stack. It is type-safe and memory-safe.
/// </summary>
[DebuggerTypeProxy(typeof(TensorSpanDebugView<>))]
[DebuggerDisplay("{ToString(),raw}")]
public readonly ref struct ReadOnlyTensorSpan<T>
{
/// <summary>A byref or a native ptr.</summary>
internal readonly ref T _reference;
/// <summary>The number of elements this ReadOnlyTensorSpan contains.</summary>
internal readonly nint _flattenedLength;
/// <summary>The length of the underlying memory. Can be different than the number of elements in the span.</summary>
internal readonly nint _memoryLength;
/// <summary>The lengths of each dimension.</summary>
internal readonly ReadOnlySpan<nint> _lengths;
/// <summary>The strides representing the memory offsets for each dimension.</summary>
private readonly ReadOnlySpan<nint> _strides;
/// <summary>
/// Creates a new span over the entirety of the target array.
/// </summary>
/// <param name="array">The target array.</param>
/// <remarks>Returns default when <paramref name="array"/> is null.</remarks>
/// <exception cref="ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception>
public ReadOnlyTensorSpan(T[]? array) : this(array, 0, [], [])
{
}
/// <summary>
/// Creates a new span over the portion of the target array beginning
/// at 'start' index and ending at 'end' index (exclusive).
/// </summary>
/// <param name="array">The target array.</param>
/// <param name="startIndex">The index at which to begin the span.</param>
/// <param name="lengths">The lengths of the dimensions. If default is provided its assumed to have 1 dimension with a length equal to the length of the data.</param>
/// <param name="strides">The strides of each dimension. If default or span of length 0 is provided then strides will be automatically calculated.</param>
/// <remarks>Returns default when <paramref name="array"/> is null.</remarks>
/// <exception cref="ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the specified <paramref name="startIndex"/> or end index is not in the range (<0 or >FlattenedLength).
/// </exception>
public ReadOnlyTensorSpan(T[]? array, Index startIndex, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
: this(array, startIndex.GetOffset(array?.Length ?? 0), lengths, strides)
{
}
/// <summary>
/// Creates a new span over the portion of the target array beginning
/// at 'start' index and ending at 'end' index (exclusive).
/// </summary>
/// <param name="array">The target array.</param>
/// <param name="start">The index at which to begin the span.</param>
/// <param name="lengths">The lengths of the dimensions. If default is provided its assumed to have 1 dimension with a length equal to the length of the data.</param>
/// <param name="strides">The strides of each dimension. If default or span of length 0 is provided then strides will be automatically calculated.</param>
/// <remarks>Returns default when <paramref name="array"/> is null.</remarks>
/// <exception cref="ArrayTypeMismatchException">Thrown when <paramref name="array"/> is covariant and array's type is not exactly T[].</exception>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the specified <paramref name="start"/> or end index is not in the range (<0 or >FlattenedLength).
/// </exception>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public ReadOnlyTensorSpan(T[]? array, int start, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
if (array == null)
{
if (start != 0 || linearLength != 0)
ThrowHelper.ThrowArgumentOutOfRangeException();
this = default;
return; // returns default
}
if (!typeof(T).IsValueType && array.GetType() != typeof(T[]))
ThrowHelper.ThrowArrayTypeMismatchException();
strides = strides.IsEmpty ? (ReadOnlySpan<nint>)TensorSpanHelpers.CalculateStrides(lengths) : strides;
nint maxElements = TensorSpanHelpers.ComputeMaxElementCount(strides, lengths);
if (Environment.Is64BitProcess)
{
// See comment in Span<T>.Slice for how this works.
if ((ulong)(uint)start + (ulong)(uint)maxElements > (ulong)(uint)array.Length)
ThrowHelper.ThrowArgumentOutOfRangeException();
}
else
{
if ((uint)start > (uint)array.Length || (uint)maxElements > (uint)(array.Length - start))
ThrowHelper.ThrowArgumentOutOfRangeException();
}
_flattenedLength = linearLength;
_memoryLength = array.Length;
_reference = ref Unsafe.Add(ref MemoryMarshal.GetArrayDataReference(array), (nint)(uint)start /* force zero-extension */);
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
/// <summary>
/// Creates a new <see cref="ReadOnlyTensorSpan{T}"/> over the provided <see cref="Span{T}"/>. The new <see cref="ReadOnlyTensorSpan{T}"/> will
/// have a rank of 1 and a length equal to the length of the provided <see cref="Span{T}"/>.
/// </summary>
/// <param name="span">The target span.</param>
public ReadOnlyTensorSpan(ReadOnlySpan<T> span) : this(span, [span.Length], []) { }
/// <summary>
/// Creates a new <see cref="ReadOnlyTensorSpan{T}"/> over the provided <see cref="Span{T}"/> using the specified lengths and strides.
/// If the strides are not provided, they will be automatically calculated.
/// </summary>
/// <param name="span">The target span.</param>
/// <param name="lengths">The lengths of each dimension.</param>
/// <param name="strides">The strides for each dimension. Will be automatically calculated if not provided.</param>
public ReadOnlyTensorSpan(ReadOnlySpan<T> span, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
if (span.IsEmpty)
{
if (linearLength != 0)
ThrowHelper.ThrowArgumentOutOfRangeException();
this = default;
return; // returns default
}
strides = strides.IsEmpty ? (ReadOnlySpan<nint>)TensorSpanHelpers.CalculateStrides(lengths) : strides;
nint maxElements = TensorSpanHelpers.ComputeMaxElementCount(strides, lengths);
if (maxElements >= span.Length)
ThrowHelper.ThrowArgument_InvalidStridesAndLengths();
_flattenedLength = linearLength;
_memoryLength = span.Length;
_reference = ref MemoryMarshal.GetReference(span);
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
/// <summary>
/// Creates a new <see cref="ReadOnlyTensorSpan{T}"/> over the provided <see cref="Array"/>. The new <see cref="ReadOnlyTensorSpan{T}"/> will
/// have a rank of 1 and a length equal to the length of the provided <see cref="Array"/>.
/// </summary>
/// <param name="array">The target array.</param>
public ReadOnlyTensorSpan(Array? array) : this(array, ReadOnlySpan<int>.Empty, [], []) { }
/// <summary>
/// Creates a new <see cref="ReadOnlyTensorSpan{T}"/> over the provided <see cref="Array"/> using the specified start offsets, lengths, and strides.
/// If the strides are not provided, they will be automatically calculated.
/// </summary>
/// <param name="array">The target array.</param>
/// <param name="start">The starting offset for each dimension.</param>
/// <param name="lengths">The lengths of each dimension.</param>
/// <param name="strides">The strides for each dimension. Will be automatically calculated if not provided.</param>
public ReadOnlyTensorSpan(Array? array, scoped ReadOnlySpan<int> start, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
strides = strides.IsEmpty ? (ReadOnlySpan<nint>)TensorSpanHelpers.CalculateStrides(lengths) : strides;
nint startOffset = TensorSpanHelpers.ComputeLinearIndex(start, strides, lengths);
if (array == null)
{
if (!start.IsEmpty || linearLength != 0)
ThrowHelper.ThrowArgumentOutOfRangeException();
this = default;
return; // returns default
}
if (!typeof(T).IsValueType && array.GetType() != typeof(T[]))
ThrowHelper.ThrowArrayTypeMismatchException();
nint maxElements = TensorSpanHelpers.ComputeMaxElementCount(strides, lengths);
if (Environment.Is64BitProcess)
{
// See comment in Span<T>.Slice for how this works.
if ((ulong)(uint)startOffset + (ulong)(uint)maxElements > (ulong)(uint)array.Length)
ThrowHelper.ThrowArgumentOutOfRangeException();
}
else
{
if ((uint)startOffset > (uint)array.Length || (uint)maxElements > (uint)(array.Length - startOffset))
ThrowHelper.ThrowArgumentOutOfRangeException();
}
_flattenedLength = linearLength;
_memoryLength = array.Length;
_reference = ref Unsafe.Add(ref Unsafe.As<byte, T>(ref MemoryMarshal.GetArrayDataReference(array)), (nint)(uint)startOffset /* force zero-extension */);
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
/// <summary>
/// Creates a new <see cref="ReadOnlyTensorSpan{T}"/> over the provided <see cref="Array"/> using the specified start offsets, lengths, and strides.
/// If the strides are not provided, they will be automatically calculated.
/// </summary>
/// <param name="array">The target array.</param>
/// <param name="startIndex">The starting offset for each dimension.</param>
/// <param name="lengths">The lengths of each dimension.</param>
/// <param name="strides">The strides for each dimension. Will be automatically calculated if not provided.</param>
public ReadOnlyTensorSpan(Array? array, scoped ReadOnlySpan<NIndex> startIndex, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
strides = strides.IsEmpty ? (ReadOnlySpan<nint>)TensorSpanHelpers.CalculateStrides(lengths) : strides;
nint start = TensorSpanHelpers.ComputeLinearIndex(startIndex, strides, lengths);
if (array == null)
{
if (!startIndex.IsEmpty || linearLength != 0)
ThrowHelper.ThrowArgumentOutOfRangeException();
this = default;
return; // returns default
}
if (!typeof(T).IsValueType && array.GetType() != typeof(T[]))
ThrowHelper.ThrowArrayTypeMismatchException();
nint maxElements = TensorSpanHelpers.ComputeMaxElementCount(strides, lengths);
if (Environment.Is64BitProcess)
{
// See comment in Span<T>.Slice for how this works.
if ((ulong)(uint)start + (ulong)(uint)maxElements > (ulong)(uint)array.Length)
ThrowHelper.ThrowArgumentOutOfRangeException();
}
else
{
if ((uint)start > (uint)array.Length || (uint)maxElements > (uint)(array.Length - start))
ThrowHelper.ThrowArgumentOutOfRangeException();
}
_flattenedLength = linearLength;
_memoryLength = array.Length;
_reference = ref Unsafe.Add(ref Unsafe.As<byte, T>(ref MemoryMarshal.GetArrayDataReference(array)), (nint)(uint)start /* force zero-extension */);
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
/// <summary>
/// Creates a new span over the target unmanaged buffer. Clearly this
/// is quite dangerous the length is not checked.
/// But if this creation is correct, then all subsequent uses are correct.
/// </summary>
/// <param name="data">An unmanaged data to memory.</param>
/// <param name="dataLength">The number of elements the unmanaged memory can hold.</param>
[CLSCompliant(false)]
public unsafe ReadOnlyTensorSpan(T* data, nint dataLength) : this(data, dataLength, [dataLength], []) { }
/// <summary>
/// Creates a new span over the target unmanaged buffer. Clearly this
/// is quite dangerous, because the length is not checked.
/// But if this creation is correct, then all subsequent uses are correct.
/// </summary>
/// <param name="data">An unmanaged data to memory.</param>
/// <param name="dataLength">The number of elements the unmanaged memory can hold.</param>
/// <param name="lengths">The lengths of the dimensions. If default is provided its assumed to have 1 dimension with a length equal to the length of the data.</param>
/// <param name="strides">The lengths of the strides. If nothing is provided it figures out the default stride configuration.</param>
/// <exception cref="ArgumentException">
/// Thrown when <typeparamref name="T"/> is reference type or contains pointers and hence cannot be stored in unmanaged memory.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the specified length is negative.
/// </exception>
[CLSCompliant(false)]
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public unsafe ReadOnlyTensorSpan(T* data, nint dataLength, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
if (RuntimeHelpers.IsReferenceOrContainsReferences<T>())
ThrowHelper.ThrowInvalidTypeWithPointersNotSupported(typeof(T));
strides = strides.IsEmpty ? (ReadOnlySpan<nint>)TensorSpanHelpers.CalculateStrides(lengths) : strides;
nint maxElements = TensorSpanHelpers.ComputeMaxElementCount(strides, lengths);
if (maxElements >= dataLength)
ThrowHelper.ThrowArgument_InvalidStridesAndLengths();
_flattenedLength = linearLength;
_memoryLength = dataLength;
_reference = ref *data;
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
// Constructor for internal use only. It is not safe to expose publicly.
[MethodImpl(MethodImplOptions.AggressiveInlining)]
internal ReadOnlyTensorSpan(ref T reference, scoped ReadOnlySpan<nint> lengths, scoped ReadOnlySpan<nint> strides, nint memoryLength)
{
nint linearLength = TensorSpanHelpers.CalculateTotalLength(lengths);
_flattenedLength = linearLength;
_memoryLength = memoryLength;
_reference = ref reference;
_lengths = lengths.ToArray();
_strides = strides.ToArray();
}
/// <summary>
/// Returns a reference to specified element of the ReadOnlyTensorSpan.
/// </summary>
/// <param name="indexes"></param>
/// <returns></returns>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when any index is less than 0 or any index is greater than or equal to FlattenedLength
/// </exception>
public ref readonly T this[params scoped ReadOnlySpan<nint> indexes]
{
[MethodImpl(MethodImplOptions.AggressiveInlining)]
get
{
if (indexes.Length != Rank)
ThrowHelper.ThrowIndexOutOfRangeException();
nint index = TensorSpanHelpers.ComputeLinearIndex(indexes, Strides, Lengths);
if (index >= _memoryLength || index < 0)
ThrowHelper.ThrowIndexOutOfRangeException();
return ref Unsafe.Add(ref _reference, index /* force zero-extension */);
}
}
/// <summary>
/// Returns a reference to specified element of the ReadOnlyTensorSpan.
/// </summary>
/// <param name="indexes"></param>
/// <returns></returns>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when any index is less than 0 or any index is greater than or equal to FlattenedLength
/// </exception>
public ref readonly T this[params scoped ReadOnlySpan<NIndex> indexes]
{
get
{
if (indexes.Length != Rank)
ThrowHelper.ThrowIndexOutOfRangeException();
nint index = TensorSpanHelpers.ComputeLinearIndex(indexes, Strides, Lengths);
if (index >= _memoryLength || index < 0)
ThrowHelper.ThrowIndexOutOfRangeException();
return ref Unsafe.Add(ref _reference, index /* force zero-extension */);
}
}
/// <summary>
/// Returns a slice of the ReadOnlyTensorSpan.
/// </summary>
/// <param name="ranges"></param>
/// <returns></returns>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when any index is less than 0 or any index is greater than or equal to FlattenedLength
/// </exception>
public ReadOnlyTensorSpan<T> this[params scoped ReadOnlySpan<NRange> ranges]
{
get
{
if (ranges.Length != Rank)
ThrowHelper.ThrowIndexOutOfRangeException();
return Slice(ranges);
}
}
/// <summary>
/// The number of items in the span.
/// </summary>
public nint FlattenedLength => _flattenedLength;
/// <summary>
/// Gets a value indicating whether this <see cref="TensorSpan{T}"/> is empty.
/// </summary>
/// <value><see langword="true"/> if this span is empty; otherwise, <see langword="false"/>.</value>
public bool IsEmpty => _flattenedLength == 0;
/// <summary>
/// Gets the length of each dimension in this <see cref="TensorSpan{T}"/>.
/// </summary>
[UnscopedRef]
public ReadOnlySpan<nint> Lengths => _lengths;
/// <summary>
/// Gets the rank, aka the number of dimensions, of this <see cref="TensorSpan{T}"/>.
/// </summary>
public int Rank => Lengths.Length;
/// <summary>
/// Gets the strides of this <see cref="TensorSpan{T}"/>
/// </summary>
[UnscopedRef]
public ReadOnlySpan<nint> Strides => _strides;
/// <summary>
/// Returns false if left and right point at the same memory and have the same length. Note that
/// this does *not* check to see if the *contents* are equal.
/// </summary>
public static bool operator !=(ReadOnlyTensorSpan<T> left, ReadOnlyTensorSpan<T> right) => !(left == right);
/// <summary>
/// Returns true if left and right point at the same memory and have the same length. Note that
/// this does *not* check to see if the *contents* are equal.
/// </summary>
public static bool operator ==(ReadOnlyTensorSpan<T> left, ReadOnlyTensorSpan<T> right) =>
left._flattenedLength == right._flattenedLength &&
left.Rank == right.Rank &&
left._lengths.SequenceEqual(right._lengths )&&
Unsafe.AreSame(ref left._reference, ref right._reference);
/// <summary>
/// This method is not supported as spans cannot be boxed. To compare two spans, use operator==.
/// </summary>
/// <exception cref="NotSupportedException">
/// Always thrown by this method.
/// </exception>
#pragma warning disable CS0809 // Obsolete member overrides non-obsolete member
[Obsolete("Equals() on ReadOnlyTensorSpan will always throw an exception. Use the equality operator instead.")]
[EditorBrowsable(EditorBrowsableState.Never)]
public override bool Equals(object? obj) =>
throw new NotSupportedException(SR.NotSupported_CannotCallEqualsOnSpan);
/// <summary>
/// This method is not supported as spans cannot be boxed.
/// </summary>
/// <exception cref="NotSupportedException">
/// Always thrown by this method.
/// </exception>
[Obsolete("GetHashCode() on ReadOnlyTensorSpan will always throw an exception.")]
[EditorBrowsable(EditorBrowsableState.Never)]
public override int GetHashCode() =>
throw new NotSupportedException(SR.NotSupported_CannotCallGetHashCodeOnSpan);
#pragma warning restore CS0809
/// <summary>
/// Returns a 0-length read-only span whose base is the null pointer.
/// </summary>
public static ReadOnlyTensorSpan<T> Empty => default;
/// <summary>
/// Casts a read-only span of <typeparamref name="TDerived"/> to a read-only span of <typeparamref name="T"/>.
/// </summary>
/// <typeparam name="TDerived">The element type of the source read-only span, which must be derived from <typeparamref name="T"/>.</typeparam>
/// <param name="items">The source read-only span. No copy is made.</param>
/// <returns>A read-only span with elements cast to the new type.</returns>
/// <remarks>This method uses a covariant cast, producing a read-only span that shares the same memory as the source. The relationships expressed in the type constraints ensure that the cast is a safe operation.</remarks>
public static ReadOnlyTensorSpan<T> CastUp<TDerived>(ReadOnlyTensorSpan<TDerived> items) where TDerived : class?, T
{
return new ReadOnlyTensorSpan<T>(ref Unsafe.As<TDerived, T>(ref items._reference), items._lengths, items._strides, items._memoryLength);
}
/// <summary>Gets an enumerator for this span.</summary>
public Enumerator GetEnumerator() => new Enumerator(this);
/// <summary>Enumerates the elements of a <see cref="ReadOnlyTensorSpan{T}"/>.</summary>
public ref struct Enumerator
{
/// <summary>The span being enumerated.</summary>
private readonly ReadOnlyTensorSpan<T> _span;
/// <summary>The current index that the enumerator is on.</summary>
private Span<nint> _curIndexes;
/// <summary>The total item count.</summary>
private nint _items;
/// <summary>Initialize the enumerator.</summary>
/// <param name="span">The span to enumerate.</param>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
internal Enumerator(ReadOnlyTensorSpan<T> span)
{
_span = span;
_items = -1;
_curIndexes = new nint[_span.Rank];
_curIndexes[_span.Rank - 1] = -1;
}
/// <summary>Advances the enumerator to the next element of the span.</summary>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public bool MoveNext()
{
TensorSpanHelpers.AdjustIndexes(_span.Rank - 1, 1, _curIndexes, _span.Lengths);
if (_items < _span.FlattenedLength)
_items++;
return _items < _span.FlattenedLength;
}
/// <summary>Gets the element at the current position of the enumerator.</summary>
public ref readonly T Current
{
[MethodImpl(MethodImplOptions.AggressiveInlining)]
get => ref _span[_curIndexes];
}
}
/// <summary>
/// Returns a reference to the 0th element of the ReadOnlyTensorSpan. If the ReadOnlyTensorSpan is empty, returns null reference.
/// It can be used for pinning and is required to support the use of span within a fixed statement.
/// </summary>
[EditorBrowsable(EditorBrowsableState.Never)]
public ref readonly T GetPinnableReference()
{
// Ensure that the native code has just one forward branch that is predicted-not-taken.
ref T ret = ref Unsafe.NullRef<T>();
if (_flattenedLength != 0) ret = ref _reference;
return ref ret;
}
/// <summary>
/// Copies the contents of this read-only span into destination span. If the source
/// and destinations overlap, this method behaves as if the original values in
/// a temporary location before the destination is overwritten.
/// </summary>
/// <param name="destination">The span to copy items into.</param>
/// <exception cref="ArgumentException">
/// Thrown when the destination ReadOnlyTensorSpan is shorter than the source ReadOnlyTensorSpan.
/// </exception>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public void CopyTo(scoped TensorSpan<T> destination)
{
// Using "if (!TryCopyTo(...))" results in two branches: one for the length
// check, and one for the result of TryCopyTo. Since these checks are equivalent,
// we can optimize by performing the check once ourselves then calling Memmove directly.
if (_flattenedLength <= destination.FlattenedLength)
{
scoped Span<nint> curIndexes;
nint[]? curIndexesArray;
if (Rank > 6)
{
curIndexesArray = ArrayPool<nint>.Shared.Rent(Rank);
curIndexes = curIndexesArray;
}
else
{
curIndexesArray = null;
curIndexes = stackalloc nint[Rank];
}
nint copiedValues = 0;
TensorSpan<T> slice = destination.Slice(_lengths);
while (copiedValues < _flattenedLength)
{
TensorSpanHelpers.Memmove(ref Unsafe.Add(ref slice._reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), ref Unsafe.Add(ref _reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), Lengths[Rank - 1]);
TensorSpanHelpers.AdjustIndexes(Rank - 2, 1, curIndexes, _lengths);
copiedValues += Lengths[Rank - 1];
}
Debug.Assert(copiedValues == _flattenedLength, "Didn't copy the right amount to the array.");
if (curIndexesArray != null)
ArrayPool<nint>.Shared.Return(curIndexesArray);
}
else
{
ThrowHelper.ThrowArgumentException_DestinationTooShort();
}
}
/// <summary>
/// Copies the contents of this read-only span into destination span. If the source
/// and destinations overlap, this method behaves as if the original values in
/// a temporary location before the destination is overwritten.
/// </summary>
/// <returns>If the destination span is shorter than the source span, this method
/// return false and no data is written to the destination.</returns>
/// <param name="destination">The span to copy items into.</param>
public bool TryCopyTo(scoped TensorSpan<T> destination)
{
bool retVal = false;
if (_flattenedLength <= destination.FlattenedLength)
{
scoped Span<nint> curIndexes;
nint[]? curIndexesArray;
if (Rank > 6)
{
curIndexesArray = ArrayPool<nint>.Shared.Rent(Rank);
curIndexes = curIndexesArray;
}
else
{
curIndexesArray = null;
curIndexes = stackalloc nint[Rank];
}
nint copiedValues = 0;
TensorSpan<T> slice = destination.Slice(_lengths);
while (copiedValues < _flattenedLength)
{
TensorSpanHelpers.Memmove(ref Unsafe.Add(ref slice._reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), ref Unsafe.Add(ref _reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), Lengths[Rank - 1]);
TensorSpanHelpers.AdjustIndexes(Rank - 2, 1, curIndexes, _lengths);
copiedValues += Lengths[Rank - 1];
}
retVal = true;
Debug.Assert(copiedValues == _flattenedLength, "Didn't copy the right amount to the array.");
if (curIndexesArray != null)
ArrayPool<nint>.Shared.Return(curIndexesArray);
}
return retVal;
}
//public static explicit operator TensorSpan<T>(Array? array);
public static implicit operator ReadOnlyTensorSpan<T>(T[]? array) => new ReadOnlyTensorSpan<T>(array);
/// <summary>
/// Returns a <see cref="string"/> with the name of the type and the number of elements.
/// </summary>
public override string ToString() => $"System.Numerics.Tensors.ReadOnlyTensorSpan<{typeof(T).Name}>[{_flattenedLength}]";
/// <summary>
/// Returns a reference to specified element of the TensorSpan.
/// </summary>
/// <param name="indexes">The indexes for the slice.</param>
/// <returns></returns>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when any index is less than 0 or any index is greater than or equal to FlattenedLength
/// </exception>
public ReadOnlyTensorSpan<T> Slice(params scoped ReadOnlySpan<NIndex> indexes)
{
NRange[] ranges = new NRange[indexes.Length];
for (int i = 0; i < indexes.Length; i++)
{
ranges[i] = new NRange(checked((int)indexes[i].GetOffset(Lengths[i])), Lengths[i]);
}
return Slice(ranges);
}
/// <summary>
/// Takes in the lengths of the dimensions and slices according to them.
/// </summary>
/// <param name="lengths">The dimension lengths</param>
/// <returns>A <see cref="ReadOnlyTensorSpan{T}"/> based on the provided <paramref name="lengths"/></returns>
internal ReadOnlyTensorSpan<T> Slice(scoped ReadOnlySpan<nint> lengths)
{
NRange[] ranges = new NRange[lengths.Length];
for (int i = 0; i < lengths.Length; i++)
{
ranges[i] = new NRange(0, lengths[i]);
}
return Slice(ranges);
}
/// <summary>
/// Forms a slice out of the given span
/// </summary>
/// <param name="ranges">The ranges for the slice</param>
/// <returns>A <see cref="ReadOnlyTensorSpan{T}"/> based on the provided <paramref name="ranges"/></returns>
public ReadOnlyTensorSpan<T> Slice(params scoped ReadOnlySpan<NRange> ranges)
{
if (ranges.Length != Lengths.Length)
throw new ArgumentOutOfRangeException(nameof(ranges), "Number of dimensions to slice does not equal the number of dimensions in the span");
scoped Span<nint> shape;
scoped Span<nint> offsets;
if (Rank > 6)
{
shape = stackalloc nint[Rank];
offsets = stackalloc nint[Rank];
}
else
{
shape = new nint[Rank];
offsets = new nint[Rank];
}
for (int i = 0; i < ranges.Length; i++)
{
(offsets[i], shape[i]) = ranges[i].GetOffsetAndLength(Lengths[i]);
}
nint index = 0;
for (int i = 0; i < offsets.Length; i++)
{
index += Strides[i] * (offsets[i]);
}
if (index >= _memoryLength || index < 0)
ThrowHelper.ThrowIndexOutOfRangeException();
return new ReadOnlyTensorSpan<T>(ref Unsafe.Add(ref _reference, index), shape, _strides, _memoryLength - index);
}
/// <summary>
/// Flattens the contents of this span into the provided <see cref="Span{T}"/>.
/// </summary>
/// <param name="destination">The span to copy items into.</param>
public bool TryFlattenTo(scoped Span<T> destination)
{
bool retVal = false;
if (destination.Length < _flattenedLength)
{
scoped Span<nint> curIndexes;
nint[]? curIndexesArray;
if (Rank > 6)
{
curIndexesArray = ArrayPool<nint>.Shared.Rent(Rank);
curIndexes = curIndexesArray;
}
else
{
curIndexesArray = null;
curIndexes = stackalloc nint[Rank];
}
nint copiedValues = 0;
while (copiedValues < _flattenedLength)
{
TensorSpanHelpers.Memmove(destination.Slice(checked((int)copiedValues)), ref Unsafe.Add(ref _reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), Lengths[Rank - 1]);
TensorSpanHelpers.AdjustIndexes(Rank - 2, 1, curIndexes, _lengths);
copiedValues += Lengths[Rank - 1];
}
if (curIndexesArray != null)
ArrayPool<nint>.Shared.Return(curIndexesArray);
retVal = true;
}
return retVal;
}
/// <summary>
/// Flattens the contents of this span into the provided <see cref="Span{T}"/>.
/// </summary>
/// <param name="destination">The span to copy items into.</param>
public void FlattenTo(scoped Span<T> destination)
{
if (destination.Length < _flattenedLength)
ThrowHelper.ThrowArgumentException_DestinationTooShort();
if (_flattenedLength == 0)
return;
scoped Span<nint> curIndexes;
nint[]? curIndexesArray;
if (Rank > 6)
{
curIndexesArray = ArrayPool<nint>.Shared.Rent(Rank);
curIndexes = curIndexesArray;
}
else
{
curIndexesArray = null;
curIndexes = stackalloc nint[Rank];
}
nint copiedValues = 0;
while (copiedValues < _flattenedLength)
{
TensorSpanHelpers.Memmove(destination.Slice(checked((int)copiedValues)), ref Unsafe.Add(ref _reference, TensorSpanHelpers.ComputeLinearIndex(curIndexes, Strides, Lengths)), Lengths[Rank - 1]);
TensorSpanHelpers.AdjustIndexes(Rank - 2, 1, curIndexes, _lengths);
copiedValues += Lengths[Rank - 1];
}
if (curIndexesArray != null)
ArrayPool<nint>.Shared.Return(curIndexesArray);
}
}
}