Support multidimensional arrays (#7)

Author: adrhill

README.md

@@ -12,6 +12,7 @@ julia> ]add UnicodeGraphics
 ```
 
 ## Examples
+By default, `uprint` prints all values in an array that are true or greater than zero:
 ```julia
 julia> pac = [
    0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0
@@ -56,7 +57,7 @@ julia> uprint(pac, :block)
      ▀▀██████▀▀     
 ```
 
-It is also possible to pass a filtering function, filling values for which the function returns `true`:
+It is also possible to pass a filtering function, filling values for which the function returns `true`, e.g. all even numbers in the following array:
 ```julia
 julia> ghost = [
    1 7 7 7 7 8 6 4 6 3 9 9 9 7
@@ -80,13 +81,65 @@ julia> uprint(iseven, ghost)
 ⣿⢿⣿⠿⣿⡿⣿
 ⠁⠀⠉⠀⠉⠀⠈
 ```
-`uprint` can be used to write into any `IO` stream, defaulting to `stdout`.
 
-`ustring` can be used to return a string instead of printing to IO:
+Non-number type inputs are also supported, 
+as long as the filtering function returns boolean values:
+
+```julia-repl
+julia> A = rand("abc123", 4, 4)
+4×4 Matrix{Char}:
+ '3'  'c'  '3'  '1'
+ 'a'  'c'  '1'  'c'
+ '1'  '1'  '2'  'a'
+ 'b'  'a'  '2'  'a'
+
+julia> uprint(isletter, A, :block)
+▄█ ▄
+▄▄ █
+```
+
+Multidimensional arrays are also supported:
+```julia-repl
+julia> A = rand(Bool, 4, 4, 1, 2)
+4×4×1×2 Array{Bool, 4}:
+[:, :, 1, 1] =
+ 0  1  0  0
+ 1  0  1  0
+ 0  1  1  1
+ 0  0  1  1
+
+[:, :, 1, 2] =
+ 1  1  0  0
+ 1  1  0  0
+ 0  0  1  0
+ 0  0  1  0
+
+julia> uprint(A, :block)
+[:, :, 1, 1] =
+▄▀▄ 
+ ▀██
+
+[:, :, 1, 2] =
+██  
+  █ 
+```
+
+`uprint` can be used to write into any `IO` stream, defaulting to `stdout`.
 ```julia-repl
-julia> ustring(iseven, ghost)
-"⢀⠴⣾⣿⠷⣦⡀\n⣴⠆⣸⣷⠆⣸⣧\n⣿⢿⣿⠿⣿⡿⣿\n⠁⠀⠉⠀⠉⠀⠈\n"
+julia> io = IOBuffer();
+
+julia> uprint(io, pac)
 
-julia> ustring(iseven, ghost, :block)
-"   ▄▄████▄▄   \n ▄▀▀████▀▀██▄ \n ▄▄  ██▄▄  ██ \n██▀ ▄███▀ ▄███\n██████████████\n██▀███▀▀███▀██\n▀   ▀▀  ▀▀   ▀\n"
+julia> String(take!(io)) |> print
+⠀⣠⣴⣾⣿⣿⣷⣦⣄⠀
+⣰⣿⣿⣿⣧⣼⣿⡿⠟⠃
+⣿⣿⣿⣿⣿⣏⡁⠀⠀⠠
+⠹⣿⣿⣿⣿⣿⣿⣷⣦⡄
+⠀⠙⠻⢿⣿⣿⡿⠟⠋⠀
+```
+
+To directly return a string instead of printing to IO, `ustring` can be used:
+```julia-repl
+julia> ustring(pac)
+"⠀⣠⣴⣾⣿⣿⣷⣦⣄⠀\n⣰⣿⣿⣿⣧⣼⣿⡿⠟⠃\n⣿⣿⣿⣿⣿⣏⡁⠀⠀⠠\n⠹⣿⣿⣿⣿⣿⣿⣷⣦⡄\n⠀⠙⠻⢿⣿⣿⡿⠟⠋⠀\n"
 ```

src/UnicodeGraphics.jl

@@ -5,6 +5,7 @@ module UnicodeGraphics
 
 const DEFAULT_METHOD = :braille
 include("api.jl")
+include("ndarray.jl")
 include("core.jl")
 include("deprecate.jl")
 

src/api.jl

@@ -30,8 +30,8 @@ julia> uprint(A, :block)
 ▄▄▀▄▄█ ▀
 ```
 """
-uprint(A::AbstractMatrix, method::Symbol=DEFAULT_METHOD) = uprint(stdout, A, method)
-function uprint(io::IO, A::AbstractMatrix, method::Symbol=DEFAULT_METHOD)
+uprint(A::AbstractArray, method::Symbol=DEFAULT_METHOD) = uprint(stdout, A, method)
+function uprint(io::IO, A::AbstractArray, method::Symbol=DEFAULT_METHOD)
     return uprint(io, >(zero(eltype(A))), A, method)
 end
 
@@ -67,18 +67,11 @@ julia> uprint(>(3), A, :block)
  ██ ██▀█
 ```
 """
-function uprint(f::Function, A::AbstractMatrix, method::Symbol=DEFAULT_METHOD)
+function uprint(f::Function, A::AbstractArray, method::Symbol=DEFAULT_METHOD)
     return uprint(stdout, f, A, method)
 end
-function uprint(io::IO, f::Function, A::AbstractMatrix, method::Symbol=DEFAULT_METHOD)
-    if method == :braille
-        to_braille(io, f, A)
-    elseif method == :block
-        to_block(io, f, A)
-    else
-        throw(ArgumentError("Valid methods are :braille and :block, got :$method."))
-    end
-    return nothing
+function uprint(io::IO, f::Function, A::AbstractArray, method::Symbol=DEFAULT_METHOD)
+    return _uprint_nd(io::IO, f::Function, A::AbstractArray, method::Symbol)
 end
 
 """
@@ -110,7 +103,7 @@ julia> ustring(A, :block)
 "█▀▀█▄█  \n█ ▄ █▄█▄\n ▄▄ ▄ ▀▄\n▄▄█▄ ▀██\n"
 ```
 """
-function ustring(A::AbstractMatrix, method::Symbol=DEFAULT_METHOD)
+function ustring(A::AbstractArray, method::Symbol=DEFAULT_METHOD)
     return ustring(>(zero(eltype(A))), A, method)
 end
 
@@ -143,7 +136,7 @@ julia> ustring(>(3), A, :block)
 "██▀▀██ ▀\n▄██▄██ █\n▄██▄  ██\n█▀█▄▄▀██\n"
 ```
 """
-function ustring(f::Function, A::AbstractMatrix, method::Symbol=DEFAULT_METHOD)
+function ustring(f::Function, A::AbstractArray, method::Symbol=DEFAULT_METHOD)
     io = IOBuffer()
     uprint(io, f, A, method)
     return String(take!(io))

src/ndarray.jl

@@ -0,0 +1,40 @@
+# For matrices, directly call core.jl method matching method Symbol.
+function _uprint_nd(io::IO, f::Function, A::AbstractMatrix, method::Symbol)
+    if method == :braille
+        to_braille(io, f, A)
+    elseif method == :block
+        to_block(io, f, A)
+    else
+        throw(ArgumentError("Valid methods are :braille and :block, got :$method."))
+    end
+    return nothing
+end
+# View vectors as 1xn adjoints
+function _uprint_nd(io::IO, f::Function, v::AbstractVector, method::Symbol)
+    _uprint_nd(io, f, adjoint(v), method)
+    return nothing
+end
+
+# For multi-dimensional arrays, iterate over tail-indices
+function _uprint_nd(io::IO, f::Function, A::AbstractArray, method::Symbol)
+    axs= axes(A)
+    tailinds = Base.tail(Base.tail(axs))
+    Is = CartesianIndices(tailinds)
+    for I in Is
+        idxs = I.I
+        _show_nd_label(io, idxs)
+        slice = view(A, axs[1], axs[2], idxs...) # matrix-shaped slice
+        _uprint_nd(io, f, slice, method)
+        print(io, idxs == map(last,tailinds) ? "" : "\n")
+    end
+    return nothing
+end
+# adapted from Base._show_nd_label
+function _show_nd_label(io::IO, idxs)
+    print(io, "[:, :, ")
+    for i = 1:length(idxs)-1
+        print(io, idxs[i], ", ")
+    end
+    println(io, idxs[end], "] =")
+    return nothing
+end

test/runtests.jl

@@ -77,6 +77,13 @@ ghost2 = [
 @test_reference "references/braille_ghost.txt" @capture_out uprint(iseven, ghost2)
 @test_reference "references/block_ghost.txt" @capture_out uprint(iseven, ghost2, :block)
 
+# Test vector and n-dimensional arrays
+v = [0, 1, 0, 1, 1, 0, 0, 1]
+@test ustring(v) == "⠈⠈⠁⠈\n"
+
+A = reshape(v, 2, 2, 1, 1, 2)
+@test ustring(A) == "[:, :, 1, 1, 1] =\n⠒\n\n[:, :, 1, 1, 2] =\n⠑\n"
+
 # Remove deprecations before next breaking release:
 @test_reference "references/braille_ghost.txt" (@test_deprecated brailize(ghost))
 @test_reference "references/block_ghost.txt" (@test_deprecated blockize(ghost))