#include <string.h>
#include "allheaders.h"
#include "pix_internal.h"

Functions
BOX *	boxCreate (l_int32 x, l_int32 y, l_int32 w, l_int32 h)

BOX *	boxCreateValid (l_int32 x, l_int32 y, l_int32 w, l_int32 h)

BOX *	boxCopy (BOX *box)

BOX *	boxClone (BOX *box)

void	boxDestroy (BOX **pbox)

l_ok	boxGetGeometry (const BOX box, l_int32 px, l_int32 py, l_int32 pw, l_int32 *ph)

l_ok	boxSetGeometry (BOX *box, l_int32 x, l_int32 y, l_int32 w, l_int32 h)

l_ok	boxGetSideLocations (const BOX box, l_int32 pl, l_int32 pr, l_int32 pt, l_int32 *pb)

l_ok	boxSetSideLocations (BOX *box, l_int32 l, l_int32 r, l_int32 t, l_int32 b)

l_ok	boxIsValid (BOX box, l_int32 pvalid)

BOXA *	boxaCreate (l_int32 n)

BOXA *	boxaCopy (BOXA *boxa, l_int32 copyflag)

void	boxaDestroy (BOXA **pboxa)

l_ok	boxaAddBox (BOXA boxa, BOX box, l_int32 copyflag)

l_ok	boxaExtendArray (BOXA *boxa)

l_ok	boxaExtendArrayToSize (BOXA *boxa, size_t size)

l_int32	boxaGetCount (const BOXA *boxa)

l_int32	boxaGetValidCount (BOXA *boxa)

BOX *	boxaGetBox (BOXA *boxa, l_int32 index, l_int32 accessflag)

BOX *	boxaGetValidBox (BOXA *boxa, l_int32 index, l_int32 accessflag)

NUMA *	boxaFindInvalidBoxes (BOXA *boxa)

l_ok	boxaGetBoxGeometry (BOXA boxa, l_int32 index, l_int32 px, l_int32 py, l_int32 pw, l_int32 *ph)

l_ok	boxaIsFull (BOXA boxa, l_int32 pfull)

l_ok	boxaReplaceBox (BOXA boxa, l_int32 index, BOX box)

l_ok	boxaInsertBox (BOXA boxa, l_int32 index, BOX box)

l_ok	boxaRemoveBox (BOXA *boxa, l_int32 index)

l_ok	boxaRemoveBoxAndSave (BOXA boxa, l_int32 index, BOX *pbox)

BOXA *	boxaSaveValid (BOXA *boxas, l_int32 copyflag)

l_ok	boxaInitFull (BOXA boxa, BOX box)

l_ok	boxaClear (BOXA *boxa)

BOXAA *	boxaaCreate (l_int32 n)

BOXAA *	boxaaCopy (BOXAA *baas, l_int32 copyflag)

void	boxaaDestroy (BOXAA **pbaa)

l_ok	boxaaAddBoxa (BOXAA baa, BOXA ba, l_int32 copyflag)

l_ok	boxaaExtendArray (BOXAA *baa)

l_ok	boxaaExtendArrayToSize (BOXAA *baa, l_int32 size)

l_int32	boxaaGetCount (BOXAA *baa)

l_int32	boxaaGetBoxCount (BOXAA *baa)

BOXA *	boxaaGetBoxa (BOXAA *baa, l_int32 index, l_int32 accessflag)

BOX *	boxaaGetBox (BOXAA *baa, l_int32 iboxa, l_int32 ibox, l_int32 accessflag)

l_ok	boxaaInitFull (BOXAA baa, BOXA boxa)

l_ok	boxaaExtendWithInit (BOXAA baa, l_int32 maxindex, BOXA boxa)

l_ok	boxaaReplaceBoxa (BOXAA baa, l_int32 index, BOXA boxa)

l_ok	boxaaInsertBoxa (BOXAA baa, l_int32 index, BOXA boxa)

l_ok	boxaaRemoveBoxa (BOXAA *baa, l_int32 index)

l_ok	boxaaAddBox (BOXAA baa, l_int32 index, BOX box, l_int32 accessflag)

BOXAA *	boxaaReadFromFiles (const char dirname, const char substr, l_int32 first, l_int32 nfiles)

BOXAA *	boxaaRead (const char *filename)

BOXAA *	boxaaReadStream (FILE *fp)

BOXAA *	boxaaReadMem (const l_uint8 *data, size_t size)

l_ok	boxaaWrite (const char filename, BOXAA baa)

l_ok	boxaaWriteStream (FILE fp, BOXAA baa)

l_ok	boxaaWriteMem (l_uint8 *pdata, size_t psize, BOXAA *baa)

BOXA *	boxaRead (const char *filename)

BOXA *	boxaReadStream (FILE *fp)

BOXA *	boxaReadMem (const l_uint8 *data, size_t size)

l_ok	boxaWriteDebug (const char filename, BOXA boxa)

l_ok	boxaWrite (const char filename, BOXA boxa)

l_ok	boxaWriteStream (FILE fp, BOXA boxa)

l_ok	boxaWriteStderr (BOXA *boxa)

l_ok	boxaWriteMem (l_uint8 *pdata, size_t psize, BOXA *boxa)

l_ok	boxPrintStreamInfo (FILE fp, BOX box)

Variables
static const size_t	MaxBoxaPtrArraySize = 10000000

static const size_t	MaxBoxaaPtrArraySize = 1000000

static const size_t	InitialPtrArraySize = 20

