#include <string.h>
#include <dirent.h>
#include <sys/stat.h>
#include <limits.h>
#include <stdlib.h>
#include "allheaders.h"

Functions
static l_int32	sarrayExtendArray (SARRAY *sa)

SARRAY *	sarrayCreate (l_int32 n)

SARRAY *	sarrayCreateInitialized (l_int32 n, const char *initstr)

SARRAY *	sarrayCreateWordsFromString (const char *string)

SARRAY *	sarrayCreateLinesFromString (const char *string, l_int32 blankflag)

void	sarrayDestroy (SARRAY **psa)

SARRAY *	sarrayCopy (SARRAY *sa)

SARRAY *	sarrayClone (SARRAY *sa)

l_ok	sarrayAddString (SARRAY sa, const char string, l_int32 copyflag)

char *	sarrayRemoveString (SARRAY *sa, l_int32 index)

l_ok	sarrayReplaceString (SARRAY sa, l_int32 index, char newstr, l_int32 copyflag)

l_ok	sarrayClear (SARRAY *sa)

l_int32	sarrayGetCount (SARRAY *sa)

char **	sarrayGetArray (SARRAY sa, l_int32 pnalloc, l_int32 *pn)

char *	sarrayGetString (SARRAY *sa, l_int32 index, l_int32 copyflag)

l_int32	sarrayGetRefcount (SARRAY *sa)

l_ok	sarrayChangeRefcount (SARRAY *sa, l_int32 delta)

char *	sarrayToString (SARRAY *sa, l_int32 addnlflag)

char *	sarrayToStringRange (SARRAY *sa, l_int32 first, l_int32 nstrings, l_int32 addnlflag)

l_ok	sarrayJoin (SARRAY sa1, SARRAY sa2)

l_ok	sarrayAppendRange (SARRAY sa1, SARRAY sa2, l_int32 start, l_int32 end)

l_ok	sarrayPadToSameSize (SARRAY sa1, SARRAY sa2, const char *padstring)

SARRAY *	sarrayConvertWordsToLines (SARRAY *sa, l_int32 linesize)

l_int32	sarraySplitString (SARRAY sa, const char str, const char *separators)

SARRAY *	sarraySelectBySubstring (SARRAY sain, const char substr)

SARRAY *	sarraySelectByRange (SARRAY *sain, l_int32 first, l_int32 last)

l_int32	sarrayParseRange (SARRAY sa, l_int32 start, l_int32 pactualstart, l_int32 pend, l_int32 pnewstart, const char *substr, l_int32 loc)

SARRAY *	sarrayRead (const char *filename)

SARRAY *	sarrayReadStream (FILE *fp)

SARRAY *	sarrayReadMem (const l_uint8 *data, size_t size)

l_ok	sarrayWrite (const char filename, SARRAY sa)

l_ok	sarrayWriteStream (FILE fp, SARRAY sa)

l_ok	sarrayWriteMem (l_uint8 *pdata, size_t psize, SARRAY *sa)

l_ok	sarrayAppend (const char filename, SARRAY sa)

SARRAY *	getNumberedPathnamesInDirectory (const char dirname, const char substr, l_int32 numpre, l_int32 numpost, l_int32 maxnum)

SARRAY *	getSortedPathnamesInDirectory (const char dirname, const char substr, l_int32 first, l_int32 nfiles)

SARRAY *	convertSortedToNumberedPathnames (SARRAY *sa, l_int32 numpre, l_int32 numpost, l_int32 maxnum)

SARRAY *	getFilenamesInDirectory (const char *dirname)

Variables
static const l_int32	INITIAL_PTR_ARRAYSIZE = 50

static const l_int32	L_BUF_SIZE = 512

