eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Cons':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: Cons

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--Cons
            |
            +--ImmutableCons
            |
            +--LazyCons
Package:
stx:libbasic2
Category:
Collections-Linked
Version:
rev: 1.48 date: 2023/12/08 09:13:11
user: cg
file: Cons.st directory: libbasic2
module: stx stc-classLibrary: libbasic2

Description:


A pair as in lisp.
    Cons car:a cdr:b

Conses are not heavily used by Smalltalk (actually: not at all).
Consider this a demo class (it is used by the embedded Scheme interpreter, though).


copyright
COPYRIGHT (c) 2002 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

instance creation
o  car: carArg
return an cons with given car and NIL as cdr

o  car: carArg cdr: cdrArg
return an cons with given car and cdr

o  fromArray: anArray
return a Lisp-like cons-chain with elements from anArray

Usage example(s): 

     Cons fromArray:#(1 2 3 4)   
     Cons fromArray:#()    
     Cons fromArray:#(1)    
     Cons fromArray:(1 to:10000)

o  makeList: sizeArg
return a Lisp-like cons-chain with size elements.
Each car is nil

Usage example(s): 

     (self makeList:0) size    
     (self makeList:1) size    
     (self makeList:10) size    
     (self makeList:100) size
     (self makeList:1000) size 
     (self makeList:10000) size

sExpressions
o  readLispAtomFrom: aStream
read a number or symbol given in lisp syntax

o  readLispFrom: aStream
read a cons given in lisp syntax;
cares for EOL comments (introduced by ';')

Usage example(s): 

     self readLispFrom:('(cons 1 2)' readStream).            
     self readLispFrom:(c'(cons 1 ; foo \n 2)' readStream).

o  readLispListFrom: aStream
read a list in Lisp syntax

o  readLispStringFrom: aStream
a string in Scheme syntax; starts with double-quote,
may have embedded C-escapes.

Instance protocol:

accessing
o  at: n
for collection compatibility:
a very slow indexed accessor