Detailed Description


  Basic 'class' functions for box, boxa and boxaa,
  including accessors and serialization.

     Box creation, copy, clone, destruction
          BOX      *boxCreate()
          BOX      *boxCreateValid()
          BOX      *boxCopy()
          BOX      *boxClone()
          void      boxDestroy()

     Box accessors
          l_int32   boxGetGeometry()
          l_int32   boxSetGeometry()
          l_int32   boxGetSideLocations()
          l_int32   boxSetSideLocations()
          l_int32   boxIsValid()

     Boxa creation, copy, destruction
          BOXA     *boxaCreate()
          BOXA     *boxaCopy()
          void      boxaDestroy()

     Boxa array extension
          l_int32   boxaAddBox()
          l_int32   boxaExtendArray()
          l_int32   boxaExtendArrayToSize()

     Boxa accessors
          l_int32   boxaGetCount()
          l_int32   boxaGetValidCount()
          BOX      *boxaGetBox()
          BOX      *boxaGetValidBox()
          NUMA     *boxaFindInvalidBoxes()
          l_int32   boxaGetBoxGeometry()
          l_int32   boxaIsFull()

     Boxa array modifiers
          l_int32   boxaReplaceBox()
          l_int32   boxaInsertBox()
          l_int32   boxaRemoveBox()
          l_int32   boxaRemoveBoxAndSave()
          BOXA     *boxaSaveValid()
          l_int32   boxaInitFull()
          l_int32   boxaClear()

     Boxaa creation, copy, destruction
          BOXAA    *boxaaCreate()
          BOXAA    *boxaaCopy()
          void      boxaaDestroy()

     Boxaa array extension
          l_int32   boxaaAddBoxa()
          l_int32   boxaaExtendArray()
          l_int32   boxaaExtendArrayToSize()

     Boxaa accessors
          l_int32   boxaaGetCount()
          l_int32   boxaaGetBoxCount()
          BOXA     *boxaaGetBoxa()
          BOX      *boxaaGetBox()

     Boxaa array modifiers
          l_int32   boxaaInitFull()
          l_int32   boxaaExtendWithInit()
          l_int32   boxaaReplaceBoxa()
          l_int32   boxaaInsertBoxa()
          l_int32   boxaaRemoveBoxa()
          l_int32   boxaaAddBox()

     Boxaa serialized I/O
          BOXAA    *boxaaReadFromFiles()
          BOXAA    *boxaaRead()
          BOXAA    *boxaaReadStream()
          BOXAA    *boxaaReadMem()
          l_int32   boxaaWrite()
          l_int32   boxaaWriteStream()
          l_int32   boxaaWriteMem()

     Boxa serialized I/O
          BOXA     *boxaRead()
          BOXA     *boxaReadStream()
          BOXA     *boxaReadMem()
          l_int32   boxaWriteDebug()
          l_int32   boxaWrite()
          l_int32   boxaWriteStream()
          l_int32   boxaWriteStderr()
          l_int32   boxaWriteMem()

     Box print (for debug)
          l_int32   boxPrintStreamInfo()

  Most functions use only valid boxes, which are boxes that have both
  width and height > 0.  However, a few functions, such as
  boxaGetMedianVals() do not assume that all boxes are valid.  For any
  function that can use a boxa with invalid boxes, it is convenient
  to use these accessors:
      boxaGetValidCount()   :  count of valid boxes
      boxaGetValidBox()     :  returns NULL for invalid boxes

Definition in file boxbasic.c.

Function Documentation

◆ boxaaAddBox()

l_ok boxaaAddBox	(	BOXAA *	baa,
		l_int32	index,
		BOX *	box,
		l_int32	accessflag )

boxaaAddBox()

Parameters

[in]	baa
[in]	index	of boxa with boxaa
[in]	box	to be added
[in]	accessflag	L_INSERT, L_COPY or L_CLONE

Returns: 0 if OK, 1 on error

Notes:
     (1) Adds to an existing boxa only.

Definition at line 1667 of file boxbasic.c.

References boxaAddBox(), boxaaGetBoxa(), boxaaGetCount(), boxaDestroy(), L_CLONE, L_COPY, and L_INSERT.

◆ boxaaAddBoxa()

l_ok boxaaAddBoxa	(	BOXAA *	baa,
		BOXA *	ba,
		l_int32	copyflag )

boxaaAddBoxa()

Parameters

[in]	baa
[in]	ba	to be added
[in]	copyflag	L_INSERT, L_COPY, L_CLONE

Returns: 0 if OK, 1 on error

Definition at line 1241 of file boxbasic.c.

References Boxaa::boxa, boxaaExtendArray(), boxaaGetCount(), boxaCopy(), L_CLONE, L_COPY, L_INSERT, Boxaa::n, and Boxaa::nalloc.

Referenced by boxaaCopy(), boxaaExtendWithInit(), boxaaReadFromFiles(), and boxaaReadStream().

◆ boxaaCopy()

BOXAA * boxaaCopy	(	BOXAA *	baas,
		l_int32	copyflag )

boxaaCopy()

Parameters

[in]	baas	input boxaa to be copied
[in]	copyflag	L_COPY, L_CLONE

Returns: baad new boxaa, composed of copies or clones of the boxa in baas, or NULL on error

Notes:
     (1) L_COPY makes a copy of each boxa in baas.
         L_CLONE makes a clone of each boxa in baas.

Definition at line 1178 of file boxbasic.c.

References boxaaAddBoxa(), boxaaCreate(), boxaaGetBoxa(), boxaaGetCount(), L_CLONE, L_COPY, and L_INSERT.

◆ boxaaCreate()

BOXAA * boxaaCreate ( l_int32 n )

boxaaCreate()

Parameters

[in] n size of boxa ptr array to be alloc'd; 0 for default

Returns: baa, or NULL on error

Definition at line 1145 of file boxbasic.c.

References Boxaa::boxa, boxaaDestroy(), InitialPtrArraySize, Boxaa::n, and Boxaa::nalloc.

Referenced by boxaaCopy(), boxaaReadFromFiles(), and boxaaReadStream().

◆ boxaAddBox()

l_ok boxaAddBox	(	BOXA *	boxa,
		BOX *	box,
		l_int32	copyflag )

boxaAddBox()

Parameters

[in]	boxa
[in]	box	to be added
[in]	copyflag	L_INSERT, L_COPY, L_CLONE

Returns: 0 if OK, 1 on error

Definition at line 553 of file boxbasic.c.

References Boxa::box, boxaExtendArray(), boxaGetCount(), boxClone(), boxCopy(), boxDestroy(), L_CLONE, L_COPY, L_INSERT, Boxa::n, and Boxa::nalloc.

