"

 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.

"

ArrayedCollection variableSubclass:#Array

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Arrayed'

!

!Array  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

"

    Instances of Array store general objects; the arrays size is fixed, 

    therefore add:/remove: are not allowed. 

    (actually, #add: is implemented for compatibility with smalltalks which 

     provide it, but it is very slow and outputs an annoying warning message ...)

    Access to the individual elements is via an integer index,

    using the well-known access messages #at: and #at:put:.

    Since Arrays are used very often in the system, some methods have been 

    tuned by reimplementing them as primitives. Also, the compiler inline-codes

    some operations (especially: the above accessing messages).

    Notice that Array is a built-in class 

    (i.e. the VM knows about its representation). 

    Therefore it is NOT possible to add named instance variables or change 

    Arrays inheritance. 

    However, subclassing is allowed of course 

    - even with added named instance variables.

    Literal arrays (i.e. array-constants) are entered in source as:

        #( element1 element2 ... element-n)

    where each element must be itself a literal constant.

    Array, symbol and byteArray constants within an array can be written

    without the initial #-character.

    In addition, true, false and nil are also allowed as array-literal.

    Examples:

      #(1 2 3)                -> 3 elements: 1, 2 and 3

      #('foo' 2 (1 2))        -> 3 elements: a String, 2 and anotherArray

      #('foo' #(1 2) #foo)    -> 3 elements: a String, another array and a symbol

      #('foo' (1 2) foo)      -> same as above

      #(nil true #true)       -> 3 elements: nil, true and a symbol (watch out)

      #(two [3 3 3] (4 4 4))  -> 3 elements: a symbol, a byteArray and another array

    [author:]

        Claus Gittinger

    [see also:]

        OrderedCollection

        ByteArray FloatArray DoubleArray

        String

"

! !

!Array  class methodsFor:'instance creation'!

basicNew:anInteger

    "return an instance of myself with anInteger indexed variables.

     Since Array-creation is so common (all other collections use them),

     it seems worth to have a specially tuned version here."

%{  /* NOCONTEXT */

    OBJ newobj;

    unsigned INT instsize, nInstVars;

    INT nindexedinstvars;

    REGISTER OBJ *op;

    if (__isSmallInteger(anInteger)) {

	nindexedinstvars = __intVal(anInteger);

	if (nindexedinstvars >= 0) {

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

	    nInstVars += nindexedinstvars;

	    instsize = OHDR_SIZE + __OBJS2BYTES__(nInstVars);

	    if (__CanDoQuickAlignedNew(instsize)) {

		/*

		 * the most common case

		 */

		__qCheckedAlignedNew(newobj, instsize);

	ok: ;

		__InstPtr(newobj)->o_class = self;

		__qSTORE(newobj, self);

#if defined(memset4) && defined(FAST_ARRAY_MEMSET4)

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

#else

# if !defined(NEGATIVE_ADDRESSES)

		/*

		 * knowing that nil is 0

		 */

#ifdef XXmips

# undef FAST_ARRAY_MEMSET_DOUBLES_UNROLLED

# undef FAST_ARRAY_MEMSET_LONGLONG_UNROLLED

/* seems to be slightly faster */

# define FAST_ARRAY_MEMSET

#endif

#ifdef sparc

# define FAST_ARRAY_MEMSET_DOUBLES_UNROLLED

#endif

#  if defined(FAST_ARRAY_MEMSET_DOUBLES_UNROLLED)

		op = __InstPtr(newobj)->i_instvars;

		if (nInstVars > 8) {

		    *op++ = nil;    /* for alignment */

		    nInstVars--;

		    while (nInstVars >= 8) {

			*(double *)op = 0.0;

			((double *)op)[1] = 0.0;

			((double *)op)[2] = 0.0;

			((double *)op)[3] = 0.0;

			op += 8;

			nInstVars -= 8;

		    }

		}

		while (nInstVars) {

		    *op++ = 0;

		    nInstVars--;

		}

#  else

#   if defined(FAST_ARRAY_MEMSET_LONGLONG_UNROLLED)

		op = __InstPtr(newobj)->i_instvars;

		if (nInstVars > 8) {

		    *op++ = nil;    /* for alignment */

		    nInstVars--;

		    while (nInstVars >= 8) {

			*(long long *)op = 0;

			((long long *)op)[1] = 0;

			((long long *)op)[2] = 0;

			((long long *)op)[3] = 0;

			op += 8;

			nInstVars -= 8;

		    }

		}

		while (nInstVars) {

		    *op++ = 0;

		    nInstVars--;

		}

#   else

#    if defined(FAST_ARRAY_MEMSET)

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

#    else

		op = __InstPtr(newobj)->i_instvars;

		while (nInstVars--)

		    *op++ = nil;

#    endif

#   endif

#  endif

# else

		op = __InstPtr(newobj)->i_instvars;

		while (nInstVars--)

		    *op++ = nil;

# endif

#endif

		RETURN ( newobj );

	    } else {

		/*

		 * a GC will happen ...

		 * have to protect all context stuff

		 * (especially for self, but also for backtrace in case of

		 *  allocation failure)

		 */

		__PROTECT_CONTEXT__

		newobj = __new(instsize);

		__UNPROTECT_CONTEXT__

		if (newobj != nil) {

		    goto ok;

		}

	    }

	}

    }

%}.

    "

     arrive here if something went wrong ...

     figure out what it was

    "

    (anInteger isMemberOf:SmallInteger) ifFalse:[

	"

	 the argument is either not an integer,

	 or a LargeInteger (which means that its definitely too big)

	"

	self error:'argument to new: must be Integer'.

	^ nil

    ].

    (anInteger < 0) ifTrue:[

	"

	 the argument is negative,

	"

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

	^ nil

    ].

    "

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

     Bad luck - you should increase the swap space on your machine.

    "

    ^ ObjectMemory allocationFailureSignal raise.

