"

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

"

String subclass:#ImmutableString

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'System-Compiler-Support'

!

!ImmutableString class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1998 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, string literals in smalltalk are mutable objects. That

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

    a string constant as argument to someone else, who changes the

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

    the first methods literals, the string 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 ImmutableString instead of Strings

    for string literals. Instances of ImmutableString 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 string literals entered in

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

    Turn the ImmutableString feature on by setting the Parsers class variable

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

    [see also:]

        ImmutableArray

        Parser Scanner

    [author:]

        Claus Gittinger

"

! !

!ImmutableString methodsFor:'accessing'!

at:index put:value

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

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

     in the debugger."

    self notifyStoreError.

    ^ super at:index put:value

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

! !

!ImmutableString methodsFor:'copying'!

copyEmpty

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

    ^ String new:self size

    "Created: / 3.8.1998 / 14:46:22 / cg"

!

copyEmptyAndGrow:size

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

    ^ String new:size

    "Created: / 3.8.1998 / 14:46:34 / cg"

!

postCopy

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

    self changeClassTo:String.

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

!

shallowCopy

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

    |sz|

    sz := self size.

    ^ (String new:sz) replaceFrom:1 to:sz with:self startingAt:1

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

! !

!ImmutableString methodsFor:'error handling'!

creator 

    "find the method that contains me"

    Method allSubInstances do:[:aMethod |

        (aMethod referencesGlobal:self) ifTrue:[

            ^ aMethod.

        ].

    ].

    ^ nil

    " 

      'hello' creator

    "

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

!

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

     string. 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

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

! !

!ImmutableString methodsFor:'private'!

species

    "Copies should be mutable"

    ^ String

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

! !

!ImmutableString methodsFor:'queries'!

isLiteral

    "return true, if the receiver can be used as a literal

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

    "yes, I must be"

    ^ true

    "Created: / 3.8.1998 / 14:48:13 / cg"

! !

!ImmutableString 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

    "Created: / 3.8.1998 / 14:48:29 / cg"

!

becomeNil

    "trigger an error if I should become nil

     (this would be an even more tricky manipulation)"

    self notifyStoreError.

    ^ super becomeNil

    "Created: / 3.8.1998 / 14:48:37 / cg"

! !

!ImmutableString class methodsFor:'documentation'!

version

    ^ '$Header: /cvs/stx/stx/libbasic/ImmutableString.st,v 1.1 1998-08-03 17:08:28 cg Exp $'

! !