\defmodule {util}

Safe functions to open and close files, to allocate dynamic memory,
to read/write booleans, and to print error messages. 
Some of the ``functions'' are actually implemented as macros, in the
interest of speed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bigskip\hrule
\code\hide
/* util.h  for ANSI C */
#ifndef UTIL_H
#define UTIL_H
\endhide
#include <testu01/gdef.h>
#include <stdio.h>
#include <stdlib.h>
\endcode




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\guisec{Macros}

\noindent 
{\tt util\_Error (S)};

 \tab  Prints the string {\tt S}, then stops the program.
 \endtab
\code
\hide
#define util_Error(S) do { \
   printf ("\n\n******************************************\n"); \
   printf ("ERROR in file %s   on line  %d\n\n", __FILE__, __LINE__); \
   printf ("%s\n******************************************\n\n", S); \
   exit (EXIT_FAILURE); \
   } while (0)
\endhide
\endcode

\noindent 
{\tt util\_Assert (Assertion, S)};

 \tab  If {\tt lebool Assertion} is {\tt FALSE} (= 0), 
  then prints the string {\tt S} and stops the program.
 \endtab
\code
\hide
#define util_Assert(Cond,S) if (!(Cond)) util_Error(S)
\endhide
\endcode

\noindent 
{\tt util\_Warning (Condition, S)};

 \tab  If {\tt lebool Condition} is {\tt TRUE} ($\not = 0$),
 then prints the string {\tt S}.
 \endtab
\code
\hide
#define util_Warning(Cond,S) do { \
   if (Cond) { \
      printf ("*********  WARNING "); \
      printf ("in file  %s  on line  %d\n", __FILE__, __LINE__); \
      printf ("*********  %s\n", S); } \
   } while (0)
\endhide
\endcode


\noindent 
{\tt util\_Max (x, y)};

 \tab  Returns the largest of the two numbers {\tt  x}, {\tt y}.
 \endtab
\code
\hide
#define util_Max(x,y) (((x) > (y)) ? (x) : (y))
\endhide
\endcode


\noindent 
{\tt util\_Min (x, y)};

 \tab  Returns the smallest of the two numbers {\tt  x}, {\tt y}.
 \endtab
\code
\hide
#define util_Min(x,y) (((x) < (y)) ? (x) : (y))
\endhide
\endcode



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\guisec{Prototypes}
\code\hide

lebool util_Freadable (const char *name);
\endhide
\endcode

\code

FILE * util_Fopen (const char *name, const char *mode);
\endcode
  \tab 
  Calls {\tt fopen} (from {\tt stdio.h}) with same arguments, but checks 
  for errors.
  Opens or creates file with name {\tt name} in mode {\tt mode}. Returns a 
  pointer to 
  FILE that is associated with the stream. If {\tt name} cannot be accessed, 
  the program
  stops. 
 \endtab
\code


int util_Fclose (FILE *stream);
\endcode
  \tab 
   Calls {\tt fclose} (from {\tt stdio.h}) with same arguments, but checks 
   for errors.
   Closes the file associated with {\tt stream}. If the file is successfully 
   closed, {\tt 0}
   is returned. If an error occurs or the file was already closed, {\tt EOF} 
   is returned.
 \endtab
\code


int util_GetLine (FILE *file, char *Line, char c);
\endcode
  \tab
  Reads a line of data from {\tt file}. Blank lines and comments are
  ignored. A comment is any line whose first non-whitespace character
  is {\tt c}. If the character {\tt c} appears anywhere on a line that is
  not a comment, then  {\tt c} and the rest of the line are ignored too. 
  The function returns $-1$ if end-of-file or an error is encountered,
  otherwise it returns 0.
  \endtab
\code


void util_ReadBool (char S[], lebool *x);
\endcode
  \tab
  Reads a {\tt lebool} value from string {\tt S} and returns it in  $x$.
  The possible values are  {\tt TRUE} and  {\tt FALSE}.
  \endtab
\code


void util_WriteBool (lebool x, int d);
\endcode
  \tab
  Writes the value of $x$ in a field of width $d$. If $d < 0$, 
  $x$ is left-justified, otherwise right-justified. 
  \endtab
\code


void * util_Malloc (size_t size);
\endcode
  \tab
  Calls {\tt malloc} (from {\tt stdlib.h}) with same arguments, but checks 
  for errors.
  Allocates memory large enough to hold an object of size {\tt size}. A 
  successful call
  returns the base address of the allocated space, otherwise the 
  programs stops. The standard type {\tt size\_t} is defined in {\tt stdio.h}.
 \endtab
\code


void * util_Calloc (size_t dim, size_t size);
\endcode
  \tab 
  Calls {\tt calloc} (from {\tt stdlib.h}) with same arguments, but checks 
  for errors.
  Allocates memory large enough to hold an array of {\tt dim} 
  objects each of size {\tt size}. A successful call
  returns the base address of the allocated space, otherwise the programs 
  stops. The standard type {\tt size\_t} is defined in {\tt stdio.h}.
 \endtab
\code


void * util_Realloc (void *ptr, size_t size);
\endcode
  \tab Calls {\tt realloc} (from {\tt stdlib.h}) with same arguments, but 
  checks for errors.
  Takes a pointer to a memory region previously allocated and referenced by
  {\tt ptr}, then changes its
  size to {\tt size} while preserving its content.
% The function attempts to  keep the same base address for the block, 
% but if it is not possible, it allocates a new block of  memory, 
% copying the relevant portion of the old block and deallocating it. 
  A successful call
  returns the base address of the resized (or new) space, otherwise the 
  programs stops. The standard type {\tt size\_t} is defined in {\tt stdio.h}.
 \endtab
\code


void * util_Free (void *p);
\endcode
  \tab Calls {\tt free (p)} (from {\tt stdlib.h}) to free
  memory allocated by {\tt util\_Malloc},
   {\tt util\_Calloc} or {\tt util\_Realloc}. Always returns the
  {\tt NULL} pointer.
 \endtab
\code

\hide
#endif
\endhide
\endcode