"{ Encoding: utf8 }"

"

 COPYRIGHT (c) 1994 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' }"

"{ NameSpace: Smalltalk }"

UninterpretedBytes variableByteSubclass:#CharacterArray

	instanceVariableNames:''

	classVariableNames:'DecoderTables DecodingFailedSignal EncoderTables

		EncodingFailedSignal PreviousMatches UnicodeDenormalizationMap

		UnicodeNormalizationMap'

	poolDictionaries:''

	category:'Collections-Text'

!

!CharacterArray class methodsFor:'documentation'!

copyright

"

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

"

    CharacterArray is a superclass for all kinds of Strings (i.e.

    (singleByte-)Strings, TwoByteStrings, UnicodeStrings

    and whatever may come in the future.

    This class is abstract, meaning that there are no instances of it;

    concrete subclasses define how the characters are stored (i.e. either as

    single byte, two-byte or four byte strings).

    All this class does is provide common protocol for concrete subclasses.

    Notice:

        internally, ST/X uses a unicode encoding for ALL characters - both

        for individual chatacter entities and for strings of characters.

        When reading/writing files in different encodings, the conversion is

        done at read/write time by use of a CharacterEncoder instance.

        These know how to convert to a wide range of encodings.

    Also notice:

        UTF8 and UTF16 are external encodings of a Unicode string; they are never

        used internally. When interacting with a UTF8 interface (OS-API or files),

        you should convert UTF8 into the internal full Unicode right at the interface.

        Do not keep UTF8 around internally as String instances.

        The reason is that UTF8 makes it harder to manipulate strings (for example

        to insert/extract substrings or to get its size. Of such operations would

        require a scan of the UTF8, which would complicate them).

        Of course, there may be rare exceptions to this, for example if a file's contents

        is treated as raw data, and the strings have to be copied/shuffled around only,

        without any real processing on it.

    [about hashing:]

        the ST/X VM uses the fnv1 hash (*) to quickly retrieve symbols,

        This has only 1 collision in my current systm with 66k symbols.

        To try, evaluate:

            ((Symbol allInstances collect:#hash_fnv1a as:Bag)

                valuesAndCountsSelect:[:h :cnt | cnt > 1]) size

        in contrast, java hash is much worse (18 collisions):

            ((Symbol allInstances collect:#hash_java as:Bag)

                valuesAndCountsSelect:[:h :cnt | cnt > 1]) size

        and hash_sdbm hash is even better (0 collisions),

        but slightly slower:

            ((Symbol allInstances collect:#hash_sdbm as:Bag)

                valuesAndCountsSelect:[:h :cnt | cnt > 1]) size

        we could use CRC32 (also with 0 collisions), 

        but that is slower on machines without CRC instruction:

            ((Symbol allInstances collect:[:s | CRC32Stream hashValueOf:s] as:Bag)

                valuesAndCountsSelect:[:h :cnt | cnt > 1]) size

        (*) slightly modified to return a 31bit positive number, eg. a SmallInt in 32bit systems.

    [author:]

        Claus Gittinger

    [see also:]

        String TwoByteString Unicode16String Uniode32String

        StringCollection

"

! !

!CharacterArray class methodsFor:'initialization'!

initialize

    DecodingFailedSignal isNil ifTrue:[

        DecodingFailedSignal := DecodingError.

        DecodingFailedSignal notifierString:'error during decode'.

        EncodingFailedSignal := EncodingError.

        EncodingFailedSignal notifierString:'error during encode'.

    ]

    "

     CharacterArray initialize

    "

    "Modified: / 03-08-1997 / 18:15:59 / cg"

    "Modified (format): / 16-01-2018 / 18:57:10 / stefan"

! !

!CharacterArray class methodsFor:'instance creation'!

basicNew

    "return a new empty string"

    ^ self basicNew:0

!

fromBytes:aByteCollection

    "return an instance of the receiver class,

     taking untranslated bytes from the argument, aByteCollection

     in most-significant first order.

     Only useful, when reading twoByteStrings from external sources."

    ^ self fromBytes:aByteCollection MSB:true

    "

     Unicode16String fromBytes:#[16r02 16r20]

     Unicode16String fromBytes:#[16r02 16r20] MSB:true

     Unicode16String fromBytes:#[16r02 16r20] MSB:false

    "

    "Modified: 30.6.1997 / 20:08:37 / cg"

!

fromBytes:aByteCollection MSB:msb

    "return an instance of the receiver class,

     taking untranslated bytes from the argument, aByteCollection

     in the given byte order.

     Only useful, when reading twoByteStrings from external sources."

    |mySize nBytes newString dstIdx|

    self assert:(self ~~ CharacterArray). "/ only works for concrete subclasses.

    "/ the following is a quite inefficient implementation.

    "/ consider rewriting, if heavily used.

    nBytes := aByteCollection size.

    mySize := self basicNew bitsPerCharacter.

    mySize == 16 ifTrue:[

        newString := self uninitializedNew:(nBytes // 2).

        dstIdx := 1.

        msb ifTrue:[

            aByteCollection pairWiseDo:[:hi :lo |

                newString at:dstIdx put:(Character value:(hi bitShift:8)+lo).

                dstIdx := dstIdx + 1

            ].

        ] ifFalse:[

            aByteCollection pairWiseDo:[:lo :hi |

                newString at:dstIdx put:(Character value:(hi bitShift:8)+lo).

                dstIdx := dstIdx + 1

            ].

        ].

        ^ newString.

    ].

    ^ (self uninitializedNew:nBytes) replaceFrom:1 with:aByteCollection

    "

     Unicode16String fromBytes:#[16r02 16r20]

    "

    "Modified: 30.6.1997 / 20:08:37 / cg"

!

fromString:aString

    "return a copy of the argument, aString"

    |sz|

    sz := aString size.

    ^ (self uninitializedNew:sz) replaceFrom:1 to:sz with:aString startingAt:1

    "

        Unicode16String fromString:'hello'

        String fromString:'hello' asUnicode16String

        Unicode16String fromString:'hello' asUnicode16String

    "

!

fromStringCollection:aCollectionOfStrings

    "return a new string formed by concatenating each in aCollectionOfStrings"

    ^ self fromStringCollection:aCollectionOfStrings separatedBy:''

    "

     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this')

    "

    "Created: / 20-11-1995 / 15:26:59 / cg"

    "Modified (comment): / 05-06-2019 / 14:28:35 / Claus Gittinger"

!

fromStringCollection:aCollectionOfStrings separatedBy:aSeparatorString

    "return a new string formed by concatenating each in aCollectionOfStrings

     separating them by aSeparatorString"

    |stream|

    aCollectionOfStrings do:[:eachString |

        stream isNil ifTrue:[

            stream := self writeStreamClass with:eachString.

        ] ifFalse:[

            stream

                nextPutAll:aSeparatorString;

                nextPutAll:eachString.

        ].

    ].

    stream isNil ifTrue:[^ ''].

    ^ stream contents

    "

     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this') separatedBy:' '

     String fromStringCollection:#('hello' 'world' 'how' 'about' 'this') separatedBy:'Ƞ'

     Text fromStringCollection:{'hello'. 'world'. 'how' allBold. 'about'. 'this'. 'äöü'} separatedBy:'Ƞ'

    "

    "Created: / 20-11-1995 / 15:32:17 / cg"

    "Modified (comment): / 05-06-2019 / 14:27:46 / Claus Gittinger"

!

fromUTF8Bytes:aByteCollection

    <resource: #obsolete>

    "return a new string which represents the characters as decoded

     from the utf8 encoded bytes, aByteCollection.

     Returns either a normal String, or a TwoByteString instance.

     Only useful, when reading twoByteStrings from external sources.

     This only handles up-to 16bit characters"

    ^ self decodeFromUTF8:aByteCollection.

    "Modified (comment): / 07-02-2017 / 17:32:38 / stefan"

!

new

    "return a new empty string"

    ^ self basicNew:0

!

readSmalltalkStringFrom:aStreamOrString keepCRs:keepCRs onError:exceptionBlock

    "read & return the next String from the (character-)stream aStream;

     skipping all whitespace first; return the value of exceptionBlock,

     if no string can be read. The sequence of characters as read from the

     stream must be one as stored via storeOn: or storeString.

     If keepCRs is true, CRLF is kept as is.

     A variant of this code is also found in the Scanner class (libcomp);

     however, libcomp is optional, whereas this is always present,

     and string reading is needed for resource file and config file parsing (sigh)"

    |str collected char withCEscapes|

    str := aStreamOrString readStream.

    "skip whiteSpace"

    str skipSeparators.

    (withCEscapes := (str peekOrNil == $c)) ifTrue:[

        str next.

    ].

    (str peekOrNil == $') ifTrue:[

        str next.

        collected := self writeStream.

        [(char := str nextOrNil) notNil] whileTrue:[

            char == $' ifTrue:[

                "/ look for another quote

                str peekOrNil ~~ $' ifTrue:[

                    "end of string reached"

                    ^ collected contents.

                ].

                "eat doubled quote"

                str next.

            ].

            (withCEscapes and:[char == $\]) ifTrue:[

                char := str nextOrNil ? char.

                char == $r ifTrue:[

                    char := Character return

                ] ifFalse:[

                    char == $n ifTrue:[

                        char := Character linefeed

                    ] ifFalse:[

                        char == $b ifTrue:[

                            char := Character backspace

                        ] ifFalse:[

                            char == $t ifTrue:[

                                char := Character tab

                            ]

                        ]

                    ]

                ].

            ].

            keepCRs ifTrue:[

                collected nextPut:char.

            ] ifFalse:[

                "compress CRLF to LF, but keep a single CR"

                ((char ~~ Character return) or:[str peekOrNil ~~ Character lf]) ifTrue:[

                    collected nextPut:char.

                ]

            ].

        ].

        "if we come here, we reached the end without finding a closing $'"

    ].

    ^ exceptionBlock value

    "

     String readSmalltalkStringFrom:('''hello world''' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('''hello '''' world''' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('1 ''hello'' ' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('1 ''hello'' ' readStream) onError:['foobar']

     String readSmalltalkStringFrom:('''hello\nworld''' readStream) onError:[self halt. 'foobar'] 

     String readSmalltalkStringFrom:('''hello\nworld''' readStream) keepCRs:false onError:[self halt. 'foobar']   

     String readSmalltalkStringFrom:('c''hello\nworld''' readStream) keepCRs:false onError:[self halt. 'foobar'] 

    "

    "Created: / 05-07-2006 / 16:41:04 / cg"

    "Modified: / 06-10-2006 / 14:05:32 / cg"

    "Modified (comment): / 02-08-2019 / 10:10:46 / Stefan Vogel"

!

readSmalltalkStringFrom:aStreamOrString onError:exceptionBlock

    "read & return the next String from the (character-)stream aStream;

     skipping all whitespace first; return the value of exceptionBlock,

     if no string can be read. The sequence of characters as read from the

     stream must be one as stored via storeOn: or storeString."

    ^ self readSmalltalkStringFrom:aStreamOrString keepCRs:false onError:exceptionBlock

    "

     String readSmalltalkStringFrom:('''hello world''' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('''hello '''' world''' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('1 ''hello'' ' readStream) onError:[self halt]

     String readSmalltalkStringFrom:('1 ''hello'' ' readStream) onError:['foobar']

    "

    "Created: / 05-07-2006 / 16:41:04 / cg"

    "Modified: / 06-10-2006 / 14:05:32 / cg"

    "Modified (comment): / 02-08-2019 / 10:10:46 / Stefan Vogel"

!

readSmalltalkStringWithCRsFrom:aStreamOrString onError:exceptionBlock

    "read & return the next String from the (character-)stream aStream;

     skipping all whitespace first; return the value of exceptionBlock,

     if no string can be read. The sequence of characters as read from the

     stream must be one as stored via storeOn: or storeString.

     Different from #readSmalltalStringFrom:onError: we keep CRLF as is."

    ^ self readSmalltalkStringFrom:aStreamOrString keepCRs:true onError:exceptionBlock

    "

     String readSmalltalkStringWithCRsFrom:('''hello world''' readStream) onError:[self halt]  

     String readSmalltalkStringWithCRsFrom:('''hello '''' world''' readStream) onError:[self halt]

     String readSmalltalkStringWithCRsFrom:('1 ''hello'' ' readStream) onError:[self halt]

     String readSmalltalkStringWithCRsFrom:('1 ''hello'' ' readStream) onError:['foobar']

    "

    "Created: / 01-08-2019 / 16:11:25 / Stefan Vogel"

    "Modified: / 02-08-2019 / 10:11:06 / Stefan Vogel"

!

writeStreamClass

    "the type of stream used in writeStream.

     Here, we return CharacterWriteStream, which automatically changes

     the underlying collection to a multiByte string (i.e. UnicodeString).

     So you can stream wide characters into it."

    ^ CharacterWriteStream

    "

     String writeStream

     - the following delivers a Unicode16String:

     String streamContents:[:s |

         s nextPut:(Character value:16r3f30).

         s nextPutAll:'hello'.

         s cr.

     ] 

    "

    "Created: / 09-01-2011 / 10:37:57 / cg"

! !

!CharacterArray class methodsFor:'Compatibility-VW'!

fromIntegerArray: anArray

    "Answer a new instance of the receiver that is created from the argument, anArray."

    | new |

    new := self new: anArray size.

    1 to: anArray size do:[:index |

        new at: index put: (anArray at: index) asCharacter

    ].

    ^new

    "

     String fromIntegerArray: #[8 127]

    "

! !

!CharacterArray class methodsFor:'Signal constants'!

decodingFailedSignal

    "return the signal, raised when decoding of a string is not possible

     due to invalid characters contained in the source.

     This may happen for example, if a non EUC coded 8-bit string

     is attempted to be decoded into a JIS string."

    ^ DecodingError

    "Created: / 28-06-1997 / 20:09:55 / cg"

    "Modified: / 03-08-1997 / 18:16:47 / cg"

    "Modified: / 16-01-2018 / 18:58:10 / stefan"

!

encodingFailedSignal

    "return the (query-) signal, raised when encoding of a string is not possible

     due to invalid characters contained in the source."

    ^ EncodingError

    "Modified: / 28-06-1997 / 20:09:35 / cg"

    "Created: / 03-08-1997 / 18:16:40 / cg"

    "Modified: / 16-01-2018 / 18:59:04 / stefan"

! !

!CharacterArray class methodsFor:'cleanup'!

lowSpaceCleanup

    "cleanup in low-memory situations"

    DecoderTables := EncoderTables := nil

    "

     CharacterArray lowSpaceCleanup

    "

    "Created: 22.2.1996 / 16:30:30 / cg"

    "Modified: 22.2.1996 / 17:58:05 / cg"

! !

!CharacterArray class methodsFor:'encoding & decoding'!

decodeFromUTF8:aStringOrByteCollection

    "given a string in UTF8 encoding,

     return a new string containing the same characters, in Unicode encoding.

     Returns either a normal String, a Unicode16String or a Unicode32String instance.

     This is only useful, when reading from external sources or communicating with

     other systems 

     (ST/X never uses utf8 internally, but always uses strings of fully decoded unicode characters).

     This only handles up-to 30bit characters."

    |decodedSize nBitsRequired

     codepoint "{ Class: SmallInteger }"

     byte  "{ Class: SmallInteger }"

     encodedSize  "{ Class: SmallInteger }"

     srcIdx  "{ Class: SmallInteger }"

     idx  "{ Class: SmallInteger }"

     nFollowBytes  "{ Class: SmallInteger }"

     minValue "{ Class: SmallInteger }"

     newString|

    encodedSize := aStringOrByteCollection size.

    decodedSize := aStringOrByteCollection utf8DecodedSize.