Constants
MAXBUF
REALLOC_INCR


Types
Boolean
BYTE


Variables
endian

Functions
Safe
MALLOC
CALLOC
REALLOC
FOPEN

Logging
debug
die
info
pb_create
pb_update
pb_finish
status
warn
yield

Binary

numbytes
bget
bset

String
STREQ
chomp
endsWith
ltrim
rtrim
trim
split
strip_comments

Array
dcompare
icompare
fcompare
create_matrix
free_matrix
push
pop

Misc
min
max
swap_int
swap_short




libutils

Detailed Documentation

Constants

MAXBUF
Used frequently throughout the library as a very large number to (hopefully) avoid overflowing buffers (unintentionally).

REALLOC_INCR
Various functions allow for growing arrays as needed. Rather than use the exponential approach (increasing by a power of two each time) I simply reallocate every REALLOC_INCR time.


Types

Boolean
Everyone needs a boolean type. It is an int, supported by enumeration of False and True.

BYTE
And everyone could use a byte type. It's easier than typing unsigned char, at least.

Variables

int endian
The endianess of the computer the library was built on, either SYS_BIG_ENDIAN or SYS_LITTLE_ENDIAN.


Functions

Safe

MALLOC(size)
malloc space of size or die with error message.

CALLOC(n,size)
calloc n elements of size or die with error message.

REALLOC(ptr, size)
realloc ptr to space of size or die with error message.

FOPEN(filename,mode)
Open filename with given mode or die with error message.

Logging

debug(level,str,...)
If level is greater than external int variable debug_level, log message (printf style).

die(str,...)
Logs a message (printf style) with line number and source file. Terminates the program. Think perl die.

info(str, ...)
Log a informational message (printf style). In text mode, logs to stderr.

pb_create(maxvalue, msg, ...)
Create a progress bar with maxvalue points, using the message msg (printf style). Returns progress bar handle.

pb_update(pb, value, msg, ...)
Update the progress bar pb to value, and update message to msg (printf style).

pb_finish(pb)
Finish the progress bar pb and dismiss (if GUI).

status(str,...)
Logs a status message (printf style). In text mode, logs to stderr.

warn(str,...)
Logs a warning message (printf style) with line number and source file (useful for unusual conditions). In text mode, logs to stderr.

yield()
Yield control of processing to a GUI, if used. This is a useful breakpoint mechanism such that the GUI can update and potentially cancel operation.

Binary String Operations

numbytes(b)
Returns the number of bytes required to store b bits.

bget(v, n)
Returns the value (0,1) of bit n in bit string (BYTE *) v.

bset(v,n,val)
Sets bit n of bit string (BYTE *) v to the value of val (0,1).

String

STREQ(a,b)
Returns True (1) if a and b are equal (ignoring case), otherwise False (0).

chomp(s)
Remove the last character from string s.

endsWith(str,sub)
Returns True if str ends with the string sub, in a case insensitive comparison.

ltrim(str)
Trim whitespace from the left portion of str.

rtrim(str,end)
Trim whitespace from the right portion of str as pointed to by end.

trim(str)
Trim whitespace from both left and right ends of str.

split(str, splitval)
Split the str into individual strings (char **) based on the character splitval. For example, split("This=that",'=') returns {"This","that"}.

strip_comments(p,c)
Remove comments (the character c and everything after) in the string p.

Array

dcompare(d1,d2)
Double-type compare routine for quicksort.

fcompare(f1,f2)
Float-type compare routine for quicksort.

icompare(i1,i2)
Int-type compare routine for quicksort.

create_matrix(rows,cols)
Create a double **matrix of size rows by cols. The matrix will actually be an array of pointers to double arrays (rather than a 2D table).

free_matrix(mat)
Free space allocated to mat by a previous call to create_matrix.

push(array, element, arraycount)
Push element onto array at position arraycount, reallocating storage if necessary. As the name implies, it must be added to the end of the array (i.e. arraycount-1 must be the last valid entry in the array). For example, push(intarray, 5, cntr++);

pop(array, arraycount)
Remove the last element of array (at position arraycount). For example, int val=pop(intarray,cntr--)

Misc

min(x,y)
Safely return the minimum value of x and y, with no side effects.

max(x,y)
Safely return the maximum value of x and y, with no side effects.

swap_int(val)
Swap bytes of an integer around.

swap_short(val)
Swap bytes of a short int around.