#include <time.h>
#include "allheaders.h"
#include <math.h>
#include <sys/time.h>
#include <sys/resource.h>

Macros
#define	DEBUG_SEV 0

#define	MAX_DEBUG_MESSAGE 2000

Functions
l_int32	setMsgSeverity (l_int32 newsev)

l_int32	returnErrorInt (const char msg, const char procname, l_int32 ival)

l_float32	returnErrorFloat (const char msg, const char procname, l_float32 fval)

void *	returnErrorPtr (const char msg, const char procname, void *pval)

l_int32	returnErrorInt1 (const char msg, const char arg, const char *procname, l_int32 ival)

l_float32	returnErrorFloat1 (const char msg, const char arg, const char *procname, l_float32 fval)

void *	returnErrorPtr1 (const char msg, const char arg, const char procname, void pval)

static void	lept_default_stderr_handler (const char *formatted_msg)

void	leptSetStderrHandler (void(handler)(const char ))

void	lept_stderr (const char *fmt,...)

l_ok	filesAreIdentical (const char fname1, const char fname2, l_int32 *psame)

l_uint16	convertOnLittleEnd16 (l_uint16 shortin)

l_uint16	convertOnBigEnd16 (l_uint16 shortin)

l_uint32	convertOnLittleEnd32 (l_uint32 wordin)

l_uint32	convertOnBigEnd32 (l_uint32 wordin)

l_ok	fileCorruptByDeletion (const char filein, l_float32 loc, l_float32 size, const char fileout)

l_ok	fileCorruptByMutation (const char filein, l_float32 loc, l_float32 size, const char fileout)

l_ok	fileReplaceBytes (const char filein, l_int32 start, l_int32 nbytes, l_uint8 newdata, size_t newsize, const char *fileout)

l_ok	genRandomIntOnInterval (l_int32 start, l_int32 end, l_int32 seed, l_int32 *pval)

l_int32	lept_roundftoi (l_float32 fval)

l_int32	lept_floor (l_float32 fval)

l_int32	lept_ceiling (l_float32 fval)

l_ok	l_hashStringToUint64 (const char str, l_uint64 phash)

l_ok	l_hashStringToUint64Fast (const char str, l_uint64 phash)

l_ok	l_hashPtToUint64 (l_int32 x, l_int32 y, l_uint64 *phash)

l_ok	l_hashFloat64ToUint64 (l_float64 val, l_uint64 *phash)

l_ok	findNextLargerPrime (l_int32 start, l_uint32 *pprime)

l_ok	lept_isPrime (l_uint64 n, l_int32 pis_prime, l_uint32 pfactor)

l_uint32	convertIntToGrayCode (l_uint32 val)

l_uint32	convertGrayCodeToInt (l_uint32 val)

char *	getLeptonicaVersion (void)

void	startTimer (void)

l_float32	stopTimer (void)

L_TIMER	startTimerNested (void)

l_float32	stopTimerNested (L_TIMER rusage_start)

void	l_getCurrentTime (l_int32 sec, l_int32 usec)

L_WALLTIMER *	startWallTimer (void)

l_float32	stopWallTimer (L_WALLTIMER **ptimer)

char *	l_getFormattedDate (void)

Variables
LEPT_DLL l_int32	LeptMsgSeverity = DEFAULT_SEVERITY

void(*	stderr_handler )(const char *) = lept_default_stderr_handler

static struct rusage	rusage_before

static struct rusage	rusage_after

