Document how to create an undefined reference (Ref) and detect that using isassigned (#35723)

* Document how to create a Ref to undef and how to detect is a Ref refers
to undef

* Document Ref{T}() behavior when T is a primitve bit type.

* Change primitive to bitstype, isdefined to isassigned, doc isassigned

* Document isassigned(::RefValue). Remove no invalid Ref language.

* Remove duplicate isassigned docs for arrays in essentials.jl

* Refer to undefined reference rather than undef for isassigned

* isassigned reference docs, fix line returns in doc

* Fix line returns for isassigned(RefValue) doc

* Add backticks to quote code as suggested by @rfourquet

Co-authored-by: Rafael Fourquet <fourquet.rafael@gmail.com>

* Change `undef` to undefined, fix examples

Change `undef` to undefined reference

Add comments to examples
Remove C_NULL example due to confusion
List normal `Ref` usage first

* Create a markdown header for examples

* Clarify that error when attempting to deference

Clarify that the act of dereferencing causes the error to be thrown. @rfourquet

* Remove undefined Ref bitstype comparison

Comparison of an undefined reference value bitstype to zero may be true. Insert a semicolon just to demonstrate usage but not the result.

Co-authored-by: Rafael Fourquet <fourquet.rafael@gmail.com>

Author: mkitti

base/refpointer.jl

@@ -13,21 +13,52 @@ Creation of a `Ref` to a value `x` of type `T` is usually written `Ref(x)`.
 Additionally, for creating interior pointers to containers (such as Array or Ptr),
 it can be written `Ref(a, i)` for creating a reference to the `i`-th element of `a`.
 
-When passed as a `ccall` argument (either as a `Ptr` or `Ref` type), a `Ref` object will be
-converted to a native pointer to the data it references.
+`Ref{T}()` creates a reference to a value of type `T` without initialization.
+For a bitstype `T`, the value will be whatever currently resides in the memory
+allocated. For a non-bitstype `T`, the reference will be undefined and attempting to
+dereference it will result in an error, "UndefRefError: access to undefined reference".
 
-There is no invalid (NULL) `Ref` in Julia, but a `C_NULL` instance of `Ptr` can be passed to
-a `ccall` Ref argument.
+To check if a `Ref` is an undefined reference, use [`isassigned(ref::RefValue)`](@ref).
+For example, `isassigned(Ref{T}())` is `false` if `T` is not a bitstype.
+If `T` is a bitstype, `isassigned(Ref{T}())` will always be true.
+
+When passed as a `ccall` argument (either as a `Ptr` or `Ref` type), a `Ref`
+object will be converted to a native pointer to the data it references.
+
+A `C_NULL` instance of `Ptr` can be passed to a `ccall` `Ref` argument to initialize it.
 
 # Use in broadcasting
-`Ref` is sometimes used in broadcasting in order to treat the referenced values as a scalar:
+`Ref` is sometimes used in broadcasting in order to treat the referenced values as a scalar.
+
+# Examples
 
 ```jldoctest
-julia> isa.(Ref([1,2,3]), [Array, Dict, Int])
+julia> Ref(5)
+Base.RefValue{Int64}(5)
+
+julia> isa.(Ref([1,2,3]), [Array, Dict, Int]) # Treat reference values as scalar during broadcasting
 3-element BitVector:
  1
  0
  0
+
+julia> Ref{Function}()  # Undefined reference to a non-bitstype, Function
+Base.RefValue{Function}(#undef)
+
+julia> try
+           Ref{Function}()[] # Dereferencing an undefined reference will result in an error
+       catch e
+           println(e)
+       end
+UndefRefError()
+
+julia> Ref{Int64}()[]; # A reference to a bitstype refers to an undetermined value if not given
+
+julia> isassigned(Ref{Int64}()) # A reference to a bitstype is always assigned
+true
+
+julia> Ref{Int64}(0)[] == 0 # Explicitly give a value for a bitstype reference
+true
 ```
 """
 Ref

base/refvalue.jl

@@ -8,6 +8,31 @@ mutable struct RefValue{T} <: Ref{T}
     RefValue{T}(x) where {T} = new(x)
 end
 RefValue(x::T) where {T} = RefValue{T}(x)
+"""
+    isassigned(ref::RefValue) -> Bool
+
+Test whether the given [`Ref`](@ref) is associated with a value.
+This is always true for a [`Ref`](@ref) of a bitstype object.
+Return `false` if the reference is undefined.
+
+# Examples
+```jldoctest
+julia> ref = Ref{Function}()
+Base.RefValue{Function}(#undef)
+
+julia> isassigned(ref)
+false
+
+julia> ref[] = (foobar(x) = x)
+foobar (generic function with 1 method)
+
+julia> isassigned(ref)
+true
+
+julia> isassigned(Ref{Int}())
+true
+```
+"""
 isassigned(x::RefValue) = isdefined(x, :x)
 
 function unsafe_convert(P::Type{Ptr{T}}, b::RefValue{T}) where T

doc/src/base/c.md

@@ -24,6 +24,7 @@ Base.systemerror
 Base.windowserror
 Core.Ptr
 Core.Ref
+Base.isassigned(::Base.RefValue)
 Base.Cchar
 Base.Cuchar
 Base.Cshort