utilities.h File Reference

Header file for general utilities. More...

#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <pwd.h>
#include <math.h>
#include <climits>
#include <cfloat>
#include <algorithm>
#include <iostream>
#include <sstream>
#include <iomanip>
#include <vector>
#include <map>
#include <list>
#include <tuple>
#include <regex>
#include <ctime>
#include "Bstring.h"

Macros
#define	BVERSION   "2.1.4-20230131"
#define	MAXLINELEN   1024
#define	SMALLFLOAT   1e-30
#define	MIN_SIZE_FOR_THREADING   100000
#define	TRIGPRECISION   1e-30
#define	PLANCK   6.626070E-34
#define	ECHARGE   1.602177E-19
#define	EMASS   9.109384E-31
#define	LIGHTSPEED   299792458
#define	COULOMB   1e-7*LIGHTSPEED*LIGHTSPEED
#define	AVOGADRO   6.02214076e23
#define	M_PI   3.14159265358979323846264338327950288
#define	M_PI_2   1.57079632679489661923132169163975144
#define	M_PI_4   0.785398163397448309615660845819875721
#define	TWOPI   6.28318530717958647692528676655900576
#define	MIN2PI   -6.28318530717958647692528676655900576
#define	GOLDEN   1.61803398874989484820458683436563811772
#define	RHO   0.81
#define	VERB_NONE   0
#define	VERB_RESULT   1
#define	VERB_LABEL   2
#define	VERB_PROCESS   4
#define	VERB_STATS   8
#define	VERB_FULL   16
#define	VERB_TIME   32
#define	VERB_MEMORY   64
#define	VERB_DEBUG   128
#define	VERB_DEBUG_STAR   256
#define	VERB_DEBUG_XML   512
#define	VERB_DEBUG_DM   1024
#define	VERB_DEBUG_ND2   2048
#define	VERB_DEBUG_EER   4096
#define	_systype_
#define	_datatype_
#define	FILL_USER   0
#define	FILL_AVERAGE   1
#define	FILL_BACKGROUND   2
#define	FILL_MIN   3
#define	FILL_MAX   4

Enumerations
enum	SysType {   Unknown_System = 0 , BigIEEE = 1 , BigOther = 5 , LittleIEEE = 6 ,   LittleAlpha = 7 , LittleVAX = 8 , LittleOther = 10 }
enum	DataType {   Unknown_Type = 0 , Bit = 1 , UCharacter = 2 , SCharacter = 3 ,   UShort = 4 , Short = 5 , UInteger = 6 , Integer = 7 ,   ULong = 8 , Long = 9 , Float = 10 , Double = 11 }
	Base data type specifier. More...
enum	CompoundType {   TSimple = 0 , TComplex = 1 , TVector2 = 2 , TVector3 = 3 ,   TView = 4 , TRGB = 10 , TRGBA = 11 , TCMYK = 12 ,   TMulti = 99 }
	Compound data type specifier. More...

Functions
ostream &	tab (ostream &out)
int	cmd_line (int argc, char **argv)
	Reconstructs the command line as a global string. More...
Bstring	command_line ()
	Returns the command line. More...
Bstring	command_line_time ()
	Returns the command line and time in a string. More...
string	command_line_time2 ()
string	get_user_name ()
	Returns the user name. More...
void	usage (const char **use, int all)
	Prints usage information. More...
SysType	systype (int show)
	Finds the system type - mostly just for byte order. More...
size_t	system_processors ()
	Returns the number of processors. More...
long	system_memory ()
	Returns system memory size. More...
int	memory_check (long mem_required)
	Checking if there is enough memory, abort if not. More...
int	bexit (int value)
	Exit function for cleanup and debugging. More...
DataType	getdatatype (char letter)
	Get the data type indicated by a single letter code. More...
CompoundType	getcompoundtype (int ch, string sct)
	Get the compound type indicated by a single letter code. More...
int	select_numbers (Bstring &string, int n, int *numsel)
	Converts a string with a selection specification into an integer array. More...