!

new:anInteger

    "return an instance of myself with anInteger indexed variables.

     Redefined here to save a few cycles when executed.

     (Since this is often called, its worth giving it an extra ilc-slot.

      Future versions of stc will do this automatically.)"

    ^ self basicNew:anInteger

    "Modified: 23.4.1996 / 15:52:15 / cg"

! !

!Array  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 == Array

    "Modified: 23.4.1996 / 15:55:06 / cg"

! !

!Array methodsFor:'accessing'!

at:index

    "return the indexed instance variable with index, anInteger.

     Reimplemented here to avoid the additional at:->basicAt: send

     (which we can do here, since at: is obviously not redefined in a subclass).

     This method is the same as basicAt:."

%{  /* NOCONTEXT */

    REGISTER int indx;

    REGISTER OBJ slf;

    REGISTER unsigned int nIndex;

    REGISTER OBJ cls;

    if (__isSmallInteger(index)) {

	indx = __intVal(index) - 1;

	slf = self;

	/* 

	 * thanks to Patterson/Hennesey - this can be done with a single

	 * compare ...

	 */

	nIndex = __BYTES2OBJS__(__qSize(slf) - OHDR_SIZE);

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

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

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

	    RETURN ( __InstPtr(slf)->i_instvars[indx] );

	}

    }

%}.

    ^ super at:index

!

at:index put:anObject

    "store the 2nd arg, anObject as indexed instvar with index, anInteger.

     Returns anObject (sigh).

     Reimplemented here to avoid the additional at:put:->basicAt:put: send

     (which we can do here, since at: is obviously not redefined in a subclass).

     This method is the same as basicAt:put:."

%{  /* NOCONTEXT */

    REGISTER int indx;

    REGISTER OBJ slf;

    REGISTER unsigned int nIndex;

    REGISTER OBJ cls;

    if (__isSmallInteger(index)) {

        indx = __intVal(index) - 1;

        slf = self;

        /* thanks to Patterson/Hennesey - this can be done with a single

         * compare ...

         */

        nIndex = __BYTES2OBJS__(__qSize(slf) - OHDR_SIZE);

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

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

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

            __InstPtr(slf)->i_instvars[indx] = anObject;

            __STORE(slf, anObject);

            RETURN ( anObject );

        }

    }

%}.

    ^ super at:index put:anObject

    "Modified: 19.4.1996 / 11:16:42 / cg"

!

basicAt:index

    "return the indexed instance variable with index, anInteger

     - added here for speed"

%{  /* NOCONTEXT */

    REGISTER int indx;

    REGISTER OBJ slf;

    REGISTER unsigned int nIndex;

    REGISTER OBJ cls;

    if (__isSmallInteger(index)) {

	indx = __intVal(index) - 1;

	slf = self;

	/* 

	 * thanks to Patterson/Hennesey - this can be done with a single

	 * compare ...

	 */

	nIndex = __BYTES2OBJS__(__qSize(slf) - OHDR_SIZE);

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

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

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

	    RETURN ( __InstPtr(slf)->i_instvars[indx] );

	}

    }