Referenced by boxaaAddBox(), boxaCopy(), boxaReadStream(), and boxaSaveValid().

◆ boxaaDestroy()

void boxaaDestroy ( BOXAA ** pbaa )

boxaaDestroy()

Parameters

[in,out] pbaa will be set to null before returning

Definition at line 1207 of file boxbasic.c.

References Boxaa::boxa, boxaDestroy(), and Boxaa::n.

Referenced by boxaaCreate(), and boxaaReadStream().

◆ boxaaExtendArray()

l_ok boxaaExtendArray ( BOXAA * baa )

boxaaExtendArray()

Parameters

[in] baa

Returns: 0 if OK, 1 on error

Notes:
     (1) Doubles the size of the boxa ptr array.
     (2) The max number of boxa ptrs is 1 million.

Definition at line 1284 of file boxbasic.c.

References boxaaExtendArrayToSize(), and Boxaa::nalloc.

Referenced by boxaaAddBoxa(), and boxaaInsertBoxa().

◆ boxaaExtendArrayToSize()

l_ok boxaaExtendArrayToSize	(	BOXAA *	baa,
		l_int32	size )

boxaaExtendArrayToSize()

Parameters

[in]	baa
[in]	size	new size of boxa array

Returns: 0 if OK; 1 on error

Notes:
     (1) If necessary, reallocs the boxa ptr array to size.
     (2) size limited to 1M boxa ptrs.

Definition at line 1307 of file boxbasic.c.

References Boxaa::boxa, and Boxaa::nalloc.

Referenced by boxaaExtendArray(), and boxaaExtendWithInit().

◆ boxaaExtendWithInit()

l_ok boxaaExtendWithInit	(	BOXAA *	baa,
		l_int32	maxindex,
		BOXA *	boxa )

boxaaExtendWithInit()

Parameters

[in]	baa
[in]	maxindex
[in]	boxa	to be replicated into the extended ptr array

Returns: 0 if OK, 1 on error

Notes:
     (1) This should be used on an existing boxaa that has been
         fully loaded with boxa.  It then extends the boxaa,
         loading all the additional ptrs with copies of boxa.
         Typically, boxa will be empty.

Definition at line 1502 of file boxbasic.c.

References boxaaAddBoxa(), boxaaExtendArrayToSize(), boxaaGetCount(), and L_COPY.

◆ boxaaGetBox()

BOX * boxaaGetBox	(	BOXAA *	baa,
		l_int32	iboxa,
		l_int32	ibox,
		l_int32	accessflag )

boxaaGetBox()

Parameters

[in]	baa
[in]	iboxa	index into the boxa array in the boxaa
[in]	ibox	index into the box array in the boxa
[in]	accessflag	L_COPY or L_CLONE

Returns: box, or NULL on error

Definition at line 1414 of file boxbasic.c.

References boxaaGetBoxa(), boxaDestroy(), boxaGetBox(), and L_CLONE.

◆ boxaaGetBoxa()

BOXA * boxaaGetBoxa	(	BOXAA *	baa,
		l_int32	index,
		l_int32	accessflag )

boxaaGetBoxa()

Parameters

[in]	baa
[in]	index	to the index-th boxa
[in]	accessflag	L_COPY or L_CLONE

Returns: boxa, or NULL on error

Definition at line 1386 of file boxbasic.c.

References Boxaa::boxa, boxaaGetCount(), boxaCopy(), L_CLONE, and L_COPY.

Referenced by boxaaAddBox(), boxaaCopy(), boxaaGetBox(), boxaaGetBoxCount(), and boxaaWriteStream().

◆ boxaaGetBoxCount()

l_int32 boxaaGetBoxCount ( BOXAA * baa )

boxaaGetBoxCount()

Parameters

[in] baa

Returns: count number of boxes, or 0 if no boxes or on error

Definition at line 1358 of file boxbasic.c.

References boxaaGetBoxa(), boxaaGetCount(), boxaDestroy(), boxaGetCount(), and L_CLONE.

◆ boxaaGetCount()

l_int32 boxaaGetCount ( BOXAA * baa )

boxaaGetCount()

Parameters

[in] baa

Returns: count number of boxa, or 0 if no boxa or on error

Definition at line 1343 of file boxbasic.c.

References Boxaa::n.

Referenced by boxaaAddBox(), boxaaAddBoxa(), boxaaCopy(), boxaaExtendWithInit(), boxaaGetBoxa(), boxaaGetBoxCount(), boxaaInsertBoxa(), boxaaRemoveBoxa(), boxaaReplaceBoxa(), and boxaaWriteStream().

◆ boxaaInitFull()

l_ok boxaaInitFull	(	BOXAA *	baa,
		BOXA *	boxa )

boxaaInitFull()

Parameters

[in]	baa	typically empty
[in]	boxa	to be replicated into the entire ptr array

Returns: 0 if OK, 1 on error

Notes:
     (1) This initializes a boxaa by filling up the entire boxa ptr array
         with copies of boxa.  Any existing boxa are destroyed.
         After this operation, the number of boxa is equal to
         the number of allocated ptrs.
     (2) Note that we use boxaaReplaceBoxa() which replaces a boxa,
         instead of boxaaInsertBoxa(), which is O(n) and shifts all
         the boxa pointers from the insertion point to the end.
     (3) Example usage.  This function is useful to prepare for a
         random insertion (or replacement) of boxa into a boxaa.
         To randomly insert boxa into a boxaa, up to some index "max":
            Boxaa *baa = boxaaCreate(max);
              // initialize the boxa
            Boxa *boxa = boxaCreate(...);
            ...  [optionally fill with boxes]
            boxaaInitFull(baa, boxa);
         A typical use is to initialize the array with empty boxa,
         and to replace only a subset that must be aligned with
         something else, such as a pixa.

Definition at line 1464 of file boxbasic.c.

References boxaaReplaceBoxa(), boxaCopy(), L_COPY, Boxaa::n, and Boxaa::nalloc.

◆ boxaaInsertBoxa()