Usage example(s): 

     (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

o  at: n put: newValue
destructive:
for collection compatibility: a very slow indexed accessor

Usage example(s): 

     |l|

     l := Cons fromArray:#(1 2 3 4).
     l at:1 put:'one'.
     l at:3 put:'three'.
     l

o  first
return the head, first or car - whatever you wonna call it

o  fourth
return the 3rd element

Usage example(s): 

     (BorgReader readFromString:'(10 20 30 40)') first   
     (BorgReader readFromString:'(10 20 30 40)') second  
     (BorgReader readFromString:'(10 20 30 40)') third   
     (BorgReader readFromString:'(10 20 30 40)') fourth   
     (BorgReader readFromString:'(10 20 30 40)') nth:1   
     (BorgReader readFromString:'(10 20 30 40)') nth:3   
     (BorgReader readFromString:'(10 20 30 40)') last

o  head
return the head, first or car - whatever you wonna call it

o  last
for lispers:
return the last element of a list

Usage example(s): 

     (Cons fromArray:#(1))       last     
     (Cons fromArray:#(1 2 3 4)) last

o  nth: n
for lispers:
return the nth element of a list

Usage example(s): 

     (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 fromArray:#( ))       nth:1  -> error

o  rest
return the tail, rest or cdr - whatever you wonna call it

o  reversed
for lispers:
return a new list with the cars in reverse order

Usage example(s): 

     (Cons fromArray:#(1))       reversed     
     (Cons fromArray:#(1 2))     reversed     
     (Cons fromArray:#(1 2 3 4)) reversed    
     (Cons fromArray:(1 to:10000)) reversed

o  second
return the 2nd element

o  tail
return the tail, rest or cdr - whatever you wonna call it

o  third
return the 3rd element

Usage example(s): 

     (BorgReader readFromString:'(10 20 30 40)') first   
     (BorgReader readFromString:'(10 20 30 40)') second  
     (BorgReader readFromString:'(10 20 30 40)') third   
     (BorgReader readFromString:'(10 20 30 40)') nth:1   
     (BorgReader readFromString:'(10 20 30 40)') nth:3   
     (BorgReader readFromString:'(10 20 30 40)') last

accessing-basic
o  cadddr
return the fourth element

o  caddr
return the third element

o  cadr
return the second element

o  car
return the head, first or car - whatever you wonna call it

o  car: newCar
set the head, first or car - whatever you wonna call it

o  car: carArg cdr: cdrArg
set both car and cdr

o  cddr
return the rest after the second element

o  cdr
return the tail, second or cdr - whatever you wonna call it

o  cdr: newCdr
set the tail, second or cdr - whatever you wonna call it

o  first: carArg rest: cdrArg
set both car and cdr

o  head: carArg tail: cdrArg
set both car and cdr

o  nthPair: n
a helper:
return the nth pair of a list

o  setCar: newCar
set the head, first or car - whatever you wonna call it

o  setCar: carArg setCdr: cdrArg
set both car and cdr

o  setCdr: newCdr
set the tail, second or cdr - whatever you wonna call it

comparing
o  = aCons
warning: this might be expensive for long lists

o  hash
warning: this might be expensive for long lists

copying
o  , aCollection
return a new list by concatenating elements from the receiver and the argument

Usage example(s): 

     |l1 l2|

     l1 := Cons fromArray:#(1 2 3 4).
     l2 := Cons fromArray:#(10 20 30 40).
     l1 , l2

Usage example(s): 

     |l1 l2|

     l1 := Cons fromArray:#(1 2 3 4).
     l1 , #(10 20 30 40)

o  copyEmpty: size
(comment from inherited method)
return a copy of the receiver with no elements, but space for
size elements. This is used by copying and enumeration methods
to get a new instance which is similar to the receiver.
This method should be redefined in subclasses with instance
variables, which should be put into the copy too.
For example, SortedCollection has to copy its sortBlock into the
new collection.

o  copyEmptyAndGrow: size
(comment from inherited method)
return a copy of the receiver with size nil elements.
This is used by copying and enumeration methods
to get a new instance which is similar to the receiver.

enumerating
o  do: aBlock
evaluate aBlock for each car;
raises an error if the receiver is a degenerated list (i.e. last cdr notNil)

list processing
o  append: aCons
for lispers:
append the arg. Return a new list, where the 2nd part is shared.
Destructive: the receiver's last cdr is modified.

Usage example(s): 

     (Cons fromArray:#(1 2 3 4)) 
        append:(Cons fromArray:#(5 6 7 8))

o  take: nTaken
for lispers:
take n elements from the front of the list;
return a new list

Usage example(s): 

^ Cons car:(self car) cdr:(self cdr take:nTaken-1)

Usage example(s): 

     (Cons fromArray:#(1 2 3 4)) take:3    
     (Cons fromArray:#(1)) take:0  
     (Cons fromArray:#()) take:3  
     (Cons fromArray:(1 to: 1000)) take:999  

     |gen allNumbers|
     gen := [:n | LazyCons car:n cdr:[ gen value:n+1 ]].
     allNumbers := gen value:1. 
     allNumbers take:10

printing
o  displayOn: aStream
(comment from inherited method)
print a representation of the receiver on aGCOrStream for display in inspectors etc.

o  displayString
(comment from inherited method)
return a string used when displaying the receiver in a view;
for example an Inspector. This is usually the same as printString,
but sometimes redefined for a better look.

Notice: displayString and displayOn: are for developers, debugging and inspectors,
whereas printString and printOn: are for the program to print data.

Note: the base method (used by the inspector) is #displayOn:.
So you should implement #displayOn: instead of #displayString in subclasses.

o  printOn: aStream
(comment from inherited method)
append a user readable representation of the receiver to aStream.
The text appended is not meant to be read back for reconstruction of
the receiver. Also, this method limits the size of generated string.

o  printRestOn: aStream

queries
o  beginAndSizeOfCycle
return the begin and size of a cycle, if the list contains one.
Nil otherwise.
Floyd's cycle-finding algorithm

Usage example(s): 

     |n1 n2 n3 n4 n5|

     n1 := Cons new car:1.
     n2 := Cons new car:2.
     n3 := Cons new car:3.
     n4 := Cons new car:4.
     n5 := Cons new car:5.
     n1 cdr: n2.
     n2 cdr: n3.
     n3 cdr: n4.
     n4 cdr: n5.
     n1 beginAndSizeOfCycle.           
     n5 cdr: n3.    
     n1 beginAndSizeOfCycle.

o  isCyclic
true if the list contains a cycle

Usage example(s): 

     |n1 n2 n3 n4 n5|

     n1 := Cons new car:1.
     n2 := Cons new car:2.
     n3 := Cons new car:3.
     n4 := Cons new car:4.
     n5 := Cons new car:5.
     n1 cdr: n2.
     n2 cdr: n3.
     n3 cdr: n4.
     n4 cdr: n5.
     n1 isCyclic.
     n5 cdr: n3.    
     n1 isCyclic.

o  length
the list's length

Usage example(s): 

     (Cons fromArray:#(1)) length       
     (Cons fromArray:#(1 2 3 4)) length    
     (Cons car:1 cdr:2) length          --> error (degenerated list)

o  size
the list's length

streaming
o  readStream
(comment from inherited method)
return a stream for reading from the receiver

testing
o  isCons

o  isImmutable
(comment from inherited method)
experimental - not yet usable; do not use.
For now the #isImmutable flag prohibits only #become*.

o  isLazy

Examples:


    |p1 p2 p3|

    p3 := Cons car:3 cdr:nil.
    p2 := Cons car:2 cdr:p3.
    p1 := Cons car:1 cdr:p2.
    p1 head.
    p1 tail.
    p1 size.
    p1 do:[:each | Transcript showCR:each].
    p1 at:2

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:29:51 GMT