From 9b6e46f28fcb4476b7026bcb124283200dbb21b4 Mon Sep 17 00:00:00 2001 From: "Viral B. Shah" Date: Thu, 23 Oct 2014 13:20:42 +0530 Subject: [PATCH] Merge Nullable types into the Types section of the manual. --- doc/index.rst | 1 - doc/manual/index.rst | 1 - doc/manual/nullable-types.rst | 102 ---------------------------------- doc/manual/types.rst | 100 +++++++++++++++++++++++++++++++++ 4 files changed, 100 insertions(+), 104 deletions(-) delete mode 100644 doc/manual/nullable-types.rst diff --git a/doc/index.rst b/doc/index.rst index 5d21854e3229c..7f4dda63fc6c0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -37,7 +37,6 @@ manual/networking-and-streams manual/parallel-computing manual/dates - manual/nullable-types manual/running-external-programs manual/calling-c-and-fortran-code manual/interacting-with-julia diff --git a/doc/manual/index.rst b/doc/manual/index.rst index 8ad135934ee2b..c9bab766f6b90 100644 --- a/doc/manual/index.rst +++ b/doc/manual/index.rst @@ -29,7 +29,6 @@ networking-and-streams parallel-computing dates - nullable-types interacting-with-julia running-external-programs calling-c-and-fortran-code diff --git a/doc/manual/nullable-types.rst b/doc/manual/nullable-types.rst deleted file mode 100644 index e789253047283..0000000000000 --- a/doc/manual/nullable-types.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. _man-nullable-types: - -******************************************* -Nullable Types: Representing Missing Values -******************************************* - -In many settings, you need to interact with a value of type ``T`` that may or -may not exist. To handle these settings, Julia provides a parametric type -called ``Nullable{T}``, which can be thought of as a specialized container -type that can contain either zero or one values. ``Nullable{T}`` provides a -minimal interface designed to ensure that interactions with missing values -are safe. At present, the interface consists of four possible interactions: - -- Construct a ``Nullable`` object. -- Check if an ``Nullable`` object has a missing value. -- Access the value of a ``Nullable`` object with a guarantee that a - ``NullException`` will be thrown if the object's value is missing. -- Access the value of a ``Nullable`` object with a guarantee that a default - value of type ``T`` will be returned if the object's value is missing. - -Constructing ``Nullable`` objects ---------------------------------- - -To construct an object representing a missing value of type ``T``, use the -``Nullable{T}()`` function: - -.. doctest:: - - julia> x1 = Nullable{Int}() - julia> x2 = Nullable{Float64}() - julia> x3 = Nullable{Vector{Int}}() - -To construct an object representing a non-missing value of type ``T``, use the -``Nullable(x::T)`` function: - -.. doctest:: - - julia> x1 = Nullable(1) - Nullable(1) - - julia> x2 = Nullable(1.0) - Nullable(1.0) - - julia> x3 = Nullable([1, 2, 3]) - Nullable([1, 2, 3]) - -Note the core distinction between these two ways of constructing a ``Nullable`` -object: in one style, you provide a type, ``T``, as a function parameter; in -the other style, you provide a single value of type ``T`` as an argument. - -Checking if an ``Nullable`` object has a value ----------------------------------------------- - -You can check if a ``Nullable`` object has any value using the ``isnull`` -function: - -.. doctest:: - - julia> isnull(Nullable{Float64}()) - true - - julia> isnull(Nullable(0.0)) - false - -Safely accessing the value of an ``Nullable`` object ----------------------------------------------------- - -You can safely access the value of an ``Nullable`` object using the ``get`` -function: - -.. doctest:: - - julia> get(Nullable{Float64}()) - ERROR: NullException() - in get at nullable.jl:26 - - julia> get(Nullable(1.0)) - 1.0 - -If the value is not present, as it would be for ``Nullable{Float64}``, a -``NullException`` error will be thrown. The error-throwing nature of the -``get`` function ensures that any attempt to access a missing value immediately -fails. - -In cases for which a reasonable default value exists that could be used -when a ``Nullable`` object's value turns out to be missing, you can provide this -default value as a second argument to ``get``: - -.. doctest:: - - julia> get(Nullable{Float64}(), 0) - 0.0 - - julia> get(Nullable(1.0), 0) - 1.0 - -Note that this default value will automatically be converted to the type of -the ``Nullable`` object that you attempt to access using the ``get`` function. -For example, in the code shown above the value ``0`` would be automatically -converted to a ``Float64`` value before being returned. The presence of default -replacement values makes it easy to use the ``get`` function to write -type-stable code that interacts with sources of potentially missing values. diff --git a/doc/manual/types.rst b/doc/manual/types.rst index b6a101366e4e3..e9f3062ffd4a0 100644 --- a/doc/manual/types.rst +++ b/doc/manual/types.rst @@ -1229,3 +1229,103 @@ If you apply ``super`` to other type objects (or non-type objects), a julia> super((Float64,Int64)) ERROR: `super` has no method matching super(::Type{(Float64,Int64)}) + +Nullable Types: Representing Missing Values +------------------------------------------- + +In many settings, you need to interact with a value of type ``T`` that may or +may not exist. To handle these settings, Julia provides a parametric type +called ``Nullable{T}``, which can be thought of as a specialized container +type that can contain either zero or one values. ``Nullable{T}`` provides a +minimal interface designed to ensure that interactions with missing values +are safe. At present, the interface consists of four possible interactions: + +- Construct a ``Nullable`` object. +- Check if an ``Nullable`` object has a missing value. +- Access the value of a ``Nullable`` object with a guarantee that a + ``NullException`` will be thrown if the object's value is missing. +- Access the value of a ``Nullable`` object with a guarantee that a default + value of type ``T`` will be returned if the object's value is missing. + +Constructing ``Nullable`` objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To construct an object representing a missing value of type ``T``, use the +``Nullable{T}()`` function: + +.. doctest:: + + julia> x1 = Nullable{Int}() + julia> x2 = Nullable{Float64}() + julia> x3 = Nullable{Vector{Int}}() + +To construct an object representing a non-missing value of type ``T``, use the +``Nullable(x::T)`` function: + +.. doctest:: + + julia> x1 = Nullable(1) + Nullable(1) + + julia> x2 = Nullable(1.0) + Nullable(1.0) + + julia> x3 = Nullable([1, 2, 3]) + Nullable([1, 2, 3]) + +Note the core distinction between these two ways of constructing a ``Nullable`` +object: in one style, you provide a type, ``T``, as a function parameter; in +the other style, you provide a single value of type ``T`` as an argument. + +Checking if an ``Nullable`` object has a value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can check if a ``Nullable`` object has any value using the ``isnull`` +function: + +.. doctest:: + + julia> isnull(Nullable{Float64}()) + true + + julia> isnull(Nullable(0.0)) + false + +Safely accessing the value of an ``Nullable`` object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can safely access the value of an ``Nullable`` object using the ``get`` +function: + +.. doctest:: + + julia> get(Nullable{Float64}()) + ERROR: NullException() + in get at nullable.jl:26 + + julia> get(Nullable(1.0)) + 1.0 + +If the value is not present, as it would be for ``Nullable{Float64}``, a +``NullException`` error will be thrown. The error-throwing nature of the +``get`` function ensures that any attempt to access a missing value immediately +fails. + +In cases for which a reasonable default value exists that could be used +when a ``Nullable`` object's value turns out to be missing, you can provide this +default value as a second argument to ``get``: + +.. doctest:: + + julia> get(Nullable{Float64}(), 0) + 0.0 + + julia> get(Nullable(1.0), 0) + 1.0 + +Note that this default value will automatically be converted to the type of +the ``Nullable`` object that you attempt to access using the ``get`` function. +For example, in the code shown above the value ``0`` would be automatically +converted to a ``Float64`` value before being returned. The presence of default +replacement values makes it easy to use the ``get`` function to write +type-stable code that interacts with sources of potentially missing values.