vector< int >	select_numbers (Bstring &string, int n)
int	findNextPowerOf (int startNumber, int powerOf)
	Finds the next greatest number that is a power of a given number. More...
int	get_integer (char *ptr, int len)
	Converts a defined length string into an integer. More...
float	get_float (char *ptr, int len)
	Converts a defined length string into a floating point number. More...
void	swapbytes (unsigned char *v, size_t n)
	Swaps bytes. More...
void	swapbytes (size_t size, unsigned char *v, size_t n)
	Swaps bytes. More...
void	vax2ieee (unsigned char *v, int sb)
	Converts VAX floating point format to IEEE floating point format. More...
double	angle_set_negPI_to_PI (double angle)
	Returns an angle between -PI and PI. More...
double	angle_set_0_to_TWOPI (double angle)
	Returns an angle between 0 and 2*PI. More...
float	remove_negative_zeros (float value0, float threshold)
	Prevent a negative sign from being placed in front of zero value in a text file. More...
size_t	get_chunk_size (size_t datasize)
	Returns the chunk size per thread. More...
size_t	get_chunk_size (size_t datasize, size_t c)
	Returns the chunk size per thread. More...
int	error_show (string message, string file, int line)
	Displays the error with file and line reference. More...

Detailed Description

Header file for general utilities.

Author

Bernard Heymann

Date

Created: 19990722

Modified: 20220713

Macro Definition Documentation

_datatype_

#define _datatype_

_systype_

#define _systype_

AVOGADRO

#define AVOGADRO   6.02214076e23

BVERSION

#define BVERSION   "2.1.4-20230131"

COULOMB

#define COULOMB   1e-7*LIGHTSPEED*LIGHTSPEED

ECHARGE

#define ECHARGE   1.602177E-19

EMASS

#define EMASS   9.109384E-31

FILL_AVERAGE

#define FILL_AVERAGE   1

FILL_BACKGROUND

#define FILL_BACKGROUND   2

FILL_MAX

#define FILL_MAX   4

FILL_MIN

#define FILL_MIN   3

FILL_USER

#define FILL_USER   0

GOLDEN

#define GOLDEN   1.61803398874989484820458683436563811772

LIGHTSPEED

#define LIGHTSPEED   299792458

M_PI

#define M_PI   3.14159265358979323846264338327950288

M_PI_2

#define M_PI_2   1.57079632679489661923132169163975144

M_PI_4

#define M_PI_4   0.785398163397448309615660845819875721

MAXLINELEN

#define MAXLINELEN   1024

MIN2PI

#define MIN2PI   -6.28318530717958647692528676655900576

MIN_SIZE_FOR_THREADING

#define MIN_SIZE_FOR_THREADING   100000

PLANCK

#define PLANCK   6.626070E-34

RHO

#define RHO   0.81

SMALLFLOAT

#define SMALLFLOAT   1e-30

TRIGPRECISION

#define TRIGPRECISION   1e-30

TWOPI

#define TWOPI   6.28318530717958647692528676655900576

VERB_DEBUG

#define VERB_DEBUG   128

VERB_DEBUG_DM

#define VERB_DEBUG_DM   1024

VERB_DEBUG_EER

#define VERB_DEBUG_EER   4096

VERB_DEBUG_ND2

#define VERB_DEBUG_ND2   2048

VERB_DEBUG_STAR

#define VERB_DEBUG_STAR   256

VERB_DEBUG_XML

#define VERB_DEBUG_XML   512

VERB_FULL

#define VERB_FULL   16

VERB_LABEL

#define VERB_LABEL   2

VERB_MEMORY

#define VERB_MEMORY   64

VERB_NONE

#define VERB_NONE   0

VERB_PROCESS

#define VERB_PROCESS   4

VERB_RESULT

#define VERB_RESULT   1

VERB_STATS

#define VERB_STATS   8

VERB_TIME

#define VERB_TIME   32

Enumeration Type Documentation