Detailed Description


      ------------------------------------------
      This file has these utilities:
        - error, warning and info messages
        - redirection of stderr
        - low-level endian conversions
        - file corruption operations
        - random and prime number operations
        - 64-bit hash functions
        - leptonica version number accessor
        - timing and date operations
      ------------------------------------------

      Control of error, warning and info messages
          l_int32    setMsgSeverity()

      Error return functions, invoked by macros
          l_int32    returnErrorInt()
          l_float32  returnErrorFloat()
          void      *returnErrorPtr()
          l_int32    returnErrorInt1()
          l_float32  returnErrorFloat1()
          void      *returnErrorPtr1()

      Runtime redirection of stderr
          void leptSetStderrHandler()
          void lept_stderr()

      Test files for equivalence
          l_int32    filesAreIdentical()

      Byte-swapping data conversion
          l_uint16   convertOnBigEnd16()
          l_uint32   convertOnBigEnd32()
          l_uint16   convertOnLittleEnd16()
          l_uint32   convertOnLittleEnd32()

      File corruption and byte replacement operations
          l_int32    fileCorruptByDeletion()
          l_int32    fileCorruptByMutation()
          l_int32    fileReplaceBytes()

      Generate random integer in given interval
          l_int32    genRandomIntOnInterval()

      Simple math functions
          l_int32    lept_roundftoi()
          l_int32    lept_floor()
          l_int32    lept_ceiling()

      64-bit hash functions
          l_int32    l_hashStringToUint64()
          l_int32    l_hashStringToUint64Fast()
          l_int32    l_hashPtToUint64()
          l_int32    l_hashFloat64ToUint64()

      Prime finders
          l_int32    findNextLargerPrime()
          l_int32    lept_isPrime()

      Gray code conversion
          l_uint32   convertIntToGrayCode()
          l_uint32   convertGrayCodeToInt()

      Leptonica version number
          char      *getLeptonicaVersion()

      Timing
          void       startTimer()
          l_float32  stopTimer()
          L_TIMER    startTimerNested()
          l_float32  stopTimerNested()
          void       l_getCurrentTime()
          L_WALLTIMER  *startWallTimer()
          l_float32  stopWallTimer()
          void       l_getFormattedDate()

 For all issues with cross-platform development, see utils2.c.

Definition in file utils1.c.

Macro Definition Documentation

◆ DEBUG_SEV

#define DEBUG_SEV 0

Definition at line 126 of file utils1.c.

◆ MAX_DEBUG_MESSAGE

#define MAX_DEBUG_MESSAGE 2000

Definition at line 360 of file utils1.c.

Function Documentation

◆ convertGrayCodeToInt()

l_uint32 convertGrayCodeToInt ( l_uint32 val )

convertGrayCodeToInt()

Parameters

[in] val gray code value

Returns: corresponding integer value

Definition at line 1044 of file utils1.c.

◆ convertIntToGrayCode()

l_uint32 convertIntToGrayCode ( l_uint32 val )

convertIntToGrayCode()

Parameters

[in] val integer value

Returns: corresponding gray code value

Notes:
     (1) Gray code values corresponding to integers differ by
         only one bit transition between successive integers.

Definition at line 1031 of file utils1.c.

◆ convertOnBigEnd16()

l_uint16 convertOnBigEnd16 ( l_uint16 shortin )

Definition at line 479 of file utils1.c.

◆ convertOnBigEnd32()

l_uint32 convertOnBigEnd32 ( l_uint32 wordin )

Definition at line 515 of file utils1.c.

◆ convertOnLittleEnd16()

l_uint16 convertOnLittleEnd16 ( l_uint16 shortin )

Definition at line 473 of file utils1.c.

◆ convertOnLittleEnd32()

l_uint32 convertOnLittleEnd32 ( l_uint32 wordin )

Definition at line 508 of file utils1.c.

◆ fileCorruptByDeletion()

l_ok fileCorruptByDeletion	(	const char *	filein,
		l_float32	loc,
		l_float32	size,
		const char *	fileout )

fileCorruptByDeletion()

Parameters

[in]	filein
[in]	loc	fractional location of start of deletion
[in]	size	fractional size of deletion
[in]	fileout	corrupted file

Returns: 0 if OK, 1 on error

Notes:
     (1) loc and size are expressed as a fraction of the file size.
     (2) This makes a copy of the data in filein, where bytes in the
         specified region have deleted.
     (3) If (loc + size) >= 1.0, this deletes from the position
         represented by loc to the end of the file.
     (4) It is useful for testing robustness of I/O wrappers when the
         data is corrupted, by simulating data corruption by deletion.

Definition at line 547 of file utils1.c.

◆ fileCorruptByMutation()