Detailed Description

 Create/Destroy/Copy
     SARRAY    *sarrayCreate()
     SARRAY    *sarrayCreateInitialized()
     SARRAY    *sarrayCreateWordsFromString()
     SARRAY    *sarrayCreateLinesFromString()
     void      *sarrayDestroy()
     SARRAY    *sarrayCopy()
     SARRAY    *sarrayClone()

 Add/Remove string
     l_int32    sarrayAddString()
     static l_int32  sarrayExtendArray()
     char      *sarrayRemoveString()
     l_int32    sarrayReplaceString()
     l_int32    sarrayClear()

 Accessors
     l_int32    sarrayGetCount()
     char     **sarrayGetArray()
     char      *sarrayGetString()
     l_int32    sarrayGetRefcount()
     l_int32    sarrayChangeRefcount()

 Conversion back to string
     char      *sarrayToString()
     char      *sarrayToStringRange()

 Join 2 sarrays
     l_int32    sarrayJoin()
     l_int32    sarrayAppendRange()

 Pad an sarray to be the same size as another sarray
     l_int32    sarrayPadToSameSize()

 Convert word sarray to (formatted) line sarray
     SARRAY    *sarrayConvertWordsToLines()

 Split string on separator list
     SARRAY    *sarraySplitString()

 Filter sarray
     SARRAY    *sarraySelectBySubstring()
     SARRAY    *sarraySelectByRange()
     l_int32    sarrayParseRange()

 Serialize for I/O
     SARRAY    *sarrayRead()
     SARRAY    *sarrayReadStream()
     SARRAY    *sarrayReadMem()
     l_int32    sarrayWrite()
     l_int32    sarrayWriteStream()
     l_int32    sarrayWriteMem()
     l_int32    sarrayAppend()

 Directory filenames
     SARRAY    *getNumberedPathnamesInDirectory()
     SARRAY    *getSortedPathnamesInDirectory()
     SARRAY    *convertSortedToNumberedPathnames()
     SARRAY    *getFilenamesInDirectory()

 These functions are important for efficient manipulation
 of string data, and they have found widespread use in
 leptonica.  For example:
    (1) to generate text files: e.g., PostScript and PDF
        wrappers around sets of images
    (2) to parse text files: e.g., extracting prototypes
        from the source to generate allheaders.h
    (3) to generate code for compilation: e.g., the fast
        dwa code for arbitrary structuring elements.

 Comments on usage:

     The user is responsible for correctly disposing of strings
     that have been extracted from sarrays.  In the following,
     "str_not_owned" means the returned handle does not own the string,
     and "str_owned" means the returned handle owns the string.
       - To extract a string from an Sarray in order to inspect it
         or to make a copy of it later, get a handle to it:
             copyflag = L_NOCOPY.
         In this case, you must neither free the string nor put it
         directly in another array:
            str-not-owned = sarrayGetString(sa, index, L_NOCOPY);
       - To extract a copy of a string from an Sarray, use:
            str-owned = sarrayGetString(sa, index, L_COPY);
       ~ To insert a string that is in one array into another
         array (always leaving the first array intact), there are
         two options:
            (1) use copyflag = L_COPY to make an immediate copy,
                which you then add to the second array by insertion:
                  str-owned = sarrayGetString(sa, index, L_COPY);
                  sarrayAddString(sa, str-owned, L_INSERT);
            (2) use copyflag = L_NOCOPY to get another handle to
                the string; you then add a copy of it to the
                second string array:
                  str-not-owned = sarrayGetString(sa, index, L_NOCOPY);
                  sarrayAddString(sa, str-not-owned, L_COPY).
         sarrayAddString() transfers ownership to the Sarray, so never
         use L_INSERT if the string is owned by another array.

         In all cases, when you use copyflag = L_COPY to extract
         a string from an array, you must either free it
         or insert it in an array that will be freed later.

Definition in file sarray1.c.

Function Documentation

◆ convertSortedToNumberedPathnames()

SARRAY* convertSortedToNumberedPathnames	(	SARRAY *	sa,
		l_int32	numpre,
		l_int32	numpost,
		l_int32	maxnum
	)

convertSortedToNumberedPathnames()

Parameters

[in]	sa	sorted pathnames including zero-padded integers
[in]	numpre	number of characters in name before number
[in]	numpost	number of characters in name after the number, up to a dot before an extension
[in]	maxnum	only consider page numbers up to this value

Returns: sarray of numbered pathnames, or NULL on error

Notes:
     (1) Typically, numpre = numpost = 0; e.g., when the filename
         just has a number followed by an optional extension.

Definition at line 1777 of file sarray1.c.

References extractNumberFromFilename(), L_RegParams::index, L_COPY, L_NOCOPY, sarrayCreate(), sarrayCreateInitialized(), sarrayGetCount(), sarrayGetString(), and sarrayReplaceString().

Referenced by getNumberedPathnamesInDirectory().

◆ getFilenamesInDirectory()

SARRAY* getFilenamesInDirectory ( const char * dirname )

getFilenamesInDirectory()

Parameters

[in] dirname directory name

Returns: sarray of file names, or NULL on error

Notes:
     (1) The versions compiled under unix and cygwin use the POSIX C
         library commands for handling directories.  For windows,
         there is a separate implementation.
     (2) It returns an array of filename tails; i.e., only the part of
         the path after the last slash.
     (3) Use of the d_type field of dirent is not portable:
         "According to POSIX, the dirent structure contains a field
         char d_name[] of unspecified size, with at most NAME_MAX
         characters preceding the terminating null character.  Use
         of other fields will harm the portability of your programs."
     (4) As a consequence of (3), we note several things:
          ~ MINGW doesn't have a d_type member.
          ~ Older versions of gcc (e.g., 2.95.3) return DT_UNKNOWN
            for d_type from all files.
         On these systems, this function will return directories
         (except for '.' and '..', which are eliminated using
         the d_name field).

Definition at line 1859 of file sarray1.c.

References genPathname(), L_COPY, sarrayAddString(), and sarrayCreate().

Referenced by getSortedPathnamesInDirectory(), and lept_rmdir().

◆ getNumberedPathnamesInDirectory()

SARRAY* getNumberedPathnamesInDirectory	(	const char *	dirname,
		const char *	substr,
		l_int32	numpre,
		l_int32	numpost,
		l_int32	maxnum
	)

getNumberedPathnamesInDirectory()

Parameters

[in]	dirname	directory name
[in]	substr	[optional] substring filter on filenames; can be NULL
[in]	numpre	number of characters in name before number
[in]	numpost	number of characters in name after the number, up to a dot before an extension
[in]	maxnum	only consider page numbers up to this value

