Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: move not nil to the experimental page #14027

Merged
merged 1 commit into from
Apr 21, 2020
Merged

docs: move not nil to the experimental page #14027

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 0 additions & 26 deletions doc/manual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1838,32 +1838,6 @@ details like this when mixing garbage collected data with unmanaged memory.
.. XXX finalizers for traced objects


Not nil annotation
------------------

All types for which ``nil`` is a valid value can be annotated to
exclude ``nil`` as a valid value with the ``not nil`` annotation:

.. code-block:: nim
type
PObject = ref TObj not nil
TProc = (proc (x, y: int)) not nil

proc p(x: PObject) =
echo "not nil"

# compiler catches this:
p(nil)

# and also this:
var x: PObject
p(x)

The compiler ensures that every code path initializes variables which contain
non nilable pointers. The details of this analysis are still to be specified
here.


Procedural type
---------------
A procedural type is internally a pointer to a procedure. ``nil`` is
Expand Down
30 changes: 30 additions & 0 deletions doc/manual_experimental.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,36 @@ This operator will be matched against assignments to missing fields.
a.b = c # becomes `.=`(a, b, c)


Not nil annotation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this changed markup in a ReStructured Text editor and it looked mostly good, but I couldn’t confirm that the .. code-block:: nim will render correctly since that’s a custom block type defined by this project.

nim rst2html foo.rst or for whole docs you can ./koch docs

==================

**Note:** This is an experimental feature. It can be enabled with
``{.experimental: "notnil"}``.

All types for which ``nil`` is a valid value can be annotated with the ``not
nil`` annotation to exclude ``nil`` as a valid value:

.. code-block:: nim
{.experimental: "notnil"}

type
PObject = ref TObj not nil
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add TObj = object (basically make sure it compiles )

TProc = (proc (x, y: int)) not nil

proc p(x: PObject) =
echo "not nil"

# compiler catches this:
p(nil)

# and also this:
var x: PObject
p(x)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

except it doesn't.... so I'd reword for honesty as:

# and also this:
=>
# but not yet this:

when true:
  {.experimental: "notnil"}

  type
    TObj = object
    PObject = ref TObj not nil
    TProc = (proc (x, y: int)) not nil

  proc p(x: PObject) =
    echo "not nil"
    echo x == nil

  # compiler catches this:
  # p(nil)

  # and also this:
  var x: PObject
  p(x)

prints:

not nil
true

maybe you could pull up some other compelling example from #13808 /cc @zah


The compiler ensures that every code path initializes variables which contain
non-nilable pointers. The details of this analysis are still to be specified
here.


Concepts
========
Expand Down