l_ok fileCorruptByMutation	(	const char *	filein,
		l_float32	loc,
		l_float32	size,
		const char *	fileout )

fileCorruptByMutation()

Parameters

[in]	filein
[in]	loc	fractional location of start of randomization
[in]	size	fractional size of randomization
[in]	fileout	corrupted file

Returns: 0 if OK, 1 on error

Notes:
     (1) loc and size are expressed as a fraction of the file size.
     (2) This makes a copy of the data in filein, where bytes in the
         specified region have been replaced by random data.
     (3) If (loc + size) >= 1.0, this modifies data from the position
         represented by loc to the end of the file.
     (4) It is useful for testing robustness of I/O wrappers when the
         data is corrupted, by simulating data corruption.

Definition at line 609 of file utils1.c.

◆ fileReplaceBytes()

l_ok fileReplaceBytes	(	const char *	filein,
		l_int32	start,
		l_int32	nbytes,
		l_uint8 *	newdata,
		size_t	newsize,
		const char *	fileout )

fileReplaceBytes()

Parameters

[in]	filein	input file
[in]	start	start location for replacement
[in]	nbytes	number of bytes to be removed
[in]	newdata	replacement bytes
[in]	newsize	size of replacement bytes
[in]	fileout	output file

Returns: 0 if OK, 1 on error

