Changeset 1810
- Timestamp:
- 08/05/10 18:34:02 (2 years ago)
- Files:
-
- trunk/docsrc/arrays.dd (modified) (31 diffs)
- trunk/docsrc/changelog.dd (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/docsrc/arrays.dd
r1663 r1810 135 135 ) 136 136 137 <h2> Usage</h2>137 <h2>$(LNAME2 usage, Usage)</h2> 138 138 139 139 $(P There are two broad kinds of operations to do on an array - … … 171 171 --------- 172 172 173 <h2> <a name="slicing">Slicing</a></h2>173 <h2>$(LNAME2 slicing, Slicing)</h2> 174 174 175 175 $(P $(I Slicing) an array means to specify a subarray of it. … … 216 216 --------- 217 217 218 <h2> Array Copying</h2>218 <h2>$(LNAME2 array-copying, Array Copying)</a></h2> 219 219 220 220 $(P When the slice operator appears as the lvalue of an assignment … … 249 249 ) 250 250 251 <h2> Array Setting</h2>251 <h2>$(LNAME2 array-setting, Array Setting)</h2> 252 252 253 253 $(P If a slice operator appears as the lvalue of an assignment … … 265 265 --------- 266 266 267 <h2> Array Concatenation</h2>267 <h2>$(LNAME2 array-concatenation, Array Concatenation)</a></h2> 268 268 269 269 $(P The binary operator ~ is the $(I cat) operator. It is used … … 285 285 286 286 --------- 287 "10" + 3 288 --------- 289 290 $(P produce the number 13 or the string "103" as the result? It isn't 291 obvious, and the language designers wind up carefully writing rules 292 to disambiguate it - rules that get incorrectly implemented, 293 overlooked, forgotten, and ignored. It's much better to have + mean 294 addition, and a separate operator to be array concatenation. 287 "10" + 3 + 4 288 --------- 289 290 $(P produce the number 17, the string "1034" or the string "107" as the 291 result? It isn't obvious, and the language designers wind up carefully 292 writing rules to disambiguate it - rules that get incorrectly 293 implemented, overlooked, forgotten, and ignored. It's much better to 294 have + mean addition, and a separate operator to be array 295 concatenation. 295 296 ) 296 297 … … 311 312 --------- 312 313 313 314 $(COMMENT 315 <h2>Array Operations</h2> 316 317 $(P $(B Note): Array operations are not implemented. 318 ) 319 320 $(P In general, (a[n..m] $(I op) e) is defined as: 321 ) 322 323 --------- 324 for (i = n; i < m; i++) 325 a[i] $(I op) e; 326 --------- 327 328 $(P So, for the expression: 329 ) 330 331 --------- 332 a[] = b[] + 3; 333 --------- 334 335 $(P the result is equivalent to:) 336 337 --------- 338 for (i = 0; i < a.length; i++) 339 a[i] = b[i] + 3; 340 --------- 341 342 $(P When more than one [] operator appears in an expression, the range 343 represented by all must match. 344 ) 345 346 --------- 347 a[1..3] = b[] + 3; // error, 2 elements not same as 3 elements 348 --------- 349 ) 350 314 $(P Appending does not always create a copy, see $(LINK2 #resize, 315 setting dynamic array length) for details. 316 ) 351 317 352 318 <h2>$(LNAME2 array-operations, Array Operations)</h2> … … 402 368 ) 403 369 404 <h2> Pointer Arithmetic</h2>370 <h2>$(LNAME2 pointer-arithmetic, Pointer Arithmetic)</h2> 405 371 406 372 --------- … … 427 393 --------- 428 394 429 <h2> Rectangular Arrays</h2>395 <h2>$(LNAME2 rectangular-arrays, Rectangular Arrays)</h2> 430 396 431 397 $(P Experienced FORTRAN numerics programmers know that multidimensional … … 457 423 --------- 458 424 459 <h2> Array Length</h2>425 <h2>$(LNAME2 array-length, Array Length)</h2> 460 426 461 427 $(V1 … … 497 463 --------- 498 464 499 <h2> Array Properties</h2>465 <h2>$(LNAME2 array-properties, Array Properties)</h2> 500 466 501 467 $(P Static array properties are:) … … 647 613 648 614 --------- 649 p.length // error, length not known for pointer 650 s.length // compile time constant 3 651 a.length // runtime value 652 653 p.dup // error, length not known 654 s.dup // creates an array of 3 elements, copies 615 int* p; 616 int[3] s; 617 int[] a; 618 619 p.length; // error, length not known for pointer 620 s.length; // compile time constant 3 621 a.length; // runtime value 622 623 p.dup; // error, length not known 624 s.dup; // creates an array of 3 elements, copies 655 625 // elements s into it 656 a.dup // creates an array of a.length elements, copies626 a.dup; // creates an array of a.length elements, copies 657 627 // elements of a into it 658 628 --------- 659 629 660 <h3> <a name="resize">Setting Dynamic Array Length</a></h3>630 <h3>$(LNAME2 resize, Setting Dynamic Array Length)</h3> 661 631 662 632 $(P The $(B $(TT .length)) property of a dynamic array can be set … … 670 640 $(P This causes the array to be reallocated in place, and the existing 671 641 contents copied over to the new array. If the new array length is 672 shorter, 673 only enough are copied to fill the new array. If the new array length 674 is longer, the remainder is filled out with the default initializer. 642 shorter, the array is not reallocated, and no data is copied. It is 643 equivalent to slicing the array: 644 645 --------- 646 array = array[0..7]; 647 --------- 648 649 If the new array length is longer, the remainder is filled out with the 650 default initializer. 675 651 ) 676 652 677 653 $(P To maximize efficiency, the runtime always tries to resize the 678 array in place to avoid extra copying. It will always do a copy 679 if the new size is larger and the array was not allocated via the 680 new operator or a previous 681 resize operation. 682 ) 683 684 $(P This means that if there is an array slice immediately following the 654 array in place to avoid extra copying. 655 $(V1 It will always do a copy if the new size is larger and the array 656 was not allocated via the new operator or a previous resize operation.) 657 $(V2 It will always do a copy if the new size is larger and the array 658 was not allocated via the new operator or resizing in place would 659 overwrite valid data in the array.) 660 ) 661 662 $(V1 $(P This means that if there is an array slice immediately following the 685 663 array being resized, the resized array could overlap the slice; i.e.: 686 664 ) … … 706 684 // the old a[3] 707 685 --------- 686 ) 687 688 $(V2 689 For example: 690 691 --------- 692 char[] a = new char[20]; 693 char[] b = a[0..10]; 694 char[] c = a[10..20]; 695 char[] d = a; 696 697 b.length = 15; // always reallocates because extending in place would 698 // overwrite other data in a. 699 b[11] = 'x'; // a[11] and c[1] are not affected 700 701 d.length = 1; 702 d.length = 20; // also reallocates, because doing this will overwrite a and 703 // c 704 705 c.length = 12; // may reallocate in place if space allows, because nothing 706 // was allocated after c. 707 c[5] = 'y'; // may affect contents of a, but not b or d because those 708 // were reallocated. 709 710 a.length = 25; // This always reallocates because if c extended in place, 711 // then extending a would overwrite c. If c didn't 712 // reallocate in place, it means there was not enough space, 713 // which will still be true for a. 714 a[15] = 'z'; // does not affect c, because either a or c has reallocated. 715 --------- 716 ) 708 717 709 718 $(P To guarantee copying behavior, use the .dup property to ensure 710 a unique array that can be resized. 711 ) 712 713 $(P These issues also apply to concatenating arrays with the ~ and ~= 714 operators. 719 a unique array that can be resized. $(V2 Also, one may use the phobos 720 $(TT .capacity) property to determine how many elements can be appended 721 to the array without reallocating.) 722 ) 723 724 $(P These issues also apply to appending arrays with the ~= operator. 725 Concatenation using the ~ operator is not affected since it always 726 reallocates. 715 727 ) 716 728 … … 754 766 ) 755 767 756 <h3>Functions as Array Properties</h3> 768 $(V2 $(P Also, you may wish to utilize the phobos $(TT reserve) 769 function to pre-allocate array data to use with the append operator.)) 770 771 <h3>$(LNAME2 func-as-property, Functions as Array Properties)</h3> 757 772 758 773 $(P If the first parameter to a function is an array, the … … 768 783 --- 769 784 770 <h2> <a name="bounds">Array Bounds Checking</a></h2>785 <h2>$(LNAME2 bounds, Array Bounds Checking)</h2> 771 786 772 787 $(P It is an error to index an array with an index that is less than 773 788 0 or greater than or equal to the array length. If an index is 774 out of bounds, an ArrayBoundsError exception is raised if detected 775 at runtime, and an error if detected at compile time. 776 777 789 out of bounds, $(V1 an ArrayBoundsError)$(V2 a RangeError) exception is 790 raised if detected at runtime, and an error if detected at compile 791 time. A program may not rely on array bounds checking happening, for 792 example, the following program is incorrect: 778 793 ) 779 794 … … 815 830 ) 816 831 817 <h2> Array Initialization</h2>818 819 <h3> Default Initialization</h3>832 <h2>$(LNAME2 array-initialization, Array Initialization)</h2> 833 834 <h3>$(LNAME2 default-initialization, Default Initialization)</h3> 820 835 821 836 $(UL … … 827 842 ) 828 843 829 <h3> Void Initialization</h3>844 <h3>$(LNAME2 void-initialization, Void Initialization)</h3> 830 845 831 846 $(P Void initialization happens when the $(I Initializer) for … … 837 852 ) 838 853 839 <h3> Static Initialization of Static Arrays</h3>854 <h3>$(LNAME2 static-init-static, Static Initialization of Static Arrays)</h3> 840 855 841 856 $(P Static initalizations are supplied by a list of array … … 863 878 864 879 865 <h2> Special Array Types</h2>866 867 < a name="strings"><h3>Strings</h3></a>880 <h2>$(LNAME2 special-array, Special Array Types)</h2> 881 882 <h3>$(LNAME2 strings, Strings)</h3> 868 883 869 884 $(P A string is … … 959 974 960 975 --------- 976 $(V1 961 977 cast(wchar [])"abc" // this is an array of wchar characters 962 978 "abc"w // so is this 979 ) 980 $(V2 981 cast(immutable(wchar) [])"abc" // this is an array of wchar characters 982 "abc"w // so is this 983 ) 963 984 --------- 964 985 … … 977 998 w = 'bc'; // error - only one wchar character at a time 978 999 w = "b"[0]; // w is assigned the wchar character 'b' 979 w = \r[0]; // w is assigned the carriage return wchar character1000 w = "\r"[0]; // w is assigned the carriage return wchar character 980 1001 d = 'd'; // d is assigned the character 'd' 981 1002 --------- 982 1003 983 <h4> C's printf() and Strings</h4>1004 <h4>$(LNAME2 printf, C's printf() and Strings)</h4> 984 1005 985 1006 $(P $(B printf()) is a C function and is not part of D. $(B printf()) … … 1031 1052 --------- 1032 1053 1033 <h3> Implicit Conversions</h3>1054 <h3>$(LNAME2 implicit-conversions, Implicit Conversions)</h3> 1034 1055 1035 1056 $(P A pointer $(TT $(I T)*) can be implicitly converted to … … 1063 1084 1064 1085 <hr> 1065 <h1> <a name="associative">Associative Arrays</a></h1>1086 <h1>$(LNAME2 associative, Associative Arrays)</h1> 1066 1087 1067 1088 $(P Associative arrays have an index that is not necessarily an integer, … … 1104 1125 ) 1105 1126 1106 <h3> Using Classes as the KeyType</h3>1127 <h3>$(LNAME2 classes-as-keys, Using Classes as the KeyType)</h3> 1107 1128 1108 1129 $(P Classes can be used as the $(I KeyType). For this to work, … … 1133 1154 1134 1155 $(V1 int $(B opEquals)(Object o))$(V2 bool $(B opEquals)(Object o)) 1135 { Foo f = cast(Foo) o;1136 return f && a == foo.a && b == foo.b;1156 { Foo foo = cast(Foo) o; 1157 return foo && a == foo.a && b == foo.b; 1137 1158 } 1138 1159 1139 1160 int $(B opCmp)(Object o) 1140 { Foo f = cast(Foo) o;1141 if (!f )1161 { Foo foo = cast(Foo) o; 1162 if (!foo) 1142 1163 return -1; 1143 1164 if (a == foo.a) … … 1153 1174 the class objects are the same or not.) 1154 1175 1155 <h3> Using Structs or Unions as the KeyType</h3>1176 <h3>$(LNAME2 structs-as-keys, Using Structs or Unions as the KeyType)</h3> 1156 1177 1157 1178 $(P If the $(I KeyType) is a struct or union type, … … 1179 1200 $(V1 hash_t $(B toHash)() 1180 1201 { hash_t hash; 1181 foreach (char c; s )1202 foreach (char c; str) 1182 1203 hash = (hash * 9) + c; 1183 1204 return hash; … … 1195 1216 $(V2 const hash_t $(B toHash)() 1196 1217 { hash_t hash; 1197 foreach (char c; s )1218 foreach (char c; str) 1198 1219 hash = (hash * 9) + c; 1199 1220 return hash; … … 1218 1239 the struct/union objects are the same or not.) 1219 1240 1220 <h3> Properties</h3>1241 <h3>$(LNAME2 aa-properties, Properties)</h3> 1221 1242 1222 1243 Properties for associative arrays are: … … 1292 1313 1293 1314 <hr> 1294 <h3> Associative Array Example: word count</h3>1315 <h3>$(LNAME2 aa-example, Associative Array Example: word count)</h3> 1295 1316 1296 1317 --------- trunk/docsrc/changelog.dd
r1773 r1810 62 62 $(LI $(BUGZILLA 3853): core.sys.posix.stdio.pclose is missing) 63 63 $(LI $(BUGZILLA 3917): opEquals for Ojbect could be more efficient) 64 $(LI $(BUGZILLA 4551): D2 Language Docs: http://www.digitalmars.com/d/2.0/arrays.html) 65 $(LI $(BUGZILLA 4590): Spec incorrectly describes array appending and memory stomping) 64 66 ) 65 67 )