kjb::Int_matrix Class Reference

This class implements matrices, in the linear-algebra sense, restricted to integer-valued elements. More...

#include <l_int_matrix.h>

Public Types
typedef int	Value_type
	data type of the elements More...
typedef int	Size_type
typedef kjb_c::Int_matrix	Impl_type
	the underlying implementation More...
typedef Int_matrix	Mat_type
	the associated matrix type More...
typedef Int_vector	Vec_type
	the associated vector type More...
typedef Value_type(*	Mapper )(Value_type)
	element transformer fun More...

Public Member Functions
	Int_matrix ()
	Default ctor builds a matrix of zero rows, zero columns. More...
	Int_matrix (int rows, int cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Int_matrix (unsigned rows, unsigned cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Int_matrix (unsigned rows, unsigned cols, Value_type val)
	Ctor builds a matrix of specified number of rows and columns. More...
	Int_matrix (unsigned long rows, unsigned long cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Int_matrix (unsigned long rows, unsigned long cols, Value_type val)
	Ctor builds a matrix of specified number of rows and columns. More...
	Int_matrix (int rows, int cols, Value_type num)
	Ctor builds a matrix of specified size, all entries set to num. More...
	Int_matrix (int rows, int cols, const Value_type *data)
	Ctor builds a matrix and initializes entries from an array. More...
	Int_matrix (Impl_type *mat_ptr)
	Conversion ctor: claim ownership of an existing int matrix pointer (i.e., make a shallow copy). More...
	Int_matrix (const Impl_type &mat_ref)
	Ctor copies contents (i.e., a deep copy) of an existing C-struct matrix. More...
	Int_matrix (const std::string &file_name)
	Read matrix from file. More...
	Int_matrix (const Int_matrix &mat_ref)
	Copy ctor. More...
	~Int_matrix ()
Int_matrix &	zero_out (int num_rows, int num_cols)
	Resize matrix, replace contents with the identity matrix. More...
Int_matrix &	zero_out (int rows)
	Resize matrix to be square, and clobber contents with zeroes. More...
Int_matrix &	zero_out ()
	Clobber contents of matrix with zeroes. More...
Int_matrix &	operator= (const Impl_type &mat_ref)
	Clone of zero_out(int,int) More...
Int_matrix &	operator= (const Int_matrix &src)
	Assign contents from a kjb::Int_matrix, a C++ object. More...
void	swap (Int_matrix &other)
	Swap the representations of two matrices. More...
int	get_num_rows () const
	Return the number of rows in the matrix. More...
int	get_num_cols () const
	Return the number of columns in the matrix. More...
int	get_length () const
	Return the number of elements in the matrix. More...
const Impl_type *	get_c_matrix () const
	Get const pointer to the underlying kjb_c::Int_matrix C struct. More...
Impl_type *	get_underlying_representation_with_guilt ()
	Get pointer to the underlying kjb_c::Matrix C struct. More...
Value_type **	ptr_to_storage_area () const
	Access a pointer to the underlying implementation, use with care. More...
Int_matrix &	resize (int new_rows, int new_cols, Value_type pad=Value_type(0))
	Resize this matrix, retaining previous values. More...
Int_matrix &	realloc (int new_rows, int new_cols)
	Resize this matrix, discarding previous values (faster than resize, because storage is reused) More...
Int_matrix	transpose ()
	Transpose this matrix, in-place. More...
void	check_bounds (int row, int col) const
	Test whether the given row and column indices are valid. More...
Value_type &	operator[] (int i)
	Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an lvalue. More...
Value_type	operator[] (int i) const
	Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an rvalue. More...
Value_type &	operator() (int i)
	MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an lvalue. More...
Value_type	operator() (int i) const
	MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an rvalue. More...
Value_type &	operator() (int row, int col)
	Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an lvalue. More...
Value_type	operator() (int row, int col) const
	Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an rvalue. More...
Value_type &	at (int i)
	Access matrix like a one-dimensional array, using row-major ordering, and returning an lvalue. More...
Value_type	at (int i) const
	Access matrix like a one-dimensional array, using row-major ordering, and returning an rvalue. More...
Value_type &	at (int row, int col)
	Access matrix with bounds checking and return an lvalue. More...
Value_type	at (int row, int col) const
	Access matrix with bounds checking and return an rvalue. More...
Vec_type	get_row (int row) const
	Return a specified row of this matrix, in the form of an Int_vector. More...
Vec_type	get_col (int col) const
	Return a specified column of this matrix, in the form of an Int_vector. More...
template<class Generic_vector >
void	set_row (int row, const Generic_vector &v)
	Replace a row of the matrix with the given vector. More...
template<class Iterator >
void	set_row (int row, Iterator begin, Iterator end)
	Dispatch for set_row. Don't call directly. More...
template<class Generic_vector >
void	set_col (int col, const Generic_vector &v)
	Replace a column of the matrix with the given vector. "vector" can be any collection of values convertible to int. More...
template<class Iterator >
void	set_col (int col, Iterator begin, Iterator end)
	Dispatch for set_col. Don't call directly. More...
int	write (const char *filename=0) const
	Writes the matrix contents to a file specified by name. More...
Int_matrix &	operator*= (const Int_matrix &op2)
	Compute product of this matrix (on the left) and another, and replace this matrix with the result. More...
Int_matrix &	multiply (const Int_matrix &op2)
	Compute product of this matrix (on the left) and another, and replace this matrix with the result, like *=. More...
Int_matrix &	operator*= (Value_type op2)
	Multiply this matrix by a scalar, in place. More...
Int_matrix &	multiply (Value_type op2)
	Multiply this matrix by a scalar, in place. More...
Int_matrix &	operator/= (Int_matrix::Value_type op2)
	Perform integer division on each entry in the matrix by a scalar value. More...
Int_matrix &	divide (Int_matrix::Value_type op2)
	Perform integer division on each entry in the matrix by a scalar value. More...
Int_matrix &	operator+= (const Int_matrix &op2)
	Add, in place, a matrix to this matrix. More...
Int_matrix &	add (const Int_matrix &op2)
	Add, in place, a matrix to this matrix. More...
Int_matrix &	operator-= (const Int_matrix &op2)
	Subtract another matrix from this matrix, in place. More...
Int_matrix &	subtract (const Int_matrix &op2)
	Subtract another matrix from this matrix, in place. More...
Int_matrix &	negate ()
	Transform this matrix into the additive inverse of its former value, in place. More...
Mat_type &	mapcar (Mapper)
	Transform the elements of a matrix. More...

Detailed Description

This class implements matrices, in the linear-algebra sense, restricted to integer-valued elements.

For better maintainability, refer to the element type using this class's Value_type typedef, instead of referring to 'int' directly.

Most methods of this class are implemented in the C language portion of the KJB library, with this class forming a thin (usually inlined) layer.

Member Typedef Documentation

typedef kjb_c::Int_matrix kjb::Int_matrix::Impl_type

the underlying implementation

typedef Value_type(* kjb::Int_matrix::Mapper)(Value_type)

element transformer fun

typedef Int_matrix kjb::Int_matrix::Mat_type

the associated matrix type

typedef int kjb::Int_matrix::Size_type

typedef int kjb::Int_matrix::Value_type

data type of the elements

typedef Int_vector kjb::Int_matrix::Vec_type

the associated vector type

Constructor & Destructor Documentation

kjb::Int_matrix::Int_matrix ( )

inline

Default ctor builds a matrix of zero rows, zero columns.

kjb::Int_matrix::Int_matrix ( int  rows, int  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

kjb::Int_matrix::Int_matrix ( unsigned  rows, unsigned  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, columns is int, not unsigned.

kjb::Int_matrix::Int_matrix ( unsigned  rows, unsigned  cols, Value_type  val  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, columns is int, not unsigned.

kjb::Int_matrix::Int_matrix ( unsigned long  rows, unsigned long  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, cols is int, not unsigned long.

kjb::Int_matrix::Int_matrix ( unsigned long  rows, unsigned long  cols, Value_type  val  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, cols is int, not unsigned long.

kjb::Int_matrix::Int_matrix ( int  rows, int  cols, Value_type  num  )

inline

Ctor builds a matrix of specified size, all entries set to num.

kjb::Int_matrix::Int_matrix ( Impl_type *  mat_ptr )

inline

Conversion ctor: claim ownership of an existing int matrix pointer (i.e., make a shallow copy).

This method is the proper way to say, ''Here is a kjb_c::Int_matrix struct that I am responsible for deleting, and I must make sure that it gets destroyed when it goes out of scope.'' This is a good way to wrap a matrix "dynamically," after it has already been created.

Anyplace you find yourself using free_int_matrix() in your C++ code, you should consider using instead this class and this ctor.

If the input pointer equals NULL then a zero size matrix is constructed.

Warning

Do not create two Int_matrix objects from the same source this way or you will get a double deletion bug.

kjb::Int_matrix::Int_matrix ( const Impl_type &  mat_ref )

inlineexplicit

Ctor copies contents (i.e., a deep copy) of an existing C-struct matrix.

Warning

This method should be seldom used: kjb_c::Int_matrix objects should rarely be left in an unwrapped state.

This kind of conversion is relatively expensive, thus we restrict its use to explicit invocation.

kjb::Int_matrix::Int_matrix ( const Int_matrix &  mat_ref )

inline

Copy ctor.

kjb::Int_matrix::~Int_matrix ( )

inline

Member Function Documentation

Int_matrix& kjb::Int_matrix::add ( const Int_matrix &  op2 )

inline

Add, in place, a matrix to this matrix.

Value_type& kjb::Int_matrix::at ( int  i )

inline

Access matrix like a one-dimensional array, using row-major ordering, and returning an lvalue.

Value_type kjb::Int_matrix::at ( int  i ) const

inline

Access matrix like a one-dimensional array, using row-major ordering, and returning an rvalue.

Value_type& kjb::Int_matrix::at ( int  row, int  col  )

inline

Access matrix with bounds checking and return an lvalue.

Value_type kjb::Int_matrix::at ( int  row, int  col  ) const

inline

Access matrix with bounds checking and return an rvalue.

void kjb::Int_matrix::check_bounds ( int  row, int  col  ) const

inline

Test whether the given row and column indices are valid.

Exceptions

Index_out_of_bounds

exception, plus an explanatory message.

Although this is a public method, users seldom will call it directly. Its main purpose is to support the at() methods.

Int_matrix& kjb::Int_matrix::divide ( Int_matrix::Value_type  op2 )

inline

Perform integer division on each entry in the matrix by a scalar value.

Returns

an lvalue to this matrix

Warning

This uses integer division, truncating fractions toward zero.

Exceptions

Divide_by_zero

if the scalar value is zero.

const Impl_type* kjb::Int_matrix::get_c_matrix ( ) const

inline

Get const pointer to the underlying kjb_c::Int_matrix C struct.

int kjb::Int_matrix::get_length ( ) const

inline

Return the number of elements in the matrix.

Warning

There is a remote chance this could overflow an int.

int kjb::Int_matrix::get_num_cols ( ) const

inline

Return the number of columns in the matrix.

int kjb::Int_matrix::get_num_rows ( ) const

inline

Return the number of rows in the matrix.

Impl_type* kjb::Int_matrix::get_underlying_representation_with_guilt ( )

inline

Get pointer to the underlying kjb_c::Matrix C struct.

Warning

: This should only be used if you know what you're doing. generally, it should only be used to write wrapper functions for c functions.

Int_matrix& kjb::Int_matrix::multiply ( const Int_matrix &  op2 )

inline

Compute product of this matrix (on the left) and another, and replace this matrix with the result, like *=.

Exceptions

Dimension_mismatch

if the number of columns of this matrix does not equal the number of rows of right factor op2.

Warning

This is not really an in-place operation – do not expect a speed-up using this operation instead of plain old star.

Int_matrix& kjb::Int_matrix::multiply ( Value_type  op2 )

inline

Multiply this matrix by a scalar, in place.

Int_matrix& kjb::Int_matrix::negate ( )

inline

Transform this matrix into the additive inverse of its former value, in place.

Value_type& kjb::Int_matrix::operator() ( int  i )

inline

MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Value_type kjb::Int_matrix::operator() ( int  i ) const

inline

MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Value_type& kjb::Int_matrix::operator() ( int  row, int  col  )

inline

Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

The comparison to Fortran does not imply column-major ordering.

Value_type kjb::Int_matrix::operator() ( int  row, int  col  ) const

inline

Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

The comparison to Fortran does not imply column-major ordering.

Int_matrix& kjb::Int_matrix::operator*= ( const Int_matrix &  op2 )

inline

Compute product of this matrix (on the left) and another, and replace this matrix with the result.

Exceptions

Dimension_mismatch

if the number of columns of this matrix does not equal the number of rows of right factor op2.

Warning

This is not really an in-place operation – do not expect a speed-up using this operation instead of plain old star.

Int_matrix& kjb::Int_matrix::operator*= ( Value_type  op2 )

inline

Multiply this matrix by a scalar, in place.

Int_matrix& kjb::Int_matrix::operator+= ( const Int_matrix &  op2 )

inline

Add, in place, a matrix to this matrix.

Int_matrix& kjb::Int_matrix::operator-= ( const Int_matrix &  op2 )

inline

Subtract another matrix from this matrix, in place.

Int_matrix& kjb::Int_matrix::operator= ( const Impl_type &  mat_ref )

inline

Clone of zero_out(int,int)

Deprecated:

The name is misleading; instead of this, use zero_out(int,int) in new code.

Assign contents from a kjb_c::Int_matrix, a C struct; make a deep copy.

Note

Consider using a shallow copy and swap() instead of assignment, to prevent unnecessary deep copying.

Implementation note: this routine formerly had a clause in it to prevent calling copy_matrix() when mat_ref pointed to a zero-element matrix. This clause has been removed because it was later decided that copy_matrix() should work even in that case.

Int_matrix& kjb::Int_matrix::operator= ( const Int_matrix &  src )

inline

Assign contents from a kjb::Int_matrix, a C++ object.

Note

Consider using swap() instead of assignment, to prevent unnecessary deep copying.

Value_type& kjb::Int_matrix::operator[] ( int  i )

inline

Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Value_type kjb::Int_matrix::operator[] ( int  i ) const

inline

Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Value_type** kjb::Int_matrix::ptr_to_storage_area ( ) const

inline

Access a pointer to the underlying implementation, use with care.

Int_matrix& kjb::Int_matrix::realloc ( int  new_rows, int  new_cols  )

inline

Resize this matrix, discarding previous values (faster than resize, because storage is reused)

Int_matrix& kjb::Int_matrix::subtract ( const Int_matrix &  op2 )

inline

Subtract another matrix from this matrix, in place.

void kjb::Int_matrix::swap ( Int_matrix &  other )

inline

Swap the representations of two matrices.

Int_matrix kjb::Int_matrix::transpose ( )

inline

Transpose this matrix, in-place.

Returns

an lvalue to this matrix.

int kjb::Int_matrix::write ( const char *  filename = 0 ) const

inline

Writes the matrix contents to a file specified by name.

See Also

kjb_c::write_int_matrix()

If filename is NULL or the first character is null, then the output is written to standard output.

Int_matrix& kjb::Int_matrix::zero_out ( int  num_rows, int  num_cols  )

inline

Resize matrix, replace contents with the identity matrix.

See Also

create_identity_matrix()

The name of this method is misleading but I can't think of a better one. It's not really an initialization routine, more like a re-init. Resize matrix, and clobber contents with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix(int,int) – more appropriate in some situations.

Int_matrix& kjb::Int_matrix::zero_out ( int  rows )

inline

Resize matrix to be square, and clobber contents with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix(int) – more appropriate in some situations.

Int_matrix& kjb::Int_matrix::zero_out ( )

inline

Clobber contents of matrix with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix() – more appropriate in some situations.

---

The documentation for this class was generated from the following files:

• /work/kobus/src/lib/l_cpp/l_int_matrix.h
• /work/kobus/src/lib/l_cpp/l_int_matrix.cpp