amaranth icon indicating copy to clipboard operation
amaranth copied to clipboard

Order of bits within pattern syntax should be documented

Open Ravenslofty opened this issue 3 years ago • 2 comments

For "pattern syntax" in Case and Value.matches it's not obvious where the least significant bit is in the pattern (first or last character in the string).

It would be nice if the documentation for these functions mentioned the ordering for this.

It might be a silly idea, but I think the order would be more obvious if the string format had an 0b prefix, showing most significant bit first like a Python integer; I don't know how to demonstrate little-bit-endian first like that however.

Ravenslofty avatar Dec 13 '21 21:12 Ravenslofty

I think this is a relatively straightforward documentation improvement? Just to confirm the desire is that the bit on the left of the pattern is MSB and the right is LSB of the value? I believe this matches the way it's implemented.

Lunaphied avatar Dec 14 '21 14:12 Lunaphied

When matching against a Python integer, one would use something like m.Case(0bxy), where x is most significant first, so it seems most natural to me to have the leftmost bit be most significant in the pattern syntax too.

Ravenslofty avatar Dec 14 '21 14:12 Ravenslofty