l_ok boxaaInsertBoxa	(	BOXAA *	baa,
		l_int32	index,
		BOXA *	boxa )

boxaaInsertBoxa()

Parameters

[in]	baa
[in]	index	location in boxaa to insert new boxa
[in]	boxa	new boxa to be inserted

Returns: 0 if OK, 1 on error

Notes:
     (1) This shifts boxa[i] --> boxa[i + 1] for all i >= index,
         and then inserts boxa as boxa[index].  It is typically used
         when baa is full of boxa.
     (2) To insert at the beginning of the array, set index = 0.
     (3) To append to the array, it is equivalent to boxaaAddBoxa().
     (4) This should not be used repeatedly to insert into large arrays,
         because the function is O(n).

Definition at line 1582 of file boxbasic.c.

References Boxaa::boxa, boxaaExtendArray(), boxaaGetCount(), Boxaa::n, and Boxaa::nalloc.

◆ boxaaRead()

BOXAA * boxaaRead ( const char * filename )

boxaaRead()

Parameters

[in] filename

Returns: boxaa, or NULL on error

Definition at line 1755 of file boxbasic.c.

References boxaaReadStream().

◆ boxaaReadFromFiles()

BOXAA * boxaaReadFromFiles	(	const char *	dirname,
		const char *	substr,
		l_int32	first,
		l_int32	nfiles )

boxaaReadFromFiles()

Parameters

[in]	dirname	directory
[in]	substr	[optional] substring filter on filenames; can be NULL
[in]	first	0-based
[in]	nfiles	use 0 for everything from first to the end

Returns: baa, or NULL on error or if no boxa files are found.

Notes:
     (1) The files must be serialized boxa files (e.g., *.ba).
         If some files cannot be read, warnings are issued.
     (2) Use substr to filter filenames in the directory.  If
         substr == NULL, this takes all files.
     (3) After filtering, use first and nfiles to select
         a contiguous set of files, that have been lexically
         sorted in increasing order.

Definition at line 1713 of file boxbasic.c.

References boxaaAddBoxa(), boxaaCreate(), boxaRead(), L_INSERT, and L_NOCOPY.

◆ boxaaReadMem()

BOXAA * boxaaReadMem	(	const l_uint8 *	data,
		size_t	size )

boxaaReadMem()

Parameters

[in]	data	serialization of boxaa; in ascii
[in]	size	of data in bytes; can use strlen to get it

Returns: baa, or NULL on error

Definition at line 1835 of file boxbasic.c.

References boxaaReadStream().

◆ boxaaReadStream()

BOXAA * boxaaReadStream ( FILE * fp )

boxaaReadStream()

Parameters

[in] fp input file stream

Returns: boxaa, or NULL on error

Notes:
     (1) It is OK for the boxaa to be empty (n == 0).

Definition at line 1787 of file boxbasic.c.

References BOXAA_VERSION_NUMBER, boxaaAddBoxa(), boxaaCreate(), boxaaDestroy(), boxaReadStream(), and L_INSERT.

Referenced by boxaaRead(), and boxaaReadMem().

◆ boxaaRemoveBoxa()

l_ok boxaaRemoveBoxa	(	BOXAA *	baa,
		l_int32	index )

boxaaRemoveBoxa()

Parameters

[in]	baa
[in]	index	of the boxa to be removed and destroyed

Returns: 0 if OK, 1 on error

Notes:
     (1) This removes boxa[index] and then shifts
         boxa[i] --> boxa[i - 1] for all i > index.
     (2) The removed boxaa is destroyed.
     (2) This should not be used repeatedly on large arrays,
         because the function is O(n).

Definition at line 1629 of file boxbasic.c.

References Boxaa::boxa, boxaaGetCount(), boxaDestroy(), and Boxaa::n.

◆ boxaaReplaceBoxa()

l_ok boxaaReplaceBoxa	(	BOXAA *	baa,
		l_int32	index,
		BOXA *	boxa )

boxaaReplaceBoxa()

Parameters

[in]	baa
[in]	index	to the index-th boxa
[in]	boxa	insert and replace any existing one

Returns: 0 if OK, 1 on error

Notes:
     (1) Any existing boxa is destroyed, and the input one
         is inserted in its place.
     (2) If the index is invalid, return 1 (error)

Definition at line 1542 of file boxbasic.c.

References Boxaa::boxa, boxaaGetCount(), and boxaDestroy().

Referenced by boxaaInitFull().

◆ boxaaWrite()

l_ok boxaaWrite	(	const char *	filename,
		BOXAA *	baa )

boxaaWrite()

Parameters

[in]	filename
[in]	baa

Returns: 0 if OK, 1 on error

Definition at line 1861 of file boxbasic.c.

References boxaaWriteStream().

◆ boxaaWriteMem()

l_ok boxaaWriteMem	(	l_uint8 **	pdata,
		size_t *	psize,
		BOXAA *	baa )

boxaaWriteMem()

Parameters

[out]	pdata	data of serialized boxaa; ascii
[out]	psize	size of returned data
[in]	baa

Returns: 0 if OK, 1 on error

Notes:
     (1) Serializes a boxaa in memory and puts the result in a buffer.

Definition at line 1935 of file boxbasic.c.

References boxaaWriteStream().

◆ boxaaWriteStream()

l_ok boxaaWriteStream	(	FILE *	fp,
		BOXAA *	baa )

boxaaWriteStream()

Parameters

[in]	fp	output file stream
[in]	baa

Returns: 0 if OK, 1 on error

Definition at line 1890 of file boxbasic.c.

References BOXAA_VERSION_NUMBER, boxaaGetBoxa(), boxaaGetCount(), boxaDestroy(), boxaWriteStream(), boxDestroy(), boxGetGeometry(), and L_CLONE.

Referenced by boxaaWrite(), and boxaaWriteMem().

◆ boxaClear()

l_ok boxaClear ( BOXA * boxa )

boxaClear()

Parameters

[in] boxa

Returns: 0 if OK, 1 on error

Notes:
     (1) This destroys all boxes in the boxa, setting the ptrs
         to null.  The number of allocated boxes, n, is set to 0.

