Move experiemental API to stable

Author: Jakob Nybo Andersen

CHANGELOG.md

@@ -12,12 +12,16 @@ not be mentioned here, because they do not impact how the package is to be used.
     - Using the inner constructor `MemoryView{T, M}(::Unsafe, ::MemoryRef{T}, ::Int)`
       was never documented API and is now removed.
 
+* `Matrix` and other `Array` types with a different dimensionality than 1 is now
+  `NotMemory`, since it is not equal to its own memory view, due to shape mismatch.
+
 * `MemoryView(::SubArray)` now accepts fewer subarray types. However, it is unlikely
   that any instance that is now no longer accepted worked previously, so it is
   unlikely to be breaking in practice.
 
 ## Other
 * `parentindices` now works correctly for zero-sized structs.
+* `Base.memoryref(::MemoryView)` obtains the `MemoryRef` in a `MemoryView`.
 
 ## 0.3.5
 * Add method `MemoryKind{::Type{<:MemoryView}}`

docs/src/interfaces.md

@@ -63,7 +63,7 @@ my_hash(x) = my_hash(MemoryKind(typeof(x)), x)
 my_hash(::IsMemory{<:MemoryView{UInt8}}, x) = my_hash(ImmutableMemoryView(x))
 
 # IsMemory with eltype other than UInt8 can't use the fast low-level function
-my_hash(T::IsMemory, x) = my_hash(NotMemory(), x)
+my_hash(::IsMemory, x) = my_hash(NotMemory(), x)
 
 function my_hash(::NotMemory, x)
     # fallback implementation

src/MemoryViews.jl

@@ -8,7 +8,11 @@ export MemoryView,
     NotMemory,
     inner,
     split_each,
-    unsafe_from_parts
+    unsafe_from_parts,
+    split_first,
+    split_last,
+    split_at,
+    split_unaligned
 
 public Mutable, Immutable, DelimitedIterator
 
@@ -207,7 +211,6 @@ MemoryKind(::Type{T}) where {T <: MemoryView} = IsMemory(T)
 
 include("construction.jl")
 include("basic.jl")
-include("experimental.jl")
 include("delimited.jl")
 include("base_arrays.jl")
 include("io.jl")

src/base_arrays.jl

@@ -14,7 +14,6 @@ function Base.Memory{T}(x::MemoryView{T}) where {T}
     end
 end
 
-
 function Base.copyto!(A::Union{Memory{T}, Array{T}}, mem::MemoryView{T}) where {T}
     copyto!(MemoryView(A), mem)
     return A

src/basic.jl

@@ -404,3 +404,122 @@ function Base.iterate(x::ReverseMemoryView, state = length(x))
     iszero(state) && return nothing
     return (@inbounds(x.mem[state]), state - 1)
 end
+
+"""
+    split_first(v::MemoryView{T}) -> Tuple{T, MemoryView{T}}
+
+Return the first element of `v` and all other elements as a new memory view.
+
+This function will throw a `BoundsError` if `v` is empty.
+
+See also: [`split_last`](@ref)
+
+# Examples
+```jldoctest
+julia> v = MemoryView([0x01, 0x02, 0x03]);
+
+julia> split_first(v)
+(0x01, UInt8[0x02, 0x03])
+
+julia> split_first(v[1:1])
+(0x01, UInt8[])
+
+julia> split_first(v[1:0])
+ERROR: BoundsError: attempt to access 0-element MutableMemoryView{UInt8} at index [1]
+[...]
+```
+"""
+function split_first(v::MemoryView)
+    @boundscheck checkbounds(v, 1)
+    return (@inbounds(v[1]), @inbounds(truncate_start(v, 2)))
+end
+
+"""
+    split_last(v::MemoryView{T}) -> Tuple{T, MemoryView{T}}
+
+Return the last element of `v` and all other elements as a new memory view.
+
+This function will throw a `BoundsError` if `v` is empty.
+
+See also: [`split_first`](@ref)
+
+# Examples
+```jldoctest
+julia> v = MemoryView([0x01, 0x02, 0x03]);
+
+julia> split_last(v)
+(0x03, UInt8[0x01, 0x02])
+
+julia> split_last(v[1:1])
+(0x01, UInt8[])
+
+julia> split_last(v[1:0])
+ERROR: BoundsError: attempt to access 0-element MutableMemoryView{UInt8} at index [1]
+[...]
+```
+"""
+function split_last(v::MemoryView)
+    @boundscheck checkbounds(v, 1)
+    return (@inbounds(v[end]), @inbounds(truncate(v, length(v) - 1)))
+end
+
+"""
+    split_at(v::T, i::Int) -> Tuple{T, T} where {T <: MemoryView}
+
+Split a memory view into two at an index.
+
+The first will contain all indices in `1:i-1`, the second `i:end`.
+This function will throw a `BoundsError` if `i` is not in `1:end+1`.
+
+# Examples
+```jldocstest
+julia> split_at(MemoryView([1,2,3,4,5]), 2)
+([1], [2, 3, 4, 5])
+
+julia> split_at(MemoryView(Int8[1, 2, 3]), 4)
+(Int8[1, 2, 3], Int8[])
+```
+"""
+function split_at(v::MemoryView, i::Int)
+    @boundscheck checkbounds(1:(lastindex(v) + 1), i)
+    return (@inbounds(truncate(v, i - 1)), @inbounds(truncate_start(v, i)))
+end
+
+"""
+    split_unaligned(v::T, ::Val{A}) -> Tuple{T, T} where {T <: MemoryView}
+
+Split memory view `v` into two views `a` and `b`, where `a` is the smallest prefix of `v`
+that guarantees the starting memory address of `b` is is aligned to the integer value `A`.
+`A` must be a normal bit-integer, and a power of two in the range 1:64.
+
+If `v` is empty or already aligned, `a` will be empty.
+If no elements of `v` is aligned, `b` will be empty and `a` will be equal to `v`.
+The element type of `v` must be a bitstype.
+
+!!! warning
+    When using this function, make sure to `GC.@preserve v`, to make sure Julia
+    does not move `v` in memory.
+
+# Examples:
+```
+julia> split_unaligned(MemoryView(Int16[1, 2, 3]), Val(8))
+(Int16[], Int16[1, 2, 3])
+
+julia> split_unaligned(MemoryView(collect(0x01:0x20))[6:13], Val(8))
+(UInt8[0x06, 0x07, 0x08], UInt8[0x09, 0x0a, 0x0b, 0x0c, 0x0d])
+```
+"""
+function split_unaligned(v::MemoryView{T, M}, ::Val{A}) where {A, T, M}
+    isbitstype(eltype(v)) || error("Alignment can only be computed for views of bitstypes")
+    A isa Bits || error("Invalid alignment")
+    in(A, (1, 2, 4, 8, 16, 32, 64)) || error("Invalid alignment")
+    alignment = A % UInt
+    mask = alignment - 1
+    sz = Base.elsize(v)
+    # Early return here to avoid division by zero: Size sz is statically known,
+    # this will be compiled away
+    iszero(sz) && return (unsafe_new_memoryview(M, v.ref, 0), v)
+    unaligned_bytes = ((alignment - (UInt(pointer(v)) & mask)) & mask)
+    n_elements = min(length(v), div(unaligned_bytes, sz % UInt) % Int)
+    return @inbounds split_at(v, n_elements + 1)
+end