dotnet / dotnet/dotnet-api-docs
Topic contains almost no info on how to use the method
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
### Type of issue
Missing information
### Description
I realize this is still pre-release material, but I want to make sure it's still on someone's todo list. The docs for 'Shuffle' aren't much better. Mostly I was looking, for some indication of how ShuffleNative is any different from just Shuffle? Looking in Vector64.cs, ShuffleNative just seems to call Shuffle, but perhaps something interesting happens in the intrinsic substitution.
When these docs do get written, I'm hoping for one specific item here. And if it's ever going to get added, it needs to happen _before_ the code is released, otherwise there are backward compatibility issues.
Looking at the current code, if your `indices` vector contains `0x0001020304050607` it reverses the vector (as expected). And if it contains `0x0x8080808004050607`, then the 4 most significant bytes gets zeroed instead of reversed (also as expected). Strictly speaking, any value greater than the number of elements in the vector would zero the corresponding output element (based on the current code). But by explicitly documenting that setting the most significant bit of the index results in zeros, it would be consistent with the [SSE shuffle](https://www.felixcloutier.com/x86/pshufb) instructions.
If there's no reason not to, being compatible with SSE seems like a good thing. Especially since no code change would be required, just a line in the (as yet unwritten) docs.
### Page URL
https://learn.microsoft.com/en-us/dotnet/api/system.runtime.intrinsics.vector64.shufflenative?view=net-10.0
### Content source URL
https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Runtime.Intrinsics/Vector64.xml
### Document Version Independent Id
b9ba8c77-1dfc-8407-41d1-7611246b02c7
### Platform Id
3bf12d49-ac45-3318-da2a-a33a38462460
### Article author
@dotnet-bot
Contributor guide
Assessment
This issue has not been assessed yet.