Returns: sarray of numbered pathnames, or NULL on error

Notes:
     (1) Returns the full pathnames of the numbered filenames in
         the directory.  The number in the filename is the index
         into the sarray.  For indices for which there are no filenames,
         an empty string ("") is placed into the sarray.
         This makes reading numbered files very simple.  For example,
         the image whose filename includes number N can be retrieved using
              pixReadIndexed(sa, N);
     (2) If substr is not NULL, only filenames that contain
         the substring can be included.  If substr is NULL,
         all matching filenames are used.
     (3) If no numbered files are found, it returns an empty sarray,
         with no initialized strings.
     (4) It is assumed that the page number is contained within
         the basename (the filename without directory or extension).
         numpre is the number of characters in the basename
         preceding the actual page number; numpost is the number
         following the page number, up to either the end of the
         basename or a ".", whichever comes first.
     (5) This is useful when all filenames contain numbers that are
         not necessarily consecutive.  0-padding is not required.
     (6) To use a O(n) matching algorithm, the largest page number
         is found and two internal arrays of this size are created.
         This maximum is constrained not to exceed maxsum,
         to make sure that an unrealistically large number is not
         accidentally used to determine the array sizes.

Definition at line 1669 of file sarray1.c.

References convertSortedToNumberedPathnames(), getSortedPathnamesInDirectory(), sarrayCreate(), sarrayDestroy(), and sarrayGetCount().

Referenced by convertNumberedMasksToBoxaa(), and convertSegmentedFilesToPdf().

◆ getSortedPathnamesInDirectory()

SARRAY* getSortedPathnamesInDirectory	(	const char *	dirname,
		const char *	substr,
		l_int32	first,
		l_int32	nfiles
	)

getSortedPathnamesInDirectory()

Parameters

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

Returns: sarray of sorted pathnames, or NULL on error

Notes:
     (1) Use substr to filter filenames in the directory.  If
         substr == NULL, this takes all files.
     (2) The files in the directory, after optional filtering by
         the substring, are lexically sorted in increasing order.
         Use first and nfiles to select a contiguous set of files.
     (3) The full pathnames are returned for the requested sequence.
         If no files are found after filtering, returns an empty sarray.

Definition at line 1717 of file sarray1.c.

References getFilenamesInDirectory(), L_INSERT, L_NOCOPY, L_SORT_INCREASING, pathJoin(), sarrayAddString(), sarrayCreate(), sarrayDestroy(), sarrayGetCount(), sarrayGetString(), sarraySelectBySubstring(), and sarraySort().

Referenced by boxaaReadFromFiles(), concatenatePdf(), concatenatePdfToData(), convertFilesToPdf(), convertToNUpPixa(), convertUnscaledFilesToPdf(), getNumberedPathnamesInDirectory(), jbWordsInTextlines(), lept_rm_match(), pixaaReadFromFiles(), pixaReadFiles(), and writeMultipageTiff().

◆ sarrayAddString()

l_ok sarrayAddString	(	SARRAY *	sa,
		const char *	string,
		l_int32	copyflag
	)

sarrayAddString()

Parameters

[in]	sa	string array
[in]	string	string to be added
[in]	copyflag	L_INSERT, L_NOCOPY or L_COPY

Returns: 0 if OK, 1 on error

Notes:
     (1) See usage comments at the top of this file.  L_INSERT is
         equivalent to L_NOCOPY.

Definition at line 446 of file sarray1.c.

References Sarray::array, L_COPY, L_INSERT, L_NOCOPY, Sarray::n, Sarray::nalloc, sarrayExtendArray(), sarrayGetCount(), and stringNew().

Referenced by bmfGetLineStrings(), ccbaWriteSVGString(), convertToNUpPixa(), generateFlatePS(), generateG4PS(), generateJpegPS(), generateUncompressedPS(), getFilenamesInDirectory(), getSortedPathnamesInDirectory(), l_genDataString(), numaConvertToSarray(), pixReadBarcodes(), recogAddMissingClassStrings(), recogExtractNumbers(), recogGetClassIndex(), recogIsPaddingNeeded(), sarrayAppendRange(), sarrayConvertWordsToLines(), sarrayCopy(), sarrayCreateInitialized(), sarrayCreateLinesFromString(), sarrayGenerateIntegers(), sarrayIntersectionByHash(), sarrayJoin(), sarrayMakeWplsCode(), sarrayPadToSameSize(), sarrayReadStream(), sarrayRemoveDupsByHash(), sarraySelectByRange(), sarraySelectBySubstring(), sarraySortByIndex(), selaGetSelnames(), splitStringToParagraphs(), strcodeGenerate(), sudokuReadFile(), and transferRchToRcha().

◆ sarrayAppend()

l_ok sarrayAppend	(	const char *	filename,
		SARRAY *	sa
	)

sarrayAppend()

Parameters

[in]	filename
[in]	sa

Returns: 0 if OK; 1 on error

Definition at line 1601 of file sarray1.c.

References fopenWriteStream(), L_RegParams::fp, and sarrayWriteStream().

◆ sarrayAppendRange()

l_ok sarrayAppendRange	(	SARRAY *	sa1,
		SARRAY *	sa2,
		l_int32	start,
		l_int32	end
	)

