eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Symbol':

Home

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

Class: Symbol


Inheritance:

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

Package:
stx:libbasic
Category:
Collections-Text
Version:
rev: 1.139 date: 2019/05/30 15:48:02
user: cg
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.

The most prominent use of symbols is as key for message sending: methods are stored
in a classes method dictionary, where symbols are used as key to map names to methods.
Also, symbols are used as key to map class names (global names) to actual class objects.

Special ST/X feature:
    The ST/X VM method lookup supports selector namespaces for method extensions.
    This means, that a class may contain method extensions in another namespace,
    which are only seen and invoked if called from a class within that namespace.
    Technically, this is done by storing the method under a special namespace-selector,
    which is a symbol consisting of the user visible name, prefixed by ':<ns>::'.
    The VM's method lookup algorithm contains special handling code for such constructs.
    Thus, if two methods are stored as 'foo' and ':NS::foo' are present in a class,
    any send of 'foo' from wíthin the NS-namespace will invoke the second method.
    Any other send will invoke the first one.


Class protocol:

Compatibility-ST80
o  tableSize
( an extension from the stx:libcompat package )
return the size of the system's symbol table

Compatibility-Squeak
o  allSymbols
( an extension from the stx:libcompat package )
self allSymbols

Javascript support
o  for: argument
Symbol.for(string) is the same as ST's string asSymbol

instance creation
o  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.

o  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).

o  intern: aString
return a unique symbol with printname taken from the String-argument

o  internCharacter: aCharacter
return a unique symbol with printname taken from the Character-argument

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

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

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

o  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

o  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:

Compatibility-Squeak
o  precedence
the precedence in an expression; 0 is highest;
unary < binary < keyword

