 |
Leptonica 1.85.0
Image processing and image analysis suite
|
|
Leptonica 1.85.0
Image processing and image analysis suite
|
#include <unistd.h>#include <sys/stat.h>#include <sys/types.h>#include <string.h>#include <stddef.h>#include "allheaders.h"Go to the source code of this file.
Functions | |
| char * | stringNew (const char *src) |
| l_ok | stringCopy (char *dest, const char *src, l_int32 n) |
| char * | stringCopySegment (const char *src, l_int32 start, l_int32 nbytes) |
| l_ok | stringReplace (char **pdest, const char *src) |
| l_int32 | stringLength (const char *src, size_t size) |
| l_int32 | stringCat (char *dest, size_t size, const char *src) |
| char * | stringConcatNew (const char *first,...) |
| char * | stringJoin (const char *src1, const char *src2) |
| l_ok | stringJoinIP (char **psrc1, const char *src2) |
| char * | stringReverse (const char *src) |
| char * | strtokSafe (char *cstr, const char *seps, char **psaveptr) |
| l_ok | stringSplitOnToken (char *cstr, const char *seps, char **phead, char **ptail) |
| l_ok | stringCheckForChars (const char *src, const char *chars, l_int32 *pfound) |
| char * | stringRemoveChars (const char *src, const char *remchars) |
| char * | stringReplaceEachSubstr (const char *src, const char *sub1, const char *sub2, l_int32 *pcount) |
| char * | stringReplaceSubstr (const char *src, const char *sub1, const char *sub2, l_int32 *ploc, l_int32 *pfound) |
| L_DNA * | stringFindEachSubstr (const char *src, const char *sub) |
| l_int32 | stringFindSubstr (const char *src, const char *sub, l_int32 *ploc) |
| l_uint8 * | arrayReplaceEachSequence (const l_uint8 *datas, size_t dataslen, const l_uint8 *seq, size_t seqlen, const l_uint8 *newseq, size_t newseqlen, size_t *pdatadlen, l_int32 *pcount) |
| L_DNA * | arrayFindEachSequence (const l_uint8 *data, size_t datalen, const l_uint8 *sequence, size_t seqlen) |
| l_ok | arrayFindSequence (const l_uint8 *data, size_t datalen, const l_uint8 *sequence, size_t seqlen, l_int32 *poffset, l_int32 *pfound) |
| void * | reallocNew (void **pindata, size_t oldsize, size_t newsize) |
| l_uint8 * | l_binaryRead (const char *filename, size_t *pnbytes) |
| l_uint8 * | l_binaryReadStream (FILE *fp, size_t *pnbytes) |
| l_uint8 * | l_binaryReadSelect (const char *filename, size_t start, size_t nbytes, size_t *pnread) |
| l_uint8 * | l_binaryReadSelectStream (FILE *fp, size_t start, size_t nbytes, size_t *pnread) |
| l_ok | l_binaryWrite (const char *filename, const char *operation, const void *data, size_t nbytes) |
| size_t | nbytesInFile (const char *filename) |
| size_t | fnbytesInFile (FILE *fp) |
| l_uint8 * | l_binaryCopy (const l_uint8 *datas, size_t size) |
| l_ok | l_binaryCompare (const l_uint8 *data1, size_t size1, const l_uint8 *data2, size_t size2, l_int32 *psame) |
| l_ok | fileCopy (const char *srcfile, const char *newfile) |
| l_ok | fileConcatenate (const char *srcfile, const char *destfile) |
| l_ok | fileAppendString (const char *filename, const char *str) |
| l_ok | fileSplitLinesUniform (const char *filename, l_int32 n, l_int32 save_empty, const char *rootpath, const char *ext) |
| FILE * | fopenReadStream (const char *filename) |
| FILE * | fopenWriteStream (const char *filename, const char *modestring) |
| FILE * | fopenReadFromMemory (const l_uint8 *data, size_t size) |
| FILE * | fopenWriteWinTempfile (void) |
| FILE * | lept_fopen (const char *filename, const char *mode) |
| l_ok | lept_fclose (FILE *fp) |
| void * | lept_calloc (size_t nmemb, size_t size) |
| void | lept_free (void *ptr) |
| l_int32 | lept_mkdir (const char *subdir) |
| l_int32 | lept_rmdir (const char *subdir) |
| void | lept_direxists (const char *dir, l_int32 *pexists) |
| l_int32 | lept_rm_match (const char *subdir, const char *substr) |
| l_int32 | lept_rm (const char *subdir, const char *tail) |
| l_int32 | lept_rmfile (const char *filepath) |
| l_int32 | lept_mv (const char *srcfile, const char *newdir, const char *newtail, char **pnewpath) |
| l_int32 | lept_cp (const char *srcfile, const char *newdir, const char *newtail, char **pnewpath) |
| l_int32 | callSystemDebug (const char *cmd) |
| l_ok | splitPathAtDirectory (const char *pathname, char **pdir, char **ptail) |
| l_ok | splitPathAtExtension (const char *pathname, char **pbasename, char **pextension) |
| char * | pathJoin (const char *dir, const char *fname) |
| char * | appendSubdirs (const char *basedir, const char *subdirs) |
| l_ok | convertSepCharsInPath (char *path, l_int32 type) |
| char * | genPathname (const char *dir, const char *fname) |
| l_ok | makeTempDirname (char *result, size_t nbytes, const char *subdir) |
| l_ok | modifyTrailingSlash (char *path, size_t nbytes, l_int32 flag) |
| char * | l_makeTempFilename (void) |
| l_int32 | extractNumberFromFilename (const char *fname, l_int32 numpre, l_int32 numpost) |
------------------------------------------
This file has these utilities:
- safe string operations
- find/replace operations on strings
- read/write between file and memory
- multi-platform file and directory operations
- file name operations
------------------------------------------
Safe string procs
char *stringNew()
l_int32 stringCopy()
l_int32 stringCopySegment()
l_int32 stringReplace()
l_int32 stringLength()
l_int32 stringCat()
char *stringConcatNew()
char *stringJoin()
l_int32 stringJoinIP()
char *stringReverse()
char *strtokSafe()
l_int32 stringSplitOnToken()
Find and replace string and array procs
l_int32 stringCheckForChars()
char *stringRemoveChars()
char *stringReplaceEachSubstr()
char *stringReplaceSubstr()
L_DNA *stringFindEachSubstr()
l_int32 stringFindSubstr()
l_uint8 *arrayReplaceEachSequence()
L_DNA *arrayFindEachSequence()
l_int32 arrayFindSequence()
Safe realloc
void *reallocNew()
Read and write between file and memory
l_uint8 *l_binaryRead()
l_uint8 *l_binaryReadStream()
l_uint8 *l_binaryReadSelect()
l_uint8 *l_binaryReadSelectStream()
l_int32 l_binaryWrite()
l_int32 nbytesInFile()
l_int32 fnbytesInFile()
Copy and compare in memory
l_uint8 *l_binaryCopy()
l_uint8 *l_binaryCompare()
File copy operations
l_int32 fileCopy()
l_int32 fileConcatenate()
l_int32 fileAppendString()
File split operations
l_int32 fileSplitLinesUniform()
Multi-platform functions for opening file streams
FILE *fopenReadStream()
FILE *fopenWriteStream()
FILE *fopenReadFromMemory()
Opening a Windows tmpfile for writing
FILE *fopenWriteWinTempfile()
Multi-platform functions that avoid C-runtime boundary crossing
with Windows DLLs (use in programs only)
FILE *lept_fopen()
l_int32 lept_fclose()
void *lept_calloc()
void lept_free()
Multi-platform file system operations in temp directories
l_int32 lept_mkdir()
l_int32 lept_rmdir()
l_int32 lept_direxists()
l_int32 lept_mv()
l_int32 lept_rm_match()
l_int32 lept_rm()
l_int32 lept_rmfile()
l_int32 lept_cp()
Special debug/test function for calling 'system'
l_int32 callSystemDebug()
General file name operations
l_int32 splitPathAtDirectory()
l_int32 splitPathAtExtension()
char *pathJoin()
char *appendSubdirs()
Special file name operations
l_int32 convertSepCharsInPath()
char *genPathname()
l_int32 makeTempDirname()
l_int32 modifyTrailingSlash()
char *l_makeTempFilename()
l_int32 extractNumberFromFilename()
Notes on multi-platform development
-----------------------------------
This is important:
(1) With the exception of splitPathAtDirectory(), splitPathAtExtension()
and genPathname(), all input pathnames must have unix separators.
(2) On macOS, iOS and Windows, for read or write to "/tmp/..."
the filename is rewritten to use the OS specific temp directory:
/tmp ==> [Temp]/...
(3) This filename rewrite, along with the conversion from unix
to OS specific pathnames, happens in genPathname().
(4) Use fopenReadStream() and fopenWriteStream() to open files,
because these use genPathname() to find the platform-dependent
filenames. Likewise for l_binaryRead() and l_binaryWrite().
(5) For moving, copying and removing files and directories that are in
subdirectories of /tmp, use the lept_*() file system shell wrappers:
lept_mkdir(), lept_rmdir(), lept_mv(), lept_rm() and lept_cp().
(6) For programs use the lept_fopen(), lept_fclose(), lept_calloc()
and lept_free() C library wrappers. These work properly on Windows,
where the same DLL must perform complementary operations on
file streams (open/close) and heap memory (malloc/free).
(7) Why read and write files to temp directories?
The library needs the ability to read and write ephemeral
files to default places, both for generating debugging output
and for supporting regression tests. Applications also need
this ability for debugging.
(8) Why do the pathname rewrite on macOS, iOS and Windows?
The goal is to have the library, and programs using the library,
run on multiple platforms without changes. The location of
temporary files depends on the platform as well as the user's
configuration. Temp files on some operating systems are in some
directory not known a priori. To make everything work seamlessly on
any OS, every time you open a file for reading or writing,
use a special function such as fopenReadStream() or
fopenWriteStream(); these call genPathname() to ensure that
if it is a temp file, the correct path is used. To indicate
that this is a temp file, the application is written with the
root directory of the path in a canonical form: "/tmp".
(9) Why is it that multi-platform directory functions like lept_mkdir()
and lept_rmdir(), as well as associated file functions like
lept_rm(), lept_mv() and lept_cp(), only work in the temp dir?
These functions were designed to provide easy manipulation of
temp files. The restriction to temp files is for safety -- to
prevent an accidental deletion of important files. For example,
lept_rmdir() first deletes all files in a specified subdirectory
of temp, and then removes the directory.
Definition in file utils2.c.
| char * appendSubdirs | ( | const char * | basedir, |
| const char * | subdirs ) |
| [in] | basedir | |
| [in] | subdirs |
Notes:
(1) Use unix pathname separators
(2) Allocates a new string: [basedir]/[subdirs]
Definition at line 2966 of file utils2.c.
References stringCat().
| L_DNA * arrayFindEachSequence | ( | const l_uint8 * | data, |
| size_t | datalen, | ||
| const l_uint8 * | sequence, | ||
| size_t | seqlen ) |
| [in] | data | byte array |
| [in] | datalen | length of data, in bytes |
| [in] | sequence | subarray of bytes to find in data |
| [in] | seqlen | length of sequence, in bytes |
Notes:
(1) The byte arrays data and sequence are not C strings,
because they can contain null bytes. Therefore, for each
we must give the length of the array.
(2) This finds every non-overlapping occurrence in data of sequence.
After it finds each match, it moves forward by the length
of the sequence before continuing the search. So for example,
if you search for the sequence 'aa' in the data 'baaabbb',
you find one match at position 1.
Definition at line 1145 of file utils2.c.
References arrayFindSequence().
Referenced by arrayReplaceEachSequence(), and stringFindEachSubstr().
| l_ok arrayFindSequence | ( | const l_uint8 * | data, |
| size_t | datalen, | ||
| const l_uint8 * | sequence, | ||
| size_t | seqlen, | ||
| l_int32 * | poffset, | ||
| l_int32 * | pfound ) |
| [in] | data | byte array |
| [in] | datalen | length of data, in bytes |
| [in] | sequence | subarray of bytes to find in data |
| [in] | seqlen | length of sequence, in bytes |
| [out] | poffset | offset from beginning of data where the sequence begins |
| [out] | pfound | 1 if sequence is found; 0 otherwise |
Notes:
(1) The byte arrays 'data' and 'sequence' are in general not C strings,
because they can contain null bytes. Therefore, for each
we must give the length of the array.
(2) This searches for the first occurrence in data of sequence,
which consists of seqlen bytes. The parameter seqlen
must not exceed the actual length of the sequence byte array.
(3) If either byte array is a C string, cast the array to
(const l_uint8 *) and use strlen() on the string for its length.
(4) If the sequence is not found, the offset will be 0, so you
must check found.
Definition at line 1205 of file utils2.c.
Referenced by arrayFindEachSequence().
| l_uint8 * arrayReplaceEachSequence | ( | const l_uint8 * | datas, |
| size_t | dataslen, | ||
| const l_uint8 * | seq, | ||
| size_t | seqlen, | ||
| const l_uint8 * | newseq, | ||
| size_t | newseqlen, | ||
| size_t * | pdatadlen, | ||
| l_int32 * | pcount ) |
| [in] | datas | source byte array |
| [in] | dataslen | length of source data, in bytes |
| [in] | seq | subarray of bytes to find in source data |
| [in] | seqlen | length of subarray, in bytes |
| [in] | newseq | replacement subarray; can be null |
| [in] | newseqlen | length of replacement subarray, in bytes |
| [out] | pdatadlen | length of dest byte array, in bytes |
| [out] | pcount | [optional] the number of times that sub1 is found in src; 0 if not found |
Notes:
(1) The byte arrays datas, seq and newseq are not C strings,
because they can contain null bytes. Therefore, for each
we must give the length of the array.
(2) If newseq == NULL, this just removes all instances of seq.
Otherwise, it replaces every non-overlapping occurrence of
seq in datas with newseq. A new array datad and its
size are returned. See arrayFindEachSequence() for more
details on finding non-overlapping occurrences.
(3) If no instances of seq are found, this returns a copy of datas.
(4) The returned datad is null terminated.
(5) Can use stringReplaceEachSubstr() if using C strings.
Definition at line 1056 of file utils2.c.
References arrayFindEachSequence(), and l_binaryCopy().
Referenced by stringReplaceEachSubstr().
| l_int32 callSystemDebug | ( | const char * | cmd | ) |
| [in] | cmd | command to be exec'd |
Notes:
(1) The C library 'system' call is only made through this function.
It only works in debug/test mode, where the global variable
LeptDebugOK == TRUE. This variable is set to FALSE in the
library as distributed, and calling this function will
generate an error message.
| l_ok convertSepCharsInPath | ( | char * | path, |
| l_int32 | type ) |
| [in] | path | |
| [in] | type | UNIX_PATH_SEPCHAR, WIN_PATH_SEPCHAR |
Notes:
(1) In-place conversion.
(2) Type is the resulting type:
* UNIX_PATH_SEPCHAR: '\' ==> '/'
* WIN_PATH_SEPCHAR: '/' ==> '\'
(3) Virtually all path operations in leptonica use unix separators.
(4) The backslash is a valid character in unix pathnames and should
not be converted. Each backslash needs to be escaped with a
preceding backslash for the shell, but the actual filename
does not include these escape characters.
Definition at line 3020 of file utils2.c.
Referenced by genPathname(), and splitPathAtDirectory().
| l_int32 extractNumberFromFilename | ( | const char * | fname, |
| l_int32 | numpre, | ||
| l_int32 | numpost ) |
| [in] | fname | |
| [in] | numpre | number of characters before the digits to be found |
| [in] | numpost | number of characters after the digits to be found |
Notes:
(1) The number is to be found in the basename, which is the
filename without either the directory or the last extension.
(2) When a number is found, it is non-negative. If no number
is found, this returns -1, without an error message. The
caller needs to check.
Definition at line 3354 of file utils2.c.
References splitPathAtDirectory(), and splitPathAtExtension().
| l_ok fileAppendString | ( | const char * | filename, |
| const char * | str ) |
| [in] | filename | |
| [in] | str | string to append to file |
Definition at line 1753 of file utils2.c.
References fopenWriteStream().
| l_ok fileConcatenate | ( | const char * | srcfile, |
| const char * | destfile ) |
| [in] | srcfile | append data from this file |
| [in] | destfile | add data to this file |
Definition at line 1727 of file utils2.c.
References l_binaryRead(), and l_binaryWrite().
| l_ok fileCopy | ( | const char * | srcfile, |
| const char * | newfile ) |
| [in] | srcfile | copy from this file |
| [in] | newfile | copy to this file |
Definition at line 1699 of file utils2.c.
References l_binaryRead(), and l_binaryWrite().
| l_ok fileSplitLinesUniform | ( | const char * | filename, |
| l_int32 | n, | ||
| l_int32 | save_empty, | ||
| const char * | rootpath, | ||
| const char * | ext ) |
| [in] | filename | input file |
| [in] | n | number of output files (>= 1) |
| [in] | save_empty | 1 to save empty lines; 0 to remove them |
| [in] | rootpath | root pathname of output files |
| [in] | ext | output extension, including the '.'; can be NULL |
Notes:
(1) This splits an input text file into n files with roughly
equal numbers of text lines in each file.
(2) if save_empty == 1, empty lines are included, and concatention
of the text in the split files will be identical to the original.
(3) The output filenames are in the form:
<rootpath>_N.<ext>, N = 1, ... n
(4) This handles the temp directory pathname conversion where needed:
/tmp ==> [OS specific temp directory]
(5) Files can also be sharded into sets of lines by the program 'split':
split -n l/<n> <filename>
Using 'split', the resulting files have approximately equal
numbers of bytes, rather than equal numbers of lines.
Definition at line 1801 of file utils2.c.
References l_binaryRead(), and l_binaryWrite().
| size_t fnbytesInFile | ( | FILE * | fp | ) |
| [in] | fp | file stream |
Definition at line 1593 of file utils2.c.
Referenced by nbytesInFile().
| FILE * fopenReadFromMemory | ( | const l_uint8 * | data, |
| size_t | size ) |
| [in] | data,size |
Notes:
(1) Work-around if fmemopen() not available.
(2) Windows tmpfile() writes into the root C:\ directory, which
requires admin privileges. This also works around that.
Definition at line 1951 of file utils2.c.
References fopenWriteWinTempfile().
| FILE * fopenReadStream | ( | const char * | filename | ) |
| [in] | filename |
Notes:
(1) This should be used whenever you want to run fopen() to
read from a stream. Never call fopen() directory.
(2) This handles the temp directory pathname conversion where needed:
/tmp ==> [OS specific temp directory]
Definition at line 1876 of file utils2.c.
References genPathname(), and splitPathAtDirectory().
Referenced by l_binaryRead(), l_binaryReadSelect(), lept_fopen(), and nbytesInFile().
| FILE * fopenWriteStream | ( | const char * | filename, |
| const char * | modestring ) |
| [in] | filename | |
| [in] | modestring |
Notes:
(1) This should be used whenever you want to run fopen() to
write or append to a stream. Never call fopen() directory.
(2) This handles the temp directory pathname conversion where needed:
/tmp ==> [OS specific temp directory]
Definition at line 1919 of file utils2.c.
References genPathname().
Referenced by fileAppendString(), l_binaryWrite(), and lept_fopen().
| FILE * fopenWriteWinTempfile | ( | void | ) |
Notes:
(1) The Windows version of tmpfile() writes into the root
C:\ directory, which requires admin privileges. This
function provides an alternative implementation.
Definition at line 1995 of file utils2.c.
References l_makeTempFilename(), and lept_free().
Referenced by fopenReadFromMemory().
| char * genPathname | ( | const char * | dir, |
| const char * | fname ) |
| [in] | dir | [optional] directory or full path name, with or without the trailing '/' |
| [in] | fname | [optional] file name within a directory |
Notes:
(1) This function generates actual paths in the following ways:
* from two sub-parts (e.g., a directory and a file name).
* from a single path full path, placed in dir, with
fname == NULL.
* from the name of a file in the local directory placed in
fname, with dir == NULL.
* if in a "/tmp" directory and on iOS, macOS or Windows,
the OS specific temp directory is used.
(2) This does an automatic directory translation for operating
systems that use a different path for /tmp.
That path is determined
* on Windows: by GetTempPath()
* on macOS, iOS: by confstr() (see man page)
(3) On unix, the TMPDIR variable is ignored. No rewriting
of temp directories is permitted.
(4) There are four cases for the input:
(a) dir is a directory and fname is defined: result is a
full path
(b) dir is a directory and fname is null: result is a directory
(c) dir is a full path and fname is null: result is a full path
(d) dir is null or an empty string: start in the current dir;
result is a full path
(5) In all cases, the resulting pathname is not terminated with a slash
(6) The caller is responsible for freeing the returned pathname.
Definition at line 3086 of file utils2.c.
References convertSepCharsInPath(), stringCat(), stringCopy(), and stringNew().
Referenced by fopenReadStream(), fopenWriteStream(), lept_cp(), lept_direxists(), lept_mkdir(), lept_mv(), lept_rm(), lept_rm_match(), lept_rmdir(), and makeTempDirname().
| l_ok l_binaryCompare | ( | const l_uint8 * | data1, |
| size_t | size1, | ||
| const l_uint8 * | data2, | ||
| size_t | size2, | ||
| l_int32 * | psame ) |
| [in] | data1 | |
| [in] | size1 | of data1 |
| [in] | data2 | |
| [in] | size2 | of data1 |
| [out] | psame | (1 if the same, 0 if different) |
Notes:
(1) This can also be used to compare C strings str1 and str2.
If the string lengths are not known, use strlen():
l_binaryCompare((l_uint8 *)str1, strlen(str1),
(l_uint8 *)str2, strlen(str2));
| l_uint8 * l_binaryCopy | ( | const l_uint8 * | datas, |
| size_t | size ) |
| [in] | datas | |
| [in] | size | of data array |
Notes:
(1) We add 4 bytes to the zeroed output because in some cases
(e.g., string handling) it is important to have the data
be null terminated. This guarantees that after the memcpy,
the result is automatically null terminated.
Definition at line 1631 of file utils2.c.
Referenced by arrayReplaceEachSequence().
| l_uint8 * l_binaryRead | ( | const char * | filename, |
| size_t * | pnbytes ) |
| [in] | filename | |
| [out] | pnbytes | number of bytes read |
Definition at line 1320 of file utils2.c.
References fopenReadStream(), and l_binaryReadStream().
Referenced by fileConcatenate(), fileCopy(), and fileSplitLinesUniform().
| l_uint8 * l_binaryReadSelect | ( | const char * | filename, |
| size_t | start, | ||
| size_t | nbytes, | ||
| size_t * | pnread ) |
| [in] | filename | |
| [in] | start | first byte to read |
| [in] | nbytes | number of bytes to read; use 0 to read to end of file |
| [out] | pnread | number of bytes actually read |
Notes:
(1) The returned array is terminated with a null byte so that it can
be used to read ascii data from a file into a proper C string.
Definition at line 1434 of file utils2.c.
References fopenReadStream(), and l_binaryReadSelectStream().
| l_uint8 * l_binaryReadSelectStream | ( | FILE * | fp, |
| size_t | start, | ||
| size_t | nbytes, | ||
| size_t * | pnread ) |
| [in] | fp | file stream |
| [in] | start | first byte to read |
| [in] | nbytes | number of bytes to read; use 0 to read to end of file |
| [out] | pnread | number of bytes actually read |
Notes:
(1) The returned array is terminated with a null byte so that it can
be used to read ascii data from a file into a proper C string.
If the file to be read is empty and start == 0, an array
with a single null byte is returned.
(2) Side effect: the stream pointer is re-positioned to the
beginning of the file.
Definition at line 1478 of file utils2.c.
Referenced by l_binaryReadSelect(), and l_binaryReadStream().
| l_uint8 * l_binaryReadStream | ( | FILE * | fp, |
| size_t * | pnbytes ) |
| [in] | fp | file stream opened to read; can be stdin |
| [out] | pnbytes | number of bytes read |
Notes:
(1) The returned array is terminated with a null byte so that it can
be used to read ascii data from a file into a proper C string.
(2) This can be used to capture data that is piped in via stdin,
because it does not require seeking within the file.
(3) For example, you can read an image from stdin into memory
using shell redirection, with one of these shell commands:
cat <imagefile> | readprog
readprog < <imagefile>
where readprog is:
l_uint8 *data = l_binaryReadStream(stdin, &nbytes);
Pix *pix = pixReadMem(data, nbytes);
Definition pix_internal.h:181
Definition at line 1369 of file utils2.c.
References L_ByteBuffer::array, l_binaryReadSelectStream(), L_ByteBuffer::n, and L_ByteBuffer::nalloc.
Referenced by l_binaryRead().
| l_ok l_binaryWrite | ( | const char * | filename, |
| const char * | operation, | ||
| const void * | data, | ||
| size_t | nbytes ) |
| [in] | filename | output file |
| [in] | operation | "w" for write; "a" for append |
| [in] | data | binary data to be written |
| [in] | nbytes | size of data array |
Definition at line 1531 of file utils2.c.
References fopenWriteStream(), stringCat(), and stringCopy().
Referenced by fileConcatenate(), fileCopy(), and fileSplitLinesUniform().
| char * l_makeTempFilename | ( | void | ) |
Notes:
(1) On unix, this makes a filename of the form
"/tmp/lept.XXXXXX",
where each X is a random character.
(2) On Windows, this makes a filename of the form
"/[Temp]/lp.XXXXXX".
(3) On all systems, this fails if the file is not writable.
(4) Safest usage is to write to a subdirectory in debug code.
(5) The returned filename must be freed by the caller, using lept_free.
(6) The tail of the filename has a '.', so that cygwin interprets
the file as having an extension. Otherwise, cygwin assumes it
is an executable and appends ".exe" to the filename.
(7) On unix, whenever possible use tmpfile() instead. tmpfile()
hides the file name, returns a stream opened for write,
and deletes the temp file when the stream is closed.
Definition at line 3300 of file utils2.c.
References makeTempDirname(), stringConcatNew(), and stringNew().
Referenced by fopenWriteWinTempfile().
| void * lept_calloc | ( | size_t | nmemb, |
| size_t | size ) |
| [in] | nmemb | number of members |
| [in] | size | of each member |
Notes:
(1) For safety with Windows DLLs, this can be used in conjunction
with lept_free() to avoid C-runtime boundary problems.
Just use these two functions throughout your application.
| l_int32 lept_cp | ( | const char * | srcfile, |
| const char * | newdir, | ||
| const char * | newtail, | ||
| char ** | pnewpath ) |
| [in] | srcfile | |
| [in] | newdir | [optional]; can be NULL |
| [in] | newtail | [optional]; can be NULL |
| [out] | pnewpath | [optional] of actual path; can be NULL |
Notes:
(1) This copies srcfile to /tmp or to a subdirectory of /tmp.
(2) srcfile can either be a full path or relative to the
current directory.
(3) newdir can either specify an existing subdirectory of /tmp,
or can be NULL. In the latter case, the file will be written
into /tmp.
(4) newtail can either specify a filename tail or, if NULL,
the filename is taken from src-tail, the tail of srcfile.
(5) For debugging, the computed newpath can be returned. It must
be freed by the caller.
(6) Reminders:
(a) specify files using unix pathnames
(b) this does an automatic directory translation for operating
systems that use a different path for /tmp
(7) Examples:
* newdir = NULL, newtail = NULL ==> /tmp/src-tail
* newdir = NULL, newtail = abc ==> /tmp/abc
* newdir = def/ghi, newtail = NULL ==> /tmp/def/ghi/src-tail
* newdir = def/ghi, newtail = abc ==> /tmp/def/ghi/abc
Definition at line 2593 of file utils2.c.
References fileCopy(), genPathname(), makeTempDirname(), pathJoin(), and splitPathAtDirectory().
| void lept_direxists | ( | const char * | dir, |
| l_int32 * | pexists ) |
| [in] | dir | |
| [out] | pexists | 1 if it exists; 0 otherwise |
Notes:
(1) Always use unix pathname separators.
(2) By calling genPathname(), if the pathname begins with "/tmp"
this does an automatic directory translation for operating
systems that use a different path for /tmp.
Definition at line 2300 of file utils2.c.
References genPathname().
Referenced by lept_rmdir().
| l_ok lept_fclose | ( | FILE * | fp | ) |
| [in] | fp | file stream |
Notes:
(1) This should be used by any application that accepts
a file handle generated by a leptonica Windows DLL.
| FILE * lept_fopen | ( | const char * | filename, |
| const char * | mode ) |
| [in] | filename | |
| [in] | mode | same as for fopen(); e.g., "rb" |
Notes:
(1) This must be used by any application that passes
a file handle to a leptonica Windows DLL.
Definition at line 2051 of file utils2.c.
References fopenReadStream(), fopenWriteStream(), and stringFindSubstr().
| void lept_free | ( | void * | ptr | ) |
| [in] | ptr |
Notes:
(1) This should be used by any application that accepts
heap data allocated by a leptonica Windows DLL.
Definition at line 2124 of file utils2.c.
Referenced by fopenWriteWinTempfile().
| l_int32 lept_mkdir | ( | const char * | subdir | ) |
| [in] | subdir | of /tmp or its OS specific equivalent |
Notes:
(1) subdir is a partial path that can consist of one or more
directories.
(2) This makes any subdirectories of /tmp that are required.
(3) The root temp directory is:
/tmp (unix) [default]
[Temp] (Windows)
Definition at line 2152 of file utils2.c.
References genPathname(), L_NOCOPY, and pathJoin().
| l_int32 lept_mv | ( | const char * | srcfile, |
| const char * | newdir, | ||
| const char * | newtail, | ||
| char ** | pnewpath ) |
| [in] | srcfile | |
| [in] | newdir | [optional]; can be NULL |
| [in] | newtail | [optional]; can be NULL |
| [out] | pnewpath | [optional] of actual path; can be NULL |
Notes:
(1) This moves srcfile to /tmp or to a subdirectory of /tmp.
(2) srcfile can either be a full path or relative to the
current directory.
(3) newdir can either specify an existing subdirectory of /tmp
or can be NULL. In the latter case, the file will be written
into /tmp.
(4) newtail can either specify a filename tail or, if NULL,
the filename is taken from src-tail, the tail of srcfile.
(5) For debugging, the computed newpath can be returned. It must
be freed by the caller.
(6) Reminders:
(a) specify files using unix pathnames
(b) this does an automatic directory translation on operating
systems that use a different path for /tmp.
(7) Examples:
* newdir = NULL, newtail = NULL ==> /tmp/src-tail
* newdir = NULL, newtail = abc ==> /tmp/abc
* newdir = def/ghi, newtail = NULL ==> /tmp/def/ghi/src-tail
* newdir = def/ghi, newtail = abc ==> /tmp/def/ghi/abc
Definition at line 2497 of file utils2.c.
References fileCopy(), genPathname(), makeTempDirname(), pathJoin(), and splitPathAtDirectory().
| l_int32 lept_rm | ( | const char * | subdir, |
| const char * | tail ) |
| [in] | subdir | [optional] subdir of '/tmp'; can be NULL |
| [in] | tail | filename without the directory |
Notes:
(1) By calling genPathname(), this does an automatic directory
translation on operating systems which use a different path.
Definition at line 2404 of file utils2.c.
References genPathname(), lept_rmfile(), and makeTempDirname().
| l_int32 lept_rm_match | ( | const char * | subdir, |
| const char * | substr ) |
| [in] | subdir | [optional] if NULL, the removed files are in /tmp |
| [in] | substr | [optional] pattern to match in filename |
Notes:
(1) This removes the matched files in /tmp or a subdirectory of /tmp.
Use NULL for subdir if the files are in /tmp.
(2) If substr == NULL, this removes all files in the directory.
If substr == "" (empty), this removes no files.
If both subdir == NULL and substr == NULL, this removes
all files in /tmp.
(3) Use unix pathname separators.
(4) By calling genPathname(), if the pathname begins with "/tmp"
this does an automatic directory translation for operating
systems that use a different path for /tmp.
(5) Error conditions:
* returns -1 if the directory is not found
* returns the number of files (> 0) that it was unable to remove.
Definition at line 2357 of file utils2.c.
References genPathname(), L_NOCOPY, lept_rmfile(), and makeTempDirname().
| l_int32 lept_rmdir | ( | const char * | subdir | ) |
| [in] | subdir | of /tmp or its OS specific equivalent |
Notes:
(1) subdir is a partial path that can consist of one or more
directories.
(2) This removes all files from the specified subdirectory of
the root temp directory:
/tmp (unix)
[Temp] (Windows)
and then removes the subdirectory.
(3) The combination
lept_rmdir(subdir);
lept_mkdir(subdir);
is guaranteed to give you an empty subdirectory.
Definition at line 2227 of file utils2.c.
References genPathname(), L_NOCOPY, lept_direxists(), and pathJoin().
| l_int32 lept_rmfile | ( | const char * | filepath | ) |
| [in] | filepath | full path to file including the directory |
Notes:
(1) This removes the named file.
(2) Use unix pathname separators.
(3) There is no name translation.
(4) Unlike the other lept_* functions in this section, this can remove
any file -- it is not restricted to files that are in /tmp or a
subdirectory of it.
(5) For files in /tmp or a subdirectory of it, this does an automatic
directory translation for operating systems that use a different
path for /tmp.
Definition at line 2445 of file utils2.c.
Referenced by lept_rm(), and lept_rm_match().
| l_ok makeTempDirname | ( | char * | result, |
| size_t | nbytes, | ||
| const char * | subdir ) |
| [in] | result | preallocated on stack or heap and passed in |
| [in] | nbytes | size of result array, in bytes |
| [in] | subdir | [optional]; can be NULL or an empty string |
Notes:
(1) This generates the directory path for output temp files,
written into result with unix separators.
(2) Caller allocates result, large enough to hold the path,
which is:
/tmp/subdir (unix)
[Temp]/subdir (Windows, macOS, iOS)
where [Temp] is the OS path
and subdir is in general a set of nested subdirectories:
dir1/dir2/.../dirN
which in use would not typically exceed 2 levels.
(3) Usage example:
char result[256];
makeTempDirname(result, sizeof(result), "lept/golden");
Definition at line 3202 of file utils2.c.
References genPathname(), pathJoin(), stringCopy(), and stringNew().
Referenced by l_makeTempFilename(), lept_cp(), lept_mv(), lept_rm(), and lept_rm_match().
| l_ok modifyTrailingSlash | ( | char * | path, |
| size_t | nbytes, | ||
| l_int32 | flag ) |
| [in] | path | preallocated on stack or heap and passed in |
| [in] | nbytes | size of path array, in bytes |
| [in] | flag | L_ADD_TRAIL_SLASH or L_REMOVE_TRAIL_SLASH |
Notes:
(1) This carries out the requested action if necessary.
Definition at line 3252 of file utils2.c.
References L_ADD_TRAIL_SLASH, and L_REMOVE_TRAIL_SLASH.
| size_t nbytesInFile | ( | const char * | filename | ) |
| [in] | filename |
Definition at line 1571 of file utils2.c.
References fnbytesInFile(), and fopenReadStream().
| char * pathJoin | ( | const char * | dir, |
| const char * | fname ) |
| [in] | dir | [optional] can be null |
| [in] | fname | [optional] can be null |
Notes:
(1) Use unix-style pathname separators ('/').
(2) fname can be the entire path, or part of the path containing
at least one directory, or a tail without a directory, or NULL.
(3) It produces a path that strips multiple slashes to a single
slash, joins dir and fname by a slash, and has no trailing
slashes (except in the cases where dir == "/" and
fname == NULL, or v.v.).
(4) If both dir and fname are null, produces an empty string.
(5) Neither dir nor fname can begin with '..'.
(6) The result is not canonicalized or tested for correctness:
garbage in (e.g., /&%), garbage out.
(7) Examples:
//tmp// + //abc/ --> /tmp/abc
tmp/ + /abc/ --> tmp/abc
tmp/ + abc/ --> tmp/abc
/tmp/ + /// --> /tmp
/tmp/ + NULL --> /tmp
// + /abc// --> /abc
// + NULL --> /
NULL + /abc/def/ --> /abc/def
NULL + abc// --> abc
NULL + // --> /
NULL + NULL --> (empty string)
"" + "" --> (empty string)
"" + / --> /
".." + /etc/foo --> NULL
/tmp + ".." --> NULL
Definition at line 2889 of file utils2.c.
References L_NOCOPY, and stringNew().
Referenced by lept_cp(), lept_mkdir(), lept_mv(), lept_rmdir(), and makeTempDirname().
| void * reallocNew | ( | void ** | pindata, |
| size_t | oldsize, | ||
| size_t | newsize ) |
| [in,out] | pindata | nulls indata before reallocing |
| [in] | oldsize | size of input data to be copied, in bytes |
| [in] | newsize | size of buffer to be reallocated in bytes |
Action: !N.B. 3) and (4! 1 Allocates memory, initialized to 0 2 Copies as much of the input data as possible to the new block, truncating the copy if necessary 3 Frees the input data 4 Zeroes the input data ptr
Notes:
(1) If newsize == 0, frees input data and nulls ptr
(2) If input data is null, only callocs new memory
(3) This differs from realloc in that it always allocates
new memory (if newsize > 0) and initializes it to 0,
it requires the amount of old data to be copied,
and it takes the address of the input ptr and
nulls the handle.
| l_ok splitPathAtDirectory | ( | const char * | pathname, |
| char ** | pdir, | ||
| char ** | ptail ) |
| [in] | pathname | full path; can be a directory |
| [out] | pdir | [optional] root directory name of input path, including trailing '/' |
| [out] | ptail | [optional] path tail, which is either the file name within the root directory or the last sub-directory in the path |
Notes:
(1) If you only want the tail, input null for the root directory ptr.
(2) If you only want the root directory name, input null for the
tail ptr.
(3) This function makes decisions based only on the lexical
structure of the input. Examples:
/usr/tmp/abc.d --> dir: /usr/tmp/ tail: abc.d
/usr/tmp/ --> dir: /usr/tmp/ tail: [empty string]
/usr/tmp --> dir: /usr/ tail: tmp
abc.d --> dir: [empty string] tail: abc.d
(4 Consider the first example above: /usr/tmp/abc.d.
Suppose you want the stem of the file, abc, without either
the directory or the extension. This can be extracted in two steps:
splitPathAtDirectory("usr/tmp/abc.d", NULL, &tail);
[sets tail: "abc.d"]
splitPathAtExtension(tail, &basename, NULL);
[sets basename: "abc"]
(5) The input can have either forward (unix) or backward (win)
slash separators. The output has unix separators.
Note that Win32 pathname functions generally accept both
slash forms, but the Windows command line interpreter
only accepts backward slashes, because forward slashes are
used to demarcate switches (vs. dashes in unix).
Definition at line 2744 of file utils2.c.
References convertSepCharsInPath(), and stringNew().
Referenced by extractNumberFromFilename(), fopenReadStream(), lept_cp(), lept_mv(), and splitPathAtExtension().
| l_ok splitPathAtExtension | ( | const char * | pathname, |
| char ** | pbasename, | ||
| char ** | pextension ) |
| [in] | pathname | full path; can be a directory |
| [out] | pbasename | [optional] pathname not including the last dot and characters after that |
| [out] | pextension | [optional] path extension, which is the last dot and the characters after it. If there is no extension, it returns the empty string |
Notes:
(1) If you only want the extension, input null for the basename ptr.
(2) If you only want the basename without extension, input null
for the extension ptr.
(3) This function makes decisions based only on the lexical
structure of the input. Examples:
/usr/tmp/abc.jpg --> basename: /usr/tmp/abc ext: .jpg
/usr/tmp/.jpg --> basename: /usr/tmp/ ext: .jpg
/usr/tmp.jpg/ --> basename: /usr/tmp.jpg/ ext: [empty str]
./.jpg --> basename: ./ ext: .jpg
(4) The input can have either forward (unix) or backward (win)
slash separators. The output has unix separators.
(5) Note that basename, as used here, is different from the result
of the unix program 'basename'. Here, basename is the entire
pathname up to a final extension and its preceding dot.
Definition at line 2812 of file utils2.c.
References splitPathAtDirectory(), stringJoin(), and stringNew().
Referenced by extractNumberFromFilename().
| l_int32 stringCat | ( | char * | dest, |
| size_t | size, | ||
| const char * | src ) |
| [in] | dest | null-terminated byte buffer |
| [in] | size | size of dest buffer |
| [in] | src | string can be null or NULL-terminated string |
Notes:
(1) Alternative implementation of strncat, that checks the input,
is easier to use (since the size of the dest buffer is specified
rather than the number of bytes to copy), and does not complain
if src is null.
(2) Never writes past end of dest.
(3) If there is not enough room to append the src, which is an error,
it does nothing.
(4) N.B. The order of 2nd and 3rd args is reversed from that in
strncat, as in the Windows function strcat_s().
Definition at line 421 of file utils2.c.
References stringLength().
Referenced by appendSubdirs(), genPathname(), l_binaryWrite(), and stringJoin().
| l_ok stringCheckForChars | ( | const char * | src, |
| const char * | chars, | ||
| l_int32 * | pfound ) |
| [in] | src | input string; can be of zero length |
| [in] | chars | string of chars to be searched for in src |
| [out] | pfound | 1 if any characters are found; 0 otherwise |
Notes:
(1) This can be used to sanitize an operation by checking for
special characters that don't belong in a string.
| char * stringConcatNew | ( | const char * | first, |
| ... ) |
| [in] | first | first string in list |
| [in] | ... | NULL-terminated list of strings |
Notes:
(1) The last arg in the list of strings must be NULL.
(2) Caller must free the returned string.
Definition at line 467 of file utils2.c.
Referenced by l_makeTempFilename().
| l_ok stringCopy | ( | char * | dest, |
| const char * | src, | ||
| l_int32 | n ) |
| [in] | dest | existing byte buffer |
| [in] | src | string [optional] can be null |
| [in] | n | max number of characters to copy |
Notes:
(1) Relatively safe wrapper for strncpy, that checks the input,
and does not complain if src is null or n < 1.
If n < 1, this is a no-op.
(2) dest needs to be at least n bytes in size.
(3) We don't call strncpy() because valgrind complains about
use of uninitialized values.
Definition at line 265 of file utils2.c.
Referenced by genPathname(), l_binaryWrite(), makeTempDirname(), stringCopySegment(), stringNew(), and strtokSafe().
| char * stringCopySegment | ( | const char * | src, |
| l_int32 | start, | ||
| l_int32 | nbytes ) |
| [in] | src | string |
| [in] | start | byte position at start of segment |
| [in] | nbytes | number of bytes in the segment; use 0 to go to end |
Notes:
(1) This is a variant of stringNew() that makes a new string
from a segment of the input string. The segment is specified
by the starting position and the number of bytes.
(2) The start location start must be within the string src.
(3) The copy is truncated to the end of the source string.
Use nbytes = 0 to copy to the end of src.
Definition at line 305 of file utils2.c.
References stringCopy().
| L_DNA * stringFindEachSubstr | ( | const char * | src, |
| const char * | sub ) |
| [in] | src | input string; can be of zero length |
| [in] | sub | substring to be searched for |
Notes:
(1) This finds every non-overlapping occurrence in src of sub.
After it finds each match, it moves forward in src by the length
of sub before continuing the search. So for example,
if you search for the sequence 'aa' in the data 'baaabbb',
you find one match at position 1.
Definition at line 974 of file utils2.c.
References arrayFindEachSequence().
| l_int32 stringFindSubstr | ( | const char * | src, |
| const char * | sub, | ||
| l_int32 * | ploc ) |
| [in] | src | input string; can be of zero length |
| [in] | sub | substring to be searched for; must not be empty |
| [out] | ploc | [optional] location of substring in src |
Notes:
(1) This is a wrapper around strstr(). It finds the first
instance of sub in src. If the substring is not found
and the location is returned, it has the value -1.
(2) Both src and sub must be defined, and sub must have
length of at least 1.
Definition at line 1003 of file utils2.c.
Referenced by lept_fopen().
| char * stringJoin | ( | const char * | src1, |
| const char * | src2 ) |
| [in] | src1 | [optional] string; can be null |
| [in] | src2 | [optional] string; can be null |
Notes:
(1) This is a safe version of strcat; it makes a new string.
(2) It is not an error if either or both of the strings
are empty, or if either or both of the pointers are null.
Definition at line 514 of file utils2.c.
References stringCat().
Referenced by splitPathAtExtension(), and stringJoinIP().
| l_ok stringJoinIP | ( | char ** | psrc1, |
| const char * | src2 ) |
| [in,out] | psrc1 | address of string src1; cannot be on the stack |
| [in] | src2 | [optional] string; can be null |
Notes:
(1) This is a safe in-place version of strcat. The contents of
src1 is replaced by the concatenation of src1 and src2.
(2) It is not an error if either or both of the strings
are empty (""), or if the pointers to the strings (*psrc1, src2)
are null.
(3) src1 should be initialized to null or an empty string
before the first call. Use one of these:
char *src1 = NULL;
char *src1 = stringNew("");
Then call with:
stringJoinIP(&src1, src2);
(4) This can also be implemented as a macro:
#define stringJoinIP(src1, src2) \
{tmpstr = stringJoin((src1),(src2)); \
LEPT_FREE(src1); \
(src1) = tmpstr;}
(5) Another function to consider for joining many strings is
stringConcatNew().
Definition at line 567 of file utils2.c.
References stringJoin().
| l_int32 stringLength | ( | const char * | src, |
| size_t | size ) |
| [in] | src | string can be null or NULL-terminated string |
| [in] | size | number of bytes to check; e.g., size of src buffer |
Notes:
(1) Safe implementation of strlen that only checks size bytes
for trailing NUL.
(2) Valid returned string lengths are between 0 and size - 1.
If size bytes are checked without finding a NUL byte, then
an error is indicated by returning size.
Definition at line 378 of file utils2.c.
Referenced by stringCat().
| char * stringNew | ( | const char * | src | ) |
| [in] | src |
Definition at line 227 of file utils2.c.
References stringCopy().
Referenced by genPathname(), l_makeTempFilename(), makeTempDirname(), pathJoin(), splitPathAtDirectory(), splitPathAtExtension(), stringRemoveChars(), stringReplace(), stringReplaceSubstr(), and stringSplitOnToken().
| char * stringRemoveChars | ( | const char * | src, |
| const char * | remchars ) |
| [in] | src | input string; can be of zero length |
| [in] | remchars | string of chars to be removed from src |
Definition at line 806 of file utils2.c.
References stringNew().
| l_ok stringReplace | ( | char ** | pdest, |
| const char * | src ) |
| [out] | pdest | string copy |
| [in] | src | [optional] string; can be null |
Notes:
(1) Frees any existing dest string
(2) Puts a copy of src string in the dest
(3) If either or both strings are null, does something reasonable.
Definition at line 343 of file utils2.c.
References stringNew().
| char * stringReplaceEachSubstr | ( | const char * | src, |
| const char * | sub1, | ||
| const char * | sub2, | ||
| l_int32 * | pcount ) |
| [in] | src | input string; can be of zero length |
| [in] | sub1 | substring to be replaced |
| [in] | sub2 | substring to put in; can be "" |
| [out] | pcount | [optional] the number of times that sub1 is found in src; 0 if not found |
Notes:
(1) This is a wrapper for simple string substitution that uses
the more general function arrayReplaceEachSequence().
(2) This finds every non-overlapping occurrence of sub1 in
src, and replaces it with sub2. By "non-overlapping"
we mean that after it finds each match, it removes the
matching characters, replaces with the substitution string
(if not empty), and continues. For example, if you replace
'aa' by 'X' in 'baaabbb', you find one match at position 1
and return 'bXabbb'.
(3) To only remove each instance of sub1, use "" for sub2
(4) Returns a copy of src if sub1 and sub2 are the same.
(5) If the input src is binary data that can have null characters,
use arrayReplaceEachSequence() directly.
Definition at line 860 of file utils2.c.
References arrayReplaceEachSequence().
| char * stringReplaceSubstr | ( | const char * | src, |
| const char * | sub1, | ||
| const char * | sub2, | ||
| l_int32 * | ploc, | ||
| l_int32 * | pfound ) |
| [in] | src | input string; can be of zero length |
| [in] | sub1 | substring to be replaced |
| [in] | sub2 | substring to put in; can be "" |
| [in,out] | ploc | [optional] input start location for search; returns the loc after replacement |
| [out] | pfound | [optional] 1 if sub1 is found; 0 otherwise |
Notes:
(1) Replaces the first instance.
(2) To remove sub1 without replacement, use "" for sub2.
(3) Returns a copy of src if either no instance of sub1 is found,
or if sub1 and sub2 are the same.
(4) If ploc == NULL, the search will start at the beginning of src.
If ploc != NULL, *ploc must be initialized to the byte offset
within src from which the search starts. To search the
string from the beginning, set loc = 0 and input &loc.
After finding sub1 and replacing it with sub2, loc will be
returned as the next position after sub2 in the output string.
(5) Note that the output string also includes all the characters
from the input string that occur after the single substitution.
Definition at line 915 of file utils2.c.
References stringNew().
| char * stringReverse | ( | const char * | src | ) |
| [in] | src | string |
| l_ok stringSplitOnToken | ( | char * | cstr, |
| const char * | seps, | ||
| char ** | phead, | ||
| char ** | ptail ) |
| [in] | cstr | input string to be split; not altered |
| [in] | seps | a string of character separators |
| [out] | phead | ptr to copy of the input string, up to the first separator token encountered |
| [out] | ptail | ptr to copy of the part of the input string starting with the first non-separator character that occurs after the first separator is found |
Notes:
(1) The input string is not altered; all split parts are new strings.
(2) The split occurs around the first consecutive sequence of
tokens encountered.
(3) The head goes from the beginning of the string up to
but not including the first token found.
(4) The tail contains the second part of the string, starting
with the first char in that part that is NOT a token.
(5) If no separator token is found, 'head' contains a copy
of the input string and 'tail' is null.
Definition at line 731 of file utils2.c.
References stringNew(), and strtokSafe().
| char * strtokSafe | ( | char * | cstr, |
| const char * | seps, | ||
| char ** | psaveptr ) |
| [in] | cstr | input string to be sequentially parsed; use NULL after the first call |
| [in] | seps | a string of character separators |
| [out] | psaveptr | ptr to the next char after the last encountered separator |
Notes:
(1) This is a thread-safe implementation of strtok.
(2) It has the same interface as strtok_r.
(3) It differs from strtok_r in usage in two respects:
(a) the input string is not altered
(b) each returned substring is newly allocated and must
be freed after use.
(4) Let me repeat that. This is "safe" because the input
string is not altered and because each returned string
is newly allocated on the heap.
(5) It is here because, surprisingly, some C libraries don't
include strtok_r.
(6) Important usage points:
~ Input the string to be parsed on the first invocation.
~ Then input NULL after that; the value returned in saveptr
is used in all subsequent calls.
(7) This is only slightly slower than strtok_r.
Definition at line 639 of file utils2.c.
References stringCopy().
Referenced by stringSplitOnToken().
1.12.0