Show
Ignore:
Timestamp:
07/16/09 18:24:08 (3 years ago)
Author:
walter
Message:

latest

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docsrc/const3.dd

    r863 r1242  
    11Ddoc 
    22 
    3 $(D_S Const and Invariant, 
     3$(D_S Const and Immutable, 
    44 
    55    $(P When examining a data structure or interface, it is very 
    …… 
    77    change, which data might change, and who may change that data. 
    88    This is done with the aid of the language typing system. 
    9     Data can be marked as const or invariant, with the default being 
     9    Data can be marked as const or immutable, with the default being 
    1010    changeable (or $(I mutable)). 
    1111    ) 
    1212 
    13     $(P $(I invariant) applies to data that cannot change. 
    14     Invariant data values, once constructed, remain the same for 
     13    $(P $(I immutable) applies to data that cannot change. 
     14    Immutable data values, once constructed, remain the same for 
    1515    the duration of the program's 
    1616    execution. 
    17     Invariant data can be placed in ROM (Read Only Memory) or in 
     17    Immutable data can be placed in ROM (Read Only Memory) or in 
    1818    memory pages marked by the hardware as read only. 
    19     Since invariant data does not change, it enables many opportunities 
     19    Since immutable data does not change, it enables many opportunities 
    2020    for program optimization, and has applications in functional 
    2121    style programming. 
    …… 
    2929    ) 
    3030 
    31     $(P Both invariant and const are $(I transitive), which means 
    32     that any data reachable through an invariant reference is also 
    33     invariant, and likewise for const. 
    34     ) 
    35  
    36 $(SECTION2 Invariant Storage Class, 
    37  
    38     $(P 
    39     The simplest invariant declarations use it as a storage class. 
     31    $(P Both immutable and const are $(I transitive), which means 
     32    that any data reachable through an immutable reference is also 
     33    immutable, and likewise for const. 
     34    ) 
     35 
     36$(SECTION2 Immutable Storage Class, 
     37 
     38    $(P 
     39    The simplest immutable declarations use it as a storage class. 
    4040    It can be used to declare manifest constants. 
    4141    ) 
    4242 
    4343--- 
    44 invariant int x = 3;  // x is set to 3 
    45 x = 4;          // error, x is invariant 
     44immutable int x = 3;  // x is set to 3 
     45x = 4;          // error, x is immutable 
    4646char[x] s;      // s is an array of 3 char's 
    4747--- 
    …… 
    5050    ) 
    5151--- 
    52 invariant y = 4;  // y is of type int 
    53 y = 5;          // error, y is invariant 
    54 --- 
    55  
    56     $(P If the initializer is not present, the invariant can 
     52immutable y = 4;  // y is of type int 
     53y = 5;          // error, y is immutable 
     54--- 
     55 
     56    $(P If the initializer is not present, the immutable can 
    5757    be initialized from the corresponding constructor: 
    5858    ) 
    5959 
    6060--- 
    61 invariant int z; 
     61immutable int z; 
    6262void test() 
    6363{ 
    64     z = 3;      // error, z is invariant 
     64    z = 3;      // error, z is immutable 
    6565} 
    6666static this() 
    6767{ 
    68     z = 3;    // ok, can set invariant that doesn't have 
     68    z = 3;    // ok, can set immutable that doesn't have 
    6969              // static initializer 
    7070} 
    7171--- 
    7272    $(P 
    73     The initializer for a non-local invariant declaration must be 
     73    The initializer for a non-local immutable declaration must be 
    7474    evaluatable 
    7575    at compile time: 
    …… 
    7979int foo(int f) { return f * 3; } 
    8080int i = 5; 
    81 invariant x = 3 * 4;      // ok, 12 
    82 invariant y = i + 1;      // error, cannot evaluate at compile time 
    83 invariant z = foo(2) + 1; // ok, foo(2) can be evaluated at compile time, 7 
    84 --- 
    85  
    86     $(P The initializer for a non-static local invariant declaration 
     81immutable x = 3 * 4;      // ok, 12 
     82immutable y = i + 1;      // error, cannot evaluate at compile time 
     83immutable z = foo(2) + 1; // ok, foo(2) can be evaluated at compile time, 7 
     84--- 
     85 
     86    $(P The initializer for a non-static local immutable declaration 
    8787    is evaluated at run time: 
    8888    ) 
    …… 
    9090int foo(int f) 
    9191{ 
    92   invariant x = f + 1;  // evaluated at run time 
    93   x = 3;                // error, x is invariant 
    94 } 
    95 --- 
    96  
    97     $(P 
    98     Because invariant is transitive, data referred to by an invariant is 
    99     also invariant: 
    100     ) 
    101  
    102 --- 
    103 invariant char[] s = "foo"; 
    104 s[0] = 'a';  // error, s refers to invariant data 
    105 s = "bar";   // error, s is invariant 
    106 --- 
    107  
    108     $(P Invariant declarations can appear as lvalues, i.e. they can 
     92  immutable x = f + 1;  // evaluated at run time 
     93  x = 3;                // error, x is immutable 
     94} 
     95--- 
     96 
     97    $(P 
     98    Because immutable is transitive, data referred to by an immutable is 
     99    also immutable: 
     100    ) 
     101 
     102--- 
     103immutable char[] s = "foo"; 
     104s[0] = 'a';  // error, s refers to immutable data 
     105s = "bar";   // error, s is immutable 
     106--- 
     107 
     108    $(P Immutable declarations can appear as lvalues, i.e. they can 
    109109    have their address taken, and occupy storage. 
    110110    ) 
    …… 
    114114 
    115115    $(P 
    116     A const declaration is exactly like an invariant declaration, 
     116    A const declaration is exactly like an immutable declaration, 
    117117    with the following differences: 
    118118    ) 
    …… 
    180180$(TABLE1 
    181181<caption>Template Argument Deduced Type</caption> 
    182 $(TR $(TH &nbsp;)               $(TH mutable $(CODE T)) $(TH1 const(T)) $(TH1 invariant(T))) 
     182$(TR $(TH &nbsp;)               $(TH mutable $(CODE T)) $(TH1 const(T)) $(TH1 immutable(T))) 
    183183$(TR $(TD1 foo(U))              $(TDE T) $(TDE T) $(TDE T)) 
    184 $(TR $(TD1 foo(U:U))            $(TDE T) $(TDE const(T)) $(TDE invariant(T))) 
     184$(TR $(TD1 foo(U:U))            $(TDE T) $(TDE const(T)) $(TDE immutable(T))) 
    185185$(TR $(TD1 foo(U:const(U)))     $(TDI T) $(TDE T) $(TDI T)) 
    186 $(TR $(TD1 foo(U:invariant(U))) $(NM) $(NM) $(TDE T)) 
     186$(TR $(TD1 foo(U:immutable(U))) $(NM) $(NM) $(TDE T)) 
    187187) 
    188188 
    …… 
    196196) 
    197197 
    198 $(SECTION2 Invariant Type, 
    199  
    200     $(P 
    201     Data that will never change its value can be typed as invariant. 
    202     The invariant keyword can be used as a $(I type constructor): 
    203     ) 
    204  
    205 --- 
    206 invariant(char)[] s = "hello"; 
    207 --- 
    208  
    209     $(P 
    210     The invariant applies to the type within the following parentheses. 
     198$(SECTION2 Immutable Type, 
     199 
     200    $(P 
     201    Data that will never change its value can be typed as immutable. 
     202    The immutable keyword can be used as a $(I type constructor): 
     203    ) 
     204 
     205--- 
     206immutable(char)[] s = "hello"; 
     207--- 
     208 
     209    $(P 
     210    The immutable applies to the type within the following parentheses. 
    211211    So, while $(CODE s) can be assigned new values, 
    212212    the contents of $(CODE s[]) cannot be: 
    …… 
    214214 
    215215--- 
    216 s[0] = 'b';  // error, s[] is invariant 
    217 s = null;    // ok, s itself is not invariant 
    218 --- 
    219  
    220     $(P 
    221     Invariantness is transitive, meaning it applies to anything that 
    222     can be referenced from the invariant type: 
    223     ) 
    224  
    225 --- 
    226 invariant(char*)** p = ...; 
    227 p = ...;        // ok, p is not invariant 
    228 *p = ...;       // ok, *p is not invariant 
    229 **p = ...;      // error, **p is invariant 
    230 ***p = ...;     // error, ***p is invariant 
    231 --- 
    232  
    233     $(P Invariant used as a storage class is equivalent to using 
    234     invariant as a type constructor for the entire type of a 
     216s[0] = 'b';  // error, s[] is immutable 
     217s = null;    // ok, s itself is not immutable 
     218--- 
     219 
     220    $(P 
     221    Immutableness is transitive, meaning it applies to anything that 
     222    can be referenced from the immutable type: 
     223    ) 
     224 
     225--- 
     226immutable(char*)** p = ...; 
     227p = ...;        // ok, p is not immutable 
     228*p = ...;       // ok, *p is not immutable 
     229**p = ...;      // error, **p is immutable 
     230***p = ...;     // error, ***p is immutable 
     231--- 
     232 
     233    $(P Immutable used as a storage class is equivalent to using 
     234    immutable as a type constructor for the entire type of a 
    235235    declaration:) 
    236236 
    237237--- 
    238 invariant int x = 3;   // x is typed as invariant(int) 
    239 invariant(int) y = 3;  // y is invariant 
    240 --- 
    241 ) 
    242  
    243  
    244 $(SECTION2 Creating Invariant Data, 
    245  
    246     $(P 
    247     The first way is to use a literal that is already invariant, 
    248     such as string literals. String literals are always invariant. 
    249     ) 
    250  
    251 --- 
    252 auto s = "hello";   // s is invariant(char)[5] 
    253 char[] p = "world"; // error, cannot implicitly convert invariant 
     238immutable int x = 3;   // x is typed as immutable(int) 
     239immutable(int) y = 3;  // y is immutable 
     240--- 
     241) 
     242 
     243 
     244$(SECTION2 Creating Immutable Data, 
     245 
     246    $(P 
     247    The first way is to use a literal that is already immutable, 
     248    such as string literals. String literals are always immutable. 
     249    ) 
     250 
     251--- 
     252auto s = "hello";   // s is immutable(char)[5] 
     253char[] p = "world"; // error, cannot implicitly convert immutable 
    254254            // to mutable 
    255255--- 
    256256 
    257257    $(P 
    258     The second way is to cast data to invariant. 
     258    The second way is to cast data to immutable. 
    259259    When doing so, it is up to the programmer to ensure that no 
    260260    other mutable references to the same data exist. 
    …… 
    263263--- 
    264264char[] s = ...; 
    265 invariant(char)[] p = cast(invariant)s;     // undefined behavior 
    266 invariant(char)[] p = cast(invariant)s.dup; // ok, unique reference 
    267 --- 
    268  
    269     $(P 
    270     The $(CODE .idup) property is a convenient way to create an invariant 
     265immutable(char)[] p = cast(immutable)s;     // undefined behavior 
     266immutable(char)[] p = cast(immutable)s.dup; // ok, unique reference 
     267--- 
     268 
     269    $(P 
     270    The $(CODE .idup) property is a convenient way to create an immutable 
    271271    copy of an array: 
    272272    ) 
    …… 
    274274--- 
    275275auto p = s.idup; 
    276 p[0] = ...;   // error, p[] is invariant 
    277 --- 
    278  
    279 <h2>Removing Invariant With A Cast</h2> 
    280  
    281     $(P 
    282     The invariant type can be removed with a cast: 
    283     ) 
    284  
    285 --- 
    286 invariant int* p = ...; 
     276p[0] = ...;   // error, p[] is immutable 
     277--- 
     278 
     279<h2>Removing Immutable With A Cast</h2> 
     280 
     281    $(P 
     282    The immutable type can be removed with a cast: 
     283    ) 
     284 
     285--- 
     286immutable int* p = ...; 
    287287int* q = cast(int*)p; 
    288288--- 
    …… 
    297297 
    298298    $(P 
    299     The ability to cast away invariant-correctness is necessary in 
     299    The ability to cast away immutable-correctness is necessary in 
    300300    some cases where the static typing is incorrect and not fixable, such 
    301301    as when referencing code in a library one cannot change. 
    302302    Casting is, as always, a blunt and effective instrument, and 
    303     when using it to cast away invariant-correctness, one must assume 
    304     the responsibility to ensure the invariantness of the data, as 
     303    when using it to cast away immutable-correctness, one must assume 
     304    the responsibility to ensure the immutableness of the data, as 
    305305    the compiler will no longer be able to statically do so. 
    306306    ) 
    …… 
    308308 
    309309 
    310 $(SECTION2 Invariant Member Functions, 
    311  
    312     $(P 
    313     Invariant member functions are guaranteed that the object 
    314     and anything referred to by the $(CODE this) reference is invariant. 
     310$(SECTION2 Immutable Member Functions, 
     311 
     312    $(P 
     313    Immutable member functions are guaranteed that the object 
     314    and anything referred to by the $(CODE this) reference is immutable. 
    315315    They are declared as: 
    316316    ) 
    …… 
    320320{   int x; 
    321321 
    322     invariant void foo() 
     322    immutable void foo() 
    323323    { 
    324     x = 4;      // error, x is invariant 
    325     this.x = 4; // error, x is invariant 
     324    x = 4;      // error, x is immutable 
     325    this.x = 4; // error, x is immutable 
    326326    } 
    327327--- 
    328328 
    329     $(P The $(D_KEYWORD const) and $(D_KEYWORD invariant) function 
     329    $(P The $(D_KEYWORD const) and $(D_KEYWORD immutable) function 
    330330    attributes 
    331331    can also appear after the closing parenthesis of 
    …… 
    336336struct S 
    337337{ 
    338     void bar() invariant 
     338    void bar() immutable 
    339339    { 
    340340    } 
    …… 
    347347 
    348348    $(P 
    349     Const types are like invariant types, except that const 
     349    Const types are like immutable types, except that const 
    350350    forms a read-only $(I view) of data. Other aliases to that 
    351351    same data may change it at any time. 
    …… 
    367367 
    368368    $(P 
    369     Mutable and invariant types can be implicitly converted to const. 
    370     Mutable types cannot be implicitly converted to invariant, 
     369    Mutable and immutable types can be implicitly converted to const. 
     370    Mutable types cannot be implicitly converted to immutable, 
    371371    and vice versa. 
    372372    ) 
    …… 
    374374 
    375375 
    376 $(SECTION2 Comparing D Invariant and Const with C++ Const, 
     376$(SECTION2 Comparing D Immutable and Const with C++ Const, 
    377377 
    378378    <table border=2 cellpadding=4 cellspacing=0 class="comp"> 
    379     <caption>Const, Invariant Comparison</caption> 
     379    <caption>Const, Immutable Comparison</caption> 
    380380 
    381381    <thead> 
    …… 
    396396 
    397397    $(TR 
    398     $(TD invariant keyword) 
     398    $(TD immutable keyword) 
    399399    $(TD Yes) 
    400400    $(TD No) 
    …… 
    520520 
    521521    $(TR 
    522     $(TD aliasing of invariant with mutable) 
     522    $(TD aliasing of immutable with mutable) 
    523523    $(TD No: 
    524524--- 
    525 void foo(invariant int* x, int* y) 
     525void foo(immutable int* x, int* y) 
    526526{ 
    527527   bar(*x); // bar(3) 
    …… 
    531531... 
    532532int i = 3; 
    533 foo(cast(invariant)&i, &i); 
    534 --- 
    535     ) 
    536     $(TD No invariants) 
     533foo(cast(immutable)&i, &i); 
     534--- 
     535    ) 
     536    $(TD No immutables) 
    537537    ) 
    538538 
    539539    $(TR 
    540540    $(TD type of string literal) 
    541     $(TD invariant(char)[]) 
     541    $(TD immutable(char)[]) 
    542542    $(TD const char*) 
    543543    ) 
    …… 
    565565    Y=$(TD $(GREEN Yes)) 
    566566    N=$(TD $(RED No)) 
    567     TITLE=Const and Invariant 
     567    TITLE=Const and Immutable 
    568568    WIKI=ConstInvariant 
    569569    NO=<td class="compNo">No</td> 
    …… 
    575575    ERROR = $(RED $(B error)) 
    576576    COMMA=, 
    577 META_KEYWORDS=D Programming Language, const, invariant 
     577META_KEYWORDS=D Programming Language, const, immutable 
    578578META_DESCRIPTION=Comparison of const between the 
    579579D programming language, C++, and C++0x