update the documentation about the new strings/seqs behaviours

doc/manual.rst

@@ -1471,7 +1471,7 @@ mysterious crashes.
 
 **Note**: The example only works because the memory is initialized to zero
 (``alloc0`` instead of ``alloc`` does this): ``d.s`` is thus initialized to
-``nil`` which the string assignment can handle. One needs to know low level
+binary zero which the string assignment can handle. One needs to know low level
 details like this when mixing garbage collected data with unmanaged memory.
 
 .. XXX finalizers for traced objects
@@ -2512,8 +2512,8 @@ char                            '\\0'
 bool                            false
 ref or pointer type             nil
 procedural type                 nil
-sequence                        nil (*not* ``@[]``)
+sequence                        ``@[]``
-string                          nil (*not* "")
+string                          ``""``
 tuple[x: A, y: B, ...]          (default(A), default(B), ...)
                                 (analogous for objects)
 array[0..., T]                  [default(T), ...]
@@ -4270,7 +4270,7 @@ therefore very useful for type specialization within generic code:
     Table[Key, Value] = object
       keys: seq[Key]
       values: seq[Value]
-      when not (Key is string): # nil value for strings used for optimization
+      when not (Key is string): # empty value for strings used for optimization
         deletedKeys: seq[bool]
 
 
@@ -7434,8 +7434,8 @@ code generation directly, but their presence can be detected by macros.
 Custom pragmas are defined using templates annotated with pragma ``pragma``:
 
 .. code-block:: nim
-  template dbTable(name: string, table_space: string = nil) {.pragma.}
+  template dbTable(name: string, table_space: string = "") {.pragma.}
-  template dbKey(name: string = nil, primary_key: bool = false) {.pragma.}
+  template dbKey(name: string = "", primary_key: bool = false) {.pragma.}
   template dbForeignKey(t: typedesc) {.pragma.}
   template dbIgnore {.pragma.}
 

doc/tut1.rst

@@ -960,11 +960,7 @@ enforced. For example, when reading strings from binary files, they are merely
 a sequence of bytes. The index operation ``s[i]`` means the i-th *char* of
 ``s``, not the i-th *unichar*.
 
-String variables are initialized with a special value, called ``nil``. However,
+String variables are initialized with the empty strings ``""``.
-most string operations cannot deal with ``nil`` (leading to an exception being
-raised) for performance reasons. It is best to use empty strings ``""``
-rather than ``nil`` as the *empty* value. But ``""`` often creates a string
-object on the heap, so there is a trade-off to be made here.
 
 
 Integers
@@ -1309,11 +1305,7 @@ Example:
     x: seq[int] # a reference to a sequence of integers
   x = @[1, 2, 3, 4, 5, 6] # the @ turns the array into a sequence allocated on the heap
 
-Sequence variables are initialized with ``nil``. However, most sequence
+Sequence variables are initialized with ``@[]``.
-operations cannot deal with ``nil`` (leading to an exception being
-raised) for performance reasons. Thus one should use empty sequences ``@[]``
-rather than ``nil`` as the *empty* value. But ``@[]`` creates a sequence
-object on the heap, so there is a trade-off to be made here.
 
 The ``for`` statement can be used with one or two variables when used with a
 sequence. When you use the one variable form, the variable will hold the value
@@ -1355,11 +1347,9 @@ type does not matter.
 .. code-block:: nim
     :test: "nim c $1"
   var
-    fruits:   seq[string]       # reference to a sequence of strings that is initialized with 'nil'
+    fruits:   seq[string]       # reference to a sequence of strings that is initialized with '@[]'
     capitals: array[3, string]  # array of strings with a fixed size
 
-  fruits = @[]                  # creates an empty sequence on the heap that will be referenced by 'fruits'
-
   capitals = ["New York", "London", "Berlin"]   # array 'capitals' allows assignment of only three elements
   fruits.add("Banana")          # sequence 'fruits' is dynamically expandable during runtime
   fruits.add("Mango")
@@ -1691,7 +1681,7 @@ rules apply:
   write(stdout, x(3))   # no error: A.x is called
   write(stdout, x(""))  # no error: B.x is called
 
-  proc x*(a: int): string = nil
+  proc x*(a: int): string = discard
   write(stdout, x(3))   # ambiguous: which `x` is to call?