Definition at line 1120 of file boxbasic.c.

References Boxa::box, boxaGetCount(), boxDestroy(), and Boxa::n.

◆ boxaCopy()

BOXA * boxaCopy	(	BOXA *	boxa,
		l_int32	copyflag )

boxaCopy()

Parameters

[in]	boxa
[in]	copyflag	L_COPY, L_CLONE, L_COPY_CLONE

Returns: new boxa, or NULL on error

Notes:
     (1) See pix.h for description of the copyflag.
     (2) The copy-clone makes a new boxa that holds clones of each box.

Definition at line 475 of file boxbasic.c.

References boxaAddBox(), boxaCreate(), boxaGetBox(), L_CLONE, L_COPY, L_COPY_CLONE, L_INSERT, Boxa::n, Boxa::nalloc, and Boxa::refcount.

Referenced by boxaaAddBoxa(), boxaaGetBoxa(), and boxaaInitFull().

◆ boxaCreate()

BOXA * boxaCreate ( l_int32 n )

boxaCreate()

Parameters

[in] n initial number of ptrs; 0 for default

Returns: boxa, or NULL on error

Definition at line 442 of file boxbasic.c.

References Boxa::box, boxaDestroy(), InitialPtrArraySize, Boxa::n, Boxa::nalloc, and Boxa::refcount.

Referenced by boxaCopy(), boxaReadStream(), and boxaSaveValid().

◆ boxaDestroy()

void boxaDestroy ( BOXA ** pboxa )

boxaDestroy()

Parameters

[in,out] pboxa will be set to null before returning

Returns: void

Notes:
     (1) Decrements the ref count and, if 0, destroys the boxa.
     (2) Always nulls the input ptr.

Definition at line 519 of file boxbasic.c.

References Boxa::box, boxDestroy(), Boxa::n, and Boxa::refcount.

Referenced by boxaaAddBox(), boxaaDestroy(), boxaaGetBox(), boxaaGetBoxCount(), boxaaRemoveBoxa(), boxaaReplaceBoxa(), boxaaWriteStream(), boxaCreate(), and boxaReadStream().

◆ boxaExtendArray()

l_ok boxaExtendArray ( BOXA * boxa )

boxaExtendArray()

Parameters

[in] boxa

Returns: 0 if OK; 1 on error

Notes:
     (1) Reallocs with doubled size of ptr array.

Definition at line 602 of file boxbasic.c.

References boxaExtendArrayToSize(), and Boxa::nalloc.

Referenced by boxaAddBox(), and boxaInsertBox().

◆ boxaExtendArrayToSize()

l_ok boxaExtendArrayToSize	(	BOXA *	boxa,
		size_t	size )

boxaExtendArrayToSize()

Parameters

[in]	boxa
[in]	size	new size of boxa ptr array

Returns: 0 if OK; 1 on error

Notes:
     (1) If necessary, reallocs new boxa ptr array to size.
     (2) The max number of box ptrs is 10M.

Definition at line 625 of file boxbasic.c.

References Boxa::box, and Boxa::nalloc.

Referenced by boxaExtendArray().

◆ boxaFindInvalidBoxes()

NUMA * boxaFindInvalidBoxes ( BOXA * boxa )

boxaFindInvalidBoxes()

Parameters

[in] boxa

Returns: na numa of invalid boxes; NULL if there are none or on error

Definition at line 765 of file boxbasic.c.

References boxaGetBoxGeometry(), boxaGetCount(), and boxaGetValidCount().

◆ boxaGetBox()

BOX * boxaGetBox	(	BOXA *	boxa,
		l_int32	index,
		l_int32	accessflag )

boxaGetBox()

Parameters

[in]	boxa
[in]	index	to the index-th box
[in]	accessflag	L_COPY or L_CLONE

Returns: box, or NULL on error

Definition at line 702 of file boxbasic.c.

References Boxa::box, boxClone(), boxCopy(), L_CLONE, L_COPY, and Boxa::n.

Referenced by boxaaGetBox(), boxaCopy(), boxaGetBoxGeometry(), boxaGetValidBox(), boxaIsFull(), boxaRemoveBoxAndSave(), boxaWriteStderr(), and boxaWriteStream().

◆ boxaGetBoxGeometry()

l_ok boxaGetBoxGeometry	(	BOXA *	boxa,
		l_int32	index,
		l_int32 *	px,
		l_int32 *	py,
		l_int32 *	pw,
		l_int32 *	ph )

boxaGetBoxGeometry()

Parameters

[in]	boxa
[in]	index	to the index-th box
[out]	px,py,pw,ph	[optional] each can be null

Returns: 0 if OK, 1 on error

Definition at line 796 of file boxbasic.c.

References boxaGetBox(), boxDestroy(), boxGetGeometry(), L_CLONE, and Boxa::n.

Referenced by boxaFindInvalidBoxes(), and boxaGetValidCount().

◆ boxaGetCount()

l_int32 boxaGetCount ( const BOXA * boxa )

boxaGetCount()

Parameters

[in] boxa

Returns: count of all boxes; 0 if no boxes or on error

Definition at line 661 of file boxbasic.c.

References Boxa::n.

Referenced by boxaAddBox(), boxaaGetBoxCount(), boxaClear(), boxaFindInvalidBoxes(), boxaGetValidCount(), boxaInsertBox(), boxaIsFull(), boxaRemoveBoxAndSave(), boxaSaveValid(), boxaWriteStderr(), and boxaWriteStream().

◆ boxaGetValidBox()

BOX * boxaGetValidBox	(	BOXA *	boxa,
		l_int32	index,
		l_int32	accessflag )

boxaGetValidBox()

Parameters

[in]	boxa
[in]	index	to the index-th box
[in]	accessflag	L_COPY or L_CLONE

Returns: box, or NULL if box is not valid or on error

Notes:
     (1) This returns NULL for an invalid box in a boxa.
         For a box to be valid, both the width and height must be > 0.
     (2) We allow invalid boxes, with w = 0 or h = 0, as placeholders
         in boxa for which the index of the box in the boxa is important.
         This is an atypical situation; usually you want to put only
         valid boxes in a boxa.

