--- a/Cons.st	Wed Jul 31 21:24:45 2002 +0200
+++ b/Cons.st	Wed Jul 31 21:34:07 2002 +0200
@@ -39,7 +39,13 @@
 "
     A pair as in lisp.
     Create with:
-        a # b
+        a !! b
+    or:
+        Cons car:a cdr:b
+
+    Conses are not heavily used by Smalltalk (actually: not at all).
+    Consider this mostly a demo class.
+
 
     [author:]
         Claus Gittinger
@@ -70,34 +76,40 @@
     ^ first.
 
     "
-     self fromArray:#(1 2 3 4)
-     self fromArray:#()    
-     self fromArray:#(1)    
+     Cons fromArray:#(1 2 3 4)   
+     Cons fromArray:#()    
+     Cons fromArray:#(1)    
     "
 ! !
 
 !Cons methodsFor:'accessing'!
 
 at:n
+    "for collection compatibility:
+     a slow indexed accessor"
+
     ^ (self nth:n) car
 
     "
-     (self fromArray:#(1))       at:1     
-     (self fromArray:#(1 2 3 4)) at:1 
-     (self fromArray:#(1 2 3 4)) at:3  
-     (self fromArray:#(1 2 3 4)) at:4  
-     (self fromArray:#(1 2 3 4)) at:5  
+     (Cons fromArray:#(1))       at:1     
+     (Cons fromArray:#(1 2 3 4)) at:1 
+     (Cons fromArray:#(1 2 3 4)) at:3  
+     (Cons fromArray:#(1 2 3 4)) at:4  
+     (Cons fromArray:#(1 2 3 4)) at:5  
     "
 !
 
 at:n put:newValue
+    "for collection compatibility:
+     a slow indexed accessor"
+
     (self nth:n) car:newValue.
     ^ newValue.
 
     "
      |l|
 
-     l := self fromArray:#(1 2 3 4).
+     l := Cons fromArray:#(1 2 3 4).
      l at:1 put:'one'.
      l at:3 put:'three'.
      l       
@@ -105,6 +117,9 @@
 !
 
 last
+    "for lispers:
+     return the last element of a list"
+
     |p rest|
 
     p := self.
@@ -114,12 +129,15 @@
     ^ p
 
     "
-     (self fromArray:#(1))       last     
-     (self fromArray:#(1 2 3 4)) last    
+     (Cons fromArray:#(1))       last     
+     (Cons fromArray:#(1 2 3 4)) last    
     "
 !
 
 nth:n
+    "for lispers:
+     return the nth element of a list"
+
     |cnt p|
 
     cnt := n.
@@ -135,43 +153,43 @@
     ].
 
     "
-     (self fromArray:#(1))       nth:1     
-     (self fromArray:#(1 2 3 4)) nth:1 
-     (self fromArray:#(1 2 3 4)) nth:3  
-     (self fromArray:#(1 2 3 4)) nth:4  
-     (self fromArray:#(1 2 3 4)) nth:5  
+     (Cons fromArray:#(1))       nth:1     
+     (Cons fromArray:#(1 2 3 4)) nth:1 
+     (Cons fromArray:#(1 2 3 4)) nth:3  
+     (Cons fromArray:#(1 2 3 4)) nth:4  
+     (Cons fromArray:#(1 2 3 4)) nth:5  
     "
 ! !
 
 !Cons methodsFor:'accessing - basic'!
 
 car
-    "return the value of the instance variable 'car' (automatically generated)"
+    "return the head, first or car - whatever you wonna call it"
 
     ^ car
 !
 
 car:something
-    "set the value of the instance variable 'car' (automatically generated)"
+    "set the head, first or car - whatever you wonna call it"
 
     car := something.
 !
 
 car:carArg cdr:cdrArg 
-    "set instance variables (automatically generated)"
+    "set both car and cdr"
 
     car := carArg.
     cdr := cdrArg.
 !
 
 cdr
-    "return the value of the instance variable 'cdr' (automatically generated)"
+    "return the tail, second or cdr - whatever you wonna call it"
 
     ^ cdr
 !
 
 cdr:something
-    "set the value of the instance variable 'cdr' (automatically generated)"
+    "set the tail, second or cdr - whatever you wonna call it"
 
     cdr := something.
 ! !
@@ -179,6 +197,9 @@
 !Cons methodsFor:'list processing'!
 
 append:aCons
+    "for lispers:
+     append the arg. Return a new list, where the 2nd part is shared"
+
     |p rest|
 
     p := self.
@@ -189,7 +210,19 @@
     ^ self
 
     "
-     (self fromArray:#(1 2 3 4)) append:(self fromArray:#(5 6 7 8))    
+     (Cons fromArray:#(1 2 3 4)) 
+        append:(Cons fromArray:#(5 6 7 8)) 
+    "
+
+    "sharing demonstrated:
+
+     |a b ab|
+
+     a := Cons fromArray:#(1 2 3 4).
+     b := Cons fromArray:#(5 6 7 8).
+     ab := a append:b.
+     b car:'five'.
+     ab    
     "
 ! !
 
@@ -226,6 +259,8 @@
 !
 
 size
+    "for smalltalkers: the lists length"
+
     |l p rest|
 
     l := 1.
@@ -237,14 +272,14 @@
     ^ l
 
     "
-     (self fromArray:#( )) size 
-     (self fromArray:#(1)) size     
-     (self fromArray:#(1 2 3 4)) size    
+     (Cons fromArray:#( )) size    
+     (Cons fromArray:#(1)) size     
+     (Cons fromArray:#(1 2 3 4)) size    
     "
 ! !
 
 !Cons class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic2/Cons.st,v 1.2 2002-07-31 19:24:45 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/Cons.st,v 1.3 2002-07-31 19:34:07 cg Exp $'
 ! !