Skip to content

Commit a70cfa0

Browse files
committed
lib.data: fix incorrect and very misleading example in documentation.
Found while working on amaranth/rfcs#15. The new code is also robust in the face of RFC 15 itself (the value returned by Signal will change but that will save work for the programmer).
1 parent 54d5c4c commit a70cfa0

File tree

1 file changed

+17
-5
lines changed

1 file changed

+17
-5
lines changed

docs/stdlib/data.rst

+17-5
Original file line numberDiff line numberDiff line change
@@ -120,18 +120,30 @@ In case the data has related operations or transformations, :class:`View` can be
120120

121121
.. testcode::
122122

123-
class RGBLayout(data.View):
124-
def __init__(self, target=None, *, r_bits, g_bits, b_bits, **kwargs):
125-
super().__init__(layout=data.StructLayout({
123+
class RGBPixelLayout(data.StructLayout):
124+
def __init__(self, r_bits, g_bits, b_bits):
125+
super().__init__({
126126
"red": unsigned(r_bits),
127127
"green": unsigned(g_bits),
128128
"blue": unsigned(b_bits)
129-
}, target=target, **kwargs))
129+
})
130+
131+
def __call__(self, value):
132+
return RGBPixelView(self, value)
130133

134+
class RGBPixelView(data.View):
131135
def brightness(self):
132136
return (self.red + self.green + self.blue)[-8:]
133137

134-
Here, the ``RGBLayout`` class itself is :ref:`shape-castable <lang-shapecasting>` and can be used anywhere a shape is accepted.
138+
Here, the ``RGBLayout`` class itself is :ref:`shape-castable <lang-shapecasting>` and can be used anywhere a shape is accepted:
139+
140+
.. doctest::
141+
142+
>>> pixel = Signal(RGBPixelLayout(5, 6, 5))
143+
>>> len(pixel)
144+
16
145+
>>> RGBPixelView(RGBPixelLayout(5, 6, 5), pixel).red
146+
(slice (sig pixel) 0:5)
135147

136148
In case the data format is static, :class:`Struct` (or :class:`Union`) can be subclassed instead of :class:`View`, to reduce the amount of boilerplate needed:
137149

0 commit comments

Comments
 (0)