deprecate memmap for empty (#82)

fixes #80

docs/src/lib/public.md

@@ -4,7 +4,6 @@
 
 ```@docs
 TiffImages.load
-memmap
 ```
 
 ### Output Types

examples/mmap_lazyio.jl

@@ -165,13 +165,14 @@ GC.gc()
 # ### Incremental writing
 
 # `TiffImages` also supports writing to a file via an append
-# operation. As with most arrays, you need to provide an element type and a
-# filepath, but we'll use the [`memmap`](@ref) function in place of `load`
+# operation. We have a special type for this called 
+# [`LazyBufferedTIFF`](@ref), that we can create via the standard
+# `empty` function
 
 using TiffImages #hide
 #--------------
 using ImageCore # reexports Gray and N0f8
-img2 = memmap(Gray{N0f8}, "test.tif")
+img2 = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif")
 
 # !!! note
 #     For data-integrity reasons, `TiffImages` will not allow you to append to
@@ -207,4 +208,4 @@ img2[:, :, 2]
 # helpful to set the `bigtiff` flag to true so that `TiffImages` can use 64-bit
 # offsets. You'll see that the addressable space sky rockets:
 
-img3 = memmap(Gray{N0f16}, "test.btif"; bigtiff=true)
+img3 = empty(LazyBufferedTIFF, Gray{N0f16}, "test.btif"; bigtiff=true)

src/TiffImages.jl

@@ -33,7 +33,7 @@ include(joinpath("types", "lazy.jl"))
 include(joinpath("types", "mmapped.jl"))
 include("load.jl")
 
-export memmap
+export memmap, LazyBufferedTIFF
 
 @deprecate TiffFile(::Type{O}) where O<:Unsigned TiffFile{O}()
 

src/types/dense.jl

@@ -167,4 +167,4 @@ function save(filepath::String, data)
     nothing
 end
 
-Base.push!(A::DenseTaggedImage{T, N, O, AA}, data) where {T, N, O, AA} = error("push! is only supported for memory mapped images. See `memmap`.")
+Base.push!(A::DenseTaggedImage{T, N, O, AA}, data) where {T, N, O, AA} = error("push! is only supported for memory mapped images. See `LazyBufferedTIFF`.")

src/types/lazy.jl

@@ -13,7 +13,7 @@ with different strengths and weaknesses.
 ```jldoctest
 julia> using TiffImages, ColorTypes
 
-julia> img = TiffImages.memmap(Gray{Float32}, joinpath(mktempdir(), "test.tif"))
+julia> img = empty(LazyBufferedTIFF, Gray{Float32}, joinpath(mktempdir(), "test.tif"))
 32-bit LazyBufferedTIFF{Gray{Float32}} 0×0×0 (writable)
     Current file size on disk:   8 bytes
     Addressable space remaining: 4.000 GiB
@@ -67,7 +67,7 @@ function LazyBufferedTIFF(file::TiffFile{O}, ifds::Vector{IFD{O}}) where {O}
 end
 
 """
-    memmap(T, filepath; bigtiff)
+    empty(LazyBufferedTIFF, T, filepath; bigtiff)
 
 Create a new memory-mapped file ready with element type `T` for appending future
 slices. The `bigtiff` flag, if true, allows 64-bit offsets for data larger than
@@ -76,7 +76,7 @@ slices. The `bigtiff` flag, if true, allows 64-bit offsets for data larger than
 ```jldoctest; setup=:(rm("test.tif", force=true))
 julia> using ColorTypes, FixedPointNumbers # for Gray{N0f8} type
 
-julia> img = memmap(Gray{N0f8}, "test.tif"); # make memory-mapped image
+julia> img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif"); # make memory-mapped image
 
 julia> push!(img, rand(Gray{N0f8}, 100, 100));
 
@@ -86,13 +86,18 @@ julia> size(img)
 (100, 100, 2)
 ```
 """
-function memmap(::Type{T}, filepath; bigtiff=false) where {T <: Colorant}
+function Base.empty(::Type{LazyBufferedTIFF}, ::Type{T}, filepath; bigtiff=false) where {T <: Colorant}
     if isfile(filepath)
         error("This file already exists, please use `TiffImages.load` to open")
     end
     LazyBufferedTIFF(T, getstream(format"TIFF", open(filepath, "w+"), filepath); bigtiff = bigtiff)
 end
 
+function memmap(t::Type{T}, filepath; bigtiff=false) where {T <: Colorant}
+    Base.depwarn("`memmap` is deprecated, please use empty(LazyBufferedTIFF, $t, $filepath; bigtiff = $bigtiff)", :memmap, force = true)
+    empty(LazyBufferedTIFF, t, filepath; bigtiff = bigtiff)
+end
+
 function LazyBufferedTIFF(::Type{T}, io::Stream; bigtiff = false) where {T}
     O = bigtiff ? UInt64 : UInt32
     tf = TiffFile{O}(io)

test/mmap_lazyio.jl

@@ -71,7 +71,7 @@ end
 
 @testset "De novo construction" begin
     rm("test.tif", force = true)
-    img = memmap(Gray{N0f8}, "test.tif")
+    img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.tif")
 
     # a newly initialized file should have every dimension equal to zero and
     # error if accessed
@@ -86,7 +86,7 @@ end
 
     @testset "BigTIFF" begin
         rm("test.btif", force = true)
-        img = memmap(Gray{N0f8}, "test.btif"; bigtiff = true)
+        img = empty(LazyBufferedTIFF, Gray{N0f8}, "test.btif"; bigtiff = true)
 
         push!(img, rand(Gray{N0f8}, 100, 100))
         @test size(img) == (100, 100, 1)