Simbody  3.6
SimTK::Vector_< ELT > Class Template Reference

This is the vector class intended to appear in user code for large, variable size column vectors. More...

Public Member Functions

Owner constructors

These constructors create a Vector_ object that allocates new data on the heap and serves as the owner of that data.

Any existing data that is supplied in these constructors is copied, not shared.

 Vector_ ()
 Default constructor creates a 0x1, reallocatable vector. More...
 
 Vector_ (const Vector_ &src)
 Copy constructor is deep, that is the source Vector_ is copied, not referenced. More...
 
 Vector_ (const Base &src)
 This copy constructor serves as an implicit conversion from objects of the base class type (for example, a VectorView_<ELT>), to objects of this Vector_<ELT> type. More...
 
 Vector_ (const BaseNeg &src)
 This copy constructor serves as an implicit conversion from objects of the base class but with negated elements, to objects of this Vector_<ELT> type. More...
 
 Vector_ (int m)
 Construct a Vector_ with a given preallocated size, but with uninitialized values. More...
 
 Vector_ (int m, const ELT *cppInitialValues)
 Construct an owner Vector_ of a given size m and initialize it from a C++ array of m ELT values pointed to by cppInitialValues. More...
 
 Vector_ (int m, const ELT &initialValue)
 Construct an owner Vector_ of a given size m and initialize all the elements to the given ELT value initialValue. More...
 
template<int M>
 Vector_ (const Vec< M, ELT > &v)
 This constructor creates a new owner Vector_ that is the same length and has a copy of the contents of a given fixed-size Vec. More...
 
View constructors

These constructors create a Vector_ object that is a view of existing data that is owned by some other object.

Any existing data that is supplied in these constructors is shared, not copied, so writing to the created Vector_ view modifies the original data.

 Vector_ (int m, const S *cppData, bool)
 Construct a Vector_ which shares read-only, borrowed space with assumed element-to-element stride equal to the C++ element spacing. More...
 
 Vector_ (int m, S *cppData, bool)
 Construct a Vector_ which shares writable, borrowed space with assumed element-to-element stride equal to the C++ element spacing. More...
 
 Vector_ (int m, int stride, const S *data, bool)
 Borrowed-space read-only construction with explicit stride supplied as "number of scalars between elements". More...
 
 Vector_ (int m, int stride, S *data, bool)
 Borrowed-space writable construction with explicit stride supplied as "number of scalars between elements". More...
 
Assignment operators
Vector_operator= (const Vector_ &src)
 Copy assignment is deep and can be reallocating if this Vector_ is an owner. More...
 
template<class EE >
Vector_operator= (const VectorBase< EE > &src)
 Like copy assignment but the source can be any object of the base type, even with a different element type EE as long as that element type is assignment-compatible to an element of our type ELT. More...
 
Vector_operator= (const ELT &v)
 Set all elements of this Vector_ to the same value v. More...
 
template<class EE >
Vector_operator+= (const VectorBase< EE > &m)
 Add in a conforming vector of the base type even if it has a different element type EE, provided that element type is add-compatible with our element type ELT, meaning that ELT+=EE is allowed. More...
 
template<class EE >
Vector_operator-= (const VectorBase< EE > &m)
 In-place subtract of a conforming vector of the base type even if it has a different element type EE, provided that element type is subtract-compatible with our element type ELT, meaning that ELT-=EE is allowed. More...
 
Vector_operator*= (const StdNumber &t)
 In-place multiply of each element of this Vector_ by a scalar t. More...
 
Vector_operator/= (const StdNumber &t)
 In-place divide of each element of this Vector_ by a scalar t. More...
 
Vector_operator+= (const ELT &b)
 In-place add to each element of this Vector_ the same given value b. More...
 
Vector_operator-= (const ELT &b)
 In-place subtract from each element of this Vector_ the same given value b. More...
 
Operator equivalents for scripting

Functions to be used for Scripting in MATLAB and languages that do not support operator overloading.

std::string toString () const
 toString() returns a string representation of the Vector_. More...
 
const ELT & get (int i) const
 Variant of operator[] that's scripting friendly to get ith element. More...
 
void set (int i, const ELT &value)
 Variant of operator[] that's scripting friendly to set ith element. More...
 