sarrayAppendRange()

Parameters

[in]	sa1	to be added to
[in]	sa2	append specified range of strings in sa2 to sa1
[in]	start	index of first string of sa2 to append
[in]	end	index of last string of sa2 to append; -1 to end of array

Returns: 0 if OK, 1 on error

Notes:
     (1) Copies of the strings in sarray2 are added to sarray1.
     (2) The [start ... end] range is truncated if necessary.
     (3) Use end == -1 to append to the end of sa2.

Definition at line 920 of file sarray1.c.

References L_COPY, L_NOCOPY, sarrayAddString(), sarrayGetCount(), and sarrayGetString().

◆ sarrayChangeRefcount()

l_ok sarrayChangeRefcount	(	SARRAY *	sa,
		l_int32	delta
	)

sarrayChangeRefCount()

Parameters

[in]	sa	string array
[in]	delta	change to be applied

Returns: 0 if OK, 1 on error

Definition at line 726 of file sarray1.c.

References Sarray::refcount.

Referenced by sarrayClone(), and sarrayDestroy().

◆ sarrayClear()

l_ok sarrayClear ( SARRAY * sa )

sarrayClear()

Parameters

[in] sa string array

Returns: 0 if OK; 1 on error

Definition at line 594 of file sarray1.c.

References Sarray::array, and Sarray::n.

◆ sarrayClone()

SARRAY* sarrayClone ( SARRAY * sa )

sarrayClone()

Parameters

[in] sa string array

Returns: ptr to same sarray, or NULL on error

Definition at line 420 of file sarray1.c.

References sarrayChangeRefcount().

Referenced by rchaExtract().

◆ sarrayConvertWordsToLines()

SARRAY* sarrayConvertWordsToLines	(	SARRAY *	sa,
		l_int32	linesize
	)

sarrayConvertWordsToLines()

Parameters

[in]	sa	sa of individual words
[in]	linesize	max num of chars in each line

Returns: saout sa of formatted lines, or NULL on error

This is useful for re-typesetting text to a specific maximum line length. The individual words in the input sarray are concatenated into textlines. An input word string of zero length is taken to be a paragraph separator. Each time such a string is found, the current line is ended and a new line is also produced that contains just the string of zero length "". When the output sarray of lines is eventually converted to a string with newlines typically appended to each line string, the empty strings are just converted to newlines, producing the visible paragraph separation.

What happens when a word is larger than linesize? We write it out as a single line anyway! Words preceding or following this long word are placed on lines preceding or following the line with the long word. Why this choice? Long "words" found in text documents are typically URLs, and it's often desirable not to put newlines in the middle of a URL. The text display program e.g., text editor will typically wrap the long "word" to fit in the window.

Definition at line 1029 of file sarray1.c.

References L_COPY, L_INSERT, L_NOCOPY, sarrayAddString(), sarrayCreate(), sarrayDestroy(), sarrayGetCount(), sarrayGetString(), and sarrayToString().

◆ sarrayCopy()

SARRAY* sarrayCopy ( SARRAY * sa )

sarrayCopy()

Parameters

[in] sa string array

Returns: copy of sarray, or NULL on error

Definition at line 393 of file sarray1.c.

References Sarray::array, L_COPY, Sarray::n, Sarray::nalloc, sarrayAddString(), and sarrayCreate().

Referenced by sarraySelectBySubstring(), sarraySort(), and sarrayUnionByAset().

◆ sarrayCreate()

SARRAY* sarrayCreate ( l_int32 n )

sarrayCreate()

Parameters

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

Returns: sarray, or NULL on error

Definition at line 163 of file sarray1.c.

Referenced by bmfGetLineStrings(), ccbaWriteSVGString(), convertSortedToNumberedPathnames(), convertToNUpPixa(), generateFlatePS(), generateG4PS(), generateJpegPS(), generateUncompressedPS(), getFilenamesInDirectory(), getNumberedPathnamesInDirectory(), getSortedPathnamesInDirectory(), l_genDataString(), lept_mkdir(), numaConvertToSarray(), numaCreateFromString(), pathJoin(), pixColorMorphSequence(), pixGrayMorphSequence(), pixMorphCompSequence(), pixMorphCompSequenceDwa(), pixMorphSequence(), pixMorphSequenceDwa(), pixReadBarcodes(), rchaCreate(), recogAddMissingClassStrings(), recogExtractNumbers(), sarrayConvertWordsToLines(), sarrayCopy(), sarrayCreateInitialized(), sarrayCreateLinesFromString(), sarrayCreateWordsFromString(), sarrayGenerateIntegers(), sarrayIntersectionByAset(), sarrayIntersectionByHash(), sarrayLookupCSKV(), sarrayMakeInnerLoopDWACode(), sarrayMakeWplsCode(), sarrayReadStream(), sarrayRemoveDupsByHash(), sarraySelectByRange(), sarraySelectBySubstring(), sarraySortByIndex(), selaGetSelnames(), splitStringToParagraphs(), strcodeCreate(), and sudokuReadFile().

◆ sarrayCreateInitialized()

SARRAY* sarrayCreateInitialized	(	l_int32	n,
		const char *	initstr
	)

