dotnet / dotnet/dotnet-api-docs

Topic contains almost no info on how to use the method

Open
#11,343 1 comment 0 reactions 0 assignees View on GitHub
area-System.Runtime.Intrinsics untriaged
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.