vectors.texi

用于VC.net的gsl的lib库文件包

calls to @code{gsl_vector_set(v,i,x)} by @code{v->data[i*v->stride]=x}.
Thus there should be no performance penalty for using the range checking
functions when range checking is turned off.

@deftypefun double gsl_vector_get (const gsl_vector * @var{v}, size_t @var{i})
This function returns the @var{i}-th element of a vector @var{v}.  If
@var{i} lies outside the allowed range of 0 to @var{n-1} then the error
handler is invoked and 0 is returned.
@end deftypefun

@deftypefun void gsl_vector_set (gsl_vector * @var{v}, size_t @var{i}, double @var{x})
This function sets the value of the @var{i}-th element of a vector
@var{v} to @var{x}.  If @var{i} lies outside the allowed range of 0 to
@var{n-1} then the error handler is invoked.
@end deftypefun

@deftypefun {double *} gsl_vector_ptr (gsl_vector * @var{v}, size_t @var{i})
@deftypefunx {const double *} gsl_vector_const_ptr (const gsl_vector * @var{v}, size_t @var{i})
These functions return a pointer to the @var{i}-th element of a vector
@var{v}.  If @var{i} lies outside the allowed range of 0 to @var{n-1}
then the error handler is invoked and a null pointer is returned.
@end deftypefun

@node Initializing vector elements
@subsection Initializing vector elements
@cindex vectors, initializing
@cindex initializing vectors

@deftypefun void gsl_vector_set_all (gsl_vector * @var{v}, double @var{x})
This function sets all the elements of the vector @var{v} to the value
@var{x}.
@end deftypefun

@deftypefun void gsl_vector_set_zero (gsl_vector * @var{v})
This function sets all the elements of the vector @var{v} to zero.
@end deftypefun

@deftypefun int gsl_vector_set_basis (gsl_vector * @var{v}, size_t @var{i})
This function makes a basis vector by setting all the elements of the
vector @var{v} to zero except for the @var{i}-th element which is set to
one.
@end deftypefun

@node Reading and writing vectors
@subsection Reading and writing vectors

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

@deftypefun int gsl_vector_fwrite (FILE * @var{stream}, const gsl_vector * @var{v})
This function writes the elements of the vector @var{v} 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_vector_fread (FILE * @var{stream}, gsl_vector * @var{v})
This function reads into the vector @var{v} from the open stream
@var{stream} in binary format.  The vector @var{v} must be preallocated
with the correct length since the function uses the size of @var{v} 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_vector_fprintf (FILE * @var{stream}, const gsl_vector * @var{v}, const char * @var{format})
This function writes the elements of the vector @var{v} 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_vector_fscanf (FILE * @var{stream}, gsl_vector * @var{v})
This function reads formatted data from the stream @var{stream} into the
vector @var{v}.  The vector @var{v} must be preallocated with the correct
length since the function uses the size of @var{v} 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

@node Vector views
@subsection Vector views

In addition to creating vectors from slices of blocks it is also
possible to slice vectors and create vector views.  For example, a
subvector of another vector can be described with a view, or two views
can be made which provide access to the even and odd elements of a
vector.

A vector view is a temporary object, stored on the stack, which can be
used to operate on a subset of vector elements.  Vector views can be
defined for both constant and non-constant vectors, using separate types
that preserve constness.  A vector view has the type
@code{gsl_vector_view} and a constant vector view has the type
@code{gsl_vector_const_view}.  In both cases the elements of the view
can be accessed as a @code{gsl_vector} using the @code{vector} component
of the view object.  A pointer to a vector of type @code{gsl_vector *}
or @code{const gsl_vector *} can be obtained by taking the address of
this component with the @code{&} operator.

