maspack.matrix
Class VectorNi

java.lang.Object
  extended by maspack.matrix.VectorNi
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Clonable

public class VectorNi
extends java.lang.Object
implements java.io.Serializable, Clonable

Implements a general vector of integers. We have provided integer implementations of all methods of VectorNd for which it makes sense to do so.

These vectors can be resized, either explicitly through a call to setSize, or implicitly through operations that require the vector size to be modified.

See Also:
Serialized Form

Constructor Summary
VectorNi()
          Creates a vector with an initial size of zero.
VectorNi(int size)
          Creates a vector of a specific size, and initializes its elements to 0.
VectorNi(int[] values)
          Creates a vector from an array of ints.
VectorNi(int size, int[] values)
          Creates a vector of a specific size, and initializes its elements from an array of values.
VectorNi(VectorNi vec)
          Creates a new VectorNi from an existing one.
 
Method Summary
 void absolute()
          Sets the elements of this vector to their absolute values.
 void absolute(VectorNi v1)
          Sets the elements of this vector to the absolute value of v1.
 void add(int i, int value)
          Adds a value to the i-th element of this vector.
 void add(VectorNi v1)
          Adds this vector to v1 and places the result in this vector.
 void add(VectorNi v1, VectorNi v2)
          Adds vector v1 to v2 and places the result in this vector.
 int adjustSize(int inc)
           
 void append(int value)
          Appends a value to the end of this vector, increasing its size by one.
 VectorNi clone()
           
 boolean equals(VectorNi v1)
          Returns true if the elements of this vector exactly equal those of vector v1.
 int get(int i)
          Gets a single element of this vector.
 void get(int[] values)
          Copies the elements of this vector into an array of ints.
 int[] getBuffer()
          Returns the internal buffer used to store the elements in this vector.
 int getCapacity()
           
static java.lang.String getDefaultFormat()
          Returns the default format string used in toString.
 int infinityNorm()
          Returns the infinity norm of this vector.
 boolean isFixedSize()
          Returns true if this vector is of fixed size.
 void max(VectorNi v)
          Computes the element-wise maximum of this vector and vector v and places the result in this vector.
 int maxElement()
          Returns the maximum element value of this vector.
 void min(VectorNi v)
          Computes the element-wise minimum of this vector and vector v and places the result in this vector.
 int minElement()
          Returns the minimum element value of this vector.
 void negate()
          Negates this vector in place.
 void negate(VectorNi v1)
          Sets this vector to the negative of v1.
 int oneNorm()
          Returns the 1 norm of this vector.
 void permute(int[] permutation)
          Rearrange the elements of this vector according to the specified permutation, such that each element i is replaced by element permutation[i].
 void scale(double s)
          Scales the elements of this vector by s.
 void scale(double s, VectorNi v1)
          Scales the elements of vector v1 by s and places the results in this vector.
 void scaledAdd(double s, VectorNi v1)
          Computes s v1 and adds the result to this vector.
 void scaledAdd(double s, VectorNi v1, VectorNi v2)
           
 void scan(ReaderTokenizer rtok)
          Sets the contents of this vector to values read from a ReaderTokenizer.
 void set(int[] values)
          Sets the elements of this vector from an array of ints.
 void set(int i, int value)
          Sets a single element of this vector.
 void set(VectorNi v1)
          Sets the size and values of this vector to those of v1.
 void setBuffer(int size, int[] buffer)
          Explicitly sets the size and internal buffer associated with this vector.
 void setCapacity(int newcap)
           
static void setDefaultFormat(java.lang.String fmtStr)
          Sets the default format string used in toString.
 void setRandom()
          Sets the elements of this vector to uniformly distributed random values in the range -1000 (inclusive) to 1000 (exclusive).
 void setRandom(int lower, int upper)
          Sets the elements of this vector to uniformly distributed random values in a specified range.
 void setRandom(int lower, int upper, java.util.Random generator)
          Sets the elements of this vector to uniformly distributed random values in a specified range, using a supplied random number generator.
 void setSize(int newSize)
          Sets the size of this vector.
 void setSubVector(int off, VectorNi v1)
          Sets a subset of the values of this vector, beginning at a specified offset, to the values of v1.
 void setZero()
          Sets the elements of this vector to zero.
 int size()
          Returns the size of this vector.
 void sort()
          Sorts the contents of this vector by element value, from largest to smallest value.
 void sort(VectorNi v1)
          Sorts the contents of vector v1 by element value, from largest to smallest value, and places the result into this vector.
 void sub(VectorNi v1)
          Subtracts v1 from this vector and places the result in this vector.
 void sub(VectorNi v1, VectorNi v2)
          Subtracts vector v1 from v2 and places the result in this vector.
 int sum()
          Returns the sum of all the elements in this vector.
 java.lang.String toString()
          Returns a String representation of this vector, using the default format returned by getDefaultFormat.
 java.lang.String toString(NumberFormat fmt)
          Returns a String representation of this vector, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.
 java.lang.String toString(java.lang.String fmtStr)
          Returns a String representation of this vector, in which each element is formatted using a C printf style format string.
 void unsetBuffer()
          Removes an explicit buffer provided for this vector and replaces it with a default implicit buffer.
 void write(java.io.PrintWriter pw, NumberFormat fmt)
          Writes the contents of this vector to a PrintWriter.
 void write(java.io.PrintWriter pw, NumberFormat fmt, boolean withBrackets)
          Writes the contents of this vector to a PrintWriter.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