%}

.

    ^ super basicAt:index

!

basicAt:index put:anObject

    "store the 2nd arg, anObject as indexed instvar with index, anInteger.

     Returns anObject (sigh).

     - added here for speed"

%{  /* NOCONTEXT */

    REGISTER int indx;

    REGISTER OBJ slf;

    REGISTER unsigned int nIndex;

    REGISTER OBJ cls;

    if (__isSmallInteger(index)) {

        indx = __intVal(index) - 1;

        slf = self;

        /* 

         * thanks to Patterson/Hennesey - this can be done with a single

         * compare ...

         */

        nIndex = __BYTES2OBJS__(__qSize(slf) - OHDR_SIZE);

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

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

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

            __InstPtr(slf)->i_instvars[indx] = anObject;

            __STORE(slf, anObject);

            RETURN ( anObject );

        }

    }

%}

.

    ^ super basicAt:index put:anObject

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

!

basicSize

    "return the number of indexed elements in the receiver"

%{  /* NOCONTEXT */

    REGISTER OBJ slf = self;

    RETURN ( __MKSMALLINT(__arraySize(slf) - __intVal(__ClassInstPtr(__qClass(slf))->c_ninstvars) ));

%}

!

size

    "return the number of indexed elements in the receiver.

     Reimplemented here to avoid the additional size->basicSize send

     (which we can do here, since size is obviously not redefined in a subclass).

     This method is the same as basicSize."

%{  /* NOCONTEXT */

    REGISTER OBJ slf = self;

    RETURN ( __MKSMALLINT(__arraySize(slf) - __intVal(__ClassInstPtr(__qClass(slf))->c_ninstvars) ));

%}

! !

!Array methodsFor:'converting'!

asArray

    "return the receiver as an array - thats the receiver itself"

    "could be an instance of a subclass..."

    self class == Array ifTrue:[

        ^ self

    ].

    ^ super asArray

    "Modified: 22.4.1996 / 12:42:09 / cg"

! !

!Array methodsFor:'copying'!

copyWith:something

    "return a new collection containing the receivers elements

     and the single new element, newElement. 

     This is different from concatentation, which expects another collection

     as argument, but equivalent to copy-and-addLast.

     Reimplemented for speed if receiver is an Array.

     (since the inherited copyWith uses replaceFromTo:, which is also

      tuned, it is questionable, if we need this)"

%{  /* NOCONTEXT */

    OBJ nObj, element;

    unsigned int sz;

    unsigned int nIndex;

    REGISTER OBJ *srcP, *dstP;

    REGISTER int spc;

    if (__qClass(self) == Array) {

	sz = __qSize(self) + sizeof(OBJ);

	__PROTECT2__(something, self);

	__qAlignedNew(nObj, sz, __context);

	__UNPROTECT2__(self, something);

	if (nObj) {

	    __InstPtr(nObj)->o_class = Array;

	    nIndex = __BYTES2OBJS__(sz - OHDR_SIZE - sizeof(OBJ));

	    /* 

	     * sorry: 

	     * cannot use bcopy, since we must take care of stores ... 

	     * could check for: notRemembered + inOld + notLifoRem

	     *                  + not incrGCRunning

	     * but copyWith: is not heavily used by real programmers ...

	     */

	    spc = __qSpace(nObj);

	    srcP = __ArrayInstPtr(self)->a_element;

	    dstP = __ArrayInstPtr(nObj)->a_element;

#ifdef UNROLL_LOOPS

	    while (nIndex >= 4) {

		element = srcP[0];

		dstP[0] = element;

		__STORE_SPC(nObj, element, spc);

		element = srcP[1];

		dstP[1] = element;

		__STORE_SPC(nObj, element, spc);

		element = srcP[2];

		dstP[2] = element;

		__STORE_SPC(nObj, element, spc);

		element = srcP[3];

		dstP[3] = element;

		__STORE_SPC(nObj, element, spc);

		srcP += 4;

		dstP += 4;

		nIndex -= 4;

	    }

#endif

	    while (nIndex--) {

		element = *srcP++;