Class: Symbol

• Inheritance
• Description
• Class protocol
  • Compatibility-ST80
  • binary storage
  • instance creation
  • queries
• Instance protocol
  • Compatibility-Squeak
  • Compatibility-VW
  • accessing
  • binary storage
  • comparing
  • converting
  • copying
  • printing & storing
  • queries
  • system primitives
  • tracing
  • visiting

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ByteArray
                  |
                  +--CharacterArray
                     |
                     +--String
                        |
                        +--Symbol

Package:

stx:libbasic

Category:

Collections-Text

Version:

rev: 1.90 date: 2010/03/06 13:45:51

user: stefan

file: Symbol.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Symbols represent unique strings - every symbol with same printString
exists exactly once in the system; Symbols are used for selectors, global
variable-keys etc. Symbols can also be used to represent things which are
enumeration type values in other programming languages (since symbols are
created at compile time, comparing them using == is a fast pointer compare).

A symbol may not change its characters - i.e. it is constant over its lifetime.
Other than that, symbols behave much like strings.

Class protocol:

 tableSize

return the size of the systems symbol table

 binaryDefinitionFrom: stream manager: manager

retrieve a symbol from a binary input stream (nonpublic interface)

 basicNew: size

redefined to return a string instead of a symbol -
this allows all copy methods inherited from String to
return strings containing the symbols characters.
Real symbols are only created with #intern: or #asSymbol.

 fromString: aString

same as intern: for Symbol, but may be used to create interned instances
of subclasses.
Notice: this fails, if you try to intern an instance of a subclass, AND
a symbol with the same name already exists. In this case, the original
symbol is returned. To use it for enum-type symbols, make certain, that the
names are unique (for example by including the classes name as a prefix-string).

 intern: aString

return a unique symbol with printname taken from the String-argument

 internCharacter: aCharacter

return a unique symbol with printname taken from the Character-argument

 new: size

redefined to return a string instead of a symbol -
this allows all copy methods inherited from String to
return strings containing the symbols characters.
Real symbols are only created with intern: or asSymbol.

 findInterned: aString

for ST-80 compatibility - if the argument, aString is known
as Symbol, return this symbol. Otherwise return nil.

 hasInterned: aString

return true, if the argument, aString is known as Symbol;
false otherwise

 hasInterned: aString ifTrue: trueBlock

for ST-80 compatibility - if the argument, aString is known
as Symbol, evaluate the block with the corresponding symbol
as argument and return true; otherwise return false

 hasSharedInstances

return true if this class has shared instances, that is, instances
with the same value are identical.
True returned here - there is only one of each symbol (per contents).

Instance protocol:

 isUnary

 << catalogID

create and return a new UserMessage, with the receiver as key,
and the argument as cataglogID.
VW compatibility.

 >> aString

create and return a new UserMessage, with the receiver as key,
and the argument as defaultString.
VW compatibility.

 basicAt: index put: something

report an error if an interned symbol is about to be changed
- interned symbols may NOT be changed.
For uninterned symbols, this is allowed.

 identityHashForBinaryStore

may not use inherited identityHashForBinaryStore, because it changes the internal object hash,
which is actually not used for symbols.

 storeBinaryDefinitionOn: stream manager: manager

append a binary representation of the receiver onto stream.
Redefined since short Symbol can be stored with a special type code
in a more compact way.
This is an internal interface for the binary storage mechanism.

 = something

return true, if the receiver and argument consist of the same characters.
Redefined here, for more efficient #= comparison of symbols
(which ought to be compared using #==).
If the argument is a symbol, we use a quick pointer compare, instead of
the inherited value compare.

 identityHash

interned symbols can return a better hash key

 ~= something

return true, if the receiver and argument do not consist of the same characters.
Redefined here, for more efficient #~= comparison of symbols
(which ought to be compared using #~~).
If the argument is a symbol, we use a quick pointer compare, instead of
the inherited value compare.

 asString

return a string with printname taken from mine

 asSymbol

Return a unique symbol with the name taken from the receivers characters.
Since I am a symbol - just return myself

 asSymbolIfInterned

If a symbol with the receivers characters is already known, return it. Otherwise, return nil.
Since I am a symbol - just return myself

 copy

return a copy of myself
- reimplemented here since symbols are immutable.

 copyReplaceAll: oldElement with: newElement

return a copy of the receiver as a string, where all elements equal to oldElement
have been replaced by newElement.

 copyReplacing: oldElement withObject: newElement

return a copy of the receiver, where all elements equal to oldElement
have been replaced by newElement.
ANSI version of what used to be #copyReplaceAll:with:

 deepCopy

return a copy of myself
- reimplemented here since symbols are immutable.

 deepCopyUsing: aDictionary postCopySelector: postCopySelector

return a deep copy of myself
- reimplemented here since symbols are immutable.

 shallowCopy

return a copy of myself
- reimplemented here since symbols are immutable and unique,
so we return the receiver.

 simpleDeepCopy

return a copy of myself
- reimplemented here since symbols are immutable.

 displayString

return a string for displaying the receiver in a view (inspector)

 printOn: aStream

append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

In contrast to ST-80, this does return the symbols characters
without any leading #. Therefore, you can directly send symbols'
printStrings to some output device. This is incompatible, but easier
to use.

 printString

return a printed representation of the receiver.
In contrast to ST-80, this does return the symbols characters
without any leading #. Therefore, you can directly send symbols'
printStrings to some output device. This is incompatible, but easier
to use.

 storeArrayElementOn: aStream

store myself on a stream.
I am stored as an array element, so the '#' may be omitted sometimes.
Take care for special symbols

 storeOn: aStream

store myself on a stream

 storeString

return a String for storing the receiver

 isInfix

return true, if the receiver is a binary message selector

 isKeyword

return true, if the receiver is a keyword message selector

 isSymbol

return true, if the receiver is some kind of symbol.
Since I am a symbol, return always true

 keywords

assuming the receiver is a keyword message selector,
return the individual keywords (i.e. break it up at colons)
and return these as a collection.
For binary and unary selectors, the result may be nonsense.

 species

when copying, or concatenating, return instances of this class

 become: anotherObject

make all references to the receiver become references to anotherObject
and vice-versa. For symbols, some special action is required, to
correctly handle a become of the global dictionaries.
Anyway: this is very dangerous - mysterous side-effects are to be
expected.

Notice: because of the danger here, this method may report an error
in future versions

 becomeNil

make all references to the receiver become nil - effectively getting
rid of the receiver. For symbols, this is not allowed, if the receiver
is used as a key in some SystemDictionary.
This can be a very dangerous operation - be warned.

Notice: because of the danger here, this method may report an error
in future versions

 traceInto: aRequestor level: level from: referrer

double dispatch into tracer, passing my type implicitely in the selector

 acceptVisitor: aVisitor with: aParameter