PIRL  PIRL++

Classes | Typedefs | Functions | Variables

PIRL Namespace Reference

The Planetary Image Research Laboratory. More...

Classes

class  Data_Binder
 A Data_Binder binds an object to data of some amount. More...
class  Binary_IO
 The Binary_IO class provides input and output of binary data values. More...
struct  Binary_Input
 Binary_Input is a subclass of Binary_IO that contains an istream reference. More...
struct  Binary_Output
 Binary_Output is a subclass of Binary_IO that contains an ostream reference. More...
class  Cache
 A Cache is a dynamic input storage area. More...
class  Data_Block
 A Data_Block manages access to a block of binary data bytes. More...
struct  Point_2D
 A Point_2D holds 2-dimensional position information. More...
struct  Size_2D
 A Size_2D holds 2-dimensional size information. More...
struct  Rectangle
 A Rectangle is a position with a size. More...
struct  Cube
 A Cube is a Rectangle with depth. More...
class  Reference_Counted_Pointer
 A Reference_Counted_Pointer acts like a normal pointer with the addition of reference counting. More...

Typedefs

typedef COORDINATE_TYPE Coordinate_Type
 The integer data type of a coordinate value.
typedef DIMENSIONS_TYPE Dimensions_Type
 The integer data type of a dimension value.

Functions

std::istream & operator>> (std::istream &stream, const Binary_IO::Binder &binder)
 Implements the stream input Binary_IO manipulator operator.
std::ostream & operator<< (std::ostream &stream, const Binary_IO::Binder &binder)
 Implements the stream output Binary_IO manipulator operator.
std::ostream & operator<< (std::ostream &stream, const Data_Block &data_block)
 Prints a description of the Data_Block to a stream.
std::istream & operator>>= (std::istream &stream, Data_Block &data_block)
 Input data bytes from a stream into the data block.
std::ostream & operator<<= (std::ostream &stream, const Data_Block &data_block)
 Output data bytes from the data block into a stream.
std::ostream & operator<< (std::ostream &stream, const Point_2D &point)
 Print a Point_2D description to an output stream.
std::ostream & operator<< (std::ostream &stream, const Size_2D &size)
 Print a Size_2D description to an output stream.
std::ostream & operator<< (std::ostream &stream, const Rectangle &rectangle)
 Print a Rectangle description to an output stream.
std::ostream & operator<< (std::ostream &stream, const Cube &cube)
 Print a Cube description to an output stream.
Coordinate_Type Round (double number)
 Rounds a floating point number to the nearest integer value.
Point_2D operator+ (const Point_2D &point_1, const Point_2D &point_2)
 Add two points.
Point_2D operator- (const Point_2D &point_1, const Point_2D &point_2)
 Subtract one point from another.
Point_2D operator- (const Point_2D &point)
 Get the negation of a point.
Point_2D operator* (const Point_2D &point, double factor)
 Multiply a point by a factor.
Point_2D operator* (double factor, const Point_2D &point)
 Multiply a point by a factor.
Point_2D operator/ (const Point_2D &point, double factor)
 Divide a point by a factor.
Size_2D operator+ (const Size_2D &size_1, const Size_2D &size_2)
 Add two sizes.
Size_2D operator- (const Size_2D &size_1, const Size_2D &size_2)
 Subtract one size from another.
Size_2D operator* (const Size_2D &size, double factor)
 Multiply a size by a factor.
Size_2D operator* (double factor, const Size_2D &size)
 Multiply a size by a factor.
Size_2D operator/ (const Size_2D &size, double factor)
 Divide a size by a factor.
Rectangle operator+ (const Rectangle &rectangle, const Point_2D &point)
 Add a Point_2D offset to a Rectangle.
Rectangle operator+ (const Point_2D &point, const Rectangle &rectangle)
 Add a Point_2D offset to a Rectangle.
Rectangle operator+ (const Rectangle &rectangle_1, const Rectangle &rectangle_2)
 Add two Rectangles.
Rectangle operator- (const Rectangle &rectangle, const Point_2D &point)
 Subtract a Point_2D offset from a Rectangle.
Rectangle operator- (const Rectangle &rectangle_1, const Rectangle &rectangle_2)
 Subtract two Rectangles.
Rectangle operator- (const Rectangle &rectangle)
 Get the negation of a Rectangle.
Rectangle operator+ (const Rectangle &rectangle, const Size_2D &size)
 Add a size amount to a Rectangle.
Rectangle operator+ (const Size_2D &size, const Rectangle &rectangle)
 Add a size amount to a Rectangle.
Rectangle operator- (const Rectangle &rectangle, const Size_2D &size)
 Subtract a size amount from a Rectangle.
Rectangle operator* (const Rectangle &rectangle, double factor)
 Multiply a Rectangle by a factor.
Rectangle operator* (double factor, const Rectangle &rectangle)
 Multiply a Rectangle by a factor.
Rectangle operator/ (const Rectangle &rectangle, double factor)
 Divide a Rectangle by a factor.
