"

 COPYRIGHT (c) 2009 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.

"

"{ Package: 'stx:libbasic' }"

ByteArray variableByteSubclass:#ImmutableByteArray

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'System-Compiler-Support'

!

!ImmutableByteArray class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 2009 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.

"

!

documentation

"

    By default, byte array literals in smalltalk are mutable objects. That

    may lead to some subtle (and hard to find errors), if some method passes

    a literal byte-array object as argument to someone else, who changes the

    bytearray using at:put: like messages. Since the bytearray object is kept in

    the first methods literals, the bytearray constant has now been changed without

    having the method's 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 ImmutableByteArray instead of ByteArrays

    for literals. Instances of ImmutableByteArray 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 bytearray literals entered in

     a workspace somewhat strange: you cannot modify it any longer).

    Turn the ImmutableArray feature on, by setting the Parser's class variable

    'ArraysAreImmutable' to true or use the new launchers settings menu.

    ATTENTION:

	there may be still code around which checks for explicit class being ByteArray

	(both in Smalltalk and in primitive code). All code like foo 'class == ByteArray'

	or '__isByteArray' will not work with ImmutableByteArrays.

	A somewhat better approach would be to either add a flag to the object (mutability)

	and check this dynamically (expensive) or to place immutable objects into a readonly

	memory segment (the good solution). We will eventually implement the second in the future...

    [see also:]

	ImmutableString

	ImmutableArray

	Parser Scanner

    [author:]

	Claus Gittinger

"

! !

!ImmutableByteArray methodsFor:'accessing'!

at:index put:value

    "Trigger an error if an immutable bytearray is stored into.

     The store will be performed (for compatibility reasons) if you continue

     in the debugger."

    self noModificationError.

    ^ super at:index put:value

!

basicAt:index put:value

    "Trigger an error if an immutable bytearray is stored into.

     The store will be performed (for compatibility reasons) if you continue

     in the debugger."

    self noModificationError.

    ^ super basicAt:index put:value

! !

!ImmutableByteArray methodsFor:'converting'!

asByteArray

    "return the receiver as a (mutable) byteArray"

    ^ self copy changeClassTo: ByteArray

    "

     #[1 2 3 4] asImmutableByteArray asByteArray

    "

!

asImmutableByteArray

    ^ self

! !

!ImmutableByteArray methodsFor:'copying'!

copyEmpty

    "when copying, return a real (mutable) ByteArray"

    ^ ByteArray new:self size

!

copyEmptyAndGrow:size

    "when copying, return a real (mutable) ByteArray"

    ^ ByteArray new:size

!

postCopy

    "when copied, make me a real (mutable) ByteArray"

    self changeClassTo:ByteArray.

!

postDeepCopy

    "when copied, make me a real (mutable) ByteArray"

    self changeClassTo:ByteArray.

    "

     #[1 2 3 4] asImmutableByteArray copy          class

     #[1 2 3 4] asImmutableByteArray shallowCopy   class

     #[1 2 3 4] asImmutableByteArray deepCopy      class

    "

!

shallowCopy

    "when copying, return a real (mutable) ByteArray"

    |sz|

    sz := self size.

    ^ (ByteArray new:sz)

	replaceFrom:1 to:sz with:self startingAt:1

! !

!ImmutableByteArray methodsFor:'error handling'!

creator

    "find the method that contains me"

    ^ Method allSubInstances detect:[:aMethod | (aMethod referencesGlobal:self)] ifNone:nil.

    "

      #(1 2 3) creator

    "

    "Modified: 24.6.1996 / 15:36:28 / stefan"

!

noModificationError

    "a store is attempted - for our convenience, find the method that

     contains me, for a nicer error message"

    |creator msg context|

    creator := self creator.

    creator notNil ifTrue:[

	msg := ' (' , creator whoString , ')'

    ].

    context := thisContext sender.

     "

     this error is reported on an attempt to store into a literal

     byte array. The literal was created in creator.

     If you press continue in the debugger, the store will be performed.

     If you don't want this, press abort and check your code.

     Storing into literals is VERY VERY bad coding style.

    "

    NoModificationError

	raiseRequestWith:self

	errorString:msg

	in:context.

    "Created: / 3.8.1998 / 14:47:45 / cg"

! !

!ImmutableByteArray methodsFor:'private'!

species

    "Copies should be mutable"

    ^ ByteArray

! !

!ImmutableByteArray methodsFor:'queries'!

isLiteral

    "return true, if the receiver can be used as a literal constant in ST syntax

     (i.e. can be used in constant arrays)"

    "yes, I must be"

    ^ true

!

referencesAny:aCollection

    "redefined to speed up searching when many byteArray instances are present"

    ^ false

! !

!ImmutableByteArray methodsFor:'specials'!

become:anotherObject

    "trigger an error if I should become something else

     (this would be an even more tricky manipulation)"

    self noModificationError.

    ^ super become:anotherObject

!

becomeNil

    "trigger an error if I should become nil

     (this would be an even more tricky manipulation)"

    self noModificationError.

    ^ super becomeNil

! !

!ImmutableByteArray class methodsFor:'documentation'!

version_CVS

    ^ '§Header: /cvs/stx/stx/libbasic/ImmutableByteArray.st,v 1.7 2009/11/16 08:59:40 stefan Exp §'

! !