\documentstyle[html,12pt,a4]{article}

\newcommand{\C}{{\bf C}}
\newcommand{\tty}[1]{{\bf #1}}
\newcommand{\safec}{\tty{safe-c}}
\newcommand{\hot}[2]{\htmladdnormallinkfoot{#1}{#2}}

\newcommand{\qt}[1]{{\tt "}#1{\tt "}}

\begin{htmlonly}
\renewcommand{\qt}[1]{"#1"}
\end{htmlonly}

\begin{document}

\title{The \safec\ User Guide}
\author{Barry McMullin}
\date{(Last Revised: 12th January 1996)}
\maketitle


\section{Introduction}

\safec\ is a \C\ module for \qt{safe} (or, at least, \qt{safer})
programming in C. It provides a collection of \C\ functions,
with related data types and constants. These permit the
development of basic \C\ programs, {\em without} recourse to the
standard \C\ library. Instead, \safec\ provides an insulating
layer between the novice \C\ programmer and the standard library
functions. \safec\ adds a variety of additional runtime checks
to guard against typical novice errors, and provide intelligible
runtime failure reports.

\safec\ is {\em not} intended to be applied in production
software.  It is strictly a pedagogical stepping-stone,
to be displaced by direct use of the standard \C\ library when
the student is ready.

This document provides a {\em User Guide} to \safec.
Specifically, it describes each constant, data type,
and function, provided by \safec.  It does {\em not}
provide any information on the rationale for the particular
features included in \safec, nor does it discuss the internal 
architecture or implementation of \safec.

\section{What is a Module anyway?}

A \C\ module normally consists of three separate files:

\begin{itemize}
\item A {\em header} file, normally having the extension \tty{.h} .
This provides a specification of the {\em external 
interface} to the module.  That is, it specifies exactly how
other modules can invoke or use the facilities of this module.

\item A {\em source} file, normally having the extension \tty{.c}
.  This is the actual \C\ source code, or definition, of the module.
It specifies the {\em internal implementation} of the module.

\item An {\em object} file, normally having the extension
\tty{.o} .  This is the file produced by using the \C\ compiler
to translate the \C\ source code in the source file into the
specific, binary, instruction codes (so-called \qt{machine code})
which can be directly
processed by the CPU in the computer on which programs will be
executed.

\end{itemize}

A {\em user} of a module, who wishes to use its facilities in her
programs, needs access to the header file and the object file.
The header file is necessary so that, while the compiler 
is translating
{\em your} source code, it can check that it is interfacing in a
correct and valid manner with the external module.  The object
file is necessary so that a complete executable file can be
created by combining or linking together the object code from
{\em your} source file, with the object code of the external
module.

The user of a module does {\em not} require access to the 
source code of that module.  The source code is only required if
someone wants to {\em modify} the module in some way - correct
some defect, or add new facilities etc.

\section{Using \safec}

As with any free-standing \C\ module, two separate issues or 
problems arise in using the \safec\ module:

\begin{itemize}
\item How can the compiler discover, or be informed about, the
facilities offered by \safec\ (the \qt{interface} to it)?

This is necessary because, in order to compile {\em your} code,
which is supposed to mesh with the \safec\ code, the compiler
must know what sort of \qt{hooks} or connections are available in the
\safec\ code.

\item How can the compiler know, or be told, to combine the
object code (compiled) version of the \safec\ module, with the
compiled version of {\em your} code, in order to produce a
complete, executable, file?

\end{itemize}

The first problem, of telling the compiler what the allowed
interface to \safec\ is,  is solved by inserting the following
preprocessor directive close to the top of your source file,
before any other reference to \safec\ entities:

\begin{verbatim}
  #include <safe-c.h>
\end{verbatim}

The effect of this directive is that, during the compilation,
the file \tty{safe-c.h} is searched for in certain  
directories.  Assuming it is found, then its text is incorporated
into the compilation exactly as it it had been part of your
source file.  The file \tty{safe-c.h} is the header file for
the \safec\ module and, as such, contains declarations of all the
entities (constants, data types, functions) provided by \safec.
Thus, when the compiler subsequently encounters references to
these entities in {\em your} code, it can recognise or decide
whether they are valid.  For example, \tty{safe-c.h} contains a
{\em prototype} for each function.  This warns the compiler of
the existence, in the \safec\ module, of the function, and also
specifies how many arguments (if any), of what types, the
function can accept.  Then when the compiler encounters an
attempt to invoke the function, it can check whether the correct
number of arguments, of the correct types, are present.

It might seem that the second problem - that of subsequently
finding the compiled version of \safec\ and combining it with the
compiled version of your own file, in order to produce the
complete executable program - simply should not arise.  Surely,
if the compiler is told, by the inclusion of \tty{safe-c.h}, that
your program makes use of facilities of \safec, that should
prompt the compiler to also look for the compiled version of
\safec, and incorporate it into the executable file?

However, few things in computer programming are as simple
as they seem.  

The \tty{\#include}
directive specifies that the text of another file must be
incorporated
into the {\em translation} phase of the compile - i.e. while
translating your source file into object code.  It does not
stipulate anything about what object files should subsequently be
linked together to create the executable file.  Indeed, it {\em
must} not.  This is because, in the general case, there is no
simple or necessary one-to-one relationship between header files
and object files.  So, in the general case, stipulations of what
header files to include during translation, and what object files
to combine during linkage, must be kept separate.

Specifying to the compiler to include the \safec\ object file in
the linkage phase simply requires an additional parameter to be
placed in the compiler command line.  However: there are a couple
of other special stipulations that also have to be made to the
compiler, and also a little postprocessing/tidying up to be done
after the compilation.  Therefore, \safec\ is accompanied by a
small {\em batch} file called \tty{scc.bat}.  A {\em batch} file
is simply a text file containing a series of \tty{DOS} commands,
to be executed in sequence.  So, if your file is called, say,
\tty{hello.c}, then the command:

\begin{verbatim}
    scc hello
\end{verbatim}

will actually cause a whole {\em series} of commands in
\tty{scc.bat} to be executed.  These will automatically invoke
the compiler in the correct way to incorporate the \safec\ object
file into the executable file.

However: note that \tty{scc.bat} is {\em only} appropriate for
compiling programs which make use of \safec.  When you progress
to the point of directly using the {\em standard} \C\ library,
then you must also learn how to directly invoke the compiler in
the appropriate way, rather than relying on \tty{scc.bat} to do it.

\newpage
\section{Overview}

\safec\ introduces three distinct {\em data types}.  A data type
is a particular format for storing information of some particular
kind.  The three \safec\ data types are:

\begin{itemize}
\item \tty{boolean\_type}: This only has two possible values,
denoted by the symbolic constants
\tty{TRUE} and \tty{FALSE}.  It is used particularly when the
behaviour of the program is to depend on whether some condition
is satisfied - whether it is {\em true} or not.
\item \tty{integer\_type}: For dealing with positive or negative
whole, or integer, numbers.  This type {\em cannot} be used to
deal with non-integer numbers, such as fractions.
\item \tty{floating\_point\_type}: This is a special kind of format
which can handle non-integer, {\em rational}, 
numbers (i.e. there is a decimal
point) but the position of the decimal point is not fixed.  That
is, these numbers have a fixed degree of {\em precision} - a
fixed number of significant digits - but the decimal point can be
located anywhere.  The decimal point is said to {\em float}.
Floating points formats are essentially similar to conventional
{\em scientific notation} such as $5.78\times 10^{8}$.
\item \tty{string\_type}: For storing strings of characters, of
variable length.
\end{itemize}

\safec\ provides {\em functions} - or \qt{subprograms} if you like -
to carry out various standard manipulations on objects of these
standard types.  Specifically, there are functions to display
strings in the \tty{MS-DOS} window, and to read strings in from
the keyboard; and to convert between string representations and
the internal binary representations of \tty{boolean\_type},
\tty{integer\_type} and \tty{floating\_point\_type}.  In this way,
objects of these types can be read in from the keyboard (as
\tty{string\_type}), converted to one of the internal binary
representations, operated upon in any appropriate way (i.e.
performing boolean or arithmetic operations) and the results can
be displayed again.

\newpage
\section{Constants and Data Types}

\subsection{\tty{boolean\_type}}

Objects of \tty{boolean\_type} may take on only logical or
boolean values.  The two possible boolean values are denoted by
the symbolic constants \tty{TRUE} and \tty{FALSE}.

\subsection{\tty{integer\_type}}

Objects of \tty{integer\_type} may take on values representing
positive or negative integer numbers.  Internally these are
stored in a 32-bit, 2's complement notation.  This means that the
range of numbers that can be represented is approximately $\pm
2^{31}$. The maximum (most positive) and minimum 
(most negative) values that can be represented are denoted by the
symbolic constants \tty{INTEGER\_MAX} and \tty{INTEGER\_MIN}.

Constants of \tty{integer\_type} may be represented in your
programs in normal, decimal, notation, such as \tty{42} or 
\tty{-4561237} etc.  You must {\em not} embed commas or spaces in
these constants - something like \tty{1,000,000} would not be
acceptable.  Nor (since these are {\em integer} values) should
you include a decimal point - not even if the fractional part is
given as zero.  So, again, something like \tty{45.0} is not 
regarded as a valid {\em integer} value.

\subsection{\tty{floating\_point\_type}}

Objects of \tty{floating\_point\_type} may take on values representing
non-integer, {\em rational}, numbers.  Internally these are
represented in so called {\em floating point} format.  This is
somewhat like normal scientific notation - such as $3.765 \times
10^{3}$.  That is, there is a {\em mantissa} ($3.765$ in this
example) and a separate {\em exponent} ($3$ in this example).
The mantissa has a some finite range which, in effect, determines
the number of significant digits that can be represented.  The
exponent also has a finite range which determines the maximum and
minimum absolute values which can be represented.  Of course,
internally in the computer, both the mantissa and the exponent are
represented in binary notation; and the exponent is a power of 2
(normally) rather than a power of 10.  

In the particular case of \tty{floating\_point\_type}, the mantissa is
equivalent to approximately 15 decimal digits; and the exponent
is equivalent to approximately $10^{\pm300}$.

Constants of \tty{floating\_point\_type} may be represented in your
programs in normal decimal notation, except that the decimal
point {\em must} be present, even if the fractional part is
intended as zero.  Thus, \tty{3.414} is a perfectly good
\tty{floating\_point\_type} value, whereas \tty{24} is {\em not} - it
would be interpreted as an \tty{integer\_type} value.  If you
{\em mean} the \tty{floating\_point\_type} value corresponding to the
number 24, then code it as \tty{24.0} instead.  Very large or
small \tty{floating\_point\_type} constants can be represented using
scientific notation like this: \tty{-23.86e54} (for $-23.6\times
10^{54}$) or \tty{0.7433681e-123} (for $0.7433681\times 10^{-
123}$).

\subsection{\tty{string\_type}}

Objects of \tty{string\_type} consist of a sequence of arbitrary
characters, of arbitrary length, up to a certain maximum.
This maximum length is denoted by the symbolic constant 
\tty{STRING\_MAXLEN} (which is of type \tty{integer\_type}).

String constants are enclosed by double quote characters, and may
not be broken across multiple lines:

\begin{verbatim}
  "This is a valid string constant."

  "This is NOT a
   valid
   string constant!"
\end{verbatim}

Within a string constant, certain special characters are denoted
by so-called {\em escape sequences} as follows:

\begin{itemize}
\item \tty{$\backslash$n} : This is the {\em newline} character.
When printed on the screen it moves the cursor down one line 
and back to the left margin.  When stored in a file it marks the 
break between one line of text and the next.

\item $\backslash${\tt "} : This allows you to embed a 
double quote character in a string (a double quote on its own
won't work because it would be mistaken for the end of the
string).

\item \tty{$\backslash\backslash$} : Since a backslash character
plays a special role in introducing the escape sequences already
mentioned, there is a problem if you actually want to have a
backslash character {\em itself} in your string.  The solution is
that a double backslash is treated as denoting literally that
you want a (single) backslash in the string.

\end{itemize}
    
\section{Functions}

\subsection{\tty{put\_string()}}

\tty{put\_string()} accepts exactly one argument which must be of
\tty{string\_type}.  This may be either a string
constant or a string variable.  If it is a variable, its value
will not be changed by \tty{put\_string()}.

\tty{put\_string()} outputs the given string on the {\em standard 
output stream}, or \tty{stdout} for short. By default, \tty{stdout} 
simply corresponds to the \tty{MS-DOS} window
in which the program is 
being executed. However, when the program is being 
started, \tty{stdout} can be {\em redirected} into a file on
disk.  Suppose the executable program is called \tty{foo.exe};
then the following way of executing the program under \tty{DOS}
would result in \tty{stdout} being redirected to a file
called \tty{output.txt} (any previous contents of this file 
being overwritten):

\begin{verbatim}
    D:\SOFTENG1>foo >output.txt
\end{verbatim}

\tty{put\_string} does not produce any \tty{return} value.


\subsection{\tty{get\_string()}}

\tty{get\_string()} accepts exactly one argument
which must be of
\tty{string\_type}, and must be a variable. 

\tty{get\_string()} reads, or inputs, a string from the {\em standard 
input stream}, or \tty{stdin} for short, and stores it in the string 
variable given as an argument. Exactly one line is read - that is,
reading of the string is terminated when a newline character is
encountered.

By default, \tty{stdin} 
simply corresponds to the keyboard.  Whatever characters are
typed in are also echoed in the \tty{MS-DOS} window in which the
program is being executed; pressing the \tty{Enter} key generates
the newline character which terminates reading.

Alternatively, when the program is being 
started, \tty{stdin} can be {\em redirected} to read from a file on
disk.  Suppose the executable program is called \tty{foo.exe};
then the following way of executing the program under \tty{DOS}
would result in \tty{stdin} being redirected to read from a file
called \tty{input.txt}:

\begin{verbatim}
    D:\SOFTENG1>foo <input.txt
\end{verbatim}

\tty{get\_string()} produces a \tty{return} value of
\tty{boolean\_type}.  This will normally be the value 
\tty{TRUE} indicating that a string has been successfully read.
However, if, for some reason, a string cannot be read, the value
\tty{FALSE} will be produced instead. The usual reason why this
might arise would be that \tty{stdin} has been redirected to come
from a disk file, and the end of the file is encountered -
naturally, in that case, \tty{get\_string} cannot actually read
in a further string.

\subsection{\tty{assign\_string()}}

\tty{assign\string()} accepts exactly two arguments, which must
both be of \tty{string\_type}.  The first must be a variable; the
second may be a variable or a constant.

\tty{assign\_string()} copies or {\em assigns} the value of the
second argument to the string variable specified by the first
argument.  The previous value of that variable is overwritten.

\tty{assign\_string()} does not produce any \tty{return} value.

\subsection{\tty{string\_equal()}}

\tty{string\_equal()} accepts exactly two arguments, which must
both be of \tty{string\_type}.  Each can be either a variable or
a constant.  Neither will be altered by \tty{string\_equal()}.

\tty{string\_equal()} produces a \tty{return} value of
\tty{boolean\_type}.

The two string arguments will be compared, character by
character. If both strings are {\em exactly} alike (including the
{\em case} of letters) then \tty{string\_equal()} will produce a
\tty{return} value of \tty{TRUE}; conversely, if there is {\em
any} difference between the two strings, \tty{string\_equal()}
will produce a \tty{return} value of \tty{FALSE}.

\subsection{\tty{string\_to\_floating\_point()}}

\tty{string\_to\_floating\_point()} accepts exactly one argument, which
must be of \tty{string\_type}.  This may be a variable or a
constant.  However, in practise, it is normally a variable
(since, otherwise, a constant of \tty{floating\_point\_type} could
simply be used directly, instead of invoking
\tty{string\_to\_floating\_point()} to process a string constant).
In any case, if the argument is a variable, it will not be
altered by \tty{string\_to\_floating\_point()}.

\tty{string\_to\_floating\_point()} produces a \tty{return} value of
\tty{floating\_point\_type}.

\tty{string\_to\_floating\_point()} examines the string given as an
argument, and interprets it (if possible) as a
decimal (base 10) number, possibly in scientific notation (e.g.
\tty{\qt{2.3e5}} would denote $2.3\times 10^{5}$ etc.).  Providing that
the string {\em
can} be interpreted successfully in this way, 
\tty{string\_to\_floating\_point()} will produce the internal binary
representation (i.e. of \tty{floating\_point\_type}) of this number as
the \tty{return} value.  If the string cannot be interpreted in
this way (e.g. \tty{\qt{rhubarb}} or \tty{\qt{forty-two}} or \tty{\qt{(01)
704-5000}} etc.) then a runtime exception will be generated and
the program will terminate abnormally.

\subsection{\tty{floating\_point\_to\_string()}}

\tty{floating\_point\_to\_string()} accepts exactly two arguments.  The
first must be a variable of \tty{string\_type}. The second must
be of \tty{floating\_point\_type}, and may be either a constant or a
variable.  However, in practise it will normally be a variable
(since, otherwise, a constant of \tty{string\_type} could simply
be used directly, instead of invoking
\tty{floating\_point\_to\_string()}).  In any case, if this second
argument is a variable, it will not be altered by
\tty{floating\_point\_to\_string()}.

\tty{floating\_point\_to\_string()} takes the value of
\tty{floating\_point\_type} given by the second argument, and converts
it into a corresponding \tty{string\_type} value, in decimal (base 10)
notation, and stores this string in the variable given as the
first argument.

\tty{floating\_point\_to\_string()} does not produce any \tty{return}
value.

\subsection{\tty{string\_to\_integer()}}

\tty{string\_to\_integer()} accepts exactly one argument, which
must be of \tty{string\_type}.  This may be a variable or a
constant.  However, in practise, it is normally a variable
(since, otherwise, a constant of \tty{integer\_type} could
simply be used directly, instead of invoking
\tty{string\_to\_integer()} to process a string constant).
In any case, if the argument is a variable, it will not be
altered by \tty{string\_to\_integer()}.

\tty{string\_to\_integer()} produces a \tty{return} value of
\tty{integer\_type}.

\tty{string\_to\_integer()} examines the string given as an
argument, and interprets it (if possible) as a
decimal (base 10) integer number. Providing that
the string {\em
can} be interpreted successfully in this way, 
\tty{string\_to\_integer()} will produce the internal binary
representation (i.e. of \tty{integer\_type}) of this number as
the \tty{return} value.  If the string cannot be interpreted in
this way (e.g. \tty{\qt{rhubarb}} or \tty{\qt{forty-two}} or
\tty{\qt{3.414}} etc.) then a runtime exception will be generated and
the program will terminate abnormally.

\subsection{\tty{integer\_to\_string()}}

\tty{integer\_to\_string()} accepts exactly two arguments.  The
first must be a variable of \tty{string\_type}. The second must
be of \tty{integer\_type}, and may be either a constant or a
variable.  However, in practise it will normally be a variable
(since, otherwise, a constant of \tty{string\_type} could simply
be used directly, instead of invoking
\tty{integer\_to\_string()}).  In any case, if this second
argument is a variable, it will not be altered by
\tty{integer\_to\_string()}.

\tty{integer\_to\_string()} takes the value of
\tty{integer\_type} given by the second argument, and converts
it into a corresponding \tty{string\_type} value, in decimal (base 10)
notation, and stores this string in the variable given as the
first argument.

\tty{integer\_to\_string()} does not produce any \tty{return}
value.


\subsection{\tty{string\_to\_boolean()}}

\tty{string\_to\_boolean()} accepts exactly one argument, which
must be of \tty{string\_type}.  This may be a variable or a
constant.  However, in practise, it is normally a variable
(since, otherwise, a constant of \tty{boolean\_type} could
simply be used directly, instead of invoking
\tty{string\_to\_boolean()} to process a string constant).
In any case, if the argument is a variable, it will not be
altered by \tty{string\_to\_double}.

\tty{string\_to\_boolean()} produces a \tty{return} value of
\tty{boolean\_type}.

\tty{string\_to\_boolean} examines the string given as an
argument, and interprets it (if possible) as a string
representation of a boolean value.  That is, the string {\em
must} have the value \tty{\qt{TRUE}} or \tty{\qt{FALSE}} - except that
leading or trailing whitespace will be ignored.
Providing that
the string {\em
can} be interpreted successfully in this way, 
\tty{string\_to\_boolean()} will produce the internal binary
representation (i.e. of \tty{boolean\_type}) of this value as
the \tty{return} value.  If the string cannot be interpreted in
this way (e.g. \tty{\qt{rhubarb}} or \tty{\qt{True}} or \tty{\qt{wrong}} 
etc.) then a runtime exception will be generated and
the program will terminate abnormally.

\subsection{\tty{boolean\_to\_string()}}

\tty{boolean\_to\_string()} accepts exactly two arguments.  The
first must be a variable of \tty{string\_type}. The second must
be of \tty{boolean\_type}, and may be either a constant or a
variable.  However, in practise it will normally be a variable
(since, otherwise, a constant of \tty{string\_type} could simply
be used directly, instead of invoking
\tty{boolean\_to\_string()}).  In any case, if this second
argument is a variable, it will not be altered by
\tty{boolean\_to\_string()}.

\tty{boolean\_to\_string()} takes the value of
\tty{boolean\_type} given by the second argument, and converts
it into a corresponding \tty{string\_type} value - i.e. either
the string \tty{\qt{TRUE}} or the string \tty{\qt{FALSE}}. It then
stores this string in the variable given as the
first argument.

\tty{boolean\_to\_string()} does not produce any \tty{return}
value.

\subsection{\tty{clear\_screen()}}

\tty{clear\_screen()} clears the \tty{MS-DOS} window in which the
program is being executed, and places the cursor in the top left
position.

\tty{clear\_screen()} accepts no arguments, and produces no
\tty{return} value.

\subsection{\tty{set\_cursor()}}

\tty{set\_cursor()} accepts exactly two arguments, both of
\tty{integer\_type}.  The first denotes a desired column number,
and must be in the range 1 to 80; the second denotes a desired
row (or line) number and must be in the range 1 to 25.  These can
be constants or variables.  If they are variables they will not
be altered by \tty{set\_cursor()}.

\tty{set\_cursor()} moves the cursor of the \tty{MS-DOS} window
in which the program is running to the specified column and row.
Nothing already displayed in the window will be modified.  Column
1, row 1 is the top left position of the window.

If either the requested column or row is outside the allowed
range, \tty{set\_cursor()} will generate a runtime exception and
the program will be terminated abnormally.

\tty{set\_cursor()} does not produce any \tty{return} value.

\section{Copyright}

This Hypermedia Document is copyrighted, \copyright\ 1994, 1995, by
\hot{Barry McMullin}{http://www.eeng.dcu.ie/\%7Emcmullin/home.html}.

Permission is hereby granted to access, copy, or store this work, in
whole or in part, for purposes of individual private study only. The
work may {\em not\/} be accessed or copied, in whole or in part, for
commercial purposes, except with the prior written permission of the
author.


\end{document}