"

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

"

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Arrayed'

!

!ByteArray class methodsFor:'documentation'!

copyright

"

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

"

    ByteArrays store integers in the range 0..255.

    In contrast to normal arrays (which store pointers to their elements),

    byteArrays store the values in a dense & compact way. ByteArrays can

    be used to hold the data for bitmaps, images and other bulk data.

    ByteArrays are also used to store the bytecode-instructions of an

    interpreted method and are used as superclass for Strings.

    ByteArrays can be used as literals i.e. you can enter ByteArray-constants

    as #[ element1 element2 .... elementN] and also use byteArray constants

    as elements in a constant array.

    As in: #( #[1 1 1] #[2 2 2] #[3 3 3])

    If you have to communicate structure-data (in the C-sense) with external

    programs/data-bases, see a companion class (Structure) in the goodies directory.

    It allows the definition of subclasses of ByteArray, which transparently fetch

    and store C-structure fields.

    [warning:]

	read the warning about 'growing fixed size collection'

	in ArrayedCollection's documentation

    [author:]

	Claus Gittinger

    [See also:]

	Array CharacterArray String

"

! !

!ByteArray class methodsFor:'instance creation'!

fromPackedString:aString

    "ST-80 compatibility: decode a byteArray from a packed string in which

     6bits are encoded per character. The argument, aString must be a multiple 

     of 4 in size (since 24 is the lcm of 6 and 8). This is somewhat like

     the radix-encoding used in good old PDP11 times ;-)

     ST-80 uses this encoding for Images ...

     PS: It took a while to figure that one out ... I dont like it ;-)"

    |index    "{ Class: SmallInteger }"

     dstIndex "{ Class: SmallInteger }"

     stop     "{ Class: SmallInteger }"

     sixBits  "{ Class: SmallInteger }"

     n        "{ Class: SmallInteger }"

     sz       "{ Class: SmallInteger }"

     lastCharacter bytes|

    sz := aString size.

    sz == 0 ifTrue:[^ self new].

    stop := sz // 4 * 3.

    "the size modulo 3 is encoded in the last character, if its in the

     range 97 .. otherwise, its exact."

    lastCharacter := aString last.

    lastCharacter asciiValue > 96 ifTrue:[

        stop := stop - 3 + lastCharacter asciiValue - 96

    ].

    bytes := self new:stop.

    index := 1. dstIndex := 1.

    [dstIndex <= stop] whileTrue:[

        "take 4 characters ..."

        sixBits := (aString at:index) asciiValue.

        sixBits := sixBits bitAnd:16r3F.

        n := sixBits.

        sixBits := (aString at:index+1) asciiValue.

        sixBits := sixBits bitAnd:16r3F.

        n := (n bitShift:6) + sixBits.

        sixBits := (aString at:index+2) asciiValue.

        sixBits := sixBits bitAnd:16r3F.

        n := (n bitShift:6) + sixBits.

        sixBits := (aString at:index+3) asciiValue.

        sixBits := sixBits bitAnd:16r3F.

        n := (n bitShift:6) + sixBits.

        index := index + 4.

        "/ now have 24 bits in n

        bytes at:dstIndex put:(n bitShift:-16).

        dstIndex < stop ifTrue:[

            bytes at:dstIndex+1 put:((n bitShift:-8) bitAnd:16rFF).

            dstIndex+2 <= stop ifTrue:[

                bytes at:dstIndex+2 put:(n bitAnd:16rFF).

            ]

        ].

        dstIndex := dstIndex + 3.

    ].

    ^ bytes

    "

     ByteArray fromPackedString:(#[1 1 1 1] asPackedString) 

     ByteArray fromPackedString:(#[1 1 1 1 1] asPackedString) 

     ByteArray fromPackedString:(#[1 1 1 1 1 1] asPackedString) 

     ByteArray fromPackedString:(#[1 1 1 1 1 1 1] asPackedString) 

     ByteArray fromPackedString:(#[1 1 1 1 1 1 1 1] asPackedString)

    "

    "Modified: / 6.3.1997 / 15:28:52 / cg"

    "Modified: / 18.12.1997 / 17:17:11 / stefan"

!

uninitializedNew:anInteger

    "return a new instance of the receiver with uninitialized

     (i.e. undefined) contents. The indexed elements have any random

     value. However, any named instance variables are still nilled. 

     For use, when contents will be set anyway shortly after - this

     is a bit faster than the regular basicNew:, which clears the bytes.

     Of course, it only makes a difference for very big ByteArrays, such

     as used for images/bitmaps.

     Notice: if you want to port code using uninitializedNew: to another

     smalltalk, you have to add an 'uninitializedNew: -> basicNew:'-calling 

     method to the ByteArray class of the other smalltalk."

%{  /* NOCONTEXT */

    OBJ newobj;

    INT instsize, nInstVars, nindexedinstvars;

    REGISTER OBJ *op;

    if (__isSmallInteger(anInteger)) {

	nindexedinstvars = __intVal(anInteger);

	if (nindexedinstvars >= 0) {

	    if (self == ByteArray) {

		/*

		 * the most common case

		 */

		instsize = OHDR_SIZE + nindexedinstvars;

		if (__CanDoQuickNew(instsize)) {        /* OBJECT ALLOCATION */

		    __qCheckedNew(newobj, instsize);

		    __InstPtr(newobj)->o_class = self;

		    RETURN (newobj );

		}

	    }

	    nInstVars = __intVal(__ClassInstPtr(self)->c_ninstvars);

	    instsize = OHDR_SIZE + __OBJS2BYTES__(nInstVars) + nindexedinstvars;

	    __PROTECT_CONTEXT__

	    __qNew(newobj, instsize);   /* OBJECT ALLOCATION */

	    __UNPROTECT_CONTEXT__

	    if (newobj != nil) {

		__InstPtr(newobj)->o_class = self;

		__qSTORE(newobj, self);

		if (nInstVars) {

		    /*

		     * still have to nil out named instvars ...

		     */

#if defined(memset4) && defined(FAST_OBJECT_MEMSET4)

		    memset4(__InstPtr(newobj)->i_instvars, nil, nInstVars);

#else

# if defined(FAST_MEMSET) && !defined(NEGATIVE_ADDRESSES)

		    /*

		     * knowing that nil is 0

		     */

		    memset(__InstPtr(newobj)->i_instvars, 0, instsize - OHDR_SIZE);

# else

		    op = __InstPtr(newobj)->i_instvars;

		    while (nInstVars--)

			*op++ = nil;

# endif

#endif

		}

		RETURN ( newobj );

	    }

	}

    }

%}

.

    (anInteger isMemberOf:SmallInteger) ifTrue:[

	(anInteger < 0) ifTrue:[

	    ^ self error:'bad (negative) argument to new'

	].

	"

	 memory allocation failed.

	 When we arrive here, there was no memory, even after

	 a garbage collect. This means, that the VM wanted to

	 get some more memory from the Operatingsystem, which

	 was not kind enough to give some.

	"

	^ ObjectMemory allocationFailureSignal raise.

    ].

    ^ self basicNew:anInteger

! !

!ByteArray class methodsFor:'binary storage'!

binaryDefinitionFrom: stream manager: manager

    "get a ByteArray from the binary stream.

     ByteArrays are stored as 4-byte size, followed by the bytes.

     This is only invoked for long bytearrays. 

     Short ones are stored with 1byte length."

    |b len|

    "take care of subclasses ..."

    self == ByteArray ifTrue:[

        len  := stream nextNumber:4.

        b := ByteArray uninitializedNew:len.

        stream nextBytes:len into:b startingAt:1.

        ^ b

    ].

    ^ super binaryDefinitionFrom:stream manager:manager

    "Modified: / 2.11.1997 / 16:19:49 / cg"

! !

!ByteArray class methodsFor:'queries'!

isBuiltInClass

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

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

    ^ self == ByteArray

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

! !

!ByteArray methodsFor:'accessing'!

basicAt:index

    "return the indexed instance variable with index, anInteger

     - redefined here to be slighly faster than the default in Object.

     Q: is it worth the extra code ?"

%{  /* NOCONTEXT */

    REGISTER int indx;

    REGISTER OBJ slf;

    REGISTER OBJ cls;

    REGISTER int nIndex;

    if (__isSmallInteger(index)) {

	indx = __intVal(index) - 1;

	slf = self;

	if ((cls = __qClass(slf)) != @global(ByteArray)) {

	    if (((INT)__ClassInstPtr(cls)->c_flags & __MASKSMALLINT(ARRAYMASK))

		!= __MASKSMALLINT(BYTEARRAY)) {

		goto fail;

	    }

	    indx += __OBJS2BYTES__(__intVal(__ClassInstPtr(cls)->c_ninstvars));

	}

	nIndex = __byteArraySize(slf);

	if ((unsigned)indx < (unsigned)nIndex) {

	    RETURN ( __MKSMALLINT(__ByteArrayInstPtr(slf)->ba_element[indx]) );

	}

    }

  fail: ;

%}.

    ^ super basicAt:index

!

basicAt:index put:value

    "set the indexed instance variable with index, anInteger to value.

     Returns value (sigh).

     - redefined here to be slighly faster than the default in Object.

     Q: is it worth the extra code ?"

%{  /* NOCONTEXT */

    REGISTER int indx;

    int nIndex;

    int val;

    REGISTER OBJ slf;

    REGISTER OBJ cls;

    if (__bothSmallInteger(index, value)) {

	val = __intVal(value);

	if ((unsigned)(val) <= 0xFF /* i.e. (val >= 0) && (val <= 255) */) {

	    indx = __intVal(index) - 1;

	    slf = self;

	    if ((cls = __qClass(slf)) != @global(ByteArray)) {

		if (((INT)__ClassInstPtr(cls)->c_flags & __MASKSMALLINT(ARRAYMASK))

		    != __MASKSMALLINT(BYTEARRAY)) {

		    goto fail;

		}

		indx += __OBJS2BYTES__(__intVal(__ClassInstPtr(cls)->c_ninstvars));

	    }

	    nIndex = __byteArraySize(slf);

	    if ((unsigned)indx < (unsigned)nIndex) {

		__ByteArrayInstPtr(slf)->ba_element[indx] = val;

		RETURN ( value );

	    }

	}

    }

  fail: ;

%}.

    ^ super basicAt:index put:value

    "Modified: 19.4.1996 / 11:14:40 / cg"

!

byteAt:index

    "return the byte at index. 

     For ByteArray, this is the same as basicAt:; 

     however, for strings or symbols, this returns a numeric byteValue

     instead of a character."

%{  /* NOCONTEXT */

    REGISTER int indx;

    int nIndex;

    REGISTER OBJ slf;

    REGISTER OBJ cls;

    if (__isSmallInteger(index)) {

	indx = __intVal(index) - 1;

	slf = self;

	if ((cls = __qClass(slf)) != @global(ByteArray))

	    indx += __OBJS2BYTES__(__intVal(__ClassInstPtr(cls)->c_ninstvars));

	nIndex = __byteArraySize(slf);

	if ((unsigned)indx < (unsigned)nIndex) {

	    RETURN ( __MKSMALLINT(__ByteArrayInstPtr(slf)->ba_element[indx]) );

	}

    }

%}.

    ^ (super basicAt:index) asInteger

!

byteAt:index put:value

    "set the byte at index. For ByteArray, this is the same as basicAt:put:.

     However, for Strings, this expects a byteValue to be stored."

%{  /* NOCONTEXT */

    REGISTER int indx;

    int nIndex;

    int val;

    REGISTER OBJ slf;

    REGISTER OBJ cls;

    if (__bothSmallInteger(index, value)) {

	val = __intVal(value);

	if ((unsigned)(val) <= 0xFF /* i.e. (val >= 0) && (val <= 255) */) {

	    indx = __intVal(index) - 1;

	    slf = self;

	    if ((cls = __qClass(slf)) != ByteArray)

		indx += __OBJS2BYTES__(__intVal(__ClassInstPtr(cls)->c_ninstvars));

	    nIndex = __byteArraySize(slf);

	    if ((unsigned)indx < (unsigned)nIndex) {

		__ByteArrayInstPtr(slf)->ba_element[indx] = val;

		RETURN ( value );

	    }

	}

    }

%}.

    ^ super basicAt:index put:value

!

doubleAt:index

    "return the 8-bytes starting at index as a Float.

     Notice, that (currently) ST/X Floats are what Doubles are in ST-80.

     Notice also, that the bytes are expected to be in this machines

     float representation - if the bytearray originated from another

     machine, some conversion is usually needed."

    |newFloat|

    newFloat := Float basicNew.

    1 to:8 do:[:destIndex|

	newFloat basicAt:destIndex put:(self at:index - 1 + destIndex)

    ].

    ^ newFloat.

!

doubleAt:index put:aFloat

    "store the value of the argument, aFloat into the receiver

     starting at index.

     Notice, that (currently) ST/X Floats are what Doubles are in ST-80.

     Notice also, that the bytes are expected to be in this machines

     float representation - if the bytearray originated from another

     machine, some conversion is usually needed."

    |flt|

    flt := aFloat asFloat.

    1 to:8 do:[:srcIndex|

        self at:index - 1 + srcIndex put:(flt basicAt:srcIndex)

    ].

    ^ aFloat

!

doubleWordAt:index

    "return the 4-bytes starting at index as an (unsigned) Integer.

     The value is retrieved in the machines natural byte order.

     Q: should it return a signed value ? (see ByteArray>>signedDoubleWordAt:)"

%{  /* NOCONTEXT */

    REGISTER int indx;

    int nIndex;

    union {

	unsigned char u_char[4];

	unsigned u_uint;

    } val;

    OBJ cls;

    unsigned char *byteP;

    if (__isSmallInteger(index)) {

	indx = __intVal(index);

	if (indx > 0) {

	    if ((cls = __qClass(self)) != @global(ByteArray))

		indx += __OBJS2BYTES__(__intVal(__ClassInstPtr(cls)->c_ninstvars));

	    nIndex = __byteArraySize(self);

	    if ((indx+3) <= nIndex) {

		byteP = (unsigned char *)(__ByteArrayInstPtr(self)->ba_element) + indx - 1;

		val.u_char[0] = byteP[0];

		val.u_char[1] = byteP[1];

		val.u_char[2] = byteP[2];

		val.u_char[3] = byteP[3];

		if ((val.u_uint >= 0) && (val.u_uint <= _MAX_INT)) {

		    RETURN ( __MKSMALLINT(val.u_uint) );

		}

		RETURN ( __MKULARGEINT(val.u_uint) );

	    }

	}

    }

%}.

    ^ SubscriptOutOfBoundsSignal raise.

    "

     |b|

     b := ByteArray withAll:#(1 2 3 4).

     (b doubleWordAt:1) printStringRadix:16   

    "

!

doubleWordAt:index MSB:msb

    "return the 4-bytes starting at index as an (unsigned) Integer.

     The value is retrieved MSB-first, if the msb-arg is true;

     LSB-first otherwise.

     Q: should it return a signed value ? (see ByteArray>>signedDoubleWordAt:)"

%{  /* NOCONTEXT */

    REGISTER int indx;

    int nIndex;

    int val;

    OBJ cls;

    unsigned char *byteP;

    if (__isSmallInteger(index)) {

	indx = __intVal(index);

	if (indx > 0) {

	    if ((cls = __qClass(self)) != @global(ByteArray))