VV        VR                                              LL
 VV      VV EEEEEE  CCCCCC TTTTTTT   OOOOOO   RRRRRRR     LL      II  BBBBBB
  VV    VV  EE      CC       TT     OO    OO  RR    RR    LL      II  BB   BB
   VV  VV   EEEEEE  CC       TT     OO    OO  RRRRRRR     LL      II  BBBBBB
    VVV     EE      CC       TT     OO    OO  RR  RR      LL      II  BB   BB
     V      EEEEEE  CCCCCC   TT      OOOOOO   RR    RR    LLLLLL  II  BBBBBB


                     VectorLib   Version 1.2
                         for Borland C++
                     (Version 3.0 or higher)

                     Dr. Martin Sander Software Development
                     Sertrnerstr. 11
                     D-37085 Gttingen
                     Germany
                     e-mail: MartinSander@Bigfoot.com

****************************************************************************

S e c o n d  P a r t :   File  FUNCREF.TXT

!!     This is an ASCII text file!  It is best viewed with a simple        !!
!!     DOS editor.                                                         !!
!!     If you load this file into a word processor under Windows, you      !!
!!     must use the filter "DOS text".                                     !!
!!     Alternatively, you may use FCONVERT (shipped with Borland C++) to   !!
!!     convert from ASCII (OEM) into the ANSI character set.               !!
!!     Preferrably use the lettertype CourierNew 10 pt.                    !!

A general description of VectorLib is given in the  F i r s t  P a r t
of this documentation, in the file HANDBOOK.TXT.
Chapter 1.2 of that file contains the licence terms.

Copyright for the Software and its documentation (C) 1996-1998 Martin Sander


****************************************************************************
*                                                                          *
*******                8. Alphabetical Reference                     *******
*                                                                          *
****************************************************************************


The functions are alphabetically ordered, with the prefixes being neglected
for the ordering. The heading of each entry lists all the versions available
of a specific function. For example, the "abs" family of functions exists in
vectorized versions for
-  the three real-number data types float, double, and extended (long double)
   with the prefixes VF_, VD_, and VE_,
-  for the three complex-number data types (prefixes VCF_, VCD_, and VCE_),
-  and for the signed integer data types int, short int, long int and quad
   (prefixes VI_, VSI_, VLI_, and VQI);
unsigned numbers are, by their very definition, always positive, and it makes
no sense to define the operation "abs" for them; consequently, the VU_, VUS_,
VUL_, and VUI_  versions are missing.

The lines following the heading describe the use of the respective functions
in greater detail:
Syntax          In most cases, only the VF_ version is described. All other
                versions are exactly analogous; one has only to replace the
                data types float and fVector by the appropriate ones and
                replace the  VF... include file by the one belonging to the
                desired data type.
Description     Often, for the sake of simplicity, the brackets around vector
                element indices are left away.
                If not stated otherwise, all vector elements from the zero'th
                up to the last one (with the index  size-1) are subjected to
                the respective operation described.
                Thus, a formula like     Yi =  Xi    is to be understood
                as an abbreviation for   Y[i] =  X[i] ,  i=0,...,size-1
                or, written as a loop:
                    for( i=0; i<size; i++ ) Y[i] = fabs( X[i] );
Error handling  All types of errors are listed which are detected and handled.
                The default result is given in each case. In case of any
                detected floating-point errors, _matherr or _matherrl are
                called (see chapter 5.3). Although we do not recommend that,
                the user may modify _matherr and _matherrl such as to specify
                other results than those suggested.
Return value    The return value of the respective function is mentioned here.
See also        References to functions without a prefix "V..." refer to
                the documentation of Borland C.

References to chapters 1. to 7. refer to the  F i r s t  P a r t  of this
documentation. See the file HANDBOOK.TXT.


Ŀ
 VF_abs                   VD_abs                   VE_abs                   
 VCF_abs                  VCD_abs                  VCE_abs                  
 VI_abs              VSI_abs             VLI_abs             VQI_abs        

Function        Absolute value
Syntax          #include <VFmath.h>
                int  VF_abs(   fVector Y,  fVector X,  ui size );
                       (similarly VD_, VE_, VSI_, VI_, VLI_, VQI_)
                int  VCF_abs(  fVector Y,  cfVector X, ui size );
                       (similarly VCD_, VCE_)
Description     Real and integer versions:    Yi  =   Xi 
                VSI_,  VI_, and VLI_ versions only: due to the implicit
                   modulo-2**n arithmetics, the absolute value of the most
                   negative numbers possible ( -32768 for short, -2147483648
                   for long) is stored as the same negative (!) number
                   (-32768 or -2147483648, resp.).
                Complex versions:      Yi  = sqrt( Xi.Re + Xi.Im )
                For the complex versions, note that the result is real-
                   valued. The same result may also be obtained slightly
                   faster, but without error handling, using VF_CtoAbs.
Error handling  Real and integer versions: no errors should occur;
                Complex versions: OVERFLOW errors lead to the default result
                +HUGE_VAL.
Return value    Floating-point versions: 0, if error-free, otherwise != 0.
                The integer versions have no return value.
See also        VF_neg,  VCF_abs,  VCF_conj


Ŀ
 VF_absmax                VD_absmax                VE_absmax                
 VCF_absmax               VCD_absmax               VCE_absmax               

Function        Largest absolute value within one vector
Syntax          #include <VFstd.h>
                float VF_absmax( fVector X, ui size );
                       (similarly VD_,  VE_)
                float VCF_absmax( cfVector X, ui size);
                       (similarly VCD_, VCE_)
Description     The absolute values of all elements of a vector are compared
                and the largest returned. For complex numbers, the magnitudes
                of the elements are compared and the largest returned. In
                order to find the greatest real and imaginary parts
                separately, please use VCF_absmaxReIm.
Error handling  none
Return value    maximum absolute value encountered.
See also        VF_max, VF_absmin, VF_runmax, VF_absmaxind, VCF_absmaxReIm


Ŀ
 VF_absmaxind             VD_absmaxind             VE_absmaxind             
 VCF_absmaxind            VCD_absmaxind            VCE_absmaxind            

Function        Largest absolute value and its index
Syntax          #include <VFstd.h>
                float  VF_absmaxind( ui *Ind, fVector X, ui size );
                       (similarly VD_,  VE_)
                float  VCF_absmaxind( ui *Ind, cfVector X, ui size );
                       (similarly VCD_, VCE_)
Description     The absolute values of all elements of a vector are compared
                and the largest returned. For complex numbers, the magnitudes
                of the elements are compared and the largest returned. The
                index of this maximum is stored at the address given by Ind.
                In case of more than one element with the same maximum value,
                the lowest index is chosen.
Error handling  none
Return value    maximum absolute value encountered.
See also        VF_maxind, VF_absmax, VF_runmax, VF_maxind, VCF_absmaxReIm


Ŀ
 VCF_absmaxReIm           VCD_absmaxReIm           VCE_absmaxReIm           

Function        Separate determination of the largest absolute values of the
                real and imaginary parts occurring in a complex vector.
Syntax          #include <VCFstd.h>
                fComplex  VCF_absmaxReIm( cfVector X, ui size );
                       (similarly VCD_, VCE_)
Description     The absolute values of the real parts of all vector elements
                are compared with each other and the largest one is returned
                as the real part of the result. Similarly, the absolute values
                of all the imaginary parts are compared with each other and
                the largest one is returned as the imaginary part of the
                result. Generally, the result is made up from different
                elements of the vector.
Error handling  none
Return value    Largest absolute real and imaginary parts, combined into one
                complex number.
See also        VCF_maxReIm, VCF_absminReIm


Ŀ
 VF_absmin                VD_absmin                VE_absmin                
 VCF_absmin               VCD_absmin               VCE_absmin               

