Merge pull request #3 from CliMA/ck/readme

Update docs + fixes

README.md

@@ -1,3 +1,45 @@
 # NullBroadcasts.jl
 
-A small package for defining null broadcasted types and behaviors
+|||
+|---------------------:|:----------------------------------------------|
+| **Docs Build**       | [![docs build][docs-bld-img]][docs-bld-url]   |
+| **Documentation**    | [![dev][docs-dev-img]][docs-dev-url]          |
+| **GHA CI**           | [![gha ci][gha-ci-img]][gha-ci-url]           |
+| **Code Coverage**    | [![codecov][codecov-img]][codecov-url]        |
+
+[docs-bld-img]: https://github.com/CliMA/NullBroadcasts.jl/actions/workflows/docs.yml/badge.svg
+[docs-bld-url]: https://github.com/CliMA/NullBroadcasts.jl/actions/workflows/docs.yml
+
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://CliMA.github.io/NullBroadcasts.jl/dev/
+
+[gha-ci-img]: https://github.com/CliMA/NullBroadcasts.jl/actions/workflows/ci.yml/badge.svg
+[gha-ci-url]: https://github.com/CliMA/NullBroadcasts.jl/actions/workflows/ci.yml
+
+[codecov-img]: https://codecov.io/gh/CliMA/NullBroadcasts.jl/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/CliMA/NullBroadcasts.jl
+
+This package defines `NullBroadcasted()`, which can be added to, subtracted
+from, or multiplied by any value in a broadcast expression without incurring a
+runtime performance penalty.
+
+# Example
+
+```julia
+using NullBroadcasts: NullBroadcasted
+using Test
+
+x = [1]; y = [1]
+a = NullBroadcasted()
+@. x = x + a + y
+@test x[1] == 2 # passes
+
+x = [1]; y = [1]
+@. x = x - a + y
+@test x[1] == 2 # passes
+
+@. x = x + (x * a) # equivalent to @. x = x
+
+@. x = x * a # not allowed, errors
+@. x = a # not allowed, errors
+```

docs/src/index.md

@@ -1,2 +1,3 @@
 # NullBroadcasts.jl
 
+Under construction. Please see the readme for the latest documentation.

src/NullBroadcasts.jl

@@ -5,10 +5,13 @@ module NullBroadcasts
 
 A `Base.AbstractBroadcasted` that represents arithmetic object.
 
-An `NullBroadcasted()` can be added to, subtracted from, or multiplied by any value in a
-broadcast expression without incurring a runtime performance penalty.
+An `NullBroadcasted()` can be added to, subtracted from, or multiplied by any
+value in a broadcast expression without incurring a runtime performance
+penalty.
+
+For example, the following rules hold when broadcasting instances of
+`NullBroadcasted`:
 
-For example, the following rules hold when broadcasting instances of `NullBroadcasted`:
 ```
 1 + NullBroadcasted() == 1
 NullBroadcasted() + 1 == 1
@@ -51,9 +54,10 @@ Base.broadcasted(op::typeof(-), a::NullBroadcasted, ::NullBroadcasted) =
     Base.broadcasted(op, a)
 
 Base.broadcasted(op::typeof(+), ::NullBroadcasted, args...) = Base.broadcasted(op, args...)
-Base.broadcasted(op::typeof(+), arg, ::NullBroadcasted) = Base.broadcasted(op, arg)
-Base.broadcasted(op::typeof(+), a::NullBroadcasted, ::NullBroadcasted) =
-    Base.broadcasted(op, a)
+Base.broadcasted(op::typeof(+), arg, ::NullBroadcasted, args...) =
+    Base.broadcasted(op, arg, args...)
+Base.broadcasted(op::typeof(+), a::NullBroadcasted, ::NullBroadcasted, args...) =
+    Base.broadcasted(op, a, args...)
 
 Base.broadcasted(op::typeof(*), ::NullBroadcasted, args...) = NullBroadcasted()
 Base.broadcasted(op::typeof(*), arg, ::NullBroadcasted) = NullBroadcasted()
@@ -62,6 +66,8 @@ Base.broadcasted(op::typeof(/), ::NullBroadcasted, args...) = NullBroadcasted()
 Base.broadcasted(op::typeof(/), arg, ::NullBroadcasted) = NullBroadcasted()
 Base.broadcasted(op::typeof(/), ::NullBroadcasted, ::NullBroadcasted) = NullBroadcasted()
 
+Base.broadcasted(op::typeof(identity), a::NullBroadcasted) = a
+
 function skip_materialize(dest, bc::Base.Broadcast.Broadcasted)
     if typeof(bc.f) <: typeof(+) || typeof(bc.f) <: typeof(-)
         if length(bc.args) == 2 &&
@@ -78,4 +84,9 @@ end
 
 Base.Broadcast.instantiate(bc::Base.Broadcast.Broadcasted{NullBroadcastedStyle}) = x
 
+Base.Broadcast.materialize!(dest, x::NullBroadcasted) =
+    error("NullBroadcasted objects cannot be materialized.")
+Base.Broadcast.materialize(dest, x::NullBroadcasted) =
+    error("NullBroadcasted objects cannot be materialized.")
+
 end # module NullBroadcasts

test/runtests.jl

@@ -32,6 +32,8 @@ import Base.Broadcast: instantiate, materialize, Broadcasted, DefaultArrayStyle
     @test materialize(lazy.(a .+ 1 .+ x)) == [2]
     @test materialize(lazy.(1 .+ a .+ x)) == [2]
     @test materialize(lazy.(1 .+ x .+ a)) == [2]
+    @test materialize(lazy.(x .+ a .+ x)) == [2]
+    @test materialize(lazy.(x .+ a .+ x)) == [2]
 
     # -
     @test materialize(lazy.(a .- x .- 1)) == [-2]
@@ -47,6 +49,10 @@ import Base.Broadcast: instantiate, materialize, Broadcasted, DefaultArrayStyle
     @test materialize(lazy.(a .* 1 .* x)) == NullBroadcasted()
     @test materialize(lazy.(1 .* a .* x)) == NullBroadcasted()
     @test materialize(lazy.(1 .* x .* a)) == NullBroadcasted()
+    @test materialize(lazy.(x .+ (x .* a))) == [1]
+    @test materialize(lazy.(x .- (x .* a))) == [1]
+    @test materialize(lazy.((x .* a) .+ x)) == [1]
+    @test materialize(lazy.((x .* a) .- x)) == [-1]
 
     # /
     @test materialize(lazy.(a ./ x ./ 1)) == NullBroadcasted()
@@ -60,6 +66,10 @@ import Base.Broadcast: instantiate, materialize, Broadcasted, DefaultArrayStyle
     @test_throws MethodError NullBroadcasted() / 1
 
     @test materialize(NullBroadcasted()) isa NullBroadcasted
+
+    @test_throws ErrorException("NullBroadcasted objects cannot be materialized.") @. x =
+        x * a
+    @test_throws ErrorException("NullBroadcasted objects cannot be materialized.") @. x = a
 end
 
 @testset "Aqua" begin