Do not use Unsafe type

CHANGELOG.md

@@ -4,6 +4,30 @@ Any new features, or breaking changes, will be written in this file.
 Bugfixes, internal refactors, documentation improvements and style changes will
 not be mentioned here, because they do not impact how the package is to be used.
 
+## 0.4.0
+### Breaking changes
+* Removed the `Unsafe` trait type:
+    - Instead of `MutableMemoryView(::Unsafe, ::MemoryView)`, use
+      `unsafe_from_parts(::MemoryRef, ::Int)`
+    - 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.
+
+* Out of bounds access now throws a `LightBoundsError` from the LightBoundsErrors
+  package, instead of `Base.BoundsError`.
+  This improves codegen slightly, as it enables escape analysis of the array,
+  and outlines error paths slightly more aggressively.
+
+* `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}}`
 * Add package extension for LibDeflate.jl

docs/src/interfaces.md

@@ -34,14 +34,14 @@ For a type `T`, `MemoryKind(T)` returns one of two types:
   they are not heap allocated, and `String`, which _are_ backed by memory, but which are semantically different from an `AbstractVector`
   containing its bytes.
 * `IsMemory{M}()` where `M` is a concrete subtype of `MemoryView`, if instances of `T` _are_ equivalent to their own memory.
-  Examples include `Array`s and `Codeunits{String}`. For these objects, it's the case that `x == MemoryView(x)`.
+  Examples include `Vector`s and `Codeunits{String}`. For these objects, it's the case that `x == MemoryView(x)`.
 
 ```jldoctest
 julia> MemoryKind(Vector{Union{Int32, UInt32}})
 IsMemory{MutableMemoryView{Union{Int32, UInt32}}}()
 
-julia> MemoryKind(Matrix{String})
-IsMemory{MutableMemoryView{String}}()
+julia> MemoryKind(Matrix{String}) # dimension mismatch, not equal
+NotMemory()
 
 julia> MemoryKind(SubString{String})
 NotMemory()
@@ -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,23 +8,16 @@ export MemoryView,
     NotMemory,
     inner,
     split_each,
-    unsafe_from_parts
+    unsafe_from_parts,
+    split_first,
+    split_last,
+    split_at,
+    split_unaligned
 
 public Mutable, Immutable, DelimitedIterator
 
 using LightBoundsErrors: checkbounds_lightboundserror, throw_lightboundserror
 
-"""
-    Unsafe
-
-Trait object used to dispatch to unsafe methods.
-The `MemoryViews.unsafe` instance is the singleton instance of this type.
-"""
-struct Unsafe end
-
-"Singleton instance of the trait type `Unsafe`"
-const unsafe = Unsafe()
-
 """
 Trait struct, only used in the mutability parameter of `MemoryView`
 """
@@ -89,7 +82,7 @@ struct MemoryView{T, M <: Union{Mutable, Immutable}} <: DenseVector{T}
     ref::MemoryRef{T}
     len::Int
 
-    function MemoryView{T, M}(::Unsafe, ref::MemoryRef{T}, len::Int) where {T, M}
+    global function unsafe_new_memoryview(::Type{M}, ref::MemoryRef{T}, len::Int) where {M, T}
         (M === Mutable || M === Immutable) ||
             error("Parameter M must be Mutable or Immutable")
         return new{T, M}(ref, len)
@@ -108,8 +101,10 @@ Create a mutable memory view from its parts.
 * `len` is not negative
 * All indices `i in 1:len` are valid for `ref` (i.e. `memoryref(ref, i)` would
   not throw)
-* If `ref` is derived from immutable memory, the returned memory view must not
-  be mutated. The caller should immediately convert it to an immutable view.
+* If `ref` is derived from immutable memory, it is the caller's responsibility
+  to ensure that mutating the memory does not result in undefined behaviour.
+  For example, `ref` may be derived from a `String`, and mutating `String`s in
+  Julia may result in undefined behaviour.
 
 # Examples
 ```jldoctest
@@ -124,28 +119,24 @@ julia> view = unsafe_from_parts(ref, 3)
  3
 ```
 """
-function unsafe_from_parts(ref::MemoryRef{T}, len::Int) where {T}
-    return MemoryView{T, Mutable}(unsafe, ref, len)
+function unsafe_from_parts(ref::MemoryRef, len::Int)
+    return unsafe_new_memoryview(Mutable, ref, len)
 end
 
+"""
+    Base.memoryref(x::MemoryView{T})::MemoryRef{T}
+
+Get the `MemoryRef` of `x`. This reference is guaranteed to be inbounds,
+except if `x` is empty, where it may point to one element past the end.
+"""
+Base.memoryref(x::MemoryView) = x.ref
+
 _get_mutability(::MemoryView{T, M}) where {T, M} = M
 
 # Mutable mem views can turn into immutable ones, but not vice versa
 ImmutableMemoryView(x) = ImmutableMemoryView(MemoryView(x)::MemoryView)
-function ImmutableMemoryView(x::MutableMemoryView{T}) where {T}
-    return ImmutableMemoryView{T}(unsafe, x.ref, x.len)
-end
-ImmutableMemoryView(x::ImmutableMemoryView) = x
-
-"""
-    MutableMemoryView(::Unsafe, x::MemoryView)
-
-Convert a memory view into a mutable memory view.
-Note that it may cause undefined behaviour, if supposedly immutable data
-is observed to be mutated.
-"""
-function MutableMemoryView(::Unsafe, x::MemoryView{T}) where {T}
-    return MutableMemoryView{T}(unsafe, x.ref, x.len)
+function ImmutableMemoryView(x::MemoryView)
+    return unsafe_new_memoryview(Immutable, x.ref, x.len)
 end
 
 # Constructors that allows users to specify eltype explicitly, e.g.
@@ -220,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