Rectangle operator& (const Rectangle &rectangle_1, const Rectangle &rectangle_2)
 Get the intersection of two Rectangles.
Rectangleoperator| (const Rectangle &rectangle_1, const Rectangle &rectangle_2)
 Get the union of two Rectangles.
Cube operator+ (const Cube &cube, int amount)
 Add an amount to a Cube Depth.
Cube operator- (const Cube &cube, int amount)
 Subtract an amount from a Cube Depth.
Cube operator+ (const Cube &cube_1, const Cube &cube_2)
 Add two Cubes.
Cube operator- (const Cube &cube_1, const Cube &cube_2)
 Subtract two Cubes.
Cube operator* (const Cube &cube, double factor)
 Multiply a Cube by a factor.
Cube operator* (double factor, const Cube &cube)
 Multiply a Cube by a factor.
Cube operator/ (const Cube &cube, double factor)
 Divide a Cube by a factor.
Cube operator& (const Cube &cube_1, const Cube &cube_2)
 Get the intersection of two Cubes.
Cubeoperator| (const Cube &cube_1, const Cube &cube_2)
 Get the union of two Cubes.
bool host_is_high_endian ()
 Tests if the host system is high-endian.
void reorder_bytes (unsigned char *data, const unsigned long amount)
 Reorders data bytes.
void reorder_bytes (unsigned char *data, const unsigned long groups, const unsigned int size)
 Reorders data bytes in groups.
void swap_bytes (unsigned char *data, const unsigned int groups, const unsigned int size)
 Swap groups of data bytes.
bool high_endian_host ()
 Tests if the host system is high-endian.
bool big_endian_host ()
 Tests if the host system is big-endian.
bool low_endian_host ()
 Tests if the host system is low-endian.
bool little_endian_host ()
 Tests if the host system is little-endian.
template<typename T >
T & MSB_native (T &value)
 A MSB (high-endian) data value is coerced to/from native byte order.
template<typename T >
T & LSB_native (T &value)
 A LSB (low-endian) data value is coerced to/from native byte order.
bool file_exists (const std::string &pathname)
 Test if a file exists at a pathname.
bool file_is_normal (const std::string &pathname)
 Test if a file at a pathname is a normal file.
bool file_is_directory (const std::string &pathname)
 Test if a file at a pathname is a directory.
bool file_is_link (const std::string &pathname)
 Test if a file at a pathname is a link file.
off_t file_size (const std::string &pathname)
 Get the size of a file.
bool file_is_absolute (const std::string &pathname)
 Test if a pathname is an absolute pathname.
std::string & clean_pathname (std::string &pathname)
 Clean a pathname of redundant segments.
std::string CWD ()
 Get the current working directory of the process.
std::string file_pathname (const std::string &filename)
 Get the full pathname for a filename.
std::string file_pathname (const std::string &directory, const std::string &filename)
 Get the full pathname for a filename.
std::string file_directory (const std::string &pathname)
 Get the leading directory portion of a pathname.
std::string file_directory_pathname (const std::string &pathname)
 Get the leading directory pathname portion of a pathname.
std::string file_name (const std::string &pathname)
 Get the final name portion of a pathname.
std::string file_basename (const std::string &pathname)
 Get the basename of a file's pathname.
std::string file_extension (const std::string &pathname)
 Get a file's extension.
bool file_is_readable (const std::string &pathname)
 Test if a file at a pathname is readable.
bool file_is_writeable (const std::string &pathname)
 Test if a file at a pathname is writeable.
std::string home_directory_pathname ()
 Get the user's home directory pathname.
std::string username ()
 Get the effective username.
unsigned int UID ()
 Get the effective user ID.
unsigned int GID ()
 Get the effective group ID.
std::string hostname ()
 Get the name of the host system.

Variables

const char * Files_ID = "PIRL::Files ($Revision: 2.4 $ $Date: 2010/11/21 20:33:26 $)"
 Module identification name with source code version and date.
const char FILE_PATHNAME_DELIMITER = PATHNAME_DELIMITER
 Host filesystem pathname delimiter ('/').
const char FILE_EXTENSION_DELIMITER = EXTENSION_DELIMITER
 Filename extension delimiter ('.').

Detailed Description

The Planetary Image Research Laboratory.

