@cindex vectors
@cindex matrices

@menu
* Initialization::
* Vectors::
* Matrices::
* Freeing objects::
@end menu

@node Initialization
@section Initialization

Since array processing is one of the strengths of Fortran, FGSL here
focuses not on implementation of the GSL interface, but instead on
leveraging Fortran-style array processing for those GSL routines which
require arguments of type @code{fgsl_vector} or @code{fgsl_matrix}.
Initialization of a vector or matrix object is performed using one of the
generic calls

@example
  type(fgsl_[vector|matrix]) fgsl_[vector|matrix]_init(type)
    [real|integer|character](...), intent(in) :: type
  end function fgsl_vector_init
@end example
@noindent Note that for now only @code{real(fgsl_double)} is
supported.


@node Vectors
@section Vectors

A slice (@code{size} elements starting at @code{offset} going on with
stride @code{stride}) of a rank 1 array with the @code{target} attribute
can be mapped into an object of type @code{fgsl_vector} by calling
@example
  integer (fgsl_int) function fgsl_vector_align(array, len, fvec, &
                              &                 size, offset, stride)
    integer(fgsl_size_t), intent(in) :: len, size, offset, stride
    real(fgsl_double), dimension(len), target, intent(in) :: array
    type(fgsl_vector), intent(inout) :: fvec
  end function fgsl_vector_align
@end example
@noindent If access to the array slice is subsequently needed (for example, for
a dummy object within the procedure it is defined for), a Fortran pointer
can be made to point at it:
@example
  integer (fgsl_int) function fgsl_vector_align(ptr, fvec)
    [real|integer|character](...), pointer, intent(out) :: ptr(:)
    type(fgsl_vector), intent(in) :: fvec
  end function fgsl_vector_align
@end example
@noindent Note that objects of type @code{gsl_vector} which are returned by GSL
routines often are persistent subobjects of other GSL objects. A Fortran
pointer aligned with a subobject hence will remain up-to-date
throughout the lifetime of the object; it may become undefined once
the object ceases to exist. Furthermore, the assignment operator has
been overloaded to enable copying of the content of a
@code{gsl_vector} into a Fortran array.

@node Matrices
@section Matrices

A matrix object can be aligned with a Fortran rank 2 array
with the @code{target} attribute by calling
@example
  integer(fgsl_int) function fgsl_matrix_align(array, lda, n, m, fmat)
    integer(fgsl_size_t), intent(in) :: lda, n, m
    real(fgsl_double), dimension(lda, m), target, intent(in) :: array
    type(fgsl_matrix), intent(inout) :: fmat
  end function fgsl_matrix_align
@end example
@noindent A Fortran pointer to a two-dimensional array can be made to point at a 
@code{fgsl_matrix} object by calling
@example
  integer(fgsl_int) function fgsl_matrix_align(ptr, fmat)
    real(fgsl_double), pointer, intent(out) :: ptr(:,:)
    type(fgsl_matrix), intent(in) :: fmat
  end function fgsl_matrix_align
@end example
@noindent Again, the assignment operator has
been overloaded to enable copying of the content of a
@code{gsl_matrix} into a Fortran array of rank 2.

@node Freeing objects
@section Freeing objects

Once an object of type @code{fgsl_vector} or @code{fgsl_matrix} is not
needed any more, it can be deallocated by calling the subroutines
@code{fgsl_vector_free} or @code{fgsl_matrix_free},
respectively. These
take the object to be allocated as their only argument. A function object
returned by a GSL routine should not be deallocated using one of these
routines.
