From d099dbf4201721f77fbd37540fd2b5dd50b24467 Mon Sep 17 00:00:00 2001 From: John Myles White Date: Sun, 23 Aug 2015 19:20:43 -0700 Subject: [PATCH] Clean up codebase for a public 0.1.0 release Move comments out into a separate design doc Add Julia 0.4 style inline documentation for in-REPL docs Remove redundant constructor Add missing constructors for NullableVector and NullableMatrix --- src/constructors.jl | 190 ++++++++++++++++++++++++++++++++++---------- src/typedefs.jl | 29 +++---- 2 files changed, 159 insertions(+), 60 deletions(-) diff --git a/src/constructors.jl b/src/constructors.jl index 8246f74..53eeda1 100644 --- a/src/constructors.jl +++ b/src/constructors.jl @@ -1,47 +1,160 @@ +@doc """ +# Description -# ----- Outer Constructors -------------------------------------------------- # +Construct a NullableArray from an array of values and a Boolean mask indicating +which values should be considered null. -# ----- Constructor #1 -# The following provides an outer constructor whose argument signature matches -# that of the inner constructor provided in 01_typedefs.jl. -function NullableArray{T, N}(A::AbstractArray{T, N}, - m::Array{Bool, N}) # -> NullableArray{T, N} - return NullableArray{T, N}(A, m) -end +# Args + +* values: An array indicating the values taken on when entries are not null. +* isnull: An array indicating which entries are not null. + +# Returns + +* x::NullableArray{T, N}: A nullable array containing the specified values + and missing the indicated entries. -# ----- Constructor #2 -------------------------------------------------------# -# Constructs a NullableArray from an Array 'a' of values and an optional -# Array{Bool, N} mask. If omitted, the mask will default to an array of -# 'false's the size of 'a'. -function NullableArray{T, N}(A::AbstractArray{T, N}) # -> NullableArray{T, N} - return NullableArray{T, N}(A, fill(false, size(A))) +# Examples + +``` +x = NullableArray([1, 2, 3], [false, false, false]) +y = NullableArray([1, 2, 3]) +``` +""" -> +function NullableArray{T, N}( + values::AbstractArray{T, N}, + isnull::Array{Bool, N} = fill(false, size(values)), +) + NullableArray{T, N}(values, isnull) end -# ----- Constructor #3 -------------------------------------------------------# -# TODO: Uncomment this doc entry when Base Julia can parse it correctly. -# @doc """ -# Allow users to construct a quasi-uninitialized `NullableArray` object by -# specifing: -# -# * `T`: The type of its elements. -# * `dims`: The size of the resulting `NullableArray`. -# -# NOTE: The `values` field will be truly uninitialized, but the `isnull` field -# will be initialized to `true` everywhere, making every entry of a new -# `NullableArray` a null value by default. -# """ -> -function NullableArray{T}(::Type{T}, dims::Dims) # -> NullableArray{T, N} - return NullableArray(Array(T, dims), fill(true, dims)) +@doc """ +# Description + +Construct a quasi-uninitialized `NullableArray` object by specifying the type +of its elements and its size as a tuple. + +The result is quasi-uninitialized because the underlying memory for +representing values will be left uninitialized, but the `isnull` bitmask will +be initialized to false everywhere. + +# Args + +* T: The type of elements of the resulting `NullableArray`. +* dims: The size of the resulting `NullableArray` as a tuple. + +# Returns + +* x::NullableArray{T, N}: A nullable array of the specified type and size. + +# Examples + +``` +x = NullableArray(Int64, (2, 2)) +``` +""" -> +function NullableArray{T}(::Type{T}, dims::Dims) + NullableArray(Array(T, dims), fill(true, dims)) end -# ----- Constructor #4 -------------------------------------------------------# -# Constructs an empty NullableArray of type parameter T and number of dimensions -# equal to the number of arguments given in 'dims...', where the latter are -# dimension lengths. -function NullableArray(T::Type, dims::Int...) # -> NullableArray +@doc """ +# Description + +Construct a quasi-uninitialized `NullableArray` object by specifying the type +of its elements and its size as a sequence of separate integer arguments. + +The result is quasi-uninitialized because the underlying memory for +representing values will be left uninitialized, but the `isnull` bitmask will +be initialized to false everywhere. + +# Args + +* T: The type of elements of the resulting `NullableArray`. +* dims: The size of the resulting `NullableArray` as a sequence of integer + arguments. + +# Returns + +* x::NullableArray{T, N}: A nullable array of the specified type and size. + +# Examples + +``` +x = NullableArray(Int64, 2, 2) +``` +""" -> +function NullableArray(T::Type, dims::Int...) return NullableArray(T, dims) end +@doc """ +# Description + +Construct an empty `NullableArray` object by calling the name of the +fully parametrized type with zero arguments. + +# Args + +NONE + +# Returns + +* x::NullableArray{T, N}: An empty nullable array of the specified type. + +# Examples + +``` +x = NullableArray{Int64, 2}() +``` +""" -> +function Base.call{T, N}(::Type{NullableArray{T, N}}) + NullableArray(T, ntuple(i -> 0, N)) +end + +@doc """ +# Description + +Construct an empty `NullableVector` object by calling the name of the +fully parametrized type with zero arguments. + +# Args + +NONE + +# Returns + +* x::NullableVector{T}: An empty nullable vector of the specified type. + +# Examples + +``` +x = NullableVector{Int64}() +``` +""" -> +Base.call{T}(::Type{NullableVector{T}}) = NullableArray(T, (0, )) + +@doc """ +# Description + +Construct an empty `NullableMatrix` object by calling the name of the +fully parametrized type with zero arguments. + +# Args + +NONE + +# Returns + +* x::NullableMatrix{T}: An empty nullable matrix of the specified type. + +# Examples + +``` +x = NullableMatrix{Int64}() +``` +""" -> +Base.call{T}(::Type{NullableMatrix{T}}) = NullableArray(T, (0, 0)) + # ----- Constructor #5 -------------------------------------------------------# # The following method constructs a NullableArray from an Array{Any} argument # 'A' that contains some placeholder of type 'T' for null values. @@ -94,12 +207,3 @@ function NullableArray{T}(A::AbstractArray, end return res end - -#----- Constructor #7 --------------------------------------------------------# - -# The following method allows for the construction of zero-element -# NullableArrays by calling the parametrized type on zero arguments. -# TODO: add support for dimensions arguments? -function Base.call{T, N}(::Type{NullableArray{T, N}}) - NullableArray(T, ntuple(i->0, N)) -end diff --git a/src/typedefs.jl b/src/typedefs.jl index 99ad5a6..5c07848 100644 --- a/src/typedefs.jl +++ b/src/typedefs.jl @@ -1,22 +1,10 @@ -# === Design Notes === -# -# `NullableArray{T, N}` is a struct-of-arrays representation of -# `Array{Nullable{T}, N}`. This makes it easy to define complicated operations -# (e.g. matrix multiplication) by reusing the existing definition for -# `Array{T}`. -# -# One complication when defining functions that operate on the internal fields -# of a `NullableArray` is that developers must take care to ensure that they -# do not index into an undefined entry in the `values` field. This is not a -# problem for `isbits` types, which are never `#undef`, but will trigger -# an exception for any other type. -# -# TODO: Ensure that size(values) == size(isnull) using inner constructor. -# TODO: Implement outer constructor required once we add an inner constructor. @doc """ `NullableArray{T, N}` is an efficient alternative to `Array{Nullable{T}, N}`. -It allows users to easily define operations on arrays with null values by -reusing operations that only work on arrays without any null values. +It allows users to define operations on arrays with null values by reusing +operations that only work on arrays without any null values. We refer to +such reuse as "lifting" an operation from the domain of non-nullable values +to the domain of nullable values. Examples include lifting the definition of +matrix multiplication from non-nullable arrays to nullable arrays. """ -> immutable NullableArray{T, N} <: AbstractArray{Nullable{T}, N} values::Array{T, N} @@ -31,5 +19,12 @@ immutable NullableArray{T, N} <: AbstractArray{Nullable{T}, N} end end +@doc """ +`NullableVector{T}` is an alias for `NullableArray{T, 1}` +""" -> typealias NullableVector{T} NullableArray{T, 1} + +@doc """ +`NullableMatrix{T}` is an alias for `NullableArray{T, 2}` +""" -> typealias NullableMatrix{T} NullableArray{T, 2}