Notes:
     (1) To remove nbytes without replacement, set newdata == NULL.
     (2) One use is for replacing the date/time in a pdf file by a
         string of 12 '0's, effectively removing the date without
         invalidating the byte counters in the pdf file:
             fileReplaceBytes(filein 86 12 (char *)"000000000000" 12 fileout

Definition at line 668 of file utils1.c.

◆ filesAreIdentical()

l_ok filesAreIdentical	(	const char *	fname1,
		const char *	fname2,
		l_int32 *	psame )

filesAreIdentical()

Parameters

[in]	fname1
[in]	fname2
[out]	psame	1 if identical; 0 if different

Returns: 0 if OK, 1 on error

Definition at line 404 of file utils1.c.

◆ findNextLargerPrime()

l_ok findNextLargerPrime	(	l_int32	start,
		l_uint32 *	pprime )

findNextLargerPrime()

Parameters

[in]	start
[out]	pprime	first prime larger than start

Returns: 0 if OK, 1 on error

Definition at line 949 of file utils1.c.

References lept_isPrime().

◆ genRandomIntOnInterval()

l_ok genRandomIntOnInterval	(	l_int32	start,
		l_int32	end,
		l_int32	seed,
		l_int32 *	pval )

genRandomIntOnInterval()

Parameters

[in]	start	beginning of interval; can be < 0
[in]	end	end of interval; must be >= start
[in]	seed	use 0 to skip; otherwise call srand
[out]	pval	random integer in interval [start ... end]

Returns: 0 if OK, 1 on error

Definition at line 722 of file utils1.c.

◆ getLeptonicaVersion()

char * getLeptonicaVersion ( void )

getLeptonicaVersion()

Return: string of version number (e.g., 'leptonica-1.74.2')

Notes: (1) The caller has responsibility to free the memory.

Definition at line 1066 of file utils1.c.

◆ l_getCurrentTime()

void l_getCurrentTime	(	l_int32 *	sec,
		l_int32 *	usec )

l_getCurrentTime()

Parameters

[out]	sec	[optional] in seconds since birth of Unix
[out]	usec	[optional] in microseconds since birth of Unix

Returns: void

Definition at line 1191 of file utils1.c.

Referenced by startWallTimer(), and stopWallTimer().

◆ l_getFormattedDate()

char * l_getFormattedDate ( void )

l_getFormattedDate()

Returns: formatted date string, or NULL on error

Notes:
     (1) This is used in pdf, in the form specified in section 3.8.2 of
         http://partners.adobe.com/public/developer/en/pdf/PDFReference.pdf
     (2) Contributed by Dave Bryan.  Works on all platforms.

Definition at line 1401 of file utils1.c.

◆ l_hashFloat64ToUint64()

l_ok l_hashFloat64ToUint64	(	l_float64	val,
		l_uint64 *	phash )

l_hashFloat64ToUint64()

Parameters

[in]	val
[out]	phash	hash key

Returns: 0 if OK, 1 on error

Notes:
     (1) This is a simple hash for using hashmaps with 64-bit float data.
     (2) The resulting hash is called a "key" in a lookup operation.
         The bucket for val in a hashmap is then found by taking the mod
         of the hash key with the number of buckets (which is prime).

Definition at line 927 of file utils1.c.

◆ l_hashPtToUint64()

l_ok l_hashPtToUint64	(	l_int32	x,
		l_int32	y,
		l_uint64 *	phash )

l_hashPtToUint64()

Parameters

[in]	x,y
[out]	phash	hash value

Returns: 0 if OK, 1 on error

Notes:
     (1) This simple hash function has no collisions for
         any of 400 million points with x and y up to 20000.

Definition at line 899 of file utils1.c.

◆ l_hashStringToUint64()

l_ok l_hashStringToUint64	(	const char *	str,
		l_uint64 *	phash )

l_hashStringToUint64()

Parameters

[in]	str
[out]	phash	hash value

Returns: 0 if OK, 1 on error

Notes:
     (1) The intent of the hash is to avoid collisions by mapping
         the string as randomly as possible into 64 bits.
     (2) To the extent that the hashes are random, the probability of
         a collision can be approximated by the square of the number
         of strings divided by 2^64.  For 1 million strings, the
         collision probability is about 1 in 16 million.
     (3) I expect non-randomness of the distribution to be most evident
         for small text strings.  This hash function has been tested
         for all 5-character text strings composed of 26 letters,
         of which there are 26^5 = 12356630.  There are no hash
         collisions for this set.

Definition at line 828 of file utils1.c.

◆ l_hashStringToUint64Fast()

l_ok l_hashStringToUint64Fast	(	const char *	str,
		l_uint64 *	phash )

l_hashStringToUint64Fast()

Parameters

[in]	str
[out]	phash	hash value

Returns: 0 if OK, 1 on error

Notes:
    (1) This very simple hash algorithm is described in "The Practice
        of Programming" by Kernighan and Pike, p. 57 (1999).
    (2) The returned hash value would then be hashed into an index into
        the hashtable, using the mod operator with the hashtable size.

Definition at line 865 of file utils1.c.

◆ lept_ceiling()

l_int32 lept_ceiling ( l_float32 fval )

lept_ceiling()

Parameters

[in] fval

Returns: smallest integer that is not less than fval

Notes:
     (1) If fval is equal to its interger value, return that.
         Otherwise:
           For fval > 0, fval --> 1 + floor(fval)
           For fval < 0, fval --> -(1 + floor(-fval))

Definition at line 795 of file utils1.c.

◆ lept_default_stderr_handler()

static void lept_default_stderr_handler ( const char * formatted_msg )

static

Definition at line 327 of file utils1.c.

◆ lept_floor()

l_int32 lept_floor ( l_float32 fval )

lept_floor()

Parameters

[in] fval

Returns: largest integer that is not greater than fval

Definition at line 774 of file utils1.c.

◆ lept_isPrime()

l_ok lept_isPrime	(	l_uint64	n,
		l_int32 *	pis_prime,
		l_uint32 *	pfactor )

lept_isPrime()

Parameters

[in]	n	64-bit unsigned
[out]	pis_prime	1 if prime, 0 otherwise
[out]	pfactor	[optional] smallest divisor, or 0 on error or if prime

Returns: 0 if OK, 1 on error

Definition at line 982 of file utils1.c.

Referenced by findNextLargerPrime().

◆ lept_roundftoi()

l_int32 lept_roundftoi ( l_float32 fval )

lept_roundftoi()

Parameters

[in] fval

Returns: value rounded to the nearest integer

Notes:
     (1) For fval >= 0, fval --> round(fval) == floor(fval + 0.5)
         For fval < 0, fval --> -round(-fval))
         This is symmetric around 0.
         e.g., for fval in (-0.5 ... 0.5), fval --> 0

