diff --git a/spec/API_specification/broadcasting.rst b/spec/API_specification/broadcasting.rst index ec72fb089..abb3ed222 100644 --- a/spec/API_specification/broadcasting.rst +++ b/spec/API_specification/broadcasting.rst @@ -112,4 +112,17 @@ The following examples demonstrate array shapes which do **not** broadcast. In-place Semantics ------------------ -As implied by the broadcasting algorithm, in-place element-wise operations must not change the shape of the in-place array as a result of broadcasting. +As implied by the broadcasting algorithm, in-place element-wise operations (including ``__setitem__``) must not change the shape of the in-place array as a result of broadcasting. Such operations should only be supported in the case where the right-hand operand can broadcast to the shape of the left-hand operand, after any indexing operations are performed. + +For example: + +:: + + x = empty((2, 3, 4)) + a = empty((1, 3, 4)) + + # This is OK. The shape of a, (1, 3, 4), can broadcast to the shape of x[...], (2, 3, 4) + x[...] = a + + # This is not allowed. The shape of a, (1, 3, 4), can NOT broadcast to the shape of x[1, ...], (3, 4) + x[1, ...] = a