changeset 31:8cc4f326fc66

Added documentation about array types.

--- a/README.txt	Sat Jan 19 18:27:00 2013 +0000
+++ b/README.txt	Sat Jan 19 23:19:02 2013 +0000
@@ -62,12 +62,11 @@
      natural       - integers starting at 0 or 1 
      bool          - true or false (Matlab allows 0 or 1)
      string        - Matlab string (array of characters)
-     A..B          - Integers between A and B inclusive
-     A--B          - Real numbers between A and B inclusive
-     [A]           - Integers between 1 and A inclusive
-     [A,B,..]      - Comma separated list of integers in 1..A, 1..B etc (used for array domains) 
+     N..M          - Integers between N and M inclusive
+     X--Y          - Real numbers between X and Y inclusive
+     [N]           - Integers between 1 and N inclusive
      A|B           - Non-discrimitated union, value of type A or B (not recommended to use if possible)
-     {A,B,C}       - Value from the enumerated set, eg {0,1,2} is equivalent to 0..2 (also deprecated)
+     {X,Y,...}     - Value from the enumerated set, eg {0,1,2} is equivalent to 0..2 (also deprecated)
 
   Array types
 
@@ -75,6 +74,12 @@
      [D]           - Array with domain D and real elements
      {D->R}        - Cell array with domain D and elements of type R
 
+     The array domain D is written as the literal array that would be returned as the
+	  size of the array, eg [N,N] for a square N-by-N array, or [N] for an N-by-1 array.
+	  Hence the types of these arrays could be [[N,N]] and [[N]->integer] respectively.
+	  Higher dimensional array types are written analogously: [[N,M,L]], etc..
+	 
+	
   Function types
 
      <type_list> -> <type_list>   - A functional function (no side effects) with input and output types.
@@ -185,6 +190,54 @@
 	  We then let void denote Z{:}, that is, an empty comma separated list. This means
 	  that void now truly denotes 0 types, not one degenerate type.
 
+     The comma-separated lists idea can also be used to account for the types 
+     of multidimensional arrays, which are rather like functions from one or more
+     integers to the array element type; in Matlab, the array reference x(i,j,k)
+     even looks like a function call f(i,j,k). If we suppose that: 
+
+        [N,M,L]      
+
+	  denotes the type of comma separated lists of 3 integers between 1 and N, M and L
+	  respectively, then
+
+	  	  [[N,M,L]->R]
+	
+	  is the type of 3 dimensional arrays of size [N,M,L] with elements of type R.
+	  Compare this with the equivalent type of functions of 3 integer arguments
+
+	     1..N, 1..M, 1..L -> R 
+	  or    [N], [M], [L] -> R
+
+     Thus, by analogy, we could write the function type as [N,M,L] -> R, or the
+	  array type as [1.N,1..M,1..L->R]. Alternatively, sometimes, we may assume
+	  that Size is a 1-by-E array Size=[n1,...,nE] and write
+
+	     [Size->R]
+
+	  as the array type. I have previously allowed such declarations to decorate size
+	  with a type annotation to indicate that it is a 1-by-E array and therefore that
+	  the type is of E-dimensional array, like this:
+
+	     [Size:[[1,E]]->R]
+
+	  but after writing the section on dependent types and variable length type lists,
+	  I realised this was inconsistent, and that the such *meta* type annotations
+	  should be written consistently, eg using the @ notation suggested above, which
+	  would give, in full,
+	  
+	     [Size@[[1,E]->natural]->R]
+		  
+	  for the type of E-dimensional arrays of elements of type R. An alternative would be 
+
+	     [D{1:E}->R]
+
+	  but this leaves implicit the assumption that N is a cell array types which
+	  must all be 1..N for appropriate integers N. A more succinct notation might be
+
+	     [S@size(E)->R]
+
+	  where the meta-type size(E) denotes the set of types that look like [N,M,...],
+	  ie that look like arrays of the type [[1,E]->natural].
 
   User-defined types
 
@@ -192,7 +245,7 @@
      A is the new type and B is an existing type, or in terms of user-defined Matlab
      classes, such as the sequence, signal and arrow types in this library.
 
-     For, the arrow type is written as
+     For example, the arrow type is written as
 
 	     arrow(A,B,C)
 
@@ -206,6 +259,7 @@
         struct {
            proc     :: A{:} => B{:};
            getstate :: void => C;
-			  ...
+           setstate :: C => void;
+           ...
         }