Definition at line 739 of file boxbasic.c.

References boxaGetBox(), boxDestroy(), and boxGetGeometry().

Referenced by boxaSaveValid().

◆ boxaGetValidCount()

l_int32 boxaGetValidCount ( BOXA * boxa )

boxaGetValidCount()

Parameters

[in] boxa

Returns: count of valid boxes; 0 if no valid boxes or on error

Definition at line 676 of file boxbasic.c.

References boxaGetBoxGeometry(), and boxaGetCount().

Referenced by boxaFindInvalidBoxes().

◆ boxaInitFull()

l_ok boxaInitFull	(	BOXA *	boxa,
		BOX *	box )

boxaInitFull()

Parameters

[in]	boxa	typically empty
[in]	box	[optional] to be replicated into the entire ptr array

Returns: 0 if OK, 1 on error

Notes:
     (1) This initializes a boxa by filling up the entire box ptr array
         with copies of box.  If box == NULL, use a placeholder box
         of zero size.  Any existing boxes are destroyed.
         After this opepration, the number of boxes is equal to
         the number of allocated ptrs.
     (2) Note that we use boxaReplaceBox() instead of boxaInsertBox().
         They both have the same effect when inserting into a NULL ptr
         in the boxa ptr array:
     (3) Example usage.  This function is useful to prepare for a
         random insertion (or replacement) of boxes into a boxa.
         To randomly insert boxes into a boxa, up to some index "max":
            Boxa *boxa = boxaCreate(max);
            boxaInitFull(boxa, NULL);
         If you want placeholder boxes of non-zero size:
            Boxa *boxa = boxaCreate(max);
            Box *box = boxCreate(...);
            boxaInitFull(boxa, box);
            boxDestroy(&box);
         If we have an existing boxa with a smaller ptr array, it can
         be reused for up to max boxes:
            boxaExtendArrayToSize(boxa, max);
            boxaInitFull(boxa, NULL);
         The initialization allows the boxa to always be properly
         filled, even if all the boxes are not later replaced.
         If you want to know which boxes have been replaced,
         and you initialized with invalid zero-sized boxes,
         use boxaGetValidBox() to return NULL for the invalid boxes.

Definition at line 1085 of file boxbasic.c.

References boxaReplaceBox(), boxCopy(), boxCreate(), Boxa::n, and Boxa::nalloc.

◆ boxaInsertBox()

l_ok boxaInsertBox	(	BOXA *	boxa,
		l_int32	index,
		BOX *	box )

boxaInsertBox()

Parameters

[in]	boxa
[in]	index	location in boxa to insert new value
[in]	box	new box to be inserted; the boxa now owns it

Returns: 0 if OK, 1 on error

Notes:
     (1) This shifts box[i] --> box[i + 1] for all i >= index,
         and then inserts box as box[index].
     (2) To insert at the beginning of the array, set index = 0.
     (3) To append to the array, it's easier to use boxaAddBox().
     (4) This should not be used repeatedly to insert into large arrays,
         because the function is O(n).

Definition at line 911 of file boxbasic.c.

References Boxa::box, boxaExtendArray(), boxaGetCount(), Boxa::n, and Boxa::nalloc.

◆ boxaIsFull()

l_ok boxaIsFull	(	BOXA *	boxa,
		l_int32 *	pfull )

boxaIsFull()

Parameters

[in]	boxa
[out]	pfull	1 if boxa is full; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 830 of file boxbasic.c.

References boxaGetBox(), boxaGetCount(), boxDestroy(), and L_CLONE.

◆ boxaRead()

BOXA * boxaRead ( const char * filename )

boxaRead()

Parameters

[in] filename

Returns: boxa, or NULL on error

Definition at line 1986 of file boxbasic.c.

References boxaReadStream().

Referenced by boxaaReadFromFiles().

◆ boxaReadMem()

BOXA * boxaReadMem	(	const l_uint8 *	data,
		size_t	size )

boxaReadMem()

Parameters

[in]	data	serialization of boxa; in ascii
[in]	size	of data in bytes; can use strlen to get it

Returns: boxa, or NULL on error

Definition at line 2063 of file boxbasic.c.

References boxaReadStream().

◆ boxaReadStream()

BOXA * boxaReadStream ( FILE * fp )

boxaReadStream()

Parameters

[in] fp input file stream

Returns: boxa, or NULL on error

Notes:
     (1) It is OK for the boxa to be empty (n == 0).

Definition at line 2018 of file boxbasic.c.

References BOXA_VERSION_NUMBER, boxaAddBox(), boxaCreate(), boxaDestroy(), boxCreate(), and L_INSERT.

Referenced by boxaaReadStream(), boxaRead(), and boxaReadMem().

◆ boxaRemoveBox()

l_ok boxaRemoveBox	(	BOXA *	boxa,
		l_int32	index )

boxaRemoveBox()

Parameters

[in]	boxa
[in]	index	of box to be removed and destroyed

Returns: 0 if OK, 1 on error

Notes:
     (1) This removes box[index] and then shifts
         box[i] --> box[i - 1] for all i > index.
     (2) It should not be used repeatedly to remove boxes from
         large arrays, because the function is O(n).

Definition at line 957 of file boxbasic.c.

References boxaRemoveBoxAndSave().

◆ boxaRemoveBoxAndSave()

l_ok boxaRemoveBoxAndSave	(	BOXA *	boxa,
		l_int32	index,
		BOX **	pbox )

boxaRemoveBoxAndSave()

Parameters

[in]	boxa
[in]	index	of box to be removed
[out]	pbox	[optional] removed box

Returns: 0 if OK, 1 on error

Notes:
     (1) This removes box[index] and then shifts
         box[i] --> box[i - 1] for all i > index.
     (2) It should not be used repeatedly to remove boxes from
         large arrays, because the function is O(n).

Definition at line 981 of file boxbasic.c.

References Boxa::box, boxaGetBox(), boxaGetCount(), boxDestroy(), L_CLONE, and Boxa::n.

