"

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

"

"{ Package: 'stx:libbasic' }"

Magnitude subclass:#Character

	instanceVariableNames:'asciivalue'

	classVariableNames:'CharacterTable'

	poolDictionaries:''

	category:'Magnitude-General'

!

!Character class methodsFor:'documentation'!

copyright

"

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

"

    This class represents characters.

    Notice, that actual character objects are not used when characters

    are stored in strings, symbols or twoByteStrings; these only store

    a characters asciiValue for a more compact representation.

    The word 'asciiValue' is a historic leftover - actually, any integer

    code is allowed (i.e. characters are not limited to 8bit).

    Single byte Characters are unique; 

    i.e. for every asciiValue (0..255) there exists exactly one instance of 

    Character, which is shared (Character value:xxx checks for this, and returns 

    a reference to an existing instance).

    Other characters (i.e. asciivalue > 255) are not shared; i.e. these

    are created as required.

    This means: you may compare characters using #== ONLY IFF you are certain,

    that the characters ranges is 0..255. Otherwise, you HAVE TO compare

    using #=. (if in doubt, always compare using #=).

    Sorry for this inconvenience, but it is (practically) impossible to keep

    the possible maximum of 2^32 characters (Unicode) around, for that

    convenience alone.

    Methods marked as (JS) come from the manchester Character goody

    (CharacterComparing) by Jan Steinman, which allow Characters to be used as

    Interval elements (i.e. ($a to:$z) do:[...] ); 

    They are not a big deal, but convenient add-ons.

    Some of these have been modified a bit.

    WARNING: characters are known by compiler and runtime system -

	     do not change the instance layout. 

    Also, although you can create subclasses of Character, the compiler always

    creates instances of Character for literals ...

    ... and other classes are hard-wired to always return instances of characters

    in some cases (i.e. String>>at:, Symbol>>at: etc.).

    Therefore, it may not make sense to create a character-subclass.

    [author:]

	Claus Gittinger

    [see also:]

	String TwoByteString

	StringCollection

"

! !

!Character class methodsFor:'instance creation'!

basicNew

    "catch new - Characters cannot be created with new"

    ^ self error:'Characters cannot be created with new'

!

digitValue:anInteger

    "return a character that corresponds to anInteger.

     0-9 map to $0-$9, 10-35 map to $A-$Z"

    |val "{ Class: SmallInteger }" |

    val := anInteger.

    (val between:0 and:9) ifTrue:[

	^ Character value:(val + ($0 asciiValue))

    ].

    (val between:10 and:35) ifTrue:[

	^ Character value:(val + ($A asciiValue - 10))

    ].

    ^self error:'value not in range 0 to 35'

!

value:anInteger

    "return a character with asciivalue anInteger"

%{  /* NOCONTEXT */

    INT ascii;

    if (__isSmallInteger(anInteger)) {

	ascii = __intVal(anInteger);

	if ((ascii & ~0xFF) == 0 /* (ascii >= 0) && (ascii <= 255) */)

	    RETURN ( __MKCHARACTER(ascii) );

    }

%}.

    (anInteger between:0 and:16rFF) ifTrue:[

	^ CharacterTable at:(anInteger + 1)

    ].

    (anInteger between:16r100 and:16rFFFF) ifTrue:[

	^ super basicNew setAsciiValue:anInteger

    ].

    "

     a characters ascii-code must be 0..16rFFFF.

     (i.e. only single-byte and twoByte characters are allowed.)

    "

    self error:'invalid ascii code for character'

! !

!Character class methodsFor:'accessing untypeable characters'!

endOfInput

	"Answer the Character representing ctrl-d ."

	^self value: 4

!

leftParenthesis

	"Answer the Character representing a left parenthesis."

	^self value: 40

!

period

	"Answer the Character representing a carriage period."

	^self value: 46

!

poundSign

	"Answer the Character representing a pound sign."

	^self value: 35

!

rightParenthesis

	"Answer the Character representing a right parenthesis."

	^self value: 41

! !

!Character class methodsFor:'constants'!

backspace

    "return the backspace character"

    ^ Character value:8

!

bell

    "return the bell character"

    ^ Character value:7

!

cr

    "return the lineEnd character 

     - actually (in unix) this is a newline character"

    ^ Character value:10

!

del 

    "return the delete character"

    ^ Character value:16r7F 

!

doubleQuote

    "return the double-quote character"

    ^ Character value:34

!

esc

    "return the escape character"

    ^ Character value:27

!

excla

    "return the exclamation-mark character"

    ^ $!!

!

ff

    "return the form-feed character"

    ^ Character value:12

!

lf

    "return the newline/linefeed character"

    ^ Character value:10

!

linefeed

    "squeak compatibility: return the newline/linefeed character"

    ^ Character value:10

!

maxValue 

    "return the maximum asciiValue a character can have"

    ^ 16rFFFF

!

newPage

    "return the form-feed character"

    ^ Character value:12

!

nl

    "return the newline character"

    ^ Character value:10

!

quote

    "return the single-quote character"

    ^ Character value:39

!

return 

    "return the return character.

     In ST/X, this is different from cr - for Unix reasons."

    ^ Character value:13 

!

space

    "return the blank character"

    ^ Character value:32

!

tab

    "return the tabulator character"

    ^ Character value:9

! !

!Character class methodsFor:'primitive input'!

