Bioplib
Protein Structure C Library
 All Data Structures Files Functions Variables Typedefs Macros Pages
Data Structures | Macros | Typedefs | Functions
general.h File Reference

Header file for general purpose routines. More...

#include <stdio.h>
#include "SysDefs.h"
#include "MathType.h"
#include "deprecated.h"

Go to the source code of this file.

Data Structures

struct  _stringlist
 

Macros

#define FREESTRINGLIST(l)
 
#define _GENERAL_H_DEPRECATED
 

Typedefs

typedef struct _stringlist STRINGLIST
 

Functions

void blStringToLower (char *string1, char *string2)
 
void blStringToUpper (char *string1, char *string2)
 
char * blKillLeadSpaces (char *string)
 
void blKillLine (FILE *fp)
 
void blSetExtn (char *File, char *Ext)
 
int blChindex (char *string, char ch)
 
void blWord (char *string1, char *string2)
 
void blWordN (char *string1, char *string2, int MaxChar)
 
void blPadterm (char *string, int length)
 
void blPadchar (char *string, int length, char ch)
 
BOOL blCheckExtn (char *string, char *ext)
 
char * blFtostr (char *str, int maxlen, REAL x, int precision)
 
void blGetFilestem (char *filename, char *stem)
 
int blUpstrcmp (char *word1, char *word2)
 
int blUpstrncmp (char *word1, char *word2, int ncomp)
 
char * blGetWord (char *buffer, char *word, int maxsize)
 
char ** blSplitStringOnCommas (char *string, int minItemLen)
 
char ** blSplitStringOnChars (char *string)
 
BOOL blOpenStdFiles (char *infile, char *outfile, FILE **in, FILE **out)
 
FILE * blOpenFile (char *filename, char *envvar, char *mode, BOOL *noenv)
 
int blCountchar (char *string, char ch)
 
char * blFgetsany (FILE *fp)
 
char * blStrcatalloc (char *instr, char *catstr)
 
char * blStrncat (char *out, const char *in, size_t len)
 
STRINGLISTblStoreString (STRINGLIST *StringList, char *string)
 
BOOL blInStringList (STRINGLIST *StringList, char *string)
 
void blFreeStringList (STRINGLIST *StringList)
 
char * blQueryStrStr (char *string, char *substring)
 
void blIndexReal (REAL *arrin, int *indx, int n)
 
FILE * blOpenOrPipe (char *filename)
 
int blCloseOrPipe (FILE *fp)
 
BOOL blWrapString (char *in, char *out, int maxlen)
 
BOOL blWrapPrint (FILE *out, char *string)
 
void blRightJustify (char *string)
 
char * blGetWordNC (char *buffer, char *word, int maxlen)
 
void blGetfield (char *buffer, int start, int width, char *str)
 
BOOL blCheckProgName (char *name, char *expected)
 
char * blCollapseSpaces (char *inText)
 

Detailed Description

Header file for general purpose routines.

Version
V1.21
Date
26.06.15
Author
Dr. Andrew C. R. Martin
Institute of Structural & Molecular Biology, University College London, Gower Street, London. WC1E 6BT.
andre.nosp@m.w@bi.nosp@m.oinf..nosp@m.org..nosp@m.uk andre.nosp@m.w.ma.nosp@m.rtin@.nosp@m.ucl..nosp@m.ac.uk

This code is NOT IN THE PUBLIC DOMAIN, but it may be copied according to the conditions laid out in the accompanying file COPYING.DOC.

The code may be modified as required, but any modifications must be documented so that the person responsible can be identified.

The code may not be sold commercially or included as part of a commercial product except as described in the file COPYING.DOC.

Description:

Usage:

Revision History:

Definition in file general.h.

Macro Definition Documentation

#define _GENERAL_H_DEPRECATED

Definition at line 145 of file general.h.

#define FREESTRINGLIST (   l)
Value:
do { \
STRINGLIST *_s = NULL; \
for(_s = (l); _s != NULL; NEXT(_s)) { \
if(_s->string != NULL) free(_s->string); \
} \
} \
while(0)
#define NULL
Definition: array2.c:99
#define NEXT(x)
Definition: macros.h:249
#define FREELIST(y, z)
Definition: macros.h:264
struct _stringlist STRINGLIST

Definition at line 88 of file general.h.

Typedef Documentation

typedef struct _stringlist STRINGLIST

Function Documentation

BOOL blCheckExtn ( char *  string,
char *  ext 
)
Parameters
[in]*stringString to be checked for given extension
[in]*extExtension to check for
Returns
Found?