sarrayCreateInitialized()

Parameters

[in]	n	size of string ptr array to be alloc'd
[in]	initstr	string to be initialized on the full array

Returns: sarray, or NULL on error

Definition at line 193 of file sarray1.c.

References L_COPY, sarrayAddString(), and sarrayCreate().

Referenced by convertSortedToNumberedPathnames().

◆ sarrayCreateLinesFromString()

SARRAY* sarrayCreateLinesFromString	(	const char *	string,
		l_int32	blankflag
	)

sarrayCreateLinesFromString()

Parameters

[in]	string
[in]	blankflag	0 to exclude blank lines; 1 to include

Returns: sarray, or NULL on error

Notes:
     (1) This finds the number of line substrings, each of which
         ends with a newline, and puts a copy of each substring
         in a new sarray.
     (2) The newline characters are removed from each substring.

Definition at line 276 of file sarray1.c.

References L_INSERT, sarrayAddString(), sarrayCreate(), sarrayDestroy(), and stringNew().

Referenced by kernelCreateFromFile(), parseTrailerPdf(), selaCreateFromFile(), splitStringToParagraphs(), strcodeCreateFromFile(), and sudokuReadFile().

◆ sarrayCreateWordsFromString()

SARRAY* sarrayCreateWordsFromString ( const char * string )

sarrayCreateWordsFromString()

Parameters

[in] string

Returns: sarray, or NULL on error

Notes:
     (1) This finds the number of word substrings, creates an sarray
         of this size, and puts copies of each substring into the sarray.

Definition at line 226 of file sarray1.c.

References sarrayCreate().

Referenced by bmfGetLineStrings(), l_getIndexFromFile(), and sudokuReadFile().

◆ sarrayDestroy()

void sarrayDestroy ( SARRAY ** psa )

sarrayDestroy()

Parameters

[in,out] psa to be nulled

Returns: void

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

Definition at line 355 of file sarray1.c.

References Sarray::array, Sarray::n, sarrayChangeRefcount(), and sarrayGetRefcount().

Referenced by bmfGetLineStrings(), boxaaReadFromFiles(), ccbaWriteSVGString(), concatenatePdf(), concatenatePdfToData(), convertFilesToPdf(), convertNumberedMasksToBoxaa(), convertSegmentedFilesToPdf(), convertToNUpPixa(), convertUnscaledFilesToPdf(), generateUncompressedPS(), getNumberedPathnamesInDirectory(), getSortedPathnamesInDirectory(), gplotDestroy(), kernelCreateFromFile(), l_genDataString(), l_getIndexFromFile(), lept_rm_match(), lept_rmdir(), parseTrailerPdf(), pixaaReadFromFiles(), pixaCompareInPdf(), pixaReadFiles(), pixReadBarcodes(), rchaDestroy(), recogDestroy(), recogExtractNumbers(), recogPadDigitTrainingSet(), sarrayConvertWordsToLines(), sarrayCreateLinesFromString(), sarrayReadStream(), sarrayUnionByAset(), selaCreateFromFile(), splitStringToParagraphs(), strcodeCreateFromFile(), strcodeDestroy(), sudokuReadFile(), and writeMultipageTiff().

◆ sarrayExtendArray()

static l_int32 sarrayExtendArray ( SARRAY * sa )

static

sarrayExtendArray()

Parameters

[in] sa string array

Returns: 0 if OK, 1 on error

Definition at line 481 of file sarray1.c.

References Sarray::array, Sarray::nalloc, and reallocNew().

Referenced by sarrayAddString().

◆ sarrayGetArray()

char** sarrayGetArray	(	SARRAY *	sa,
		l_int32 *	pnalloc,
		l_int32 *	pn
	)

sarrayGetArray()

Parameters

[in]	sa	string array
[out]	pnalloc	[optional] number allocated string ptrs
[out]	pn	[optional] number allocated strings

Returns: ptr to string array, or NULL on error

Notes:
     (1) Caution: the returned array is not a copy, so caller
         must not destroy it!

Definition at line 646 of file sarray1.c.

References Sarray::array, Sarray::n, and Sarray::nalloc.

Referenced by sarrayRemoveString().

◆ sarrayGetCount()

l_int32 sarrayGetCount ( SARRAY * sa )

sarrayGetCount()

Parameters

[in] sa string array

Returns: count, or 0 if no strings or on error

Definition at line 621 of file sarray1.c.

References Sarray::n.

