root/trunk/docsrc/const3.dd

Ddoc

$(D_S 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  ) $(TH AddrOf) $(TH CTFEInit) $(TH Static) $(TH Field) $(TH Stack) $(TH Ctor))

$(TR $(TD  )
 $(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</h2>

    $(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;

    immutable void foo()
    {
    x = 4;      // error, x is immutable
    this.x = 4; // error, x is immutable
    }
---

    $(P The $(D_KEYWORD const) and $(D_KEYWORD immutable) function
    attributes
    can also appear after the closing parenthesis of
    the parameter list:
    )

---
struct S
{
    void 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
    Mutable and immutable types can be implicitly converted to const.
    Mutable types cannot be implicitly converted to immutable,
    and vice versa.
    )
)


$(SECTION2 Comparing D Immutable and Const with C++ Const,

    <table border=2 cellpadding=4 cellspacing=0 class="comp">
    <caption>Const, Immutable Comparison</caption>

    <thead>
    $(TR
    $(TH Feature)
    $(TH D)
    $(TH C++98)
    )
    </thead>

    <tbody>

    $(TR
    $(TD const keyword)
    $(TD Yes)
    $(TD Yes)
    )

    $(TR
    $(TD immutable keyword)
    $(TD Yes)
    $(TD No)
    )

    $(TR
    $(TD const notation)
    $(TD Functional:
---
//ptr to const ptr to const int
const(int*)* p;
---
    )
    $(TD Postfix:
$(CPPCODE
//ptr to const ptr to const int
const int *const *p;
)
    )
    )

    $(TR
    $(TD transitive const)
    $(TD Yes:
---
//const ptr to const ptr to const int
const int** p;
**p = 3; // error
---
     )
    $(TD No:
$(CPPCODE
// const ptr to ptr to int
int** const p;
**p = 3;    // ok
)
     )
    )

    $(TR
    $(TD cast away const)
    $(TD Yes:
---
// ptr to const int
const(int)* p;
int* q = cast(int*)p; // ok
---
    )
    $(TD Yes:
$(CPPCODE
// ptr to const int
const int* p;
int* q = const_cast&lt;int*&gt;p; //ok
)
    )
    )

    $(TR
    $(TD modification after casting away const)
    $(TD No:
---
// ptr to const int
const(int)* p;
int* q = cast(int*)p;
*q = 3;   // undefined behavior
---
    )
    $(TD Yes:
$(CPPCODE
// ptr to const int
const int* p;
int* q = const_cast&lt;int*&gt;p;
*q = 3;   // ok
)
    )
    )

    $(TR
    $(TD overloading of top level const)
    $(TD Yes:
---
void foo(int x);
void foo(const int x);  //ok
---
    )
    $(TD No:
$(CPPCODE
void foo(int x);
void foo(const int x);  //error
)
    )
    )

    $(TR
    $(TD aliasing of const with mutable)
    $(TD Yes:
---
void foo(const int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;
   bar(*x); // bar(4)
}
...
int i = 3;
foo(&i, &i);
---
    )
    $(TD Yes:
$(CPPCODE
void foo(const int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;
   bar(*x); // bar(4)
}
...
int i = 3;
foo(&i, &i);
)
    )
    )

    $(TR
    $(TD aliasing of immutable with mutable)
    $(TD No:
---
void foo(immutable int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;  // undefined behavior
   bar(*x); // bar(??)
}
...
int i = 3;
foo(cast(immutable)&i, &i);
---
    )
    $(TD No immutables)
    )

    $(TR
    $(TD type of string literal)
    $(TD immutable(char)[])
    $(TD const char*)
    )


    $(TR
    $(TD implicit conversion of string literal to non-const)
    $(TD not allowed)
    $(TD allowed, but deprecated)
    )

    </tbody>
    </table>
)


)

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=Const and Immutable
    WIKI=ConstInvariant
    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>
    D_CODE = <pre class="d_code2">$0</pre>
    CPPCODE2 = <pre class="cppcode2">$0</pre>
    ERROR = $(RED $(B error))
    COMMA=,
META_KEYWORDS=D Programming Language, const, immutable
META_DESCRIPTION=Comparison of const between the
D programming language, C++, and C++0x