The Planetary Image Research Laboratory (http://PIRL.LPL.Arizona.edu/) is located at the University of Arizona in the Department of Planetary Sciences and Lunar and Planetary Laboratory (http://www.lpl.arizona.edu/).


Typedef Documentation

typedef COORDINATE_TYPE PIRL::Coordinate_Type

The integer data type of a coordinate value.

typedef DIMENSIONS_TYPE PIRL::Dimensions_Type

The integer data type of a dimension value.


Function Documentation

std::istream& PIRL::operator>> ( std::istream &  stream,
const Binary_IO::Binder &  binder 
) [inline]
std::ostream& PIRL::operator<< ( std::ostream &  stream,
const Binary_IO::Binder &  binder 
) [inline]
std::ostream & PIRL::operator<< ( std::ostream &  stream,
const Data_Block data_block 
)

Prints a description of the Data_Block to a stream.

Parameters:
streamThe ostream to which to print the description.
data_blockThe Data_Block to describe.
Returns:
The stream.
See also:
Data_Block::print(ostream)

References PIRL::Data_Block::print().

std::istream & PIRL::operator>>= ( std::istream &  stream,
Data_Block data_block 
)

Input data bytes from a stream into the data block.

Parameters:
streamThe istream from which to read the data.
data_blockThe Data_Block to receive the data.
Returns:
The stream.
See also:
Data_Block::output(ostream)

References PIRL::Data_Block::input().

std::ostream & PIRL::operator<<= ( std::ostream &  stream,
const Data_Block data_block 
)

Output data bytes from the data block into a stream.

Parameters:
streamThe ostream to which to write the data.
data_blockThe Data_Block to write.
Returns:
The stream.
See also:
Data_Block::output(ostream)

References PIRL::Data_Block::output().

std::ostream & PIRL::operator<< ( std::ostream &  stream,
const Point_2D &  point 
)

Print a Point_2D description to an output stream.

Parameters:
streamThe ostream where the Point_2D will be printed.
pointThe Print_2D to be printed.
Returns:
The stream that was written.

References PIRL::Point_2D::X, and PIRL::Point_2D::Y.

std::ostream & PIRL::operator<< ( std::ostream &  stream,
const Size_2D &  size 
)

Print a Size_2D description to an output stream.

Parameters:
streamThe ostream where the Size_2D will be printed.
sizeThe Size_2D to be printed.
Returns:
The stream that was written.

References PIRL::Size_2D::Height, and PIRL::Size_2D::Width.

std::ostream & PIRL::operator<< ( std::ostream &  stream,
const Rectangle &  rectangle 
)

Print a Rectangle description to an output stream.

Parameters:
streamThe ostream where the Rectangle will be printed.
rectangleThe Rectangle to be printed.
Returns:
The stream that was written.
std::ostream & PIRL::operator<< ( std::ostream &  stream,
const Cube &  cube 
)

Print a Cube description to an output stream.

Parameters:
streamThe ostream where the Cube will be printed.
cubeThe Cube to be printed.
Returns:
The stream that was written.

References PIRL::Cube::Depth.

Coordinate_Type PIRL::Round ( double  number ) [inline]

Rounds a floating point number to the nearest integer value.

The nearest integer value is found by adding 0.5 to the floating point number and truncating the result to the Coordinate_Type integer value. For negative numbers 0.5 is subtracted. Thus a floating point number exactly halfway beteen two integer values is rounded to the absolute larger integer with the sign preserved.

Parameters:
numberThe floating point (double) number to be rounded.
Returns:
The integer value of the rounded number.

Referenced by PIRL::Cube::operator*=(), PIRL::Point_2D::operator*=(), PIRL::Size_2D::operator*=(), PIRL::Cube::operator/=(), PIRL::Size_2D::operator/=(), and PIRL::Point_2D::operator/=().

Point_2D PIRL::operator+ ( const Point_2D &  point_1,
const Point_2D &  point_2 
) [inline]

Add two points.

Parameters:
point_1A Point_2D.
point_2A Point_2D.
Returns:
A Point_2D in which the dimensions are the sum of the dimensions of the specified points.
Point_2D PIRL::operator- ( const Point_2D &  point_1,
const Point_2D &  point_2 
) [inline]

Subtract one point from another.

Parameters:
point_1A Point_2D.
point_2A Point_2D.
Returns:
A Point_2D in which the dimensions are the difference of the dimensions of the specified points.
Point_2D PIRL::operator- ( const Point_2D &  point ) [inline]

Get the negation of a point.

Parameters:
pointA Point_2D.
Returns:
A Point_2D in which the dimensions are the negation of the dimensions of the specified points.

References PIRL::Point_2D::X, and PIRL::Point_2D::Y.

Point_2D PIRL::operator* ( const Point_2D &  point,
double  factor 
) [inline]

Multiply a point by a factor.

Parameters:
pointA Point_2D.
factorA floating point (double) number.
Returns:
A Point_2D in which the dimensions are the dimensions of the specified point multiplied by the factor and rounded.
Point_2D PIRL::operator* ( double  factor,
const Point_2D &  point 
) [inline]

Multiply a point by a factor.

Parameters:
factorA floating point (double) number.
pointA Point_2D.
Returns:
A Point_2D in which the dimensions are the dimensions of the specified point multiplied by the factor and rounded.
Point_2D PIRL::operator/ ( const Point_2D &  point,
double  factor 
) [inline]

Divide a point by a factor.

Parameters:
pointA Point_2D.
factorA floating point (double) number.
Returns:
A Point_2D in which the dimensions are the dimensions of the specified point divided by the factor and rounded.
Size_2D PIRL::operator+ ( const Size_2D &  size_1,
const Size_2D &  size_2 
) [inline]

Add two sizes.

Parameters:
size_1A Size_2D.
size_2A Size_2D.
Returns:
A Size_2D in which the dimensions are the sum of the dimensions of the specified sizes.
Size_2D PIRL::operator- ( const Size_2D &  size_1,
const Size_2D &  size_2 
) [inline]

Subtract one size from another.

N.B.: If the size Dimensions_Type values are an unsigned type (as they are by default) and a size amount to be subtracted is greater than the corresponding dimension value, the result will be zero.

Parameters:
size_1A Size_2D.
size_2A Size_2D.
Returns:
A Size_2D in which the dimensions are the difference of the dimensions of the specified sizes.
Size_2D PIRL::operator* ( const Size_2D &  size,
double  factor 
) [inline]

Multiply a size by a factor.

Parameters:
sizeA Size_2D.
factorA floating point (double) number.
Returns:
A Size_2D in which the dimensions are the dimensions of the specified size multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Size_2D PIRL::operator* ( double  factor,
const Size_2D &  size 
) [inline]

Multiply a size by a factor.

Parameters:
factorA floating point (double) number.
sizeA Size_2D.
Returns:
A Size_2D in which the dimensions are the dimensions of the specified size multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Size_2D PIRL::operator/ ( const Size_2D &  size,
double  factor 
) [inline]

Divide a size by a factor.

Parameters:
sizeA Size_2D.
factorA floating point (double) number.
Returns:
A Size_2D in which the dimensions are the dimensions of the specified size divided by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Rectangle PIRL::operator+ ( const Rectangle &  rectangle,
const Point_2D &  point 
) [inline]

Add a Point_2D offset to a Rectangle.

Parameters:
rectangleA Rectangle.
pointA Point_2D.
Returns:
A Rectangle in which the coordinate point dimensions are the Point_2D have been added to the coordinate point of the Rectangle.
Rectangle PIRL::operator+ ( const Point_2D &  point,
const Rectangle &  rectangle 
) [inline]

Add a Point_2D offset to a Rectangle.

Parameters:
pointA Point_2D.
rectangleA Rectangle.
Returns:
A Rectangle in which the coordinate point dimensions of the Point_2D have been added to the coordinate point of the Rectangle.
Rectangle PIRL::operator+ ( const Rectangle &  rectangle_1,
const Rectangle &  rectangle_2 
) [inline]

Add two Rectangles.

Parameters:
rectangle_1A Rectangle.
rectangle_2A Rectangle.
Returns:
A Rectangle in which the coordinate point dimensions and the size amounts of the two Rectangles have been added.
Rectangle PIRL::operator- ( const Rectangle &  rectangle,
const Point_2D &  point 
) [inline]

Subtract a Point_2D offset from a Rectangle.

Parameters:
rectangleA Rectangle.
pointA Point_2D.
Returns:
A Rectangle in which the coordinate point dimensions of the Point_2D have been subtracted from the coordinate point of the Rectangle.
Rectangle PIRL::operator- ( const Rectangle &  rectangle_1,
const Rectangle &  rectangle_2 
) [inline]

Subtract two Rectangles.

Parameters:
rectangle_1A Rectangle.
rectangle_2A Rectangle.
Returns:
A Rectangle in which the coordinate point dimensions and the size amounts of the two Rectangles have been added.
Rectangle PIRL::operator- ( const Rectangle &  rectangle ) [inline]

Get the negation of a Rectangle.

Parameters:
rectangleA Rectangle.
Returns:
A Rectangle in which the coordinate point dimensions are the negation of the Rectangle's coordinate point; the size is the same.

References PIRL::Size_2D::Height, PIRL::Size_2D::Width, PIRL::Point_2D::X, and PIRL::Point_2D::Y.

Rectangle PIRL::operator+ ( const Rectangle &  rectangle,
const Size_2D &  size 
) [inline]

Add a size amount to a Rectangle.

Parameters:
rectangleA Rectangle.
sizeA Size_2D.
Returns:
A Rectangle in which the size amount has been added to the Rectangle size dimensions; the coordinate point is the same.
Rectangle PIRL::operator+ ( const Size_2D &  size,
const Rectangle &  rectangle 
) [inline]

Add a size amount to a Rectangle.

Parameters:
sizeA Size_2D.
rectangleA Rectangle.
Returns:
A Rectangle in which the size amount has been added to the negation of the Rectangle size dimensions; the coordinate point is the same.
Rectangle PIRL::operator- ( const Rectangle &  rectangle,
const Size_2D &  size 
) [inline]

Subtract a size amount from a Rectangle.

N.B.: If the size Dimensions_Type values are an unsigned type (as they are by default) and a size amount to be subtracted is greater than the corresponding dimension value, the result will be zero.

Parameters:
sizeA Size_2D.
rectangleA Rectangle.
Returns:
A Rectangle in which the size amount has been subtracted from the Rectangle size dimensions; the coordinate point is the same.
Rectangle PIRL::operator* ( const Rectangle &  rectangle,
double  factor 
) [inline]

Multiply a Rectangle by a factor.

Parameters:
rectangleA Rectangle.
factorA floating point (double) number.
Returns:
A Size_2D in which the dimensions are the dimensions of the specified size multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Rectangle PIRL::operator* ( double  factor,
const Rectangle &  rectangle 
) [inline]

Multiply a Rectangle by a factor.

Parameters:
factorA floating point (double) number.
rectangleA Rectangle.
Returns:
A Rectangle in which the size dimensions are the dimensions of the specified Rectangle multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Rectangle PIRL::operator/ ( const Rectangle &  rectangle,
double  factor 
) [inline]

Divide a Rectangle by a factor.

The new size dimensions will be rounded to the nearest Dimensions_Type values.

N.B.: Divide by zero is handled as a special case. If the coordinate value was zero it will remain zero. If the Dimensions_Type has an infinity value (determined by numeric_types) that is used, or its negative if the coordinate value is negative. Otherwise, if the Dimensions_Type is signed the type's max value is used, or the min value if the coordinate value is negative; for an unsigned value the max value is used.

Parameters:
rectangleA Rectangle.
factorA floating point (double) number.
Returns:
A Rectangle in which the dimensions are the dimensions of the specified Rectangle divided by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Rectangle PIRL::operator& ( const Rectangle &  rectangle_1,
const Rectangle &  rectangle_2 
) [inline]

Get the intersection of two Rectangles.

Parameters:
rectangle_1A Rectangle.
rectangle_2A Rectangle.
Returns:
A Rectangle with its position and size set to the intersection of the two Rectangles. If the Rectangles do not intersect this will result in a Rectangle with no area (Width and Height both zero) but the position of the first Rectangle.
Rectangle& PIRL::operator| ( const Rectangle &  rectangle_1,
const Rectangle &  rectangle_2 
) [inline]

Get the union of two Rectangles.

Parameters:
rectangle_1A Rectangle.
rectangle_2A Rectangle.
Returns:
A Rectangle with its position and size set to the union - i.e. the bounding box - of the two Rectangles.
Cube PIRL::operator+ ( const Cube &  cube,
int  amount 
) [inline]

Add an amount to a Cube Depth.

Parameters:
cubeA Cube.
amountAn integer amount to add to the Depth.
Returns:
A Cube in which the amount has been added to the Depth of the other cube.
See also:
Cube::operator+=(int)
Cube PIRL::operator- ( const Cube &  cube,
int  amount 
) [inline]

Subtract an amount from a Cube Depth.

Parameters:
cubeA Cube.
amountAn integer amount to substract from the Depth of the other cube.
Returns:
A Cube in which the amount has been subtracted from the Depth of the other cube.
See also:
Cube::operator-=(int)
Cube PIRL::operator+ ( const Cube &  cube_1,
const Cube &  cube_2 
) [inline]

Add two Cubes.

Parameters:
cube_1A Cube.
cube_2A Cube.
Returns:
A Cube in which the coordinate point dimensions and the size and depth amounts of the two Cubes have been added.
See also:
Cube::operator+=(const Cube&)
Cube PIRL::operator- ( const Cube &  cube_1,
const Cube &  cube_2 
) [inline]

Subtract two Cubes.

Parameters:
cube_1A Cube.
cube_2A Cube.
Returns:
A Cube in which the coordinate point dimensions and the size and depth amounts of the two Cubes have been subtracted.
See also:
Cube::operator-=(const Cube&)
Cube PIRL::operator* ( const Cube &  cube,
double  factor 
) [inline]

Multiply a Cube by a factor.

Parameters:
cubeA Cube.
factorA floating point (double) number.
Returns:
A Cube in which the dimensions are the dimensions of the specified cube multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Cube PIRL::operator* ( double  factor,
const Cube &  cube 
) [inline]

Multiply a Cube by a factor.

Parameters:
factorA floating point (double) number.
cubeA Cube.
Returns:
A Cube in which the dimensions are the dimensions of the specified cube multiplied by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Cube PIRL::operator/ ( const Cube &  cube,
double  factor 
) [inline]

Divide a Cube by a factor.

The new size dimensions will be rounded to the nearest Dimensions_Type values.

N.B.: Divide by zero is handled as a special case. If the coordinate value was zero it will remain zero. If the Dimensions_Type has an infinity value (determined by numeric_types) that is used, or its negative if the coordinate value is negative. Otherwise, if the Dimensions_Type is signed the type's max value is used, or the min value if the coordinate value is negative; for an unsigned value the max value is used.

Parameters:
cubeA Cube.
factorA floating point (double) number.
Returns:
A Cube in which the dimensions are the dimensions of the specified Cube divided by the factor and rounded.
Exceptions:
invalid_argumentIf the factor is negative and the size values Dimensions_Type are an unsigned type (as they are by default).
Cube PIRL::operator& ( const Cube &  cube_1,
const Cube &  cube_2 
) [inline]

Get the intersection of two Cubes.

The intersection the Depths of two Cubes is the minimum Depth; i.e. the two Cubes are assumed to be aligned at the zero X-Y plane.

Parameters:
cube_1A Cube.
cube_2A Cube.
Returns:
A Cube with its position, size and depth set to the intersection with the other Cube. If the Cubes do not intersect this will result in an emtpy Cube (Width, Height and Depth zero) but the position of the first Cube.
Cube& PIRL::operator| ( const Cube &  cube_1,
const Cube &  cube_2 
) [inline]

Get the union of two Cubes.

The union of the Depths of two Cubes is the maximum Depth; i.e. the two Cubes are assumed to be aligned at the zero X-Y plane.

Parameters:
cube_1A Cube.
cube_2A Cube.
Returns:
A Cube with its position, size and depth set to the union - i.e. the bounding volume - of the two Cubes.
bool PIRL::host_is_high_endian (  )

Tests if the host system is high-endian.

A system is high-endian if native multi-byte binary data is ordered most significant byte (MSB) first. In this case the MSB will be at the lowest address of each datum's bytes, with each subsequent byte at a higher address until the least significant byte (LSB) is at the highest address.

Returns:
true if the host system is high-endian; false otherwise.

Referenced by big_endian_host(), PIRL::Data_Block::data_order(), PIRL::Data_Block::get_backwards(), PIRL::Data_Block::get_forwards(), high_endian_host(), little_endian_host(), low_endian_host(), LSB_native(), MSB_native(), PIRL::Data_Block::native_order(), PIRL::Data_Block::put_backwards(), and PIRL::Data_Block::put_forwards().

void PIRL::reorder_bytes ( unsigned char *  data,
const unsigned long  amount 
)

Reorders data bytes.

The bytes are mirrored, in place. The first byte is swapped with the last byte, the second byte is swapped with the next-to-last byte, etc. until all byte pairs have been swapped.

Parameters:
dataA pointer (unsigned char*) to the first byte to be reordered. WARNING: This argument is not checked for NULL.
amountThe number of bytes to be reordered.

Referenced by LSB_native(), MSB_native(), and reorder_bytes().

void PIRL::reorder_bytes ( unsigned char *  data,
const unsigned long  groups,
const unsigned int  size 
)

Reorders data bytes in groups.

The byte groups are mirrored, in place. The first group is swapped with the last group, the second group is swapped with the next-to-last group, etc. until all group pairs have been swapped. The bytes within each group are not swapped; they stay in the same order.

Parameters:
dataA pointer (unsigned char*) to the first byte to be reordered.
groupsThe number of groups to be reordered.
sizeThe number of bytes per group.

References reorder_bytes().

void PIRL::swap_bytes ( unsigned char *  data,
const unsigned int  groups,
const unsigned int  size 
)

Swap groups of data bytes.

The byte groups are swapped in place. The first byte of each group is swapped with the last byte in the group, the second byte is swapped with the next-to-last byte in the group, etc. until all bytes within the group have been reorderd. All byte groups are swapped in the same way.

Parameters:
dataA pointer (unsigned char*) to the first byte to be reordered.
groupsThe number of groups to be reordered. If this is zero nothing is done.
sizeThe number of bytes per group. If this is less than two nothing is done.
bool PIRL::high_endian_host (  ) [inline]

Tests if the host system is high-endian.

See also:
host_is_high_endian()

References host_is_high_endian().

Referenced by PIRL::Binary_IO::get_3(), PIRL::Binary_IO::IO(), and PIRL::Binary_IO::put_3().

bool PIRL::big_endian_host (  ) [inline]

Tests if the host system is big-endian.

See also:
host_is_high_endian()

References host_is_high_endian().

bool PIRL::low_endian_host (  ) [inline]

Tests if the host system is low-endian.

See also:
host_is_high_endian()

References host_is_high_endian().

Referenced by PIRL::Binary_IO::IO().

bool PIRL::little_endian_host (  ) [inline]

Tests if the host system is little-endian.

See also:
host_is_high_endian()

References host_is_high_endian().

template<typename T >
T& PIRL::MSB_native ( T &  value )

A MSB (high-endian) data value is coerced to/from native byte order.

If the host system is high-endian the data is left unchanged; otherwise, it is reordered. Therefore, if the argument value is in MSB order the result is in native order; it the argument value is in native order the result in in MSB order.

N.B.: The data value is reordered in place. Make a copy first if the original datum is to remain unchanged; e.g.:

int tmp_value, value = 1;
cout << MSB_value (tmp_value = value)
     << " = MSB_value (" << value << ')' << endl;

Parameters:
valueA datum to be coerced to MSB byte order. The datum should be a primitive type, otherwise the results are undefined.
Returns:
The value (reference) in MSB order.
See also:
high_endian_host()
reorder_bytes(unsigned char*, const unsigned long, const unsigned int)

References host_is_high_endian(), and reorder_bytes().

template<typename T >
T& PIRL::LSB_native ( T &  value )

A LSB (low-endian) data value is coerced to/from native byte order.

If the host system is low-endian the data is left unchanged; otherwise, it is reordered. Therefore, if the argument value is in LSB order the result is in native order; it the argument value is in native order the result in in LSB order.

N.B.: The data value is reordered in place. Make a copy first if the original datum is to remain unchanged; e.g.:

int tmp_value, value = 1;
cout << LSB_value (tmp_value = value)
     << " = LSB_value (" << value << ')' << endl;

Parameters:
valueA datum to be coerced to LSB byte order. The datum should be a primitive type, otherwise the results are undefined.
Returns:
The value (reference) in LSB order.
See also:
high_endian_host()
reorder_bytes(unsigned char*, const unsigned long, const unsigned int)

References host_is_high_endian(), and reorder_bytes().

bool PIRL::file_exists ( const std::string &  pathname )

Test if a file exists at a pathname.

Parameters:
pathnameThe filesystem pathname to test.
Returns:
true if the file exists; false otherwise.

Referenced by file_is_readable(), file_is_writeable(), and main().

bool PIRL::file_is_normal ( const std::string &  pathname )

Test if a file at a pathname is a normal file.

Parameters:
pathnameThe pathname to test.
Returns:
true if the file is accessable and is a normal type of file; false otherwise.

References S_ISREG.

Referenced by main().

bool PIRL::file_is_directory ( const std::string &  pathname )

Test if a file at a pathname is a directory.

Parameters:
pathnameThe pathname to test.
Returns:
true if the file is accessable and is a directory; false otherwise.

References S_ISDIR.

Referenced by main().

bool PIRL::file_is_link ( const std::string &  pathname )

Test if a file at a pathname is a link file.

Parameters:
pathnameThe pathname to test.
Returns:
true if the file is accessable and is a link; false otherwise.

References file_extension(), and S_ISLNK.

Referenced by main().

off_t PIRL::file_size ( const std::string &  pathname )

Get the size of a file.

N.B.: For MS/Windows a directory always has a file size of zero.

Parameters:
pathnameThe pathname to the file.
Returns:
The size of the file in bytes. This will be -1 if the file could not be accessed. The return data type is off_t, the natural type for a file offset value for the host system.

Referenced by main().

bool PIRL::file_is_absolute ( const std::string &  pathname )

Test if a pathname is an absolute pathname.

An absolute pathname begins with the FILE_PATHNAME_DELIMITER character.

Parameters:
pathnameThe pathname to test.
Returns:
true if the pathname is an absolute pathname; false otherwise.

References FILE_PATHNAME_DELIMITER, PATHNAME_DELIMITER_UNIX, and PATHNAME_DELIMITER_WIN32.

Referenced by file_directory_pathname(), file_pathname(), and main().

std::string & PIRL::clean_pathname ( std::string &  pathname )

Clean a pathname of redundant segments.

All sequences of multiple FILE_PATHNAME_DELIMITER characters are replaced with a single delimiter. All sequences of FILE_PATHNAME_DELIMITER-'.'-FILE_PATHNAME_DELIMITER characters are replaced with a single delimiter. Any trailing FILE_PATHNAME_DELIMITER is removed.

Parameters:
pathnameThe pathname from which to obtain the extension.
Returns:
The cleaned pathname. N.B.: The pathname string is modified in place.

References FILE_PATHNAME_DELIMITER.

Referenced by file_directory_pathname(), file_pathname(), and main().

std::string PIRL::CWD (  )

Get the current working directory of the process.

This is a convenience function for the system getcwd function.

Returns:
The absolute pathname for the current working directory of the process.
Exceptions:
runtime_errorIf the current working directory can not be obtained.

References Files_ID.

Referenced by file_directory_pathname(), file_pathname(), and main().

std::string PIRL::file_pathname ( const std::string &  filename )

Get the full pathname for a filename.

If the filename is relative the current working directory of the process is prepended.

The directory pathname is cleaned before it is returned.

Parameters:
filenameThe filename for which to obtain an absolute pathname.
Returns:
The absolute pathname for the filename.
Exceptions:
runtime_errorIf the current working directory can not be obtained.

References clean_pathname(), CWD(), file_is_absolute(), and FILE_PATHNAME_DELIMITER.

Referenced by main().

std::string PIRL::file_pathname ( const std::string &  directory,
const std::string &  filename 
)

Get the full pathname for a filename.

If the filename is relative the directory is prepended. If the directory is relative the current working directory of the process is prepended to it.

The directory pathname is cleaned before it is returned.

Parameters:
directoryThe directory to prepend to the filename if it is not an absolute pathname.
filenameThe filename for which to obtain an absolute pathname.
Returns:
The absolute pathname for the filename.
Exceptions:
runtime_errorIf the current working directory can not be obtained.

References clean_pathname(), CWD(), file_is_absolute(), and FILE_PATHNAME_DELIMITER.

std::string PIRL::file_directory ( const std::string &  pathname )

Get the leading directory portion of a pathname.

The leading directory portion of a pathname is that substring preceding the last FILE_PATHNAME_DELIMITER, or the empty string if it does not contain the delimiter. N.B.: If the pathname contains only one delimiter that is the first character, then the leading directory pathname is the delimiter (i.e. the filesystem root).

Parameters:
pathnameThe pathname from which to obtain the directory pathname.
Returns:
The directory pathname from the pathname.

References FILE_PATHNAME_DELIMITER.

Referenced by file_directory_pathname(), and main().

std::string PIRL::file_directory_pathname ( const std::string &  pathname )

Get the leading directory pathname portion of a pathname.

The leading directory portion of the pathname is obtained. If it is not an absolute pathname the current working directory of the process is prepended.

The directory pathname is cleaned before it is returned.

Parameters:
pathnameThe pathname from which to obtain the directory pathname.
Returns:
The directory pathname from the pathname.
Exceptions:
runtime_errorIf the current working directory can not be obtained.

References clean_pathname(), CWD(), file_directory(), file_is_absolute(), and FILE_PATHNAME_DELIMITER.

Referenced by main().

std::string PIRL::file_name ( const std::string &  pathname )

Get the final name portion of a pathname.

The final name portion of a pathname is that substring following the last FILE_PATHNAME_DELIMITER, or the entire string if it does not contain the delimiter.

Parameters:
pathnameThe pathname from which to obtain the file's name.
Returns:
The name of the file referenced by the pathname.

References FILE_PATHNAME_DELIMITER.

Referenced by main().

std::string PIRL::file_basename ( const std::string &  pathname )

Get the basename of a file's pathname.

The basename is that portion of the path preceeding the last FILE_EXTENSION_DELIMITER; or the entire string if there it does not contain the delimiter. N.B.: Any directory segments of the pathname are retained in the basename; these can be removed using the file_name method.

Parameters:
pathnameThe pathname from which to obtain the basename.
Returns:
The basename of the pathname.

References FILE_EXTENSION_DELIMITER.

Referenced by main().

std::string PIRL::file_extension ( const std::string &  pathname )

Get a file's extension.

The extension is that portion of the path following the last FILE_EXTENSION_DELIMITER. This will be the empty string if no extension is present or the pathname ends with the delimiter.

Parameters:
pathnameThe pathname from which to obtain the extension.
Returns:
The extension of the file referenced by the pathname.

References FILE_EXTENSION_DELIMITER.

Referenced by file_is_link(), and main().

bool PIRL::file_is_readable ( const std::string &  pathname )

Test if a file at a pathname is readable.

Readability is determined by the system's access method. The file must be readable by the real ID of the process.

Parameters:
pathnameThe pathname to test.
Returns:
true if the file is accessable and can be read; false otherwise.
Exceptions:
runtime_errorIf the file attributes can not be obtained (MS/Windows only).

References file_exists(), GID(), and UID().

Referenced by main().

bool PIRL::file_is_writeable ( const std::string &  pathname )

Test if a file at a pathname is writeable.

Writeability is determined by the system's access method. The file must be writeable by the real ID of the process.

Parameters:
pathnameThe pathname to test.
Returns:
true if the file is accessable and can be written; false otherwise.
Exceptions:
runtime_errorIf the file attributes can not be obtained (MS/Windows only).

References file_exists(), GID(), and UID().

Referenced by main().

std::string PIRL::home_directory_pathname (  )

Get the user's home directory pathname.

Returns:
The pathname of the effective user home directory.
Exceptions:
runtime_errorIf the user info can not be obtained.

Referenced by main().

std::string PIRL::username (  )

Get the effective username.

Returns:
The name of the effective user.
Exceptions:
runtime_errorIf the user info can not be obtained (UNIX only).

Referenced by main().

unsigned int PIRL::UID (  )

Get the effective user ID.

Returns:
The effective user ID value.

Referenced by file_is_readable(), file_is_writeable(), and main().

unsigned int PIRL::GID (  )

Get the effective group ID.

Returns:
The effective group ID value.

Referenced by file_is_readable(), file_is_writeable(), and main().

std::string PIRL::hostname (  )

Get the name of the host system.

Returns:
The name of the host system.

Referenced by main().


Variable Documentation

const char * PIRL::Files_ID = "PIRL::Files ($Revision: 2.4 $ $Date: 2010/11/21 20:33:26 $)"

Module identification name with source code version and date.

Referenced by CWD(), and main().

const char PIRL::FILE_PATHNAME_DELIMITER = PATHNAME_DELIMITER

Host filesystem pathname delimiter ('/').

Referenced by clean_pathname(), file_directory(), file_directory_pathname(), file_is_absolute(), file_name(), file_pathname(), and main().

const char PIRL::FILE_EXTENSION_DELIMITER = EXTENSION_DELIMITER

Filename extension delimiter ('.').

Referenced by file_basename(), file_extension(), and main().