Check the extension of a filename. For use on machines like VAXes, MS-DOS and Amigas, everything is converted to upper case first.

  • 18.06.93 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 120 of file CheckExtn.c.

BOOL blCheckProgName ( char *  progname,
char *  expected 
)
Parameters
[in]*filenameA PDB filename containing a PDB code
Returns
The PDB code (lower case) NULL if memory allocation fails XXXX if filename blank or NULL or if unable to find PDB code

This routine attempts to convert a filename stem to a PDB code.

  • 12.03.15 Original By: ACRM

Definition at line 95 of file filename.c.

int blChindex ( char *  string,
char  ch 
)
Parameters
[in]*stringA string
[in]chA character for which to search
Returns
The offset of ch in string.

Returns the offset of a character in a string. -1 if not found. This is used in a similar manner to strchr(), but gives an offset in the string rather than a pointer to the character.

  • 10.02.91 Original
  • 28.05.92 ANSIed
  • 06.10.93 Changed name to chindex() to avoid UNIX name clash
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 122 of file chindex.c.

int blCloseOrPipe ( FILE *  fp)
Parameters
[in]*fpFile pointer to be closed
Returns
Error code (as for fclose())

Attempts to close a file pointer as a pipe. If it isn't associated with a pipe (i.e. pclose returns (-1)), tries again to close it as a normal file.

  • 26.05.97 Original By: ACRM
  • 26.06.97 Added call to signal()
  • 28.01.05 Added NOPIPE define
  • 02.04.09 Moved 'int ret' to be in the #else
  • 07.07.14 Use bl prefix for functions By: CTP
  • 17.07.14 Added check that the file pointer isn't stdout By: ACRM

Definition at line 172 of file openorpipe.c.

char* blCollapseSpaces ( char *  inText)
Parameters
[in]*inTextInput text string
Returns
malloc()'d string with multiple spaces collapsed

Takes a string and collapses multiple spaces down to a single space Equivalent of perl 's/+/ /g' The input string is unmodified and malloc()s the output.

28.04.15 Original By: ACRM

Definition at line 108 of file stringutil.c.

int blCountchar ( char *  string,
char  ch 
)
Parameters
[in]*stringString to search for characters
[in]chCharacter for which to search
Returns
Number of occurrences of ch in string

Counts occurrences of charcater ch in string, string.

  • 17.07.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 115 of file countchar.c.

char* blFgetsany ( FILE *  fp)
Parameters
[in]*fpFile pointer open for reading
Returns
Allocated string or NULL on EOF and no memory (errno==ENOMEM)

blFgetsany() provides a routine like fgets() for reading strings from a file, but does not require you to impose a limit on the length of string which may be read. blFgetsany() allocates memory to store a string of any length and returns a pointer to that allocated memory. After use, this memory must be freed by the calling routine.

