Skip to content

Commit a78ee8a

Browse files
authored
Call {.cursor.} a pragma. (nim-lang#19116)
* Call {.cursor.} a pragma. Its hard to find .curser annotation while googling because all other things like it are called pragmas. See https://nim-lang.org/docs/manual.html#pragmas Also the . in front of the name makes it hard to find and search for. Can we just call it cursor pragma? * Small fix for comment.
1 parent 15157d0 commit a78ee8a

File tree

1 file changed

+8
-8
lines changed

1 file changed

+8
-8
lines changed

doc/destructors.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -555,14 +555,14 @@ for expressions of type `lent T` or of type `var T`.
555555
echo t[0] # accessor does not copy the element!
556556
557557
558-
The .cursor annotation
559-
======================
558+
The cursor pragma
559+
=================
560560

561561
Under the `--gc:arc|orc`:option: modes Nim's `ref` type is implemented
562562
via the same runtime "hooks" and thus via reference counting.
563563
This means that cyclic structures cannot be freed
564564
immediately (`--gc:orc`:option: ships with a cycle collector).
565-
With the `.cursor` annotation one can break up cycles declaratively:
565+
With the `cursor` pragma one can break up cycles declaratively:
566566

567567
.. code-block:: nim
568568
@@ -575,7 +575,7 @@ But please notice that this is not C++'s weak_ptr, it means the right field is n
575575
involved in the reference counting, it is a raw pointer without runtime checks.
576576

577577
Automatic reference counting also has the disadvantage that it introduces overhead
578-
when iterating over linked structures. The `.cursor` annotation can also be used
578+
when iterating over linked structures. The `cursor` pragma can also be used
579579
to avoid this overhead:
580580

581581
.. code-block:: nim
@@ -586,18 +586,18 @@ to avoid this overhead:
586586
it = it.next
587587
588588
589-
In fact, `.cursor` more generally prevents object construction/destruction pairs
589+
In fact, `cursor` more generally prevents object construction/destruction pairs
590590
and so can also be useful in other contexts. The alternative solution would be to
591591
use raw pointers (`ptr`) instead which is more cumbersome and also more dangerous
592-
for Nim's evolution: Later on, the compiler can try to prove `.cursor` annotations
592+
for Nim's evolution: Later on, the compiler can try to prove `cursor` pragmas
593593
to be safe, but for `ptr` the compiler has to remain silent about possible
594594
problems.
595595

596596

597597
Cursor inference / copy elision
598598
===============================
599599

600-
The current implementation also performs `.cursor` inference. Cursor inference is
600+
The current implementation also performs `cursor` inference. Cursor inference is
601601
a form of copy elision.
602602

603603
To see how and when we can do that, think about this question: In `dest = src` when
@@ -612,7 +612,7 @@ indirections:
612612
.. code-block:: nim
613613
614614
proc main(tab: Table[string, string]) =
615-
let v = tab["key"] # inferred as .cursor because 'tab' is not mutated.
615+
let v = tab["key"] # inferred as cursor because 'tab' is not mutated.
616616
# no copy into 'v', no destruction of 'v'.
617617
use(v)
618618
useItAgain(v)

0 commit comments

Comments
 (0)