--- a/Array.st	Tue Feb 04 21:09:59 2014 +0100
+++ b/Array.st	Wed Apr 01 10:20:10 2015 +0100
@@ -11,6 +11,8 @@
 "
 "{ Package: 'stx:libbasic' }"
 
+"{ NameSpace: Smalltalk }"
+
 ArrayedCollection variableSubclass:#Array
 	instanceVariableNames:''
 	classVariableNames:''
@@ -36,10 +38,10 @@
 
 documentation
 "
-    Instances of Array store general objects; the arrays size is fixed,
-    therefore add:/remove: are not allowed.
+    Instances of Array store general objects; 
+    an array's size is fixed, therefore add:/remove: are not allowed.
     (actually, #add: is implemented for compatibility with smalltalks which
-     provide it, but it is very slow and outputs an annoying warning message ...)
+     provide it, but it is very slow and outputs an annoying warning message...)
 
     Access to the individual elements is via an integer index,
     using the well-known access messages #at: and #at:put:.
@@ -51,14 +53,13 @@
 
     Notice that Array is a built-in class
     (i.e. the VM knows about its representation).
-    Therefore it is NOT possible to add named instance variables or change
-    Arrays inheritance.
+    Therefore it is NOT possible to add named instance variables or change Arrays inheritance.
     However, subclassing is allowed of course
     - even with added named instance variables.
 
     Literal arrays (i.e. array-constants) are entered in source as:
 
-	#( element1 element2 ... element-n)
+        #( element1 element2 ... element-N)
 
     where each element must be itself a literal constant.
     Array, symbol and byteArray constants within an array can be written
@@ -73,20 +74,40 @@
       #(nil true #true)       -> 3 elements: nil, true and a symbol (watch out)
       #(two [3 3 3] (4 4 4))  -> 3 elements: a symbol, a byteArray and another array
 
+    Also, a syntactic sugar piece allows for Array instances to be created dynamcially
+    at runtime with the brace syntax:
+
+        { expr1 . expr2 . ... . expr-N }
+
+    where each expr-i evaluates to an element of the new array instance.
+    Notice that the expressions are separated by a period.
+    Semantically, this is equivalent to ``Array with:expr1 with:expr2 ... with:expr-N''
+    Examples:
+        { 1 . 2 . 3 }         -> a new 3 element array; similar to #( 1 2 3 ),
+                                 but in contrast, a new array instance is created
+        { 
+            { 'foo' . [ Transcript showCR:'foo' ] } .
+            { 'bar' . [ Transcript showCR:'bar' ] } 
+            { 'baz' . [ Transcript showCR:'baz' ] } 
+        }                     
+                              -> a new 3 element array, consisting of 3 new
+                                 2-element array instances, consisting of a string
+                                 and a block each
+
     [memory requirements:]
-	OBJ-HEADER + (size * ptr-size)
+        OBJ-HEADER + (size * ptr-size)
 
     [warning:]
-	read the warning about 'growing fixed size collection'
-	in ArrayedCollection's documentation
+        read the warning about 'growing fixed size collection'
+        in ArrayedCollection's documentation
 
     [author:]
-	Claus Gittinger
+        Claus Gittinger
 
     [see also:]
-	OrderedCollection
-	ByteArray FloatArray DoubleArray
-	String
+        OrderedCollection
+        ByteArray FloatArray DoubleArray IntegerArray BitArray
+        CharacterArray String
 "
 ! !
 
@@ -280,6 +301,7 @@
     "Modified: 23.4.1996 / 15:55:06 / cg"
 ! !
 
+
 !Array methodsFor:'accessing'!
 
 at:index
@@ -453,7 +475,6 @@
 beImmutable
     "make myself write-protected"
 
-    "/ self assert:(ImmutableArray notNil).
     self changeClassTo:ImmutableArray
 
     "Created: / 07-06-2012 / 11:06:33 / cg"
@@ -1830,13 +1851,13 @@
 
 refersToLiteral:aLiteral
     "return true if the receiver or recursively any array element in the
-     receiver referes to aLiteral (i.e. a deep search)"
+     receiver refers to aLiteral (i.e. a deep search)"
 
     self do: [ :el |
-	el == aLiteral ifTrue:[^true].
-	el class == Array ifTrue:[
-	    (el refersToLiteral: aLiteral) ifTrue: [^true]
-	]
+        el == aLiteral ifTrue:[^true].
+        el class == Array ifTrue:[
+            (el refersToLiteral: aLiteral) ifTrue: [^true]
+        ]
     ].
     ^ false
 
@@ -2612,10 +2633,10 @@
 !Array class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.161 2013-12-05 11:34:23 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.165 2015-02-03 13:54:47 stefan Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.161 2013-12-05 11:34:23 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Array.st,v 1.165 2015-02-03 13:54:47 stefan Exp $'
 ! !