vector.h File Reference

File for generic vector functions. More...

#include <iostream>
#include <cmath>
#include <string>
#include <fstream>
#include <sstream>
#include <o2scl/err_hnd.h>
#include <gsl/gsl_ieee_utils.h>
#include <gsl/gsl_sort.h>

Go to the source code of this file.


Detailed Description

This file contains a set of template functions which can be applied to almost any vector or matrix type which allow element access through operator[]. Detailed requirements on the template parameters are given in the functions below.

For a general discussion of vectors and matrices in O2scl , see the Arrays, Vectors, Matrices and Tensors of the User's Guide.

For overloaded arithmetic operators involving vectors and matrices, see vec_arith.h . For statistics operations not included here, see vec_stats.h in the directory src/other . For assorted functions and classes which are specific to C-style arrays, see array.h . Also related are the matrix output functions, matrix_out(), matrix_cx_out_paren(), and matrix_out_paren() which are defined in columnify.h because they utilize the class columnify to format the output.

For functions which search for a value in an ordered (either increasing or decreasing) vector, see the class search_vec .

Idea for future:
Create a matrix transpose copy function?

Definition in file vector.h.


Data Structures

class  matrix_row
 Create a vector-like class from a row of a matrix. More...

Functions

Copying functions
template<class vec_t , class vec2_t >
void vector_copy (size_t N, vec_t &src, vec2_t &dest)
 Naive vector copy.
template<class mat_t , class mat2_t >
void matrix_copy (size_t M, size_t N, mat_t &src, mat2_t &dest)
 Naive matrix copy.
template<class vec_t , class vec2_t >
void vector_cx_copy_gsl (size_t N, vec_t &src, vec2_t &dest)
 GSL complex vector copy.
template<class mat_t , class mat2_t >
void matrix_cx_copy_gsl (size_t M, size_t N, mat_t &src, mat2_t &dest)
 GSL complex matrix copy.
Sorting functions
template<class vec_t , class data_t >
void sort_downheap (vec_t &data, size_t n, size_t k)
 Provide a downheap() function for vector_sort().
template<class vec_t , class data_t >
int vector_sort (size_t n, vec_t &data)
 Sort a vector (in increasing order).
template<class vec_t , class vec_size_t >
int sort_index_downheap (size_t N, const vec_t &data, vec_size_t &order, size_t k)
 Provide a downheap() function for vector_sort_index().
template<class vec_t , class vec_size_t >
int vector_sort_index (size_t n, const vec_t &data, vec_size_t &order)
 Create a permutation which sorts a vector (in increasing order).
template<class vec_t >
int vector_sort_double (size_t n, vec_t &data)
 Sort a vector of doubles (in increasing order).
Smallest and largest functions
template<class vec_t , class data_t >
int vector_smallest (size_t n, vec_t &data, size_t k, vec_t &smallest)
 Find the k smallest entries of a vector.
template<class vec_t , class data_t >
int vector_largest (size_t n, vec_t &data, size_t k, vec_t &largest)
 Find the k largest entries of a vector.
Vector minimum and maximum functions
template<class vec_t , class data_t >
data_t vector_max (size_t n, const vec_t &data)
 Compute the maximum of the first n elements of a vector.
template<class vec_t , class data_t >
data_t vector_min (size_t n, const vec_t &data)
 Compute the minimum of the first n elements of a vector.
template<class vec_t , class data_t >
int vector_minmax (size_t n, vec_t &data, data_t &min, data_t &max)
 Compute the minimum and maximum of the first n elements of a vector.
Matrix minimum and maximum functions
template<class mat_t , class data_t >
data_t matrix_max (size_t n, const size_t m, const mat_t &data)
 Compute the maximum of a matrix.
template<class mat_t , class data_t >
data_t matrix_min (size_t n, const size_t m, const mat_t &data)
 Compute the minimum of a matrix.
template<class mat_t , class data_t >
int matrix_minmax (size_t n, const size_t m, const mat_t &data, data_t &min, data_t &max)
 Compute the minimum and maximum of a matrix.
Vector minimum and maximum functions returning an index
template<class vec_t , class data_t >
size_t vector_max_index (size_t n, vec_t &data, data_t &max)
 Compute the maximum of the first n elements of a vector.
template<class vec_t , class data_t >
int vector_min_index (size_t n, vec_t &data, data_t &min)
 Compute the minimum of the first n elements of a vector.
template<class vec_t , class data_t >
int vector_minmax_index (size_t n, vec_t &data, data_t &min, size_t &ix, data_t &max, size_t &ix2)
 Compute the minimum and maximum of the first n elements of a vector.
Searching functions
template<class vec_t >
size_t vector_lookup (size_t n, const vec_t &x, double x0)
 Lookup element x0 in vector x of length n.
