Merge pull request #1941 from JinShil/deprecate_delete

Fix Issue 9433 - Deprecate delete

Author: wilzbach

deprecate.dd

@@ -15,7 +15,7 @@ $(SPEC_S Deprecated Features,
         $(TROW $(DEPLINK Implicit comparison of different enums),                 2.075,  2.075,  ,  )
         $(TROW $(DEPLINK Implicit string concatenation),                          2.072,  2.072,  ,  )
         $(TROW $(DEPLINK Using the result of a comma expression),                 2.072,  2.072,  2.079,  )
-        $(TROW $(DEPLINK delete),                                                 future,  ,  ,  )
+        $(TROW $(DEPLINK delete),                                                  ,  2.079,  ,  )
         $(TROW $(DEPLINK scope for allocating classes on the stack),              future,  ,  ,  )
         $(TROW $(DEPLINK Imaginary and complex types),                            future,  ,  ,  )
         $(TROW $(DEPLINK Implicit catch statement),                               2.072, 2.072,  future, future )

spec/class.dd

@@ -632,11 +632,10 @@ $(GNAME Destructor):
         object.
         )
 
-        $(P The  program can explicitly inform the garbage collector that an
-        object is no longer referred to (with the delete expression), and
-        then the garbage collector calls the destructor
-        immediately, and adds the object's memory to the free storage.
-        The destructor is guaranteed to never be called twice.
+        $(P The program can explicitly inform the garbage collector that an
+        object is no longer referred to with $(REF1 destroy, object), and
+        then the garbage collector calls the destructor immediately.  The
+        destructor is guaranteed to never be called twice.
         )
 
         $(P The destructor for the super class automatically gets called when
@@ -654,8 +653,8 @@ $(GNAME Destructor):
         members that are references to garbage collected objects, those
         references may no longer be valid. This means that destructors
         cannot reference sub objects.
-        This rule does not apply to auto objects or objects deleted
-        with the $(I DeleteExpression), as the destructor is not being run
+        This rule does not apply to auto objects or objects destructed
+        with $(REF1 destroy, object), as the destructor is not being run
         by the garbage collector, meaning all references are valid.
         )
 

spec/expression.dd

@@ -732,6 +732,9 @@ $(GRAMMAR
 $(GNAME DeleteExpression):
     $(D delete) $(GLINK UnaryExpression)
 )
+    $(P NOTE: `delete` has been deprecated.  Instead, please use $(REF1 destroy, object)
+    if feasible, or $(REF __delete, core, memory) as a last resort.)
+
     $(P If the $(I UnaryExpression) is a class object reference, and
         there is a destructor for that class, the destructor
         is called for that object instance.

spec/function.dd

@@ -2395,7 +2395,6 @@ $(H2 $(LNAME2 nogc-functions, No-GC Functions))
         $(LI $(DDSUBLINK expression, IndexExpression, indexing) an associative array
             (because it may throw $(D RangeError) if the specified key is not present))
         $(LI $(DDSUBLINK expression, NewExpression, allocating an object) on the heap)
-        $(LI $(DDSUBLINK expression, DeleteExpression, deleting an object) on the heap)
         )
 
             ---
@@ -2410,7 +2409,6 @@ $(H2 $(LNAME2 nogc-functions, No-GC Functions))
                 aa["abc"];         // error, indexing may allocate and throws
 
                 auto p = new int;  // error, operator new allocates
-                delete p;          // error, operator delete deallocates
             }
             ---
 

spec/interface.dd

@@ -240,7 +240,7 @@ $(SECTION2 $(LEGACY_LNAME2 COM-Interfaces, com-interfaces, COM Interfaces),
 
     $(UL
     $(LI It derives from the interface $(D core.stdc.windows.com.IUnknown).)
-    $(LI It cannot be the argument of a $(I DeleteExpression).)
+    $(LI It cannot be the argument to $(REF1 destroy, object).)
     $(LI References cannot be upcast to the enclosing class object, nor
     can they be downcast to a derived interface. To accomplish this,
     an appropriate $(D QueryInterface()) would have to be implemented
@@ -328,7 +328,7 @@ class Ifoo
     )
 
     $(UL
-    $(LI It cannot be the argument of a $(I DeleteExpression).)
+    $(LI It cannot be the argument to $(REF1 destroy, object).)
     $(LI References cannot be upcast to the enclosing class object, nor
     can they be downcast to a derived interface.)
     $(LI The C++ calling convention is the default convention