VectorNi

public VectorNi()
Creates a vector with an initial size of zero.


VectorNi

public VectorNi(int size)
         throws ImproperSizeException
Creates a vector of a specific size, and initializes its elements to 0. It is legal to create a vector with a size of zero.

Parameters:
size - size of the vector
Throws:
ImproperSizeException - if size is negative

VectorNi

public VectorNi(int size,
                int[] values)
         throws ImproperSizeException
Creates a vector of a specific size, and initializes its elements from an array of values.

Parameters:
size - size of the vector
values - element values for the new vector
Throws:
ImproperSizeException - if size is negative

VectorNi

public VectorNi(int[] values)
Creates a vector from an array of ints. The vector size is determined by the size of this array.

Parameters:
values - element values for the new vector

VectorNi

public VectorNi(VectorNi vec)
Creates a new VectorNi from an existing one.

Parameters:
vec - Vector to be copied
Method Detail

setDefaultFormat

public static void setDefaultFormat(java.lang.String fmtStr)
Sets the default format string used in toString. For a description of the format string syntax, see NumberFormat.

Parameters:
fmtStr - new format string
Throws:
java.lang.IllegalArgumentException - if the format string is invalid
See Also:
getDefaultFormat()

getDefaultFormat

public static java.lang.String getDefaultFormat()
Returns the default format string used in toString. If unset, this string is "%d". For a description of the format string syntax, see NumberFormat.

Returns:
Default format string

getBuffer

public int[] getBuffer()
Returns the internal buffer used to store the elements in this vector. When possible, applications should access the vector elements using the various set and get methods. However, if efficiency requires it, this buffer can be used directly.

Note that the buffer may be larger than the vector. The i-th element in the vector corresponds to the i-th entry in the buffer.

If this vector is resized, then the internal buffer may change and the buffer previously returned by this routine may no longer be valid.

Returns:
internal buffer for this vector
See Also:
setBuffer(int, int[])

size

public int size()
Returns the size of this vector.

Returns:
size of the vector

isFixedSize

public boolean isFixedSize()
Returns true if this vector is of fixed size. In the present implementation, VectorNi objects always have variable size, and so this routine always returns false.

Returns:
true if this vector is of fixed size
See Also:
setSize(int)

setSize

public void setSize(int newSize)
             throws ImproperSizeException
Sets the size of this vector. This operation may enlarge the internal buffer associated with this vector, invalidating buffers previously returned by getBuffer.

If a vector is resized, then previous element values which are still within the new vector dimension are preserved. Other (new) element values are undefined.

Parameters:
newSize - new vector size
Throws:
ImproperSizeException - if this vector has an explicit internal buffer and that buffer is too small for the requested size

adjustSize

public int adjustSize(int inc)
               throws ImproperSizeException
Throws:
ImproperSizeException

getCapacity

public int getCapacity()

setCapacity

public void setCapacity(int newcap)

setBuffer

public void setBuffer(int size,
                      int[] buffer)
Explicitly sets the size and internal buffer associated with this vector. Any previous values will be discarded, and the vector will assume the new values presently contained within the buffer. The length of buffer must equal or exceed the specified size. The vector can continue to be resized as long as the requested sizes do not exceed the buffer size.

Parameters:
size - new vector size
buffer - explicit buffer for this vector
Throws:
ImproperSizeException - if the specified buffer is too small for the requested size
See Also:
unsetBuffer()

unsetBuffer

public void unsetBuffer()
Removes an explicit buffer provided for this vector and replaces it with a default implicit buffer. The vector retains its present size but all values are replaced with zero.

Throws:
java.lang.IllegalStateException - if this vector does not have an explicit buffer given by setBuffer
See Also:
setBuffer(int, int[])

get

public int get(int i)
Gets a single element of this vector.