template<class vec_t , class data_t >
size_t vector_bsearch_inc (const data_t x0, const vec_t &x, size_t lo, size_t hi)
 Binary search a part of an increasing vector for x0.
template<class vec_t , class data_t >
size_t vector_bsearch_dec (const data_t x0, const vec_t &x, size_t lo, size_t hi)
 Binary search a part of an decreasing vector for x0.
Miscellaneous mathematical functions
template<class vec_t , class data_t >
data_t vector_sum (size_t n, vec_t &data)
 Compute the sum of the first n elements of a vector.
template<class vec_t , class data_t >
data_t vector_norm (size_t n, const vec_t &x)
 Compute the norm of a vector of floating-point (single or double precision) numbers.
Other functions
template<class vec_t , class data_t >
int vector_rotate (size_t n, vec_t &data, size_t k)
 "Rotate" a vector so that the kth element is now the beginning
template<class vec_t , class data_t >
int vector_reverse (size_t n, vec_t &data)
 Reverse a vector.
template<class vec_t >
int vector_out (std::ostream &os, size_t n, vec_t &v, bool endline=false)
 Output a vector to a stream.

Function Documentation

void matrix_copy ( size_t  M,
size_t  N,
mat_t &  src,
mat2_t &  dest 
) [inline]

Note:
This ordering is reversed from the GSL function gsl_matrix_memcpy(). This is to be used with
      matrix_copy(N,source,destination);
instead of
      gsl_matrix_memcpy(destination,source);
It is assumed that the memory allocation for dest has already been performed.

This function will work for any class vec2_t which has an operator[][] which returns a reference to the corresponding element and class vec_t with an operator[][] which returns either a reference or the value of the corresponding element.

Definition at line 117 of file vector.h.

void matrix_cx_copy_gsl ( size_t  M,
size_t  N,
mat_t &  src,
mat2_t &  dest 
) [inline]

Idea for future:
At present this works only with complex types based directly on the GSL complex format. This could be improved.

Definition at line 146 of file vector.h.

size_t vector_bsearch_dec ( const data_t  x0,
const vec_t &  x,
size_t  lo,
size_t  hi 
) [inline]

This function performs a binary search of between x[lo] and x[hi] (inclusive). It returns

  • lo if x0 > x[lo]
  • i if x[i] >= x0 > x[i+1] for lo <= i < hi
  • hi-1 if x0 <= x[hi-1]

The element at x[hi] is never referenced by this function. The parameter hi can be either the last element in the vector, or one element past the last element of the vector, depending on whether or not the user wants the function to return the index of the last element.

The operation of this function is undefined if the data is not strictly monotonic, i.e. if some of the data elements are equal.

This function will call the error handler if lo is greater than hi.

Definition at line 807 of file vector.h.

size_t vector_bsearch_inc ( const data_t  x0,
const vec_t &  x,
size_t  lo,
size_t  hi 
) [inline]

This function performs a binary search of between x[lo] and x[hi]. It returns

  • lo if x0 < x[lo]
  • i if x[i] <= x0 < x[i+1] for lo <= i < hi
  • hi-1 if x0 >= x[hi-1]

The element at x[hi] is never referenced by this function. The parameter hi can be either the last element in the vector, or one element past the last element of the vector, depending on whether or not the user wants the function to return the index of the last element.

This function operates in the same way as gsl_interp_bsearch().

The operation of this function is undefined if the data is not strictly monotonic, i.e. if some of the data elements are equal.

This function will call the error handler if lo is greater than hi.

Definition at line 764 of file vector.h.

void vector_copy ( size_t  N,
vec_t &  src,
vec2_t &  dest 
) [inline]

Note:
This ordering is reversed from the GSL function gsl_vector_memcpy(). This is to be used with
      vector_copy(N,source,destination);
instead of
      gsl_vector_memcpy(destination,source);
It is assumed that the memory allocation for dest has already been performed.

This function will work for any class vec2_t which has an operator[] which returns a reference to the corresponding element and class vec_t with an operator[] which returns either a reference or the value of the corresponding element.

Definition at line 90 of file vector.h.

void vector_cx_copy_gsl ( size_t  N,
vec_t &  src,
vec2_t &  dest 
) [inline]

Idea for future:
At present this works only with complex types based directly on the GSL complex format. This could be improved.

Definition at line 132 of file vector.h.

int vector_largest ( size_t  n,
vec_t &  data,
size_t  k,
vec_t &  largest 
) [inline]

Given a vector data of size n this sets the first k entries of the vector largest to the k largest entries from vector data in descending order. The vector largest must be allocated beforehand to hold at least k elements.

This works similarly to the GSL function gsl_sort_largest().

Note:
This $ {\cal O}(k N) $ algorithm is useful only when $ k << N $.
If k is zero, then this function does nothing and returns gsl_success .

Definition at line 432 of file vector.h.

