"
 COPYRIGHT (c) 1995 by Claus Gittinger
	      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.
"

Array subclass:#ImmutableArray
	 instanceVariableNames:''
	 classVariableNames:''
	 poolDictionaries:''
	 category:'System-Compiler-Support'
!

!ImmutableArray class methodsFor:'documentation'!

copyright
"
 COPYRIGHT (c) 1995 by Claus Gittinger
	      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.
"
!

documentation
"
    By default, array literals in smalltalk are mutable objects. That
    may lead to some subtle (and hard to find errors), if some method passes
    a literal array constant as argument to someone else, who changes the
    array using at:put: like messages. Since the array object is kept in 
    the first methods literals, the array constant has now been changed without
    having the methods sourcecode reflect this. Thus, the method will
    behave differently from what its source may make you think.

    To help finding this kind of 'feature/bug', the compiler can be
    configured to create instances of this ImmutableArray instead of Arrays
    for array literals. Instances of ImmutableArray catch storing accesses and
    enter the debugger. Although useful, this feature is disabled by default
    for compatibility to other smalltalk implementations. 
    (Also, if turned on, this makes inspecting array literals entered in
     a workspace somewhat strange: you cannot modify it any longer).

    Turn the ImmutableArray feature on by setting the Parsers class variable
    'ArraysAreImmutable' to true or use the new launchers settings menu.
"
!

version
    ^ '$Header: /cvs/stx/stx/libbasic/ImmutableArray.st,v 1.11 1995-11-23 02:13:03 cg Exp $'
! !

!ImmutableArray methodsFor:'accessing'!

at: index put: value
    "Trigger an error if an immutable array is stored into.
     The store will be performed (for compatibility reasons) if you continue
     in the debugger."

    self notifyStoreError.
    ^ super at: index put: value
!

basicAt: index put: value
    "Trigger an error if an immutable array is stored into.
     The store will be performed (for compatibility reasons) if you continue
     in the debugger."

    self notifyStoreError.
    ^ super basicAt: index put: value
! !

!ImmutableArray methodsFor:'copying'!

copyEmpty
    "when copying, return a real (mutable) Array"

    ^ Array new:self size
!

copyEmptyAndGrow:size
    "when copying, return a real (mutable) Array"

    ^ Array new:size
!

postCopy
    "when copied, make it me a real (mutable) Array"

    self changeClassTo:Array.
!

shallowCopy
    "when copying, return a real (mutable) Array"

    |sz|

    sz := self size.
    ^ (Array new:sz)
	replaceFrom:1 to:sz with:self startingAt:1
! !

!ImmutableArray methodsFor:'error handling'!

creator 
    "find the method that contains me"

    Method allSubInstances do:[:aMethod |
	|lits|

	lits := aMethod literals.
	(lits notNil and:[(lits identityIndexOf:self) ~~ 0]) ifTrue:[
	    ^ aMethod
	]
    ].
    ^ nil
!

notifyStoreError
    "a store is attempted - for our convenience, find the method that
     contains me, for a nicer error message"

    |creator msg|

    creator := self creator.
    msg := 'store into/change of literal'.
    creator notNil ifTrue:[
	msg := msg , ' (' , creator whoString , ')'
    ].
    "
     this error is reported on an attempt to store into a literal
     array. The literal was created in creator.
     If you press continue in the debugger, the store will be performed.
     If you dont want this, press abort and check your code.
     Storing into literals is VERY VERY bad coding style.
    "
    self error:msg
! !

!ImmutableArray methodsFor:'private'!

species
    "Copies should be mutable"

    ^Array
! !

!ImmutableArray methodsFor:'queries'!

isLiteral
    "return true, if the receiver can be used as a literal
     (i.e. can be used in constant arrays)"

    "yes, I must be"
    ^ true

! !

!ImmutableArray methodsFor:'specials'!

become:anotherObject
    "trigger an error if I should become something else
     (this would be an even more tricky manipulation)"

    self notifyStoreError.
    ^ super become:anotherObject
!

becomeNil
    "trigger an error if I should become nil
     (this would be an even more tricky manipulation)"

    self notifyStoreError.
    ^ super becomeNil
! !