Parameters:
i - element index
Returns:
element value

get

public void get(int[] values)
Copies the elements of this vector into an array of ints.

Parameters:
values - array into which values are copied

set

public void set(int i,
                int value)
Sets a single element of this vector.

Parameters:
i - element index
value - element value

append

public void append(int value)
Appends a value to the end of this vector, increasing its size by one. If the vector's capacity (i.e., the length of the underlying array) needs to be increased, this is done by an extended amount in order to reduce the overall number of capacity increases that may be incurred by a sequence of append calls.

Parameters:
value - value to append to the end of this vector
Throws:
ImproperSizeException - if the capacity needs to be increased but the internal buffer is explicit and so cannot be increased.

set

public void set(int[] values)
Sets the elements of this vector from an array of ints.

Parameters:
values - array from which values are copied

set

public void set(VectorNi v1)
Sets the size and values of this vector to those of v1.

Parameters:
v1 - vector whose size and values are copied
Throws:
ImproperSizeException - if this vector needs resizing but is of fixed size

setSubVector

public void setSubVector(int off,
                         VectorNi v1)
Sets a subset of the values of this vector, beginning at a specified offset, to the values of v1.

Parameters:
off - offset where copying should begin in this vector
v1 - vector whose values are copied
Throws:
ImproperSizeException - if this vector is not large enough to accomodate the specified subvector

add

public void add(VectorNi v1,
                VectorNi v2)
         throws ImproperSizeException
Adds vector v1 to v2 and places the result in this vector. This vector is resized if necessary.

Parameters:
v1 - left-hand vector
v2 - right-hand vector
Throws:
ImproperSizeException - if v1 and v2 have different sizes, or if this vector needs resizing but is of fixed size

add

public void add(VectorNi v1)
         throws ImproperSizeException
Adds this vector to v1 and places the result in this vector.

Parameters:
v1 - right-hand vector
Throws:
ImproperSizeException - if this vector and v1 have different sizes

add

public void add(int i,
                int value)
Adds a value to the i-th element of this vector.

Parameters:
i - index of the element
value - value to be added

sub

public void sub(VectorNi v1,
                VectorNi v2)
         throws ImproperSizeException
Subtracts vector v1 from v2 and places the result in this vector. This vector is resized if necessary.

Parameters:
v1 - left-hand vector
v2 - right-hand vector
Throws:
ImproperSizeException - if v1 and v2 have different sizes, or if this vector needs resizing but is of fixed size

sub

public void sub(VectorNi v1)
         throws ImproperSizeException
Subtracts v1 from this vector and places the result in this vector.

Parameters:
v1 - right-hand vector
Throws:
ImproperSizeException - if this vector and v1 have different sizes

negate

public void negate(VectorNi v1)
Sets this vector to the negative of v1. This vector is resized if necessary.

Parameters:
v1 - vector to negate
Throws:
ImproperSizeException - if this vector needs resizing but is of fixed size

negate

public void negate()
Negates this vector in place.


scale

public void scale(double s)
Scales the elements of this vector by s.

Parameters:
s - scaling factor

scale

public void scale(double s,
                  VectorNi v1)
Scales the elements of vector v1 by s and places the results in this vector. This vector is resized if necessary.

Parameters:
s - scaling factor
v1 - vector to be scaled
Throws:
ImproperSizeException - if this vector needs resizing but is of fixed size

scaledAdd

public void scaledAdd(double s,
                      VectorNi v1,
                      VectorNi v2)
               throws ImproperSizeException
Throws:
ImproperSizeException

scaledAdd

public void scaledAdd(double s,
                      VectorNi v1)
               throws ImproperSizeException
Computes s v1 and adds the result to this vector.

Parameters:
s - scaling factor
v1 - vector to be scaled and added
Throws:
ImproperSizeException - if this vector and v1 have different sizes

maxElement

public int maxElement()
Returns the maximum element value of this vector.

Returns:
maximal element

minElement

public int minElement()
Returns the minimum element value of this vector.

Returns:
minimal element

infinityNorm

public int infinityNorm()
Returns the infinity norm of this vector. This is the maximum absolute value over all elements.

Returns:
vector infinity norm

oneNorm

public int oneNorm()
Returns the 1 norm of this vector. This is the sum of the absolute values of the elements.

Returns:
vector 1 norm

equals

public boolean equals(VectorNi v1)
               throws ImproperSizeException
Returns true if the elements of this vector exactly equal those of vector v1.

Parameters:
v1 - vector to compare with
Returns:
false if the vectors are not equal or have different sizes
Throws:
ImproperSizeException

sum

public int sum()
Returns the sum of all the elements in this vector.