CompoundType

enum CompoundType

Compound data type specifier.

This determines what compound data type is used in an image.

Enumerator
TSimple
TComplex
TVector2
TVector3
TView
TRGB
TRGBA
TCMYK
TMulti

DataType

enum DataType

Base data type specifier.

This determines what simple data type is used in an image.

Enumerator
Unknown_Type
Bit
UCharacter
SCharacter
UShort
Short
UInteger
Integer
ULong
Long
Float
Double

SysType

enum SysType

Enumerator
Unknown_System
BigIEEE
BigOther
LittleIEEE
LittleAlpha
LittleVAX
LittleOther

Function Documentation

angle_set_0_to_TWOPI()

double angle_set_0_to_TWOPI

(

double

angle

)

Returns an angle between 0 and 2*PI.

Parameters

angle

input angle.

Returns

double angle between 0 and 2*PI.

angle_set_negPI_to_PI()

double angle_set_negPI_to_PI

(

double

angle

)

Returns an angle between -PI and PI.

Parameters

angle

input angle.

Returns

double angle between -PI and PI.

bexit()

int bexit

(

int

value

)

Exit function for cleanup and debugging.

Parameters

value

exit value.

Returns

int given value.

cmd_line()

int cmd_line	(	int	argc,
		char **	argv
	)

Reconstructs the command line as a global string.

Parameters

argc	the number of command line arguments.
**argv	the command line arguments.

Returns

int 0.

Concatenates the command line arguments into one string.

command_line()

Bstring command_line

(

)

Returns the command line.

Returns

Bstring new string.

This is designed to pack the command line into a string.

command_line_time()

Bstring command_line_time

(

)

Returns the command line and time in a string.

Returns

Bstring new string.

This is designed to pack the command line into a string followed by
a second string for the time.

command_line_time2()

string command_line_time2

(

)

error_show()

int error_show	(	string	message,
		string	file,
		int	line
	)

Displays the error with file and line reference.

Parameters

*message	a string to be included.
*file	the file name (should be FILE).
line	the line number (should be LINE).

Returns

int error number.

The function uses perror() to display a message containing the source
file and line number where it originated.

Reference: Derived from CCP4 code

findNextPowerOf()

int findNextPowerOf	(	int	startNumber,
		int	powerOf
	)

Finds the next greatest number that is a power of a given number.

Author

Dan Krainak

Parameters

startNumber	number to begin from.
powerOf	power of this number is the number returned.

Returns

int the next greatest power (i.e. 128) or 0 on error.

Loop through the powerOf variable, multiplying it each successive
iteration until it is greater than the starting number.
Eg., the next greatest power of 2 starting at 100 is 128.

get_chunk_size() [1/2]

size_t get_chunk_size

(

size_t

datasize

)

Returns the chunk size per thread.

Parameters

datasize

size of data to be divided into chunks.

Returns

long chunk size.

If multiple processors are used, the chunk size is set to the data size
divided by the number of processors.
Otherwise, the chunk size is equal to the data size.

Reference: Derived from CCP4 code

get_chunk_size() [2/2]

size_t get_chunk_size	(	size_t	datasize,
		size_t	c
	)

Returns the chunk size per thread.

Parameters

datasize	size of data to be divided into chunks.
c	channel size to align chunk to.

Returns

long chunk size.

If multiple processors are used, the chunk size is set to the data size
divided by the number of processors.
Otherwise, the chunk size is equal to the data size.

Reference: Derived from CCP4 code

get_float()

float get_float	(	char *	ptr,
		int	len
	)

Converts a defined length string into a floating point number.

Parameters

*ptr	pointer to the string.
len	length to be scanned.

Returns

float the floating point number.

The string is copied, 0-terminated, and scanned for a floating point number.

get_integer()

int get_integer	(	char *	ptr,
		int	len
	)

Converts a defined length string into an integer.

Parameters

*ptr	pointer to the string.
len	length to be scanned.

Returns

int the integer.

