From b8971ea4fd1e75a6946674d696c8b64bdd4b4f07 Mon Sep 17 00:00:00 2001 From: Michele Zaffalon Date: Wed, 18 Jan 2017 06:52:38 +0100 Subject: [PATCH] remove some links to Nullable and methods (#19961) * 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` --- doc/src/manual/types.md | 75 +++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 40 deletions(-) diff --git a/doc/src/manual/types.md b/doc/src/manual/types.md index 45b88ccaafbd3..6887bdd2e737b 100644 --- a/doc/src/manual/types.md +++ b/doc/src/manual/types.md @@ -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 @@ -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}()) @@ -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}()) @@ -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) @@ -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 @@ -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 @@ -1415,9 +1410,9 @@ 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 @@ -1425,7 +1420,7 @@ 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