fromUser

    "return a character from the keyboard (C's standard input stream)

     - this should only be used for emergency evaluators and the like."

%{  /* NOCONTEXT */

    int c;

    c = getchar();

    if (c < 0) {

        RETURN (nil);

    }

    RETURN ( __MKCHARACTER(c & 0xFF) );

%}.

    ^ Stdin next

! !

!Character class methodsFor:'queries'!

allCharacters

    "added for squeak compatibility: return a collection of all chars"

    ^ CharacterTable

    "

     Character allCharacters 

    "

!

hasSharedInstances

    "return true if this class has shared instances, that is, instances

     with the same value are identical.

     False is returned here, only redefined in classes which have unified

     instances (or should be treated so)."

    ^ true

!

isBuiltInClass

    "return true if this class is known by the run-time-system.

     Here, true is returned for myself, false for subclasses."

    ^ self == Character

    "Modified: 23.4.1996 / 15:56:39 / cg"

!

separators

    "added for squeak compatibility: return a collection of separator chars"

    ^ Array 

	with:Character space

	with:Character cr

	with:Character tab

	with:Character lf

	with:Character ff

    "

     Character separators

    "

! !

!Character methodsFor:'accessing'!

asciiValue

    "return the asciivalue of myself.

     The name 'asciiValue' is a historic leftover - characters are not

     limited to 8bit characters.

     PP has removed this methhod with 4.1 and providing

     asInteger instead."

    ^asciivalue

    "Modified: 27.6.1996 / 12:34:34 / cg"

!

instVarAt:index put:anObject

    "catch instvar access - asciivalue may not be changed"

    self error:'Characters may not be modified'

!

newDigitValue

	"Answer 0-9 if the receiver is $0-$9, 10-35 if it is $A-$Z, and < 0 otherwise. 

	This is used to parse literal numbers of radix 2-36."

	| code value |

	code := self asInteger.

	value := code - $0 asInteger.

	value <= 9 ifTrue: [^value].

	value := code - $A asInteger.

	(value >= 0 and: [value < 26])

		ifTrue: [^value + 10].

	^-1

! !

!Character methodsFor:'arithmetic'!

+ aMagnitude

    "Return the Character that is <aMagnitude> higher than the receiver. 

     Wrap if the resulting value is not a legal Character value. (JS)"

    ^ Character value:(asciivalue + aMagnitude asInteger \\ 256)

    "

     $A + 5

    "

    "Modified: 27.6.1996 / 12:34:51 / cg"

!

- aMagnitude

    "Return the Character that is <aMagnitude> lower than the receiver.  

     Wrap if the resulting value is not a legal Character value. (JS)

     claus: 

	modified to return the difference as integer, if the argument

	is another character. If the argument is a number, a character is

	returned."

    aMagnitude isCharacter ifTrue:[

	^ self asciiValue - aMagnitude asciiValue

    ].

    ^ Character value:(asciivalue - aMagnitude asInteger \\ 256)

    "

     $z - $a  

     $d - 3

    "

    "Modified: 27.6.1996 / 12:35:34 / cg"

!

// aMagnitude

    "Return the Character who's value is the receiver divided by <aMagnitude>. 

     Wrap if the resulting value is not a legal Character value. (JS)"

    ^ Character value:(asciivalue // aMagnitude asInteger \\ 256)

!

\\ aMagnitude

    "Return the Character who's value is the receiver modulo <aMagnitude>.  

     Wrap if the resulting value is not a legal Character value. (JS)"

    ^ Character value:(asciivalue \\ aMagnitude asInteger \\ 256)

! !

!Character methodsFor:'binary storage'!

hasSpecialBinaryRepresentation

    "return true, if the receiver has a special binary representation"

    ^ true

!

storeBinaryOn:stream manager:manager

    "store a binary representation of the receiver on stream;

     redefined, since single-byte characters are stored more compact

     with a special type-code followed by the asciiValue."

    (asciivalue < 256) ifTrue:[

	stream nextPut:manager codeForCharacter; nextPut:asciivalue.

    ] ifFalse:[

	stream nextPut:manager codeForTwoByteCharacter.

	stream nextPutShort:asciivalue MSB:true

    ]

! !

!Character methodsFor:'comparing'!

< aCharacter

    "return true, if the arguments asciiValue is greater than mine"

    ^ (asciivalue < aCharacter asInteger)

!

<= aCharacter

    "return true, if the arguments asciiValue is greater or equal to mine"

    ^ (asciivalue <= aCharacter asInteger)

!

= aCharacter

    "return true, if the argument, aCharacter is the same character

     Redefined to take care of 16bit characters."

    self == aCharacter ifTrue:[^ true].

    aCharacter isCharacter ifFalse:[^ false].

    ^ (asciivalue = aCharacter asciiValue)

!

> aCharacter

    "return true, if the arguments asciiValue is less than mine"

    ^ (asciivalue > aCharacter asInteger)

!

>= aCharacter

    "return true, if the arguments asciiValue is less or equal to mine"

    ^ (asciivalue >= aCharacter asInteger)

!

hash

    "return an integer useful for hashing"

    ^ asciivalue

!

identityHash

    "return an integer useful for hashing on identity"

    asciivalue <= 255 ifTrue:[

	^ 4096 + asciivalue

    ].

    ^ super identityHash

!