Referenced by bmfGetLineStrings(), bmfGetWordWidths(), boxaaReadFromFiles(), convertNumberedMasksToBoxaa(), convertSegmentedFilesToPdf(), convertSortedToNumberedPathnames(), convertToNUpPixa(), getNumberedPathnamesInDirectory(), getSortedPathnamesInDirectory(), gplotGenDataFiles(), jbWordsInTextlines(), kernelCreateFromFile(), l_dnaHashCreateFromSarray(), lept_rm_match(), lept_rmdir(), morphSequenceVerify(), pixaAddTextlines(), pixaaReadFromFiles(), pixaConvertToNUpPixa(), pixaReadFilesSA(), pixaSetText(), pixReadBarcodes(), pixReadIndexed(), recogAddDigitPadTemplates(), recogExtractNumbers(), saConcatenatePdfToData(), saConvertFilesToPdfData(), saConvertUnscaledFilesToPdfData(), sarrayAddString(), sarrayAppendRange(), sarrayConvertWordsToLines(), sarrayIntersectionByAset(), sarrayIntersectionByHash(), sarrayJoin(), sarrayLookupCSKV(), sarrayPadToSameSize(), sarrayParseRange(), sarrayRemoveDupsByHash(), sarrayReplaceString(), sarraySelectByRange(), sarraySelectBySubstring(), sarraySort(), sarraySortByIndex(), sarrayToStringRange(), sarrayWriteStream(), selaCreateFromFile(), selCreateFromSArray(), showExtractNumbers(), splitStringToParagraphs(), strcodeCreateFromFile(), sudokuReadFile(), writeCustomTiffTags(), and writeMultipageTiffSA().

◆ sarrayGetRefcount()

l_int32 sarrayGetRefcount ( SARRAY * sa )

sarrayGetRefCount()

Parameters

[in] sa string array

Returns: refcount, or UNDEF on error

Definition at line 708 of file sarray1.c.

References Sarray::refcount.

Referenced by sarrayDestroy().

◆ sarrayGetString()

char* sarrayGetString	(	SARRAY *	sa,
		l_int32	index,
		l_int32	copyflag
	)

sarrayGetString()

Parameters

[in]	sa	string array
[in]	index	to the index-th string
[in]	copyflag	L_NOCOPY or L_COPY

Returns: string, or NULL on error

Notes:
     (1) See usage comments at the top of this file.
     (2) To get a pointer to the string itself, use L_NOCOPY.
         To get a copy of the string, use L_COPY.

Definition at line 681 of file sarray1.c.

References Sarray::array, L_RegParams::index, L_COPY, L_NOCOPY, Sarray::n, and stringNew().

Referenced by bmfGetWordWidths(), boxaaReadFromFiles(), convertNumberedMasksToBoxaa(), convertSegmentedFilesToPdf(), convertSortedToNumberedPathnames(), convertToNUpPixa(), getSortedPathnamesInDirectory(), gplotGenDataFiles(), kernelCreateFromFile(), l_dnaHashCreateFromSarray(), l_getIndexFromFile(), lept_rm_match(), lept_rmdir(), morphSequenceVerify(), parseTrailerPdf(), pixaAddTextlines(), pixaaReadFromFiles(), pixaConvertToNUpPixa(), pixaReadFilesSA(), pixaSetText(), pixReadIndexed(), ptraConcatenatePdfToData(), recogAddAllSamples(), recogAddCharstrLabels(), recogAddDigitPadTemplates(), recogAddMissingClassStrings(), recogExtractNumbers(), recogGetClassString(), recogIsPaddingNeeded(), saConcatenatePdfToData(), saConvertFilesToPdfData(), saConvertUnscaledFilesToPdfData(), sarrayAppendRange(), sarrayConvertWordsToLines(), sarrayFindStringByHash(), sarrayIntersectionByHash(), sarrayJoin(), sarrayLookupCSKV(), sarrayParseRange(), sarrayRemoveDupsByHash(), sarraySelectByRange(), sarraySelectBySubstring(), sarraySortByIndex(), sarrayToStringRange(), selaCreateFromFile(), selCreateFromSArray(), showExtractNumbers(), splitStringToParagraphs(), strcodeCreateFromFile(), sudokuReadFile(), writeCustomTiffTags(), and writeMultipageTiffSA().

◆ sarrayJoin()

l_ok sarrayJoin	(	SARRAY *	sa1,
		SARRAY *	sa2
	)

sarrayJoin()

Parameters

[in]	sa1	to be added to
[in]	sa2	append to sa1

Returns: 0 if OK, 1 on error

Notes:
     (1) Copies of the strings in sarray2 are added to sarray1.

Definition at line 880 of file sarray1.c.

References L_COPY, L_NOCOPY, sarrayAddString(), sarrayGetCount(), and sarrayGetString().

Referenced by sarrayUnionByAset().

◆ sarrayPadToSameSize()

l_ok sarrayPadToSameSize	(	SARRAY *	sa1,
		SARRAY *	sa2,
		const char *	padstring
	)

sarrayPadToSameSize()

Parameters

[in]	sa1,sa2
[in]	padstring

Returns: 0 if OK, 1 on error

Notes:
     (1) If two sarrays have different size, this adds enough
         instances of padstring to the smaller so that they are
         the same size.  It is useful when two or more sarrays
         are being sequenced in parallel, and it is necessary to
         find a valid string at each index.

Definition at line 972 of file sarray1.c.

References L_COPY, sarrayAddString(), and sarrayGetCount().

◆ sarrayParseRange()

l_int32 sarrayParseRange	(	SARRAY *	sa,
		l_int32	start,
		l_int32 *	pactualstart,
		l_int32 *	pend,
		l_int32 *	pnewstart,
		const char *	substr,
		l_int32	loc
	)

sarrayParseRange()

Parameters

