"{ Encoding: utf8 }"

"
 COPYRIGHT (c) 2018 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:libbasic2' }"

"{ NameSpace: Smalltalk }"

AbstractNumberVector variableFloatSubclass:#ComplexFloatArray
	instanceVariableNames:''
	classVariableNames:''
	poolDictionaries:''
	category:'Collections-Arrayed'
!

!ComplexFloatArray class methodsFor:'documentation'!

copyright
"
 COPYRIGHT (c) 2018 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
"
    ComplexFloatArrays store complex numbers (in single prevision) and nothing else.
    They have been added to support heavy duty number crunching and
    data exchange with openGL frameworks and other mass data libraries
    somewhat better than other smalltalks do. 
    Storing Complex numbers in these objects (instead of Arrays)
    has some benefits:

    1) since the values are stored directly (instead of pointers to them)
       both access overhead and garbage collect overhead is minimized.

    2) they can be much faster passed to c functions (such as graphics 
       libraries or heavy duty math packages), since the double values
       come packed and can be used in C by using a (double *) or double[].
       There is no need to loop over the array extracting doubles.      

    3) they could (in theory) be much more easily be processed by things like
       vector and array processors

    Be aware however, that ComplexFloatArrays are not supported in other
    smalltalks - your program will thus become somewhat less portable.
    (since their protocol is the same as normal arrays filled with floats,
     they can of course be easily simulated - a bit slower though)

    However, they could be simulated by a ByteArray, using doubleAt: and 
    doubleAtPut: messages to access the elements, but that seems a bit
    clumsy and unelegant. Also, the stc-compiler may learn how to deal
    with Float- and DoubleArrays, making accesses very fast in the future.
    Hint: if you use doubleArrays in your application and must port it
    to some other smalltalk, define a DoubleArray class there, which is derived
    from ByteArray, and add access methods.

    Of course, ComplexFloatArrays can be subclassed,
    and named instance variables can be added there.

    [memory requirements:]
        OBJ-HEADER + (size * float-size * 2)

    [See also:]
        ComplexSoubleArray DoubleArray FloatArray Array

    [author:]
        Claus Gittinger
"
!

examples
"
                                                                [exBegin]
    |vec|

    vec := ComplexFloatArray new:4.
    vec size.
    vec at:1.
    vec at:2.
    vec at:3.
    vec at:4.
    vec at:1 put:(1 + 4i).
    vec at:2 put:(2 + 4i).
    vec at:4 put:(4 + 4i).
    vec
                                                                [exEnd]
"
! !

!ComplexFloatArray class methodsFor:'instance creation'!

new:size
    ^ super new:(size * 2)
! !

!ComplexFloatArray class methodsFor:'queries'!

elementByteSize
    "for bit-like containers, return the number of bytes stored per element.
     Here, 2*4 is returned"

    ^ 8
! !

!ComplexFloatArray methodsFor:'accessing'!

at:index
    |baseIdx|

    baseIdx := index * 2.
    ^ Complex basicNew
        setReal:(self basicAt:(baseIdx - 1))
        setImaginary:(self basicAt:(baseIdx))
!

at:index put:aComplex
    |baseIdx|

    baseIdx := index * 2.
    self basicAt:(baseIdx - 1) put:aComplex real.
    self basicAt:(baseIdx) put:aComplex imaginary.
!

at:index put:realPart i:imaginaryPart
    |baseIdx|

    baseIdx := index * 2.
    self basicAt:(baseIdx - 1) put:realPart.
    self basicAt:(baseIdx) put:imaginaryPart.
!

imaginaryAt:index
    |baseIdx|

    baseIdx := index * 2.
    ^ (self basicAt:(baseIdx))
!

realAt:index
    |baseIdx|

    baseIdx := index * 2.
    ^ (self basicAt:(baseIdx - 1))
! !

!ComplexFloatArray methodsFor:'queries'!

defaultElement
    ^ Complex zero
!

isValidElement:anObject
    "return true, if I can hold this kind of object"

    ^ anObject isNumber
!

size
    ^ super size // 2
! !

!ComplexFloatArray class methodsFor:'documentation'!

version
    ^ '$Header$'
!

version_CVS
    ^ '$Header$'
! !