Definition at line 761 of file utils1.c.

◆ lept_stderr()

void lept_stderr	(	const char *	fmt,
			... )

lept_stderr()

Parameters

[in]	fmt	format string
[in]	...	varargs

Returns: void

Notes:
     (1) This is a replacement for fprintf(), to allow redirection
         of output.  All calls to fprintf(stderr, ...) are replaced
         with calls to lept_stderr(...).
     (2) The message size is limited to 2K bytes.
     (3) This utility was provided by jbarlow83.

Definition at line 377 of file utils1.c.

Referenced by returnErrorFloat(), returnErrorFloat1(), returnErrorInt(), returnErrorInt1(), returnErrorPtr(), and returnErrorPtr1().

◆ leptSetStderrHandler()

void leptSetStderrHandler ( void(* handler )(const char *) )

leptSetStderrHandler()

Parameters

[in] handler callback function for lept_stderr output

Returns: void

Notes:
     (1) This registers a handler for redirection of output to stderr
         at runtime.
     (2) If called with NULL, the output goes to stderr.

Definition at line 351 of file utils1.c.

◆ returnErrorFloat()

l_float32 returnErrorFloat	(	const char *	msg,
		const char *	procname,
		l_float32	fval )

returnErrorFloat()

Parameters

[in]	msg	error message
[in]	procname	use func
[in]	fval	return float error val

Returns: fval

Definition at line 219 of file utils1.c.

References lept_stderr().

◆ returnErrorFloat1()

l_float32 returnErrorFloat1	(	const char *	msg,
		const char *	arg,
		const char *	procname,
		l_float32	fval )

returnErrorFloat1()

Parameters

[in]	msg	error message
[in]	arg	additional error message argument (will be appended to the error message)
[in]	procname	use func
[in]	fval	return float error val

Returns: fval

Definition at line 278 of file utils1.c.

References lept_stderr().

◆ returnErrorInt()

l_int32 returnErrorInt	(	const char *	msg,
		const char *	procname,
		l_int32	ival )

returnErrorInt()

Parameters

[in]	msg	error message
[in]	procname	use func
[in]	ival	return error val (typically 1 for an error)

Returns: ival

Definition at line 201 of file utils1.c.

References lept_stderr().

◆ returnErrorInt1()

l_int32 returnErrorInt1	(	const char *	msg,
		const char *	arg,
		const char *	procname,
		l_int32	ival )

returnErrorInt1()

Parameters

[in]	msg	error message
[in]	arg	additional error message argument (will be appended to the error message)
[in]	procname	use func
[in]	ival	return error val; typically 1 for an error return

Returns: ival typically 1 for an error return

Definition at line 257 of file utils1.c.

References lept_stderr().

◆ returnErrorPtr()

void * returnErrorPtr	(	const char *	msg,
		const char *	procname,
		void *	pval )

returnErrorPtr()

Parameters

[in]	msg	error message
[in]	procname	use func
[in]	pval	return error val (typically null for an error)

Returns: pval

Definition at line 237 of file utils1.c.

References lept_stderr().

◆ returnErrorPtr1()

void * returnErrorPtr1	(	const char *	msg,
		const char *	arg,
		const char *	procname,
		void *	pval )

returnErrorPtr1()

Parameters

[in]	msg	error message
[in]	arg	additional error message argument (will be appended to the error message)
[in]	procname	use func
[in]	pval	return error val (typically null for an error)

Returns: pval

Definition at line 299 of file utils1.c.

References lept_stderr().

◆ setMsgSeverity()

l_int32 setMsgSeverity ( l_int32 newsev )

setMsgSeverity()

Parameters

[in] newsev

Returns: oldsev

Notes:
     (1) setMsgSeverity() allows the user to specify the desired
         message severity threshold.  Messages of equal or greater
         severity will be output.  The previous message severity is
         returned when the new severity is set.
     (2) If L_SEVERITY_EXTERNAL is passed, then the severity will be
         obtained from the LEPT_MSG_SEVERITY environment variable.

Definition at line 148 of file utils1.c.

