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

Macros
#define	DEBUG_SEV 0

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_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	genRandomIntegerInRange (l_int32 range, l_int32 seed, l_int32 *pval)

l_int32	lept_roundftoi (l_float32 fval)

l_ok	l_hashStringToUint64 (const char str, l_uint64 phash)

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

l_ok	l_hashFloat64ToUint64 (l_int32 nbuckets, 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	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 ()

Variables
LEPT_DLL l_int32	LeptMsgSeverity = DEFAULT_SEVERITY

static struct rusage	rusage_before

static struct rusage	rusage_after

Detailed Description



      This file has these utilities:
error, warning and info messages
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()

      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 operation
          l_int32    fileCorruptByDeletion()
          l_int32    fileCorruptByMutation()

      Generate random integer in given range
          l_int32    genRandomIntegerInRange()

      Simple math function
          l_int32    lept_roundftoi()

      64-bit hash functions
          l_int32    l_hashStringToUint64()
          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.

Function Documentation

◆ convertGrayCodeToInt()

l_uint32 convertGrayCodeToInt ( l_uint32 val )

convertGrayCodeToInt()

Parameters

[in] val gray code value

Returns: corresponding integer value

Definition at line 788 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 775 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 388 of file utils1.c.

References l_binaryRead(), and l_binaryWrite().

◆ 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 452 of file utils1.c.

References l_binaryRead(), and l_binaryWrite().

◆ 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 244 of file utils1.c.

References l_binaryRead(), and nbytesInFile().

◆ 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 689 of file utils1.c.

References lept_isPrime().

Referenced by l_dnaHashCreateFromDna(), l_dnaHashCreateFromPta(), l_dnaHashCreateFromSarray(), l_dnaIntersectionByHash(), l_dnaMakeHistoByHash(), l_dnaRemoveDupsByHash(), ptaIntersectionByHash(), ptaRemoveDupsByHash(), sarrayIntersectionByHash(), and sarrayRemoveDupsByHash().

◆ genRandomIntegerInRange()

l_ok genRandomIntegerInRange	(	l_int32	range,
		l_int32	seed,
		l_int32 *	pval
	)

genRandomIntegerInRange()

Parameters

[in]	range	size of range; must be >= 2
[in]	seed	use 0 to skip; otherwise call srand
[out]	pval	random integer in range {0 ... range-1}

Returns: 0 if OK, 1 on error

Notes:
     (1) For example, to choose a rand integer between 0 and 99,
         use range = 100.

Definition at line 510 of file utils1.c.

Referenced by sudokuGenerate().

◆ getLeptonicaVersion()

char* getLeptonicaVersion ( )

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 810 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 935 of file utils1.c.

Referenced by startWallTimer(), and stopWallTimer().

◆ l_getFormattedDate()

char* l_getFormattedDate ( )

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 1115 of file utils1.c.

References stringNew().

◆ l_hashFloat64ToUint64()

l_ok l_hashFloat64ToUint64	(	l_int32	nbuckets,
		l_float64	val,
		l_uint64 *	phash
	)

l_hashFloat64ToUint64()

Parameters

[in]	nbuckets
[in]	val
[out]	phash	hash value

Returns: 0 if OK, 1 on error

Notes:
     (1) Simple, fast hash for using dnaHash with 64-bit data
         (e.g., sets and histograms).
     (2) The resulting hash is called a "key" in a lookup
         operation.  The bucket for val in a dnaHash is simply
         found by taking the mod of the hash with the number of
         buckets (which is prime).  What gets stored in the
         dna in that bucket could depend on use, but for the most
         flexibility, we store an index into the associated dna.
         This is all that is required for generating either a hash set
         or a histogram (an example of a hash map).
     (3) For example, to generate a histogram, the histogram dna,
         a histogram of unique values aligned with the histogram dna,
         and a dnahash hashmap are built.  See l_dnaMakeHistoByHash().

Definition at line 665 of file utils1.c.

Referenced by l_dnaFindValByHash(), l_dnaHashCreateFromDna(), l_dnaIntersectionByHash(), l_dnaMakeHistoByHash(), and l_dnaRemoveDupsByHash().

◆ 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) I found that a simple hash function has no collisions for
         any of 400 million points with x and y up to 20000.
     (2) Previously used a much more complicated and slower function:
           mulp = 26544357894361;
           hash = 104395301;
           hash += (x * mulp) ^ (hash >> 5);
           hash ^= (hash << 7);
           hash += (y * mulp) ^ (hash >> 7);
           hash = hash ^ (hash << 11);
         Such logical gymnastics to get coverage over the 2^64
         values are not required.