The string is copied, 0-terminated, and scanned for an integer.

get_user_name()

string get_user_name

(

)

Returns the user name.

Returns

string user name.

It uses getpwuid_r (thread safe) to find the user in the password file.

getcompoundtype()

CompoundType getcompoundtype	(	int	ch,
		string	sct
	)

Get the compound type indicated by a single letter code.

Parameters

ch	number of channels.
sct	string indicating compound type.

Returns

CompoundType compound type.

This function is used in optional command-line arguments to indicate
a new compound type for an image.

getdatatype()

DataType getdatatype

(

char

letter

)

Get the data type indicated by a single letter code.

Parameters

letter

letter indicating data type.

Returns

DataType data type.

This function is used in optional command-line arguments to indicate 
a new data type for an image.

memory_check()

int memory_check

(

long

mem_required

)

Checking if there is enough memory, abort if not.

Parameters

mem_required

memory required.

Returns

int 1 if enough.

remove_negative_zeros()

float remove_negative_zeros	(	float	value0,
		float	threshold
	)

Prevent a negative sign from being placed in front of zero value in a text file.

Author

David Belnap

Parameters

value0	input value to be tested
threshold	a small negative number

Returns

float "Corrected" or input value

This function is intended to be used when obvious zero values are set
to a very small negative number.  Input value is set to zero if
              value0 > threshold  and  value0 < 0
If so, the value is reset to zero.  Otherwise, the input value is 
returned.

Reference: Derived from CCP4 code

select_numbers() [1/2]

vector< int > select_numbers	(	Bstring &	string,
		int	n
	)

select_numbers() [2/2]

int select_numbers	(	Bstring &	string,
		int	n,
		int *	numsel
	)

Converts a string with a selection specification into an integer array.

Parameters

&string	string.
n	length of integer array.
*numsel	pre-allocated integer array.

Returns

int number of levels.

The integer array must be allocated to a length that would accommodate
the highest number in the selection.
If the string length is zero, all elements are selected.
Multiple subsets are separated by colons

swapbytes() [1/2]

void swapbytes	(	size_t	size,
		unsigned char *	v,
		size_t	n
	)

Swaps bytes.

Parameters

size	size of the block to be swapped.
*v	a pointer to the bytes.
n	number of bytes to swap. Byte swapping is done in place.

swapbytes() [2/2]

void swapbytes	(	unsigned char *	v,
		size_t	n
	)

Swaps bytes.

Parameters

*v	a pointer to the bytes.
n	number of bytes to swap. Byte swapping is done in place.

system_memory()

long system_memory

(

)

Returns system memory size.

Returns

long memory size.

system_processors()

size_t system_processors

(

)

Returns the number of processors.

Returns

long number of processors.

systype()

SysType systype

(

int

show

)

Finds the system type - mostly just for byte order.

Parameters

show	a flag to indicate if the result should be shown.

Returns

SysType an enumerated type.

Test the byte order of an arbitrary byte sequence by interpreting it as
an integer or a floating point number.

tab()

ostream & tab

(

ostream &

out

)

usage()

void usage	(	const char **	use,
		int	all
	)

Prints usage information.

Parameters

**use

the string array.

all

flag to output all usage information. The usage information must be written into an array of srings, with each string a line and following a specific convention for the Bsoft package. The first line with non-space characters must start with "Usage:" followed by the command-line syntax. The next lines should describe the program. The options are indicated by lines strating with "-". The options are categorized as "Actions", "Parameters", "Input", and "Output". This constitutes the brief form. An additional section can be added as "Examples", that is shown only when the "all" argument is set.

vax2ieee()

void vax2ieee	(	unsigned char *	v,
		int	sb
	)

Converts VAX floating point format to IEEE floating point format.

Parameters

*v	four-byte array holding the floating point value
sb	flag to swap bytes before conversion Swap bytes prior to conversion if the swap flag is set. Handle special cases of zero, infinity, NaN or normalized values Otherwise assign the new byte values Reference: Derived from CCP4 code