References LeptMsgSeverity.

◆ startTimer()

void startTimer ( void )

startTimer(), stopTimer()

Notes: (1) These measure the cpu time elapsed between the two calls: startTimer(); .... lept_stderr( "Elapsed time = %7.3f sec\n", stopTimer());

Definition at line 1125 of file utils1.c.

◆ startTimerNested()

L_TIMER startTimerNested ( void )

startTimerNested(), stopTimerNested()

Example of usage:

L_TIMER  t1 = startTimerNested();
....
L_TIMER  t2 = startTimerNested();
....
lept_stderr( "Elapsed time 2 = %7.3f sec\n", stopTimerNested(t2));
....
lept_stderr( "Elapsed time 1 = %7.3f sec\n", stopTimerNested(t1));

Definition at line 1157 of file utils1.c.

◆ startWallTimer()

L_WALLTIMER * startWallTimer ( void )

startWallTimer()

Returns: walltimer-ptr

Notes:
     (1) These measure the wall clock time  elapsed between the two calls:
           L_WALLTIMER *timer = startWallTimer();
           ....
           lept_stderr( "Elapsed time = %f sec\n", stopWallTimer(&timer);
     (2) Note that the timer object is destroyed by stopWallTimer().

Definition at line 1352 of file utils1.c.

References l_getCurrentTime().

◆ stopTimer()

l_float32 stopTimer ( void )

Definition at line 1131 of file utils1.c.

◆ stopTimerNested()

l_float32 stopTimerNested ( L_TIMER rusage_start )

Definition at line 1167 of file utils1.c.

◆ stopWallTimer()

l_float32 stopWallTimer ( L_WALLTIMER ** ptimer )

stopWallTimer()

Parameters

[in,out] ptimer walltimer pointer

Returns: time wall time elapsed in seconds

Definition at line 1368 of file utils1.c.

References l_getCurrentTime().

Variable Documentation

◆ LeptMsgSeverity

LEPT_DLL l_int32 LeptMsgSeverity = DEFAULT_SEVERITY

The run-time message severity threshold is defined in utils1.c.

Definition at line 124 of file utils1.c.

Referenced by setMsgSeverity().

◆ rusage_after

struct rusage rusage_after

static

Definition at line 1113 of file utils1.c.

◆ rusage_before

struct rusage rusage_before

static

Definition at line 1112 of file utils1.c.

◆ stderr_handler

void(* stderr_handler) (const char *) ( const char * ) = lept_default_stderr_handler

Definition at line 335 of file utils1.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEBUG_SEV

◆ MAX_DEBUG_MESSAGE

Function Documentation

◆ convertGrayCodeToInt()

◆ convertIntToGrayCode()

◆ convertOnBigEnd16()

◆ convertOnBigEnd32()

◆ convertOnLittleEnd16()

◆ convertOnLittleEnd32()

◆ fileCorruptByDeletion()

◆ fileCorruptByMutation()

◆ fileReplaceBytes()

◆ filesAreIdentical()

◆ findNextLargerPrime()

◆ genRandomIntOnInterval()

◆ getLeptonicaVersion()

◆ l_getCurrentTime()

◆ l_getFormattedDate()

◆ l_hashFloat64ToUint64()

◆ l_hashPtToUint64()

◆ l_hashStringToUint64()

◆ l_hashStringToUint64Fast()

◆ lept_ceiling()

◆ lept_default_stderr_handler()

◆ lept_floor()

◆ lept_isPrime()

◆ lept_roundftoi()

◆ lept_stderr()

◆ leptSetStderrHandler()

◆ returnErrorFloat()

◆ returnErrorFloat1()

◆ returnErrorInt()

◆ returnErrorInt1()

◆ returnErrorPtr()

◆ returnErrorPtr1()

◆ setMsgSeverity()

◆ startTimer()

◆ startTimerNested()

◆ startWallTimer()

◆ stopTimer()

◆ stopTimerNested()

◆ stopWallTimer()

Variable Documentation

◆ LeptMsgSeverity

◆ rusage_after

◆ rusage_before

◆ stderr_handler