From b768fae2b5b92425d0b753e743b3c801634a6fa4 Mon Sep 17 00:00:00 2001 From: Charles Kawczynski Date: Fri, 31 Jan 2025 09:24:52 -0500 Subject: [PATCH] Update readme Docs + fixes --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++- docs/src/index.md | 1 + src/NullBroadcasts.jl | 23 ++++++++++++++++------ test/runtests.jl | 10 ++++++++++ 4 files changed, 71 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index fa6a1d3..a4a9dad 100644 --- a/README.md +++ b/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 +``` diff --git a/docs/src/index.md b/docs/src/index.md index 05b1173..a20ac2c 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,2 +1,3 @@ # NullBroadcasts.jl +Under construction. Please see the readme for the latest documentation. diff --git a/src/NullBroadcasts.jl b/src/NullBroadcasts.jl index a4e5ac6..7946945 100644 --- a/src/NullBroadcasts.jl +++ b/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 diff --git a/test/runtests.jl b/test/runtests.jl index 3eea262..391677a 100644 --- a/test/runtests.jl +++ b/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