Object-oriented Scientific Computing Library: Version 0.910
Data Structures | Functions
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 <o2scl/uniform_grid.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?
Idea for Future:
Create matrix swap row and column functions

Definition in file vector.h.

Data Structures

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

Functions

template<class vec_t , class data_t >
void vector_grid (uniform_grid< data_t > g, vec_t &v)
 Fill a vector with a specified grid.
Copying functions
template<class vec_t , class vec2_t >
void vector_copy (size_t N, vec_t &src, vec2_t &dest)
 Simple vector copy.
template<class vec_t , class vec2_t , class base_t >
void vector_swap (size_t N, vec_t &v1, vec2_t &v2)
 Generic vector swap.
template<class mat_t , class mat2_t >
void matrix_copy (size_t M, size_t N, mat_t &src, mat2_t &dest)
 Simple 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_value (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 >
size_t vector_max_index (size_t n, const vec_t &data)
 Compute the index which holds the maximum of the first n elements of a vector.
template<class vec_t , class data_t >
void vector_max (size_t n, const vec_t &data, size_t &index, data_t &val)
 Compute the maximum of the first n elements of a vector.
template<class vec_t , class data_t >
data_t vector_min_value (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 >
size_t vector_min_index (size_t n, const vec_t &data)
 Compute the index which holds the minimum of the first n elements of a vector.
template<class vec_t , class data_t >
void vector_min (size_t n, const vec_t &data, size_t &index, data_t &val)
 Compute the minimum of the first n elements of a vector.
template<class vec_t , class data_t >
void vector_minmax_value (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.
template<class vec_t , class data_t >
void vector_minmax_index (size_t n, vec_t &data, size_t &ix_min, size_t &ix_max)
 Compute the minimum and maximum of the first n elements of a vector.
template<class vec_t , class data_t >
void vector_minmax (size_t n, vec_t &data, size_t &ix_min, data_t &min, size_t &ix_max, 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.
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.
template<class vec_t , class data_t >
size_t vector_bsearch (const data_t x0, const vec_t &x, size_t lo, size_t hi)
 Binary search a part of a monotonic 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, const vec_t &v, bool endline=false)
 Output a vector to a stream.

Function Documentation

template<class vec_t , class vec2_t >
void vector_copy ( size_t  N,
vec_t &  src,
vec2_t &  dest 
)
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.

template<class vec_t , class vec2_t , class base_t >
void vector_swap ( size_t  N,
vec_t &  v1,
vec2_t &  v2 
)

This function swaps the elements of v1 and v2, one element at a time.

Definition at line 110 of file vector.h.

template<class mat_t , class mat2_t >
void matrix_copy ( size_t  M,
size_t  N,
mat_t &  src,
mat2_t &  dest 
)
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 157 of file vector.h.

template<class vec_t , class vec2_t >
void vector_cx_copy_gsl ( size_t  N,
vec_t &  src,
vec2_t &  dest 
)
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 171 of file vector.h.

template<class mat_t , class mat2_t >
void matrix_cx_copy_gsl ( size_t  M,
size_t  N,
mat_t &  src,
mat2_t &  dest 
)
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 184 of file vector.h.

template<class vec_t , class data_t >
int vector_sort ( size_t  n,
vec_t &  data 
)

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 251 of file vector.h.

template<class vec_t , class vec_size_t >
int vector_sort_index ( size_t  n,
const vec_t &  data,
vec_size_t &  order 
)

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 344 of file vector.h.

template<class vec_t >
int vector_sort_double ( size_t  n,
vec_t &  data 
)

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 396 of file vector.h.

template<class vec_t , class data_t >
int vector_smallest ( size_t  n,
vec_t &  data,
size_t  k,
vec_t &  smallest 
)

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 419 of file vector.h.

template<class vec_t , class data_t >
int vector_largest ( size_t  n,
vec_t &  data,
size_t  k,
vec_t &  largest 
)

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 466 of file vector.h.

template<class mat_t , class data_t >
data_t matrix_max ( size_t  n,
const size_t  m,
const mat_t &  data 
)
Idea for Future:
Write matrix_max_index() and related functions similar to the way vector_max_index() works.

Definition at line 701 of file vector.h.

template<class vec_t >
size_t vector_lookup ( size_t  n,
const vec_t &  x,
double  x0 
)

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 (i.e. n is zero), 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).

Idea for Future:
Write matrix_lookup().

Definition at line 820 of file vector.h.

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 
)

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+2] 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 index of the last element (e.g. n-1 for a vector of size n with starting index 0), or the index of one element (e.g. n for a vector of size n and a starting index 0) for a depending on whether or not the user wants to allow 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 874 of file vector.h.

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 
)

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 index of the last element (e.g. n-1 for a vector of size n with starting index 0), or the index of one element (e.g. n for a vector of size n and a starting index 0) for a depending on whether or not the user wants to allow 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 919 of file vector.h.

template<class vec_t , class data_t >
size_t vector_bsearch ( const data_t  x0,
const vec_t &  x,
size_t  lo,
size_t  hi 
)

This wrapper just calls vector_bsearch_inc() or vector_bsearch_dec() depending on the ordering of x.

Definition at line 945 of file vector.h.

template<class vec_t , class data_t >
data_t vector_sum ( size_t  n,
vec_t &  data 
)

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

Definition at line 962 of file vector.h.

template<class vec_t , class data_t >
data_t vector_norm ( size_t  n,
const vec_t &  x 
)

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

Definition at line 978 of file vector.h.

template<class vec_t , class data_t >
int vector_rotate ( size_t  n,
vec_t &  data,
size_t  k 
)

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.

Note:
This function is not the same as a Givens rotation, which is typically referred to in BLAS routines as drot().

Definition at line 1025 of file vector.h.

template<class vec_t , class data_t >
int vector_reverse ( size_t  n,
vec_t &  data 
)

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

Definition at line 1044 of file vector.h.

template<class vec_t >
int vector_out ( std::ostream &  os,
size_t  n,
const vec_t &  v,
bool  endline = false 
)

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 1070 of file vector.h.

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).

Get Object-oriented Scientific Computing
Lib at SourceForge.net. Fast, secure and Free Open Source software
downloads.