Referenced by boxaRemoveBox().

◆ boxaReplaceBox()

l_ok boxaReplaceBox	(	BOXA *	boxa,
		l_int32	index,
		BOX *	box )

boxaReplaceBox()

Parameters

[in]	boxa
[in]	index	to the index-th box
[in]	box	insert this box to replace existing one

Returns: 0 if OK, 1 on error

Notes:
     (1) In-place replacement of one box; the input box is now
         owned by the boxa.
     (2) The previous box at that location, if any, is destroyed.

Definition at line 875 of file boxbasic.c.

References Boxa::box, boxDestroy(), and Boxa::n.

Referenced by boxaInitFull().

◆ boxaSaveValid()

BOXA * boxaSaveValid	(	BOXA *	boxas,
		l_int32	copyflag )

boxaSaveValid()

Parameters

[in]	boxas
[in]	copyflag	L_COPY or L_CLONE

Returns: boxad if OK, NULL on error

Notes:
     (1) This makes a copy/clone of each valid box.

Definition at line 1023 of file boxbasic.c.

References boxaAddBox(), boxaCreate(), boxaGetCount(), boxaGetValidBox(), L_CLONE, L_COPY, and L_INSERT.

◆ boxaWrite()

l_ok boxaWrite	(	const char *	filename,
		BOXA *	boxa )

boxaWrite()

Parameters

[in]	filename
[in]	boxa

Returns: 0 if OK, 1 on error

Definition at line 2118 of file boxbasic.c.

References boxaWriteStream().

Referenced by boxaWriteDebug().

◆ boxaWriteDebug()

l_ok boxaWriteDebug	(	const char *	filename,
		BOXA *	boxa )

boxaWriteDebug()

Parameters

[in]	filename
[in]	boxa

Returns: 0 if OK; 1 on error

Notes:
     (1) Debug version, intended for use in the library when writing
         to files in a temp directory with names that are compiled in.
         This is used instead of boxaWrite() for all such library calls.
     (2) The global variable LeptDebugOK defaults to 0, and can be set
         or cleared by the function setLeptDebugOK().

Definition at line 2098 of file boxbasic.c.

References boxaWrite().

◆ boxaWriteMem()

l_ok boxaWriteMem	(	l_uint8 **	pdata,
		size_t *	psize,
		BOXA *	boxa )

boxaWriteMem()

Parameters

[out]	pdata	data of serialized boxa; ascii
[out]	psize	size of returned data
[in]	boxa

Returns: 0 if OK, 1 on error

Notes:
     (1) Serializes a boxa in memory and puts the result in a buffer.

Definition at line 2216 of file boxbasic.c.

References boxaWriteStream().

◆ boxaWriteStderr()

l_ok boxaWriteStderr ( BOXA * boxa )

boxaWriteStderr()

Parameters

[in] boxa

Returns: 0 if OK, 1 on error

Definition at line 2180 of file boxbasic.c.

References BOXA_VERSION_NUMBER, boxaGetBox(), boxaGetCount(), boxDestroy(), Box::h, L_CLONE, Box::w, Box::x, and Box::y.

Referenced by boxaWriteStream().

◆ boxaWriteStream()

l_ok boxaWriteStream	(	FILE *	fp,
		BOXA *	boxa )

boxaWriteStream()

Parameters

[in]	fp	file stream; use NULL for stderr
[in]	boxa

Returns: 0 if OK, 1 on error

Definition at line 2148 of file boxbasic.c.

References BOXA_VERSION_NUMBER, boxaGetBox(), boxaGetCount(), boxaWriteStderr(), boxDestroy(), Box::h, L_CLONE, Box::w, Box::x, and Box::y.

Referenced by boxaaWriteStream(), boxaWrite(), and boxaWriteMem().

◆ boxClone()

BOX * boxClone ( BOX * box )

boxClone()

Parameters

[in] box

Returns: ptr to same box, or NULL on error

Definition at line 249 of file boxbasic.c.

References Box::refcount.

Referenced by boxaAddBox(), and boxaGetBox().

◆ boxCopy()

BOX * boxCopy ( BOX * box )

boxCopy()

Parameters

[in] box

Returns: copy of box, or NULL on error

Definition at line 230 of file boxbasic.c.

References boxCreate(), Box::h, Box::w, Box::x, and Box::y.

Referenced by boxaAddBox(), boxaGetBox(), and boxaInitFull().

◆ boxCreate()

BOX * boxCreate	(	l_int32	x,
		l_int32	y,
		l_int32	w,
		l_int32	h )

boxCreate()

Parameters

[in] x,y,w,h

Returns: box, or NULL on error

Notes:
     (1) This clips the box to the +quad.  If no part of the
         box is in the +quad, this returns NULL.
     (2) We allow you to make a box with w = 0 and/or h = 0.
         This does not represent a valid region, but it is useful
         as a placeholder in a boxa for which the index of the
         box in the boxa is important.  This is an atypical
         situation; usually you want to put only valid boxes with
         nonzero width and height in a boxa.  If you have a boxa
         with invalid boxes, the accessor boxaGetValidBox()
         will return NULL on each invalid box.
     (3) If you want to create only valid boxes, use boxCreateValid(),
         which returns NULL if either w or h is 0.

Definition at line 171 of file boxbasic.c.

References boxSetGeometry(), and Box::refcount.

Referenced by boxaInitFull(), boxaReadStream(), boxCopy(), and boxCreateValid().

◆ boxCreateValid()

BOX * boxCreateValid	(	l_int32	x,
		l_int32	y,
		l_int32	w,
		l_int32	h )

boxCreateValid()

Parameters

[in] x,y,w,h

Returns: box, or NULL on error

Notes:
     (1) This returns NULL if either w = 0 or h = 0.

Definition at line 212 of file boxbasic.c.

References boxCreate().

◆ boxDestroy()

void boxDestroy ( BOX ** pbox )

boxDestroy()

Parameters

[in,out] pbox will be set to null before returning

Returns: void

Notes:
     (1) Decrements the ref count and, if 0, destroys the box.
     (2) Always nulls the input ptr.

