
/**************************************************************************\

MODULE: tools

SUMMARY:

Some useful tools that are used throughout NTL.

\**************************************************************************/

#include <cstdlib>
#include <cmath>
#include <cstring>

#include <utility>
#include <iostream>
#include <new>
#include <stdexcept>

#include <NTL/config.h>
#include <NTL/mach_desc.h>




double GetTime();
// returns number of seconds of CPU time used by this process.

double GetWallTime();
// returns the "wall clock" time, measured since the beginning
// of some unspecified epoch.  This is useful for measuring the
// performance of multi-threaded code, since in this case,
// GetTime does not return very useful information in that case.

void PrintTime(ostream& s, double t);
// prints the time t (in seconds) to s in the format
//     ss  or  mm:ss  or  hh:mm:ss,
// where the value t is first rounded to the nearest integer.


long IsWhiteSpace(long c);
// returns 1 if c is "white space" (as defined by isspace is the
// standard library...usually blanks, tabs, newlines), and 0 otherwise.

long SkipWhiteSpace(istream& s);
// skips white space (as defined by IsWhiteSpace).
// Return value is 0 if end-of-file is reached; otherwise,
// return value is 1.


long IsEOFChar(long c);
// test if c == EOF


long CharToIntVal(long c);
// returns the hexidecimal value of c if c is '0'..'9', 'A'..'F', or 'a'..'f';
// otherwise, the return value is -1.

char IntValToChar(long x);
// returns the hexadecimal digit '0'..'9', 'a'..'f' representing x;
// an error is raised if x < 0 or x > 15.

long IsFinite(double *p);
// Returns 1 if *p is a "finite" floating point number.
// A pointer is used to ensure that the number is in memory,
// which on some architectures (notably x86/Pentium) can make a difference.

// some min/max and swap routines:

int min(int a, int b);
int max(int a, int b);

long min(long a, long b);
long max(long a, long b);

long min(int a, long b);
long max(int a, long b);

long min(long a, int b);
long max(long a, int b);

unsigned int min(unsigned int a, unsigned int b);
unsigned int max(unsigned int a, unsigned int b);

unsigned long min(unsigned long a, unsigned long b);
unsigned long max(unsigned long a, unsigned long b);

unsigned long min(unsigned int a, unsigned long b);
unsigned long max(unsigned int a, unsigned long b);

unsigned long min(unsigned long a, unsigned int b);
unsigned long max(unsigned long a, unsigned int b);


void swap(long& a, long& b);
void swap(int& a, int& b);


// defined here are all the conversion routines among the types 
// int, long, float, double.  See conversions.txt for complete details.



// The following platform-dependent macros are defined:

#define NTL_BITS_PER_LONG      (...)  /* bits in a long */
#define NTL_MAX_LONG           (...)  /* max value of a long */
#define NTL_MIN_LONG           (...)  /* min value of a long */

#define NTL_BITS_PER_INT       (...)  /* bits in a int */
#define NTL_MAX_INT            (...)  /* max value of a int */
#define NTL_MIN_INT            (...)  /* min value of a int */

#define NTL_DOUBLE_PRECISION   (...)  /* # of bits of precision in a double */
#define NTL_FDOUBLE_PRECISION  (...)  /* the double value 
                                        2^{NTL_DOUBLE_PRECISION-1} */

#define NTL_ARITH_RIGHT_SHIFT  (...)  /* 1 if signed right-shift is
                                        arithmetic; 0 otherwise */

#define NTL_EXT_DOUBLE         (...)  /* 1 if platform has "extended" doubles;
                                        0 otherwise */


// ERROR HANDLING

void TerminalError(const char *s);
// print an error message and call abort

extern thread_local void (*ErrorMsgCallback)(const char *);
extern thread_local void (*ErrorCallback)();
// Pointers (initially NULL) to callback functions.
// Upon encountering an unrecoverable error with an error
// message s, the following happens:
//
//    if (ErrorMsgCallback)
//       (*ErrorMsgCallback)(s);
//    else
//       cerr << s << "\n";
// 
//    if (ErrorCallback) (*ErrorCallback)();
//    abort();
//
// NOTE: if threads are enabled, these are actually thread_local variables.



// The following classes are defined even if exceptions are not
// enabled with NTL_EXCEPTIONS

class ErrorObject : public runtime_error {
public:
   ErrorObject(const char *msg);
};

class LogicErrorObject : public ErrorObject {
public: 
   LogicErrorObject(const char *msg);
};

class ArithmeticErrorObject : public ErrorObject {
public: 
   ArithmeticErrorObject(const char *msg);
};

class ResourceErrorObject : public ErrorObject {
public: 
   ResourceErrorObject(const char *msg);
};

class FileErrorObject : public ErrorObject {
public: 
   FileErrorObject(const char *msg);
};

class InputErrorObject : public ErrorObject {
public: 
   InputErrorObject(const char *msg);
};


// The following functions throw the indicated exception if
// exceptions are enabled with NTL_EXCEPTIONS; otherwise,
// they simply invoke TerminalError.

void MemoryError();
// throws bad_alloc

void Error(const char *msg);
// throws ErrorObject

void LogicError(const char *msg);
// throws LogicErrorObject

void ArithmeticError(const char *msg);
// throws ArithmeticErrorObject

void ResourceError(const char *msg);
// throws ResourceErrorObject

void FileError(const char *msg);
// throws FileErrorObject

void InputError(const char *msg);
// throws InputErrorObject



