txt: ## nil.md
  class Nil
  
  Absence of a value or a benign failure
  
  ```raku
  class Nil is Cool { }
  ```
  
  The value `Nil` may be used to fill a spot where a value would normally go, and in so doing, explicitly indicate that no value is present. It may also be used as a cheaper and less explosive alternative to a [`Failure`](/type/Failure). (In fact, class [`Failure`](/type/Failure) is derived from `Nil`, so smartmatching `Nil` will also match [`Failure`](/type/Failure).)
  
  The class `Nil` is the same exact thing as its only possible value, `Nil`.
  
  ```raku
  say Nil === Nil.new;        # OUTPUT: «True␤»
  ```
  
  Along with [`Failure`](/type/Failure), `Nil` and its subclasses may always be returned from a routine even when the routine specifies a particular return type. It may also be returned regardless of the definedness of the return type, however, `Nil` is considered undefined for all other purposes.
  
  ```raku
  sub a( --> Int:D ) { return Nil }
  a().say;                    # OUTPUT: «Nil␤»
  ```
  
  `Nil` is what is returned from empty routines or closure, or routines that use a bare `return` statement.
  
  ```raku
  sub a { }; a().say;         # OUTPUT: «Nil␤»
  sub b { return }; b().say;  # OUTPUT: «Nil␤»
  say (if 1 { });             # OUTPUT: «Nil␤»
  { ; }().say;                # OUTPUT: «Nil␤»
  say EVAL "";                # OUTPUT: «Nil␤»
  ```
  
  In a list, `Nil` takes the space of one value. Iterating `Nil` behaves like iteration of any non-iterable value, producing a sequence of one `Nil`. (When you need the other meaning, the special value [Empty](/type/Slip#constant_Empty) is available to take no spaces when inserted into list, and to return no values when iterated.)
  
  ```raku
  (1, Nil, 3).elems.say;      # OUTPUT: «3␤»
  (for Nil { $_ }).raku.say;  # OUTPUT: «(Nil,)␤»
  ```
  
  Any method call on `Nil` of a method that does not exist, and consequently, any subscripting operation, will succeed and return `Nil`.
  
  ```raku
  say Nil.ITotallyJustMadeThisUp;  # OUTPUT: «Nil␤»
  say (Nil)[100];                  # OUTPUT: «Nil␤»
  say (Nil){100};                  # OUTPUT: «Nil␤»
  ```
  
  When assigned to a [container](/language/containers), the `Nil` value (but not any subclass of `Nil`) will attempt to revert the container to its default value; if no such default is declared, Raku assumes [`Any`](/type/Any).
  
  Since a hash assignment expects two elements, use `Empty` not `Nil`, e.g.
  
  ```raku
  my %h = 'a'..'b' Z=> 1..*;
  # stuff happens
  %h = Empty; # %h = Nil will generate an error
  ```
  
  However, if the container type is constrained with `:D`, assigning `Nil` to it will immediately throw an exception. (In contrast, an instantiated [`Failure`](/type/Failure) matches `:D` because it's a definite value, but will fail to match the actual nominal type unless it happens to be a parent class of [`Failure`](/type/Failure).) Native types can not have default values nor hold a type object. Assigning `Nil` to a native type container will fail with a runtime error.
  
  ```raku
  my Int $x = 42;
  $x = Nil;
  $x.say;                     # OUTPUT: «(Int)␤»
  
  sub f( --> Int:D ){ Nil };  # this definedness constraint is ignored
  my Int:D $i = f;            # this definedness constraint is not ignored, so throws
  CATCH { default { put .^name, ': ', .Str } };
  # OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $y; expected Int but got Any (Any)»
  
  sub g( --> Int:D ){ fail "oops" }; # this definedness constraint is ignored
  my Any:D $h = g;                   # failure object matches Any:D, so is assigned
  ```
  
  but
  
  ```raku
  my Int:D $j = g;
  # It will throw both exceptions:
  # Earlier failure:
  #  oops
  #   in sub g at <unknown file> line 1
  #   in block <unit> at <unknown file> line 1
  #
  # Final error:
  #  Type check failed in assignment to $j; expected Int:D but got Failure (Failure.new(exception...)
  #   in block <unit> at <unknown file> line 1
  
  ```
  
  Because an untyped variable is type [`Any`](/type/Any), assigning a `Nil` to one will result in an [(Any)](/type/Any) type object.
  
  ```raku
  my $x = Nil;
  $x.say;          # OUTPUT: «(Any)␤»
  my Int $y = $x;  # will throw an exception
  CATCH { default { put .^name, ': ', .Str } };
  # OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $y; expected Int but got Any (Any)␤»
  ```
  
  If you are looking for a variable which transforms objects into type objects when said variable appears on the right-hand side, you can type the container as `Nil`.
  
  ```raku
  my Nil $x;
  my Str $s = $x;
  $s.say;          # OUTPUT: «(Str)␤»
  ```
  
  There is an important exception to this transforms-into-type-object rule: assigning `Nil` to a variable which has a default will restore that default.
  
  ```raku
  my Int $x is default(42) = -1;
  my $y = 1;
  for $x, $y -> $val is rw { $val = Nil unless $val > 0 }
  $x.say;          # OUTPUT: «42␤»
  ```
  
  Methods such as `BIND-POS`, `ASSIGN-KEY`, `ASSIGN-POS` will die; `BIND-KEY` will produce a failure with an [`X::Bind`](/type/X/Bind) exception in it, and `STORE` will produce an [`X::Assignment::RO`](/type/X/Assignment/RO) exception.
  
  # [Methods](#class_Nil "go to top of document")[§](#Methods "direct link")
  
  ## [method append](#class_Nil "go to top of document")[§](#method_append "direct link")
  
  ```raku
  method append(*@)
  ```
  
  Warns the user that they tried to append onto a `Nil` (or derived type object).
  
  ## [method gist](#class_Nil "go to top of document")[§](#method_gist "direct link")
  
  ```raku
  method gist(--> Str:D)
  ```
  
  Returns `"Nil"`.
  
  ## [method Str](#class_Nil "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  method Str()
  ```
  
  Warns the user that they tried to stringify a `Nil`.
  
  ## [method new](#class_Nil "go to top of document")[§](#method_new "direct link")
  
  ```raku
  method new(*@)
  ```
  
  Returns `Nil`
  
  ## [method prepend](#class_Nil "go to top of document")[§](#method_prepend "direct link")
  
  ```raku
  method prepend(*@)
  ```
  
  Warns the user that they tried to prepend onto a `Nil` or derived type object.
  
  ## [method push](#class_Nil "go to top of document")[§](#method_push "direct link")
  
  ```raku
  method push(*@)
  ```
  
  Warns the user that they tried to push onto a `Nil` or derived type object.
  
  ## [method unshift](#class_Nil "go to top of document")[§](#method_unshift "direct link")
  
  ```raku
  method unshift(*@)
  ```
  
  Warns the user that they tried to unshift onto a `Nil` or derived type object.
  
  ## [method ords](#class_Nil "go to top of document")[§](#method_ords "direct link")
  
  Returns an empty [`Seq`](/type/Seq), but will also issue a warning depending on the context it's used (for instance, a warning about using it in string context if used with `say`).
  
  ## [method chrs](#class_Nil "go to top of document")[§](#method_chrs "direct link")
  
  Will return `\0`, and also throw a warning.
  
  ## [method FALLBACK](#class_Nil "go to top of document")[§](#method_FALLBACK "direct link")
  
  ```raku
  method FALLBACK(| --> Nil) {}
  ```
  
  The [fallback method](/language/typesystem#index-entry-FALLBACK_(method)) takes any arguments and always returns a `Nil`.
  
  ## [method Numeric](#class_Nil "go to top of document")[§](#method_Numeric "direct link")
  
  ```raku
  method Numeric()
  ```
  
  Warns the user that they tried to numify a `Nil`.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Nil`
  
  
  
  raku-type-graph
  
  
  
  Nil
  Nil
  
  
  Cool
  Cool
  
  
  Nil->Cool
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  Cool->Any
  
  
  
  Failure
  Failure
  
  
  Failure->Nil
  
  [Expand chart above](/assets/typegraphs/Nil.svg)
  