deprecate.dd

Ddoc

$(SPEC_S Deprecated Features,

	$(P Sometimes it becomes clear that a feature is just a bad idea.
	These are called $(I deprecated features) and once they are judged
	to merit removal from the language, they follow a procedure in
	order to allow plenty of time for users to adjust to the change.
	)

	$(TABLE2 Deprecated Features,
	$(THEAD Feature,                                                          Spec,  Warn,   Dep,    Error,  Gone)
	$(TROW $(DEPLINK Cast T[] to integral type),                                      ?,     N/A,    2.060,  2.061,   )
	$(TROW $(DEPLINK Base Class Protection),                                  2.058, N/A,    2.058,   ,  )
	$(TROW $(DEPLINK Using length in index expressions),                      ?,     N/A,    2.041,  2.061,   )
	$(TROW $(DEPLINK typedef),                                                2.057, N/A,    2.057,   ,  )
	$(TROW $(DEPLINK Variable shadowing inside functions),                    ?,     N/A,    0.161,  2.061,   )
	$(TROW $(DEPLINK invariant as an alias for immutable),                    2.057, N/A,    2.057,   ,  )
	$(TROW $(DEPLINK Using * to dereference arrays),                          ?,     N/A,    2.057,   ,  )
	$(TROW $(DEPLINK Removing an item from an associative array with delete), ?,     N/A,    0.127,  2.061,   )
	$(TROW $(DEPLINK .offset property),                                       ?,     N/A,    0.107,  2.061,   )
	$(TROW $(DEPLINK .size property),                                         ?,     N/A,    0.107,  0.107,  2.061 )
	$(TROW $(DEPLINK Escape string literals),                                 ?,     N/A,    2.026,  2.061,   )
	$(TROW $(DEPLINK Lower case 'l' suffix for integer literals),             ?,     N/A,    1.054,  0.174,  (never) )
	$(TROW $(DEPLINK Octal literals),                                         2.054, N/A,    2.053,   ,  )
	$(TROW $(DEPLINK Upper case 'I' suffix for imaginary literals),           ?,     N/A,    0.154,  2.061,   )
	$(TROW $(DEPLINK HTML source files),                                      ?,     N/A,    2.013,  N/A,    2.061 )
	$(TROW $(DEPLINK .typeinfo property),                                     ?,     N/A,    0.093,  2.061,   )
	$(TROW $(DEPLINK C-style function pointers),                              ?,     N/A,    2.050,   ,  )
	$(TROW $(DEPLINK C-style array pointers),                                 ?,     N/A,    2.050,   ,  )
	$(TROW $(DEPLINK if (v; e)),                                              ?,     N/A,    0.149,  2.061,   )
	$(TROW $(DEPLINK volatile),                                               2.013, N/A,    2.013,   ,  )
	$(TROW $(DEPLINK Non-final switch statements without a default case),     2.054, N/A,    2.054,   ,  )
	$(TROW $(DEPLINK Hiding base class functions),                            2.054, N/A,    2.054,   ,  )
	$(TROW $(DEPLINK Windows 3.x and Windows 9x support),                     2.058, N/A,    N/A,    N/A,    2.058 )

    $(TROW $(DEPLINK .min property for floating point types),                 N/A,    2.061,   ,  ,  )
    $(TROW $(DEPLINK Imaginary and complex types),                            future,  ,  ,  ,  )
    $(TROW $(DEPLINK Floating point NCEG operators),                          future,  ,  2.066,  ,  )
    $(TROW $(DEPLINK .sort and .reverse properties for arrays),               future,  ,  ,  ,  )
    $(TROW $(DEPLINK clear),                                                   2.060,  ,  2.066,  ,  )
    $(TROW $(DEPLINK delete),                                                 future,  ,  ,  ,  )
    $(TROW $(DEPLINK Overriding without override),                            future,  ,  ,  ,  )
    $(TROW $(DEPLINK scope for allocating classes on the stack),              future,  ,  ,  ,  )
	)

	$(DL
	$(DT Spec)
	$(DD Removal from the Specification)
	$(DT Warn)
	$(DD The compiler emits a warning if the feature is used)
	$(DT Dep)
	$(DD The compiler issues an error if not compiled with the -d switch)
	$(DT Error)
	$(DD It is an error to use the feature)
	$(DT Gone)
	$(DD The feature is completely gone)
    )



$(H3 $(DEPNAME Cast T[] to integral type))
	At some point in time you could do:
---
ulong u = cast(ulong)[1,2];
---
	To get the length of the array.
$(H4 Corrective Action)
	$(P Use the $(LINK2 http://dlang.org/arrays.html#array-properties, .length) property instead.)

$(H4 Rationale)
	$(P Using a cast to get the length of an array is just confusing.)



$(H3 $(DEPNAME Base Class Protection))
	Base class protections are things like:
---
class A : $(D protected) B {
   ...
}
---
$(H4 Corrective Action)
	$(P Delete the protection attribute keyword from in front of the base class
	and base interfaces.
	)
$(H4 Rationale)
	$(P With D's module system, it doesn't seem to serve any useful purpose, and has never worked correctly.
    )



$(H3 $(DEPNAME Using length in index expressions))
	When used inside an indexing or slicing expression, length is rewritten to be the length of the array being sliced.
---
auto a = new int[5];
a = a[0..length-1];
---
$(H4 Corrective Action)
	$(P Replace length with the equivalent $(LINK2 arrays.html#array-length, '$')
	)
$(H4 Rationale)
	$(P The implicitly defined length variable shadows existing declarations, and is less concise than the alternative.
    )



$(H3 $(DEPNAME typedef))
	typedef can be used to construct a strongly-typed alias of a type.
---
typedef int myint;
static assert(!is(myint == int));
---
$(H4 Corrective Action)
	$(P Replace use of typedef with alias or use $(FULL_XREF typecons, Typedef).
	)
$(H4 Rationale)
	$(P typedef is not flexible enough to cover all use cases.  This is better done with a library solution.
    )





$(H3 $(DEPNAME Variable shadowing inside functions))
	Variable shadowing is when a variable in an inner scope has the same name as a variable in an enclosing scope.
---
void myFun()
{
    int var;
    if (x)
    {
        int var;
        var = 3; // which var was meant?
    }
}
---
$(H4 Corrective Action)
	$(P Rename shadowing variables so they don't conflict.
	)
$(H4 Rationale)
	$(P Variable shadowing can introduce hard to find bugs where the wrong variable is modified.
    )





$(H3 $(DEPNAME invariant as an alias for immutable))
	The invariant storage class and type modifier is an alias for immutable.
---
static assert(is(invariant(int) == immutable(int)));
---
$(H4 Corrective Action)
	$(P Replace all uses of invariant as a storage class or type modifier with immutable.  The invariant() syntax for struct and class invariants is still supported.
	)
$(H4 Rationale)
	$(P The alias is unnecessary.
    )






$(H3 $(DEPNAME Using * to dereference arrays))
	D array variables can be dereferenced to get the first element, much like pointers.
---
int[] arr = [1, 2, 3];
assert(*arr == 1);
---
$(H4 Corrective Action)
	$(P Use indexing syntax to access first member.
---
int[] arr = [1, 2, 3];
assert(arr[0] == 1);
---
	)
$(H4 Rationale)
	$(P D arrays are not pointers.
    )




$(H3 $(DEPNAME Removing an item from an associative array with delete))
	delete can be used to remove an item from an associative array.
---
int[int] aa = [1 : 2];
delete aa[1];
assert(1 !in aa);
---
$(H4 Corrective Action)
	$(P Use .remove instead.
---
int[int] aa = [1 : 2];
aa.remove(1);
assert(1 !in aa);
---
	)
$(H4 Rationale)
	$(P The delete syntax is confusing and conflicts with the normal delete syntax.
    )





$(H3 $(DEPNAME .offset property))
	The .offset property can be used to get member offset information.
---
struct S { int a, b; }
static assert(S.b.offset == 4);
---
$(H4 Corrective Action)
	$(P Use .offsetof instead
---
struct S { int a, b; }
static assert(S.b.offsetof == 4);
---
	)
$(H4 Rationale)
	$(P The .offset syntax has been superseded by .offsetof
    )






$(H3 $(DEPNAME .size property))
	The .size property can be used to get type size information
---
struct S { int a, b; }
static assert(S.size == 8);
---
$(H4 Corrective Action)
	$(P Use .sizeof instead
---
struct S { int a, b; }
static assert(S.sizeof == 8);
---
	)
$(H4 Rationale)
	$(P The .size syntax has been superseded by .sizeof
    )




$(H3 $(DEPNAME Escape string literals))
	Escape string literals can be used to describe characters using escape sequences.
---
// deprecated code
// string x = "hello" ~ \n;
---
$(H4 Corrective Action)
	$(P Put escape sequences inside a regular string literal.
---
string x = "hello\n";
---
	)
$(H4 Rationale)
	$(P Escape string literals are unintuitive and unnecessary.
    )




$(H3 $(DEPNAME Lower case 'l' suffix for integer literals))
	Lower case 'l' is an alternative suffix to denote 64 bit integer literals.
---
// deprecated code
// auto x = 123l;
---
$(H4 Corrective Action)
	$(P Use the upper case 'L' suffix.
---
auto x = 123L;
---
	)
$(H4 Rationale)
	$(P The lower case suffix is easily confused with the digit '1'.
    )
$(H4 Note)
    $(P In lexical analysis phase, compiler can recognize lower case suffix 'l'
        to report better error message - for the use case such as C-to-D code
        translation. Thus DMD would continue to parse 'l' suffix.
    )




$(H3 $(DEPNAME Octal literals))
	Octal literals can be used to enter literals in base 8.
---
// deprecated code
// auto x = 0123;
---
$(H4 Corrective Action)
	$(P Use the $(FULL_XREF conv, octal) template.
---
auto x = octal!123;
---
	)
$(H4 Rationale)
	$(P The use of a leading zero is confusing, as 0123 != 123.
    )





$(H3 $(DEPNAME Upper case 'I' suffix for imaginary literals))
	The 'I' suffix can be used to denote imaginary floating point values.
---
// deprecated code
// auto x = 1.234I;
---
$(H4 Corrective Action)
	$(P Use the lower case 'i' suffix.
---
auto x = 1.234i;
---
	)
$(H4 Rationale)
	$(P The 'I' suffix is easily confused with the digit '1'.
    )





$(H3 $(DEPNAME HTML source files))
	The D compiler can parse html files by ignoring everything not contained in <code&gt&lt/code&gt tags.
---
<html>
<code>
    ... source ...
</code>
</html>
---
$(H4 Corrective Action)
	$(P Extract code to regular source files.
	)
$(H4 Rationale)
	$(P This has been replaced for documentation by the introduction of ddoc
    )




$(H3 $(DEPNAME .typeinfo property))
	The .typeinfo property can be used to get the associated TypeInfo class.
---
T.typeinfo
---
$(H4 Corrective Action)
	$(P Use typeid() instead
---
typeid(T)
---
	)
$(H4 Rationale)
	$(P The .typeinfo syntax has been superseded by typeid()
    )




$(H3 $(DEPNAME C-style function pointers))
	C-style function pointers can be used in D.
---
alias void(*fptr)(int, long);
---
$(H4 Corrective Action)
	$(P Replace with D-style function pointers.
---
alias void function(int, long) fptr;
---
	)
$(H4 Rationale)
	$(P The D syntax is much cleaner and easier to use.
    )



$(H3 $(DEPNAME C-style array pointers))
	C-style array pointers can be used in D.
---
alias float *arrayptr[10][15];
---
$(H4 Corrective Action)
	$(P Replace with D-style array pointers.
---
alias float[15][10]* arrayptr;
---
	)
$(H4 Rationale)
	$(P The D syntax is much cleaner and easier to use.
    )




$(H3 $(DEPNAME if (v; e)))
	This syntax can be used to declare a variable in an if statement condition.
---
if (v; calculateAndReturnPointer()) { ... }
---
$(H4 Corrective Action)
	$(P Replace with an auto declaration.
---
if (auto v = calculateAndReturnPointer()) { ... }
---
	)
$(H4 Rationale)
	$(P The syntax is clearer with auto.
    )



$(H3 $(DEPNAME volatile))
	volatile can be used to mark statement, in order to prevent some compiler optimizations.
---
volatile
{
    ... do something involving ghared variables ...
}
---
$(H4 Corrective Action)
	$(P Convert the code to use synchronized statements instead.
	)
$(H4 Rationale)
	$(P volatile statements are a misfeature.
    )




$(H3 $(DEPNAME Non-final switch statements without a default case))
	Switch statements can be declared without a default case, and the compiler automatically adds one.
---
switch(a)
{
case 1:
    break;
case 2:
    break;
// the compiler adds
// default:
//     throw new SwitchError();
}
---
$(H4 Corrective Action)
	$(P Add the default case manually.
---
switch(a)
{
case 1:
    break;
case 2:
    break;
default:
    assert(0);
}
---
	)
$(H4 Rationale)
	$(P Missing default cases can hide bugs, and making the default case explicit should be mandatory.
    )




$(H3 $(DEPNAME Hiding base class functions))
	Declaration functions in a derived class that can be called with the same arguments as a function in a base class, but do not override that function causes the base class function to be hidden.
---
class A
{
    void fun(int x) {}
}
class B : A
{
    void fun(long x) {}
}
---
$(H4 Corrective Action)
	$(P Add the function to the base class, or use an alias to bring the base class overload into the derived class.
---
class A
{
    void fun(int x) {}
    void fun(long x) {} // this fixes it
}
class B : A
{
    void fun(long x) {}
    alias A.fun fun; // so does this
}
---
	)
$(H4 Rationale)
	$(P This is an error that is already detected at runtime, and is being extended to compile time.
    )



$(H3 $(DEPNAME Windows 3.x and Windows 9x support))
	There is some code in Phobos for Windows 3.x/9x support.
$(H4 Corrective Action)
	$(P Upgrade Windows or switch to another supported OS.
	)
$(H4 Rationale)
	$(P Supporting such outdated and rarely used OS-es isn't worth the trouble.
	)



$(H3 $(DEPNAME .min property for floating point types))
	Floating point types have the .min property to access the smallest value.
---
enum m = real.min;
---
$(H4 Corrective Action)
	$(P Replace with .min_normal
---
enum m = real.min_normal;
---
	)
$(H4 Rationale)
	$(P The name min_normal is more accurate, as .min does not include denormalized floating point values.
    )


$(H3 $(DEPNAME Imaginary and complex types))
	D currently supports imaginary and complex versions of all floating point types.
---
float a = 2;
ifloat b = 4i;
cfloat c = a + b;
assert(c == 2 + 4i);
---
$(H4 Corrective Action)
	$(P Use the library types in $(STDFILEREF complex).
	)
$(H4 Rationale)
	$(P These types are too specialized to be a part of the core language.
    )





$(H3 $(DEPNAME Floating point NCEG operators))
	D currently supports the NCEG floating point operators (!<>=, <>, <>=, !>, !>=, !<, !<=, !<>) for comparisons involving NaNs.
$(H4 Corrective Action)
	$(P Use the normal operators and $(FULL_XREF math, isNaN).
	)
$(H4 Rationale)
	$(P These operators are too specialized to be a part of the core language.
    )





$(H3 $(DEPNAME .sort and .reverse properties for arrays))
	D arrays can be manipulated using these built-in properties.
---
int[] x = [2, 3, 1];
assert(x.sort == [1, 2, 3]);
---
$(H4 Corrective Action)
	$(P Use the generic functions in $(STDFILEREF algorithm).
	)
$(H4 Rationale)
	$(P These operations are better implemented in the standard library.
    )




$(H3 $(DEPNAME clear))
	Call an object's destructor.
---
auto a = new Class();
clear(a);
---
$(H4 Corrective Action)
	$(P Use $(LINK2 phobos/object.html#.destroy, $(D object.destroy())) instead.
---
auto a = new Class();
destroy(a);
---
	)
$(H4 Rationale)
	$(P Due to Uniform Function Call Syntax (UFCS), $(D clear) can cause confusion with other methods of the same name, such as a $(D clear) method used to remove the contents of a container.
    )





$(H3 $(DEPNAME delete))
	Memory allocated on the GC heap can be freed with $(D delete).
---
auto a = new Class();
delete a;
---
$(H4 Corrective Action)
	$(P Use $(LINK2 phobos/object.html#.destroy, $(D object.destroy())) 
	to finalize the object instead.
---
auto a = new Class();
destroy(a);
---
	)
	$(P Note that $(D destroy) does not free the allocated memory. If
	necessary, call $(LINK2 phobos/core_memory.html#.GC.free, $(D core.GC.free)) also.
	)
$(H4 Rationale)
	$(P $(D delete) makes assumptions about the type of garbage collector available that limits which implementations can be used, and can be replaced by a library solution.
    )





$(H3 $(DEPNAME Overriding without override))
	Virtual functions can currently override a function in a base class without the 'override' attribute.
---
class A
{
    void fun() {}
}
class B : A
{
    // overrides but is not marked with override
    void fun() {}
}
---
$(H4 Corrective Action)
	$(P Mark overriding functions with 'override'
---
class A
{
    void fun() {}
}
class B : A
{
    override void fun() {}
}
---
	)
$(H4 Rationale)
	$(P Making the 'override' attribute mandatory makes it explicit, and can catch errors when a base class function is accidentally overridden.
    )

$(H3 $(DEPNAME scope for allocating classes on the stack))
	The $(D scope) keyword can be used to allocate class objects on the stack:
---
class A
{
    int x;
    this(int x) { this.x = x; }
}

void main()
{
    A obj;
    {
        scope A a = new A(1);
        obj = a;
    }
    assert(obj.x == 1);  // fails, 'a' has been destroyed
}
---
$(H4 Corrective Action)
	$(P Use $(FULL_XREF typecons, scoped) instead.
---
class A
{
    this(int x) { }
}
void main()
{
    auto a = scoped!A(1);
}
---
	)
$(H4 Rationale)
	$(P $(D scope) was an unsafe feature. A reference to a scoped class could easily
        be returned from a function without errors, which would make using such
        an object undefined behavior due to the object being destroyed after
        exiting the scope of the function it was allocated in. To discourage it
        from general-use but still allow usage when needed a library solution was
        implemented.
    )

    $(P
        Note that $(D scope) for other usages (e.g. scoped variables) is unrelated
        to this feature and will not be deprecated.
    )



)

Macros:
	DEPLINK=$(RELATIVE_LINK2 $0, $0)
	DEPLINK2=$(LINK2 $1.html#$2, $2)
	DEPNAME=$(LNAME2 $0, $0)
	TITLE=Deprecated Features
	WIKI=DeprecatedFeatures
	STDFILEREF = <a href="phobos/std_$1.html">$(D std.$1)</a>