vectors.texi

来自「math library from gnu」· TEXI 代码 · 共 1,492 行 · 第 1/5 页

@cindex blocks
@cindex vectors
@cindex matrices

The functions described in this chapter provide a simple vector and
matrix interface to ordinary C arrays. The memory management of these
arrays is implemented using a single underlying type, known as a
block. By writing your functions in terms of vectors and matrices you
can pass a single structure containing both data and dimensions as an
argument without needing additional function parameters.  The structures
are compatible with the vector and matrix formats used by @sc{blas}
routines.

@menu
* Data types::                  
* Blocks::                      
* Vectors::                     
* Matrices::                    
* Vector and Matrix References and Further Reading::  
@end menu

@node Data types
@section Data types

All the functions are available for each of the standard data-types.
The versions for @code{double} have the prefix @code{gsl_block},
@code{gsl_vector} and @code{gsl_matrix}.  Similarly the versions for
single-precision @code{float} arrays have the prefix
@code{gsl_block_float}, @code{gsl_vector_float} and
@code{gsl_matrix_float}.  The full list of available types is given
below,

@example
gsl_block                       double         
gsl_block_float                 float         
gsl_block_long_double           long double   
gsl_block_int                   int           
gsl_block_uint                  unsigned int  
gsl_block_long                  long          
gsl_block_ulong                 unsigned long 
gsl_block_short                 short         
gsl_block_ushort                unsigned short
gsl_block_char                  char          
gsl_block_uchar                 unsigned char 
gsl_block_complex               complex double        
gsl_block_complex_float         complex float         
gsl_block_complex_long_double   complex long double   
@end example

@noindent
Corresponding types exist for the @code{gsl_vector} and
@code{gsl_matrix} functions.



@node Blocks
@section Blocks

For consistency all memory is allocated through a @code{gsl_block}
structure.  The structure contains two components, the size of an area of
memory and a pointer to the memory.  The @code{gsl_block} structure looks
like this,

@example
typedef struct
@{
  size_t size;
  double * data;
@} gsl_block;
@end example
@comment

@noindent
Vectors and matrices are made by @dfn{slicing} an underlying block. A
slice is a set of elements formed from an initial offset and a
combination of indices and step-sizes. In the case of a matrix the
step-size for the column index represents the row-length.  The step-size
for a vector is known as the @dfn{stride}.

The functions for allocating and deallocating blocks are defined in
@file{gsl_block.h}

@menu
* Block allocation::            
* Reading and writing blocks::  
* Example programs for blocks::  
@end menu

@node Block allocation
@subsection Block allocation

The functions for allocating memory to a block follow the style of
@code{malloc} and @code{free}.  In addition they also perform their own
error checking.  If there is insufficient memory available to allocate a
block then the functions call the GSL error handler (with an error
number of @code{GSL_ENOMEM}) in addition to returning a null
pointer.  Thus if you use the library error handler to abort your program
then it isn't necessary to check every @code{alloc}.  

@deftypefun {gsl_block *} gsl_block_alloc (size_t @var{n})
This function allocates memory for a block of @var{n} double-precision
elements, returning a pointer to the block struct.  The block is not
initialized and so the values of its elements are undefined.  Use the
function @code{gsl_block_calloc} if you want to ensure that all the
elements are initialized to zero.

A null pointer is returned if insufficient memory is available to create
the block.
@end deftypefun

@deftypefun {gsl_block *} gsl_block_calloc (size_t @var{n})
This function allocates memory for a block and initializes all the
elements of the block to zero.
@end deftypefun

@deftypefun void gsl_block_free (gsl_block * @var{b})
This function frees the memory used by a block @var{b} previously
allocated with @code{gsl_block_alloc} or @code{gsl_block_calloc}.  The
block @var{b} must be a valid block object (a null pointer is not
allowed).
@end deftypefun

@node Reading and writing blocks
@subsection Reading and writing blocks

The library provides functions for reading and writing blocks to a file
as binary data or formatted text.

@deftypefun int gsl_block_fwrite (FILE * @var{stream}, const gsl_block * @var{b})
This function writes the elements of the block @var{b} to the stream
@var{stream} in binary format.  The return value is 0 for success and
@code{GSL_EFAILED} if there was a problem writing to the file.  Since the
data is written in the native binary format it may not be portable
between different architectures.
@end deftypefun

@deftypefun int gsl_block_fread (FILE * @var{stream}, gsl_block * @var{b})
This function reads into the block @var{b} from the open stream
@var{stream} in binary format.  The block @var{b} must be preallocated
with the correct length since the function uses the size of @var{b} to
determine how many bytes to read.  The return value is 0 for success and
@code{GSL_EFAILED} if there was a problem reading from the file.  The
data is assumed to have been written in the native binary format on the
same architecture.
@end deftypefun

@deftypefun int gsl_block_fprintf (FILE * @var{stream}, const gsl_block * @var{b}, const char * @var{format})
This function writes the elements of the block @var{b} line-by-line to
the stream @var{stream} using the format specifier @var{format}, which
should be one of the @code{%g}, @code{%e} or @code{%f} formats for
floating point numbers and @code{%d} for integers.  The function returns
0 for success and @code{GSL_EFAILED} if there was a problem writing to
the file.
@end deftypefun