Related Functions

(Note that these are not member functions.)

Matrix_<T> serialization and I/O

These methods are at namespace scope but are logically part of the Vector classes.

These deal with reading and writing Vectors from and to streams, which places an additional requirement on the element type T: the element must support the same operation you are trying to do on the Vector as a whole.

template<class E >
void writeUnformatted (std::ostream &o, const Vector_< E > &v)
 Raw serialization of Vector_<E>; same as VectorBase<E>. More...
 
template<class E >
bool readUnformatted (std::istream &in, Vector_< E > &v)
 Read variable-size Vector from input stream. More...
 
template<class T >
std::ostream & operator<< (std::ostream &o, const VectorBase< T > &v)
 Output a human readable representation of a Vector to an std::ostream (like std::cout). More...
 
template<class T >
static std::istream & readVectorFromStream (std::istream &in, Vector_< T > &out)
 Read in a Vector_<T> from a stream, as a sequence of space-separated or comma-separated values optionally surrounded by parentheses (), or square brackets [], or the "transposed" ~() or ~[]. More...
 
template<class T >
static std::istream & fillVectorFromStream (std::istream &in, Vector_< T > &out)
 Read in a fixed number of elements from a stream into a Vector. More...
 
template<class T >
std::istream & operator>> (std::istream &in, Vector_< T > &out)
 Read Vector_<T> from a stream as a sequence of space- or comma-separated values of type T, optionally delimited by parentheses, or brackets, and preceded by "~". More...
 

Detailed Description

template<class ELT>
class SimTK::Vector_< ELT >

This is the vector class intended to appear in user code for large, variable size column vectors.

More commonly, the typedef Vector is used instead; that is just an abbreviation for Vector_<Real>.

A Vector_ can be a fixed-size view of someone else's data, or can be a resizable data owner itself, although of course it will always have just one column.

See also
Vec for handling of small, fixed-size vectors with no runtime overhead.
Matrix_ for variable size, two-dimensional matrix.

Constructor & Destructor Documentation