[in]	sa	input sarray
[in]	start	index to start range search
[out]	pactualstart	index of actual start; may be > 'start'
[out]	pend	index of end
[out]	pnewstart	index of start of next range
[in]	substr	substring for matching at beginning of string
[in]	loc	byte offset within the string for the pattern; use -1 if the location does not matter;

Returns: 0 if valid range found; 1 otherwise

Notes:
     (1) This finds the range of the next set of strings in SA,
         beginning the search at 'start', that does NOT have
         the substring 'substr' either at the indicated location
         in the string or anywhere in the string.  The input
         variable 'loc' is the specified offset within the string;
         use -1 to indicate 'anywhere in the string'.
     (2) Always check the return value to verify that a valid range
         was found.
     (3) If a valid range is not found, the values of actstart,
         end and newstart are all set to the size of sa.
     (4) If this is the last valid range, newstart returns the value n.
         In use, this should be tested before calling the function.
     (5) Usage example.  To find all the valid ranges in a file
         where the invalid lines begin with two dashes, copy each
         line in the file to a string in an sarray, and do:
            start = 0;
            while (!sarrayParseRange(sa, start, &actstart, &end, &start,
                   "--", 0))
                fprintf(stderr, "start = %d, end = %d\n", actstart, end);

Definition at line 1260 of file sarray1.c.

References arrayFindSequence(), L_NOCOPY, sarrayGetCount(), and sarrayGetString().

◆ sarrayRead()

SARRAY* sarrayRead ( const char * filename )

sarrayRead()

Parameters

[in] filename

Returns: sarray, or NULL on error

Definition at line 1345 of file sarray1.c.

References fopenReadStream(), L_RegParams::fp, and sarrayReadStream().

◆ sarrayReadMem()

SARRAY* sarrayReadMem	(	const l_uint8 *	data,
		size_t	size
	)

sarrayReadMem()

Parameters

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

Returns: sarray, or NULL on error

Definition at line 1449 of file sarray1.c.

References fopenReadFromMemory(), L_RegParams::fp, and sarrayReadStream().

◆ sarrayReadStream()

SARRAY* sarrayReadStream ( FILE * fp )

sarrayReadStream()

Parameters

[in] fp file stream

Returns: sarray, or NULL on error

Notes:
     (1) We store the size of each string along with the string.
         The limit on the number of strings is 2^24.
         The limit on the size of any string is 2^30 bytes.
     (2) This allows a string to have embedded newlines.  By reading
         the entire string, as determined by its size, we are
         not affected by any number of embedded newlines.

Definition at line 1382 of file sarray1.c.

References L_RegParams::fp, L_RegParams::index, L_BUF_SIZE, L_COPY, SARRAY_VERSION_NUMBER, sarrayAddString(), sarrayCreate(), sarrayDestroy(), and L_RegParams::success.

Referenced by sarrayRead(), and sarrayReadMem().

◆ sarrayRemoveString()

char* sarrayRemoveString	(	SARRAY *	sa,
		l_int32	index
	)

sarrayRemoveString()

Parameters

[in]	sa	string array
[in]	index	of string within sarray

Returns: removed string, or NULL on error

Definition at line 506 of file sarray1.c.

References L_RegParams::index, Sarray::n, and sarrayGetArray().

◆ sarrayReplaceString()

l_ok sarrayReplaceString	(	SARRAY *	sa,
		l_int32	index,
		char *	newstr,
		l_int32	copyflag
	)

sarrayReplaceString()

Parameters

[in]	sa	string array
[in]	index	of string within sarray to be replaced
[in]	newstr	string to replace existing one
[in]	copyflag	L_INSERT, L_COPY

Returns: 0 if OK, 1 on error

Notes:
     (1) This destroys an existing string and replaces it with
         the new string or a copy of it.
     (2) By design, an sarray is always compacted, so there are
         never any holes (null ptrs) in the ptr array up to the
         current count.

Definition at line 557 of file sarray1.c.

References Sarray::array, L_RegParams::index, L_COPY, L_INSERT, sarrayGetCount(), and stringNew().

Referenced by convertSortedToNumberedPathnames().

◆ sarraySelectByRange()

SARRAY* sarraySelectByRange	(	SARRAY *	sain,
		l_int32	first,
		l_int32	last
	)

sarraySelectByRange()

Parameters

[in]	sain	input sarray
[in]	first	index of first string to be selected
[in]	last	index of last string to be selected; use 0 to go to the end of the sarray

Returns: saout output sarray, or NULL on error

Notes:
     (1) This makes saout consisting of copies of all strings in sain
         in the index set [first ... last].  Use last == 0 to get all
         strings from first to the last string in the sarray.

Definition at line 1191 of file sarray1.c.

References L_COPY, L_INSERT, sarrayAddString(), sarrayCreate(), sarrayGetCount(), and sarrayGetString().

◆ sarraySelectBySubstring()

SARRAY* sarraySelectBySubstring	(	SARRAY *	sain,
		const char *	substr
	)

sarraySelectBySubstring()

Parameters

[in]	sain	input sarray
[in]	substr	[optional] substring for matching; can be NULL

Returns: saout output sarray, filtered with substring or NULL on error

Notes:
     (1) This selects all strings in sain that have substr as a substring.
         Note that we can't use strncmp() because we're looking for
         a match to the substring anywhere within each filename.
     (2) If substr == NULL, returns a copy of the sarray.

