const3.dd

Ddoc

$(D_S Type Constructors,

	$(P Type constructors modify a type by applying a $(GLINK2 declaration, TypeCtor).
	$(I TypeCtor)s are: $(D const), $(D immutable),	$(D shared), and $(D inout).
	Each applies transitively to all subtypes.
	)

$(SECTION2 Const and Immutable,

	$(P When examining a data structure or interface, it is very
	helpful to be able to easily tell which data can be expected to not
	change, which data might change, and who may change that data.
	This is done with the aid of the language typing system.
	Data can be marked as const or immutable, with the default being
	changeable (or $(I mutable)).
	)

	$(P $(I immutable) applies to data that cannot change.
	Immutable data values, once constructed, remain the same for
	the duration of the program's
	execution.
	Immutable data can be placed in ROM (Read Only Memory) or in
	memory pages marked by the hardware as read only.
	Since immutable data does not change, it enables many opportunities
	for program optimization, and has applications in functional
	style programming.
	)

	$(P $(I const) applies to data that cannot be changed by
	the const reference to that data. It may, however, be changed
	by another reference to that same data.
	Const finds applications in passing data through interfaces
	that promise not to modify them.
	)

	$(P Both immutable and const are $(I transitive), which means
	that any data reachable through an immutable reference is also
	immutable, and likewise for const.
	)
)

$(SECTION2 Immutable Storage Class,

	$(P
	The simplest immutable declarations use it as a storage class.
	It can be used to declare manifest constants.
	)

---
immutable int x = 3;  // x is set to 3
x = 4;        // error, x is immutable
char[x] s;    // s is an array of 3 char's
---

	$(P The type can be inferred from the initializer:
	)
---
immutable y = 4; // y is of type int
y = 5;           // error, y is immutable
---

	$(P If the initializer is not present, the immutable can
	be initialized from the corresponding constructor:
	)

---
immutable int z;
void test() {
  z = 3; // error, z is immutable
}
static this() {
  z = 3; // ok, can set immutable that doesn't
         // have static initializer
}
---
	$(P
	The initializer for a non-local immutable declaration must be
	evaluatable
	at compile time:
	)

---
int foo(int f) { return f * 3; }
int i = 5;
immutable x = 3 * 4;      // ok, 12
immutable y = i + 1;      // error, cannot evaluate at compile time
immutable z = foo(2) + 1; // ok, foo(2) can be evaluated at compile time, 7
---

	$(P The initializer for a non-static local immutable declaration
	is evaluated at run time:
	)
---
int foo(int f)
{
  immutable x = f + 1;  // evaluated at run time
  x = 3;                // error, x is immutable
}
---

	$(P
	Because immutable is transitive, data referred to by an immutable is
	also immutable:
	)

---
immutable char[] s = "foo";
s[0] = 'a';  // error, s refers to immutable data
s = "bar";   // error, s is immutable
---

	$(P Immutable declarations can appear as lvalues, i.e. they can
	have their address taken, and occupy storage.
	)
)

$(SECTION2 Const Storage Class,

	$(P
	A const declaration is exactly like an immutable declaration,
	with the following differences:
	)

	$(UL
	$(LI Any data referenced by the const declaration cannot be
	changed from the const declaration, but it might be changed
	by other references to the same data.)

	$(LI The type of a const declaration is itself const.)
	)

$(COMMENT
$(TABLE1

$(TR $(TH $(NBSP)) $(TH AddrOf) $(TH CTFEInit) $(TH Static) $(TH Field) $(TH Stack) $(TH Ctor))

$(TR $(TD $(NBSP))
 $(TD Can the address be taken?)
 $(TD Is compile time function evaluation done on the initializer?)
 $(TD allocated as static data?)
 $(TD allocated as a per-instance field?)
 $(TD allocated on the stack?)
 $(TD Can the variable be assigned to in a constructor?)
)


$(TR $(TH Global data))

$(TR $(TD1 const T x;)		$(Y)	$(N)	$(Y)	$(N)	$(N)	$(Y))
$(TR $(TD1 const T x = 3;)		$(N)	$(Y)	$(N)	$(N)	$(N)	$(N))
$(TR $(TD1 static const T x;)	$(Y)	$(N)	$(Y)	$(N)	$(N)	$(Y))
$(TR $(TD1 static const T x = 3;)	$(Y)	$(Y)	$(Y)	$(N)	$(N)	$(N))


$(TR $(TH Class Members))

$(TR $(TD1 const T x;)		$(Y)	$(N)	$(N)	$(Y)	$(N)	$(Y))
$(TR $(TD1 const T x = 3;)		$(N)	$(Y)	$(N)	$(N)	$(N)	$(N))
$(TR $(TD1 static const T x;)	$(Y)	$(N)	$(Y)	$(N)	$(N)	$(Y))
$(TR $(TD1 static const T x = 3;)	$(Y)	$(Y)	$(Y)	$(N)	$(N)	$(N))


$(TR $(TH Local Variables))

$(TR $(TD1 const T x;)		$(Y)	$(Y)	$(N)	$(N)	$(Y)	$(N))
$(TR $(TD1 const T x = 3;)		$(Y)	$(N)	$(N)	$(N)	$(Y)	$(N))
$(TR $(TD1 static const T x;)	$(Y)	$(Y)	$(Y)	$(N)	$(N)	$(N))
$(TR $(TD1 static const T x = 3;)	$(Y)	$(Y)	$(Y)	$(N)	$(N)	$(N))

$(TR $(TH Function Parameters))

$(TR $(TD1 const T x;)		$(Y)	$(N)	$(N)	$(N)	$(Y)	$(N))
)


$(P Notes:)

$(OL
$(LI If CTFEInit is true, then the initializer can also be used for
constant folding.)
)


$(TABLE1
<caption>Template Argument Deduced Type</caption>
$(TR $(TH $(NBSP))               $(TH mutable $(CODE T)) $(TH1 const(T)) $(TH1 immutable(T)))
$(TR $(TD1 foo(U))              $(TDE T) $(TDE T) $(TDE T))
$(TR $(TD1 foo(U:U))            $(TDE T) $(TDE const(T)) $(TDE immutable(T)))
$(TR $(TD1 foo(U:const(U)))     $(TDI T) $(TDE T) $(TDI T))
$(TR $(TD1 foo(U:immutable(U))) $(NM) $(NM) $(TDE T))
)

$(P Where:)

$(TABLE1
$(TR $(TD $(GREEN green)) $(TD exact match))
$(TR $(TD $(ORANGE orange)) $(TD implicit conversion))
)
)
)

$(SECTION2 Immutable Type,

	$(P
	Data that will never change its value can be typed as immutable.
	The immutable keyword can be used as a $(I type constructor):
	)

---
immutable(char)[] s = "hello";
---

	$(P
	The immutable applies to the type within the following parentheses.
	So, while $(CODE s) can be assigned new values,
	the contents of $(CODE s[]) cannot be:
	)

---
s[0] = 'b';  // error, s[] is immutable
s = null;    // ok, s itself is not immutable
---

	$(P
	Immutableness is transitive, meaning it applies to anything that
	can be referenced from the immutable type:
	)

---
immutable(char*)** p = ...;
p = ...;        // ok, p is not immutable
*p = ...;       // ok, *p is not immutable
**p = ...;      // error, **p is immutable
***p = ...;     // error, ***p is immutable
---

	$(P Immutable used as a storage class is equivalent to using
	immutable as a type constructor for the entire type of a
	declaration:)

---
immutable int x = 3;   // x is typed as immutable(int)
immutable(int) y = 3;  // y is immutable
---
)


$(SECTION2 Creating Immutable Data,

	$(P
	The first way is to use a literal that is already immutable,
	such as string literals. String literals are always immutable.
	)

---
auto s = "hello";   // s is immutable(char)[5]
char[] p = "world"; // error, cannot implicitly convert immutable
		    // to mutable
---

	$(P
	The second way is to cast data to immutable.
	When doing so, it is up to the programmer to ensure that no
	other mutable references to the same data exist.
	)

---
char[] s = ...;
immutable(char)[] p = cast(immutable)s;     // undefined behavior
immutable(char)[] p = cast(immutable)s.dup; // ok, unique reference
---

	$(P
	The $(CODE .idup) property is a convenient way to create an immutable
	copy of an array:
	)

---
auto p = s.idup;
p[0] = ...;	  // error, p[] is immutable
---

$(H2 Removing Immutable With A Cast)

	$(P
	The immutable type can be removed with a cast:
	)

---
immutable int* p = ...;
int* q = cast(int*)p;
---

	$(P
	This does not mean, however, that one can change the data:
	)

---
*q = 3; // allowed by compiler, but result is undefined behavior
---

	$(P
	The ability to cast away immutable-correctness is necessary in
	some cases where the static typing is incorrect and not fixable, such
	as when referencing code in a library one cannot change.
	Casting is, as always, a blunt and effective instrument, and
	when using it to cast away immutable-correctness, one must assume
	the responsibility to ensure the immutableness of the data, as
	the compiler will no longer be able to statically do so.
	)
)


$(SECTION2 Immutable Member Functions,

	$(P
	Immutable member functions are guaranteed that the object
	and anything referred to by the $(CODE this) reference is immutable.
	They are declared as:
	)

---
struct S {
  int x;

  void foo() immutable {
    x = 4;      // error, x is immutable
    this.x = 4; // error, x is immutable
  }
}
---
    $(P Note that using $(D_KEYWORD immutable) on the left hand side of a method does not apply to the return type:
    )

---
struct S {
  immutable int[] bar()  // bar is still immutable, return type is not!
  {
  }
}
---
    $(P To make the return type $(D_KEYWORD immutable), you need to surround the return type with parentheses:
    )

---
struct S {
  immutable(int[]) bar()  // bar is now mutable, return type is immutable.
  {
  }
}
---
    $(P To make both the return type and the method $(D_KEYWORD immutable), you can write:
    )
---
struct S {
  immutable(int[]) bar() immutable
  {
  }
}
---
)


$(SECTION2 Const Type,

	$(P
	Const types are like immutable types, except that const
	forms a read-only $(I view) of data. Other aliases to that
	same data may change it at any time.
	)
)


$(SECTION2 Const Member Functions,

	$(P
	Const member functions are functions that are not allowed to
	change any part of the object through the member function's
	this reference.
	)
)


$(SECTION2 Implicit Conversions,

	$(P Values can be implicitly converted between $(I mutable), $(D const), $(D immutable),
	$(D shared const), $(D inout) and $(D inout shared).
	)

	$(P References can be converted according to the following rules:
	)

    $(TABLE_SPECIAL $(ARGS Implicit Conversion of Reference Types)
    $(TROW from/to, $(I mutable), $(D const), $(D shared), $(D shared const), $(D inout), $(D inout const), $(D inout shared), $(D inout shared const), $(D immutable))
    $(TROW $(I mutable)            $(YES) $(YES) $(NO)  $(NO)  $(NO)  $(NO)  $(NO)  $(NO)  $(NO) )
    $(TROW $(D const)              $(NO)  $(YES) $(NO)  $(NO)  $(NO)  $(NO)  $(NO)  $(NO)  $(NO) )
    $(TROW $(D shared)             $(NO)  $(NO)  $(YES) $(YES) $(NO)  $(NO)  $(NO)  $(NO)  $(NO) )
    $(TROW $(D shared const)       $(NO)  $(NO)  $(NO)  $(YES) $(NO)  $(NO)  $(NO)  $(NO)  $(NO) )
    $(TROW $(D inout)              $(NO)  $(YES) $(NO)  $(NO)  $(YES) $(YES) $(NO)  $(NO)  $(NO) )
    $(TROW $(D inout const)        $(NO)  $(YES) $(NO)  $(NO)  $(NO)  $(YES) $(NO)  $(NO)  $(NO) )
    $(TROW $(D inout shared)       $(NO)  $(NO)  $(NO)  $(YES) $(NO)  $(NO)  $(YES) $(YES) $(NO) )
    $(TROW $(D inout shared const) $(NO)  $(NO)  $(NO)  $(YES) $(NO)  $(NO)  $(NO)  $(YES) $(NO) )
    $(TROW $(D immutable)          $(NO)  $(YES) $(NO)  $(YES) $(NO)  $(YES) $(NO)  $(YES) $(YES))
    )

	$(P If an implicit conversion is disallowed by the table, an $(GLINK2 expression, Expression)
	may be converted if:
	)

	$(P An expression may be converted from mutable or shared to immutable if the expression
	is unique and all expressions it transitively refers to are either unique or immutable.
	)

	$(P An expression may be converted from mutable to shared if the expression
	is unique and all expressions it transitively refers to are either unique, immutable,
	or shared.
	)

	$(P An expression may be converted from immutable to mutable if the expression
	is unique.
	)

	$(P An expression may be converted from shared to mutable if the expression
	is unique.
	)

	$(P A $(I Unique Expression) is one for which there are no other references to the
	value of the expression and all expressions it transitively refers to are either
	also unique or are immutable. For example:
---
void main()
{
  immutable int** p = new int*(null); // ok, unique

  int x;
  immutable int** q = new int*(&x); // error, there may be other references to x

  immutable int y;
  immutable int** r = new immutable(int)*(&y); // ok, y is immutable
}
---
	)

	$(P Otherwise, a $(GLINK2 expression, CastExpression) can be used to force a conversion
	when an implicit version is disallowed, but this cannot be done in $(D @safe) code,
	and the correctness of it must be verified by the user.
	)
)


)

Macros:
	TH1=<th nowrap="nowrap">$(CODE $0)</th>
	TD1=<td nowrap="nowrap">$(CODE $0)</td>
	TDE=<td nowrap="nowrap">$(GREEN $(CODE $0))</td>
	TDI=<td nowrap="nowrap">$(ORANGE $(CODE $0))</td>
	NM=$(TD $(RED no match))
	Y=$(TD $(GREEN Yes))
	N=$(TD $(RED No))
	TITLE=Type Constructors
	WIKI=ConstInvariant
	CATEGORY_SPEC=$0
	NO=<td class="compNo">No</td>
	NO1=<td class="compNo"><a href="$1">No</a></td>
	YES=<td class="compYes">Yes</td>
	YES1=<td class="compYes"><a href="$1">Yes</a></td>
	ERROR = $(RED $(B error))
    META_KEYWORDS=D Programming Language, const, immutable
    META_DESCRIPTION=Comparison of const between the D programming language, C++, and C++0x