Definition at line 273 of file boxbasic.c.

References Box::refcount.

Referenced by boxaAddBox(), boxaaWriteStream(), boxaClear(), boxaDestroy(), boxaGetBoxGeometry(), boxaGetValidBox(), boxaIsFull(), boxaRemoveBoxAndSave(), boxaReplaceBox(), boxaWriteStderr(), and boxaWriteStream().

◆ boxGetGeometry()

l_ok boxGetGeometry	(	const BOX *	box,
		l_int32 *	px,
		l_int32 *	py,
		l_int32 *	pw,
		l_int32 *	ph )

boxGetGeometry()

Parameters

[in]	box
[out]	px,py,pw,ph	[optional] each can be null

Returns: 0 if OK, 1 on error

Definition at line 301 of file boxbasic.c.

References Box::h, Box::w, Box::x, and Box::y.

Referenced by boxaaWriteStream(), boxaGetBoxGeometry(), boxaGetValidBox(), and boxGetSideLocations().

◆ boxGetSideLocations()

l_ok boxGetSideLocations	(	const BOX *	box,
		l_int32 *	pl,
		l_int32 *	pr,
		l_int32 *	pt,
		l_int32 *	pb )

boxGetSideLocations()

Parameters

[in]	box
[out]	pl,pr,pt,pb	[optional] each can be null

Returns: 0 if OK, 1 on error

Notes:
     (1) All returned values are within the box.

Definition at line 358 of file boxbasic.c.

References boxGetGeometry().

◆ boxIsValid()

l_ok boxIsValid	(	BOX *	box,
		l_int32 *	pvalid )

boxIsValid()

Parameters

[in]	box
[out]	pvalid	1 if valid; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 417 of file boxbasic.c.

References Box::h, and Box::w.

◆ boxPrintStreamInfo()

l_ok boxPrintStreamInfo	(	FILE *	fp,
		BOX *	box )

boxPrintStreamInfo()

Parameters

[in]	fp	file stream; use NULL for stderr
[in]	box

Returns: 0 if OK, 1 on error

Notes:
     (1) This outputs debug info.  Use serialization functions to
         write to file if you want to read the data back.

Definition at line 2274 of file boxbasic.c.

References Box::h, Box::w, Box::x, and Box::y.

◆ boxSetGeometry()

l_ok boxSetGeometry	(	BOX *	box,
		l_int32	x,
		l_int32	y,
		l_int32	w,
		l_int32	h )

boxSetGeometry()

Parameters

[in]	box
[in]	x,y,w,h	[optional] use -1 to leave unchanged

Returns: 0 if OK, 1 on error

Definition at line 329 of file boxbasic.c.

References Box::h, Box::w, Box::x, and Box::y.

Referenced by boxCreate(), and boxSetSideLocations().

◆ boxSetSideLocations()

l_ok boxSetSideLocations	(	BOX *	box,
		l_int32	l,
		l_int32	r,
		l_int32	t,
		l_int32	b )

boxSetSideLocations()

Parameters

[in]	box
[in]	l,r,t,b	[optional] use -1 to leave unchanged

Returns: 0 if OK, 1 on error

Definition at line 390 of file boxbasic.c.

References boxSetGeometry(), Box::h, Box::w, Box::x, and Box::y.

Variable Documentation

◆ InitialPtrArraySize

const size_t InitialPtrArraySize = 20

static

n'importe quoi

Definition at line 143 of file boxbasic.c.

Referenced by boxaaCreate(), and boxaCreate().

◆ MaxBoxaaPtrArraySize

const size_t MaxBoxaaPtrArraySize = 1000000

static

Definition at line 142 of file boxbasic.c.

◆ MaxBoxaPtrArraySize

const size_t MaxBoxaPtrArraySize = 10000000

static

Definition at line 141 of file boxbasic.c.

Functions

Variables

Detailed Description

Function Documentation

◆ boxaaAddBox()

◆ boxaaAddBoxa()

◆ boxaaCopy()

◆ boxaaCreate()

◆ boxaAddBox()

◆ boxaaDestroy()

◆ boxaaExtendArray()

◆ boxaaExtendArrayToSize()

◆ boxaaExtendWithInit()

◆ boxaaGetBox()

◆ boxaaGetBoxa()

◆ boxaaGetBoxCount()

◆ boxaaGetCount()

◆ boxaaInitFull()

◆ boxaaInsertBoxa()

◆ boxaaRead()

◆ boxaaReadFromFiles()

◆ boxaaReadMem()

◆ boxaaReadStream()

◆ boxaaRemoveBoxa()

◆ boxaaReplaceBoxa()

◆ boxaaWrite()

◆ boxaaWriteMem()

◆ boxaaWriteStream()

◆ boxaClear()

◆ boxaCopy()

◆ boxaCreate()

◆ boxaDestroy()

◆ boxaExtendArray()

◆ boxaExtendArrayToSize()

◆ boxaFindInvalidBoxes()

◆ boxaGetBox()

◆ boxaGetBoxGeometry()

◆ boxaGetCount()

◆ boxaGetValidBox()

◆ boxaGetValidCount()

◆ boxaInitFull()

◆ boxaInsertBox()

◆ boxaIsFull()

◆ boxaRead()

◆ boxaReadMem()

◆ boxaReadStream()

◆ boxaRemoveBox()

◆ boxaRemoveBoxAndSave()

◆ boxaReplaceBox()

◆ boxaSaveValid()

◆ boxaWrite()

◆ boxaWriteDebug()

◆ boxaWriteMem()

◆ boxaWriteStderr()

◆ boxaWriteStream()

◆ boxClone()

◆ boxCopy()

◆ boxCreate()

◆ boxCreateValid()

◆ boxDestroy()

◆ boxGetGeometry()

◆ boxGetSideLocations()

◆ boxIsValid()

◆ boxPrintStreamInfo()

◆ boxSetGeometry()

◆ boxSetSideLocations()

Variable Documentation

◆ InitialPtrArraySize

◆ MaxBoxaaPtrArraySize

◆ MaxBoxaPtrArraySize