Definition at line 1145 of file sarray1.c.

References arrayFindSequence(), L_COPY, L_NOCOPY, sarrayAddString(), sarrayCopy(), sarrayCreate(), sarrayGetCount(), and sarrayGetString().

Referenced by getSortedPathnamesInDirectory().

◆ sarrayToString()

char* sarrayToString	(	SARRAY *	sa,
		l_int32	addnlflag
	)

sarrayToString()

Parameters

[in]	sa	string array
[in]	addnlflag	flag: 0 adds nothing to each substring 1 adds ' ' to each substring 2 adds ' ' to each substring

Returns: dest string, or NULL on error

Notes:
     (1) Concatenates all the strings in the sarray, preserving
         all white space.
     (2) If addnlflag != 0, adds either a '

' or a ' ' after
         each substring.
     (3) This function was NOT implemented as:
           for (i = 0; i < n; i++)
                    strcat(dest, sarrayGetString(sa, i, L_NOCOPY));
         Do you see why?

Definition at line 763 of file sarray1.c.

References sarrayToStringRange().

Referenced by ccbaWriteSVGString(), generateUncompressedPS(), l_genDataString(), recogExtractNumbers(), sarrayConvertWordsToLines(), and splitStringToParagraphs().

◆ sarrayToStringRange()

char* sarrayToStringRange	(	SARRAY *	sa,
		l_int32	first,
		l_int32	nstrings,
		l_int32	addnlflag
	)

sarrayToStringRange()

Parameters

[in]	sa	string array
[in]	first	index of first string to use; starts with 0
[in]	nstrings	number of strings to append into the result; use 0 to append to the end of the sarray
[in]	addnlflag	flag: 0 adds nothing to each substring 1 adds ' ' to each substring 2 adds ' ' to each substring

Returns: dest string, or NULL on error

Notes:
     (1) Concatenates the specified strings inthe sarray, preserving
         all white space.
     (2) If addnlflag != 0, adds either a '

' or a ' ' after
         each substring.
     (3) If the sarray is empty, this returns a string with just
         the character corresponding to addnlflag.

Definition at line 798 of file sarray1.c.

References L_RegParams::index, L_NOCOPY, sarrayGetCount(), sarrayGetString(), and stringNew().

Referenced by bmfGetLineStrings(), and sarrayToString().

◆ sarrayWrite()

l_ok sarrayWrite	(	const char *	filename,
		SARRAY *	sa
	)

sarrayWrite()

Parameters

[in]	filename
[in]	sa	string array

Returns: 0 if OK; 1 on error

Definition at line 1477 of file sarray1.c.

References fopenWriteStream(), L_RegParams::fp, and sarrayWriteStream().

◆ sarrayWriteMem()

l_ok sarrayWriteMem	(	l_uint8 **	pdata,
		size_t *	psize,
		SARRAY *	sa
	)

sarrayWriteMem()

Parameters

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

Returns: 0 if OK, 1 on error

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

Definition at line 1553 of file sarray1.c.

References fopenWriteWinTempfile(), L_RegParams::fp, l_binaryReadStream(), and sarrayWriteStream().

◆ sarrayWriteStream()

l_ok sarrayWriteStream	(	FILE *	fp,
		SARRAY *	sa
	)

sarrayWriteStream()

Parameters

[in]	fp	file stream
[in]	sa	string array

Returns: 0 if OK; 1 on error

Notes:
     (1) This appends a '

' to each string, which is stripped
         off by sarrayReadStream().

Definition at line 1514 of file sarray1.c.

References Sarray::array, L_RegParams::fp, SARRAY_VERSION_NUMBER, and sarrayGetCount().

Referenced by parseTrailerPdf(), sarrayAppend(), sarrayWrite(), and sarrayWriteMem().

Functions

Variables

Detailed Description

Function Documentation

◆ convertSortedToNumberedPathnames()

◆ getFilenamesInDirectory()

◆ getNumberedPathnamesInDirectory()

◆ getSortedPathnamesInDirectory()

◆ sarrayAddString()

◆ sarrayAppend()

◆ sarrayAppendRange()

◆ sarrayChangeRefcount()

◆ sarrayClear()

◆ sarrayClone()

◆ sarrayConvertWordsToLines()

◆ sarrayCopy()

◆ sarrayCreate()

◆ sarrayCreateInitialized()

◆ sarrayCreateLinesFromString()

◆ sarrayCreateWordsFromString()

◆ sarrayDestroy()

◆ sarrayExtendArray()

◆ sarrayGetArray()

◆ sarrayGetCount()

◆ sarrayGetRefcount()

◆ sarrayGetString()

◆ sarrayJoin()

◆ sarrayPadToSameSize()

◆ sarrayParseRange()

◆ sarrayRead()

◆ sarrayReadMem()

◆ sarrayReadStream()

◆ sarrayRemoveString()

◆ sarrayReplaceString()

◆ sarraySelectByRange()

◆ sarraySelectBySubstring()

◆ sarrayToString()

◆ sarrayToStringRange()

◆ sarrayWrite()

◆ sarrayWriteMem()

◆ sarrayWriteStream()