Returns:
sum of all the elements

setZero

public void setZero()
Sets the elements of this vector to zero.


absolute

public void absolute()
Sets the elements of this vector to their absolute values.


absolute

public void absolute(VectorNi v1)
Sets the elements of this vector to the absolute value of v1. This vector is resized if necessary.

Parameters:
v1 - vector to take the absolute value of
Throws:
ImproperSizeException - if this vector needs resizing but is of fixed size

sort

public void sort()
Sorts the contents of this vector by element value, from largest to smallest value.


sort

public void sort(VectorNi v1)
Sorts the contents of vector v1 by element value, from largest to smallest value, and places the result into this vector.

Parameters:
v1 - vector to sort

setRandom

public void setRandom()
Sets the elements of this vector to uniformly distributed random values in the range -1000 (inclusive) to 1000 (exclusive).


setRandom

public void setRandom(int lower,
                      int upper)
Sets the elements of this vector to uniformly distributed random values in a specified range.

Parameters:
lower - lower random value (inclusive)
upper - upper random value (exclusive)

setRandom

public void setRandom(int lower,
                      int upper,
                      java.util.Random generator)
Sets the elements of this vector to uniformly distributed random values in a specified range, using a supplied random number generator.

Parameters:
lower - lower random value (inclusive)
upper - upper random value (exclusive)
generator - random number generator

max

public void max(VectorNi v)
         throws ImproperSizeException
Computes the element-wise maximum of this vector and vector v and places the result in this vector.

Parameters:
v - vector to compare with
Throws:
ImproperSizeException - if this vector and v have different sizes

min

public void min(VectorNi v)
         throws ImproperSizeException
Computes the element-wise minimum of this vector and vector v and places the result in this vector.

Parameters:
v - vector to compare with
Throws:
ImproperSizeException - if this vector and v have different sizes

clone

public VectorNi clone()
Specified by:
clone in interface Clonable
Overrides:
clone in class java.lang.Object

permute

public void permute(int[] permutation)
Rearrange the elements of this vector according to the specified permutation, such that each element i is replaced by element permutation[i].

Parameters:
permutation - describes the element exchanges
Throws:
ImproperSizeException - if the length of permutation is less than the size of this vector.

toString

public java.lang.String toString()
Returns a String representation of this vector, using the default format returned by getDefaultFormat.

Overrides:
toString in class java.lang.Object
Returns:
String representation of this vector
See Also:
toString(String)

toString

public java.lang.String toString(java.lang.String fmtStr)
Returns a String representation of this vector, in which each element is formatted using a C printf style format string. For a description of the format string syntax, see NumberFormat. Note that when called numerous times, toString(NumberFormat) will be more efficient because the NumberFormat will not need to be recreated each time from a specification string.

Parameters:
fmtStr - numeric format specification
Returns:
String representation of this vector

toString

public java.lang.String toString(NumberFormat fmt)
Returns a String representation of this vector, in which each element is formatted using a C printf style format as decribed by the parameter NumberFormat.

Parameters:
fmt - numeric format
Returns:
String representation of this vector

write

public void write(java.io.PrintWriter pw,
                  NumberFormat fmt)
           throws java.io.IOException
Writes the contents of this vector to a PrintWriter. Element values are separated by spaces, and each element is formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this vector to
fmt - numeric format
Throws:
java.io.IOException

write

public void write(java.io.PrintWriter pw,
                  NumberFormat fmt,
                  boolean withBrackets)
           throws java.io.IOException
Writes the contents of this vector to a PrintWriter. Element values are separated by spaces, and optionally surrounded by square brackets [ ] if withBrackets is set true. Each element is formatted using a C printf style as decribed by the parameter NumberFormat.

Parameters:
pw - PrintWriter to write this vector to
fmt - numeric format
withBrackets - if true, causes the output to be surrounded by square brackets.
Throws:
java.io.IOException

scan

public void scan(ReaderTokenizer rtok)
          throws java.io.IOException
Sets the contents of this vector to values read from a ReaderTokenizer. The input should consist of a sequence of integers, separated by white space and optionally surrounded by square brackets [ ].

If the input is not surrounded by square brackets, then the number of values should equal the current size of this vector.

If the input is surrounded by square brackets, then all values up to the closing bracket are read, and the resulting number of values should either equal the current size of this vector, or this vector should be resizeable to fit the input. For example,

 [ 1 4 5 3 ]
 
defines a vector of size 4.

Parameters:
rtok - Tokenizer from which vector values are read. Number parsing should be enabled.
Throws:
ImproperSizeException - if this vector has a fixed size which is incompatible with the input
java.io.IOException