Skip to content

Commit

Permalink
remove some links to Nullable and methods (#19961)
Browse files Browse the repository at this point in the history
* remove some links to Nullable and methods

I find it distracting that every word `Nullable` and every method associated is a link.
The link should appear only the first time the new method is mentioned.

* remove links to Nullable, included comments

* remove links to Nullable

comment about broadcast on `Nullable`
  • Loading branch information
mzaffalon authored and tkelman committed Jan 18, 2017
1 parent 1659b8c commit b8971ea
Showing 1 changed file with 35 additions and 40 deletions.
75 changes: 35 additions & 40 deletions doc/src/manual/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -1242,25 +1242,23 @@ about the proper (and improper) uses of `Val`, please read the more extensive di
## [Nullable Types: Representing Missing Values](@id man-nullable-types)

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
handle these settings, Julia provides a parametric type called [`Nullable{T}`](@ref), 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 several possible interactions:

* Construct a [`Nullable`](@ref) object.
* Check if a [`Nullable`](@ref) object has a missing value.
* Access the value of a [`Nullable`](@ref) object with a guarantee that a [`NullException`](@ref)
* Construct a `Nullable` object.
* Check if a `Nullable` object has a missing value.
* Access the value of a `Nullable` object with a guarantee that a [`NullException`](@ref)
will be thrown if the object's value is missing.
* Access the value of a [`Nullable`](@ref) object with a guarantee that a default value of type
* 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.
* Perform an operation on the value (if it exists) of a [`Nullable`](@ref)
object, getting a [`Nullable`](@ref) result. The result will be missing
if the original value was missing.
* Performing a test on the value (if it exists) of a [`Nullable`](@ref)
object, getting a result that is missing if either the [`Nullable`](@ref)
* Perform an operation on the value (if it exists) of a `Nullable` object, getting a
`Nullable` result. The result will be missing if the original value was missing.
* Performing a test on the value (if it exists) of a `Nullable`
object, getting a result that is missing if either the `Nullable`
itself was missing, or the test failed.
* Perform general operations on single or multiple [`Nullable`](@ref)
objects, propagating the missing data.
* Perform general operations on single `Nullable` objects, propagating the missing data.

### Constructing [`Nullable`](@ref) objects

Expand Down Expand Up @@ -1291,13 +1289,13 @@ julia> x3 = Nullable([1, 2, 3])
Nullable{Array{Int64,1}}([1,2,3])
```

Note the core distinction between these two ways of constructing a [`Nullable`](@ref) object:
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 a [`Nullable`](@ref) object has a value
### Checking if a `Nullable` object has a value

You can check if a [`Nullable`](@ref) object has any value using [`isnull()`](@ref):
You can check if a `Nullable` object has any value using [`isnull()`](@ref):

```julia
julia> isnull(Nullable{Float64}())
Expand All @@ -1307,9 +1305,9 @@ julia> isnull(Nullable(0.0))
false
```

### Safely accessing the value of a [`Nullable`](@ref) object
### Safely accessing the value of a `Nullable` object

You can safely access the value of a [`Nullable`](@ref) object using [`get()`](@ref):
You can safely access the value of a `Nullable` object using [`get()`](@ref):

```julia
julia> get(Nullable{Float64}())
Expand All @@ -1322,12 +1320,12 @@ julia> get(Nullable(1.0))
```

If the value is not present, as it would be for `Nullable{Float64}`, a [`NullException`](@ref)
error will be thrown. The error-throwing nature of the [`get()`](@ref) function ensures that any
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`](@ref)
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()`](@ref):
to `get()`:

```julia
julia> get(Nullable{Float64}(), 0.0)
Expand All @@ -1338,46 +1336,43 @@ julia> get(Nullable(1.0), 0.0)
```

!!! tip
Make sure the type of the default value passed to [`get()`](@ref) and that of the [`Nullable`](@ref)
Make sure the type of the default value passed to `get()` and that of the `Nullable`
object match to avoid type instability, which could hurt performance. Use [`convert()`](@ref)
manually if needed.

### Performing operations on [`Nullable`](@ref) objects
### Performing operations on `Nullable` objects

[`Nullable`](@ref) objects represent values that are possibly missing, and it
`Nullable` objects represent values that are possibly missing, and it
is possible to write all code using these objects by first testing to see if
the value is missing with [`isnull()`](@ref), and then doing an appropriate
action. However, there are some common use cases where the code could be more
concise or clear by using a higher-order function.

The [`map`](@ref) function takes as arguments a function `f` and a
[`Nullable`](@ref) value `x`. It produces a [`Nullable`](@ref):
The [`map`](@ref) function takes as arguments a function `f` and a `Nullable` value
`x`. It produces a `Nullable`:

- If `x` is a missing value, then it produces a missing value;
- If `x` has a value, then it produces a [`Nullable`](@ref) containing
- If `x` has a value, then it produces a `Nullable` containing
`f(get(x))` as value.

This is useful for performing simple operations on values that might be missing
if the desired behaviour is to simply propagate the missing values forward.

The [`filter`](@ref) function takes as arguments a predicate function `p`
(that is, a function returning a boolean) and a [`Nullable`](@ref) value `x`.
It produces a [`Nullable`](@ref) value:
(that is, a function returning a boolean) and a `Nullable` value `x`.
It produces a `Nullable` value:

- If `x` is a missing value, then it produces a missing value;
- If `p(get(x))` is true, then it produces the original value `x`;
- If `p(get(x))` is false, then it produces a missing value.

In this way, [`filter`](@ref) can be thought of as selecting only allowable
In this way, `filter` can be thought of as selecting only allowable
values, and converting non-allowable values to missing values.

While [`map`](@ref) and [`filter`](@ref) are useful in specific cases, by far
the most useful higher-order function is [`broadcast`](@ref), which can handle
a wide variety of cases.

[`broadcast`](@ref) can be thought of as a way to make existing operations work
on multiple data simultaneously and propagate nulls. An example will motivate
the need for [`broadcast`](@ref). Suppose we have a function that computes the
While `map` and `filter` are useful in specific cases, by far the most useful
higher-order function is [`broadcast`](@ref), which can handle a wide variety of cases,
including making existing operations work and propagate `Nullable`s. An example
will motivate the need for `broadcast`. Suppose we have a function that computes the
greater of two real roots of a quadratic equation, using the quadratic formula:

```julia
Expand All @@ -1400,7 +1395,7 @@ example, we will assume that the best solution is to propagate the missing
values forward; that is, if any input is missing, we simply produce a missing
output.

The [`broadcast()`](@ref) function makes this task easy; we can simply pass the
The `broadcast()` function makes this task easy; we can simply pass the
`root` function we wrote to `broadcast`:

```julia
Expand All @@ -1415,17 +1410,17 @@ Nullable{Float64}()
```

If one or more of the inputs is missing, then the output of
[`broadcast()`](@ref) will be missing.
`broadcast()` will be missing.

There exists special syntactic sugar for the [`broadcast()`](@ref) function
There exists special syntactic sugar for the `broadcast()` function
using a dot notation:

```julia
julia> root.(Nullable(1), Nullable(-9), Nullable(20))
Nullable{Float64}(5.0)
```

In particular, the regular arithmetic operators can be [`broadcast()`](@ref)
In particular, the regular arithmetic operators can be `broadcast()`
conveniently using `.`-prefixed operators:

```julia
Expand Down

0 comments on commit b8971ea

Please sign in to comment.