◆ Vector_() [1/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( )
inline

Default constructor creates a 0x1, reallocatable vector.

◆ Vector_() [2/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( const Vector_< ELT > &  src)
inline

Copy constructor is deep, that is the source Vector_ is copied, not referenced.

◆ Vector_() [3/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( const Base src)
inline

This copy constructor serves as an implicit conversion from objects of the base class type (for example, a VectorView_<ELT>), to objects of this Vector_<ELT> type.

Note that the source object is copied, not referenced.

◆ Vector_() [4/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( const BaseNeg src)
inline

This copy constructor serves as an implicit conversion from objects of the base class but with negated elements, to objects of this Vector_<ELT> type.

Note that the source object is copied, not referenced.

◆ Vector_() [5/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m)
inlineexplicit

Construct a Vector_ with a given preallocated size, but with uninitialized values.

In Debug builds the elements will be initialized to NaN as a debugging aid, but in Release (optimized) builds they will be uninitialized garbage so that we don't waste time setting them.

◆ Vector_() [6/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
const ELT *  cppInitialValues 
)
inline

Construct an owner Vector_ of a given size m and initialize it from a C++ array of m ELT values pointed to by cppInitialValues.

Note that there is no way to check that the correct number of elements has been provided; make sure you have supplied enough of them.

◆ Vector_() [7/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
const ELT &  initialValue 
)
inline

Construct an owner Vector_ of a given size m and initialize all the elements to the given ELT value initialValue.

◆ Vector_() [8/12]

template<class ELT >
template<int M>
SimTK::Vector_< ELT >::Vector_ ( const Vec< M, ELT > &  v)
inlineexplicit

This constructor creates a new owner Vector_ that is the same length and has a copy of the contents of a given fixed-size Vec.

◆ Vector_() [9/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
const S *  cppData,
bool   
)
inline

Construct a Vector_ which shares read-only, borrowed space with assumed element-to-element stride equal to the C++ element spacing.

Last parameter is a required dummy to avoid overload conflicts when ELT=S; pass it as "true".

◆ Vector_() [10/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
S *  cppData,
bool   
)
inline

Construct a Vector_ which shares writable, borrowed space with assumed element-to-element stride equal to the C++ element spacing.

Last parameter is a required dummy to avoid overload conflicts when ELT=S; pass it as "true".

◆ Vector_() [11/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
int  stride,
const S *  data,
bool   
)
inline

Borrowed-space read-only construction with explicit stride supplied as "number of scalars between elements".

Last parameter is a dummy to avoid overload conflicts; pass it as "true".

◆ Vector_() [12/12]

template<class ELT >
SimTK::Vector_< ELT >::Vector_ ( int  m,
int  stride,
S *  data,
bool   
)
inline

Borrowed-space writable construction with explicit stride supplied as "number of scalars between elements".

Last parameter is a dummy to avoid overload conflicts; pass it as "true".

Member Function Documentation

◆ operator=() [1/3]

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator= ( const Vector_< ELT > &  src)
inline

Copy assignment is deep and can be reallocating if this Vector_ is an owner.

Otherwise the source is copied into the destination view.

◆ operator=() [2/3]

template<class ELT >
template<class EE >
Vector_& SimTK::Vector_< ELT >::operator= ( const VectorBase< EE > &  src)
inline

Like copy assignment but the source can be any object of the base type, even with a different element type EE as long as that element type is assignment-compatible to an element of our type ELT.

◆ operator=() [3/3]

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator= ( const ELT &  v)
inline

Set all elements of this Vector_ to the same value v.

◆ operator+=() [1/2]

template<class ELT >
template<class EE >
Vector_& SimTK::Vector_< ELT >::operator+= ( const VectorBase< EE > &  m)
inline

Add in a conforming vector of the base type even if it has a different element type EE, provided that element type is add-compatible with our element type ELT, meaning that ELT+=EE is allowed.

◆ operator-=() [1/2]

template<class ELT >
template<class EE >
Vector_& SimTK::Vector_< ELT >::operator-= ( const VectorBase< EE > &  m)
inline

In-place subtract of a conforming vector of the base type even if it has a different element type EE, provided that element type is subtract-compatible with our element type ELT, meaning that ELT-=EE is allowed.

◆ operator*=()

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator*= ( const StdNumber &  t)
inline

In-place multiply of each element of this Vector_ by a scalar t.

Returns a reference to the now-modified Vector_.

◆ operator/=()

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator/= ( const StdNumber &  t)
inline

In-place divide of each element of this Vector_ by a scalar t.

Returns a reference to the now-modified Vector_.

◆ operator+=() [2/2]

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator+= ( const ELT &  b)
inline

In-place add to each element of this Vector_ the same given value b.

Returns a reference to the now-modified Vector_. This is the same operation as elementwiseAddScalarInPlace().

◆ operator-=() [2/2]

template<class ELT >
Vector_& SimTK::Vector_< ELT >::operator-= ( const ELT &  b)
inline

In-place subtract from each element of this Vector_ the same given value b.

Returns a reference to the now-modified Vector_. This is the same operation as elementwiseSubtractScalarInPlace().

◆ toString()

template<class ELT >
std::string SimTK::Vector_< ELT >::toString ( ) const
inline

toString() returns a string representation of the Vector_.

Please refer to operator<< for details.

◆ get()

template<class ELT >
const ELT& SimTK::Vector_< ELT >::get ( int  i) const
inline

Variant of operator[] that's scripting friendly to get ith element.

◆ set()

template<class ELT >
void SimTK::Vector_< ELT >::set ( int  i,
const ELT &  value 
)
inline

Variant of operator[] that's scripting friendly to set ith element.

Friends And Related Function Documentation

◆ writeUnformatted()

template<class E >
void writeUnformatted ( std::ostream &  o,
const Vector_< E > &  v 
)
related

Raw serialization of Vector_<E>; same as VectorBase<E>.

◆ readUnformatted()

template<class E >
bool readUnformatted ( std::istream &  in,
Vector_< E > &  v 
)
related

Read variable-size Vector from input stream.

Reads until error or eof.

◆ operator<<()

template<class T >
std::ostream & operator<< ( std::ostream &  o,
const VectorBase< T > &  v 
)
related

Output a human readable representation of a Vector to an std::ostream (like std::cout).

The format is ~[ elements ] where elements is a space-separated list of the Vector's contents output by invoking the "<<" operator on the elements. This function will not compile if the element type does not support the "<<" operator. No newline is issued before or after the output.

◆ readVectorFromStream()

template<class T >
static std::istream & readVectorFromStream ( std::istream &  in,
Vector_< T > &  out 
)
related

Read in a Vector_<T> from a stream, as a sequence of space-separated or comma-separated values optionally surrounded by parentheses (), or square brackets [], or the "transposed" ~() or ~[].

In the case that the transpose operator is present, the parentheses or brackets are required, otherwise they are optional. We will continue to read elements of type T from the stream until we find a reason to stop, using type T's stream extraction operator>>() to read in each element and resizing the Vector as necessary. If the data is bracketed, we'll read until we hit the closing bracket. If it is not bracketed, we'll read until we hit eof() or get an error such as the element extractor setting the stream's fail bit due to bad formatting. On successful return, the stream will be positioned right after the final read-in element or terminating bracket, and the stream's status will be good() or eof(). We will not consume trailing whitespace after bracketed elements; that means the stream might actually be empty even if we don't return eof(). If you want to know whether there is anything else in the stream, follow this call with the STL whitespace skipper std::ws() like this:

if (readVectorFromStream(in,vec) && !in.eof())
std::ws(in); // might take us to eof
if (in.fail()) {...} // probably a formatting error
else {
// Here if the stream is good() then there is more to read; if the
// stream got used up the status is guaranteed to be eof().
}

A compilation error will occur if you try to use this method on an Vector_<T> for a type T for which there is no stream extraction operator>>().

Note
If you want to fill a resizeable Vector_<T> with a fixed amount of data from the stream, resize() the Vector to the appropriate length and then use fillVectorFromStream() instead.
See also
fillVectorFromStream()

◆ fillVectorFromStream()

template<class T >
static std::istream & fillVectorFromStream ( std::istream &  in,
Vector_< T > &  out 
)
related

Read in a fixed number of elements from a stream into a Vector.

We expect to read in exactly size() elements of type T, using type T's stream extraction operator>>(). This will stop reading when we've read size() elements, or set the fail bit in the stream if we run out of elements or if any element's extract operator sets the fail bit. On successful return, all size() elements will have been set, the stream will be positioned right after the final read-in element or terminating bracket, and the stream's status will be good() or eof(). We will not consume trailing whitespace after reading all the elements; that means the stream might actually be empty even if we don't return eof(). If you want to know whether there is anything else in the stream, follow this call with std::ws() like this:

if (!in.eof()) std::ws(in); // might take us to eof
if (in.fail()) {...} // deal with I/O or formatting error
// Here if the stream is good() then there is more to read; if the
// stream got used up the status is guaranteed to be eof().

A compilation error will occur if you try to use this method on a Vector_<T> for a type T for which there is no stream extraction operator>>().

Note
If you want to read in a variable number of elements and have the Vector_<T> resized as needed, use readVectorFromStream() instead.
See also
readVectorFromStream()

◆ operator>>()

template<class T >
std::istream & operator>> ( std::istream &  in,
Vector_< T > &  out 
)
related

Read Vector_<T> from a stream as a sequence of space- or comma-separated values of type T, optionally delimited by parentheses, or brackets, and preceded by "~".

The Vector_<T> may be an owner (variable size) or a view (fixed size n). In the case of an owner, we'll read all the elements in brackets or until eof if there are no brackets. In the case of a view, there must be exactly n elements in brackets, or if there are no brackets we'll consume exactly n elements and then stop. Each element is read in with its own operator ">>" so this won't work if no such operator is defined for type T.


The documentation for this class was generated from the following files:
SimTK::Vector_::fillVectorFromStream
static std::istream & fillVectorFromStream(std::istream &in, Vector_< T > &out)
Read in a fixed number of elements from a stream into a Vector.
Definition: BigMatrix.h:1430
SimTK::Vector_::readVectorFromStream
static std::istream & readVectorFromStream(std::istream &in, Vector_< T > &out)
Read in a Vector_<T> from a stream, as a sequence of space-separated or comma-separated values option...
Definition: BigMatrix.h:1400