Definition at line 625 of file utils1.c.

Referenced by l_dnaHashCreateFromPta(), ptaFindPtByHash(), ptaIntersectionByHash(), and ptaRemoveDupsByHash().

◆ l_hashStringToUint64()

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

l_hashStringToUint64()

Parameters

[in]	str
[out]	phash	hash vale

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 579 of file utils1.c.

Referenced by l_dnaHashCreateFromSarray(), sarrayFindStringByHash(), sarrayIntersectionByHash(), and sarrayRemoveDupsByHash().

◆ 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 724 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 int

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 547 of file utils1.c.

Referenced by numaGetBinnedMedian(), pixaDisplayTiledByIndex(), and pixCompareWithTranslation().

◆ returnErrorFloat()

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

returnErrorFloat()

Parameters

[in]	msg	error message
[in]	procname
[in]	fval	return val

Returns: fval

Definition at line 205 of file utils1.c.

◆ returnErrorInt()

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

returnErrorInt()

Parameters

[in]	msg	error message
[in]	procname
[in]	ival	return val

Returns: ival typically 1 for an error return

Definition at line 187 of file utils1.c.

◆ returnErrorPtr()

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

returnErrorPtr()

Parameters

[in]	msg	error message
[in]	procname
[in]	pval	return val

Returns: pval typically null

Definition at line 223 of file utils1.c.

◆ 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 136 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(); .... fprintf(stderr, "Elapsed time = %7.3f sec\n", stopTimer());

Definition at line 869 of file utils1.c.

◆ startTimerNested()

L_TIMER startTimerNested ( void )

startTimerNested(), stopTimerNested()

Example of usage:

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

Definition at line 901 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();
           ....
           fprintf(stderr, "Elapsed time = %f sec\n", stopWallTimer(&timer);
     (2) Note that the timer object is destroyed by stopWallTimer().

Definition at line 1064 of file utils1.c.

References l_getCurrentTime().

◆ stopWallTimer()

l_float32 stopWallTimer ( L_WALLTIMER ** ptimer )

stopWallTimer()

Parameters

[in,out] ptimer walltimer-ptr

Returns: time wall time elapsed in seconds

Definition at line 1080 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 utils.c.

Definition at line 112 of file utils1.c.

Referenced by setMsgSeverity().

Macros

Functions

Variables

Detailed Description

- timing and date operations

Function Documentation

◆ convertGrayCodeToInt()

◆ convertIntToGrayCode()

◆ fileCorruptByDeletion()

◆ fileCorruptByMutation()

◆ filesAreIdentical()

◆ findNextLargerPrime()

◆ genRandomIntegerInRange()

◆ getLeptonicaVersion()

◆ l_getCurrentTime()

◆ l_getFormattedDate()

◆ l_hashFloat64ToUint64()

◆ l_hashPtToUint64()

◆ l_hashStringToUint64()

◆ lept_isPrime()

◆ lept_roundftoi()

◆ returnErrorFloat()

◆ returnErrorInt()

◆ returnErrorPtr()

◆ setMsgSeverity()

◆ startTimer()

◆ startTimerNested()

◆ startWallTimer()

◆ stopWallTimer()

Variable Documentation

◆ LeptMsgSeverity