@deftypefun int gsl_block_fscanf (FILE * @var{stream}, gsl_block * @var{b})
This function reads formatted data from the stream @var{stream} into the
block @var{b}.  The block @var{b} must be preallocated with the correct
length since the function uses the size of @var{b} to determine how many
numbers to read.  The function returns 0 for success and
@code{GSL_EFAILED} if there was a problem reading from the file.
@end deftypefun
@comment

@node Example programs for blocks
@subsection Example programs for blocks

The following program shows how to allocate a block,

@example
@verbatiminclude examples/block.c
@end example
@comment

@noindent
Here is the output from the program,

@example
@verbatiminclude examples/block.out
@end example
@comment

@node Vectors
@section Vectors
@cindex vectors
@cindex stride, of vector index

Vectors are defined by a @code{gsl_vector} structure which describes a
slice of a block.  Different vectors can be created which point to the
same block.  A vector slice is a set of equally-spaced elements of an
area of memory.

The @code{gsl_vector} structure contains five components, the
@dfn{size}, the @dfn{stride}, a pointer to the memory where the elements
are stored, @var{data}, a pointer to the block owned by the vector,
@var{block}, if any, and an ownership flag, @var{owner}.  The structure
is very simple and looks like this,

@example
typedef struct
@{
  size_t size;
  size_t stride;
  double * data;
  gsl_block * block;
  int owner;
@} gsl_vector;
@end example
@comment

@noindent
The @var{size} is simply the number of vector elements.  The range of
valid indices runs from 0 to @code{size-1}.  The @var{stride} is the
step-size from one element to the next in physical memory, measured in
units of the appropriate datatype.  The pointer @var{data} gives the
location of the first element of the vector in memory.  The pointer
@var{block} stores the location of the memory block in which the vector
elements are located (if any).  If the vector owns this block then the
@var{owner} field is set to one and the block will be deallocated when the
vector is freed.  If the vector points to a block owned by another
object then the @var{owner} field is zero and any underlying block will not be
deallocated with the vector.

The functions for allocating and accessing vectors are defined in
@file{gsl_vector.h}

@menu
* Vector allocation::           
* Accessing vector elements::   
* Initializing vector elements::  
* Reading and writing vectors::  
* Vector views::                
* Copying vectors::             
* Exchanging elements::         
* Vector operations::           
* Finding maximum and minimum elements of vectors::  
* Vector properties::           
* Example programs for vectors::  
@end menu

@node Vector allocation
@subsection Vector allocation

The functions for allocating memory to a vector follow the style of
@code{malloc} and @code{free}.  In addition they also perform their own
error checking.  If there is insufficient memory available to allocate a
vector then the functions call the GSL error handler (with an error
number of @code{GSL_ENOMEM}) in addition to returning a null
pointer.  Thus if you use the library error handler to abort your program
then it isn't necessary to check every @code{alloc}.

@deftypefun {gsl_vector *} gsl_vector_alloc (size_t @var{n})
This function creates a vector of length @var{n}, returning a pointer to
a newly initialized vector struct. A new block is allocated for the
elements of the vector, and stored in the @var{block} component of the
vector struct.  The block is ``owned'' by the vector, and will be
deallocated when the vector is deallocated.
@end deftypefun

@deftypefun {gsl_vector *} gsl_vector_calloc (size_t @var{n})
This function allocates memory for a vector of length @var{n} and
initializes all the elements of the vector to zero.
@end deftypefun

@deftypefun void gsl_vector_free (gsl_vector * @var{v})
This function frees a previously allocated vector @var{v}.  If the
vector was created using @code{gsl_vector_alloc} then the block
underlying the vector will also be deallocated.  If the vector has
been created from another object then the memory is still owned by
that object and will not be deallocated.  The vector @var{v} must be a
valid vector object (a null pointer is not allowed).
@end deftypefun

@node Accessing vector elements
@subsection Accessing vector elements
@cindex vectors, range-checking
@cindex range-checking for vectors
@cindex bounds checking, extension to GCC
@cindex gcc extensions, range-checking
@cindex Fortran range checking, equivalent in gcc

Unlike @sc{fortran} compilers, C compilers do not usually provide
support for range checking of vectors and matrices.  Range checking is
available in the GNU C Compiler bounds-checking extension, but it is not
part of the default installation of GCC.  The functions
@code{gsl_vector_get} and @code{gsl_vector_set} can perform portable
range checking for you and report an error if you attempt to access
elements outside the allowed range.

The functions for accessing the elements of a vector or matrix are
defined in @file{gsl_vector.h} and declared @code{extern inline} to
eliminate function-call overhead.  You must compile your program with
the macro @code{HAVE_INLINE} defined to use these functions.  

If necessary you can turn off range checking completely without
modifying any source files by recompiling your program with the
preprocessor definition @code{GSL_RANGE_CHECK_OFF}.  Provided your
compiler supports inline functions the effect of turning off range
checking is to replace calls to @code{gsl_vector_get(v,i)} by