blFgetsany() returns NULL on end-of-file and if memory allocation failed. It uses the global `errno' variable to indicate a memory allocation failure (errno==ENOMEM).

  • 11.09.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 143 of file fgetsany.c.

void blFreeStringList ( STRINGLIST StringList)
Parameters
[in]*StringListLinked list of strings

Frees memory allocated for a string list.

  • 06.11.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 122 of file FreeStringList.c.

char* blFtostr ( char *  str,
int  maxlen,
REAL  x,
int  precision 
)
Parameters
[out]*strString version of number
[in]maxlenMax length for f-form. Switches to e-form if exceeded
[in]xNumber to convert
[in]precisionNumber of decimal places If negative, use e-form rather than f-form
Returns
Same as str

Convert a REAL to a string using precision decimal places. If precision is negative, use e-form, otherwise use f-form. This is used to generate precisely formatted string versions of numbers for applications where the appearance of a numeric value is important.

  • 01.07.92 Original
  • 07.07.92 Changed to stop value of -0.0
  • 24.07.92 Added maxlen parameter. If the f-form will exceed this number of characters we switch to e-form autmatically
  • 28.07.92 If precision -ve, is never < maxlen-5
  • 27.07.93 Changed to double precision I/O
  • 09.10.97 If precision is 0 prints as an integer since C libraries handle "%.0f" inconsistently
  • 14.11.97 Oops, had forgotten to fix this in the check for e-form
  • 03.06.05 Tidied up some loops to stop warnings under GCC 3.2.2
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 133 of file ftostr.c.

void blGetfield ( char *  buffer,
int  start,
int  width,
char *  str 
)
Parameters
[in]*bufferBuffer from which to read a field
[in]startStarting column (count from 0)
[in]widthWidth of field to read
[out]*strField read from buffer

Reads a column out of a buffer. If the specfied column extends beyond the size of the buffer, then it will be padded with spaces.

Note that the output string must be of at lease width+1 characters to store the field read from the buffer plus the terminating character.

  • 30.05.02 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 99 of file getfield.c.

void blGetFilestem ( char *  filename,
char *  stem 
)
Parameters
[in]*filenameComplete filename
[out]*stemThe filestem

Extracts the filestem from a complete filename. Should work under Unix, VMS, MS-DOS, AmigaDOS, etc.

  • 14.04.94 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 116 of file GetFilestem.c.

char* blGetWord ( char *  buffer,
char *  word,
int  maxlen 
)
Parameters
[in]*bufferInput buffer to read words from
[in]maxlenMax length of output word
[out]*wordWord read from buffer
Returns
Pointer to start of next word in buffer or NULL

This code is a wrapper to doGetWord()

Reads a whitespace/comma delimited word out of buffer into word.

Words containing white space may be wrapped in double inverted commas. A \ is used as an escape character and maybe used to escape any following character. In particular: "\\" -> '\' To get a backslash "\ " -> ' ' To get a hard whitespace (alternatively wrap the string in double inverted commas) "\"" -> '"' To get a double inverted comma

  • 10.06.99 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 268 of file GetWord.c.

char* blGetWordNC ( char *  buffer,
char *  word,
int  maxlen 
)
Parameters
[in]*bufferInput buffer to read words from
[in]maxlenMax length of output word
[out]*wordWord read from buffer
Returns
Pointer to start of next word in buffer or NULL

This code is a wrapper to doGetWord()

Reads a whitespace delimited word out of buffer into word. Commas are treated just like normal characters.

Words containing white space may be wrapped in double inverted commas. A \ is used as an escape character and maybe used to escape any following character. In particular: "\\" -> '\' To get a backslash "\ " -> ' ' To get a hard whitespace (alternatively wrap the string in double inverted commas) "\"" -> '"' To get a double inverted comma

  • 10.06.99 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 300 of file GetWord.c.

void blIndexReal ( REAL arrin,
int *  indx,
int  n 
)
Parameters
[in]*arrinArray to be indexed
[in]nNumber of elements in array
[out]*indxIndex array

Index an array by Heapsort.

  • 03.06.90 Original
  • 01.06.92 ANSIed and autodoc'd
  • 19.07.93 Corrected bug (said j=l+1 rather than j=l+l). Oops!
  • 08.07.96 Changed from double to REAL and tidied. Changed param order
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 110 of file IndxReal.c.

BOOL blInStringList ( STRINGLIST StringList,
char *  string 
)
Parameters
[in]*StringListLinked list of strings
[in]*stringString for which to search
Returns
Is string found?

Searches a string list for an exact match with the specified string.

  • 06.11.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 118 of file InStringList.c.

char* blKillLeadSpaces ( char *  string)
Parameters
[in]*stringA character string
Returns
A pointer to the string with the leading spaces removed

This routine strips leading spaces and tabs from a string returning a pointer to the first non-whitespace character.

N.B. THE MACRO KILLLEADSPACES() MAY NOW BE USED INSTEAD

  • 06.02.91 Original
  • 28.05.92 ANSIed
  • 06.07.93 Added tab skipping
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 121 of file KillLeadSpaces.c.

void blKillLine ( FILE *  fp)
Parameters
[in]*fpA file pointer

This routine reads characters from a file till it reaches a '
' or the end of file.

  • 08.02.91 Original
  • 28.05.92 ANSIed
  • 18.03.94 getc() -> fgetc()
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 117 of file KillLine.c.

FILE* blOpenFile ( char *  filename,
char *  envvar,
char *  mode,
BOOL noenv 
)
Parameters
[in]*filenameFilename to be opened
[in]*envvarUnix/MS-DOS environment variable Other OS assign name (with :)
[in]*modeMode in which to open file (r, w, etc)
[out]*noenvSet to TRUE under Unix/MS-DOS if the reason for failure was that the environment variable was not set.
Returns
File pointer or NULL on failure

Attempts to open a filename as specified. Returns a file pointer. If this fails:

Under UNIX/MS-DOS: gets the contents of the envvar environment variable and prepends that to the filename and tries again. If envvar was not set, noenv is set to TRUE and the routine returns a NULL pointer.

Under other OSs: prepends the envvar string onto the filename and tries to open the file again.

Returns the pointer returned by the open() command after all this.

  • 22.09.94 Original By: ACRM
  • 11.09.94 Puts a : in for the assign type.
  • 24.11.94 Added unix define. Checks for trailing / in environment variable
  • 08.03.95 Corrected basename to filename in non-unix version
  • 09.03.95 Checks that filename is not a NULL or blank string
  • 28.07.05 Added conditionals for Mac OS/X: __MACH and APPLE
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 146 of file OpenFile.c.

FILE* blOpenOrPipe ( char *  filename)
Parameters
[in]*filenameA file or pipe to be opened
Returns
A file pointer

Opens a file for writing unless the filename begins with a | in which case it is opened as a pipe.

Broken pipe signals are ignored.

  • 26.05.97 Original By: ACRM
  • 26.06.97 Added call to signal()
  • 18.08.98 Added case to popen() for SunOS
  • 28.01.05 Added NOPIPE define
  • 07.07.14 Use bl prefix for functions By: CTP
  • 17.07.14 Added special 'stdout' file By: ACRM

Definition at line 128 of file openorpipe.c.

BOOL blOpenStdFiles ( char *  infile,
char *  outfile,
FILE **  in,
FILE **  out 
)
Parameters
[in]*infileInput filename
[in]*outfileOutput filename
[out]**inInput file pointer
[out]**outOutput file pointer
Returns
Success?

Open the files if specified. In and out are not modified if files are not specified.

  • 29.06.94 Original By: ACRM
  • 24.08.94 Name changed from OpenFiles() and placed in gen lib.
  • 18.12.95 Now treats a filename of - as stdin/stdout
  • 05.02.96 Allows NULL pointers
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 126 of file OpenStdFiles.c.

void blPadchar ( char *  string,
int  length,
char  ch 
)
Parameters
[in,out]*stringString to be padded with spaces
[in]lengthRequired size for string
[in]chCharacter with which to pad

Pads a string with a specified character to length characters, then terminates it.

  • 18.09.96 Original based on padterm() By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 119 of file padchar.c.

void blPadterm ( char *  string,
int  length 
)
Parameters
[in,out]*stringString to be padded with spaces
[in]lengthRequired size for string

Pads a string with spaces to length characters, then terminates it.

  • 06.09.91 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 117 of file padterm.c.

char* blQueryStrStr ( char *  string,
char *  substring 
)

This is like strstr() but allows a ? character in the substring which matches any character.

  • 15.12.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 113 of file QueryStrStr.c.

void blRightJustify ( char *  string)
Parameters
[in,out]*stringA string

Right justifies a string in place

  • 30.05.02 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 90 of file justify.c.

void blSetExtn ( char *  File,
char *  Ext 
)
Parameters
[in,out]*FileFilename to be modified
[in]*ExtNew extension

Force a filename extension. Modifies the input filename to have the specified extension. Note that the string File should be large enough to cope with longer extensions, if required. Searches back through the string to find a `.' Anything after this is replaced with the specified extension. The search for a `.' stops as soon as a `/',`\', or a `:' is found as these indicate a directory. If no `.' is found, one is appended to the string and the extension is added.

  • 10.02.91 Original
  • 28.05.92 ANSIed
  • 22.06.92 Improved to work from end of string for Unix filenames, etc.
  • 11.03.94 Added check on '\' for MS-DOS
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 125 of file SetExtn.c.

char** blSplitStringOnChars ( char *  string)
Parameters
[in]*stringString containing comma-separated items
Returns
Malloc'd array of strings

Splits a string into a list of items malloc'ing a 2D array which contains the item strings. The first dimension will be the number if items plus one. The second dimension will be 2 - a single charcater plus the \0

The last position in the first array will be set to a null string

Note that this routine malloc's a 2D array which will need to be freed

  • 12.03.15 Original By: ACRM

Definition at line 394 of file GetWord.c.

char** blSplitStringOnCommas ( char *  string,
int  minItemLen 
)
Parameters
[in]*stringString containing comma-separated items
[in]minItemLengthMin size to allocate for each item
Returns
Malloc'd array of strings

Splits a comma separated list of items malloc'ing a 2D array which contains the item strings. The first dimension will be the number if items plus one. The second dimension will be the maximum item length plus one, or at least minItemLen.

The last position in the first array will be set to a null string

Note that this routine malloc's a 2D array which will need to be freed

  • 10.03.15 Original By: ACRM

Definition at line 325 of file GetWord.c.

STRINGLIST* blStoreString ( STRINGLIST StringList,
char *  string 
)
Parameters
[in]*StringListThe current linked list or NULL if nothing yet allocated
[in]*stringThe string to store
Returns
Start of linked list. Used on first call (when input StringList is NULL) to return the pointer to the start of the linked list. NULL if unable to allocate.

Stores strings (of any length) in a linked list of type STRINGLIST. Return a pointer to the start of the linked list which is used on the first call to access the newly allocated memory.

If allocation fails, memory allocated so far is freed and the routine returns NULL.

  • 06.11.95 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 131 of file StoreString.c.

char* blStrcatalloc ( char *  instr,
char *  catstr 
)
Parameters
[in]*instrString to append to
[in]*catstrString to append
Returns
realloc'd version of instr with catstr appended

Like strcat() but uses a realloc() on instr to make space available.

  • 22.05.99 Original By: ACRM
  • 16.06.99 Initialise outstr to NULL
  • 25.08.99 Fixed bug where testing for NULL outstr instead of catstr
  • 11.07.00 Check that realloc succeeded
  • 07.07.14 Use bl prefix for functions By: CTP
  • 26.06.15 Corrected checks on instr and catstr being null By: ACRM

Definition at line 100 of file strcatalloc.c.

void blStringToLower ( char *  string1,
char *  string2 
)
Parameters
[in]*string1A character string
[out]*string2Lower case version of string1

This routine converts a lower or mixed case string to lower case.

  • 06.02.91 Original
  • 28.05.92 ANSIed
  • 07.01.93 Checks case before converting for SysV
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 119 of file StringToLower.c.

void blStringToUpper ( char *  string1,
char *  string2 
)
Parameters
[in]*string1A character string
[out]*string2Upper case version of string1

This routine converts a lower or mixed case string to upper case.

  • 06.02.91 Original
  • 28.05.92 ANSIed
  • 07.01.93 Checks case before converting for SysV
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 119 of file StringToUpper.c.

char* blStrncat ( char *  out,
const char *  in,
size_t  len 
)
Parameters
[in]*inInput string to be appended
[in]lenLength of output string
[in,out]*outString that we are appending to

A simpler version of strncat. strncat takes the max number of chars to be appended whereas this takes the max number of chars that 'out' can hold.

  • 16.01.15 Original By: ACRM
  • 04.06.15 Fixed - was subtracting the input string length as well!

Definition at line 97 of file stringcat.c.

int blUpstrcmp ( char *  word1,
char *  word2 
)
Parameters
[in]*word1First word
[in]*word2Second word
Returns
0 if strings match or offset of first mismatched character

Like strcmp(), but upcases each character before comparison

  • 20.04.94 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 116 of file upstrcmp.c.

int blUpstrncmp ( char *  word1,
char *  word2,
int  ncomp 
)
Parameters
[in]*word1First word
[in]*word2Second word
[in]ncompNumber of characters to compare
Returns
0 if strings match or offset of first mismatched character

Like strncmp(), but upcases each character before comparison

  • 20.04.94 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 116 of file upstrncmp.c.

void blWord ( char *  string1,
char *  string2 
)
Parameters
[in]*string1A string
[out]*string2A new string

Removes leading spaces and extracts a space/tab delimited word. string2 must have the same amount of space as string1.

  • 20.03.91 Original
  • 28.05.92 ANSIed
  • 22.06.92 Added tab check.
  • 29.03.01 Changed to use KILLLEADSPACES macro
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 121 of file Word.c.

void blWordN ( char *  string1,
char *  string2,
int  MaxChar 
)
Parameters
[in]*string1A string
[in]MaxCharMax characters to copy
[out]*string2A new string

Removes leading spaces and extracts a space/tab delimited word. A maximum of MaxChar characters will be copied into the word. If necessary a terminating NULL will be added after MaxChar other characters. Thus MaxChar should always be at least 1 smaller than the size of string2.

  • 22.06.92 Original based on Word()
  • 29.03.01 Changed to use KILLLEADSPACES() macro
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 122 of file WordN.c.

BOOL blWrapPrint ( FILE *  out,
char *  string 
)
Parameters
[in]*outOutput file pointer
[in]*stringString to be printed
Returns
OK?

Wraps a string with double inverted commas if it contains spaces and escapes any contained double inverted commas with a backslash. Allocates memory for temporary storage of the wrapped string. Returns FALSE if this memory allocation failed.

  • 30.05.02 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 204 of file wrapprint.c.

BOOL blWrapString ( char *  in,
char *  out,
int  maxlen 
)
Parameters
[in]*inInput string
[in]maxlenMax length of output string
[out]*outOutput wrapped string
Returns
Output string was long enough

Wraps a string with double inverted commas if it contains spaces and escapes any contained double inverted commas with a backslash. If the output string wasn't big enough, then the routine just returns FALSE without copying anything into the output string.

  • 30.05.02 Original By: ACRM
  • 07.07.14 Use bl prefix for functions By: CTP

Definition at line 104 of file wrapprint.c.