Robot Control Library

Functions for vector manipulation.
The small rc_vector_t struct contains information about the vector's size and a pointer to where dynamically allocated memory exists that stores the actual data for the vector. Use rc_vector_alloc to dynamically allocate memory for each new vector. Then use rc_vector_free() and to free the memory when you are done using it. See the remaining vector, matrix, and linear algebra functions for more details.
Data Structures  
struct  rc_vector_t 
Struct containing the state of a vector and a pointer to dynamically allocated memory to hold its contents. More...  
Macros  
#define  RC_VECTOR_INITIALIZER 
Typedefs  
typedef struct rc_vector_t  rc_vector_t 
Struct containing the state of a vector and a pointer to dynamically allocated memory to hold its contents. More...  
Functions  
rc_vector_t  rc_vector_empty (void) 
Returns an rc_vector_t with no allocated memory and the initialized flag set to 0. More...  
int  rc_vector_alloc (rc_vector_t *v, int length) 
Allocates memory for vector v to have specified length. More...  
int  rc_vector_free (rc_vector_t *v) 
Frees the memory allocated for vector v. More...  
int  rc_vector_zeros (rc_vector_t *v, int length) 
Resizes vector v and fills with zeros. More...  
int  rc_vector_ones (rc_vector_t *v, int length) 
Resizes vector v and fills with ones. More...  
int  rc_vector_random (rc_vector_t *v, int length) 
Resizes vector v and fills with random numbers between 1.0 and 1.0. More...  
int  rc_vector_fibonnaci (rc_vector_t *v, int length) 
Resizes vector v and fills with Fibonnaci sequence. More...  
int  rc_vector_from_array (rc_vector_t *v, double *ptr, int length) 
Resizes vector v and populates with values from specified array ptr. More...  
int  rc_vector_duplicate (rc_vector_t a, rc_vector_t *b) 
Duplicates the contents of vector a and into a new vector b. More...  
int  rc_vector_print (rc_vector_t v) 
Prints to stdout the contents of vector v in one line. More...  
int  rc_vector_print_sci (rc_vector_t v) 
Prints to stdout the contents of vector v in one line. More...  
int  rc_vector_zero_out (rc_vector_t *v) 
Sets all values of an alreadyallocated vector to 0. More...  
int  rc_vector_times_scalar (rc_vector_t *v, double s) 
Multiplies every entry in vector v by scalar s. More...  
double  rc_vector_norm (rc_vector_t v, double p) 
Returns the vector norm defined by sum(abs(v)^p)^(1/p), where p is any positive real value. More...  
int  rc_vector_max (rc_vector_t v) 
Returns the index of the maximum value in v. More...  
int  rc_vector_min (rc_vector_t v) 
Returns the index of the minimum value in v. More...  
double  rc_vector_std_dev (rc_vector_t v) 
Returns the standard deviation of the values in a vector. More...  
double  rc_vector_mean (rc_vector_t v) 
Returns the mean (average) of all values in vector v or 1.0f on error. More...  
int  rc_vector_projection (rc_vector_t v, rc_vector_t e, rc_vector_t *p) 
Populates vector p with the projection of vector v onto e. More...  
double  rc_vector_dot_product (rc_vector_t v1, rc_vector_t v2) 
Calculates the dot product of two equallength vectors. More...  
int  rc_vector_cross_product (rc_vector_t v1, rc_vector_t v2, rc_vector_t *p) 
Computes the crossproduct of two vectors, each of length 3. More...  
int  rc_vector_sum (rc_vector_t v1, rc_vector_t v2, rc_vector_t *s) 
Populates vector s with the sum of vectors v1 and v2. More...  
int  rc_vector_sum_inplace (rc_vector_t *v1, rc_vector_t v2) 
Adds vector v2 to v1 and leaves the result in v1. More...  
int  rc_vector_subtract (rc_vector_t v1, rc_vector_t v2, rc_vector_t *s) 
Populates vector s with the difference v1  v2. More...  
Variables  
double  zero_tolerance 
#define RC_VECTOR_INITIALIZER 
rc_vector_t rc_vector_empty  (  void  ) 
Returns an rc_vector_t with no allocated memory and the initialized flag set to 0.
This is essential for initializing vectors when they are declared since local variables declared in a function without global variable scope in C are not guaranteed to be zeroed out which can lead to bad memory pointers and segfaults if not handled carefully. We recommend initializing all vectors with this function before using rc_vector_alloc or any other function.
int rc_vector_alloc  (  rc_vector_t *  v, 
int  length  
) 
Allocates memory for vector v to have specified length.
If v is initially the right length then nothing is done and the data in v is preserved. If v is uninitialized or of the wrong length then any existing memory is freed and new memory is allocated, helping to prevent accidental memory leaks.
The contents of the new vector is not guaranteed to be anything in particular as it is allocated with malloc. Use rc_vector_zeros or rc_vector_ones if you require known starting values.
Returns 0 if successful, otherwise returns 1. Will only be unsuccessful if length is invalid or there is insufficient memory available.
v  Pointer to user's rc_vector_t struct  
[in]  length  Length of vector to allocate memory for 
int rc_vector_free  (  rc_vector_t *  v  ) 
Frees the memory allocated for vector v.
Also sets the length and initialized flag of the rc_vector_t struct to 0 to indicate to other functions that v no longer points to allocated memory and cannot be used until more memory is allocated such as with rc_vector_alloc or rc_vector_zeros. Returns 0 on success. Will only fail and return 1 if it is passed a NULL pointer.
v  Pointer to user's rc_vector_t struct 
int rc_vector_zeros  (  rc_vector_t *  v, 
int  length  
) 
Resizes vector v and fills with zeros.
uses calloc to allocate new memory. Any existing memory allocated for v is freed if necessary to avoid memory leaks. It is not necessary to call rc_alloc_vector before this.
v  Pointer to user's rc_vector_t struct  
[in]  length  Length of vector to allocate memory for 
int rc_vector_ones  (  rc_vector_t *  v, 
int  length  
) 
Resizes vector v and fills with ones.
Any existing memory allocated for v is freed if necessary to avoid memory leaks. It is not necessary to call rc_alloc_vector before this.
v  Pointer to user's rc_vector_t struct  
[in]  length  Length of vector to allocate memory for 
int rc_vector_random  (  rc_vector_t *  v, 
int  length  
) 
Resizes vector v and fills with random numbers between 1.0 and 1.0.
Any existing memory allocated for v is freed if necessary to avoid memory leaks. It is not necessary to call rc_alloc_vector before this.
v  Pointer to user's rc_vector_t struct  
[in]  length  Length of vector to allocate memory for 
int rc_vector_fibonnaci  (  rc_vector_t *  v, 
int  length  
) 
Resizes vector v and fills with Fibonnaci sequence.
Any existing memory allocated for v is freed if necessary to avoid memory leaks. It is not necessary to call rc_alloc_vector before this.
v  Pointer to user's rc_vector_t struct  
[in]  length  Length of vector to allocate memory for 
int rc_vector_from_array  (  rc_vector_t *  v, 
double *  ptr,  
int  length  
) 
Resizes vector v and populates with values from specified array ptr.
Any existing memory allocated for v is freed if necessary to avoid memory leaks. It is not necessary to call rc_alloc_vector before this. This is generally used when the user has an existing array of data and wants to use it with other math functions.
v  Pointer to user's rc_vector_t struct  
[in]  ptr  pointer to array to read values from 
[in]  length  Length of vector to allocate memory for 
int rc_vector_duplicate  (  rc_vector_t  a, 
rc_vector_t *  b  
) 
Duplicates the contents of vector a and into a new vector b.
Simply making a copy of an rc_vector_t struct is not sufficient as the rc_vector_t struct simply contains a pointer to the memory allocated to contain the contents of the vector. rc_vector_duplicate sets b to be a new rc_vector_t with a pointer to freshlyallocated memory.
[in]  a  Vector to be duplicated 
b  pointer to new vector to be allocated and written 
int rc_vector_print  (  rc_vector_t  v  ) 
Prints to stdout the contents of vector v in one line.
This is not advisable for extremely long vectors but serves for quickly debugging or printing results. It prints 4 decimal places with padding for a sign. We recommend rc_vector_print_sci() for very small or very large numbers where scientific notation would be more appropriate.
[in]  v  Pointer to user's rc_vector_t struct 
int rc_vector_print_sci  (  rc_vector_t  v  ) 
Prints to stdout the contents of vector v in one line.
Like rc_vector_print but prints with scientific notation. This is not advisable for extremely long vectors but serves for quickly debugging or printing.
[in]  v  Pointer to user's rc_vector_t struct 
int rc_vector_zero_out  (  rc_vector_t *  v  ) 
Sets all values of an alreadyallocated vector to 0.
v  pointer to vector to be zero'd out 
int rc_vector_times_scalar  (  rc_vector_t *  v, 
double  s  
) 
Multiplies every entry in vector v by scalar s.
It is not strictly necessary for v to be provided as a pointer since a copy of the struct v would also contain the correct pointer to the original vector's allocated memory. However, in this library we use the convention of passing an rc_vector_t struct or rc_matrix_struct as a pointer when its data is to be modified by the function, and as a normal argument when it is only to be read by the function.
v  Pointer to user's rc_vector_t struct  
[in]  s  scalar multiplier 
double rc_vector_norm  (  rc_vector_t  v, 
double  p  
) 
Returns the vector norm defined by sum(abs(v)^p)^(1/p), where p is any positive real value.
Just like the matlab norm(v,p) function.
Most common norms are the 1 norm which gives the sum of absolute values of the vector and the 2norm which is the square root of sum of squares. for infinity and infinity norms see rc_vector_max and rc_vector_min
[in]  v  User's vector struct 
[in]  p  Which norm to use. Positive real values only. 
int rc_vector_max  (  rc_vector_t  v  ) 
Returns the index of the maximum value in v.
The value contained in the returned index is the equivalent to the infinity norm. If the max value occurs multiple times then the index of the first instance is returned.
[in]  v  User's vector struct 
int rc_vector_min  (  rc_vector_t  v  ) 
Returns the index of the minimum value in v.
The value contained in the returned index is the equivalent to the infinity norm. If the minimum value occurs multiple times then the index of the first instance is returned.
[in]  v  User's vector struct 
double rc_vector_std_dev  (  rc_vector_t  v  ) 
Returns the standard deviation of the values in a vector.
[in]  v  User's vector struct 
double rc_vector_mean  (  rc_vector_t  v  ) 
Returns the mean (average) of all values in vector v or 1.0f on error.
[in]  v  User's vector struct 
int rc_vector_projection  (  rc_vector_t  v, 
rc_vector_t  e,  
rc_vector_t *  p  
) 
Populates vector p with the projection of vector v onto e.
p is resized appropriately and any exising memory is freed to avoid memory leaks.
[in]  v  User's vector struct 
[in]  e  User's vector struct 
[out]  p  output 
double rc_vector_dot_product  (  rc_vector_t  v1, 
rc_vector_t  v2  
) 
Calculates the dot product of two equallength vectors.
[in]  v1  User's vector struct 
[in]  v2  User's vector struct 
int rc_vector_cross_product  (  rc_vector_t  v1, 
rc_vector_t  v2,  
rc_vector_t *  p  
) 
Computes the crossproduct of two vectors, each of length 3.
The result is placed in vector p and and any existing memory used by p is freed to avoid memory leaks.
[in]  v1  User's vector struct 
[in]  v2  User's vector struct 
[out]  p  resulting cross product 
int rc_vector_sum  (  rc_vector_t  v1, 
rc_vector_t  v2,  
rc_vector_t *  s  
) 
Populates vector s with the sum of vectors v1 and v2.
v1 and v2 must be of the same length. Any existing memory allocated for s is freed and lost, new memory is allocated if necessary.
[in]  v1  User's vector struct 
[in]  v2  User's vector struct 
[out]  s  output sum 
int rc_vector_sum_inplace  (  rc_vector_t *  v1, 
rc_vector_t  v2  
) 
Adds vector v2 to v1 and leaves the result in v1.
The original contents of v1 are lost and v2 is left untouched. v1 and v2 must be of the same length.
v1  User's vector struct, holds the result  
[in]  v2  User's vector struct 
int rc_vector_subtract  (  rc_vector_t  v1, 
rc_vector_t  v2,  
rc_vector_t *  s  
) 
Populates vector s with the difference v1  v2.
v1 and v2 must be of the same length. Any existing memory allocated for s is freed and lost, new memory is allocated if necessary.
[in]  v1  User's vector struct 
[in]  v2  User's vector struct 
[out]  s  output difference v1v2 
double zero_tolerance 