@deftypefun gsl_vector_view gsl_vector_subvector (gsl_vector *@var{v}, size_t @var{offset}, size_t @var{n})
@deftypefunx {gsl_vector_const_view} gsl_vector_const_subvector (const gsl_vector * @var{v}, size_t @var{offset}, size_t @var{n})
These functions return a vector view of a subvector of another vector
@var{v}.  The start of the new vector is offset by @var{offset} elements
from the start of the original vector.  The new vector has @var{n}
elements.  Mathematically, the @var{i}-th element of the new vector
@var{v'} is given by,

@example
v'(i) = v->data[(offset + i)*v->stride]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n-1}.

The @code{data} pointer of the returned vector struct is set to null if
the combined parameters (@var{offset},@var{n}) overrun the end of the
original vector.

The new vector is only a view of the block underlying the original
vector, @var{v}.  The block containing the elements of @var{v} is not
owned by the new vector.  When the view goes out of scope the original
vector @var{v} and its block will continue to exist.  The original
memory can only be deallocated by freeing the original vector.  Of
course, the original vector should not be deallocated while the view is
still in use.

The function @code{gsl_vector_const_subvector} is equivalent to
@code{gsl_vector_subvector} but can be used for vectors which are
declared @code{const}.
@end deftypefun


@deftypefun gsl_vector gsl_vector_subvector_with_stride (gsl_vector *@var{v}, size_t @var{offset}, size_t @var{stride}, size_t @var{n})
@deftypefunx {gsl_vector_const_view} gsl_vector_const_subvector_with_stride (const gsl_vector * @var{v}, size_t @var{offset}, size_t @var{stride}, size_t @var{n})
These functions return a vector view of a subvector of another vector
@var{v} with an additional stride argument. The subvector is formed in
the same way as for @code{gsl_vector_subvector} but the new vector has
@var{n} elements with a step-size of @var{stride} from one element to
the next in the original vector.  Mathematically, the @var{i}-th element
of the new vector @var{v'} is given by,

@example
v'(i) = v->data[(offset + i*stride)*v->stride]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n-1}.

Note that subvector views give direct access to the underlying elements
of the original vector. For example, the following code will zero the
even elements of the vector @code{v} of length @code{n}, while leaving the
odd elements untouched,

@example
gsl_vector_view v_even 
  = gsl_vector_subvector_with_stride (v, 0, 2, n/2);
gsl_vector_set_zero (&v_even.vector);
@end example
@noindent
A vector view can be passed to any subroutine which takes a vector
argument just as a directly allocated vector would be, using
@code{&}@var{view}@code{.vector}.  For example, the following code
computes the norm of odd elements of @code{v} using the @sc{blas}
routine @sc{dnrm2},

@example
gsl_vector_view v_odd 
  = gsl_vector_subvector_with_stride (v, 1, 2, n/2);
double r = gsl_blas_dnrm2 (&v_odd.vector);
@end example

The function @code{gsl_vector_const_subvector_with_stride} is equivalent
to @code{gsl_vector_subvector_with_stride} but can be used for vectors
which are declared @code{const}.
@end deftypefun

@deftypefun gsl_vector_view gsl_vector_complex_real (gsl_vector_complex *@var{v})
@deftypefunx {gsl_vector_const_view} gsl_vector_complex_const_real (const gsl_vector_complex *@var{v})
These functions return a vector view of the real parts of the complex
vector @var{v}.

The function @code{gsl_vector_complex_const_real} is equivalent to
@code{gsl_vector_complex_real} but can be used for vectors which are
declared @code{const}.
@end deftypefun

@deftypefun gsl_vector_view gsl_vector_complex_imag (gsl_vector_complex *@var{v})
@deftypefunx {gsl_vector_const_view} gsl_vector_complex_const_imag (const gsl_vector_complex *@var{v})
These functions return a vector view of the imaginary parts of the
complex vector @var{v}.

The function @code{gsl_vector_complex_const_imag} is equivalent to
@code{gsl_vector_complex_imag} but can be used for vectors which are
declared @code{const}.
@end deftypefun

@deftypefun gsl_vector_view gsl_vector_view_array (double *@var{base}, size_t @var{n}) 
@deftypefunx {gsl_vector_const_view} gsl_vector_const_view_array (const double *@var{base}, size_t @var{n})
These functions return a vector view of an array.  The start of the new
vector is given by @var{base} and has @var{n} elements.  Mathematically,
the @var{i}-th element of the new vector @var{v'} is given by,

@example
v'(i) = base[i]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n-1}.

The array containing the elements of @var{v} is not owned by the new
vector view.  When the view goes out of scope the original array will
continue to exist.  The original memory can only be deallocated by
freeing the original pointer @var{base}.  Of course, the original array
should not be deallocated while the view is still in use.

The function @code{gsl_vector_const_view_array} is equivalent to
@code{gsl_vector_view_array} but can be used for arrays which are
declared @code{const}.
@end deftypefun

@deftypefun gsl_vector_view gsl_vector_view_array_with_stride (double * @var{base}, size_t @var{stride}, size_t @var{n})
@deftypefunx gsl_vector_const_view gsl_vector_const_view_array_with_stride (const double * @var{base}, size_t @var{stride}, size_t @var{n})
These functions return a vector view of an array @var{base} with an
additional stride argument. The subvector is formed in the same way as
for @code{gsl_vector_view_array} but the new vector has @var{n} elements
with a step-size of @var{stride} from one element to the next in the
original array.  Mathematically, the @var{i}-th element of the new
vector @var{v'} is given by,

@example
v'(i) = base[i*stride]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n-1}.

Note that the view gives direct access to the underlying elements of the
original array.  A vector view can be passed to any subroutine which
takes a vector argument just as a directly allocated vector would be,
using @code{&}@var{view}@code{.vector}.

The function @code{gsl_vector_const_view_array_with_stride} is
equivalent to @code{gsl_vector_view_array_with_stride} but can be used
for arrays which are declared @code{const}.
@end deftypefun


@comment @node Modifying subvector views
@comment @subsection Modifying subvector views
@comment 
@comment @deftypefun int gsl_vector_view_from_vector (gsl_vector *@var{v}, gsl_vector *@var{base}, size_t @var{offset}, size_t @var{n}, size_t @var{stride})
@comment This function modifies and existing vector view @var{v} to form a new
@comment view of a vector @var{base}, starting from element @var{offset}.  The
@comment vector has @var{n} elements separated by stride @var{stride}.  Any
@comment existing view in @var{v} will be lost as a result of this function.
@comment @end deftypefun
@comment 
@comment @deftypefun int gsl_vector_view_from_array (gsl_vector *@var{v}, double *@var{base}, size_t @var{offset}, size_t @var{n}, size_t @var{stride})
@comment This function modifies and existing vector view @var{v} to form a new
@comment view of an array @var{base}, starting from element @var{offset}.  The
@comment vector has @var{n} elements separated by stride @var{stride}.  Any
@comment existing view in @var{v} will be lost as a result of this function.
@comment @end deftypefun

@comment @deftypefun {gsl_vector *} gsl_vector_alloc_from_block (gsl_block * @var{b}, size_t @var{offset}, size_t @var{n}, size_t @var{stride})
@comment This function creates a vector as a slice of an existing block @var{b},
@comment returning a pointer to a newly initialized vector struct.  The start of
@comment the vector is offset by @var{offset} elements from the start of the
@comment block.  The vector has @var{n} elements, with a step-size of @var{stride}
@comment from one element to the next.  Mathematically, the @var{i}-th element of
@comment the vector is given by,
@comment 
@comment @example
@comment v(i) = b->data[offset + i*stride]
@comment @end example
@comment @noindent
@comment where the index @var{i} runs from 0 to @code{n-1}.
@comment 
@comment A null pointer is returned if the combined parameters
@comment (@var{offset},@var{n},@var{stride}) overrun the end of the block or if
@comment insufficient memory is available to store the vector.
@comment 
@comment The vector is only a view of the block @var{b}, and the block is not
@comment owned by the vector.  When the vector is deallocated the block @var{b}
@comment will continue to exist.  This memory can only be deallocated by freeing
@comment the block itself.  Of course, this block should not be deallocated while
@comment the vector is still in use.
@comment @end deftypefun
@comment