Function        Smallest absolute value within one vector
Syntax          #include <VFstd.h>
                float VF_absmin( fVector X, ui size );
                      (similarly VD_,  VE_)
                float VCF_absmin( cfVector X, ui size );
                      (similarly( VCD_, VCE_)
Description     The absolute values of all elements of a vector are compared
                and the smallest returned. For complex numbers, the magnitudes
                of the elements are compared and the smallest returned. In
                order to find the smallest real and imaginary parts
                separately, please use VCF_absminReIm.
Error handling  none
Return value    minimum absolute value encountered.
See also        VF_min, VF_absmax, VF_runmin, VF_minind, VCF_absminReIm


Ŀ
 VF_absminind             VD_absminind             VE_absminind             
 VCF_absminind            VCD_absminind            VCE_absminind            

Function        Smallest absolute value and the index of its first
                occurrence.
Syntax          #include <VFstd.h>
                float  VF_absminind(  ui *Ind, fVector X, ui size );
                      (similarly VD_,  VE_)
                float  VCF_absminind( ui *Ind, cfVector X, ui size );
                      (similarly VCD_, VCE_)
Description     The absolute values of all elements of a vector are compared
                and the smallest returned. For complex numbers, the magnitudes
                of the elements are compared and the smallest returned. The
                index of this minimum is stored at the address given by Ind.
                In case of more than one element with the same minimum value,
                the lowest index is chosen.
Error handling  none
Return value    minimum absolute value encountered.
See also        VF_minind, VF_absmin, VF_runmin, VF_maxind, VCF_absminReIm


Ŀ
 VCF_absminReIm           VCD_absminReIm           VCE_absminReIm           

Function        Separate determination of the smallest absolute values of the
                real and imaginary parts occurring in a complex vector.
Syntax          #include <VCFstd.h>
                fComplex  VCF_absminReIm( cfVector X, ui size );
                      (similarly( VCD_, VCE_)
Description     The absolute values of the real parts of all vector elements
                are compared with each other and the smallest one is returned
                as the real part of the result. Similarly, the absolute values
                of all the imaginary parts are compared with each other and
                the smallest one is returned as the imaginary part of the
                result. Generally, the result is made up from different
                elements of the vector.
Error handling  none
Return value    Smallest absolute real and imaginary parts, combined into one
                complex number.
See also        VCF_minReIm, VCF_absmaxReIm


Ŀ
 VF_acos                  VD_acos                  VE_acos                  
 VCF_acos                 VCD_acos                 VCE_acos                 
 VFx_acos                 VDx_acos                 VEx_acos                 
 VCFx_acos                VCDx_acos                VCEx_acos                

Function        arcus cosinus function
Syntax          #include <VFmath.h>
                int  VF_acos(   fVector Y,  fVector X, ui size );
                int  VFx_acos(  fVector Y,  fVector  X, ui size,
                                float A, float B, float C );
Description     normal versions:   Yi  =  arccos ( Xi )
                expanded versions: Yi  =  C *  arccos (A*Xi + B )
Error handling  Real versions: DOMAIN errors occur for arguments outside the
                range    -1 <= Xi <= +1;  the default result is NAN ("not-a-
                number").
                The complex versions should be error-proof as long as the
                parameter C in the expanded versions is not already near the
                OVERFLOW limit; this very rare error is neither detected nor
                handled.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cos,  VF_asin,  VF_atan,  acos


Ŀ
 VF_addC                  VD_addC                  VE_addC                  
 VCF_addC                 VCD_addC                 VCE_addC                 
 VCF_addReC               VCD_addReC               VCE_addReC               
 VI_addC             VSI_addC            VLI_addC            VQI_addC       
 VU_addC             VUS_addC            VUL_addC            VUI_addC       

Function        Add a constant to a vector
Syntax          #include <VFmath.h>
                void VF_addC( fVector Y, fVector X, ui size, float C);
                      (similarly VD_, VI_, etc.)
                void  VCF_addC( cfVector Y, cfVector X, ui size,
                                fComplex C );
                void  VCF_addReC( cfVector Y, cfVector X, ui size,
                                  float CRe );
                      (similarly VCD_, VCE_)
Description     Yi  =  Xi  +  C
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe added to the complex vector.
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_addV,  VF_subC,  VF_mulC,  VF_divC,  VF_visC,  VF_redC


Ŀ
 VF_addV                  VD_addV                  VE_addV                  
 VCF_addV                 VCD_addV                 VCE_addV                 
 VCF_addReV               VCD_addReV               VCE_addReV               
 VFs_addV                 VDs_addV                 VEs_addV                 
 VFx_addV                 VDx_addV                 VEx_addV                 
 VCFx_addV                VCDx_addV                VCEx_addV                
 VCFx_addReV              VCDx_addReV              VCEx_addReV              
 VI_addV             VSI_addV            VLI_addV            VQI_addV       
 VU_addV             VUS_addV            VUL_addV            VUI_addV       

Function        Add two vectors
Syntax          #include <VFmath.h>
                void  VF_addV( fVector Z, fVector X, fVector Y,	ui size );
                void  VFs_addV( fVector Z, fVector X, fVector Y, ui size,
                                float C );
                void  VFx_addV( fVector Z, fVector X, fVector Y,
                                ui size, float A, float B );
                      (similarly VD_,  VDx_,  VE_, VEx_,  VI_, etc.)
                void  VCF_addV( cfVector Z, cfVector X, cfVector Y,
                                ui size );
                void  VCF_addReV( cfVector Z, cfVector X, fVector Y,
                                  ui size );
                void  VCFx_addV( cfVector Z, cfVector X, cfVector Y,
                                 ui size, fComplex A, fComplex B );
                void  VCFx_addReV( cfVector Z, cfVector X, fVector Y,
                                   ui size, fComplex A, fComplex B );
                      (similarly VCD_,  VCDx_,  VCE_,  VCEx_)
Description     normal versions:    Zi  =  Xi + Yi
                scaled versions:    Zi  =  C * (Xi + Yi)
                expanded versions:  Zi  =  (A * Xi + B)  +  Yi
                The complex floating-point versions exist in two variants. In
                the first variant (e.g.VCF_addV,  VCFx_addV), X, Y, and Z are
                all complex; in the second variant, Y is real-valued (e.g.,
                VCF_addReV - "add a real vector").
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_addC,  VF_subV,  VF_mulV,  VF_divV,  VF_visV,  VF_redV


Ŀ
 VI_and              VSI_and             VLI_and             VQI_and        
 VU_and              VUS_and             VUL_and             VUI_and        

Function        Bit-wise AND operation.
Syntax          #include <VImath.h>
                void VI_and( iVector Y, iVector X, ui size, int C );
                      (similarly all other functions of this family)
Description     Yi  =  (Xi) & C
                The bit-wise AND operation is performed on each element Xi
                with the bit-mask given by C.  A bit is 1 in Yi, if it was 1
                both in Xi and in C, and 0 otherwise. Perhaps the most useful
                application of this family of functions is the fast "modulo"
                operation on unsigned or positive numbers with the modulus
                being an integer power of 2. For example, a modulo division by
                64 is performed by
                      VU_and( Y, X, size, 64-1 );
Error handling  none
Return value    none
See also        VI_not,  VI_or,  VI_xor


Ŀ
 VCF_arg                  VCD_arg                  VCE_arg                  

Function        Argument (angle in polar coordinates). Implemented as a macro
                that calls VF_CtoArg, VD_CtoArg, VE_CtoArg, resp.  See these
                functions  for details.


Ŀ
 VF_asin                  VD_asin                  VE_asin                  
 VCF_asin                 VCD_asin                 VCE_asin                 
 VFx_asin                 VDx_asin                 VEx_asin                 
 VCFx_asin                VCDx_asin                VCEx_asin                

Function        arcus sinus function
Syntax          #include <VFmath.h>
                int  VF_asin( fVector Y, fVector X, ui size );
                int  VFx_asin( fVector  Y, fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  arcsin ( Xi )
                expanded versions:  Yi  =  C *  arcsin (A*Xi + B )
Error handling  Real versions: DOMAIN errors occur for arguments outside the
                range    -1 <= Xi <= +1;  the default result is NAN ("not-a-
                number").
                The complex versions should be error-proof as long as the
                parameter C in the expanded versions is not already near the
                OVERFLOW limit; this very rare error is either detected nor
                handled.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sin,  VF_acos,  VF_atan,  asin


Ŀ
 VF_atan                  VD_atan                  VE_atan                  
 VCF_atan                 VCD_atan                 VCE_atan                 
 VFx_atan                 VDx_atan                 VEx_atan                 
 VCFx_atan                VCDx_atan                VCEx_atan                

Function        arcus tangens function
Syntax          #include <VFmath.h>
                int  VF_atan(  fVector Y, fVector X, ui size );
                int  VFx_atan( fVector Y, fVector X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  arctan ( Xi )
                expanded versions:  Yi  =  C *  arctan (A*Xi + B )
Error handling  The real versions should be error-proof as long as the
                parameter C in the expanded versions is not already near the
                OVERFLOW limit; this very rare error is neither detected nor
                handled.
                In the complex versions, the result for an argument of {0, -1}
                is set to   {0, -Pi} without notice (and without the program
                crash resulting in Borland C++ from calling the complex atan
                with this argument).
Return value    always 0.
See also        VF_tan,  VF_asin,  VF_acos,  VF_atan2,  atan,  atan2


Ŀ
 VF_atan2                 VD_atan2                 VE_atan2                 
 VFx_atan2                VDx_atan2                VEx_atan2                

Function        arcus tangens function of quotients
Syntax          #include <VFmath.h>
                int VF_atan2( fVector Z, fVector X, fVector Y, ui size );
                int  VFx_atan2( fVector Z,  fVector X,  fVector Y, ui size,
                                float A, float B, float C );
Description     normal versions:    Zi  =  arctan(  Yi / Xi )
                expanded versions:  Zi  =  C *  arctan(  Yi / (A*Xi+B) )
                From Cartesian X - Y- coordinates, the angle of the
                corresponding polar coordinates is calculated. Be careful: in
                comparison to the ANSI C function atan2, the ordering of the
                parameters X and Y is reversed.
Error handling  If Xi  and Yi are both zero, a DOMAIN error results with the
                default result NAN ("not-a-number"); this error is handled by
                _matherr and _matherrl  with Xi  and Yi as e->x and e->y.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_tan,  VF_asin,  VF_acos,  VF_atan,  atan,  atan2


Ŀ
 VF_autocorr              VD_autocorr              VE_autocorr              

Function        autocorrelation function
Syntax          #include <VFstd.h>
                void VF_autocorr(  fVector Y, fVector X, ui size );
Description     The autocorrelation function (ACF) of X is calculated and
                stored in Y  in wrap-around order: Y[0] to Y[size/2-1]
                contain the ACF for zero and positive lags. Beginning with
                the most negative lag in Y[size/2+1], the elements up to
                Y[size-1] contain the ACF for negative lags. Since this
                function assumes X to be periodic, the ACF for the most
                positive lag is identical to the ACF for the most negative
                lag. This element is stored as Y[size/2].
                To get the ACF into normal order, you may call
                   VF_rotate( Y, Y, size, size/2 );
                After that, the zero point is at the position size/2.

                In case X is non-periodic, you should avoid end effects
                by the methods described in connection with VF_convolve.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_autocorr
                is based) complains "Size must be an integer power of 2"
                and the program is aborted.
Return value    none
See also        VF_FFT,  VF_convolve,  VF_xcorr, VF_spectrum


Ŀ
 VCF_autoPlot             VCD_autoPlot             VCE_autoPlot             

Function        Automatic plot of a complex vector into a Cartesian complex
                plane.
Syntax          #include <Vgraph.h>
                void VCF_autoPlot( cfVector X, ui size,
                                   unsigned form, COLORREF color );
Description     A Cartesian complex plane is drawn with the axes automatically
                scaled and the vector X plotted into it. For a description of
                the parameters form and color, see VF_xyAutoPlot. The plotting
                routines have to be initialized by V_initGraph or V_initPlot
                prior to calling VCF_autoPlot.
Error handling  none
Return value    none
See also        VCF_2AutoPlot,  VCF_dataPlot, VF_xyAutoPlot,  chapter 4.11


Ŀ
 VCF_2AutoPlot            VCD_2AutoPlot            VCE_2AutoPlot            

Function        Automatic plot of two complex vectors into a Cartesian
                complex plane.
Syntax          #include <Vgraph.h>
                void VCF_2AutoPlot(  cfVector X1, ui size1,
                                     unsigned form1, COLORREF color1,
                                     cfVector X2, ui size2,
                                     unsigned form2, COLORREF color2 );
Description     A Cartesian complex plane is drawn with the axes automatically
                scaled and the vectors X1 and X2 plotted into it. For a
                description of the parameters form1, form2, color1, and
                color2, see VF_xyAutoPlot. The plotting routines have to be
                initialized by V_initGraph or V_initPlot prior to calling
                VCF_2AutoPlot.
Error handling  none
Return value    none
See also        VCF_autoPlot,  VCF_dataPlot, VF_xyAutoPlot,  chapter 4.11


Ŀ
 VF_avdevC                VD_avdevC                VE_avdevC                

Function        average deviation from a preset value
Syntax          #include <VFstd.h>
                float  VF_avdevC( fVector X, ui size, float C );
Description     avdevC  =  1/size * sum(  Xi - C )
                The average of the absolute deviation of each element of X
                from C is calculated and returned.
Error handling  none
Return value    average deviation.
See also        VF_ssq, VF_ssqdevC, VF_avdevV


Ŀ
 VF_avdevV                VD_avdevV                VE_avdevV                

Function        average deviation of the elements of one vector from the
                corresponding elements of another vector.
Syntax          #include <VFstd.h>
                float  VF_avdevV( fVector X, fVector Y, ui size );
Description     avdevV  =  1/size * sum(  Xi - Yi )
                The average of the absolute deviation of each element of X
                from the corresponding element of Y is calculated.
Error handling  none
Return value    average deviation.
See also        VF_ssq, VF_ssqdevC, VF_avdevV,  VF_chi2


Ŀ
 V_CDtoCF                 V_CDtoCE                                          
 V_CEtoCF                 V_CEtoCD                                          
 V_CFtoCD                 V_CFtoCE                                          

Function        Data type conversions.  See V_FtoD.


Ŀ
 VF_ceil                  VD_ceil                  VE_ceil                  
 VF_ceiltoI               VD_ceiltoI               VE_ceiltoI               
 VF_ceiltoSI              VD_ceiltoSI              VE_ceiltoSI              
 VF_ceiltoLI              VD_ceiltoLI              VE_ceiltoLI              
 VF_ceiltoQI              VD_ceiltoQI              VE_ceiltoQI              
 VF_ceiltoU               VD_ceiltoU               VE_ceiltoU               
 VF_ceiltoUS              VD_ceiltoUS              VE_ceiltoUS              
 VF_ceiltoUL              VD_ceiltoUL              VE_ceiltoUL              
 VF_ceiltoUI              VD_ceiltoUI              VE_ceiltoUI              

Function        Rounding to the next whole number that is greater or equal.
Syntax          #include <VFmath.h>
                int VF_ceil(    fVector Y,  fVector X,  ui size );
                int VF_ceiltoI( iVector Y,  fVector X,  ui size );
                int VF_ceiltoLI( liVector Y, fVector X, ui size );
                     (similarly  all other functions of this family)
Description     Each element of X is rounded to the nearest whole number that
                is greater than or equal to the input number and the result
                stored in Y. The functions VF_ceiltoI, VF_ceiltoLI,
                VF_ceiltoU etc. convert the result into the various integer
                data types (in the cases mentioned, to int,  long int, and
                unsigned, resp.).
Error handling  OVERFLOW errors are handled by setting the result to the
                extreme value possible. Negative numbers in the versions
                VF_ceiltoU, VF_ceiltoUS, VF_ceiltoUL, and VF_ceiltoUI  lead
                to DOMAIN errors; they are handled by setting the result to 0.
Return value    0, if no error occurred, otherwise non-zero.
See also        ceil, floor, VF_round,  VF_floor, VF_chop, VF_trunc


Ŀ
 VF_chi2                  VD_chi2                  VE_chi2                  

Function        Calculates the chi-square merit function.
Syntax          #include <VFstd.h>
                float  VF_chi2(  fVector X,  fVector Y,
                                 fVector InvVar, ui size );
Description	    chi  =   sum( 1/sigmai * (Xi - Yi) ).
                The chi-square merit function is most often used to judge the
                quality of a fit. One vector (either X or Y) represents
                experimental values that are obtained with individual standard
                deviations sigmai, the other contains the values predicted on
                the basis of a theory or a model. If the experimental data are
                "normally" distributed, and if sigma is the correct measure
                for the quality of these data, then chi is a measure for the
                quality of the fit. Rather than the standard deviations
                themselves, the routine needs the inverse of their squares
                (i.e., the inverse of the variances) to be passed as the
                vector InvVar.
Error handling  none
Return value    chi merit function.
See also        VF_meanwW,  VF_varianceVwW, VF_varianceV, VF_varianceCwW,
                VF_square, VF_inv, VF_linregress


Ŀ
 VF_chop                  VD_chop                  VE_chop                  
 VF_choptoI               VD_choptoI               VE_choptoI               
 VF_choptoSI              VD_choptoSI              VE_choptoSI              
 VF_choptoLI              VD_choptoLI              VE_choptoLI              
 VF_choptoQI              VD_choptoQI              VE_choptoQI              
 VF_choptoU               VD_choptoU               VE_choptoU               
 VF_choptoUS              VD_choptoUS              VE_choptoUS              
 VF_choptoUL              VD_choptoUL              VE_choptoUL              
 VF_choptoUI              VD_choptoUI              VE_choptoUI              

Function        "Chopping" towards zero.
Syntax          #include <VFmath.h>
                int VF_chop(     fVector Y,  fVector X, ui size );
                int VF_choptoI(  iVector Y,  fVector X, ui size );
                int VF_choptoLI( liVector Y, fVector X, ui size );
                     (similarly  all other functions of this family)
Description     Each element of X is rounded to an integer number by "chopping
                off" the fractional part. For example, -3.9 yields -3, and
                +3.9 yields +3. The result is stored in Y. The functions
                VF_choptoI, VF_choptoLI, etc. convert the result into the
                various integer data types.
Error handling  OVERFLOW errors are handled by setting the result to the
                extreme value possible. Negative numbers in the versions
                VF_choptoU, VF_choptoUS, VF_choptoUL, and VF_choptoUI  lead
                to DOMAIN errors; they are handled by setting the result to 0.
Return value    0, if no error occurred, otherwise non-zero.
See also        ceil, floor, VF_round,  VF_floor, VF_ceil


Ŀ
 V_closeErrorEventFile                                                      

Function        Restore default printing of error messages into stderr.
Syntax          #include <VecLib.h>
                void  V_closeErrorEventFile( void );
Description     After error messages have been redirected into an event file
                by V_setErrorEventFile, the default is restored by
                V_closeErrorEventFile and any further messages will be printed
                into stderr  which normally is the screen (see Chapter 5.5).
                Both of thess functions will not be included in versions of
                VectorLib for compilers that do already offer the possibility
                of printing error messages simultaneously to the screen and to
                an event file.
Error handling  none
Return value    none
See also        V_noteError,  V_setErrorEventFile,  _matherr


Ŀ
 VF_cmp0                  VD_cmp0                  VE_cmp0                  

Function        Compares each element of a vector with 0 (signum function).
Syntax          #include <VFmath.h>
                void VF_cmp0( fVector Y,  fVector X, ui size );
Description     Each element of X is compared with 0 and the result of the
                comparison stored in Y:
                    Yi =   1.0,   if  Xi > 0
                    Yi =   0.0,   if  Xi = 0
                    Yi =  -1.0,   if  Xi < 0.
                This function may also be called under its synonym VF_sgn.
Error handling  none
Return value    none
See also        VF_cmp_..., VF_cmpC, VF_cmpV


Ŀ
 VF_cmpC                  VD_cmpC                  VE_cmpC                  

Function        Compares each element of a vector with a constant.
Syntax          #include <VFmath.h>
                void VF_cmpC( fVector Y, fVector X, ui size, float C );
Description     Each element of X is compared with C and the result of the
                comparison stored in Y:
                     Yi =   1.0,   if  Xi > C
                     Yi =   0.0,   if  Xi = C
                     Yi =  -1.0,   if  Xi < C
                To compare with C=0, use more efficiently the function VF_cmp0.
Error handling  none
Return value    none
See also        VF_cmp_..., VF_cmp0, VF_cmpV,  VF_iselementC


Ŀ
 VF_cmpV                  VD_cmpV                  VE_cmpV                  

Function        Compares each element of a vector with the corresponding
                element of another vector.
Syntax          #include <VFmath.h>
                void VF_cmpV( fVector Z, fVector X, fVector Y, ui size );
Description     Each element of X is compared with the corresponding element
                of Y and the result of the comparison stored in Z:
                     Zi =   1.0,   if  Xi > Yi
                     Zi =   0.0,   if  Xi = Yi
                     Zi =  -1.0,   if  Xi < Yi.
Error handling  none
Return value    none
See also        VF_cmp_..., VF_cmp0, VF_cmpV


Ŀ
 VF_cmp_...               VD_cmp_...               VE_cmp_...               
 VCF_cmp_...              VCD_cmp_...              VCE_cmp_...              

Function        Comparisons
Syntax          #include <VFmath.h>
                ui VF_cmp_eq0(  fVector Y,  fVector X,  ui size );
                ui VF_cmp_ne0(  fVector Y,  fVector X,  ui size );
                ui VF_cmp_gt0(  fVector Y,  fVector X,  ui size );
                ui VF_cmp_ge0(  fVector Y,  fVector X,  ui size );
                ui VF_cmp_lt0(  fVector Y,  fVector X , ui size );
                ui VF_cmp_le0(  fVector Y,  fVector X,  ui size );
                ui VF_cmp_eqC( fVector Y, fVector X, ui size, float C );
                   ... (similarly: VF_cmp_neC,  VF_cmp_gtC, VF_cmp_geC,
                                   VF_cmp_ltC, VF_cmp_leC)
                ui VF_cmp_eqV( fVector Z, fVector X, fVector Y, ui size);
                   ... (similarly: VF_cmp_neV, VF_cmp_gtV, VF_cmp_geV,
                                   VF_cmp_ltV, VF_cmp_leV)
                ui VF_cmp_eq0ind( uiVector Ind, fVector X, ui size );
                   ... (similarly: VF_cmp_ne0ind,  VF_cmp_gt0ind,
                                   VF_cmp_ge0ind,  VF_cmp_lt0ind,
                                   VF_cmp_le0ind)
                ui VF_cmp_eqCind( uiVector Ind, fVector X, ui size,
                                  float C );
                   ...  (similarly: VF_cmp_neCind,  VF_cmp_gtCind,
                                    VF_cmp_geCind,  VF_cmp_ltCind,
                                    VF_cmp_leCind)
                ui VF_cmp_eqVind( uiVector Ind, fVector X, fVector Y,
                                  ui size );
                   ...  (similarly: VF_cmp_neVind,  VF_cmp_gtVind,
                                    VF_cmp_geVind,  VF_cmp_ltVind,
                                    VF_cmp_leVind)
                   (similarly VD_ and VE_ versions)

                ui VCF_cmp_eq0( cfVector Y, cfVector X,  ui size );
                ui VCF_cmp_ne0( cfVector Y, cfVector X,  ui size );
                ui VCF_cmp_eqC( cfVector Y, cfVector X,  ui size,
                                fComplex C );
                ui VCF_cmp_neC( cfVector Y, cfVector X,  ui size,
                                fComplex C );
                ui VCF_cmp_eqV( cfVector Z, cfVector X, cfVector Y,
                                ui size );
                ui VCF_cmp_neV( cfVector Z, cfVector X, cfVector Y,
                                ui size );
                ui VCF_cmp_eq0ind( uiVector Ind, cfVector X, ui size );
                ui VCF_cmp_ne0ind( uiVector Ind, cfVector X, ui size );
                ui VCF_cmp_eqCind( uiVector Ind, cfVector X, ui size,
                                   fComplex C );
                ui VCF_cmp_neCind( uiVector Ind, cfVector X, ui size,
                                   fComplex C );
                ui VCF_cmp_eqVind( uiVector Ind, cfVector X,
                                   cfVector Y, ui size );
                ui VCF_cmp_neVind( uiVector Ind, cfVector X,
                                   cfVector Y, ui size );
                   (similarly VCD_ and  VCE_ versions)
Description     Each element of X is compared with either 0, or a constant C,
                or the corresponding element of another vector, Y. The
                conditions to be tested are denoted by two letters as in
                ASSEMBLER or FORTRAN:
                "eq"  ("equal"):            True, if  Xi  = 0  (C, Yi, resp.)
                "ne"  ("not equal"):        True, if  Xi != 0  (C, Yi, resp.)
                "gt"  ("gteater than"):     True, if  Xi  > 0  (C, Yi, resp.)
                "ge"  ("greater or equal"): True, if  Xi >= 0  (C, Yi, resp.)
                "lt"  ("less than"):        True, if  Xi  < 0  (C, Yi, resp.)
                "le"  ("less or equal"):    True, if  Xi <= 0  (C, Yi, resp.).

                For complex numbers, only the testing for equality ("eq") or
                inequality ("ne") makes sense and is available.

                There are two different ways how the result of the comparison
                is treated. The result for each element of X is either stored
                as 1.0 for TRUE and 0.0 for FALSE in a vector of a floating-
                point data type (with the imaginary part in the complex
                versions always set to 0), or the indices of the elements for
                which the result is TRUE are stored in an index vector; the
                latter is the case in the functions with the suffix "ind" as
                the last part of their names, like in VF_cmp_neCind. In any
                case, the number of TRUE results encountered is returned by
                the function. The index-finding variant is especially useful
                to extract the elements for which the condition is TRUE into a
                sub-vector by VF_indpick; be sure to check that the return
                value nTrue is non-zero if you wish to do that (remember that
                the parameter size for any of the functions of this VectorLib
                library must be non-zero!).
Error handling  none
Return value    number of elements for which the condition was found to be
                TRUE.
See also        VF_cmp0, VF_cmpC, VF_cmpV, VF_indpick, VF_iselementC


Ŀ
 VF_comb                  VD_comb                  VE_comb                  

Function        Initializes a vector with a comb function.
Syntax          #include <VFstd.h>
                void VF_comb( fVector X, ui size, ui spac, float C );
Description     Xi  = C,     i = 0,  1*spac,  2*spac,...
                Xi  = 0,     otherwise
Error handling  If the spacing spac of the comb exceeds size, an error message
                "Invalid parameter(s)" is displayed and the program aborted.
Return value    none
See also        VF_equ1, VF_equ0, VF_equC


Ŀ
 VCF_complex              VCD_complex              VCE_complex              

Function        Constructs a Cartesian complex vector from its real and
                imaginary parts. Implemented as a macro that calls VF_ReImtoC,
                VD_ReImtoC, VE_ReImtoC, resp.  See these functions for details.


Ŀ
 VCF_conj                 VCD_conj                VCE_conj                  

Function        Find the complex conjugate of a vector.
Syntax          #include <VCFmath.h>
                int  VCF_conj(  cfVector Y,  cfVector X,  ui size );
Description     Re(Yi)  =   Re(Xi)
                Im(Yi)  =  -Im(Xi)
Error handling  none
Return value    always 0
See also        VCF_neg,  VF_abs


Ŀ
 VF_convolve              VD_convolve              VE_convolve              

Function        Calculates the convolution of a vector with a response
                function.
Syntax          #include <VFstd.h>
                void VF_convolve( fVector Y, fVector Flt, fVector X,
                                  fVector Rsp, ui size );
Description     The convolution of X with the response function Rsp is
                calculated and stored in Y.  A filter Flt is also calculated.
                If more than one vector is to be convolved with the same Rsp,
                use VF_convolve only once and use VF_filter for the other
                vectors.
                The response has to be stored in Rsp in wrap-around order:
                the response for zero and positive times (or whatever the
                independent variable is) is stored in Rsp[0]  to Rsp[size/2]
                and the response for negative times (beginning with the most
                negative time) in Rsp[size/2+1] to Rsp[size-1].  You may wish
                to use VF_rotate or VF_reflect to achieve this wrap-around
                order and to construct the response vector.
                Notice that Rsp has to be of the same size as X.

                The result of the convolution appears scaled with the sum
                of all elements of Rsp. Normally, therefore, Rsp should be
                normalized to 1.0.

                X, Y, Rsp, and Flt must all be of the same size, which has to
                be an integer power of 2.  X may be overwritten by Y, Rsp may
                be overwritten by Flt, but X and Flt as well as Y and Rsp
                have to be distinct from each other.

                The treatment of round-off errors in the construction of
                Flt may be modified by VF_setRspEdit.

Example         VF_ramp(  Time,  1024, 0.0, 1.0 );
                VF_Gauss( Rsp, Time, 513, 10.0, 0.0, 1.0 );
                      /* Response function for zero and positive times */
                VF_reflect( Rsp+1, 1023 );
                      /* ... and for negative times  */
                VF_divC( Rsp, Rsp, 1024, VF_sum( Rsp, 1024 ) );
                      /*  Normalisation of Rsp */
                VF_convolve(  X, Rsp, X, Rsp, 1024 );
                      /* Convolution;  X is overwritten by the desired result
                         and Rsp is overwritten by the frequency filter    */
                VF_filter( Y, Y, Rsp, 1024 );
                      /* Next convolution: instead of another call to
                         VF_convolve,  Y is filtered using the frequency
                         filter just obtained                            */

                Mathematically, this convolution is based on the assumption
                that X is periodic; it still works well if X is non-periodic
                but converges on both ends to the same value X[0] = X[size-1].
                If that is not the case, the first and the last elements of Y
                are spoiled by "wrap-around" from elements on the other side.
                Extrapolate X on both sides in order to imbed the original X
                in a larger vector, if wrap-around is a problem. The minimum
                number of elements to be added equals half the width of the
                response function. (In the case of an asymmetric response
                function, it is the broader wing that counts.) After con-
                volving the larger vector with the response function, it
                will be the dummy elements just added which become spoiled
                by wrap-around. Those elements of the result vector which
                correspond to the original X will represent the desired
                convolution of X with Rsp.
                If X is smoothly converging on both sides to different values,
                it is not necessary to employ the procedure just described.
                Rather, the difference between the end points may be regarded
                as a linear trend. In this case, remove the trend, convolve
                the resultant vector and add the trend to the result.

Example         d = (X[size-1] - X[0]) / (size-1);
                VF_ramp( Trend, size, 0.0, d );
                VF_subV( Y, X, Trend, size );
                VF_convolve( Y, Flt, Y, Rsp, size );
                VF_addV( Y, Y, Trend, size );

                You might notice that Flt is declared as fVector rather than
                cfVector,  although the information stored in Flt consists of
                complex numbers. The reason is that these numbers are stored
                in the packed complex format (as described for VF_FFT) which
                is used only in connection with Fourier-Transform operations
                of real vectors.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_convolve
                is based) complains "Size must be an integer power of 2"
                and the program is aborted.
Return value    none
See also        VF_filter,  VF_deconvolve, VF_FFT,  VF_autocorr, VF_xcorr,
                VF_spectrum


Ŀ
 VF_corrcoeff             VD_corrcoeff             VE_corrcoeff             

Function        Linear correlation coefficient between two distributions
Syntax          #include <VFstd.h>
                float VF_corrcoeff( fVector X, fVector Y, ui size,
                                    float Xmean, float Ymean );
Description     The linear correlation coefficient ("Pearson's r") takes on
                values between -1.0 and +1.0.  The mean values of both
                distributions must be known. They are passed to VF_corrcoeff
                as the parameters Xmean and Ymean.
Example         r = VF_corrcoeff(  X,  Y,  n,  VF_mean( X, n ),
                                               VF_mean( Y, n ) );
Error handling  none
Return value    linear correlation coefficient r
See also        VF_mean,  VF_varianceV,  VF_linregress


Ŀ
 VF_cos                   VD_cos                   VE_cos                   
 VCF_cos                  VCD_cos                  VCE_cos                  
 VFx_cos                  VDx_cos                  VEx_cos                  
 VCFx_cos                 VCDx_cos                 VCEx_cos                 

Function        Cosine function
Syntax          #include <VFmath.h>
                int  VF_cos(   fVector  Y,  fVector  X, ui size );
                int  VFx_cos(  fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Beschreibung    normal versions:     Yi  =  cos ( Xi )
                expanded versions:   Yi  =  C *  cos (A*Xi + B )
                For large values of Xi, round-off error becomes appreciable;
                if the Xi values are representable as rational multiples of Pi,
                it is better to use  VF_cosrpi  than VF_cos.
Error handling  Precision errors in the real-value functions lead to a default
                result of 1.0 (as if the input were 0.0) and to a non-zero
                return value, but are otherwise ignored; _matherr is not
                called.
                OVERFLOW errors can only occur in the complex versions and
                lead to a result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cos2,  VF_cosrpi,  VF_sin,  VF_cosh,  VF_acos,  cos


Ŀ
 VF_cos2                  VD_cos2                  VE_cos2                  
 VFx_cos2                 VDx_cos2                 VEx_cos2                 

Function        Square of the cosine function
Syntax          #include <VFmath.h>
                int  VF_cos2(  fVector  Y,  fVector  X, ui size );
                int  VFx_cos2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  cos( Xi )
                expanded versions:  Yi  =  C *  cos(A*Xi + B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  Precision errors lead to a default result of 1.0 (as if the
                input were 0.0) and a non-zero return value, but are otherwise
                ignored; _matherr is not called.
                OVERFLOW errors can only occur in the complex versions and
                lead to a result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cos,   VF_cosrpi,   cos


Ŀ
 VF_cosec                 VD_cosec                 VE_cosec                 
 VFx_cosec                VDx_cosec                VEx_cosec                

Function        Cosecant function
Syntax          #include <VFmath.h>
                int  VF_cosec(  fVector  Y,  fVector  X, ui size );
                int  VFx_cosec( fVector  Y,  fVector  X, ui size,
                                float A, float B, float C );
Description     normal versions:     Yi =  cosec ( Xi )   =  1.0 / sin ( Xi )
                expanded versions:   Yi =  C * cosec ( A*Xi + B )
                The cosecant is defined as the inverse of the sine (not to be
                mistaken for the arcus function arcsin!) For large values of
                Xi, round-off error becomes appreciable; if the Xi values are
                representable as rational multiples of Pi, it is better to use
                VF_cosecrpi  than VF_cosec.
Error handling  For TLOSS precision errors, the default result is arbitrarily
                set to 1.0 (as an exception from the general rule which would
                require the result to be the mean of the results for +0 and -0.
                This would be 0.0. However, zero is not a valid result for the
                cosecant function). For SING and OVERFLOW errors, the default
                result is HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cosec2,  VF_cosecrpi,  VF_sin,  VF_cosech,  sin


Ŀ
 VF_cosec2                VD_cosec2                VE_cosec2                
 VFx_cosec2               VDx_cosec2               VEx_cosec2               

Function        Square of the cosecant function
Syntax          #include <VFmath.h>
                int  VF_cosec2(  fVector  Y,  fVector  X, ui size );
                int  VFx_cosec2( fVector  Y,  fVector  X, ui size,
                                 float A, float B, float C );
Description     normal versions:    Yi =  cosec ( Xi )
                expanded versions:  Yi =  C *  cosec ( A*Xi + B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  For SING, OVERFLOW, and TLOSS errors, the default result is
                HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cosec,   VF_cosecrpi,   sin


Ŀ
 VF_cosech                VD_cosech                VE_cosech                
 VFx_cosech               VDx_cosech               VEx_cosech               

Function        Hyperbolic cosecant function
Syntax          #include <VFmath.h>
                int  VF_cosech(  fVector  Y,  fVector  X, ui size );
                int  VFx_cosech( fVector  Y,  fVector  X, ui size,
                                 float A, float B, float C );
Description     normal versions:     Yi =  cosech ( Xi )
                expanded versions:   Yi =  C * cosech ( A*Xi+B )
Error handling  SING errors lead to a default result of 0 (mean of +HUGE_VAL
                and -HUGE_VAL); OVERFLOW errors lead to a default result
                of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sinh,  VF_exp,   sinh


Ŀ
 VF_cosecrpi             VD_cosecrpi              VE_cosecrpi               
 VF_cosecrpi2            VD_cosecrpi2             VE_cosecrpi2              
 VF_cosecrpi3            VD_cosecrpi3             VE_cosecrpi3              

Function        Cosecant function of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int VF_cosecrpi(  fVector Y, iVector P, ui size, int q );
                int VF_cosecrpi2( fVector Y, iVector P, ui size, int q );
                int VF_cosecrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  cosec( (P[i] / q) * Pi )
                The cosecant of fractional multiples of Pi is calculated.
                There are three versions: VF_cosecrpi is for general use
                with any arbitrary denominator q. If q is a power of 2,
                VF_cosecrpi2 should be used which is a highly optimized
                version using a look-up table. If q is a multiple of 3,
                VF_cosecrpi3 should be used. VF_cosecrpi2 and VF_cosecrpi3
                work also with q values they are not optimized for; in this
                case, however, memory space is wasted for the tables.
Error handling  SING errors occur if P[i] / q  is exactly an integer number;
                the default result is 0.0 (which is the mean of +HUGE_VAL and
                -HUGE_VAL; in contrast to VF_cosec, 0.0 is chosen irrespective
                of the fact that it is not a valid result of the cosecant
                function);
                q must be non-zero; this is, however, not tested for.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cosec,    sin


Ŀ
 VF_cosectab2             VD_cosectab2             VE_cosectab2             
 VF_cosectab3             VD_cosectab3             VE_cosectab3             

                Table of cosecant values for arguments between 0 and Pi/2.
Syntax          #include <xmath.h>
                extern float     VF_cosectab2[ VF_tabsz2+1 ];
                extern double    VD_cosectab2[ VD_tabsz2+1 ];
                extern extended  VE_cosectab2[ VE_tabsz2+1 ];
                extern float     VF_cosectab3[ VF_tabsz3+1 ];
                extern double    VD_cosectab3[ VD_tabsz3+1 ];
                extern extended  VE_cosectab3[ VE_tabsz3+1 ];
Description     VF_cosectab2[ i ]  =  cosec( i/(2*VF_tabsz2) * Pi ),
                                                      i=0,...,VF_tabsz2-1
                VF_cosectab3[ i ]  =  cosec ( i/(2*VF_tabsz3) * Pi ),
                                                      i=0,...,VF_tabsz3-1
                VF_cosectab2[ VF_tabsz2 ]  =  VF_cosectab3[ VF_tabsz3 ] = 0
                These look-up tables of cosecant values for arguments between
                0 and Pi/2 are used by VF_cosecrpi2 and the other functions
                of that family and are also available to the user. Since the
                cosecant of Pi/2 is not defined, zero is stored at its place.
                The symbols VF_tabsz2 etc., denoting the size of the tables,
                are defined in <xmath.h>.
See also        VF_cosecrpi2,  VF_tantab2,  VF_sintab2


Ŀ
 VF_cosh                  VD_cosh                  VE_cosh                  
 VCF_cosh                 VCD_cosh                 VCE_cosh                 
 VFx_cosh                 VDx_cosh                 VEx_cosh                 
 VCFx_cosh                VCDx_cosh                VCEx_cosh                

Function        Hyperbolic cosine function
Syntax          #include <VFmath.h>
                int  VF_cosh(  fVector  Y,  fVector  X, ui size );
                int  VFx_cosh( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
                int  VCF_cosh(  cfVector Y,  cfVector X, ui size );
                int  VCFx_cosh( cfVector Y,  cfVector X, ui size,
                                fComplex A, fComplex B, fComplex C );
Description     normal versions:     Yi =  cosh ( Xi )
                expanded versions:   Yi =  C * cosh ( A*Xi+B )
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sinh,  VF_exp,   cosh


Ŀ
 VF_cosrpi                VD_cosrpi                VE_cosrpi                
 VF_cosrpi2               VD_cosrpi2               VE_cosrpi2               
 VF_cosrpi3               VD_cosrpi3               VE_cosrpi3               

Function        Cosine function of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int VF_cosrpi(  fVector Y, iVector P, ui size, int q );
                int VF_cosrpi2( fVector Y, iVector P, ui size, int q );
                int VF_cosrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  cos( (P[i] / q) * Pi )
                The cosine of fractional multiples of Pi is calculated. There
                are three versions: VF_cosrpi is for general use with any
                arbitrary denominator q. If q is a power of 2,  VF_cosrpi2
                should be used which is a highly optimized version reading the
                results from a look-up table, if possible. If q is a multiple
                of 3,  VF_cosrpi3 should be used. VF_cosrpi3 offers a
                convenient way to use degrees instead of radians; if, for
                example, q is 180, the unit of the elements of P is "degree".
                VF_cosrpi2 and VF_cosrpi3 work also with q values they are not
                optimized for; in this case, however, memory space is wasted
                for the tables.
Error handling  These functions are error-proof, as long as q != 0.
Return value    always 0
See also        VF_cos,    cos


Ŀ
 VF_cot                   VD_cot                   VE_cot                   
 VFx_cot                  VDx_cot                  VEx_cot                  

Function        Cotangent function
Syntax          #include <VFmath.h>
                int  VF_cot(   fVector  Y,  fVector  X, ui size );
                int  VFx_cot(  fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:     Yi  =  cot ( Xi )
                expanded versions:   Yi  =  C * cot ( A*Xi+B )
                The cotangent is defined as the inverse of the tangent (not to
                be mistaken for the arcus function arctan!) For large values
                of Xi, round-off error becomes appreciable; if the Xi values
                are representable as rational multiples of Pi, it is better to
                use VF_cotrpi  than VF_cot.
Error handling  For TLOSS precision errors, the default result is 0.0 (which
                is the mean of +HUGE_VAL and -HUGE_VAL); for SING and OVERFLOW
                errors, the default result is HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cot2,  VF_cotrpi,  VF_coth,  VF_atan,  VF_atan2, tan


Ŀ
 VF_cot2                  VD_cot2                  VE_cot2                  
 VFx_cot2                 VDx_cot2                 VEx_cot2                 

Function        Square of the cotangent function
Syntax          #include <VFmath.h>
                int  VF_cot2(  fVector  Y,  fVector  X, ui size );
                int  VFx_cot2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:   Yi  =  cot( Xi )
                expanded versions: Yi  =  C *  cot( A*Xi+B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  For SING,  OVERFLOW and TLOSS errors, the default result is
                +HUGE_VAL (multiplied by the sign of C in the expanded
                versions).
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cot,   VF_cotrpi,   sin


Ŀ
 VF_coth                  VD_coth                  VE_coth                  
 VFx_coth                 VDx_coth                 VEx_coth                 

Function        Hyperbolic cotangent function
Syntax          #include <VFmath.h>
                int  VF_coth(  fVector  Y,  fVector  X, ui size );
                int  VFx_coth( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:     Yi  =  coth ( Xi )
                expanded versions:   Yi  =  C * coth ( A*Xi+B )
Error handling  SING errors lead to a default result of 0.0 (the mean of
                +HUGE_VAL and -HUGE_VAL);  OVERFLOW errors lead to a default
                result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sinh,  VF_tanh,  VF_exp,   tanh


Ŀ
 VF_cotrpi                VD_cotrpi                VE_cotrpi                
 VF_cotrpi2               VD_cotrpi2               VE_cotrpi2               
 VF_cotrpi3               VD_cotrpi3               VE_cotrpi3               

Function        Cotangent function of rational multiples of Pi
Syntax          #include <VFmath.h>
                int VF_cotrpi(  fVector Y, iVector P, ui size, int q );
                int VF_cotrpi2( fVector Y, iVector P, ui size, int q );
                int VF_cotrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  cot( (P[i] / q) * Pi )
                The cotangent of fractional multiples of Pi is calculated.
                There are three versions: VF_cotrpi is for general use with
                any arbitrary denominator q. If q is a power of 2,  VF_cotrpi2
                should be used which is a highly optimized version using a
                look-up table. If q is a multiple of 3,  VF_cotrpi3 should be
                used. VF_cotrpi2 and VF_cotrpi3 also work with q values they
                are not optimized for; in this case, however, memory space is
                wasted for the tables.
Error handling  SING errors occur if P[i] / q  is a whole number. The default
                result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL);
                q must be non-zero; this is, however, not tested for.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cot,    tan


Ŀ
 VF_cprint                VD_cprint                VE_cprint                
 VCF_cprint               VCD_cprint               VCE_cprint               
 VI_cprint           VSI_cprint          VLI_cprint          VQI_cprint     
 VU_cprint           VUS_cprint          VUL_cprint          VUI_cprint     

Function        print a vector to the screen
Syntax          #include <VFstd.h>
                VF_cprint( fVector X, ui size, unsigned nperline );
Description     size elements of X are printed to the screen (or "console"),
                into the actual text window, nperline elements in each line.

                The display starts always with a new line. Please note that
                this may lead to an empty line at the beginning.
                Each line begins with the index of the first element printed
                into that line. The index is followed by a colon and by
                the requested nperline elements.
                Complex numbers are printed in braces, with the real and
                imaginary parts separated by a komma:  {Re, Im}.

                The display pauses every screenful. The user is prompted
                after each page to continue or to stop printing.
                The number of digits per element is determined by the
                available space, which depends in turn on the line width
                and on the parameter nperline.

                This family of functions is not available under Windows and
                should not be used within TurboVision programs.
Error handling  If nperline exceeds the maximum number of entries possible in
                the current text mode, an error message "Cannot use requested
                format (too many entries per line)!" is generated; in this
                case, the program chooses the maximum number nperline that is
                possible.
Return value    none
See also        cprintf, VF_fprint,  VF_print,  VF_write, VF_store


Ŀ
 VF_CtoAbs                VD_CtoAbs                VE_CtoAbs                

Function        Absolute value (magnitude) of complex numbers
Syntax          #include <VCFstd.h>
                void VF_CtoAbs( fVector Abs, cfVector X, ui size );
Description     Abs[i]  =  sqrt( Re(Xi) + Im(Xi) )
                The absolute value, i.e. the magnitude of each element of the
                complex vector X is calculated. This function is almost
                identical to VCF_abs, but does not perform any error handling.
Error handling  none
Return value    none
See also        VCF_abs,  VF_PolartoC, VF_CtoReIm, VF_CtoArg, VF_CtoNorm


Ŀ
 VF_CtoArg                VD_CtoArg                VE_CtoArg                

Function        Argument (angle) of complex numbers
Syntax          #include <VCFstd.h>
                void VF_CtoArg( fVector Arg, cfVector X, ui size );
Description     Arg[i]  =  arctan( Im(Xi) / Re(Xi) )
                The argument, i.e. the angle of each element of the complex
                vector X is calculated. For Cartesian coordinates {0, 0}, the
                angle is arbitrary and is set to zero.
                When necessary, depending on the signs of Re(Xi) and Im(Xi),
                Pi is added or subtracted from the arctan to obtain the
                correct quadrant.
Error handling  none
Return value    none
See also        VF_PolartoC, VF_CtoPolar, VF_atan2, VF_CtoAbs, VF_CtoReIm


Ŀ
 VF_CtoIm                 VD_CtoIm                 VE_CtoIm                 

Function        Extract the imaginary part from a complex vector.
Syntax          #include <VCFstd.h>
                void VF_CtoIm( fVector Im, cfVector X, ui size );
Description     The imaginary part of the complex vector X is extracted and
                stored in Im.
Error handling  none
Return value    none
See also        VF_CtoReIm, VF_ReImtoC,  VF_ImtoC, VF_PolartoC, VF_extract


Ŀ
 VF_CtoNorm               VD_CtoNorm               VE_CtoNorm               

Function        Norm (square of the absolute value) of complex numbers
Syntax          #include <VCFstd.h>
                void VF_CtoNorm( fVector Norm, cfVector X, ui size );
Description     Norm[i]  =  Re(Xi) + Im(Xi)
                This definition of the Norm of a complex number is the same as
                in C++, but it is not consistent with the usual definition in
                mathematics, where the term "norm" is used as a synomym for
                "absolute value" or "magnitude". As defined here, the Norm is
                the square of the absolute value. The absolute value itself is
                available by the functions VF_CtoAbs (without error handling)
                and VCF_abs (with error handling).
Error handling  none
Return value    none
See also        VF_PolartoC, VF_CtoReIm, VF_CtoArg, VF_CtoAbs


Ŀ
 VF_CtoPolar              VD_CtoPolar              VE_CtoPolar              

Function        Transformation of complex numbers from Cartesian into polar
                coordinates.
Syntax          #include <VCFstd.h>
                void VF_CtoPolar( fVector Mag, fVector Arg,
                                  cfVector X, ui size );
Description     The polar coordinates Mag (magnitude, absolute value) and Arg
                (argument, angle) of each element of the Cartesian complex
                vector X are calculated. For the Cartesian coordinates {0, 0},
                the polar coordinates are also set to {0, 0}.
Error handling  none
Return value    none
See also        VF_PolartoC,  VF_CtoReIm,  VF_CtoAbs,  VF_CtoArg,  VF_CtoNorm


Ŀ
 VF_CtoRe                 VD_CtoRe                 VE_CtoRe                 

Function        Extracts the real part from a complex vector.
Syntax          #include <VCFstd.h>
                void VF_CtoRe( fVector Re, cfVector X, ui size );
Description     The real part of the complex vector X is extracted and stored
                in Re.
Error handling  none
Return value    none
See also        VF_CtoReIm,  VF_ReImtoC,  VF_RetoC,  VF_PolartoC,  VF_extract


Ŀ
 VF_CtoReIm               VD_CtoReIm               VE_CtoReIm               

Function        Extracts the real and imaginary parts from a complex vector.
Syntax          #include <VCFstd.h>
                void VF_CtoReIm( fVector Re, fVector Im, cfVector X, ui size );
Description     The real and imaginary parts of the complex vector X are
                extracted and stored in Re and Im, resp.
Error handling  none
Return value    none
See also        VF_CtoRe,  VF_ReImtoC,  VF_RetoC,  VF_PolartoC,  VF_extract


Ŀ
 VF_cubic                 VD_cubic                 VE_cubic                 
 VCF_cubic                VCD_cubic                VCE_cubic                
 VFx_cubic                VDx_cubic                VEx_cubic                
 VCFx_cubic               VCDx_cubic               VCEx_cubic               

Function        Cubic (third power)
Syntax          #include <VFmath.h>
                int  VF_cubic(  fVector  Y,  fVector  X, ui size );
                int  VFx_cubic(  fVector  Y,  fVector  X, ui size,
                                 float A, float B );
Description     normal versions:   Yi  =  (Xi)**3
                expanded versions: Yi  =  (A*Xi+B)**3
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_square,   VF_quartic,  VF_sqrt,  VF_pow,  VF_ipow,  VF_poly


Ŀ
 VCF_dataPlot             VCD_dataPlot             VCE_dataPlot             

Function        Plot of a complex vector into an existing Cartesian complex
                plane.
Syntax          #include <Vgraph.h>
                void VCF_dataPlot( cfVector X, ui size,
                                   unsigned form,  COLORREF color );
Description     The vector X is plotted into a Cartesian complex plane that
                has to be already drawn by a prior call to either
                VCF_autoPlot, or VCF_2AutoPlot  or V_drawAxes.
                For a description of the parameters form and color, see
                VF_xyAutoPlot.
Error handling  none
Return value    none
See also        VCF_autoPlot,  VCF_2AutoPlot, VF_xyAutoPlot,  chapter 4.11


Ŀ
 VF_deconvolve            VD_deconvolve            VE_deconvolve            

Function        Deconvolution
Syntax          #include <VFstd.h>
                void VF_deconvolve( fVector Y, fVector Flt, fVector X,
                                    fVector Rsp, ui size );
Description     X is assumed to be the result of a convolution of some "true"
                profile with the response function Rsp; a deconvolution is
                attempted and stored in Y. A filter Flt is also calculated; if
                more than one vector is to be deconvolved with the same Rsp,
                use VF_deconvolve only once and use the filter Flt thus
                obtained to deconvolve other vectors by calling VF_filter.
                The response has to be stored in Rsp in wrap-around order:
                the elements for zero and positive times (or whatever the
                independent variable is) are stored as Rsp[0]  to Rsp[size/2]
                and the elements for negative times as Rsp[size/2+1] to
                Rsp[size-1].
                You may wish to use VF_rotate or VF_reflect to obtain the
                correct order when constructing the response vector.

                X, Y, Rsp, and Flt must all be of the same size, which has to
                be an integer power of 2.  X may be overwritten by Y, Rsp may
                be overwritten by Flt, but X and Flt as well as Y and Rsp
                have to be distinct from each other.

                Mathematically, Flt is the inverse of the Fourier transform of
                Rsp. If the Fourier transform of Rsp contains elements equal
                to zero, all information is lost for the respective frequency
                and no reconstruction is possible. The best one can do in
                this case is to accept this loss and to  deconvolve only up
                to those frequencies where still something is left to be
                reconstructed.
                You are therefore advised not to use this function blindly
                but rather to inspect the Fourier transform of Rsp and
                decide what to do on the basis of your specific application.
                If you wish to use this function nevertheless, you may rely
                on the automatic editing of the filter, built into
                VF_deconvolve. Thereby, Flt is set to zero (instead of
                infinity) at those frequences where all information has
                been lost. You may set the threshold for this implicit
                editing by VF_setRspEdit. In order to retrieve the threshold
                actually set, use VF_getRspEdit.

                This deconvolution is based on the implicit assumption that
                X is periodic; if this is not the case, see the description
                of  VF_convolve  about how to avoid end effects.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_deconvolve
                is based) complains "Size must be an integer power of 2" and
                the program is aborted.
                If, by VF_setRspEdit, you specified Trunc.Re = Trunc.Im = 0,
                SING errors may occur that are handled by setting Flt to
                HUGE_VAL at the respective frequency. During multiplication
                with the transform of X, this may lead to unhandled floating-
                point overflow errors (in case your guess of Rsp was wrong
                and there is some information left at the frequencies where
                you thought it was not).
Return value    none
See also        VF_filter,  VF_convolve, VF_FFT,  VF_xcorr, VF_spectrum


Ŀ
 VF_delete                VD_delete                VE_delete                
 VCF_delete               VCD_delete               VCE_delete               
 VI_delete           VSI_delete          VLI_delete          VQI_delete     
 VU_delete           VUS_delete          VUL_delete          VUI_delete     

Function        Delete one element from a vector
Syntax          #include <VFstd.h>
                void  VF_delete( fVector X, ui size, ui pos );
Description     This is one of the few functions where the input vector itself
                is changed, instead of being mapped onto an output vector.
                The element numbered  pos is deleted from the vector, and all
                the following elements are shifted one position lower; the
                last element is left undefined.
Error handling  none
Return value    none
See also        VF_rotate, VF_insert


Ŀ
 VF_derivC                VD_derivC                VE_derivC                

Function        Derivative of an array with respect to an independent
                variable sampled at constant intervals
Syntax          #include <VFstd.h>
                void  VF_derivC(  fVector Y,  fVector  X,  ui size,
                                  float DeltaT );
Description     Y(t) = dX(t) / dt.
                The vector X is assumed to be a function of a variable t; the
                t values themselves are equally spaced. Therefore, only the
                spacing, DeltaT, must be passed to the function. By parabolic
                interpolation, the derivative of X with respect to t is
                calculated. This function does the inverse of the integration
                by  VF_runintegralC.
Error handling  none
Return value    none
See also        VF_derivV,  VF_runintegralC


Ŀ
 VF_derivV                VD_derivV                VE_derivV                

Function        Derivative of one array with respect to another
Syntax          #include <VFstd.h>
                void  VF_derivV(  fVector Z, fVector X,  fVector Y, ui size );
Description     Z(X)  = dY(X) / dX.
                The derivative of  Y with respect to X is calculated by
                parabolic interpolation and stored in Z. If the elements of X
                are equally-spaced, it is better to use VF_derivC. The inverse
                procedure, i.e. integration, is performed by VF_runintegralV.
Error handling  none
Return value    none
See also        VF_derivC,  VF_runintegralV


Ŀ
 VF_distribution          VD_distribution          VE_distribution          

Function        Distribution function
Syntax          #include <VFstd.h>
                ui  VF_distribution(
                     uiVector Abund, fVector Limits, ui nbins,
                     fVector X, ui sizex,
                     int mode );
Description     This function counts the number of elements of X falling
                into each of the intervals defined by Limits. The abundances
                thus determined are stored in Abund.
                nbins is the number of elements of Limits, i.e. the number
                of intervals. sizex is the size of X.

                Limits must be in ascending order. The spacing between the
                elements of Limits need not necessarily be constant.

                The parameter mode specifies how to interpret the values
                given in Limits.
                  mode > 0:  Limits contains the upper limits of the
                             intervals
                  mode < 0:  Limits contains the lower limits of the
                             intervals
                  mode = 0:  Limits contains the mid-points of the intervals.
                             An element of X belongs to the element of Limits
                             closest to it. In case of exactly equal dis-
                             tances, the interval with the lower index is
                             chosen.
                             The interval defined by Limits[0] extends down
                             to -HUGE_VAL, the interval defined by
                             Limits[nbins-1] reaches up to +HUGE_VAL.

                The number of elements of X not falling into one of the
                intervals is returned. For mode > 0, these are the elements
                greater than the highest limit. For mode < 0, these are the
                elements smaller than the lowest limit.
                For mode = 0, the return value is always zero, because
                the intervals are open on both sides. So every element
                of X is accounted for in Abund.

                In order to get the normalized distribution function,
                use the sequence
                     VF_distribution( Abund, Limits, nbins, X, sizex, 0 );
                     V_UItoD( Y, Abund, nbins );
                     VD_divC( Y, Y, nbins, VD_integralV(Limits,Y,nbins) );

                After that, a call to
                     VD_runintegralC( Y, Y, nbins, 1.0 );
                yields the cumulated distribution function.
Error handling  none
Return value    number of elements of X not accounted for in Abund
See also        VF_searchV


Ŀ
 VF_divC                  VD_divC                  VE_divC                  
 VCF_divC                 VCD_divC                 VCE_divC                 
 VCF_divReC               VCD_divReC               VCE_divReC               
 VI_divC             VSI_divC            VLI_divC            VQI_divC       
 VU_divC             VUS_divC            VUL_divC            VUI_divC       

Function        Divide by a constant
Syntax          #include <VFmath.h>
                void VF_divC( fVector Y, fVector X, ui size, float C );
                void  VCF_divC(  cfVector Y,  cfVector X,  ui size,
                                 fComplex C );
                void  VCF_divReC( cfVector Y, cfVector X,  ui size,
                                  float CRe );
Description     Yi  =  Xi / C
                The integer versions perform an integer division, discarding
                the remainder; the remainder itself may be obtained by the
                functions of the VI_modC family.
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe by which the complex vector is divided.
Error handling  none
Return value    none
See also        VF_divV,   VF_addC,  VF_subC,  VF_mulC,  VF_divrC,  VF_modC,
                VF_visC,  VF_redC


Ŀ
 VF_divrC                 VD_divrC                 VE_divrC                 
 VCF_divrC                VCD_divrC                VCE_divrC                
 VCF_divrReC              VCD_divrReC              VCE_divrReC              
 VFx_divrC                VDx_divrC                VEx_divrC                
 VCFx_divrC               VCDx_divrC               VCEx_divrC               
 VI_divrC            VSI_divrC           VLI_divrC           VQI_divrC      
 VU_divrC            VUS_divrC           VUL_divrC           VUI_divrC      

Function        Reverse division: divide a constant by a vector
Syntax          #include <VFmath.h>
                void  VF_divrC( fVector Y, fVector X, ui size, float C );
                void  VFx_divrC( fVector Y, fVector X, ui size,
                                 float A, float B, float C );
                void  VCF_divrC( cfVector Y,  cfVector X,  ui size,
                                 fComplex C );
                void  VCFx_divrC( cfVector Y, cfVector X, ui size,
                                  fComplex A, fComplex B, fComplex C );
                void  VCF_divrReC( cfVector Y, cfVector X,  ui size,
                                   float CRe );
Description     normal versions:   Yi  =   C / Xi
                expanded versions: Yi  =   C / (A*Xi+B)
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe which are divided by the complex vector.
Error handling  none;  for the floating-point versions, there are related
                functions that calculate  1.0 / Xi   and  1.0 / (A*Xi+B):
                VF_inv and VFx_inv, respectively; both of these detect and
                handle SING errors.
Return value    none
See also        VF_divV,  VF_inv, VF_addC,  VF_subC,  VF_mulC,  VF_divC,
                VF_modC, VF_visC,  VF_redC


Ŀ
 VF_divrV                 VD_divrV                 VE_divrV                 
 VCF_divrV                VCD_divrV                VCE_divrV                
 VCF_divrReV              VCD_divrReV              VCE_divrReV              
 VFx_divrV                VDx_divrV                VEx_divrV                
 VCFx_divrV               VCDx_divrV               VCEx_divrV               
 VCFx_divrReV             VCDx_divrReV             VCEx_divrReV             
 VI_divrV            VSI_divrV           VLI_divrV           VQI_divrV      
 VU_divrV            VUS_divrV           VUL_divrV           VUI_divrV      

Function        Divide two vectors in reverse order
Syntax          #include <VFmath.h>
                void  VF_divrV( fVector Z, fVector X, fVector Y, ui size );
                void  VFx_divrV( fVector Z,  fVector X, fVector Y,
                                 ui size, float A,  float  B );
                void  VCF_divrV( cfVector Z, cfVector  X, cfVector Y,
                                 ui size );
                void  VCF_divrReV( cfVector Z, cfVector X, fVector Y,
                                   ui size );
                void  VCFx_divrV(  cfVector Z, cfVector X, cfVector Y,
                                   ui size, fComplex A, fComplex B );
                void  VCFx_divrReV( cfVector Z, cfVector X, fVector Y,
                                    ui size, fComplex A, fComplex B );
Description     normal versions:   Zi  =   Yi / Xi
                expanded versions: Zi  =   Yi / (A*Xi+B)
                The complex floating-point versions exist in two variants: in
                the first variant (e.g., VCF_divrV,  VCFx_divrV), X, Y, and Z
                are all complex; in the second variant, Y is real-valued
                (e.g., VCF_divrReV - "division in reverse order: divide a
                real vector by a complex one").
Error handling  none
Return value    none
See also        VF_divrC,  VF_addV,  VF_mulV,  VF_modV,  VF_visV,  VF_redV


Ŀ
 VF_divV                  VD_divV                  VE_divV                  
 VCF_divV                 VCD_divV                 VCE_divV                 
 VCF_divReV               VCD_divReV               VCE_divReV               
 VFs_divV                 VDs_divV                 VEs_divV                 
 VFx_divV                 VDx_divV                 VEx_divV                 
 VCFx_divV                VCDx_divV                VCEx_divV                
 VCFx_divReV              VCDx_divReV              VCEx_divReV              
 VI_divV             VSI_divV            VLI_divV            VQI_divV       
 VU_divV             VUS_divV            VUL_divV            VUI_divV       

Function        Divide two vectors
Syntax          #include <VFmath.h>
                void VF_divV( fVector Z, fVector X, fVector Y, ui size );
                void VFs_divV( fVector Z, fVector X, fVector Y, ui size,
                               float C );
                void VFx_divV( fVector Z,  fVector X, fVector Y,
                               ui size, float A,  float  B );
                void  VCF_divV( cfVector Z, cfVector  X, cfVector Y,
                                ui size );
                void  VCF_divReV( cfVector Z, cfVector X, fVector Y,
                                  ui size );
                void  VCFx_divV(  cfVector Z, cfVector X, cfVector Y,
                                  ui size, fComplex A, fComplex B );
                void  VCFx_divReV( cfVector Z, cfVector X, fVector Y,
                                   ui size, fComplex A, fComplex B );
Description     normal versions:    Zi  =  Xi / Yi
                scaled versions:    Zi  =  C * (Xi / Yi)
                expanded versions:  Zi  =  (A*Xi+B) / Yi
                The complex floating-point versions exist in two variants: in
                the first variant (e.g., VCF_divV,  VCFx_divV),  X, Y, and Z
                are all complex; in the second variant, Y is real-valued
                (e.g., VCF_divReV - "divide by a real vector").
Error handling  none
Return value    none
See also        VF_divC,  VF_addV,  VF_mulV,  VF_modV,  VF_visV,  VF_redV


Ŀ
 V_drawAxes                                                                 

Function        Draws a Cartesian coordinate system.
Syntax          #include <Vgraph.h>
                void V_drawAxes( long double Xmin, long double Xmax,
                                 long double Ymin, long double Ymax );
Description     A Cartesian coordinate system is drawn with the axes scaled
                according to the values passed as Xmin, Xmax, Ymin, and Ymax.
                Ten subdivision lines are drawn on each axis. No adjustment
                of this scaling is performed; if automatic fine-tuning of the
                scaling is desired, call V_findAxes instead. Before using this
                function, either V_initGraph or V_initPlot has to be called.
                V_drawAxes is used internally by all functions of the AutoPlot
                family.
Error handling  none
Return value    none
See also        V_findAxes,   V_initPlot,   VF_xyAutoPlot,   VF_xyDataPlot,
                chapter 4.11


Ŀ
 V_DtoF                   V_DtoE                                            

Function        Data type conversions.  See V_FtoD.


Ŀ
 VF_equ0                  VD_equ0                  VE_equ0                  
 VCF_equ0                 VCD_equ0                 VCE_equ0                 
 VI_equ0             VSI_equ0            VLI_equ0            VQI_equ0       
 VU_equ0             VUS_equ0            VUL_equ0            VUI_equ0       

Function        (Re-) initialize a vector with zero.
Syntax          #include <VFstd.h>
                void VF_equ0( fVector X, ui size );
Description     Xi = 0
Error handling  none
Return value    none
See also        VF_equ1, VF_equC, VF_equV


Ŀ
 VF_equ1                  VD_equ1                  VE_equ1                  
 VCF_equ1                 VCD_equ1                 VCE_equ1                 

Function        Initialize a vector with 1.0.
Syntax          #include <VFstd.h>
                void VF_equ1( fVector X,  ui size );
Description     Xi = 1.0
                In the complex versions, the imaginary parts are set to zero.
Error handling  none
Return value    none
See also        VF_equ0, VF_equC, VF_equV


Ŀ
 VF_equC                  VD_equC                  VE_equC                  
 VCF_equC                 VCD_equC                 VCE_equC                 
 VI_equC             VSI_equC            VLI_equC            VQI_equC       
 VU_equC             VUS_equC            VUL_equC            VUI_equC       

Function        Initializes a vector with a constant value.
Syntax          #include <VFstd.h>
                void VF_equC(  fVector X,  ui size, float C );
Description     Xi = C
Error handling  none
Return value    none
See also        VF_equ0, VF_equ1, VF_equV, VF_comb



Ŀ
 VF_equV                  VD_equV                  VE_equV                  
 VCF_equV                 VCD_equV                 VCE_equV                 
 VFx_equV                 VDx_equV                 VEx_equV                 
 VCFx_equV                VCDx_equV                VCEx_equV                
 VI_equV             VSI_equV            VLI_equV            VQI_equV       
 VU_equV             VUS_equV            VUL_equV            VUI_equV       

Function        Copies one vector to another.
Syntax          #include <VFstd.h>
                void VF_equV(  fVector Y, fVector X, ui size );
                void VFx_equV( fVector Y, fVector X,  ui size,
                               float A,  float B );
Description     normal versions:     Yi = Xi
                expanded versions:   Yi = A * Xi + B
Error handling  none
Return value    none
See also        VF_equ0, VF_equ1, VF_equC,  memcpy, memmove, movmem


Ŀ
 VF_Euclid                VD_Euclid                VE_Euclid                

Function        Calculates the Euclidean norm of a vector
Syntax          #include <VFstd.h>
                float VF_Euclid( fVector X, ui size );
Description     norm  =  sqrt(  sum( Xi ) )
                The Euclidean norm of a vector is defined as the square-root
                of the scalar product of the vector with itself.
Error handling  none  (but beware of a possible overflow!)
Return value    The Euclidean norm is returned
See also        VF_ssq, VF_rms, VF_scalprod, VF_xprod


Ŀ
 VF_exp                   VD_exp                   VE_exp                   
 VCF_exp                  VCD_exp                  VCE_exp                  
 VFx_exp                  VDx_exp                  VEx_exp                  
 VCFx_exp                 VCDx_exp                 VCEx_exp                 

Function        Exponential function
Syntax          #include <VFmath.h>
                int  VF_exp(   fVector  Y,  fVector  X, ui size );
                int  VFx_exp(  fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  exp( Xi )
                expanded versions:  Yi  =  C *  exp( A*Xi+B )
                Euler's constant e is raised to the Xi'th power.  Variants of
                the exponential function, like its complement (VF_expc), the
                hyperbolic functions (e.g. VF_sinh) or the Gaussian
                distribution (VF_Gauss) are also available; see chapter 4.6.6
                about "Exponentials" before using VF_exp for sums or other
                combinations of exponentials - maybe the desired function
                already exists.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_log,  VF_expc, VF_pow,  VF_sinh,  VF_exp2,  VF_Gauss,  exp


Ŀ
 VF_exp2                  VD_exp2                  VE_exp2                  
 VFx_exp2                 VDx_exp2                 VEx_exp2                 

Function        Exponential function to the basis 2
Syntax          #include <VFmath.h>
                int  VF_exp2(   fVector  Y,  fVector  X, ui size );
                int  VFx_exp2(  fVector  Y,  fVector  X, ui size,
                                float A, float B, float C );
Description     normal versions:    Yi  =  2 ** Xi
                expanded versions:  Yi  =  C *  2 ** ( A*Xi+B )
                Two is raised to the Xi'th power. These function names
                are used as synonyms for VF_pow2 etc.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_exp, VF_exp10, VF_ipow2, VF_scale2, VF_log2


Ŀ
 VF_exp10                 VD_exp10                 VE_exp10                 
 VFx_exp10                VDx_exp10                VEx_exp10                

Function        Exponential function to the basis 10
Syntax          #include <VFmath.h>
                int  VF_exp10(   fVector  Y,  fVector  X, ui size );
                int  VFx_exp10(  fVector  Y,  fVector  X, ui size,
                                 float A, float B, float C );
Description     normal versions:    Yi  =  10 ** Xi
                expanded versions:  Yi  =  C *  10 ** ( A*Xi+B )
                Ten is raised to the Xi'th power. These function names
                are used as synonyms for VF_pow10 etc.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_exp, VF_exp2, VF_ipow10, VF_scale10, VF_log10


Ŀ
 VF_expArbBase            VD_expArbBase            VE_expArbBase            
 VCF_expArbBase           VCD_expArbBase           VCE_expArbBase           
 VFx_expArbBase           VDx_expArbBase           VEx_expArbBase           
 VCFx_expArbBase          VCDx_expArbBase          VCEx_expArbBase          

Function        Exponential function of an arbitrary base
Syntax          #include <VFmath.h>
                int  VF_expArbBase(   fVector  Y,  fVector  X, ui size,
                                      float Base );
                int  VFx_expArbBase(  fVector  Y,  fVector  X, ui size,
                                      float Base, float A, float B, float C );
Description     normal versions:    Yi  =  Base ** Xi
                expanded versions:  Yi  =  C *  Base ** ( A*Xi+B )
                Base must be positive and non-zero in the real-number
                versions. In the complex versions, Base must be non-zero.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_exp, VF_pow


Ŀ
 VF_expc                  VD_expc                  VE_expc                  
 VFx_expc                 VDx_expc                 VEx_expc                 

Function        Calculate the "complementary exponential function" of each
                element of a vector.
Syntax          #include <VFmath.h>
                int  VF_expc(  fVector  Y,  fVector  X, ui size );
                int  VFx_expc( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  1  -  exp( Xi )
                expanded versions:  Yi  =  C * (1 - exp [A*Xi + B ])
                The difference between 1.0 and the exponential function of Xi
                is calculated. Note that the expc function is directly
                available from the 80x87 coprocessor in high accuracy; in
                fact, it is the exponential function itself that is internally
                calculated via the expc function. The expc function is often
                encountered in the natural sciences for the description of
                decay and growth processes.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_log,  VF_exp, VF_pow,  VF_sinh,  VF_exp2,  VF_Gauss,  exp


Ŀ
 VF_expmx2                VD_expmx2                VE_expmx2                
 VFx_expmx2               VDx_expmx2               VEx_expmx2               

Function        Exponential function of the negative square of the argument
Syntax          #include <VFmath.h>
                int  VF_expmx2(  fVector  Y,  fVector  X, ui size );
                int  VFx_expmx2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:     Yi  =  exp( -Xi )
                expanded versions:   Yi  =  C * exp( -(A*Xi+B) )
                This function yields a bell-shaped curve similar to the
                Gaussian function.
Error handling  This function should be error-proof.
Return value    always 0
See also        VF_log,  VF_exp,  VF_Gauss,  VF_sech2,  VF_Lorentz,  exp


Ŀ
 VF_FFT                   VD_FFT                   VE_FFT                   
 VCF_FFT                  VCD_FFT                  VCE_FFT                  

Function        Fast Fourier transform
Syntax          #include <VFstd.h>
                void VF_FFT(  fVector Y, fVector X, ui size, int dir );
Description     The Fourier transform of X is calculated and stored in Y. The
                forward transform is obtained by setting dir = 1,  the inverse
                (or backward) transform by setting dir = -1.  A Fast Fourier
                Transform algorithm is used that requires size to be a power
                of 2.
                Complex version: Both X and the output Y are complex vectors.
                Real version:  For the forward transform, X is a real vector.
                The output Y is also defined as fVector, although it consists
                of complex numbers. These are packed in a special way such
                as to fit into the same amount of memory as the original
                real vector X. The order of storage in Y is indicated in the
                following table (N=size, U is the uncompressed Fourier
                Transform of X):

Ŀ
  Y[0]      Y[1]        Y[2]    Y[3]   .......   Y[N-2]       Y[N-1]  
Ĵ
 U[0].Re  U[N/2].Re  U[1].Re  U[1].Im  ....... U[N/2-1].Re U[N/2-1].Im

                The reason for this packing is the following. If the size real
                data points of X represent a function of the time, X = g(t),
                then the forward transform yields a function U = G(f) in the
                frequency domain. In principle, U consists of size+1 complex
                data points:  size/2 points for positive frequencies, another
                size/2 points for negative frequencies, and one point at
                frequency zero.
                For the Fourier Transform of a real vector, the symmetry
                relation G(-f) = G(f)*  holds (the asterisc denoting the
                complex conjugate). This means that the points at
                negative frequencies need not be stored; all information is
                already contained in the positive frequency half. Moreover,
                the zeroth and the size2'th element of the transform are both
                purely real.  Therefore, only these two real and size/2-1
                complex data points have to be stored - which exactly fit
                into the same amount of memory as the original size real data
                points of X. This allows X to be overwritten by its transform,
                if desired.

                In cases where it is more convenient to obtain the unpacked
                complex vector, the following sequence should to be used:
                   Y = VCF_vector0( size );
                         /* create Y as a zeroed complex Vector */
                   VF_RetoC( Y, X, size );
                         /* Y.Re = X, Y.Im remains zero */
                   VCF_FFT( Y, Y, size, 1 ) ;       /*  transform Y  */

                For the real version of the inverse transform, X has to be a
                complex vector packed in the way just described, and a real-
                valued vector Y is obtained.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  an error message "Size must be
                an integer power of 2" is generated and the program aborted.
Return value    none
See also        VF_filter, VF_convolve, VF_autocorr, VF_xcorr, VF_spectrum


Ŀ
 VF_filter                VD_filter                VE_filter                
 VCF_filter               VCD_filter               VCE_filter               

Function        Frequency filtering
Syntax          #include <VFstd.h>
                void VF_filter(	fVector Y,  fVector X,
                                fVector Flt,  ui size );
Description     A frequency filter Flt is applied to the vector X. Internally,
                this is done by performing a Fourier transform on X,
                multiplying the transform with Flt and transforming the
                product back into the time domain.

                Complex versions: X, Y and the filter Flt are complex vectors.
                Real versions:   X and Y are real.  Flt has to be in the
                packed complex format that is obtained by Fourier transforming
                a real vector with VF_FFT (see that function for the
                description of the packed complex format) or by using
                VF_convolve.

                If X is non-periodic, both ends of the filtered function may
                be spoiled by wrap-around. See VF_convolve about how to avoid
                end-effects by embedding X in a larger vector or by removing
                a possible linear trend.
                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_filter
                is based) complains "Size must be an integer power of 2"
                and the program is aborted.
Return value    none
See also        VF_FFT, VF_convolve, VF_autocorr, VF_xcorr, VF_spectrum


Ŀ
 V_findAxes                                                                 

Function        Calculate an appropriate scaling and draw a Cartesian
                coordinate system.
Syntax          #include <Vgraph.h>
                void V_findAxes( long double Xmin, long double Xmax,
                                 long double Ymin, long double Ymax );
Description     This function will rarely be called by the user, but is used
                internally in VF_xyAutoPlot and other plotting functions.
                According to the x- and y ranges given in the parameters Xmin,
                Xmax, Ymin and Ymax, a linear Cartesian coordinate system is
                drawn with ten subdivisions both for the  abscissa and the
                ordinate. If necessary, the x and y ranges are enlarged so as
                to meet the following conditions:
                1.  Every subdivision line represents an exact (and not
                    only a rounded) value.
                2.  If the range of one axis or both includes zero, zero
                    falls exactly on a subdivision line.

                If the automatic scaling is not desired, use V_drawAxes
                instead.
                Before calling V_findAxes, the plotting routines have to be
                initialized by either V_initGraph or V_initPlot.
Error handling  none
Return value    none
See also        V_drawAxes, V_initPlot, VF_xyAutoPlot


Ŀ
 VF_floor                 VD_floor                 VE_floor                 
 VF_floortoI              VD_floortoI              VE_floortoI              
 VF_floortoSI             VD_floortoSI             VE_floortoSI             
 VF_floortoLI             VD_floortoLI             VE_floortoLI             
 VF_floortoQI             VD_floortoQI             VE_floortoQI             
 VF_floortoU              VD_floortoU              VE_floortoU              
 VF_floortoUS             VD_floortoUS             VE_floortoUS             
 VF_floortoUL             VD_floortoUL             VE_floortoUL             
 VF_floortoUI             VD_floortoUI             VE_floortoUI             

Function        Rounding towards minus infinity
Syntax          #include <VFmath.h>
                int VF_floor(     fVector Y,   fVector X,  ui size );
                int VF_floortoI(  iVector Y,   fVector X,  ui size );
                int VF_floortoLI( liVector Y, fVector X,  ui size );
                int VF_floortoU(  uVector Y, fVector X,  ui size );
                     (similarly  all others)
Description     Each element of X is rounded to the nearest whole number that
                is less than or equal to the input number and the result
                stored in Y. The functions VF_floortoI, VF_floortoLI,
                VF_floortoU, etc. convert the result to the various integer
                data types (in the cases mentioned, to the types int,  long
                int, or unsigned, respectively).
Error handling  OVERFLOW errors are handled by setting the result to the
                extreme value possible. Negative numbers in the versions
                VF_floortoU, VF_floortoUS, VF_floortoUL, and VF_floortoUI
                lead to DOMAIN errors; they are handled by setting the result
                to 0.
Return value    0, if no error occurred, otherwise non-zero.
See also        ceil, floor, VF_round,  VF_ceil, VF_chop, VF_trunc


Ŀ
 VF_flush0                VD_flush0                VE_flush0                
 VCF_flush0               VCD_flush0               VCE_flush0               

Function        Sets vector elements with an absolute value less than a
                certain threshold to 0.
Syntax          #include <VFmath.h>
                void  VF_flush0(  fVector Y,  fVector X,  ui size,
                                  float  AbsMin );
                void  VCF_flush0( fVector Y,  fVector X,  ui size,
                                  fComplex  AbsMin );
Description     Yi  =  Xi,   if   Xi   >=  AbsMin,
                Yi  =  0,    otherwise
                The complex versions treat the real and imaginary parts
                separately, using the real and imaginary parts of AbsMin to
                determine where to cut. If only the imaginary part is to be
                edited, set the real part of AbsMin to zero, e.g.:
                   VCF_flush0( Y, X, size, fcplx( 0, 1.e-6 ));
Error handling  none
Return value    none
See also        VF_limit,  VF_maxC


Ŀ
 VF_fmodC                 VD_fmodC                 VE_fmodC                 
 VF_fmodV                 VD_fmodV                 VE_fmodV                 
 VFx_fmodV                VDx_fmodV                VEx_fmodV                

Function        Floating-point modulo division
Syntax          #include <VFmath.h>
                void VF_fmodC( fVector Y, fVector X, ui size, float C );
                void VF_fmodV( fVector Z, fVector X, fVector Y, ui size );
                void VFx_fmodV( fVector Z,  fVector X, fVector Y,
                                ui size, float A, float B );
Description     These functions have been included in order to provide
                consistency with ANSI C function names. They are implemented
                as macros that call VF_modC, VF_modV,  VFx_modV etc.  See
                these functions for details.


Ŀ
 VF_fprint                VD_fprint                VE_fprint                
 VCF_fprint               VCD_fprint               VCE_fprint               
 VI_fprint           VSI_fprint          VLI_fprint          VQI_fprint     
 VU_fprint           VUS_fprint          VUL_fprint          VUI_fprint     

Function        print a vector to a stream
Syntax          #include <VFstd.h>
                VF_fprint( FILE *stream, fVector X, ui size,
                           unsigned nperline, unsigned linewidth );
Description     size elements of X are written to stream,  nperline in each
                line of linewidth characters.

                Printing starts always with a new line. This may lead to
                an empty line at the beginning. Especially the first line
                of a file is reserved for a possible headline.

                Each line begins with the index of the first element printed
                into that line. The index is followed by a colon and by
                the requested nperline elements.
                Complex numbers are printed in braces, with the real and
                imaginary parts separated by a komma:   {Re, Im}.

                In contrast to VF_write and VF_nwrite, it is not possible
                to override the automatic choice of the format used for
                printing. The number of digits per element is determined
                by the available space, which depends in turn on the
                parameters nperline and linewidth.
Error handling  if nperline exceeds the maximum number of entries possible for
                the linewidth chosen, an error message "Cannot use requested
                format (too many entries per line)!" is generated; in this
                case, the program chooses the maximum number nperline
                possible.
Return value    none
See also        fprintf, VF_cprint, VF_print, VF_write, VF_store


Ŀ
 V_free                                                                     

Function        De-allocate a single vector
Syntax          #include <VecLib.h>
                void  V_free(  void *X );
Description     The vector X is freed (i.e. de-allocated). V_free  should be
                used only for the de-allocation of vectors which have
                previously be allocated by one of the functions of the
                VF_vector or VF_vector0  family. To free several vectors
                simultaneously, use V_nfree.
Error handling  Trying to free a vector that has already been freed, or that
                has never been allocated memory, leads to a warning message
                "Cannot free non-existent vector". Program execution is
                continued without freeing anything in this case.
Return value    none
See also        V_nfree,  V_freeAll, VF_vector,  VF_vector0


Ŀ
 V_freeAll                                                                  

Function        De-allocate all vectors
Syntax          #include <VecLib.h>
                void  V_freeAll(  void );
Description     All vectors previously be allocated by one of the functions
                of the VF_vector or VF_vector0  families are freed.
Error handling  none
Return value    none
See also        V_free,  V_nfree, VF_vector,  VF_vector0


Ŀ
 VF_frexp                 VD_frexp                VE_frexp                  

Function        Split up the elements of a vector into their mantissa and
                exponent parts.
Syntax          #include <VFmath.h>
                int  VF_frexp( fVector Mant, iVector Exp, fVector X,
                               ui size );
Description     The function is implemented as a macro calling VF_mantexp; the
                name VF_frexp is included only to maintain consistency with
                the ANSI C function name frexp. For details, see VF_mantexp
                and frexp.


Ŀ
 V_FtoD              V_FtoE              V_CFtoCD            V_CFtoCE       
 V_DtoF              V_DtoE              V_CDtoCF            V_CDtoCE       
 V_EtoF              V_EtoD              V_CEtoCF            V_CEtoCD       

Function        Data type interconversions.
Syntax          #include <VDstd.h>
                     (always include the <V..std.h>  file of the destination
                      data-type!)
                void V_FtoD(  dVector Y,  fVector X, ui size );
                     (similarly all other functions of this family)
Description     Each element of X is converted from the data type specified
                for X to the data type specified for Y and stored in Y.
Error handling  floating-point versions: OVERFLOW errors may occur in the
                course of the "down-conversions" (e.g., V_EtoF); by default,
                the extreme value possible for the destination data type is
                stored in Y with the correct sign. The occurrence of errors
                may be excluded by calling VE_limit or VD_limit (whichever
                is appropriate) prior to performing the data type conversion.
Return value    none
See also        VF_limit, V_ItoF, V_roundtoI, V_roundtoLI


Ŀ
 VF_Gauss                 VD_Gauss                 VE_Gauss                 

Function        Gaussian normal distribution function.
Syntax          #include <VFmath.h>
                int  VF_Gauss( fVector  Y,  fVector  X, ui size,
                               float Wid,  float Cent, float C );
Description     Yi   = C / (Wid * sqrt(2*Pi)) * exp( -0.5*((Xi-Cent) / Wid) )
                Wid  =  width of the distribution
                Cent =  center of the distribution
                C is a scaling factor; for C = 1.0, the distribution is
                normalized.
                For Wid = 0, the normal distribution is in fact a delta
                distribution with Y = C * INF  at X = Cent  and Y = 0 at
                all other values of X.
                Since infinities are not supported, the existence of a point
                X = Cent will lead to a SING error  in case Wid is zero.
Error handling  SING errors may occur only for a Wid of zero. They are
                handled with the default result set to HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_exp,  VF_sech2,  VF_Lorentz,  exp


Ŀ
 VF_getRspEdit            VD_getRspEdit            VE_getRspEdit            

Function        Read the present threshold for the editing of the filter in
                VF_convolve and VF_deconvolve
Syntax          #include <VFstd.h>
                fComplex  VF_getRspEdit( void );
Description     The threshold for the treatment of round-off errors in the
                functions for convolution and deconvolution is returned.
Error handling  none
Return value    present threshold.
                real part:      acts on the real parts of the filter elements
                imaginary part: acts on the imaginary parts of the filter
                                elements
See also        VF_setRspEdit,  VF_convolve,  VF_deconvolve


Ŀ
 VF_Hanning               VD_Hanning               VE_Hanning               

Function        "Hanning" window for use in spectral analysis
Syntax          #include <VFstd.h>
                void VF_Hanning( fVector X, ui size );
Description     Xi = 0.5 * (1 - cos( 2 Pi i / (size-1) ))
Error handling  none
Return value    none
See also        VF_Welch, VF_Parzen, VF_spectrum


Ŀ
 VF_hypC                  VD_hypC                  VE_hypC                  

Function        Quotient of Xi over the sum of Xi and a constant.
Syntax          #include <VFmath.h>
                void VF_hypC( fVector Y, fVector X, ui size, float C );
Description     Yi  =  hyp( Xi, C )  =  Xi / (Xi + C)
                The function calculating Yi according to this formula is
                dubbed "hyp" for its formal similarity to the expression
                constructing a hyperbola.
Error handling  none
Return value    none
See also        VF_hypV, VF_redC,  VF_addC,  VF_subC,  VF_divC,  VF_visC


Ŀ
 VF_hypV                  VD_hypV                  VE_hypV,                 
 VFx_hypV                 VDx_hypV                 VEx_hypV                 

Function        Quotient of Xi over the sum of Xi and Yi
Syntax          #include <VFmath.h>
                void  VF_hypV( fVector  Z, fVector  X, fVector  Y, ui size );
                void  VFx_hypV( fVector  Z,  fVector  X,  fVector  Y,
                                ui size, float  A,  float  B );
Description     normal versions:     Zi = hyp( Xi, Yi ) = Xi / (Xi + Yi)
                expanded versions:   Zi = hyp( A*Xi+B), Yi )
Error handling  none
Return value    none
See also        VF_hypC,  VF_redV,  VF_addV,  VF_subV,  VF_divV,  VF_visV


Ŀ
 VF_hypotC                VD_hypotC                VE_hypotC                

Function        Pythagoras "hypotenuse" function.
Syntax          #include <VFmath.h>
                int  VF_hypotC( fVector Y,  fVector X,  ui size, float C );
Description     Yi =  sqrt( Xi + C )
                This is a variant of the famous Pythagorean theorem for the
                hypotenuse of a right triangle.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL. Unlike
                the treatment of the ANSI C function hypot by several com-
                pilers, only an overflowing final result is regarded as an
                error. Intermediate overflows (by the calculation of the
                square) are avoided by appropriate scaling.
Return value    0, if no error occurred;  otherwise non-zero.
See also        VF_hypotV,  VF_redC,  VF_visC,  VCF_abs, hypot


Ŀ
 VF_hypotV                VD_hypotV                VE_hypotV                
 VFx_hypotV               VDx_hypotV               VEx_hypotV                                   

Function        Pythagoras "hypotenuse" function.
Syntax          #include <VFmath.h>
                int  VF_hypotV(  fVector Z, fVector X, fVector Y, ui size );
                int  VFx_hypotV( fVector Z, fVector X, fVector Y,
                                 ui size,  float A,  float B );
Description     normal version:    Yi =  sqrt( Xi + Yi )
                expanded version:  Yi =  sqrt( (A*Xi+B) + Yi )
                These are variants of the Pythagoras formula for the
                hypotenuse of a right triangle.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
                (Intermediate overflows are avoided by appropriate scaling.)
Return value    0, if no error occurred;  otherwise non-zero.
See also        VF_redC,  VF_visC,  VCF_abs, hypot


Ŀ
 VCF_imag                 VCD_imag                 VCE_imag                 

Function        Extracts the imaginary part from a complex vector. Implemented
                as a macro that calls VF_CtoIm, VD_CtoIm, VE_CtoIm, resp.  See
                these functions for details.


Ŀ
 VF_ImtoC                 VD_ImtoC                 VE_ImtoC                 

Function        Overwrites the imaginary part of a complex vector with a real-
                valued vector.
Syntax          #include <VCFstd.h>
                void VF_ImtoC( cfVector Y, fVector Im, ui size );
Description     The imaginary part of the complex vector Y is overwritten with
                the elements of the real-valued vector Im. The real part of Y
                is not affected.
Error handling  none
Return value    none
See also        VF_CtoReIm, VF_ReImtoC,  VF_RetoC,  VF_CtoIm, VF_PolartoC


Ŀ
 VF_indpick               VD_indpick               VE_indpick               
 VCF_indpick              VCD_indpick              VCE_indpick              
 VI_indpick          VSI_indpick         VLI_indpick         VQI_indpick    
 VU_indpick          VUS_indpick         VUL_indpick         VUI_indpick    

Function        Fill a vector with elements "picked" from another one
                according to their indices.
Syntax          #include <VFstd.h>
                void  VF_indpick( fVector Y, uiVector Ind, ui size,
                                  fVector X );
Description     Y[i] = X[ Ind[i] ],               i=0,..size-1
                The vector Y is filled with size elements taken from X
                according to their indices specified in Ind. The parameter
                size refers to Y and Ind. The size of X is unimportant, as
                long as the elements specified in Ind exist.
Error handling  none
Return value    none
See also        VF_indput, VF_subvector, VF_sortind


Ŀ
 VF_indput                VD_indput                VE_indput                
 VCF_indput               VCD_indput               VCE_indput               
 VI_indput           VSI_indput          VLI_indput          VQI_indput     
 VU_indput           VUS_indput          VUL_indput          VUI_indput     

Function        Distribute the elements of one vector to the places within
                another vector specified by their indices.
Syntax          #include <VFstd.h>
                void  VF_indput( fVector Y, fVector X, uiVector Ind,
                                 ui sizex );
Description     Y[ Ind[i] ] = X[i],               i=0,..sizex-1
                The sizex elements of X are put into the places of Y accor-
                ding to the indices specified in Ind. The parameter
                sizex refers to X and Ind. The size of Y is unimportant, as
                long as the elements specified in Ind exist.
Error handling  none
Return value    none
See also        VF_indpick, VF_subvector, VF_sortind


Ŀ
 V_initGraph                                                                

Function        Initializes Borland's graphics system and the plotting
                functions of the VectorLib library  (DOS only).
Syntax          #include <Vgraph.h>
                void V_initGraph( char *pathtodriver );
Description     In DOS programs, this function is used to initialize Borland's
                graphics system by calling Borland's function initgraph and to
                initialize the VectorLib plotting functions (by internally
                calling V_initPlot). The search-path for graphics driver
                files has to be passed as a pointer to the string pathtodriver
                (see initgraph for details). The function uses initgraph to
                automatically detect the graphics driver present. This
                automatic detection ensures that programs may run on different
                PC systems without changes in the source code. If, however, it
                causes problems or for other reasons is not desired, do not
                use V_initGraph (but first initgraph and then V_initPlot). The
                global variable V_gmode is set to the graphics mode with the
                highest resolution possible for the detected graphics driver.
                If initgraph has already been called, do not use V_initGraph,
                but call only V_initPlot. Normally, V_initGraph will be called
                at the beginning of a program that uses graphics; to switch
                back into text mode within the program, use restorecrtmode.
                The next call to one of the AutoPlot functions switches again
                into graphics mode. You may also do that yourself by using
                    setgraphmode( V_gmode );
                (to do this, the declaration  external int V_gmode;  has to
                appear in the module containing this call).

                At the end of the program, free the memory allocated for
                graphics operations and go back to the standard mode with
                closegraph.

                Windows programs do not use the BGI routines. Consequently,
                BGI initialization is available only under DOS, but not under
                Windows.   V_initPlot has to be used in order to prepare the
                VectorLib plotting operations under Windows.
Error handling  In case of failure, grapherrormsg is called, the appropriate
                error message displayed and the program aborted.
Return value    none
See also        V_initPlot,  initgraph, closegraph, V_setPlotRegion,
                VF_xyAutoPlot, VF_yAutoPlot, VF_xyDataPlot, VCF_autoPlot


Ŀ
 V_initPlot                                                                 

Function        Initialize the global variables used by the plotting functions
Syntax          #include <Vgraph.h>
                #ifdef _Windows
                    void V_initPlot( HWND vwindow,  HDC  vdc );
                #else
                    void V_initPlot( int graphmode );
                #endif
Description     DOS programs:
                   If the graphics system has been initialized by a call to
                   initgraph, V_initPlot is used to initialize the global
                   constants necessary for the operation of the VectorLib
                   plotting functions like VF_xyAutoPlot. If the graphics
                   system is not yet initialized, use V_initGraph to
                   initialize both the basic graphics system and the plotting
                   functions; a call to V_initPlot is not necessary then.
                   graphmode is the graphics mode set by initgraph.
                Windows programs:
                   vwindow is the handle for a window and vdc the handle of a
                   device context. As long as these handles remain valid,
                   future plotting operations (like VF_xyAutoPlot) will be
                   directed to the window specified by vwindow and use the
                   fonts defined in the device context vdc.  Be sure that
                   vwindow and vdc are still valid when a plotting operation
                   is performed; if in doubt, call  V_initPlot again.
                   If you use OWL, the handle of the actual window is always
                   available as HWindow.
                DOS and Windows:
                   V_initPlot reserves the rightmost about 2/3 of the screen
                   for following plotting operations, leaving one line empty
                   at the top of the screen and a few lines at the bottom.
                   To override this, call V_setPlotRegion after V_initPlot.
Error handling  none
Return value    none
See also        V_initGraph, VF_xyAutoPlot, V_findAxes, V_drawAxes,
                V_setPlotRegion, V_initPrint


Ŀ
 V_initPrint                                                                

Function        Initialize VectorLib plotting functions for use with
                a printer. Windows only!
Syntax          #include <Vgraph.h>
                void V_initPrint( HDC  printdc );
Description     This function exists only for Windows. It tells the VectorLib
                plotting functions to send their output to the printer context
                specified as printdc. By default, one whole page is reserved
                for the printout. To change this, call V_setPlotRegion
                after V_initPrint.
                To switch back to screen output, call V_initPlot.
Error handling  none
Return value    none
See also        V_initPlot, V_setPlotRegion, VF_xyAutoPlot


Ŀ
 VF_insert                VD_insert                VE_insert                
 VCF_insert               VCD_insert               VCE_insert               
 VI_insert           VSI_insert          VLI_insert          VQI_insert     
 VU_insert           VUS_insert          VUL_insert          VUI_insert     

Function        Insert an element into a vector
Syntax          #include <VFstd.h>
                void VF_insert( fVector X, ui size, ui pos, float C );
Description     This is one of the few functions where the input vector is
                changed itself (instead of being mapped onto an output
                vector). A new element is inserted at the position pos and has
                the value C. Elements before pos are unchanged, elements from
                pos on are shifted one position higher; the last element is
                lost. (If you wish to save the last element, choose size big
                enough to have a dummy element at the end of the vector; now
                it will be the dummy that gets lost.)
Error handling  none
Return value    none
See also        VF_delete, VF_rotate


Ŀ
 VF_integralC             VD_integralC             VE_integralC             

Function        Integral of an array plotted over an equally-spaced abscissa.
Syntax          #include <VFstd.h>
                float  VF_integralC( fVector X, ui size,
                                     float DeltaT );
Description     The vector X is assumed to be a function of a variable t; the
                t values themselves are equally spaced, so that only the
                spacing DeltaT is needed. The area under X, i.e. the integral
                of X over t from t[0] to t[size-1] is calculated. If not only
                the value of the integral is of interest, but a point-by-point
                integration has to be performed, VF_runintegralC should be
                used.
Error handling  none
Return value    The value of the integral is returned.
See also        VF_integralV,  VF_runintegralC,  VF_derivC


Ŀ
 VF_integralV             VD_integralV             VE_integralV             

Function        Integral
Syntax          #include <VFstd.h>
                float  VF_integralV( fVector X, fVector Y, ui size );
Description     The vector Y is assumed to be a function of X; the integral of
                Y over X is calculated. If the elements of X are regularly
                spaced with a constant difference between them, the integral
                is obtained more efficiently by VF_integralC. If not only the
                value of the integral is of interest, but a point-by-point
                integration has to be performed, VF_runintegralV may be used.
Error handling  none
Return value    The value of the integral is returned.
See also        VF_integralC,  VF_runintegralV,  VF_derivV


Ŀ
 VF_intfrac               VD_intfrac               VE_intfrac               

Function        Split up the elements of a vector into their integer and
                fractional parts.
Syntax          #include <VFmath.h>
                int  VF_intfrac( fVector IntPart, fVector FracPart,
                                 fVector X, ui size );
Description     The integer parts of the elements of X are stored in IntPart,
                the fractional parts in FracPart. Notice that IntPart is a
                floating-point vector, even though it contains integer numbers
                (which might be larger than could be stored in the integer
                data types).
Error handling  none
Return value    always 0
See also        modf,  VF_mantexp


Ŀ
 VF_inv                   VD_inv                   VE_inv                   
 VFx_inv                  VDx_inv                  VEx_inv                  
 VCF_inv                  VCD_inv                  VCE_inv                  
 VCFx_inv                 VCDx_inv                 VCEx_inv                 

Function        Inverse
Syntax          #include <VFmath.h>
                int  VF_inv(  fVector Y,  fVector  X,  ui size );
                int  VFx_inv( fVector Y,  fVector  X,  ui size,
                              float A,  float B );
Description     normal versions:   Yi = 1.0 / Xi
                expanded versions: Yi = 1.0 / (A*Xi+B)
Error handling  Division by zero is treated as a SING error with the default
                result set to HUGE_VAL. In the expanded versions, OVERFLOW
                errors may also occur; the default result is set to HUGE_VAL.
Return value    0, if no error occurred;  otherwise non-zero.
See also        VF_divrC,  VF_divrV


Ŀ
 VF_ipow                  VD_ipow                  VE_ipow                  
 VCF_ipow                 VCD_ipow                 VCE_ipow                 
 VFx_ipow                 VDx_ipow                 VEx_ipow                 
 VCFx_ipow                VCDx_ipow                VCEx_ipow                

Function        Raise each element of a vector to a specified integer power.
Syntax          #include <VFmath.h>
                int VF_ipow( fVector Y, fVector X, ui size, int Expo );
                int VFx_ipow( fVector Y, fVector X, ui size, int Expo,
                              float A, float B, float C );
Description     normal versions:   Yi = Xi**Expo
                expanded versions: Yi = C * (A*Xi+B)**Expo
                If Expo is larger than a data-type dependent threshold (which
                will be a very rare occasion), VF_ipow does not calculate the
                result itself, but calls VF_pow,  which is safer and faster in
                this case.
Error handling  SING errors occur, if zero is raised to a negative power; the
                default result is HUGE_VAL, as in the case of OVERFLOW
                errors.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_pow,  VF_poly,  VF_pow2,  VF_exp,  pow


Ŀ
 VF_ipow10                VD_ipow10                VE_ipow10                

Function        Integer powers of 10
Syntax          #include <VFmath.h>
                int  VF_ipow10(  fVector Y, iVector X, ui size );
Description     Yi  =  10**Xi
                Notice: this function (and not VF_pow10 !) is the vectorized
                form of the function pow10 defined in Borland C/C++.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_pow10,  VF_scale10,  VF_log10,  VF_ipow,  VF_exp,  pow


Ŀ
 VF_ipow2                 VD_ipow2                 VE_ipow2                 

Function        Integer powers of 2
Syntax          #include <VFmath.h>
                int  VF_ipow2(  fVector Y,  iVector X, ui size );
Description     Yi  =  2**Xi
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_pow2,  VF_scale2,  VF_log2,  VF_pow,  VF_exp,  pow


Ŀ
 VF_iselementC            VD_iselementC            VE_iselementC            
 VCF_iselementC           VCD_iselementC           VCE_iselementC           
 VI_iselementC       VSI_iselementC      VLI_iselementC      VQI_iselementC 
 VU_iselementC       VUS_iselementC      VUL_iselementC      VUI_iselementC 

Function        Test if one or more elements of a table are equal to C.
Syntax          #include <VFstd.h>
                int  VF_iselementC( fVector Tab, ui size, float C );
Description     The vector Tab is searched for the value C. If one or more
                elements are equal to C, TRUE (+1) is returned, otherwise
                FALSE (0). No ordering of Tab is assumed and a linear search
                performed. A related function that finds the table element
                closest (but not necessarily equal) to C is VF_searchC.
Error handling  none
Return value    +1, if C  is an element of X, otherwise 0.
See also        VF_searchC, VF_iselementV, lfind, lsearch


Ŀ
 VF_iselementV            VD_iselementV            VE_iselementV            
 VCF_iselementV           VCD_iselementV           VCE_iselementV           
 VI_iselementV       VSI_iselementV      VLI_iselementV      VQI_iselementV 
 VU_iselementV       VUS_iselementV      VUL_iselementV      VUI_iselementV 

Function        Test for each element of a vector, if an identical element is
                present in a table.
Syntax          #include <VFstd.h>
                ui  VF_iselementV(  fVector Y,  fVector X,  ui sizex,
                                    fVector Tab, ui sizetab );
Description     The table Tab is searched for each of the elements of X. For
                those elements of X which are found in Tab, the corresponding
                element of Y is set to +1 (in the complex versions: {1, 0} ).
                No ordering of X and Tab is assumed and a linear search for
                each Xi performed. A related function that finds the table
                element closest (but not necessarily equal) to each element of
                X  is VF_searchV.
Error handling  none
Return value    The number of elements of X for which an element of Tab was
                found is returned.
See also        VF_searchV, VF_iselementC


Ŀ
 VF_ismonoton             VD_ismonoton             VE_ismonoton             

Function        Test if the elements of a vector are monotonously increasing
                or decreasing
Syntax          #include <VFstd.h>
                int  VF_ismonoton( fVector X,  ui size );
Description     The vector X is analyzed. If the elements are in strict
                descending order, -1 is returned; if they are either constant
                or in strict ascending order, +1 is returned. Otherwise the
                return value is 0. If X contains passages that are increasing
                as well as passages that remain at a constant value, X is
                regarded as monotonous only if the increasing passage follows
                the constant passage, but not the other way round. Thus, the
                series 0, 0, 0, 1, 2, 3 will be accepted as monotonous (return
                value +1), whereas the series 1, 2, 3, 4, 4, 4 will not
                (return value 0). Also the initially constant, then falling
                series 0, 0, 0, -1, -2, -3 will not be regarded as monotonous.
Error handling  none
Return value    +1 in case of monotonous rise, or if all elements are
                identical, -1 in case of monotonously falling values,  0 if
                neither of these conditions is fulfilled.
See also        VF_sort


Ŀ
 V_ItoF                   V_ItoD                   V_ItoE                   
 V_SItoF                  V_SItoD                  V_SItoE                  
 V_LItoF                  V_LItoD                  V_LItoE                  
 V_QItoF                  V_QItoD                  V_QItoE                  
 V_UtoF                   V_UtoD                   V_UtoE                   
 V_UStoF                  V_UStoD                  V_UStoE                  
 V_ULtoF                  V_ULtoD                  V_ULtoE                  
 V_UItoF                  V_UItoD                  V_UItoE                  

Function        Convert integer numbers into floating-point data types.
Syntax          #include <VFstd.h>
                  (always the include-file belonging to the destination type!)
                void V_ItoF( fVector Y, iVector X, ui size );
                    (all other functions of this family are similar)
Description     Each element of X is converted from the data type int, short
                int, long int, quad, unsigned, unsigned short, unsigned long,
                or ui, resp., into the data type float, double, or extended,
                resp., and stored in Y. For the inverse procedure, i.e. the
                conversion of floating-point numbers to integers, the
                functions of the VF_roundtoI,  VF_floortoI,  VF_ceiltoI,  and
                VF_choptoI families have to be used.
Error handling  none
Return value    none
See also        VF_roundtoI,  VF_floortoI,  VF_ceiltoI,  VF_choptoI,
                VF_trunctoI,  V_ItoLI


Ŀ
 V_ItoSI                  V_ItoLI                  V_ItoQI                  
 V_SItoI                  V_SItoLI                 V_SItoQI                 
 V_LItoSI                 V_LItoI                  V_LItoQI                 
 V_QItoSI                 V_QItoI                  V_QItoLI                 
 V_UtoUS                  V_UtoUL                  V_UtoUI                  
 V_UStoU                  V_UStoUL                 V_UStoUI                 
 V_ULtoU                  V_ULtoUS                 V_ULtoUI                 
 V_UItoU                  V_UItoUS                 V_UItoUL                 
 V_ItoU                   V_SItoUS                 V_LItoUL                 
 V_UtoI                   V_UStoSI                 V_ULtoLI                 

Function        Interconversion of the integer data types
Syntax          #include <VLIstd.h>
                   (or <VIstd.h>,  <VUstd.h>,..., resp., depending on the
                    destination data type!)
                void V_ItoLI( liVector Y,  iVector X, ui size );
                    (all other functions of this family are similar)
Description     Each element of the vector X is converted into the desired
                data type and stored in Y.
Error handling  see chapter 5.2.
Return value    none
See also        V_ItoF


Ŀ
 VF_ldexp                 VD_ldexp                 VE_ldexp                 

Function        Scale by an integer power of 2.
Syntax          #include <VFmath.h>
                int  VF_ldexp( fVector Y, fVector X, ui size, int expo );
Description     These functions are implemented as alias names for VF_scale2
                etc., in order to maintain consistency with the ANSI C
                function name ldexp. For details, see VF_scale2.


Ŀ
 VF_limit                 VD_limit                 VE_limit                 
 VCF_limit                VCD_limit                VCE_limit                

Function        Limit the values of the elements of a vector to a specified
                range.
Syntax          #include <VFmath.h>
                void  VF_limit( fVector Y,  fVector X,  ui size,
                                float  Min,  float  Max );
                void  VCF_limit( cfVector Y,  cfVector X,  ui size,
                                 fComplex  Min,  fComplex  Max );
Description     Real version:
                    Yi  =  Xi ,   if  Min <=  Xi  <=  Max
                    Yi  =  Max,   if  Xi  >   Max
                    Yi  =  Min,   if  Xi  <   Min
                    This function may be seen as a combination of VF_maxC
                    and VF_minC.
                Complex version:
                    Similar to the real version, but the real and imaginary
                    parts are limited separately to the ranges specified in
                    the respective parts of Min and Max.
Error handling  none
Return value    none
See also        VF_maxC,   VF_minC,  VF_min,  VF_flush0


Ŀ
 VF_linregress            VD_linregress            VE_linregress            

Function        Linear regression
Syntax          #include <VFstd.h>
                void  VF_linregress( fVector Param,  fVector X,
                                     fVector Y, ui size );
Description     The X-Y data are fitted to a straight line  y = ax + b;  the
                parameters a and b are determined in such a way that the
                quantity
                  h = sum( (Yi - y(x=Xi) ) )
                is minimized. Uncertainties da and db are also determined. On
                output, Param is filled with the 5 elements {a, da, b, db, h}
                in the order indicated.
Error handling  none
Return value    none
See also        VF_linregresswW, VF_corrcoeff,  VF_chi2


Ŀ
 VF_lincomb               VD_lincomb               VE_lincomb               
 VCF_lincomb              VCD_lincomb              VCE_lincomb              

Function        linear combination of two vectors
Syntax          #include <VFstd.h>
                void  VF_lincomb( fVector Z, fVector X, fVector Y, ui size,
                                  float  CX, float  CY );
Descirption     Zi = CX * Xi  +  CY * Yi
Error handling  none
Return value    none
See also        VFx_addV


Ŀ
 VF_linregresswW          VD_linregresswW          VE_linregresswW          

Function        Linear regression with weights
Syntax          #include <VFstd.h>
                void  VF_linregresswW( fVector Param, fVector X,
                                       fVector Y, fVector InvVar, ui size );
Description     The X-Y data are weighted with the inverse of their variances
                and fitted to a straight line  y = ax + b; the parameters a
                and b are determined in such a way as to minimize the merit
                function
                  chi  =  sum(  (1 / Var[i]) * (Yi - y(x=Xi) ) )
                (see also VF_chi2). The inverse of the variance of each data
                point has to be passed to the function in the vector InvVar.
                Uncertainties da and db are also  determined. On output,
                Param is filled with the 5 elements {a, da, b, db, chi} in
                the order indicated.
Error handling  none
Return value    none
See also        VF_linregress, VF_corrcoeff,  VF_chi2


Ŀ
 V_LItoF                  V_LItoD                  V_LItoE                  

Function        Data type interconversions.  See V_ItoF!


Ŀ
 VF_ln                    VD_ln                    VE_ln                    
 VCF_ln                   VCD_ln                   VCE_ln                   
 VFx_ln                   VDx_ln                   VEx_ln                   
 VCFx_ln                  VCDx_ln                  VCEx_ln                  

Function        Natural logarithm
Syntax          #include <VFmath.h>
                int  VF_ln(  fVector  Y,  fVector  X, ui size );
                int  VFx_ln( fVector  Y,  fVector  X, ui size,
                             float A, float B, float C );
Description     These function names are synonyms for the functions of the
                VF_log family. See VF_log for details.


Ŀ
 VF_localmaxima           VD_localmaxima           VE_localmaxima           

Function        Find the indices of local maxima
Syntax          #include <VFstd.h>
                ui VF_localmaxima( uiVector Ind, fVector X,  ui size );
Description     The indices of local maxima in X are stored in Ind and the
                number of local maxima is returned (this is the number of
                elements of Ind). A local maximum is defined as one element
                of X that is greater than both its neighbours to the right
                and to the left. That means that the zeroth and the last
                element of X (which have only one neighbour) cannot be local
                maxima. Also, if two adjacent elements are equal, none of
                them can be a local maximum.
Error handling  none
Return value    number of local maxima found
See also        VF_maxind, VF_max, VF_indpick, VF_localminima


Ŀ
 VF_localminima           VD_localminima           VE_localminima           

Function        Find the indices of local minima
Syntax          #include <VFstd.h>
                ui VF_localminima( uiVector Ind, fVector X,  ui size );
Description     The indices of local minima in X are stored in Ind and the
                number of local minima is returned (this is the number of
                elements of Ind). A local minimum is defined as one element of
                X that is smaller than both its neighbours to the right and to
                the left. That means that the zeroth and the last element of X
                (which have only one neighbour) cannot be local minima. Also,
                if two adjacent elements are equal, none of them can be a
                local minimum.
Error handling  none
Return value    number of local minima found
See also        VF_minind, VF_min, VF_indpick, VF_localmaxima


Ŀ
 VF_log                   VD_log                   VE_log                   
 VCF_log                  VCD_log                  VCE_log                  
 VFx_log                  VDx_log                  VEx_log                  
 VCFx_log                 VCDx_log                 VCEx_log                 

Function        Natural logarithm
Syntax          #include <VFmath.h>
                int  VF_log(  fVector  Y,  fVector  X, ui size );
                int  VFx_log( fVector  Y,  fVector  X, ui size,
                              float A, float B, float C );
Description     normal versions:    Yi = ln( Xi )
                expanded versions:  Yi = C * ln( A*Xi+B )
                The "logarithmus naturalis", i.e. the logarithm to the basis
                of Euler's constant  e  is calculated.
Error handling  Real versions: DOMAIN errors occur in the case of negative Xi
                (including -0.0), with NAN ("not-a-number") as the default
                result. SING errors occur for Xi= +0.0 and yield a result of
                -HUGE_VAL. In the complex version, numbers with an imaginary
                part of zero are always treated as real numbers; therefore,
                an argument {0, 0} is treated as a real 0, causing a SING
                error with the default result {-HUGE_VAL,  0}.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_exp,  VF_log2,  VF_log10, VF_pow,  log


Ŀ
 VF_log10                   VD_log10                   VE_log10             
 VCF_log10                  VCD_log10                  VCE_log10            
 VFx_log10                  VDx_log10                  VEx_log10            
 VCFx_log10                 VCDx_log10                 VCEx_log10           

Function        Decadic logarithm
Syntax          #include <VFmath.h>
                int  VF_log10(  fVector  Y,  fVector  X, ui size );
                int  VFx_log10( fVector  Y,  fVector  X, ui size,
                                float A, float B, float C );
Description     normal versions:    Yi = lg( Xi )
                expanded versions:  Yi = C * lg( A*Xi+B )
                The decadic logarithm (to the basis of 10) is calculated.
Error handling  Real versions: DOMAIN errors occur in the case of negative Xi
                (including -0.0), with NAN ("not-a-number") as the default
                result. SING errors occur for Xi= +0.0 and yield a result of
                -HUGE_VAL. In the complex version, numbers with an imaginary
                part of zero are always treated as real numbers; therefore,
                an argument {0, 0} is treated as a real 0, causing a SING
                error with the default result {-HUGE_VAL,  0}.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_pow10,  VF_log,  VF_log2,  VF_pow,  log10


Ŀ
 VF_log2                   VD_log2                   VE_log2                
 VCF_log2                  VCD_log2                  VCE_log2               
 VFx_log2                  VDx_log2                  VEx_log2               
 VCFx_log2                 VCDx_log2                 VCEx_log2              

Function        Binary logarithm
Syntax          #include <VFmath.h>
                int  VF_log2(  fVector  Y,  fVector  X, ui size );
                int  VFx_log2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi = lb( Xi )
                expanded versions:  Yi = C * lb( A*Xi+B )
                The binary logarithm (to the basis 2) is calculated.
Error handling  Real versions: DOMAIN errors occur in the case of negative Xi
                (including -0.0), with NAN ("not-a-number") as the default
                result. SING errors occur for Xi= +0.0 and yield a result of
                -HUGE_VAL. In the complex version, numbers with an imaginary
                part of zero are always treated as real numbers; therefore,
                an argument {0, 0} is treated as a real 0, causing a SING
                error with the default result {-HUGE_VAL,  0}.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_pow2,  VF_log,  VF_log10,  VF_pow,  log2 (the latter
                function is not defined in ANSI C, but an addition contained
                in the VectorLib package, see chapter 9).


Ŀ
 VF_Lorentz               VD_Lorentz               VE_Lorentz               

Function        Lorentzian lineshape function
Syntax          #include <VFmath.h>
                int  VF_Lorentz( fVector Y,  fVector X,  ui siz,
                                 float Wid,  float Cent,  float C );
Description	Yi   = C *  Wid / ( (Xi - Cent) + Wid )
                Wid  = width of the resonance line
                Cent = centre of the line
                C is a scaling factor; at the center of the line (Xi=Cent),
                the amplitude Yi equals C. This is even true for a width of
                zero.
Error handling  This function should be error-proof.
Return value    always 0
See also        VF_Gauss,  VF_sech2


Ŀ
 VF_mantexp               VD_mantexp               VE_mantexp               

Function        Split up the elements of a vector into their mantissa and
                exponent parts
Syntax          #include <VFmath.h>
                int  VF_mantexp( fVector MantPart,  iVector ExpPart,
                                 fVector  X,  ui size );
Description     The elements of X are split up into their mantissa, stored in
                MantPart, and exponent, stored as ints in ExpPart.
Error handling  none
Return value    always 0
See also        VF_scale2,  VF_intfrac,  frexp,  ldexp


Ŀ
 VF_max                   VD_max                   VE_max                   
 VI_max              VSI_max             VLI_max             VQI_max        
 VU_max              VUS_max             VUL_max             VUI_max        

Function        Find the largest element of a vector.
Syntax          #include <VFstd.h>
                float  VF_max( fVector X, ui size );
Description     The vector X is searched for its largest element, whose value
                is returned.
Error handling  none
Return value    maximum value encountered.
See also        VF_min, VF_absmax, VF_runmax, VF_maxind


Ŀ
 VF_maxC                  VD_maxC                  VE_maxC                  
 VI_maxC            VSI_maxC             VLI_maxC            VQI_maxC       
 VU_maxC            VUS_maxC             VUL_maxC            VUI_maxC       

Function        Compare each element of a vector to a constant and take the
                larger of the two.
Syntax          #include <VFmath.h>
                void VF_maxC( fVector Y, fVector X, ui size, float C );
Description     Yi  =  Xi,      if  Xi  >   C
                Yi  =  C,       if  Xi  <=  C
Error handling  none
Return value    none
See also        VF_maxV,  VF_minC,  VF_max,  VF_absmax,  VF_limit, VF_flush0


Ŀ
 VF_maxind                VD_maxind                VE_maxind                
 VI_maxind           VSI_maxind          VLI_maxind          VQI_maxind     
 VU_maxind           VUS_maxind          VUL_maxind          VUI_maxind     

Function        Find the largest element of a vector and its index.
Syntax          #include <VFstd.h>
                float  VF_maxind( ui *Ind, fVector X, ui size );
Description     The vector X is searched for its largest element; its value is
                returned. At the address passed as Ind, the index of this
                element is stored.In the case of several maxima of equal
                height, the first one is chosen (i.e., the smallest index
                is stored in Ind).
Error handling  none
Return value    maximum value encountered.
See also        VF_max, VF_minind, VF_absmax, VF_runmax


Ŀ
 VCF_maxReIm              VCD_maxReIm              VCE_maxReIm              

Function        Find the largest real and imaginary parts occurring in a
                vector.
Syntax          #include <VFmath.h>
                fComplex   VCF_maxReIm( cfVector X, ui size );
Description     The vector X is separately searched for its largest real and
                imaginary parts.
Error handling  none
Return value    struct of type fComplex (dComplex,  eComplex,  resp.), in
                which the maxima of the real and imaginary parts of X are
                packed together.
See also        VCF_minReIm,  VCF_absmaxReIm,  VCF_absmax,  VCF_absmaxind


Ŀ
 VF_maxV                  VD_maxV                  VE_maxV                  
 VI_maxV             VSI_maxV            VLI_maxV            VQI_maxV       
 VU_maxV             VUS_maxV            VUL_maxV            VUI_maxV       

Function        Compare each element of a vector to the corresponding element
                of another vector and take the larger of the two.
Syntax          #include <VFmath.h>
                void VF_maxV( fVector Z, fVector X, fVector Y, ui size );
Description     Zi  =  Xi,    if  Xi  >   Yi
                Zi  =  Yi,    if  Xi  <=  Yi
Error handling  none
Return value    none
See also        VF_minV,   VF_maxC,  VF_max,   VF_absmax


Ŀ
 VF_mean                  VD_mean                  VE_mean                  
 VCF_mean                 VCD_mean                 VCE_mean                 
 VI_mean             VSI_mean            VLI_mean            VQI_mean       
 VU_mean             VUS_mean            VUL_mean            VUI_mean       

Function        Mean of a one-dimensional distribution
Syntax          #include <VFstd.h>
                float    VF_mean(  fVector  X, ui size );
                     (similarly VD_, VE_, VCF_, VCD_, VCE_)
                double   VI_mean( iVector X, ui size );
                     (similarly VSI_, VLI_, VU_, VUS_, VUL_, VUI_)
                extended VQI_mean( qiVector X, ui size );
Description     mean  = (1 / size) * sum( Xi )
                Integer versions: the mean of a distribution consisting of
                whole numbers generally is a fractional, i.e. a floating-
                point number. Therefore, the return value of the 16-bit
                and 32-bit integer versions is a double. For the 64-bit
                integer version VQI_mean, the return value is an extended.
Error handling  none
Return value    Mean of the vector elements
See also        VF_meanwW, VF_median, VF_meanvar, VF_varianceC, VF_linregress


Ŀ
 VF_meanvar               VD_meanvar               VE_meanvar               

Function        Mean and variance of a one-dimensional distribution
Syntax          #include <VFstd.h>
                float  VF_meanvar( float *Var,  fVector X, ui size );
Description     mean = (1 / size)     * sum( Xi )
                var  = (1 / (size-1)) * sum( (Xi - mean) )
                Note that the denominator in the definition of var is size-1,
                whereas, in the routine VF_varianceC, it is simply size.The
                reason for that difference is that here the mean is calculated
                first and then the variance is determined using this value,
                whereas in VF_varianceC, the parameter C is pre-set.
                The mean is returned and the variance stored at the address
                passed as Var.
Error handling  none
Return value    mean of the vector elements.
See also        VF_mean, VF_varianceC, VF_varianceV, VF_sum, VF_ssq,
                VF_ssqdevC, VF_linregress


Ŀ
 VF_meanvarwW             VD_meanvarwW             VE_meanvarwW             

Function        Mean and variance with weights
Syntax          #include <VFmath.h>
                float VF_meanvarwW( float *Var, fVector X, fVector Wt,
                                    ui size );
Description     mean =  (1 / sum( Wti )) * sum(  Xi * Wti )
                var  =  (1 / sum( Wti )) * sum(  Wti * (Xi - mean) )
                The weighted mean is returned and the variance stored at the
                address passed as Var.
Error handling  none
Return value    mean of the vector elements.
See also        VF_meanwW, VF_varianceCwW, VF_varianceVwW, VF_linregress


Ŀ
 VF_meanwW                VD_meanwW                VE_meanwW                
 VCF_meanwW               VCD_meanwW               VCE_meanwW               

Function        Mean with weights
Syntax          #include <VFstd.h>
                float VF_meanwW( fVector X,  fVector Wt, ui size );
                    (similarly  VD_,  VE_)
                fComplex VCF_meanwW( cfVector X, fVector Wt, ui size );
                    (similarly  VCD_,  VCE_)
Description     meanwW  =  (1 / sum( Wti )) *  sum( Xi * Wti )
                Notice that, also in the complex version, the weights are
                always real and not complex.
Error handling  none
Return value    weighted mean of the vector elements.
See also        VF_mean, VF_sum, VF_ssq, VF_ssqdevC, VF_median, VF_mean_varwW,
                VF_linregresswW


Ŀ
 VF_median                VD_median                VE_median                

Function        Median of a one-dimensional distribution
Syntax          #include <VFmath.h>
                float  VF_median( fVector X, ui size );
Description     The median of a distribution is defined as the value for which
                values above and below are equally probable, i.e., for which
                the number of elements greater and less than the median is
                equal. If the table X is ordered, the median is simply the
                element with the index (size+1)/2 (if size is odd) or the
                mean of the two central elements (if size is even).
                If a table is not ordered, VF_median finds its median by
                repeatedly scanning through it without actually sorting it.
Error handling  none
Return value    The median is returned.
See also        VF_mean,VF_meanwW, VF_sum


Ŀ
 VF_min                   VD_min                   VE_min                   
 VI_min              VSI_min             VLI_min             VQI_min        
 VU_min              VUS_min             VUL_min             VUI_min        

Function        Finds the smallest (or the most negative) element of a vector.
Syntax          #include <VFstd.h>
                float  VF_min( fVector X, ui size );
Description     The vector X is searched for its smallest (or most negative)
                element.
Error handling  none
Return value    Minimum value encountered.
See also        VF_absmin,  VF_runmin,  VF_minind


Ŀ
 VF_minC                  VD_minC                  VE_minC                  
 VI_minC             VSI_minC            VLI_minC            VQI_minC       
 VU_minC             VUS_minC            VUL_minC            VUI_minC       

Function        Compare each element of a vector to a constant and take the
                smaller of the two.
Syntax          #include <VFmath.h>
                void VF_minC( fVector Y, fVector X, ui size, float C );
Description     Yi  =  Xi,    if  Xi  <=  C
                Yi  =  C,     if  Xi  >   C
Error handling  none
Return value    none
See also        VF_minV,  VF_maxC, VF_min, VF_absmin, VF_limit, VF_flush0


Ŀ
 VF_minind                VD_minind                VE_minind                
 VI_minind           VSI_minind          VLI_minind          VQI_minind     
 VU_minind           VUS_minind          VUL_minind          VUI_minind     

Function        Find the smallest (or the most negative) element of a vector
                and its index.
Syntax          #include <VFstd.h>
                float  VF_minind( ui *Ind, fVector X, ui size );
Description     The vector X is searched for its smallest (or most negative)
                element; its value is returned. At the address passed as Ind,
                the index of this element is stored. In the case of several
                mimima of equal depth, the first one is chosen (i.e., the
                smallest of their indices is stored in Ind).
Error handling  none
Return value    minimum value encountered.
See also        VF_min, VF_minind, VF_absmin, VF_runmin


Ŀ
 VCF_minReIm              VCD_minReIm              VCE_minReIm              

Function        Find the smallest (or most negative) real and imaginary parts
                occurring in a vector.
Syntax          #include <VCFstd.h>
                fComplex  VCF_minReIm( cfVector X, ui size );
Description     The vector X is separately searched for its smallest real and
                imaginary parts.
Error handling  none
Return value    struct of type fComplex (dComplex,  eComplex,  resp.), in
                which the minima of the real and imaginary parts of X are
                packed together.
See also        VCF_maxReIm,  VCF_absminReIm,  VCF_absmin,  VCF_absminind


Ŀ
 VF_minV                  VD_minV                  VE_minV                  
 VI_minV             VSI_minV            VLI_minV            VQI_minV       
 VU_minV             VUS_minV            VUL_minV            VUI_minV       

Function        Compare each element of a vector to the corresponding element
                of another vector and take the smaller of the two.
Syntax          #include <VFmath.h>
                void VF_minV( fVector Z, fVector X, fVector Y, ui size );
Description     Zi  =  Xi,    if  Xi  <=  Yi
                Zi  =  Yi,    if  Xi  >   Yi
Error handling  none
Return value    none
See also        VF_maxV,   VF_minC,  VF_min,   VF_absmin


Ŀ
 VF_modC                  VD_modC                  VE_modC                  
 VI_modC             VSI_modC            VLI_modC            VQI_modC       
 VU_modC             VUS_modC            VUL_modC            VUI_modC       

Function        Modulus, i.e. the remainder of a division by a constant
Syntax          #include <VFmath.h>
                void VF_modC( fVector Y, fVector X, ui size, float C );
Description     Yi  =  Xi  mod  C
                Floating-point versions: a constant C = 0.0 leads to all Yi
                   being 0.0, independently of the Xi values (as in the
                   ANSI C math function fmod ).
                Integer versions:  a constant C = 0 leads to a ZERODIVIDE
                   error (as in the intrinsic "%" operation of ANSI C).
Error handling  none
Return value    none  (also the floating-point versions are treated as basic
                arithmetic rather than mathematical functions, despite their
                relation to the math function fmod).
See also        VF_modV,   VF_addC,  VF_mulC,  VF_divC,  VF_visC,  VF_redC


Ŀ
 VF_modf                  VD_modf                  VE_modf                  

Function        Split up into integer and fractional parts.
Syntax          #include <VFmath.h>
                int  VF_modf( fVector IntPart,  fVector FracPart,
                              fVector X, ui size );
Description     These functions are implemented as alias names for VF_intfrac
                etc., in order to maintain consistency with the ANSI C
                function name modf. For details, see VF_intfrac.


Ŀ
 VF_modV                  VD_modV                  VE_modV                  
 VFx_modV                 VDx_modV                 VEx_modV                 
 VI_modV             VSI_modV            VLI_modV            VQI_modV       
 VU_modV             VUS_modV            VUL_modV            VUI_modV       

Function        Modulus, i.e. the remainder of a division of corresponding
                vector elements
Syntax          #include <VFmath.h>
                void  VF_modV(  fVector Z, fVector X, fVector Y, ui size );
                void  VFx_modV( fVector Z, fVector X, fVector Y,
                                ui size, float A,  float  B );
Description     normal versions:    Zi  =  Xi  mod  Yi
                expanded versions:  Zi  =  (A * Xi + B)  mod Yi
                Floating-point versions: an argument Xi = 0.0 leads to Zi
                   being 0.0, independently of Yi (as in the ANSI C math
                   function fmod).
                Integer versions:  an argument Xi = 0 leads to a ZERODIVIDE
                   error (as in the intrinsic "%" operation of ANSI C).
Error handling  none
Return value    none  (also the floating-point versions are treated as basic
                arithmetic rather than mathematical functions, despite their
                relation to the math function fmod).
See also        VF_modC,  VF_addV,  VF_mulV,  VF_divV,  VF_visV,  VF_redV


Ŀ
 VF_mulC                  VD_mulC                  VE_mulC                  
 VCF_mulC                 VCD_mulC                 VCE_mulC                 
 VCF_mulReC               VCD_mulReC               VCE_mulReC               
 VI_mulC             VSI_mulC            VLI_mulC            VQI_mulC       
 VU_mulC             VUS_mulC            VUL_mulC            VUI_mulC       

Function        Multiply all vector elements by a constant
Syntax          #include <VFmath.h>
                void VF_mulC( fVector Y, fVector X, ui size, float C );
                    (similarly  VD_,  VE_, VI_,  etc.)
                void VCF_mulC(  cfVector Y, cfVector X, ui size, fComplex C );
                void VCF_mulReC( cfVector Y, cfVector X, ui size, float CRe );
                    (similarly  VCD_,  VCE_)
Description     Yi  =  C  *  Xi
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe by which the complex vector is multiplied.
Error handling  none
Return value    none
See also        VF_mulV,  VF_addC,   VF_divC,  VF_divrC,  VF_visC,  VF_redC


Ŀ
 VF_mulV                  VD_mulV                  VE_mulV                  
 VCF_mulV                 VCD_mulV                 VCE_mulV                 
 VCF_mulReV               VCD_mulReV               VCE_mulReV               
 VFs_mulV                 VDs_mulV                 VEs_mulV                 
 VFx_mulV                 VDx_mulV                 VEx_mulV                 
 VCFx_mulV                VCDx_mulV                VCEx_mulV                
 VCFx_mulReV              VCDx_mulReV              VCEx_mulReV              
 VI_mulV             VSI_mulV            VLI_mulV            VQI_mulV       
 VU_mulV             VUS_mulV            VUL_mulV            VUI_mulV       

Function        Multiply corresponding vector elements
Syntax          #include <VFmath.h>
                void  VF_mulV(  fVector Z, fVector X, fVector Y, ui size );
                void  VFs_mulV( fVector Z, fVector X, fVector Y, ui size,
                                float C );
                void  VFx_mulV( fVector Z, fVector X, fVector Y,
                                ui size, float A,  float  B );
                void  VCF_mulV( cfVector Z,  cfVector X,  cfVector Y,
                                ui size );
                void  VCF_mulReV( cfVector Z,  cfVector X, fVector Y,
                                  ui size );
                void  VCFx_mulV(  cfVector Z, cfVector X, cfVector Y,
                                  ui size, fComplex A,  fComplex B );
                void  VCFx_mulReV( cfVector Z, cfVector X, fVector Y,
                                   ui size, fComplex A, fComplex B );
Description     normal versions:    Zi  =  Xi  *  Yi
                scaled versions:    Zi  =  C * (Xi * Yi)
                expanded versions:  Zi  =  (A * Xi + B)  *  Yi
                The complex floating-point versions exist in two variants: in
                the first variant (e.g. VCF_mulV,  VCFx_mulV), X, Y, and Z are
                all complex; in the second variant, Y is real-valued
                (e.g. VCF_mulReV - "multiply by a real vector").
Error handling  none
Return value    none
See also        VF_mulC,  VF_addV,  VF_subV,  VF_divV,  VF_visV,  VF_redV


Ŀ
 VF_neg                   VD_neg                   VE_neg                   
 VCF_neg                  VCD_neg                  VCE_neg                  
 VI_neg              VSI_neg             VLI_neg             VQI_neg        

Function        Negation
Syntax          #include <VFmath.h>
                int  VF_neg( fVector Y,  fVector X,  ui size );
Description     Yi  =  - (Xi)
                VSI_,  VI_, and VLI_ versions only: the negation of the most
                negative number possible (-32768 for short, -2147483648 for
                long) is again the same - negative! - number. This is due to
                the implicit modulo-2**n arithmetics, where the overflowing
                short +32768 is stored as -32768, and the overflowing long
                +2147483648 is stored as -2147483648.
Error handling  none
Return value    By analogy with VF_abs,  the floating-point versions are
                treated as math functions. Therefore, they have a return
                value which, since no errors can occur, is always 0. The
                integer versions have no return value.
See also        VF_abs,  VCF_conj


Ŀ
 V_nfree                                                                    

Function        De-allocate memory occupied by one or more vectors.
Syntax          #include <VecLib.h>
                void  V_nfree(  unsigned numfree, ... );
Description     The parameter numfree "tells" the function how many vectors it
                has to free. These vectors follow in the parameter list after
                numfree. De-allocation of vectors not allocated by one of the
                functions of the VF_vector or VF_vector0 family is dis-
                couraged, especially in Windows programs.
                Note for Turbo Pascal users: since a variable number of
                parameters is not supported in Turbo Pascal, this
                function is missing in VectorLib for Turbo Pascal.
Example         V_nfree( 3, X, Y, Z );
Error handling  see V_free
Return value    none
See also        V_free,  VF_vector,  VF_vector0


Ŀ
 VF_noise                 VD_noise                 VE_noise                 

Function        Initialize a vector with "white" noise
Syntax          #include <VFstd.h>
                long VF_noise( fVector X, ui size, long seed, float Amp );
Description     White noise is generated with the amplitude Amp, i.e., the
                output values are between -Amp/2 and +Amp/2 (both extrema
                included). seed may be chosen completely arbitrary; successive
                calls with the same seed yield identical results, for
                different values of seed, the obtained results are
                uncorrelated.

                Internally, these functions employ a 32-bit integer random
                number generator by H.W.Lewis, with additional steps (so-
                called "Bays-Durham shuffle") to break sequential correla-
                tions. This ensures very good randomness, far superior
                to simpler generators (like the rand function shipped with
                Borland C++).

                A long value is returned which may be used as new seed for
                subsequent calls.
Error handling  none
Return value    last 32-bit random number internally generated; may be used as
                new seed value for future calls.
See also        rand, random, VF_random


Ŀ
 VCF_norm                 VCD_norm                 VCE_norm                 

Function        Norm (square of the magnitude) of cartesian complex numbers.
                Implemented as macros calling VF_CtoNorm, VD_CtoNorm,
                and VE_CtoNorm, resp.  See these functions for details.


Ŀ
 VI_not              VSI_not             VLI_not             VQI_not        
 VU_not              VUS_not             VUL_not             VUI_not        

Function        Bit-wise complement
Syntax          #include <VImath.h>
                void VI_not( iVector Y,  iVector X,  ui size );
Description     Yi  =  ~(Xi)
                Each single bit of the element Xi is inverted (i.e., it is 0
                in Yi, if it was 1 in Xi, and vice versa).
Error handling  none
Return value    none
See also        VI_and,  VI_or,  VI_neg


Ŀ
 V_noteError                                                                

Function        Construct and print an error message
Syntax          #include <VecLib.h>
                void  V_noteError( char *fname, unsigned why );
Description     In case of an error, the math functions of VectorLib invoke
                the following steps: First call _matherr (or _matherrl),
                then inspect the return value of _matherr (or _matherrl) and
                call V_noteError in case this return value was 0.
                V_noteError then constructs the appropriate error message and
                passes it to V_printErrorMsg, which is the function in charge
                of actually printing the error message.
                By default, the message is printed to the screen. The function
                V_setErrorEventFile may be used to change this default action
                and to redirect the output into an event file (exclusively or
                in addition to the screen message).
                fname is the name of the "complaining" function and  why
                specifies the reason for the complaint (as defined in <math.h>
                and described in connection with _matherr in the Borland C++
                documentation). How to call V_noteError from a user-defined
                _matherr function is described in chapter 5.3.  This function
                will not be included in versions of VectorLib for compilers
                that do already offer the possibility of printing error
                messages simultaneously to the screen and to an event file.
Return value    none
See also        V_setErrorEventFile,  V_printErrorMsg, _matherr


Ŀ
 VF_nread                 VD_nread                 VE_nread                 
 VCF_nread                VCD_nread                VCE_nread                
 VI_nread            VSI_nread           VLI_nread           VQI_nread      
 VU_nread            VUS_nread           VUL_nread           VUI_nread      

Function        Read the columns of a table from a stream
Syntax          #include <VFstd.h>
                VF_nread( unsigned n, ui size, FILE *stream, ... );
Description     n columns of a table are read into the vectors passed to
                VF_nread. The number of lines is specified as the number
                of elements of each vector, which is size.

                The entries of each line should be separated by spaces
                (' ') or tab characters ('\t').

                Each line must be terminated by a line-feed character ('\n').
                The length of the lines is limited according the following
                rules:
                - Either all lines have the same length. In this case, the
                  length is determined automatically and might in principle
                  be as large as 65535 characters.
                - Or the maximum length is given by the number n of vectors
                  to be read and by the data type:
                    VF_    24*n        VSI_,  VUS_   21*n
                    VD_    32*n        VLI_,  VUL_   37*n
                    VE_    40*n        VQI_          32*n
                    VCF_   48*n        VI_,   VU_    as VSI_, VUS_  (in the
                    VCD_   64*n                      memory model FLAT as
                    VCE_   80*n                      VLI_, VUL_)

                It is possible to read fewer vectors than there are columns
                in a table. In this case, the trailing columns are neglected.
                If, however, you try to read more vectors than there are
                columns, the result is undefined and might lead to an error.

                Complex versions:
                      Real und imaginary parts may (but need not) be enclosed
                      in braces { }. However, you must be consequent: Either
                      all or no element may be written with braces.

                Whole-number versions except VQI_nread:
                       By default, the numbers to be read are interpreted
                       as decimal numbers. You may use V_setRadix to define
                       any radix between 2 and 36.
Example         VF_nread( 3, 100, DataFile, X, Y, Z );
Error handling  Real, complex and quad versions:
                      Overflowing numbers are silently truncated to
                      HUGE_VAL.
                 Whole-number versions except VQI_nread:
                      As long as the numbers can be represented as long or
                      unsigned long, overflowing bits are ignored in the
                      16-bit versions.
                      Numbers beyond the long range yield -1 (signed types)
                      or +HUGE_VAL (unsigned types).
Return value    none
See also        VF_nwrite, VF_read, VF_store, VF_recall, strtod, strtol


Ŀ
 VF_nwrite                VD_nwrite                VE_nwrite                
 VCF_nwrite               VCD_nwrite               VCE_nwrite               
 VI_nwrite           VSI_nwrite          VLI_nwrite          VQI_nwrite     
 VU_nwrite           VUS_nwrite          VUL_nwrite          VUI_nwrite     

Function        Write vectors as the columns of a table into a stream.
Syntax          #include <VFstd.h>
                VF_nwrite( FILE *stream, unsigned n, ui size, ... );
Description     n vectors are written in ASCII format as the columns of a
                table into stream. The number of lines is given by the
                number of elements of each vector: size.

                The default format and separation may be changed using
                VF_setWriteFormat and VF_setNWriteSeparate, respectively.

Example         VF_nwrite( DataFile, 3, 100, X, Y, Z );
                     /* generates a table with 3 columns and 100 lines;
                        the columns are given by X, Y and Z.           */
Error handling  none
Return value    none
See also        VF_write, VF_nread, VF_store, VF_recall, fprintf


Ŀ
 VI_or               VSI_or              VLI_or              VQI_or         
 VU_or               VUS_or              VUL_or              VUI_or         

Function        Bit-wise "OR" operation
Syntax          #include <VImath.h>
                void VI_or( iVector Y,  iVector X,  ui size,  int C);
                void VUL_or( ulVector Y, ulVector X,  ui size,
                             unsigned long C );
Description     Yi  =  (Xi)  C
                The bit-wise "inclusive OR" operation is performed on each
                element Xi with the bit-mask given by C. A bit is 1 in Yi, if
                it was not simultaneously 0 in Xi and in C, i.e., if it was 1
                at least in one of them.
Error handling  none
Return value    none
See also        VI_not,  VI_and,  VI_xor


Ŀ
 VF_Parzen                VD_Parzen                VE_Parzen                

Function        "Parzen" window for spectral analyses
Syntax          #include <VFmath.h>
                void VF_Parzen( fVector X, ui size );
Description     Xi  = 1 - (i - 0.5*(size - 1)) / 0.5*(size + 1)
Error handling  none
Return value    none
See also        VF_Welch, VF_Hanning, VF_spectrum


Ŀ
 VCF_polar                VCD_polar                VCE_polar                

Function        Construct Cartesian complex numbers from polar coordinates
                Implemented as a macro that calls VF_PolartoC, VD_PolartoC,
                VE_PolartoC, resp.  See these functions for details.


Ŀ
 VF_PolartoC              VD_PolartoC              VE_PolartoC              

Function        Construct Cartesian complex numbers from polar coordinates
Syntax          #include <VFmath.h>
                void VF_PolartoC( cfVector X,  fVector Mag,
                                  fVector Arg, ui size );
Description     The polar coordinates Mag (magnitude, absolute value) and
                Arg (argument, angle) of each element are used to construct
                the Cartesian complex vector X.
Error handling  The total loss of precision for very large values of Arg is
                treated tacitly (without an error message); if it occurs,
                the result is set to {Magi, 0}.
Return value    none
See also        VF_CtoPolar, VF_ReImtoC, VF_CtoAbs, VF_CtoArg, VF_CtoNorm


Ŀ
 VF_poly                  VD_poly                  VE_poly                  
 VFx_poly                 VDx_poly                 VEx_poly                 

Function        Polynomial
Syntax          #include <VFmath.h>
                int  VF_poly( fVector  Y,  fVector  X, ui size,
                              fVector Coeff,  unsigned deg );
                int  VFx_poly(  fVector  Y,  fVector  X, ui size,
                                fVector Coeff,  unsigned deg,
                                float A, float B );
Description     normal versions:
                       Yi  =  c0 + c1 * Xi + c2 * Xi + ... + cn * Xi**n
                expanded versions:
                       xi  =  (A*Xi + B),
                       Yi  =  c0 + c1 * xi + c2 * xi + ... + cn * xi**n
                A polynomial of degree deg is generated for every element of
                X, using the coefficients contained in the vector Coeff.
                The coefficients in Coeff have to be ordered in such a way
                that the constant term is the zeroth element, the linear
                coefficient the first element etc., up to the deg'th  element
                which is the coefficient for the highest power used in the
                polynomial. (Beware a frequent source of errors: for a
                polynomial of deg = 4, there are 5 (!) coefficients; do not
                forget the constant term).
Error handling  OVERFLOW errors lead to HUGE_VAL as the default result. In
                contrast to the ANSI C function poly (where deg is declared
                as int), the declaration of deg as unsigned precludes DOMAIN
                errors (which would occur for negative deg).
Return value    0, if no error occurred, otherwise non-zero
See also        VF_ipow,  VF_pow,  poly


Ŀ
 VF_polyinterpol          VD_polyinterpol          VE_polyinterpol          

Function        Polynomial interpolation of X-Y-table values
Syntax          #include <VFstd.h>
                void VF_polyinterpol(
                      fVector Y,    fVector X,    ui sizex,
                      fVector XTab, fVector YTab, ui sizetab,
                      unsigned deg );
Description     For each of the sizex elements of X, the corresponding element
                of Y is interpolated from the XTab-YTab value pairs. XTab must
                be ordered (either ascending or descending). All values of
                XTab must be distinct; otherwise a division by zero may occur
                and lead to a program abort. For each element of X, the
                routine finds itself the appropriate place in the table. The
                parameter deg denotes the number of points that will be taken
                into account for the interpolation (this is not the degree of
                the interpolating polynomial!). Any value between 0 and 2 will
                be interpreted as meaning linear interpolation. A maximum of
                10-point interpolation is possible.
Error handling  Trying to use too many elements for the interpolation
                (deg > 10) leads to an error message "Not possible with more
                than 10 elements" and to a program abort. If deg exceeds
                sizetab, an error message "Invalid parameter(s)" is displayed
                and the program aborted.
                No other errors are detected (you have to take care yourself
                that the XTab values are distinct and that the YTab values
                are not near the limit of overflowing).
Return value    none
See also        VF_ratinterpol, VF_splineinterpol


Ŀ
 VF_pow                   VD_pow                   VE_pow                   
 VCF_pow                  VCD_pow                  VCE_pow                  
 VFx_pow                  VDx_pow                  VEx_pow                  
 VCFx_pow                 VCDx_pow                 VCEx_pow                 
 VCF_powReExpo            VCD_powReExpo            VCE_powReExpo            
 VCFx_powReExpo           VCDx_powReExpo           VCEx_powReExpo           

Function        Raise each element of a vector to a specified power
Syntax          #include <VFmath.h>
                int  VF_pow( fVector Y, fVector X, ui size, float Expo );
                int  VFx_pow(  fVector Y, fVector X, ui size, float Expo,
                               float A, float B, float C );
                int  VCF_pow(  cfVector Y, cfVector X, ui size,
                               fComplex Expo );
                int  VCFx_pow( cfVector Y,  cfVector X, ui size,
                               fComplex Expo,
                               fComplex A, fComplex B, fComplex C );
                int  VCF_powReExpo(  cfVector Y, cfVector X, ui size,
                               float Expo );
                int  VCFx_powReExpo( cfVector Y,  cfVector X, ui size,
                               float Expo,
                               fComplex A, fComplex B, fComplex C );
Description     normal versions:     Yi  =  Xi ** Expo
                expanded versions:   Yi  =  C *  ((A*Xi+B) ** Expo)
                If Expo is a moderately small integer number, the functions of
                this family pass the job to the appropriate routine of the
                VF_ipow family. More efficiently, the user could do just that
                himself.
                The complex version exists in two variants: one for complex
                exponents, the other for complex numbers raised to a real
                exponent.
Error handling  DOMAIN errors occur, if negative numbers are raised to
                fractional powers; the default result is NAN ("not-a-number").
                SING errors occur, if zero is raised to a negative power; the
                default result is HUGE_VAL, which is true for OVERFLOW errors
                as well.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_ipow,  VF_poly,  VF_pow2,  VF_exp,  pow


Ŀ
 VF_pow10                 VD_pow10                 VE_pow10                 
 VFx_pow10                VDx_pow10                VEx_pow10                

Function        Real powers of 10
Syntax          #include <VFmath.h>
                int  VF_pow10(  fVector Y, fVector  X, ui size );
                int  VFx_pow10( fVector Y, fVector X, ui size,
                                float A, float B, float C );
Description     normal versions:    Yi  =  10.0 ** Xi
                expanded versions:  Yi  =  C * 10.0 ** (A*Xi+B)
                This is an exponential function to the basis of 10.0.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_ipow10,  VF_scale10,  VF_log10,  VF_pow,  VF_exp,  pow


Ŀ
 VF_pow2                  VD_pow2                  VE_pow2                  
 VFx_pow2                 VDx_pow2                 VEx_pow2                 

Function        Real powers of 2
Syntax          #include <VFmath.h>
                int  VF_pow2(  fVector Y, fVector X, ui size );
                int  VFx_pow2( fVector Y, fVector X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  2.0 ** Xi
                expanded versions:  Yi  =  C * 2.0 ** (A*Xi+B)
                This is an exponential function to the basis of 2.0.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_ipow2,  VF_scale2,  VF_log2,  VF_pow,  VF_exp,  pow


Ŀ
 VF_print                 VD_print                 VE_print                 
 VCF_print                VCD_print                VCE_print                
 VI_print            VSI_print           VLI_print           VQI_print      
 VU_print            VUS_print           VUL_print           VUI_print      

Function        Print a vector as ASCII numbers to stdout, assuming a
                linewidth of 80 characters.
Syntax          #include <VFstd.h>
                VF_print( fVector X, ui size,  unsigned nperline );
Description     size elements of X are printed to stdout,  nperline in each
                line. The available linewidth is assumed to be 80 characters.
                Each line begins with the index of the first element printed
                into that line. The index is followed by a colon and by
                the requested nperline elements.
                Complex numbers are printed in braces, with the real and
                imaginary parts separated by a komma:   {Re, Im}.

                In contrast to VF_cprint, no paging is performed.
                The number of digits per element is determined by the
                available space, which depends in turn on nperline.

                This family of functions is available under Windows only in
                connection with EasyWin, and should not be used within
                TurboVision programs.
Error handling  If nperline exceeds the maximum number of entries possible
                within 80 characters, an error message "Cannot use requested
                format (too many entries per line)" is generated; in this
                case, the program chooses the maximum number nperline
                possible.
Return value    none
See also        printf, VF_cprint, VF_fprint, VF_write, VF_store


Ŀ
 V_printErrorMsg                                                            

Function        Print an error message.
Syntax          #include <VecLib.h>
                void  V_printErrorMsg( char *ErrMsg );
Description     As described in connection with V_noteError, this function is
                in charge of printing error messages. By default, output is
                directed to the screen. The function V_setErrorEventFile may
                be used to redirect the output into an event file (exclusively
                or in addition to the screen message). V_printErrorMsg may be
                called from user-defined routines in which error conditions
                are detected. If the message is longer than one line, carriage
                returns ("\n" or "\r\n") have to be included at the desired
                place. Note, however, that this function will not be included
                in versions of VectorLib for compilers that do already offer
                the possibility of printing error messages simultaneously to
                the screen and to an event file.
Return value    none
See also        V_setErrorEventFile,  V_noteError, _matherr


Ŀ
 VF_prod                  VD_prod                  VE_prod                  
 VCF_prod                 VCD_prod                 VCE_prod                 

Function        Calculates the product of all the elements of a vector.
Syntax          #include <VFstd.h>
                float   VF_prod( fVector X, ui size );
Description     The product of all elements of a vector is calculated.
Error handling  none (but be careful: this function may easily overflow!)
Return value    the product of the vector elements
See also        VF_runprod, VF_sum


Ŀ
 VF_quartic               VD_quartic               VE_quartic               
 VCF_quartic              VCD_quartic              VCE_quartic              
 VFx_quartic              VDx_quartic              VEx_quartic              
 VCFx_quartic             VCDx_quartic             VCEx_quartic             

Function        Fourth power
Syntax          #include <VFmath.h>
                int  VF_quartic(  fVector  Y,  fVector  X, ui size );
                int  VFx_quartic( fVector Y,  fVector  X, ui size,
                                  float A, float B );
Description     normal versions:    Yi  =  Xi ** 4
                expanded versions:  Yi  =  (A*Xi+B) ** 4
                The fourth power of the elements of X is stored in Y.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_square,  VF_cubic,  VF_sqrt,  VF_pow,  VF_ipow,  VF_poly


Ŀ
 VF_ramp                  VD_ramp                  VE_ramp                  
 VCF_ramp                 VCD_ramp                 VCE_ramp                 
 VI_ramp             VSI_ramp            VLI_ramp            VQI_ramp       
 VU_ramp             VUS_ramp            VUL_ramp            VUI_ramp       

Function        Initialize a vector with an ascending or descending "ramp".
Syntax          #include <VFstd.h>
                void VF_ramp(   fVector X, ui size,
                                float Start, float Rise );
                    (similarly  VD_,  VE_,  VCF_, VCD_, VCE_, VI_,  etc.)
                void VU_ramp(   uVector  X, ui size,
                                unsigned Start, int Rise );
                    (similarly  VUS_,  VUL_)
Description     Xi  =  Start + i * Rise
                For the floating-point versions, remember the limited accuracy
                of floating-point numbers. For example, after calling
                    VF_ramp( F1, 101, -1.0, 0.01 );
                the element F1[100] will not be 0.0, as you might wish, but
                rather something like 2.2E-8. Ths is due to the fact that
                the number 0.01 (passed as a float to the function) is not
                exactly representable in the data type float. If that is a
                problem, consider building the ramp with moderately large
                integers and dividing by a scaling factor afterwards:
                     VF_ramp( F1, 101, -100.0, 1.0 );
                     VF_divC( F1, F1, 101, 100.0 );
                Note that Rise is defined as int instead of unsigned in the
                VU_ version and as long instead of unsigned long in the VUL_
                version; this exception from the general rules - that all
                parameters in one function be of the same data type - allows
                to create descending ramps of unsigned numbers, which
                would not be possible otherwise.
Error handling  floating-point versions: none;
                integer versions:  see chapter 5.2.
Return value    none
See also        VF_Parzen, VF_Welch, VF_equ1, VF_random


Ŀ
 VF_random                VD_random                VE_random                
 VI_random           VSI_random          VLI_random          VQI_random     
 VU_random           VUS_random          VUL_random          VUI_random     

Function        High-quality random numbers
Syntax          #include <VFstd.h>
                long  VF_random( fVector X, ui siz, long seed,
                                 float MinVal, float MaxVal );
Description     The X vector is filled with a sequence of random numbers.
                Within the ranges defined by MinVal and MaxVal, and within the
                restrictions of floating-point representation, all numbers are
                equally probable (including the extreme values themselves),
                i.e., so-called "uniform deviates" are produced. The parameter
                seed may be any number. Successive calls to one and the same
                of these functions will yield identical sequences, if seed is
                chosen equal; if seed is chosen differently for successive
                calls, the results will be uncorrelated.

                Internally, these functions employ a 32-bit integer random
                number generator by H.W.Lewis, with additional steps (so-
                called "Bays-Durham shuffle") to break sequential
                correlations. This ensures very good randomness, far superior
                to simpler generators (like the rand function shipped with
                Borland C++).

                A long value is returned which may be used as new seed for
                subsequent calls.
Error handling  none
Return value    last 32-bit random number generated; this may be used as a new
                seed value for future calls.
See also        rand, srand, random, VF_noise


Ŀ
 VF_ratinterpol           VD_ratinterpol           VE_ratinterpol           

Function        Diagonal-rational interpolation
Syntax          #include <VFmath.h>
                void  VF_ratinterpol(
                                fVector Y, fVector X, ui sizex,
                                fVector XTab, fVector YTab, ui sizetab,
                                unsigned deg );
Description     For each of the sizex elements of X, the corresponding element
                of Y is interpolated from the XTab-YTab value pairs. XTab must
                be ordered (either ascending or descending). All values of
                XTab must be distinct; otherwise a division by zero may occur
                and lead to a program abort. The parameter deg denotes the
                number of points that will be taken into account for the
                interpolation; the diagonal rational interpolation scheme by
                Stoer and Bulirsch is used. The interpolating function is
                formed by the quotient of two polynomials, the polynomial in
                the denominator being of the same order (for even deg) or of
                an order higher by one (for odd deg) than the polynomial of
                the numerator.
                Diagonal rational interpolation is superior to polynomial
                interpolation, especially in the presence of poles. It is,
                however, much slower.
                deg must be between 3 and 20.
Error handling  A pole (infinity) in the interpolated function is recognized
                and leads to a SING error with the proposed result being
                HUGE_VAL. (Note: the x-value passed to _matherr is the first
                element of XTab). Trying to use too many elements for the
                interpolation (deg > 20) leads to an error message "Not
                possible with more than 20 elements" and to a program abort.
                If deg is not between 3 and 20, or exceeds sizetab, an error
                message "Invalid parameter(s)" is displayed and the program
                aborted.
Return value    none
See also        VF_polyinterpol, VF_splineinterpol


Ŀ
 VF_read                  VD_read                  VE_read                  
 VCF_read                 VCD_read                 VCE_read                 
 VI_read             VSI_read            VLI_read            VQI_read       
 VU_read             VUS_read            VUL_read            VUI_read       

Function        reads a vector in ASCII format from a stream
Syntax          #include <VFstd.h>
                VF_read( fVector X, ui size, FILE *stream );
Description     size elements are read in ASCII format (up to 80 characters)
                from stream and stored in X. Normally, this function will be
                used to import vectors from a program which cannot store
                numbers in machine format. It can also be used to retrieve
                vectors previously stored by VF_write. For storing and
                retrieving intermediate results, however, the function pair
                VF_store / VF_recall  is to be preferred over  VF_write /
                VF_read  (see VF_write).

                The entries to be read must be separated by whitespace
                (' ', '\n', or '\t'). Additionally, one (!) "non-whitespace"
                character is tolerated after each entry, if it follows
                directly after the last digit. After it, there must be one
                or more whitespace characters.

                Complex versions:
                      Real und imaginary parts may (but need not) be enclosed
                      in braces { }. However, you must be consequent: Either
                      all or no element may be written with braces.

                Whole-number versions except VQI_nread:
                       By default, the numbers to be read are interpreted
                       as decimal numbers. You may use V_setRadix to define
                       any radix between 2 and 36.
Error handling  Real, complex and quad versions:
                      Overflowing numbers are silently truncated to
                      HUGE_VAL.
                 Whole-number versions except VQI_read:
                      As long as the numbers can be represented as long or
                      unsigned long, overflowing bits are ignored in the
                      16-bit versions.
                      Numbers beyond the long range yield -1 (signed types)
                      or +HUGE_VAL (unsigned types).
Return value    none
See also        VF_nread, VF_write, VF_store, VF_recall, strtod, strtol


Ŀ
 VCF_real                 VCD_real                 VCE_real                 

Function        Extracts the real part from a complex vector. Implemented as
                macros calling VF_CtoRe, VD_CtoRe, or VE_CtoRe, resp.
                See these functions for details.


Ŀ
 VF_recall                VD_recall                VE_recall                
 VCF_recall               VCD_recall               VCE_recall               
 VI_recall           VSI_recall          VLI_recall          VQI_recall     
 VU_recall           VUS_recall          VUL_recall          VUI_recall     

Function        Read a vector in binary format from a stream
Syntax          #include <VFstd.h>
                VF_recall( fVector X, ui size, FILE *stream );
Description     size elements of X are read from stream in binary format.
                Normally, these functions are used to retrieve data stored by
                the respective function of the VF_store family.
Error handling  none
Return value    none
See also        fwrite,  fread,  VF_store, VF_write, VF_print


Ŀ
 VF_redC                  VD_redC                  VE_redC                  

Function        "Reduce"  by a constant
Syntax          #include <VFmath.h>
                void VF_redC( fVector Y, fVector X, ui size, float C );
Description     Yi  =   red( Xi, C )  =  Xi * C / (Xi + C)
                Expressions of this type are frequently used in physics; for
                example, the "reduced mass" of a two-body system is the
                product of both masses divided by their sum.
Error handling  none
Return value    none
See also        VF_redV,  VF_addC,  VF_subC,  VF_divC,  VF_visC


Ŀ
 VF_redV                  VD_redV                  VE_redV                  
 VFx_redV                 VDx_redV                 VEx_redV                 

Function        "Reduce" by corresponding vector elements
Syntax          #include <VFmath.h>
                void  VF_redV(  fVector  Z,  fVector  X,  fVector  Y,
                                ui size );
                void  VFx_redV( fVector  Z,  fVector  X,  fVector  Y,
                                ui size, float  A,  float  B );
Description     normal versions:      Zi =  red( Xi, Yi )
                                         =  Xi * Yi / (Xi + Yi)
                expanded versions:    xi =  (A * Xi + B),
                                      Zi =  red( xi, Yi )
Error handling  none
Return value    none
See also        VF_redC,  VF_addV,  VF_subV,  VF_divV,  VF_visV


Ŀ
 VF_reflect               VD_reflect               VE_reflect               
 VCF_reflect              VCD_reflect              VCE_reflect              

Function        Derive the second half of a vector from the first half by
                reflection at the midpoint.
Syntax          #include <VFstd.h>
                void  VF_reflect( fVector X, ui size );
Description     X[size-i-1] =  X[i],   i=0,...,(size-1)/2
                The elements of the lower half of a vector are copied in
                reverse order into the upper half, i.e., the zeroth element is
                copied to the last, the element number 1 to the second last,
                and so on. The elements of the first half are not affected by
                this operation. This function will be used, e.g., to construct
                a response function for convolutions (see VF_convolve). In
                this case, note that the zeroth element is to appear only once
                in the response function and must not be included in the
                reflection by VF_reflect. Therefore, you have to calculate
                the response function for size/2+1 elements and to apply
                reflection from element 1 on. For an example, see VF_convolve.
Error handling  none
Return value    none
See also        VF_rotate, VF_rev, VF_convolve, VF_deconvolve, VF_filter


Ŀ
 VF_ReImtoC               VD_ReImtoC               VE_ReImtoC               

Function        Construct a complex vector from real and imaginary parts
Syntax          #include <VCFstd.h>
                void VF_ReImtoC( cfVector Y, fVector Re, fVector Im,
                                 ui size );
Description     The complex vector Y is constructed from two real vectors that
                become the real and imaginary parts of Y.
Error handling  none
Return value    none
See also        VF_CtoReIm, VF_RetoC, VF_PolartoC


Ŀ
 VF_RetoC                 VD_RetoC                 VE_RetoC                 

Function        Overwrite the real part of a complex vector with a real vector
Syntax          #include <VCFstd.h>
                void VF_RetoC( cfVector Y, fVector Re, ui size );
Description     The real part of the complex vector Y is overwritten with the
                elements of the real-valued vector Re. The imaginary part of Y
                is not affected.
Error handling  none
Return value    none
See also        VF_CtoReIm, VF_ReImtoC,  VF_ImtoC, VF_PolartoC


Ŀ
 VF_rev                   VD_rev                   VE_rev                   
 VCF_rev                  VCD_rev                  VCE_rev                  
 VI_rev              VSI_rev             VLI_rev             VQI_rev        
 VU_rev              VUS_rev             VUL_rev             VUI_rev        

Function        Reverse the ordering of the elements of a vector
Syntax          #include <VFstd.h>
                void  VF_rev( fVector Y, fVector X, ui size );
Description     Y[i] = X[size-i-1]
Error handling  none
Return value    none
See also        VF_reflect, VF_rotate


Ŀ
 VF_rms                   VD_rms                   VE_rms                   

Function        Root of the mean square
Syntax          #include <VFstd.h>
                float VF_rms( fVector X, ui size );
Description     rms = sqrt( (1/size) * sum( Xi ) )
Error handling  none
Return value    rms
See also        VF_ssq, VF_Euclid, VF_mean


Ŀ
 VF_rotate                VD_rotate                VE_rotate                
 VCF_rotate               VCD_rotate               VCE_rotate               
 VI_rotate           VSI_rotate          VLI_rotate          VQI_rotate     
 VU_rotate           VUS_rotate          VUL_rotate          VUI_rotate     

Function        Rotate the ordering of the elements of a vector
Syntax          #include <VFstd.h>
                void  VF_rotate(  fVector Y, fVector X, ui size,  int  pos );
Description     Y[i]  = X[size-pos+i],   i=0,..,pos-1
                Y[i]  = X[i-pos],        i=pos,..,size-1
                The output vector equals the rotated input vector. Clockwise
                rotation is achieved by a positive number pos.
Error handling  none
Return value    none
See also        VF_reflect, VF_rev


Ŀ
 VF_round                 VD_round                 VE_round                 
 VF_roundtoI              VD_roundtoI              VE_roundtoI              
 VF_roundtoSI             VD_roundtoSI             VE_roundtoSI             
 VF_roundtoLI             VD_roundtoLI             VE_roundtoLI             
 VF_roundtoQI             VD_roundtoQI             VE_roundtoQI             
 VF_roundtoU              VD_roundtoU              VE_roundtoU              
 VF_roundtoUS             VD_roundtoUS             VE_roundtoUS             
 VF_roundtoUL             VD_roundtoUL             VE_roundtoUL             
 VF_roundtoUI             VD_roundtoUI             VE_roundtoUI             

Function        Rounding to the nearest whole number.
Syntax          #include <VFmath.h>
                int VF_round(     fVector Y,  fVector X,  ui size );
                int VF_roundtoI(  iVector Y,  fVector X,  ui size );
                int VF_roundtoLI( liVector Y, fVector X, ui size );
                   (similarly  all other functions of this family)
Description     Each element of X is rounded to the nearest integer value. In
                case of a fractional part of exactly 0.5, the nearest even
                integer value is chosen and stored in Y. For example, 2.5 is
                rounded to 2, and 3.5 is rounded to 4.
                The functions VF_roundtoI, VF_roundtoLI, VF_roundtoU, etc.
                convert the result into the various integer data types.
Error handling  OVERFLOW errors are handled by setting the result to the
                extreme value possible. Negative numbers in the versions
                VF_roundtoU, VF_roundtoUS, VF_roundtoUL, and VF_roundtoUI
                lead to DOMAIN errors; they are handled by setting the result
                to 0.
Return value    Returns 0, if no error occurred, otherwise non-zero.
See also        round,  floor, VF_round,  VF_floor, VF_chop, VF_trunc


Ŀ
 VF_runintegralC          VD_runintegralC          VE_runintegralC          

Function        "running integral" of an array sampled at equally-spaced
                abscissa points.
Syntax          #include <VFstd.h>
                void  VF_runintegralC(  fVector  Y,  fVector  X,
                                        ui size,  float DeltaT );
Description     The vector X is assumed to be a function of a variable t; the
                t values themselves are equally spaced. Therefore, only their
                spacing, DeltaT, must be known to the function. Each element
                of Y is the integral of all elements of X up to and including
                the one with the same index. Thus, the last element of Y
                contains the value of the integral over the whole of X (the
                area under X). If only this value is of interest, VF_integralC
                should be used.
Error handling  none
Return value    none
See also        VF_runintegralV,  VF_integralC,  VF_derivC,  VF_runsum


Ŀ
 VF_runintegralV          VD_runintegralV          VE_runintegralV          

Function        "running integral"
Syntax          #include <VFmath.h>
                void  VF_runintegralV(  fVector Z,  fVector  X,
                                        fVector  Y,  ui size );
Description     Y is a function of the variable x which is represented by X.
                Each element of Z is the integral over all elements of Y up to
                and including the one with the same index. The first element
                of Z is always 0.0.  The last element of Z is equal to the
                value of the integral, i.e. to the area under Y. If only this
                value of the integral is of interest, VF_integralV should be
                used.
Error handling  none
Return value    none
See also        VF_runintegralC,  VF_integralV,  VF_derivV


Ŀ
 VF_runmax                VD_runmax                VE_runmax                
 VI_runmax           VSI_runmax          VLI_runmax          VQI_runmax     
 VU_runmax           VUS_runmax          VUL_runmax          VUI_runmax     

Function        "running" maximum.
Syntax          #include <VFstd.h>
                void  VF_runmax( fVector Y, fVector X, ui size );
Description     Each element of Y is the maximum of the corresponding and all
                preceding elements of X.
Error handling  none
Return value    none
See also        VF_max, VF_runmin, VF_runsum


Ŀ
 VF_runmin                VD_runmin                VE_runmin                
 VI_runmin           VSI_runmin          VLI_runmin          VQI_runmin     
 VU_runmin           VUS_runmin          VUL_runmin          VUI_runmin     

Function        "running" minimum
Syntax          #include <VFstd.h>
                void  VF_runmin( fVector Y, fVector X, ui size );
Description     Each element of Y is the minimum of the corresponding and all
                preceding elements of X.
Error handling  none
Return value    none
See also        VF_min, VF_runmax, VF_runsum


Ŀ
 VF_runprod               VD_runprod               VE_runprod               
 VCF_runprod              VCD_runprod              VCE_runprod              

Function        "running" product
Syntax          #include <VFstd.h>
                void  VF_runprod( fVector Y, fVector X, ui size );
Description     Each element of Y is the product of the corresponding and all
                preceding elements of X. This function should be used with
                care: overflow is easily reached, and underflow may lead to
                all elements from a certain position on being zero.
Error handling  none
Return value    none
See also        VF_prod, VF_runsum


Ŀ
 VF_runsum                VD_runsum                VE_runsum                
 VCF_runsum               VCD_runsum               VCE_runsum               
 VI_runsum           VSI_runsum          VLI_runsum          VQI_runsum     
 VU_runsum           VUS_runsum          VUL_runsum          VUI_runsum     

Function        "running" sum
Syntax          #include <VFstd.h>
                void  VF_runsum( fVector Y, fVector X, ui size );
Description     Each element of Y is the sum of the corresponding and all
                preceding elements of X.
Error handling  none (but be careful: this function may easily overflow!)
Return value    none
See also        VF_sum, VF_runprod


Ŀ
 VF_scale10               VD_scale10               VE_scale10               

Function        Scaling by an integer power of 10.
Syntax          #include <VFmath.h>
                int  VF_scale10( fVector Y,  fVector X,  ui size, int expo );
Description     Yi  =  Xi * (10 ** expo)
                Notice that higher powers of ten are not representable as
                exact numbers, which may lead to the introduction of round-off
                error by the scaling. If this is a problem, VF_scale2  should
                be used instead.
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_scale2,  VF_mantexp,  ldexp


Ŀ
 VF_scale2                VD_scale2                VE_scale2                

Function        Scaling by an integer power of  2.
Syntax          #include <VFmath.h>
                int VF_scale2( fVector Y, fVector X, ui size, int expo );
Description     Yi  =  Xi  *  (2 ** expo)
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_scale10,  VF_mantexp,  ldexp


Ŀ
 VF_scalprod              VD_scalprod              VE_scalprod              

Function        Scalar product of two vectors
Syntax          #include <VFstd.h>
                float VF_scalprod( fVector X, fVector Y, ui size );
Description     scalprod  =  sum( Xi * Yi )
                The scalar (or dot) product of two vectors is defined as the
                sum of the products of the corresponding elements. The scalar
                product of a vector with itself is the square of its magnitude
                and may be calculated using the function VF_ssq.
Error handling  none
Return value	scalar product
See also        VF_prod,  VF_xprod, VF_sum, VF_ssq


Ŀ
 VF_searchC               VD_searchC               VE_searchC               

Function        Binary searches of an ordered table for the entry coming
                closest to a specified value
Syntax          #include <VFstd.h>
                ui VF_searchC( fVector X, ui size, float C, int mode );
Description     In a binary search, the element of X is located that is
                closest to the value specified as C. X has to be an ordered
                table (either ascending or descending); if this condition is
                not fulfilled, the result will be wrong. If C is outside the
                range covered by X, the first or the last element of X is
                chosen, whichever is closer to C. If C is within the range of
                the table, three modes of the search are available:
                mode =  +1:  find the next element greater than or equal to C
                mode =   0:  find the element closest to C; if two elements
                             are within equal distance, choose the lower index
                mode =  -1:  find the next element less than or equal to C
Error handling  none
Return value    index of the element found.
See also        VF_searchV,  VF_sort, VF_polyinterpol


Ŀ
 VF_searchV               VD_searchV               VE_searchV               

Function        Binary search of an ordered table for the entries coming
                closest to the values specified as the elements of a vector
Syntax          #include <VFstd.h>
                void VF_searchV( uiVector Ind, fVector X, ui sizex,
                                 fVector Tab, ui sizetab, int mode );
Description     For each element of X, the element of the ordered table Tab is
                located that is closest to it. If Xi is outside the range of
                the table, the first or the last element of the table is
                chosen, whichever is appropriate. Otherwise, three modes of
                the search are available:
                mode =  +1:  find the next element greater than or equal to Xi
                mode =   0:  find the element closest to Xi; if two elements
                             are within equal distance, choose the lower index
                mode =  -1:  find the next element less than or equal to Xi

                sizex is the number of elements of X and of Ind, whereas
                sizetab denotes the number of elements of the table Tab.
Error handling  none
Return value    none
See also        VF_searchC, VF_indpick, VF_sortind, VF_polyinterpol


Ŀ
 VF_sec                   VD_sec                   VE_sec                   
 VFx_sec                  VDx_sec                  VEx_sec                  

Function        Secant function
Syntax          #include <VFmath.h>
                int  VF_sec(  fVector  Y,  fVector  X, ui size );
                int  VFx_sec( fVector  Y,  fVector  X, ui size,
                              float A,  float B,  float C );
Description     normal versions:    Yi  =  sec( Xi )
                                        =  1 / cos( Xi )
                expanded versions:  Yi  =  C * sec( A*Xi+B )
                The secant is defined as the inverse of the cosine (not to be
                mistaken for the arcus function arccos). For large values of
                Xi, round-off error becomes appreciable; if the Xi values are
                representable as rational multiples of Pi, it is better to use
                VF_secrpi  than VF_sec.
Error handling  SING or OVERFLOW errors lead to the default result HUGE_VAL.
                TLOSS precision errors lead to a result of 1.0 (as if the
                input were 0.0).
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sec2,  VF_secrpi,  VF_cos,  VF_sech,  cos


Ŀ
 VF_sec2                  VD_sec2                  VE_sec2                  
 VFx_sec2                 VDx_sec2                 VEx_sec2                 

Function        Square of the secant function
Syntax          #include <VFmath.h>
                int  VF_sec2(   fVector  Y,  fVector  X, ui size );
                int  VFx_sec2(  fVector  Y,  fVector  X, ui size,
                                float A,  float B,  float C );
Description     normal versions:     Yi = sec( Xi )
                expanded versions:   Yi = C * sec( A*Xi+B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  For SING and OVERFLOW errors, the default result is HUGE_VAL
                (multiplied by the sign of C in the expanded versions);
                TLOSS errors lead to a default result of 1.0 or C, resp. (as
                if the input were 0.0).
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sec,   VF_secrpi,   sin


Ŀ
 VF_sech                  VD_sech                  VE_sech                  
 VFx_sech                 VDx_sech                 VEx_sech                 

Function        Hyperbolic secant function
Syntax          #include <VFmath.h>
                int  VF_sech(   fVector  Y,  fVector  X, ui size );
                int  VFx_sech(  fVector  Y,  fVector  X, ui size,
                                float A, float B, float C );
Description     normal versions:     Yi  =  sech( Xi )
                                         =  2 / (exp( Xi ) + exp( -Xi ))
                expanded versions:   Yi  =  C * sech( A*Xi+B )
Error handling  These functions should be error-proof.
Return value    always 0
See also        VF_sinh,  VF_sech2, VF_exp,   sinh


Ŀ
 VF_sech2                 VD_sech2                 VE_sech2                 
 VFx_sech2                VDx_sech2                VEx_sech2                

Function        Square of the hyperbolic secant function
Syntax          #include <VFmath.h>
                int  VF_sech2(   fVector  Y,  fVector  X, ui size );
                int  VFx_sech2(  fVector  Y,  fVector  X, ui size,
                                 float A, float B, float C );
Description     normal versions:      Yi =  sech( Xi )
                expanded versions:    Yi =  C * sech( A*Xi+B )
                The sech function is used in physics, e.g., to describe the
                shape of ultrashort light pulses. Compared to a Gaussian or
                Lorentzian pulse shape of the same autocorrelation width (see
                VF_autocorr), the sech function has the smallest FWHM (full
                width to half maximum).
Error handling  These functions should be error-proof.
Return value    always 0
See also        VF_sech,  VF_sinh, VF_exp,   VF_Gauss,  VF_Lorentz


Ŀ
 VF_secrpi                VD_secrpi                VE_secrpi                
 VF_secrpi2               VD_secrpi2               VE_secrpi2               
 VF_secrpi3               VD_secrpi3               VE_secrpi3               

Function        Secant function of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int  VF_secrpi(  fVector Y, iVector P, ui size, int q );
                int  VF_secrpi2( fVector Y, iVector P, ui size, int q );
                int  VF_secrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  sec( (P[i] / q) * Pi )
                The secant of fractional multiples of Pi is calculated. There
                are three versions: VF_secrpi is for general use with any
                arbitrary denominator q. If q is a power of 2,  VF_secrpi2
                should be used which is a highly optimized version utilizing a
                look-up table. If q is a multiple of 3,  VF_secrpi3 should be
                used. VF_secrpi2 and VF_secrpi3 work also with q values they
                are not optimized for; in this case, however, memory space is
                wasted for the tables.
Error handling  SING errors occur if P[i] / q  is an odd multiple of ; the
                default result is 0.0 (which is the mean of +HUGE_VAL and
                -HUGE_VAL; similarly to VF_cosecrpi2, 0.0 is chosen irrespec-
                tive to the fact that it is not a valid result of the secant
                function!);
                q must be non-zero; this is, however, not tested for.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sec,   cos


Ŀ
 V_setErrorEventFile                                                        

Function        Prepare a file for printing error messages into it
Syntax          #include <VecLib.h>
                void  V_setErrorEventFile(
                                char *filename,
                                unsigned ScreenAndFile );
Description     This function determines where to print messages notifying
                math errors that occur within VectorLib routines. filename is
                the desired name of the event file (often called "log-file").
                ScreenAndFile decides if you wish to have error messages
                printed simultaneously into the file and onto the screen
                (ScreenAndFile > 0)  or exclusively into the file
                (ScreenAndFile = 0).
                If a user-defined _matherr function calls V_noteError,
                also errors occurring outside VectorLib routines will lead to
                a message printed into the event file (see Chapter 5.5). This
                function will not be included in versions of VectorLib for
                compilers which offer the possibility of printing error
                messages simultaneously to the screen and into an event file.

                The default, i.e., printing error messages to the screen, is
                restored by V_closeErrorEventFile.
Error handling  If the desired event file cannot be opened or created, the
                program is aborted with a message "Cannot open error event
                file".
Return value    none
See also        V_noteError,  V_closeErrorEventFile,  _matherr


Ŀ
 V_setLineThickness                                                         

Function        Modify the line thickness used in plotting functions
Syntax          #include <Vgraph.h>
                void V_setLineThickness( unsigned linethickness );
Description     The line thickness used in the plotting functions
                VF_xyAutoPlot, VCF_autoPlot, etc., is set to linethickness.
                To reset the default value, call V_setLineThickness with
                linethickness = 1.
                DOS:
                   There are only two possible values for linethickness:
                   NORM_WIDTH=1 and THICK_WIDTH=3. Any value of linethickness
                   below 3 is interpreted as NORM_WIDTH, any value above 3 is
                   taken as THICK_WIDTH.
                Windows:
                   Any value of linethickness between 1 and 500 is allowed,
                   useful values ranging from 1 to about 10. A minimum thick-
                   ness of one pixel is always secured, even if linethickness
                   is set to 0. Note that broken or dotted lines are plotted
                   accurately only with a linethicknes of 1. At higher values
                   of linethickness, all lines will look like solid lines.
                   Thicker lines are plotted considerably slower than thinner
                   ones.
Error handling  DOS: "silent" correction of the input value.
                Windows: A value of linethickness greater than 500 leads to a
                warning message "Cannot use line thicker than 500 pixels."
                Program execution is continued with linethickness set to 500.
Return value    none
See also        VF_xyAutoPlot, V_setSymbolSize


Ŀ
 VF_setNWriteSeparate     VD_setNWriteSeparate     VE_setNWriteSeparate     
 VCF_setNWriteSeparate    VCD_setNWriteSeparate    VCE_setNWriteSeparate    
 VI_setNWriteSeparate     VSI_setNWriteSeparate                             
 VLI_setNWriteSeparate    VQI_setNWriteSeparate                             
 VU_setNWriteSeparate     VUS_setNWriteSeparate                             
 VUL_setNWriteSeparate    VUI_setNWriteSeparate                             

Function        Definition of the string to be used by the V.._nwrite
                functions to separate table entries.
Syntax          #include <VFstd.h>
                void VF_setNWriteSeparate( char *SepString );
Description     This function defines the character string to be inserted
                between the columns of a table written by VF_nwrite.
                VF_setNWriteSeparate does not influence the end of each
                line which is always a line-feed character ("\n").
                SepString may contain up to twelve characters. The default
                setting is a tab character (#9).
Error handling  In the case of SepString longer than twelve characters,
                the program is aborted with the error message
                "Invalid Parameter(s)".
                The contents of SepString is not checked.
Return value    none
See also        VF_setWriteFormat, VF_setWriteSeparate, VF_nwrite, VF_nread


Ŀ
 V_setPlotRegion                                                            

Function        Defines a screen or printer-page region to be used by
                VectorLib plotting operations.
Syntax          #include <Vgraph.h>
                void V_setPlotRegion( int left, int top,
                                      int right, int bottom );
Description     The rectangular region defined by the parameters, passed to
                V_setPlotRegion, will hold the coordinate system including
                all labels generated by future calls to VectorLib plotting
                functions such as VF_xyAutoPlot. The parameters left, top,
                right, and bottom are in pixels, counting from the upper
                left corner of the screen or of the printer page.
                V_setPlotRegion has to be called after (!) V_initPlot
                or V_initPrint.
Error handling  none
Return value    none
See also        V_initPlot, V_initPrint


Ŀ
 V_setRadix                                                                 

Function        Define the radix for the whole-number read functions
Syntax          #include <VIstd.h>
                          /* or <VSIstd.h>, <VLIstd.h>, <VUstd.h>, ... */
                void V_setRadix( int radix );
Description     By default, the V.._read functions for the whole-number data
                types interpret all numbers as decimal numbers. V_setRadix
                allows to change this default behaviour.
                The radix set by V_setRadix will be used in VI_read, VI_nread
                and their VSI_, VLI_, VUS_, VU_, VUL_, and VUL_ analogues.
                It does, however, not affect VQI_read or VQI_nread (where the
                radix is always 10).

                radix may take on values between 2 and 36 or 0.
                In the case of radix=0, the basis of each number is determined
                at run-time:
                All numbers beginning with the ciphers 1-9 are recognized
                as decimal numbers.
                All numbers beginning with "0x" are interpreted as
                hexadecimal and all numbers beginning with "0" without "x"
                are read as octal numbers.
Error handling  radix < 0, radix=1, or radix > 36 lead to a program abort
                with the error message "Invalid Parameter(s)".
Return value    none
See also        VI_read, VI_nread, strtol, strtoul


Ŀ
 VF_setRspEdit            VD_setRspEdit            VE_setRspEdit            

Function        Modify the treatment of round-off errors in VF_convolve
                and  VF_deconvolve
Syntax          #include <VFstd.h>
                void  VF_setRspEdit( fComplex Trunc );
Description     In the functions VF_convolve and VF_deconvolve, a frequency
                filter is calculated by Fourier-transforming a given response
                function. The filter is then applied to a vector. Due to
                accumulated round-off, filter elements that should be zero
                may be not so, but contain small non-zero numbers.

                The maximum round-off error in the construction of Flt
                accumulates roughly to (size * big * prec), where big is the
                largest element of Flt and prec the relative floating-point
                precision. Any element smaller than that should be regarded as
                zero. In order to determine the exact threshold for the real
                and imaginary parts separately, the function uses the real
                and imaginary parts of Trunc, substituting them for prec in
                the above expression. Normally, you would choose
                Trunc.Re = Trunc.Im,  although a stricter (i.e. larger)
                value for Trunc.Im is also reasonable.

                By default, Trunc.Re = 16*EPSILON and Trunc.Im = 32*EPSILON,
                where EPSILON is FLT_EPSILON, DBL_EPSILON, or LDBL_EPSILON
                (these constants are defined in <float.h>), depending on
                the data type.

                In order to switch the editing of the filter completely off,
                choose Trunc.Re = Trunc.Im = 0.

                During convolutions, the editing of the filter leads to
                slightly smoother results. During deconvolutions, the
                editing has also another meaning: for all "lost" frequencies
                (i.e., those for which the Fourier transform of the response
                function contains only numbers near zero), the filter is set
                to 0 instead of the inverse of these small numbers. Thereby,
                possible OVERFLOW and SING errors are avoided.

                To read the currently set threshold, call VF_getRspEdit.
Error handling  none
Return value    none
See also        VF_convolve,  VF_deconvolve, VF_getRspEdit


Ŀ
 V_setSymbolSize                                                            

Function        Modify the size of the symbols used in plotting functions
Syntax          #include <Vgraph.h>
                void V_setSymbolSize( float symsiz );
Description     The size of the symbols used in the plotting functions
                VF_xyAutoPlot, VCF_autoPlot, etc., is modified by scaling with
                symsiz. To reset the symbol size to the default value, call
                V_setSymbolSize with symsiz=1.0. Note that it is not possible
                to make the symbols completely vanish (e.g., by setting
                symsiz = 0.0), since a minimum radius of one pixel is always
                secured. Useful values of symsiz range from about 0.5 to 5.0.
                Values above 50.0 are prohibited.

                When magnifying the symbols, you should also consider modifying
                the thickness of the connecting lines, if you are using any.
                See V_setLineThickness.

                Notice: An automatic scaling is always performed in order to
                maintain a constant relation between the symbol size and the
                overall size of the coordinate grid (which is especially
                important for Windows applications). The factor symsiz of this
                function scales the symbol size with respect to the
                automatically-found value. The automatic scaling cannot be
                switched off.
Error handling  DOS: "silent" correction of the input value.
                Windows: A value of symsiz greater than 50.0 leads to a
                warning message "Cannot scale symbols by more than a factor
                of 50.0". Program execution is continued with symsiz set
                to 50.0.
Return value    none
See also        VF_xyAutoPlot, V_setLineThickness


Ŀ
 VF_setWriteFormat        VD_setWriteFormat        VE_setWriteFormat        
 VCF_setWriteFormat       VCD_setWriteFormat       VCE_setWriteFormat       
 VI_setWriteFormat        VSI_setWriteFormat                                
 VLI_setWriteFormat       VQI_setWriteFormat                                
 VU_setWriteFormat        VUS_setWriteFormat                                
 VUL_setWriteFormat       VUI_setWriteFormat                                

Function        Definition of the format to be used by V.._write and
                V.._nwrite
Syntax          #include <VFstd.h>
                void VF_setWriteFormat( char *FormatString );
Description     The functions of the VF_write and VF_nwrite families employ
                internally the ANSI C function fprintf in order to print
                numbers into a stream.
                According to the rules described in the documentation of
                Borland C++ for printf, the format may be specified as fits
                your needs. When defining a write format, one should always
                be aware of the restrictions imposed by the read functions
                (not all formats you can write will be read correcly, see
                VF_read).

                VF_setWriteFormat should not be used for the definition of
                whitespace before or after the numbers. This is the task
                of VF_setWriteSeparate.

                For details about the formats used for each of the various
                data types, please refer to the following table. The last
                column of this table gives the maximum length of the format
                string.

    Version      Standard Format        Alternative Example  max.length 
   Ĵ
    VF_                   "% 11.8e"                 "% 8.4f"      16    
    VD_                 "% 19.16le"               "% 16.8lf"      16    
    VE_                 "% 22.19Le"              "% 22.19LG"      16    
    VCF_         "% 11.8e, % 11.8e"       "{% 8.4f, % 8.4f}"      32    
    VCD_     "% 19.16le, % 19.16le"  "{% 19.16lE % 19.16lE}"      32    
    VCE_     "% 22.19Le, % 22.19Le"  "{% 22.19Lg % 22.19Lg}"      32    
    VI_                      "% 5d"                 "0x% 4x"      12    
    VSI_                    "% 5hd"                "0x% 4hX"      12    
    VLI_                   "% 10ld"                 "%08lXh"      12    
    VQI_                 "% 20.0Lf"                               16    
    VU_                      "% 5u"                  "%04xh"      12    
    VUS_                    "% 5hu"                 "0%04ho"      12    
    VUL_                   "% 10lu"                 "0%08lO"      12    
   

                The data type quad is converted into extended before
                being passed to fprintf (which, at present, does not
                support quads). This explains why the format string in
                the VQI_ version tells fprintf to expect a long double.

                In the memory model FLAT of the registered version of
                VectorLib, the VI_ variant gets the standard format "% 10d"
                and the VU_ variant gets the standard format "% 10u".
Error handling  Format strings longer than the maximum length specified
                in the above table lead to a program abort with the error
                message "Invalid Parameter(s)".
                The contents of the format string is not checked. So you
                have to be very careful to specify a format which is valid
                for the respective data type.
Return value    none
See also        VF_setWriteSeparate, VF_write, VF_nwrite, VF_read, VF_nread


Ŀ
 VF_setWriteSeparate      VD_setWriteSeparate      VE_setWriteSeparate      
 VCF_setWriteSeparate     VCD_setWriteSeparate     VCE_setWriteSeparate     
 VI_setWriteSeparate      VSI_setWriteSeparate                              
 VLI_setWriteSeparate     VQI_setWriteSeparate                              
 VU_setWriteSeparate      VUS_setWriteSeparate                              
 VUL_setWriteSeparate     VUI_setWriteSeparate                              

Function        Definition of the separation string used by V.._write
Syntax          #include <VFstd.h>
                void VF_setWriteSeparate( char *SepString );
Description     By default, VF_write puts a line feed character after each
                vector element written into a stream. This means that each
                element gets its own line. You may use VF_setWriteSeparate
                to define another separation string. This may be, for
                example, a tab character ("\t") or a series of spaces
                (e.g., "    ").
                If you use VF_write with the output sent directly to the
                printer (stream = stdprn), you probably have to explicitly
                use a carriage return character in addition to the line
                feed. To do this, call
                      VF_setWriteSeparate( "\n\r" );

                VF_write will insert the separation string only in between
                the vector elements. At the end, after the last element,
                there is always a line feed ("\n") instead of the separation
                string.

                SepString may contain up to twelve characters.
Error handling  In the case of SepString longer than twelve characters,
                the program is aborted with the error message
                "Invalid Parameter(s)".
                The contents of SepString is not checked.
Return value    none
See also        VF_setWriteFormat, VF_setNWriteSeparate, VF_write, VF_read


Ŀ
 VF_sgn                   VD_sgn                   VE_sgn                   

Function        Signum function, compares each element of a vector with 0.
Syntax          #include <VFmath.h>
                void VF_sgn( fVector Y, fVector X, ui size );
Description     Each element of X is compared with 0 and the result of the
                comparison stored in Y:
                   Yi  =  +1.0,    if  Xi > 0
                   Yi  =   0.0,    if  Xi = 0
                   Yi  =  -1.0,    if  Xi < 0.
                This function is implemented as a macro that calls VF_cmp0.
Error handling  none
Return value    none
See also        VF_cmp_..., VF_cmpC, VF_cmpV


Ŀ
 VI_shl              VSI_shl             VLI_shl             VQI_shl        
 VU_shl              VUS_shl             VUL_shl             VUI_shl        

Function        "Shift to the left", i.e. multiply by integer powers of 2.
Syntax          #include <VImath.h>
                void VI_shl(  iVector Y, iVector X, ui size, unsigned C );
                void VUL_shl( ulVector Y, ulVector X, ui size, unsigned C );
                    (similarly all other functions of this family)
Description     Yi  =  Xi  <<  C
                All bits of Xi are shifted to the left by as many positions as
                indicated in the parameter C. This corresponds to a
                multiplication by 2**C, neglecting possible overflow (in all
                versions) and loss of the sign bit (for signed numbers, i.e.
                in the VI_, VSI_, VLI_, and VQI_ versions). Note that by
                shifting 16-bit numbers (VSI_, VUS_ versions) by more than 15
                positions, any non-zero bit present in the original number is
                lost and the result is 0. Similarly, 32-bit numbers (VLI_,
                VUL_ versions) yield 0 upon shifting by more than 31
                positions.  C is always of the data type unsigned. Shifting by
                negative numbers C is, therefore, not possible. To perform a
                right-shift, the appropriate function of the VI_shr family
                has to be used.
Error handling  none
Return value    none
See also        VI_mul,  VI_shr


Ŀ
 VI_shr              VSI_shr             VLI_shr             VQI_shr        
 VU_shr              VUS_shr             VUL_shr             VUI_shr        

Function        "Shift to the right", i.e., divide by integer powers of 2.
Syntax          #include <VImath.h>
                void VI_shr(  iVector  Y, iVector  X,  ui size,	unsigned C );
                void VUL_shr( ulVector Y, ulVector X,  ui size, unsigned C );
                   (similarly all other functions of this family)
Description     Yi  =  Xi  >>  C
                All bits of Xi are shifted to the right by as many positions
                as indicated in the parameter C. This corresponds to an
                integer division by 2**C. The sign of Yi is always the same as
                of Xi. In contrast to explicit integer divisions, the result
                is always rounded toward minus infinity:  -15 / 2 = -7,  but
                -15 >> 1 = -8. Note that by shifting 16-bit numbers (VSI_,
                VUS_ versions) by more than 15 positions, any unsigned or
                positive number yields 0, whereas any negative number (in the
                VSI_ version) yields -1 in this case. The same is true for 32-
                bit numbers (VLI_, VUL_ versions) upon shifting by more than
                31 positions. C is always of the data type unsigned. Shifting
                by negative numbers C is, therefore, not possible. To perform
                a left-shift, the appropriate function of the VI_shl family
                has to be used.
Error handling  none
Return value    none
See also        VI_div,  VI_shl


Ŀ
 VF_sin                   VD_sin                   VE_sin                   
 VCF_sin                  VCD_sin                  VCE_sin                  
 VFx_sin                  VDx_sin                  VEx_sin                  
 VCFx_sin                 VCDx_sin                 VCEx_sin                 

Function        Sine function
Syntax          #include <VFmath.h>
                int  VF_sin(  fVector  Y,  fVector  X, ui size );
                int  VFx_sin( fVector  Y,  fVector  X, ui size,
                              float A, float B, float C );
Description     normal versions:    Yi =  sin( Xi )
                expanded versions:  Yi =  C *  sin( A*Xi+B )
                For large values of Xi, round-off error becomes appreciable;
                if the Xi values are representable as fractional multiples of
                Pi, it is better to use VF_sinrpi  than VF_sin.
Error handling  Precision errors lead to a default result of 0.0 and a non-
                zero return value, but are ignored otherwise; _matherr is
                not called.
                OVERFLOW errors can only occur in the complex versions and
                lead to a result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_sin2,  VF_sinrpi,  VF_cos,  VF_sinh,  VF_asin,  sin


Ŀ
 VF_sin2                  VD_sin2                  VE_sin2                  
 VFx_sin2                 VDx_sin2                 VEx_sin2                 

Function        Square of the sine function
Syntax          #include <VFmath.h>
                int  VF_sin2(  fVector  Y,  fVector  X, ui size );
                int  VFx_sin2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  sin( Xi )
                expanded versions:  Yi  =  C *  sin( A*Xi+B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  Precision errors lead to a default result of 0.0 and a non-
                zero return value, but are otherwise ignored; _matherr is not
                called.
                OVERFLOW errors can only occur in the complex versions and
                lead to a result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sin,   VF_sinrpi,   sin


Ŀ
 VF_sinc                  VD_sinc                  VE_sinc                  
 VFx_sinc                 VDx_sinc                 VEx_sinc                 

Function        Sinc function
Syntax          #include <VFmath.h>
                int  VF_sinc(  fVector  Y,  fVector  X, ui size );
                int  VFx_sinc( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi =  sinc( Xi )  =  sin( Xi ) / Xi
                expanded versions:  Yi = C * sinc( A*Xi+B )
                The sinc function for an argument of 0.0 is defined as 1.0.
                The sinc function is the Fourier transform of a square pulse
                and is used, for example, to describe the diffraction pattern
                of a slit.
Error handling  These functions should be error-proof.
Return value    always 0.
See also        VF_sin,   VF_sinrpi,   sin


Ŀ
 VF_sincos                VD_sincos                VE_sincos                
 VFx_sincos               VDx_sincos               VEx_sincos               

Function        Sine and Cosine simultaneously
Syntax          #include <VFmath.h>
                int  VF_sincos( fVector  YSin,  fVector YCos,
                                fVector  X, ui size );
                int  VFx_sincos( fVector  YSin,  fVector YCos,
                                 fVector  X, ui size,
                                 float A, float B, float C );
Description     normal versions:   YSin[i]  =  sin( Xi )
                                   YCos[i]  =  cos( Xi )
                expanded versions: YSin[i]  =  C *  sin( A*Xi+B )
                                   YCos[i]  =  C *  cos( A*Xi+B )
                The sine and the cosine are calculated simultaneously, which
                is far more efficient than calculating them separately if both
                of them are needed. For large values of Xi, round-off error
                becomes appreciable; if the Xi values are representable as
                fractional multiples of Pi, it is better to use VF_sincosrpi
                than VF_sincos.
Error handling  Precision errors lead to a result of 0.0 for the sine and 1.0
                for the cosine (as if the input were 0.0) along with a non-
                zero return value, but are otherwise ignored; _matherr is not
                called. Other errors should not occur.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sincos2,  VF_sincosrpi,  sin,  cos


Ŀ
 VF_sincos2               VD_sincos2               VE_sincos2               
 VFx_sincos2              VDx_sincos2              VEx_sinco2               

Function        Square of the sine and of the cosine simultaneously
Syntax          #include <VFmath.h>
                int  VF_sincos2(  fVector YSin2, fVector YCos2,
                                  fVector  X, ui size );
                int  VFx_sincos2( fVector YSin2, fVector YCos2,
                                  fVector  X, ui size,
                                  float A, float B, float C );
Description     normal versions:    YSin2[i]  =  sin( Xi )
                                    YCos2[i]  =  cos( Xi )
                expanded versions:  YSin2[i]  =  C * sin( A*Xi+B )
                                    YCos2[i]  =  C * cos( A*Xi+B )
                The squared sine and the squared cosine are calculated
                simultaneously, which is far more efficient than calculating
                them separately, if both of them are needed.
Error handling  Precision errors lead to a result of 0.0 for the sin and of
                1.0 for the cos (as if the input were 0.0) along with a non-
                zero return value, but are otherwise ignored; _matherr is not
                called. Other errors should not occur.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_sincos,   sin,  cos


Ŀ
 VF_sincosrpi             VD_sincosrpi             VE_sincosrpi             
 VF_sincosrpi2            VD_sincosrpi2            VE_sincosrpi2            
 VF_sincosrpi3            VD_sincosrpi3            VE_sincosrpi3            

Function        Sine and cosine of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int  VF_sincosrpi(   fVector  YSin,  fVector YCos,
                                     iVector  P, ui size,  int q );
                int  VF_sincosrpi2(  fVector  YSin,  fVector YCos,
                                     iVector  P, ui size,  int q );
                int  VF_sincosrpi3(  fVector  YSin,  fVector YCos,
                                     iVector  P, ui size,  int q );
Description     YSin[i]  =  sin( (P[i] / q) * Pi )
                YCos[i]  =  cos( (P[i] / q) * Pi )
                The sine and the cosine of fractional multiples of Pi are
                calculated. There are three versions: VF_sincosrpi is for
                general use with any arbitrary denominator q. If q is a power
                of 2,  VF_sincosrpi2 should be used which is a highly
                optimized version reading the results from a table named
                VF_sintab2, if possible. If q is a multiple of 3,
                VF_sincosrpi3 should be used which utilizes a table named
                VF_sintab3. The use of VF_sincosrpi3 is a convenient way to
                use degrees instead of radians; if, for example, q is 180,
                then the unit of the elements of P is "degree". VF_sincosrpi2
                and VF_sincosrpi3 work also with q values they are not
                optimized for; in this case, however, memory space is wasted
                for the (then useless) tables.
Error handling  These functions should be error-proof, as long as q!=0.
Return value    always 0
See also        VF_sincos,    sin, cos


Ŀ
 VF_sinh                  VD_sinh                  VE_sinh                  
 VCF_sinh                 VCD_sinh                 VCE_sinh                 
 VFx_sinh                 VDx_sinh                 VEx_sinh                 
 VCFx_sinh                VCDx_sinh                VCEx_sinh                

Function        Hyperbolic sine function
Syntax          #include <VFmath.h>
                int  VF_sinh(  fVector  Y,  fVector  X, ui size );
                int  VFx_sinh( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:      Yi  =  sinh( Xi )
                expanded versions:    Yi  =  C * sinh ( A*Xi+B )
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_cosh,  VF_exp,   sinh


Ŀ
 VF_sinrpi                VD_sinrpi                VE_sinrpi                
 VF_sinrpi2               VD_sinrpi2               VE_sinrpi2               
 VF_sinrpi3               VD_sinrpi3               VE_sinrpi3               

Function        Sine function of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int  VF_sinrpi(  fVector Y, iVector P, ui size, int q );
                int  VF_sinrpi2( fVector Y, iVector P, ui size, int q );
                int  VF_sinrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  sin( (P[i] / q) * Pi )
                The sine of fractional multiples of Pi is calculated. There
                are three versions: VF_sinrpi is for general use with any
                arbitrary denominator q. If q is a power of 2,  VF_sinrpi2
                should be used which is a highly optimized version reading
                the results from a look-up table, if possible. If q is a
                multiple of 3,  VF_sinrpi3 should be used.  VF_sinrpi3 offers
                a convenient way to use degrees instead of radians; if, for
                example, q is 180, then the unit of the elements of P is
                "degree".  VF_sinrpi2 and VF_sinrpi3 work also with q values
                they are not optimized for; in this case, however, memory
                space is wasted for the tables.
Error handling  These functions should be error-proof, as long as q!=0.
Return value    always 0
See also        VF_sin,    sin


Ŀ
 VF_sintab2               VD_sintab2               VE_sintab2               
 VF_sintab3               VD_sintab3               VE_sintab3               

                Table of sine values for arguments between 0 and Pi/2
Syntax          #include <xmath.h>
                extern float     VF_sintab2[ VF_tabsz2+1 ];
                extern double    VD_sintab2[ VD_tabsz2+1 ];
                extern extended  VE_sintab2[ VE_tabsz2+1 ];
                extern float     VF_sintab3[ VF_tabsz3+1 ];
                extern double    VD_sintab3[ VD_tabsz3+1 ];
                extern extended  VE_sintab3[ VE_tabsz3+1 ];
Description     VF_sintab2[ i ]  =  sin( i/(2*VF_tabsz2) * Pi ),
                                                      i=0,...,VF_tabsz2
                VF_sintab3[ i ]  =  sin( i/(2*VF_tabsz3) * Pi ),
                                                      i=0,...,VF_tabsz3
                These look-up tables of sine values for arguments between 0
                and Pi/2 are used by VF_sinrpi2 and the other functions of
                that family and are also available for other purposes.
                The symbols VF_tabsz2 etc., denoting the size of the tables,
                are defined in <xmath.h>.
See also        VF_sinrpi2,  VF_tantab2,  VF_cosectab2


Ŀ
 VF_sort                  VD_sort                  VE_sort                  
 VI_sort             VSI_sort            VLI_sort            VQI_sort       
 VU_sort             VUS_sort            VUL_sort            VUI_sort       

Function        Sorting into ascending or descending order
Syntax          #include <VFstd.h>
                void  VF_sort( fVector Y, fVector X, ui size, int dir );
Description     The vector is sorted in ascending order, if dir is positive;
                negative dir yields descending order. The present
                implementation uses the "Heapsort" algorithm.
Error handling  none
Return value    none
See also        VF_sortind,  VF_rotate, VF_rev,  qsort


Ŀ
 VF_sortind               VD_sortind               VE_sortind               
 VI_sortind          VSI_sortind         VLI_sortind         VQI_sortind    
 VU_sortind          VUS_sortind         VUL_sortind         VUI_sortind    

Function        Sort the index-array of a vector
Syntax          #include <VFstd.h>
                void VF_sortind( uiVector Ind,  fVector X, ui size, int dir );
Description     The routine is similar to VF_sort, but this time it is the
                index-array of X rather than the vector X itself that is
                ordered. Ascending order is obtained by setting dir to any
                positive number. Here, ascending order means that Ind[0] will
                contain the index of the smallest element of X, Ind[1] the
                index of the second-smallest, and so on, up to Ind[size-1],
                the index of the largest element in X. Descending order is
                obtained by setting dir negative. This routine is used if
                other vectors are correlated with X and the correlation of the
                individual elements has to be maintained. After sorting the
                index-array, use VF_indpick (VD_indpick, VI_indpick, etc.) to
                actually perform the sorting of X and the other vectors
                correlated with X.
Error handling  none
Return value    none
See also        VF_sort, VF_indpick


Ŀ
 VF_spectrum              VD_spectrum              VE_spectrum              

Function        Power-density spectrum
Syntax          #include <VFstd.h>
                float VF_spectrum(  fVector Spc,  ui specsiz,
                                    fVector X,  ui xsiz, fVector Win );
Description     The data set X is analyzed for its power spectral density
                (PSD), i.e. the mean square amplitude. The result is stored
                in Spc.  xsiz must be at least 2*specsiz, and specsiz has to
                be an integer power of 2.   Internally, X is divided into
                xsiz*specsiz/2 segments and the average over the spectra of
                the individual segments is calculated. Each segment of length
                2*specsiz yields the PSD for specsiz+1 frequencies (see
                VF_FFT). In order to keep specsiz an integer power of 2, there
                are only specsiz points stored in Spc and the last one, the
                PSD at the Nyquist frequency, is given as the return value
                of the function and may either be neglected (by calling the
                function like a void function) or stored as the last element
                in Spc by calling the function as
                   Spc[specsiz] = VF_spectrum( Spc, specsiz, X, xsiz, Win );
                in this case, Spc must have a length of specsiz+1.

                Win is a window that is applied to the data segments. The size
                of the Win vector must be 2*specsiz. Within the VectorLib
                library, three functions are available that give suitable
                Windows: VF_Welch, VF_Parzen, and VF_Hanning. A square window
                (i.e. no windowing at all) is achieved by setting all elements
                of Win to 1.0 using VF_equ1. Use of the square window is not
                recommended here, though.

                You may wish to test the quality of the calculated spectrum by
                applying the Wiener-Khinchin theorem (provided you called
                VF_spectrum as in the above example and stored the PSD for the
                Nyquist frequency):
                1.0/xsize * VF_ssq( X, xsize ) must be about equal to
                VF_sum( Spc, specsiz+1 ).
                If the deviation between both results is large, the sampling
                interval in X probably is too large.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Example (for DOS):
                #include <VFstd.h>
                #include <VFmath.h>
                #include <Vgraph.h>
                #include <math.h>
                #include <conio.h>
                void main( void )
                {
                    fVector  X,   Spc,  Win,  Time,   Freq;
                    ui       xsize=1024,  specsiz=128;
                    X    = VF_vector( xsize );
                    Spc  = VF_vector( specsiz+1 );
                    Win  = VF_vector( 2*specsiz );
                    Time = VF_vector( xsize );
                    Freq = VF_vector( specsiz+1);

                    VF_ramp( Time, xsize, 0.0, 200 * M_PI / xsize );
                    VF_ramp( Freq, specsiz+1,  0.0, (xsize / (200*M_PI)) /
                             specsiz );
                       /* get a Time axis from 0 to 200 Pi and a corresponding
                          frequency axis from 0 to the Nyquist frequency */
                    VF_sin( X, Time, xsize );    /* 100 periods of a sine */
                    VF_cmpC( X, X, xsize, 0.5 );
                                  /* convert into asymmetric square wave */
                    VF_Welch( Win, 2*specsiz );   /* or another window */
                    Spc[specsiz] = VF_spectrum( Spc, specsiz, X, xsize, Win );
                    V_initGraph( "\\BorlandC\\BGI\\" );
                                       /* give the correct BGI path! */
                    VF_xyAutoPlot( Freq, Spc, specsiz+1,
                                   PS_SOLID | SY_CROSS, GREEN );
                    getch();   /* hit any key when you have seen enough */
                    closegraph();
                    V_nfree( 5, Freq, Time, Win, Spc, X );
                }
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_spectrum
                is based) complains "Size must be an integer power of 2"
                and the program is aborted.
Return value    PSD at the Nyquist frequency
See also        VF_FFT, VF_convolve, VF_autocorr, VF_xcorr, VF_filter


Ŀ
 VF_splinederiv2          VD_splinederiv2          VE_splinederiv2          

Function        Generate a second-derivative table from an X-Y-table to be
                used for cubic-spline interpolation.
Syntax          #include <VFstd.h>
                void  VF_splinederiv2(
                                fVector Y2,
                                fVector XTab, fVector YTab, ui size,
                                int specify,  float Yp0, float Ypn );
Description     A table of second derivatives of YTab is generated to be used
                for cubic-spline interpolation with VF_splineinterpol. In
                order to get a unique solution, two additional conditions have
                to be specified. Setting specify to 0 yields the "natural
                cubic spline" with Y2 being set to zero at both end-points; in
                this case, Yp0 and Ypn have no influence. Setting specify to 1
                yields Y2 calculated in such a way that the first(!)
                derivative at the zeroth and at the last position equals Yp0
                and Ypn, resp.
Error handling  none
Return value    none
See also        VF_splineinterpol


Ŀ
 VF_splineinterpol        VD_splineinterpol        VE_splineinterpol        

Function        Cubic-spline interpolation of X-Y-table values
Syntax          #include <VFstd.h>
                void  VF_splineinterpol(
                             fVector Y,  fVector X,  ui sizex,
                             fVector XTab,  fVector YTab,
                             fVector Y2Tab,  ui sizetab );
Description     For each of the sizex elements of X, the corresponding element
                of Y is interpolated from the XTab-YTab value pairs. A table
                of second derivatives of YTab is needed that has to be
                generated by a call to VF_splinederiv2 prior to calling
                VF_splineinterpol.  XTab must be ordered (either ascending or
                descending). All values of XTab must be distinct; otherwise a
                division by zero may occur and lead to a program abort.
                sizetab must be greater than or equal to 3.
Error handling  none (you have to take care yourself that the XTab values are
                distinct and that the YTab values are not near the limit of
                overflowing).
Return value    none
See also        VF_splinederiv2, VF_ratinterpol, VF_polyinterpol


Ŀ
 VF_square                VD_square                VE_square                
 VCF_square               VCD_square               VCE_square               
 VFx_square               VDx_square               VEx_square               
 VCFx_square              VCDx_square              VCEx_square              

Function        Square
Syntax          #include <VFmath.h>
                int  VF_square(  fVector  Y,  fVector  X, ui size );
                int  VFx_square( fVector  Y,  fVector  X, ui size,
                                 float A, float B );
Description     normal versions:    Yi = Xi
                expanded versions:  Yi = (A*Xi+B)
Error handling  OVERFLOW errors lead to a default result of HUGE_VAL.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_cubic,  VF_sqrt,  VF_pow,  VF_ipow,  VF_poly


Ŀ
 VF_sqrt                  VD_sqrt                  VE_sqrt                  
 VCF_sqrt                 VCD_sqrt                 VCE_sqrt                 
 VFx_sqrt                 VDx_sqrt                 VEx_sqrt                 
 VCFx_sqrt                VCDx_sqrt                VCEx_sqrt                

Function        Square root
Syntax          #include <VFmath.h>
                int  VF_sqrt(  fVector Y,  fVector X, ui size );
                int  VFx_sqrt( fVector Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi =  sqrt( Xi )
                expanded versions:  Yi =  C * sqrt( A*Xi+B )
Error handling  DOMAIN errors occur if, in the real-number versions, the
                square root of a negative numbers is requested; NAN ("not-a-
                number") is the default result in this case.
Return value    0, if no error occurred, otherwise non-zero
See also        VF_square,  VF_sqrt,  VF_pow,  VF_ipow,  VF_poly


Ŀ
 VF_ssq                   VD_ssq                   VE_ssq                   

Function        Sum-of-squares
Syntax          #include <VFstd.h>
                float  VF_ssq( fVector X, ui size );
Description     ssq  =  sum( Xi )
Error handling  none (but be careful: this function may lead to an overflow!)
Return value    sum of the squares of the vector elements.
See also        VF_sum,  VF_rms,  VF_ssqdevC, VF_scalprod,  VF_Euclid


Ŀ
 VF_ssqdevC               VD_ssqdevC               VE_ssqdevC               

Function        Sum of the squares of the deviations from a preset value.
Syntax          #include <VFstd.h>
                float  VF_ssqdevC( fVector X, ui size, float C );
Description     ssqdevC  =  sum( (Xi - C) )
Error handling  none
Return value    sum of the squares of the deviations.
See also        VF_ssq, VF_ssqdevV, VF_avdevC,  VF_chi2


Ŀ
 VF_ssqdevV               VD_ssqdevV               VE_ssqdevV               

Function        Sum of the squares of the deviations of the elements of one
                vector from the corresponding elements of another
Syntax          #include <VFstd.h>
                float  VF_ssqdevV( fVector X, fVector Y, ui size );
Description     ssqdevV  =  sum( (Xi - Yi) )
                The deviation of each element of X from the corresponding
                element of Y is calculated and the squares of the deviations
                summed up and returned.
Error handling  none
Return value    sum of the squares of the deviations.
See also        VF_ssq, VF_ssqdevC, VF_avdevV,  VF_chi2


Ŀ
 VF_store                 VD_store                 VE_store                 
 VCF_store                VCD_store                VCE_store                
 VI_store            VSI_store           VLI_store           VQI_store      
 VU_store            VUS_store           VUL_store           VUI_store      

Function        Store a vector in binary format into a stream
Syntax          #include <VFstd.h>
                VF_store( FILE *stream,  fVector X,  ui size );
Description     size elements of X are written to stream in binary format.
                The stream must be already open for binary write operations.
Error handling  none
Return value    none
See also        fwrite,  fread, VF_recall,  VF_write, VF_cprint, VF_print


Ŀ
 VF_subC                  VD_subC                  VE_subC                  
 VCF_subC                 VCD_subC                 VCE_subC                 
 VCF_subReC               VCD_subReC               VCE_subReC               
 VI_subC             VSI_subC            VLI_subC            VQI_subC       
 VU_subC             VUS_subC            VUL_subC            VUI_subC       

Function        Subtract a constant from each vector element
Syntax          #include <VFmath.h>
                void  VF_subC( fVector Y, fVector X, ui size, float C );
                void  VCF_subC(  cfVector Y,  cfVector X,  ui size,
                                 fComplex C );
                void  VCF_subReC( cfVector Y,  cfVector X,  ui size,
                                  float CRe );
Description     Yi  =  Xi -  C
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe subtracted from the complex vector.
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_subV,   VF_subrC, VF_addC,  VF_mulC,  VF_divC


Ŀ
 VF_subrC                 VD_subrC                 VE_subrC                 
 VCF_subrC                VCD_subrC                VCE_subrC                
 VCF_subrReC              VCD_subrReC              VCE_subrReC              
 VI_subrC            VSI_subrC           VLI_subrC           VQI_subrC      
 VU_subrC            VUS_subrC           VUL_subrC           VUI_subrC      

Function        Reverse subtraction: subtract a vector from a constant
Syntax          #include <VFmath.h>
                void  VF_subrC(  fVector Y,  fVector X,  ui size, float C );
                void  VCF_subrC( cfVector Y,  cfVector X,  ui size,
                                 fComplex C );
                void  VCF_subrReC( cfVector Y,  cfVector X,  ui size,
                                   float CRe );
Description     Yi  =  C  -  Xi
                The complex floating-point versions exist in two variants, one
                for complex constants C, the other for real-valued constants
                CRe from which the complex vector is subtracted.
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_addV,  VF_subC,  VF_mulC,  VF_divC,  VF_visC,  VF_redC


Ŀ
 VF_subrV                 VD_subrV                 VE_subrV                 
 VCF_subrV                VCD_subrV                VCE_subrV                
 VCF_subrReV              VCD_subrReV              VCE_subrReV              
 VFx_subrV                VDx_subrV                VEx_subrV                
 VCFx_subrV               VCDx_subrV               VCEx_subrV               
 VCFx_subrReV             VCDx_subrReV             VCEx_subrReV             
 VI_subrV            VSI_subrV           VLI_subrV           VQI_subrV      
 VU_subrV            VUS_subrV           VUL_subrV           VUI_subrV      

Function        Subtraction in reverse order
Syntax          #include <VFmath.h>
                void  VF_subrV( fVector Z, fVector X, fVector Y, ui size );
                void  VFx_subrV( fVector Z, fVector X,  fVector Y,
                                 ui size, float A,  float  B );
                void  VCF_subrV(  cfVector Z, cfVector X, cfVector Y,
                                  ui size );
                void  VCF_subrReV( cfVector Z, cfVector X, fVector Y,
                                   ui size );
                void  VCFx_subrV( cfVector Z, cfVector X, cfVector Y,
                                  ui size, fComplex A,  fComplex B );
                void  VCFx_subrReV( cfVector Z, cfVector X, fVector Y,
                                    ui size, fComplex A,  fComplex B );
Description     normal versions:    Zi  =  Yi  -  Xi
                expanded versions:  Zi  =  Yi  -  (A*Xi+B)
                The complex floating-point versions exist in two variants: in
                the first variant (e.g., VCF_subrV,  VCFx_subrV), X, Y, and Z
                are all complex; in the second variant, Y is real-valued
                (e.g., VCF_subrReV - "reverse subtraction of a real vector",
                i.e., subtraction of a complex vector from a real vector).
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_subrC,  VF_addV,  VF_mulV,  VF_divV,  VF_visV,  VF_redV


Ŀ
 VF_subV                  VD_subV                  VE_subV                  
 VCF_subV                 VCD_subV                 VCE_subV                 
 VCF_subReV               VCD_subReV               VCE_subReV               
 VFs_subV                 VDs_subV                 VEs_subV                 
 VFx_subV                 VDx_subV                 VEx_subV                 
 VCFx_subV                VCDx_subV                VCEx_subV                
 VCFx_subReV              VCDx_subReV              VCEx_subReV              
 VI_subV             VSI_subV            VLI_subV            VQI_subV       
 VU_subV             VUS_subV            VUL_subV            VUI_subV       

Function        Subtract two vectors
Syntax          #include <VFmath.h>
                void  VF_subV( fVector Z, fVector X, fVector Y, ui size );
                void  VFs_subV( fVector Z, fVector X, fVector Y, ui size,
                                float C );
                void  VFx_subV( fVector Z, fVector X, fVector Y, ui size,
                                float A,  float  B );
                void  VCF_subV( cfVector Z, cfVector X, cfVector Y, ui size );
                void  VCF_subReV( cfVector Z, cfVector X, fVector Y,
                                  ui size );
                void  VCFx_subV( cfVector Z, cfVector X, cfVector Y,
                                 ui size,  fComplex A,  fComplex B );
                void  VCFx_subReV( cfVector Z, cfVector X, fVector Y,
                                   ui size,  fComplex A,  fComplex B );
Description     normal versions:      Zi  =  Xi - Yi
                scaled versions:      Zi  =  C * (Xi - Yi)
                expanded versions:    Zi  =  (A*Xi+B) - Yi
                The complex floating-point versions exist in two variants: in
                the first variant (e.g., VCF_subV,  VCFx_subV), X, Y, and Z
                are all complex; in the second variant, Y is real-valued
                (e.g., VCF_subReV - "subtract a real vector").
Error handling  floating-point versions: none;
                integer versions: see chapter 5.2.
Return value    none
See also        VF_subC,  VF_addV,  VF_mulV,  VF_divV,  VF_visV,  VF_redV


Ŀ
 VF_subvector             VD_subvector             VE_subvector             
 VCF_subvector            VCD_subvector            VCE_subvector            
 VI_subvector        VSI_subvector       VLI_subvector       VQI_subvector  
 VU_subvector        VUS_subvector       VUL_subvector       VUI_subvector  

Function        Extract a sub-vector from the input vector
Syntax          #include <VFstd.h>
                void  VF_subvector( fVector Y,  ui subsize,
                                    fVector X,  int samp );
Description     Y[i]  =  X[i*samp]
                A sub-vector Y is extracted from X with a sampling interval
                samp. This means that every samp'th element is taken, up to
                a total of subsize elements, starting with the zeroth element
                of X. Since X may be an expression like XX+1000, samp does
                not always need to be positive, but may also take on negative
                values (or the trivial value of 0).  X and Y have to be
                distinct. Instead of using a samp of 0, 1, or -1, one should
                use VF_equC, VF_equV,  or VF_rev,  respectively.
Error handling  none
Return value    none
See also        VF_indpick, VF_CtoRe


Ŀ
 VF_subvector_...         VD_subvector_...         VE_subvector_...         
 VCF_subvector_...        VCD_subvector_...        VCE_subvector_...        
               ..._addC                 ..._addV                            
               ..._divC                 ..._divV                            
               ..._divrC                ..._divrV                           
               ..._mulC                 ..._mulV                            
               ..._subC                 ..._subV                            
               ..._subrC                ..._subrV                           

Function        Arithmetic functions working on a sub-set of elements within
                a vector of one of the floating-point data types.
Syntax          #include <VFmath.h>
                void  VF_subvector_addC( fVector Y, ui subsize,
                                         unsigned samp, float C );
                void VF_subvector_addV( fVector Y, ui subsize,
                                        unsigned samp, fVector X );
                     (similarly all other functions of this family)
Description     ..._addC:    Y[i*samp]  +=  C,              i=0,...subsize-1
                ..._addV:    Y[i*samp]  +=  Xi,             i=0,...subsize-1
                ..._subC:    Y[i*samp]  -=  C,              i=0,...subsize-1
                ..._subV:    Y[i*samp]  -=  Xi,             i=0,...subsize-1
                ..._subrC:   Y[i*samp]   =  C - Y[i*samp],  i=0,...subsize-1
                ..._subrV:   Y[i*samp]   =  Xi- Y[i*samp],  i=0,...subsize-1
                ..._mulC:    Y[i*samp]  *=  C,              i=0,...subsize-1
                ..._mulV:    Y[i*samp]  *=  Xi,             i=0,...subsize-1
                ..._divC:    Y[i*samp]  /=  C,              i=0,...subsize-1
                ..._divV:    Y[i*samp]  /=  Xi,             i=0,...subsize-1
                ..._divrC:   Y[i*samp]   =  C  / Y[i*samp], i=0,...subsize-1
                ..._divrV:   Y[i*samp]   =  Xi / Y[i*samp], i=0,...subsize-1
                The operation indicated in the suffix of the function name is
                perfomed on a sub-set of the elements of a vector. The
                sampling interval is denoted by samp: every samp'th element is
                taken, up to a total of subsize, starting with the zeroth one
                (that means, subsize is not the total size of the vector, but
                rather the size of the sub-set, i.e. the number of elements
                for which the function is performed).  Notice that all
                operations are performed in place, i.e., the input vector
                itself is changed.
                For similar functions not included in the above list, the
                necessary sequence of calls is similar to the following
                example (which shows how to calculate the sinc function of the
                zeroth and then every tenth element of X, assuming that size
                is an integer multiple of 10):
                     VF_subvector( Y, size/10, 10, X );
                     VF_sinc( Y, Y, size/10 );
                     VF_subvector_equV( X, size/10, 10, Y );
                (However, in such cases, you would sometimes prefer the
                classic style of a loop with the loop-increment set to 10.
                Only if the desired function is not available in the math
                library of Borland C, the effort of copying back and forth
                into the dummy vector Y will pay off.)
Error handling  none
Return value    none
See also        VF_subvector,  VF_subvector_equC,  VF_subvector_equV,  VF_addC


Ŀ
 VF_subvector_...         VD_subvector_...         VE_subvector_...         
 VCF_subvector_...        VCD_subvector_...        VCE_subvector_...        
 VI_subvector_...         VSI_subvector_...                                 
 VLI_subvector_...        VQI_subvector_...                                 
 VU_subvector_...         VUS_subvector_...                                 
 VUL_subvector_...        VUI_subvector_...                                 
               ..._equC                 ..._equV                            

Function        Initialize a sub-set of elements within a vector either with a
                constant value or with values stored as the elements of
                another vector.
Syntax          #include <VFstd.h>
                void  VF_subvector_equC( fVector Y, ui subsize,
                                         unsigned samp, float C );
                void  VF_subvector_equV( fVector Y,  ui subsize,
                                         unsigned samp, fVector X );
                     (similarly all other functions of this family)
Description     ..._equC:  Y[i*samp]  =  C,         i=0,...subsize-1
                ..._equV:  Y[i*samp]  =  Xi,        i=0,...subsize-1
                A sub-set of the elements of a vector is overwritten according
                to the sampling interval samp: every samp'th element is
                initialized either with the constant C, or with the value
                specified as an element of the vector X. A total of subsize
                elements is initialized, starting with the zeroth one (that
                means, subsize is not the total size of the vector, but rather
                the size of the sub-set). VF_subvector_equV is the exact
                reverse of VF_subvector.
Error handling  none
Return value    none
See also        VF_subvector,  VF_equC,  VF_equV,  VF_subvector_addC


Ŀ
 VF_sum                   VD_sum                   VE_sum                   
 VCF_sum                  VCD_sum                  VCE_sum                  
 VI_sum            VSI_sum             VLI_sum             VQI_sum          
 VU_sum            VUS_sum             VUL_sum             VUI_sum          

Function        Sum up all the elements of a vector.
Syntax          #include <VFstd.h>
                float  VF_sum(  fVector  X, ui size );
Description     sum  =  sum( Xi )
                The sum over all elements of a vector is calculated and
                returned.
Error handling  none (but be careful: this function may easily overflow!)
Return value    sum of the vector elements.
See also        VF_runsum, VF_prod, VF_ssq, VF_ssqdevC, VF_mean


Ŀ
 VF_tan                   VD_tan                   VE_tan                   
 VCF_tan                  VCD_tan                  VCE_tan                  
 VFx_tan                  VDx_tan                  VEx_tan                  
 VCFx_tan                 VCDx_tan                 VCEx_tan                 

Function        Tangent function
Syntax          #include <VFmath.h>
                int  VF_tan(  fVector  Y,  fVector  X, ui size );
                int  VFx_tan( fVector  Y, fVector  X, ui size,
                             float A, float B, float C );
Description     normal versions:     Yi  =  tan ( Xi )
                expanded versions:   Yi  =  C *  tan( A*Xi+B )
                For large values of Xi, round-off error becomes appreciable;
                if the Xi values are representable as rational multiples of Pi,
                it is better to use VF_tanrpi  than VF_tan.
Error handling  SING and OVERFLOW errors (for arguments very close to Pi/2)
                lead to a default result of HUGE_VAL. Precision errors lead
                to a default result of 0.0.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_tan2,  VF_tanrpi,  VF_sin,  VF_tanh,  VF_atan,  VF_atan2


Ŀ
 VF_tan2                  VD_tan2                  VE_tan2                  
 VFx_tan2                 VDx_tan2                 VEx_tan2                 

Function        Square of the tangent function
Syntax          #include <VFmath.h>
                int  VF_tan2(  fVector  Y,  fVector  X, ui size );
                int  VFx_tan2( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:    Yi  =  tan( Xi )
                expanded versions:  Yi  =  C * tan( A*Xi+B )
                Calculating the squared trigonometric functions directly is
                faster and sometimes more accurate than first calculating the
                trigonometric function itself and squaring it afterwards.
Error handling  SING and OVERFLOW errors (for arguments close to Pi/2) lead
                to a default result of HUGE_VAL. Precision errors lead to a
                default result of 0.0.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_tan,   VF_tanrpi,   sin


Ŀ
 VF_tanh                  VD_tanh                  VE_tanh                  
 VCF_tanh                 VCD_tanh                 VCE_tanh                 
 VFx_tanh                 VDx_tanh                 VEx_tanh                 
 VCFx_tanh                VCDx_tanh                VCEx_tanh                

Function        Hyperbolic tangent function
Syntax          #include <VFmath.h>
                int  VF_tanh(  fVector  Y,  fVector  X, ui size );
                int  VFx_tanh( fVector  Y,  fVector  X, ui size,
                               float A, float B, float C );
Description     normal versions:   Yi = tanh( Xi )

                                         exp( Xi ) - exp( -Xi )
                                      =  
                                         exp( Xi ) + exp( -Xi )

                expanded versions: Yi = C * tanh( A*Xi+B )
Error handling  These functions should be error-proof.
Return value    always 0.
See also        VF_sinh,  VF_exp,   tanh


Ŀ
 VF_tanrpi                VD_tanrpi                VE_tanrpi                
 VF_tanrpi2               VD_tanrpi2               VE_tanrpi2               
 VF_tanrpi3               VD_tanrpi3               VE_tanrpi3               

Function        Tangent function of fractional multiples of Pi
Syntax          #include <VFmath.h>
                int  VF_tanrpi(  fVector Y, iVector P, ui size, int q );
                int  VF_tanrpi2( fVector Y, iVector P, ui size, int q );
                int  VF_tanrpi3( fVector Y, iVector P, ui size, int q );
Description     Yi  =  tan( (P[i] / q) * Pi )
                The tangent of fractional multiples of Pi is calculated. There
                are three versions: VF_tanrpi is for general use with any
                arbitrary denominator q. If q is a power of 2,  VF_tanrpi2
                should be used which is a highly optimized version using a
                look-up table. If q is a multiple of 3,  VF_tanrpi3 should be
                used. VF_tanrpi2 and VF_tanrpi3 work also with q values they
                are not optimized for; in this case, however, memory space is
                wasted for the then useless tables.
Error handling  SING errors occur if P[i] / q  is an odd multiple of 1/2; the
                default result is 0.0 (which is the mean of +HUGE_VAL and
                -HUGE_VAL).
                q must be non-zero; this is, however, not tested for.
Return value    0, if no error occurred, otherwise non-zero.
See also        VF_tan,   tan


Ŀ
 VF_tantab2               VD_tantab2               VE_tantab2               
 VF_tantab3               VD_tantab3               VE_tantab3               

                Table of tangent values for arguments between 0 and Pi/2.
Syntax          #include <xmath.h>
                extern float     VF_tantab2[ VF_tabsz2+1 ];
                extern double    VD_tantab2[ VD_tabsz2+1 ];
                extern extended  VE_tantab2[ VE_tabsz2+1 ];
                extern float     VF_tantab3[ VF_tabsz3+1 ];
                extern double    VD_tantab3[ VD_tabsz3+1 ];
                extern extended  VE_tantab3[ VE_tabsz3+1 ];
Description     VF_tantab2[ i ]  =  tan( i/(2*VF_tabsz2) * Pi ),
                                                      i=0,...,VF_tabsz2-1
                VF_tantab3[ i ]  =  tan( i/(2*VF_tabsz3) * Pi ),
                                                      i=0,...,VF_tabsz3-1
                VF_tantab2[ VF_tabsz2 ]  =  VF_tantab3[ VF_tabsz3 ] = 0;

                These look-up tables of tangent values for arguments between 0
                and Pi/2 are used by VF_tanrpi2 and the other functions of
                that family and are also available for other purposes. Since
                the tangent of Pi/2 is not defined, zero is stored at its
                place. The symbols VF_tabsz2 etc., denoting the size of the
                tables, are defined in <xmath.h>.
See also        VF_tanrpi2,  VF_sintab2,  VF_cosectab2


Ŀ
 VF_trunc                 VD_trunc                 VE_trunc                 
 VF_trunctoI              VD_trunctoI              VE_trunctoI              
 VF_trunctoSI             VD_trunctoSI             VE_trunctoSI             
 VF_trunctoLI             VD_trunctoLI             VE_trunctoLI             
 VF_trunctoQI             VD_trunctoQI             VE_trunctoQI             
 VF_trunctoU              VD_trunctoU              VE_trunctoU              
 VF_trunctoUS             VD_trunctoUS             VE_trunctoUS             
 VF_trunctoUL             VD_trunctoUL             VE_trunctoUL             
 VF_trunctoUI             VD_trunctoUI             VE_trunctoUI             

Function        Rounding by "truncating" toward zero.
Syntax          #include <VFmath.h>
                int VF_trunc(     fVector Y,  fVector X,  ui size );
                int VF_trunctoI(  iVector Y,  fVector X,  ui size );
                int VF_trunctoU(  uVector Y,  fVector X,  ui size );
                     (similarly  all other functions of this family)
Description     These functions are identical to those of the VF_chop family.
                They have been defined in order to maintain consistency with
                the function name trunc defined in Turbo Pascal. For details,
                see VF_chop.


Ŀ
 V_UtoF                   V_UtoD                   V_UtoE                   
 V_UItoF                  V_UItoD                  V_UItoE                  
 V_ULtoF                  V_ULtoD                  V_ULtoE                  
 V_UStoF                  V_UStoD                  V_UStoE                  

Function        Data type interconversions.  See V_ItoF!


Ŀ
 VF_varianceC             VD_varianceC             VE_varianceC             

Function        Variance of a one-dimensional distribution with respect to a
                pre-set value
Syntax          #include <VFstd.h>
                float  VF_varianceC( fVector X, ui size, float C );
Description     var  = (1 / size) * sum( (Xi - C) )
Error handling  none
Return value    The variance is returned.
See also        VF_mean, VF_varianceV, VF_ssq, VF_ssqdevC, VF_linregress


Ŀ
 VF_varianceCwW           VD_varianceCwW           VE_varianceCwW           

Function        "Variance with weights" of a one-dimensional distribution with
                respect to a pre-set value.
Syntax          #include <VFstd.h>
                float  VF_varianceCwW( fVector X, fVector Wt, ui size,
                                       float C );
Description     var  =  (1 / sum( Wti )) * sum(  Wti * (Xi - C) )
                The weights need not be normalized.
Error handling  none
Return value    variance of the distribution.
See also        VF_meanwW, VF_varianceC, VF_varianceVwW, VF_linregress


Ŀ
 VF_varianceV             VD_varianceV             VE_varianceV             

Function        Variance between two one-dimensional distributions.
Syntax          #include <VFstd.h>
                float  VF_varianceV( fVector X, fVector Y, ui size );
Description     var  = (1 / size) * sum( (Xi - Yi) )
Error handling  none
Return value    The variance is returned.
See also        VF_mean, VF_varianceC,  VF_ssq, VF_ssqdevV, VF_linregress


Ŀ
 VF_varianceVwW           VD_varianceVwW           VE_varianceVwW           

Function        "Variance with weights" between two one-dimensional
                distributions.
Syntax          #include <VFstd.h>
                float  VF_varianceVwW( fVector X, fVector Y,
                                       fVector Wt, ui size );
Description     var  = (1 / sum( Wti )) * sum( Wti * (Xi - Yi) )
                The weights need not be normalized.
Error handling  none
Return value    weighted variance
See also        VF_meanwW,  VF_chi2, VF_varianceV, VF_varianceCwW,
                VF_linregress


Ŀ
 VF_vector                VD_vector                VE_vector                
 VCF_vector               VCD_vector               VCE_vector               
 VI_vector         VSI_vector          VLI_vector          VQI_vector       
 VU_vector         VUS_vector          VUL_vector          VUI_vector       

Function        Memory allocation for a vector
Syntax          #include <VFstd.h>
                fVector   VF_vector(  ui size );
Description     Based on memory model and environment, the most appropriate
                allocation procedure is chosen by these functions. Failure to
                allocate memory always leads to an error message and a
                subsequent program abort (similar to the error handling of the
                "new" operator in C++). To release the memory thus allocated,
                V_free or V_nfree should be used. Notice: the declaration of a
                vector (e.g., as fVector) reserves only a name, but no memory!
                See chapter 4.1 if you are interested in details of the
                implementation.
Error handling  If there is not enough memory available, or if size is zero,
                an error message "Not enough memory" is displayed and the
                program aborted.
                Models SMALL, MEDIUM, COMPACT, and LARGE only:
                  If more than 64 kB of memory are requested,
                  an error message "Vector > 64 kB not possible" is displayed
                  and the program aborted.
Return value    Pointer to the allocated memory
See also        malloc, calloc


Ŀ
 VF_vector0               VD_vector0               VE_vector0               
 VCF_vector0              VCD_vector0              VCE_vector0              
 VI_vector0        VSI_vector0         VLI_vector0         VQI_vector0      
 VU_vector0        VUS_vector0         VUL_vector0         VUI_vector0      

Function        Memory allocation for a vector and initialization of all
                elements with 0
Syntax          #include <VFstd.h>
                fVector   VF_vector0(  ui size );
Description     The functions of this family are almost identical to those of
                the VF_vector family; in addition to allocating memory, they
                initialize all elements with 0. (Calls to VF_vector and
                VF_vector0  may be mixed; they use the same tables to keep
                track of the handles and pointers).  For further information,
                see VF_vector.
Error handling  If there is not enough memory available, or if size is zero,
                an error message "Not enough memory" is displayed and the
                program aborted.
                Models SMALL, MEDIUM, COMPACT, and LARGE only:
                  If more than 64 kB of memory are requested,
                  an error message "Vector > 64 kB not possible" is displayed
                  and the program aborted.
Return value    A pointer to the allocated memory is returned.
See also        malloc, calloc


Ŀ
 VF_visC                  VD_visC                  VE_visC                  

Function        Visibility (or contrast) function of a vector with respect to
                a constant
Syntax          #include <VFmath.h>
                void  VF_visC( fVector Y, fVector X, ui size, float C );
Description     Yi  =  vis( Xi, C )  =  (Xi - C) / (Xi + C)
                These functions are generalizations of the "visibility" or
                "contrast" function used in optics, where the contrast between
                two intensities is defined as their difference divided by
                their sum.
                For Xi=C, the visibility is defined as 0, even in the case
                of Xi=C=0.
Error handling  none
Return value    none
See also        VF_redV,  VF_addC,  VF_subC,  VF_divC,  VF_visC


Ŀ
 VF_visV                  VD_visV                  VE_visV                  
 VFx_visV                 VDx_visV                 VEx_visV                 

Function        Visibility function of one vector with respect to another
Syntax          #include <VFmath.h>
                void  VF_visV( fVector Z,   fVector X,  fVector Y, ui size );
                void  VFx_visV( fVector Z,   fVector X,  fVector Y,
                                ui size,  float  A,  float  B );
Description     normal versions:   Zi  =  vis( Xi, Yi )
                                       =  (Xi - Yi) / (Xi + Yi)
                expanded versions: Zi  =  vis( A*Xi+B, Yi )
                For Xi=Yi, the visibility is defined as 0, even in the case
                of Xi=Yi=0.
Error handling  none
Return value    none
See also        VF_visC,  VF_addV,  VF_subV,  VF_divV,  VF_redV


Ŀ
 VF_Welch                 VD_Welch                 VE_Welch                 

Function        "Welch" window for use in spectral analysis
Syntax          #include <VFstd.h>
                void VF_Welch(  fVector X, ui size );
Description     Xi  = 1 - ( (i - 0.5*(size - 1)) / (0.5*(size + 1)) )
Error handling  none
Return value    none
See also        VF_Parzen, VF_Hanning, VF_spectrum


Ŀ
 VF_write                 VD_write                 VE_write                 
 VCF_write                VCD_write                VCE_write                
 VI_write          VSI_write           VLI_write           VQI_write        
 VU_write          VUS_write           VUL_write           VUI_write        

Function        Write a vector in ASCII format to a stream.
Syntax          #include <VFstd.h>
                void VF_write(  FILE *stream, fVector X, ui size );
Description     size elements of X are written to stream in ASCII format.
                By default, one element is written per line. To use these
                functions, stream must already be open for write operations
                in text format.

                The number format and the separation of consecutive elements
                may be specified using VF_setWriteFormat and
                VF_setWriteSeparate, respectively. See these functions
                for details.

                Storing data in ASCII format is useful if the data have to be
                readable by human eyes, or if they are to be exported into
                other programs which are not able to read machine-format
                numbers. If avoidable, these functions should not be used for
                the storage of intermediate results that later have again to
                be read in. Instead, the function pairs of the VF_store /
                VF_recall  family are recommended for the following reasons:
                conversion into ASCII format is slow, may lead to round-off
                errors, and requires much more disk memory than storage in
                machine format.
Error handling  none
Return value    none
See also        VF_setWriteFormat, VF_setWriteSeparate, VF_nwrite, VF_read,
                VF_store, fprintf, VF_cprint, VF_print


Ŀ
 VF_xcorr                 VD_xcorr                 VE_xcorr                 

Function        Cross-correlation function of two vectors.
Syntax          #include <VFstd.h>
                void VF_xcorr(  fVector Z, fVector X, fVector Y, ui size );
Description     The cross-correlation function (CCF) of X and Y is calculated
                and stored in Z  in wrap-around order: Z[0] to Z[size/2-1]
                contain the CCF for zero and positive lags. Beginning with
                the most negative lag in Z[size/2+1], the elements up to
                Z[size-1] contain the CCF for negative lags. Since this
                function assumes X to be periodic, the CCF for the most
                positive lag is identical to the CCF for the most negative
                lag. This element is stored as Z[size/2].
                To get the CCF into normal order, you may call
                   VF_rotate( Z, Z, size, size/2 );
                After that, the zero point is at the position size/2.

                In case X is non-periodic, end effects should be avoided
                by the methods described in connection with VF_convolve.

                About special versions with the prefixes  VFs_  and VFl_,
                consult chapter 4.8.
Error handling  If size is not a power of 2,  VF_FFT  (on which VF_xcorr
                is based) complains "Size must be an integer power of 2"
                and the program is aborted.
Return value    none
See also        VF_FFT,  VF_convolve,  VF_autocorr, VF_spectrum


Ŀ
 VI_xor              VSI_xor             VLI_xor             VQI_xor        
 VU_xor              VUS_xor             VUL_xor             VUI_xor        

Function        Bit-wise "XOR" operation.
Syntax          #include <VImath.h>
                void VI_xor(  iVector Y, iVector X, ui size,  int C );
                void VUL_xor( ulVector Y, ulVector X,  ui size,
                              unsigned long C );
Description     Yi  =  (Xi) ^ C
                The bit-wise "exclusive OR" operation is performed on each
                element Xi with the bit-mask given by C  (i.e., a bit is 0 in
                Yi, if it was either 0 or 1 both in Xi and C simultaneously.
                It is 1 if  Xi and C differed in this bit position).
Error handling  none
Return value    none
See also        VI_not,  VI_and,  VI_or


Ŀ
 VF_xprod                 VD_xprod                 VE_xprod                 

Function        Cross-product of two vectors.
Syntax          #include <VFstd.h>
                void VF_xprod( fVector Z, fVector X, fVector Y );
Description     Z  =  X x Y
                The cross- product of X and Y is calculated. Since this
                operation is defined specifically for vectors representing
                three dimensions in the geometrical sense, there is no
                parameter "size" for this function. The number of elements
                is 3 for each of the participating vectors, implicitly.
Error handling  none
Return value    none
See also        VF_scalprod, VF_Euclid


Ŀ
 VF_xyAutoPlot            VD_xyAutoPlot            VE_xyAutoPlot            
 VI_xyAutoPlot     VSI_xyAutoPlot       VLI_xyAutoPlot      VQI_xyAutoPlot  
 VU_xyAutoPlot     VUS_xyAutoPlot       VUL_xyAutoPlot      VUI_xyAutoPlot  

Function        Draws a Cartesian coordinate system and plots a Y-vector
                against an X-vector into it.
Syntax          #include <Vgraph.h>
                void VF_xyAutoPlot(  fVector X,  fVector Y,  ui size,
                                     unsigned form,   COLORREF color );
Description     A Cartesian coordinate system is drawn with automatic scaling
                of the axes and the vector Y is plotted against the vector X.
                Prior to calling VF_xyAutoPlot, the plotting routines have to
                be initialized by V_initGraph (for DOS programs) or V_initPlot
                (DOS or Windows programs).

                The style of the plot is determined by the parameter form
                which should be constructed using the symbolic constants
                defined in <Vgraph.h>. For the line styles, either the BGI
                notation or the Windows notation may be used both in DOS and
                Windows programs; the necessary macros for the translation are
                included in <Vgraph.h>.

                1. Style of lines connecting adjacent data points:
                  PS_SOLID         SOLID_LINE            ____   (default)
                  PS_DOT           DOTTED_LINE             
                  PS_DASH          DASHED_LINE           - - -
                  PS_DASHDOT       CENTER_LINE           ---
                  PS_DASHDOTDOT                          --
                  PS_NULL          NULL_LINE             (no line at all)

                2. Symbols used to mark data points:
                  SY_NULL              (no symbol at all)       (default)
                  SY_CROSS                   x
                  SY_PLUS                    +
                  SY_STAR                    *
                  SY_CIRCLE                  o
                  SY_BOX                     
                  SY_DIAMOND	               
                  SY_TRIANGLEUP              
                  SY_TRIANGLEDOWN            
                     (if you loaded this file into a Windows program, some
                      symbols may have been lost during character conversion)

                3. Fill-style of the symbols:
                  SY_HOLLOW         (no filling)              (default)
                  SY_FILLED         (filled)
                  SY_DOTTED         (hollow, with a dot at the exact
                                     position of the data point)

                The parameter form has to be constructed by adding the
                appropriate line style, the symbol and its fill-style, e.g.
                (SOLID_LINE + SY_TRIANGLEUP). Alternatively, the bit-wise "OR"
                operation may be used,  e.g.  (PS_SOLID | SY_CIRCLE |
                SY_DOTTED).

                If any of the line styles except NULL_LINE (or PS_NULL) is
                chosen, each data point will be represented by at least one
                pixel in DOS programs. Therefore, dotted or broken lines
                should be specified only if there are not too many data
                points. Otherwise, all line styles will eventually look like
                SOLID_LINE. In Windows programs, these line styles will always
                be plotted correctly and points will be left out if necessary.

                Notice that  NULL_LINE or PS_NULL has to be explicitly
                specified, if the data points are not to be connected by
                lines. Just writing, e.g. (SY_BOX | SY_HOLLOW) would be
                interpreted as using the default line style, which is
                SOLID_LINE.

                SY_NULL and SY_HOLLOW need not be specified, since these are
                the default symbol and fill-style, resp. For SY_NULL,
                SY_CROSS, SY_PLUS and SY_STAR, the choice of fill-style has no
                effect.

                The parameter color denotes the color that is to be used for
                the plot (the data type COLORREF is unsigned for DOS programs
                and unsigned long for Windows programs). See the Borland C++
                function setcolor for a description of the colors available in
                the various graphics modes under DOS. For Windows, the colors
                BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
                DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED,
                LIGHTMAGENTA, YELLOW, and WHITE are defined in <Vgraph.h> by
                analogy with the COLORS defined in <graphics.h> for the BGI
                routines, i.e. for DOS programs. Thereby, portability between
                DOS and Windows programs is improved. For programs designed to
                run exclusively under Windows, it is nevertheless recommended
                to use fine-tuned colors defined by the RGB macro, instead of
                the predefined colors.

                The size of the symbols may be modified with the function
                V_setSymbolSize. The thickness of the lines may be modified
                using V_setLineThickness.

Example of a DOS program:
                #include <VFstd.h>
                #include <VFmath.h>
                #include <Vgraph.h>
                #include <conio.h>
                void main( void )
                {
                     ui       size=101;
                     fVector  X,  Y1,   Y2;

                     V_initGraph( "C:\\BorlandC\\BGI\\" );
                            /* Be sure the path is correct! */
                     X  = VF_vector( size );
                     Y1 = VF_vector( size );
                     Y2 = VF_vector( size );
                     VF_ramp( X, size, -1.0, 2.0/100 );
                     VFx_sincos( Y1, Y2, X, size, 3.1415927, 0.0, 1.0 );
                     VF_xyAutoPlot( X, Y1, size,
                                    PS_SOLID | SY_CROSS,
                                    LIGHTGREEN );
                     VF_xyDataPlot( X, Y2, size,
                                    PS_SOLID | SY_CIRCLE | SY_DOTTED,
                                    LIGHTRED );
                     getch();      /* interrupt execution while watching;
                                      then press any key  */
                     closegraph();
                     V_nfree( 3, Y2, Y1, X );
                }

                Under Windows, call V_initPlot instead of V_initGraph, before
                performing plotting operations.
Error handling  none
Return value    none
See also        VF_xyAutoPlot,  VF_yAutoPlot,  VCF_autoPlot, V_drawAxes,
                V_findAxes, V_setSymbolSize,  chapter 4.11


Ŀ
 VF_xy2AutoPlot           VD_xy2AutoPlot           VE_xy2AutoPlot           
 VI_xy2AutoPlot    VSI_xy2AutoPlot      VLI_xy2AutoPlot     VQI_xy2AutoPlot 
 VU_xy2AutoPlot    VUS_xy2AutoPlot      VUL_xy2AutoPlot     VUI_xy2AutoPlot 

Function        Draws a Cartesian coordinate system and plots two X-Y vector
                pairs into it.
Syntax          #include <Vgraph.h>
                void VF_xy2AutoPlot(   fVector X1, fVector Y1, ui size1,
                                       unsigned form1, COLORREF color1,
                                       fVector X2, fVector Y2, ui size2,
                                       unsigned form2, COLORREF color2 );
Description     The vector Y1 is plotted against the vector X1 and Y2 against
                X2 after automatically drawing a Cartesian coordinate system.
                For a description of the parameters form1, form2, and color1,
                color2, see VF_xyAutoPlot. Prior to calling VF_xy2AutoPlot,
                the plotting routines have to be initialized by V_initGraph or
                V_initPlot.
Error handling  none
Return value    none
See also        VF_xyAutoPlot,  VF_yAutoPlot,  VCF_autoPlot, V_drawAxes,
                V_findAxes


Ŀ
 VF_xyDataPlot            VD_xyDataPlot            VE_xyDataPlot            
 VI_xyDataPlot     VSI_xyDataPlot       VLI_xyDataPlot      VQI_xyDataPlot  
 VU_xyDataPlot     VUS_xyDataPlot       VUL_xyDataPlot      VUI_xyDataPlot  

Function        X-Y-plot into an existing Cartesian coordinate system.
Syntax          #include <Vgraph.h>
                void VF_xyDataPlot( fVector X,  fVector Y,  ui size,
                                    unsigned form,  COLORREF color );
Description     The vector Y is plotted against the vector X into a Cartesian
                coordinate system drawn by a prior call to one of the AutoPlot
                functions or to V_drawAxes. For a description of the parameters
                form and color, see VF_xyAutoPlot.
Error handling  none
Return value    none
See also        VF_xyAutoPlot,  VF_yAutoPlot,  VCF_autoPlot, V_drawAxes,
                V_findAxes


Ŀ
 VF_yAutoPlot             VD_yAutoPlot             VE_yAutoPlot             
 VI_yAutoPlot      VSI_yAutoPlot        VLI_yAutoPlot       VQI_yAutoPlot   
 VU_yAutoPlot      VUS_yAutoPlot        VUL_yAutoPlot       VUI_yAutoPlot   

Function        Draws a Cartesian coordinate system and plots each element of
                a Y-vector against its index.
Syntax          #include <Vgraph.h>.
                void VF_yAutoPlot( fVector Y, ui size,
                                   unsigned form, COLORREF color );
Description     A Cartesian coordinate system is automatically scaled and
                drawn. Each element of the vector Y is plotted against its
                index into this coordinate system. For a description of the
                parameters form and color, see VF_xyAutoPlot. The plotting
                routines have to be initialized by V_initGraph or V_initPlot
                prior to calling VF_yAutoPlot.
Error handling  none
Return value    none
See also        VF_yDataPlot,  VF_y2AutoPlot,   VF_xyAutoPlot, VCF_autoPlot,
                V_drawAxes, V_findAxes,  chapter 4.11


Ŀ
 VF_y2AutoPlot            VD_y2AutoPlot            VE_y2AutoPlot            
 VI_y2AutoPlot     VSI_y2AutoPlot       VLI_y2AutoPlot      VQI_y2AutoPlot  
 VU_y2AutoPlot     VUS_y2AutoPlot       VUL_y2AutoPlot      VUI_y2AutoPlot  

Function        Draws a Cartesian coordinate system and plots two Y-vectors,
                taking the index as the X-axis.
Syntax          #include <Vgraph.h>
                void VF_y2AutoPlot(   fVector Y1, ui size1,
                                      unsigned form1, COLORREF color1,
                                      fVector Y2, ui size2,
                                      unsigned form2, COLORREF color2 );
Description     A Cartesian coordinate system is automatically scaled and
                drawn. Each element of the vectors Y1 and Y2 is plotted at the
                X-position given by its index. For a description of the
                parameters form1, form2, and color1, color2, see
                VF_xyAutoPlot. The plotting routines have to be initialized by
                V_initGraph or V_initPlot prior to calling VF_yAutoPlot.
Error handling  none
Return value    none
See also        VF_yDataPlot,  VF_y2AutoPlot,   VF_xyAutoPlot, VCF_autoPlot,
                V_drawAxes, V_findAxes,  chapter 4.11


Ŀ
 VF_yDataPlot             VD_yDataPlot             VE_yDataPlot             
 VI_yDataPlot      VSI_yDataPlot        VLI_yDataPlot       VQI_yDataPlot   
 VU_yDataPlot      VUS_yDataPlot        VUL_yDataPlot       VUI_yDataPlot   

Function        Plots a Y-vector into an existing Cartesian coordinate system,
                taking the index as the X-axis.
Syntax          #include <Vgraph.h>
                void VF_yDataPlot(   fVector Y, ui size,
                                     unsigned form, COLORREF color );
Description     Each element of the vector Y is plotted into a Cartesian
                coordinate system that has to be already drawn by a prior call
                to one of the AutoPlot functions or to V_drawAxes. The X-
                position is given by the index of the Y-element to be plotted.
                For a description of the parameters form and color, see
                VF_xyAutoPlot.
Error handling  none
Return value    none
See also        VF_yAutoPlot,  VF_y2AutoPlot,   VF_xyAutoPlot, VCF_autoPlot,
                V_drawAxes, V_findAxes,  chapter 4.11





****************************************************************************
*                                                                          *
*******            9. Non-vectorized Functions                       *******
*                                                                          *
*****************************************************************************

There are a few non-vectorized functions, stemming from CMATH and XMATH,
which are necessary to use VectorLib. They are described here:

Ŀ
 fcplx                    dcplx                    ecplx                    

Function        Initialization of complex numbers
Syntax          #include <VecLib.h>
                fComplex  fcplx( float ReVal, float ImVal );
                     (similarly dcplx,  ecplx)
Description     These functions allow to generate complex numbers of the three
                complex data types fComplex, dComplex, and eComplex.
                CMATH offers overloaded versions of these functions for C++.
                See CMATH.TXT for details.
                fcplx should be used, whenever temporary complex variables
                are needed as arguments for functions. In this case, fcplx
                replaces the less elegant direct assignment of the real
                and imaginary parts.
Example         z.Re = 3.0;  z.Im = 4.0;
                VCF_equC( X, size, z );     /* less convenient */
                VCF_equC( Y, size, fcplx( 3.0, 4.0 ));  /* easier */
Error handling  none
Return value    the generated complex number


Ŀ
 quadtod                  _quadtold                                         

Function        convert a quad into a double or long double.
Syntax          #include <VecLib.h>
                double	      quadtod( quad x );
                long double   _quadtold( quad x );
Description     These functions, along with their counterpart, setquad,
                provide the necessary interface for the use of the data type
                quad within Borland C/C++. If, e.g., the value of a quad
                (say, of x) has to be printed, this must be done by a
                function call like
                     printf( "% 20.0Lf",  _quadtold( x ));
Error handling  none
Return value    the value of x is returned as a double or long double.


Ŀ
 isint                    isintl                                            

Function        tests if a number is a whole number
Syntax          #include <xmath.h>
                int  isint( double x );
                int  isintl( long double x );
Description     Returns TRUE (a value different from 0), if x is an integer
                number. FALSE (a value of 0) is returned, if x contains a non-
                zero fractional part.
Error handling  none
Return value    see above


Ŀ
 log2                     log2l                                             

Function        Binary logarithm
Syntax          #include <xmath.h>
                double       log2( double x );
                long double  log2l( long double x );
Description     The logarithm of the argument to the basis 2 is calculated and
                the result returned.
Error handling  A DOMAIN error with  NAN ("not-a-number") as return value
                results from x < 0 (including -0). A  SING  error with
                -HUGE_VAL as return value results from x=0. The handling of
                both errors can be modified via _matherr or _matherrl, resp.
Return value    The binary logarithm of the argument is returned.
See also        log, logl,  log10, log10l,  VF_log2


Ŀ
 setquad                                                                    

Function        converts a long double into a quad.
Syntax          #include <VecLib.h>
                quad  setquad( long double x );
Description     This function, along with its counterparts, quadtod and
                _quadtold, provides the necessary interface for the use of the
                data type quad within Borland C/C++. If, e.g.,  quad
                parameters are required by a function, they have to be passed
                either as existing variables of this data type or as in the
                following example:
                    VQI_addC( QI2, QI1,size, setquad( 53563369.L ));
Error handling  none
Return value    the value of x is returned as a quad.



****************************************************************************
*                                                                          *
*******               10. VectorLib Error Messages                   *******
*                                                                          *
****************************************************************************


Just as with any C or C++ program, errors occurring within mathematical
functions lead to the appropriate error messages. See chapter 5 of this
documentation (in the file HANDBOOK.TXT) and the description of _matherr
in the Borland C++ documentation for details. Apart from math errors, there
are some run-time errors specific to VectorLib routines. These errors lead to
the messages noted below. The name of the function where the error occurred
is not always exactly the name you wrote in your program. Instead of the
prefix VI_, the message will read VLI_ or VSI_, depending on the memory model
used. Similarly, instead of VU_, you will find VUL_ or VUS_, and VFs_FFT or
VFl_FFT is substituted for VF_FFT, again depending on the memory model.
The reason for this behavior is that many functions share code and even names.

Ŀ
 Cannot free non-existent vector.                                           

You called V_free or V_nfree for a vector that has no memory allocated.
Program execution is continued without freeing anything.

Ŀ
 Cannot scale symbols by more than a factor of 50.                          

(Windows only.) The symbols used in VectorLib plotting functions cannot be
magnified by more than a factor of 50 (which means already filling the screen
with a single symbol). Program execution is continued with a value of 50.0.

Ŀ
 Cannot use line thicker than 500 pixels.                                   

(Windows only.) The lines used in VectorLib plotting functions cannot be
thicker than 500 pixels (which is already nonsense). Program execution is
continued with a value of 500.

Ŀ
 Cannot use requested format (too many entries per line).                   

This error occurs with the printing functions. The parameter nperline was
chosen too large. The function automatically selects the maximum nperline
possible and continues execution, but you should nevertheless consider
adapting your program.

Ŀ
 Invalid parameter(s).                                                      

In some functions, certain combinations of input parameters are illegal. For
example, it is not possible to perform a 9-point interpolation on only 5
data points.

Ŀ
 Not enough memory.                                                         

You are trying to allocate memory, but there is not enough left. This error
occurs during calls to VF_vector etc. or to functions which need to allocate
their own working space. Try these solutions:
*   Look out for vectors that might be no longer needed and free them as soon
    as possible. Be sure that any vectors allocated in subroutines are freed
    before leaving the subroutine.
*   If you need to work with large amounts of data, the memory model FLAT
    should be used, working with Win32, WindowsNT, or Windows95.
*   Store data intermediately on disk, using VF_store, and retrieve them
    using VF_recall, when needed. This method is slow and should be used only
    if really necessary.

Ŀ
 Not possible with fewer than n elements.                                   

Some functions require a minimum size of n elements of the vector processed.

Ŀ
 Not possible with more than n elements.                                    

Some functions are limited to a maximum size of n elements. This is true,
for example, for VF_polyinterpol, where only up to 10 table elements may be
used for the each interpolation.

Ŀ
 Size must be an integer power of 2.                                        

For all functions using - explicitly or implicitly - Fast Fourier Transform
methods, the size has to be an integer power of 2. Enlarge or truncate your
vector(s) to meet that condition.

Ŀ
 Vector > 64 kB not possible.                                               

*    Either you are trying to allocate a vector whose size exceeds 64 kB in
     a memory model other than HUGE or FLAT. If you need larger vectors, you
     have to switch to one of these models.
*    Or you are already in the HUGE model and attempt to process a huge vector
     in a function where the size is limited to 64 kB even in the HUGE model.
     This might happen, e.g., if the table is too large in one of the
     interpolation routines. In this case, you must either use the model FLAT
     or split up your problem into smaller vectors.

Ŀ
 Vectors must not be identical.                                             

In some functions where more than one input vector is used to calculate more
than one output vector, attention has to be paid, which output vector may or
may not overwrite which input vector. See the specification of the function
where the error occurred.


****************************************************************************
*                                                                          *
*******                      E  N  D                                 *******
*                                                                          *
*****************************************************************************
****************************************************************************

Copyright for VectorLib software and documentation
(C) 1996-1998 Martin Sander.
All rights reserved!