usage example(s):

     self assert:(#foo precedence < #+ precedence).
     self assert:(#+ precedence < #key: precedence).
     self assert:(#foo precedence < #key: precedence).

Compatibility-VW
o  << catalogID
create and return a new UserMessage, with the receiver as key,
and the argument as cataglogID.
VW compatibility.

usage example(s):

     (#theFooMessage << #myMessages)
     (#theFooMessage << #myMessages >> 'cannot read subclass of metaclass')
     (#theFooMessage >> 'cannot read subclass of metaclass')

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

usage example(s):

     (#theFooMessage << #myMessages)
     (#theFooMessage << #myMessages >> 'cannot read subclass of metaclass')
     (#theFooMessage >> 'cannot read subclass of metaclass')

accessing
o  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.

o  formattedCode
( an extension from the stx:libtool package )
private helper for the CodeGenerator

o  nameSpace
if I have the format of a namespace-selector,
retrieve the namespace. Otherwise, return nil.
Also return nil, if that namespace does not exist (in contrast to nameSpacePart).
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.

usage example(s):

     #':foo:' nameSpace       -> nil (bad format)
     #':foo::bar' nameSpace   -> nil (non existing)
     #':Tools::bar' nameSpace -> Tools
     #'bar' nameSpace -> nil
     #'bar:' nameSpace -> nil

o  nameSpaceAndSelector
return a two element tuple consisting of the namespace and the raw selector.
If I do not have the format of a namespace-selector, or the namespace is non-existing,
the first element of the returned tuple will be nil.
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.

usage example(s):

     #':foo:bar' nameSpaceAndSelector     -> #(nil #':foo:bar')
     #':foo::bar' nameSpaceAndSelector    -> #(nil #bar)
     #':Tools::foo' nameSpaceAndSelector  -> #(Tools (* NameSpace *) #foo)

o  nameSpaceAndSelectorParts
return a two element tuple consisting of the namespace name and the raw selector.
If I do not have the format of a namespace-selector,
the first element of the returned tuple will be nil.
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.

usage example(s):

     #':foo:bar' nameSpaceAndSelectorParts     -> #(nil #':foo:bar')
     #':foo:bar' nameSpaceAndSelector          -> #(nil #':foo:bar')

     #':foo::bar' nameSpaceAndSelectorParts    -> #('foo' #bar)
     #':foo::bar' nameSpaceAndSelector         -> #(nil #bar)

     #'bar' nameSpaceAndSelectorParts          -> #(nil #bar)
     #'bar' nameSpaceAndSelector               -> #(nil #bar)

     #':Tools::foo' nameSpaceAndSelectorParts  -> #('Tools' #foo)
     #':Tools::foo' nameSpaceAndSelector       -> #(Tools (* NameSpace *) #foo)

o  nameSpacePart
if I have the format of a namespace-selector,
retrieve the namespace name. Otherwise, return nil.
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.

usage example(s):

     #':foo:' nameSpacePart       -> nil (bad format)
     #':foo::bar' nameSpacePart   -> 'foo'
     #':Tools::bar' nameSpacePart -> 'Tools'

o  selector
if I have the format of a namespace-selector, retrieve the raw selector.
Otherwise, return myself.
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen,
because almost every other selector is legal,
and this can be checked quickly in the VM, by just looking at the first character.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  selectorWithoutNameSpace
if I have the format of a namespace-selector, retrieve the raw selector.
Otherwise, return myself.
Namespace selectors have a special, fix defined format, which is also known in the VM.
They must be of the form :<ns>::<sel>,
where <ns> is the namespace and <sel> is the raw selector.
This special format (a symbol starting with a colon) was chosen, because almost every other selector
is legal, and this can be checked quickly by just looking at the first character.

usage example(s):

     #':foo:' selectorWithoutNameSpace       -> #':foo:' (bad format)
     #':foo::bar' selectorWithoutNameSpace   -> #bar
     #':Tools::bar' selectorWithoutNameSpace -> #bar

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

o  identityHash
interned symbols can return a better hash key

o  ~= 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.

converting
o  asClass
return the class named after me

usage example(s):

     #Array asClass 
     #Foo asClass 

o  asClassIfAbsent: exceptionValue
return the class named after me

usage example(s):

     #Array asClassIfAbsent:123
     #Foo asClassIfAbsent:123 

o  asImmutableCollection
I am immutable

o  asImmutableString
I am immutable

o  asString
return a string with printname taken from mine

o  asSymbol
Return a unique symbol with the name taken from the receiver's characters.
Since I am a symbol - just return myself

o  asSymbolIfInterned
If a symbol with the receiver's characters is already known, return it. Otherwise, return nil.
Since I am a symbol - just return myself

o  asSymbolIfInternedOrSelf

o  beImmutable
I am already immutable

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

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

o  deepCopyUsing: aDictionary postCopySelector: postCopySelector
return a deep copy of myself
- reimplemented here since symbols are immutable.

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

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

evaluation
o  value: anObject
this is sent by collection enumeration methods,
if a symbol is given instead of a block as loop-block argument

usage example(s):

     this enables the elegant construct:
         #(1 2 3 4 5 6 7) collect:#negated
      
     but also, as a side effect, this ugly thing (if the arg understands the receiver):
         #negated value:#(1 2 3 4 5 6 7)

o  value: el value: arg
this is sent by collection enumeration methods,
if a symbol is given instead of a block as loop-block argument

inspecting
o  inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package )
returns the icon to be shown alongside the value list of an inspector

o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

printing & storing
o  displayString
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.

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

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

o  storeOn: aStream
store myself on a stream

o  storeString
return a String for storing the receiver

usage example(s):

      #'abc'       storeString
      #'abc:'      storeString
      #'abc:def:'  storeString
      #'abc:def'   storeString
      #'abc::def'  storeString
      #'abc &^*'   storeString
      #'abcdef::'  storeString
      #'hello''world'  storeString
      #'' storeString
      #'''' storeString
      #'_hello' storeString
      #'123'  storeString

private array element printing
o  displayArrayElementOn: aStream
Display myself as an Array element on a stream.
I am displayed as an array element, so the '#' may be omitted sometimes.
Take care for special symbols

o  printArrayElementOn: aStream
Print myself as an Array element on a stream.
I am printed as an array element, so the '#' may be omitted sometimes.
Take care for special symbols

o  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

queries
o  species
when copying, or concatenating, return instances of this class

system primitives
o  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

o  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

o  grow: newSize
blocked

o  removeAll
blocked

testing
o  isImmutable
return true, if the receiver is immutable.
Since I am a symbol, return always true

o  isSingleByteString
returns true only for strings and immutable strings.
Must replace foo isMemberOf:String and foo class == String

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

tracing
o  traceInto: aRequestor level: level from: referrer
double dispatch into tracer, passing my type implicitely in the selector

visiting
o  acceptVisitor: aVisitor with: aParameter
dispatch for visitor pattern; send #visitSymbol:with: to aVisitor



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Thu, 26 May 2022 11:20:42 GMT