size_t vector_lookup ( size_t  n,
const vec_t &  x,
double  x0 
) [inline]

This function finds the element in vector x which is closest to x0. It ignores all elements in x which are not finite. If the vector is empty, or if all of the elements in x are not finite, then the error handler will be called.

This function works for all classes vec_t where an operator[] is defined which returns a double (either as a value or a reference).

Definition at line 712 of file vector.h.

data_t vector_norm ( size_t  n,
const vec_t &  x 
) [inline]

This function is a more generic version of o2scl_cblas::dnrm2 .

Definition at line 851 of file vector.h.

int vector_out ( std::ostream &  os,
size_t  n,
vec_t &  v,
bool  endline = false 
) [inline]

No trailing space is output after the last element, and an endline is output only if endline is set to true. If the parameter n is zero, this function silently does nothing.

Note that the O2scl vector classes also have their own operator<<() defined for them.

This works with any class vec_t which has an operator[] which returns either the value of or a reference to the ith element and the element type has its own output operator which has been defined.

Definition at line 942 of file vector.h.

int vector_reverse ( size_t  n,
vec_t &  data 
) [inline]

If n is zero, this function will silenly do nothing.

Definition at line 915 of file vector.h.

int vector_rotate ( size_t  n,
vec_t &  data,
size_t  k 
) [inline]

This is a generic template function which will work for any types data_t and vec_t for which

  • data_t has an operator=
  • vec_t::operator[] returns a reference to an object of type data_t

This function is used, for example, in pinside.

Definition at line 896 of file vector.h.

int vector_smallest ( size_t  n,
vec_t &  data,
size_t  k,
vec_t &  smallest 
) [inline]

Given a vector data of size n this sets the first k entries of the vector smallest to the k smallest entries from vector data in ascending order. The vector smallest must be allocated beforehand to hold at least k elements.

This works similarly to the GSL function gsl_sort_smallest().

Note:
This $ {\cal O}(k N) $ algorithm is useful only when $ k << N $.
If k is zero, then this function does nothing and returns gsl_success .

Definition at line 385 of file vector.h.

int vector_sort ( size_t  n,
vec_t &  data 
) [inline]

This is a generic sorting template function using a heapsort algorithm. It will work for any types data_t and vec_t for which

  • data_t has a non-const version of operator=
  • data_t has a less than operator to compare elements
  • vec_t::operator[] returns a non-const reference to an object of type data_t

In particular, it will work with ovector, uvector, ovector_int, uvector_int (and other related O2scl vector classes), the STL template class std::vector, and arrays and pointers of numeric, character, and string objects.

For example,

      std::string list[3]={"dog","cat","fox"};
      vector_sort<std::string[3],std::string>(3,list);

Note:
With this function template alone, the user cannot avoid explicitly specifying the template types for this function because there is no parameter of type data_t, and function templates cannot handle default template types. For this reason, the function template vector_sort_double() was also created which provides the convenience of not requiring the user to specify the vector template type.

This sorting routine is not stable, i.e. equal elements have arbtrary final ordering

This works similarly to the GSL function gsl_sort_vector().

Definition at line 215 of file vector.h.

int vector_sort_double ( size_t  n,
vec_t &  data 
) [inline]

This function is just a wrapper for

      vector_sort<vec_t,double>(n,data);
See the documentation of vector_sort() for more details.

Definition at line 362 of file vector.h.

int vector_sort_index ( size_t  n,
const vec_t &  data,
vec_size_t &  order 
) [inline]

This function takes a vector data and arranges a list of indices in order, which give a sorted version of the vector. The value order[i] gives the index of entry in in data which corresponds to the ith value in the sorted vector. The vector data is unchanged by this function, and the initial values in order are ignored. Before calling this function, order must already be allocated as a vector of size n.

For example, after calling this function, a sorted version the vector can be output with

      size_t n=5;
      double data[5]={3.1,4.1,5.9,2.6,3.5};
      permutation order(n);
      vector_sort_index(n,data,order);
      for(size_t i=0;i<n;i++) {
        cout << data[order[i]] << endl;
      }

To create a permutation which stores as its ith element, the index of data[i] in the sorted vector, you can invert the permutation created by this function.

This is a generic sorting template function. It will work for any types vec_t and vec_size_t for which

  • vec_t has an operator[], and
  • vec_size_t has an operator[] which returns a size_t . One possible type for vec_size_t is permutation.

This works similarly to the GSL function gsl_sort_index().

Definition at line 309 of file vector.h.

data_t vector_sum ( size_t  n,
vec_t &  data 
) [inline]

If n is zero, this will set sum to zero and return gsl_success.

Definition at line 835 of file vector.h.


Documentation generated with Doxygen and provided under the GNU Free Documentation License. See License Information for details.

Project hosting provided by SourceForge.net Logo, O2scl Sourceforge Project Page