Topic contains almost no info on how to use the method

[rindlespot]

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 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

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime-intrinsics