Leptonica
1.54
|
#include "allheaders.h"
L_PTRAA* ptraaCreate | ( | l_int32 | n | ) |
Input: size of ptr array to be alloc'd Return: paa, or null on error
Notes: (1) The ptraa is generated with a fixed size, that can not change. The ptra can be generated and inserted randomly into this array.
Input: ptra item (generic ptr to a struct) Return: 0 if OK, 1 on error
Notes: (1) This adds the element to the next location beyond imax, which is the largest occupied ptr in the array. This is what you expect from a stack, where all ptrs up to and including imax are occupied, but here the occuption of items in the array is entirely arbitrary.
void ptraaDestroy | ( | L_PTRAA ** | ppaa, |
l_int32 | freeflag, | ||
l_int32 | warnflag | ||
) |
Input: &paa (<to be="" nulled>="">) freeflag (TRUE to free each remaining item in each ptra) warnflag (TRUE to warn if any remaining items are not destroyed) Return: void
Notes: (1) See ptraDestroy() for use of and . (2) To destroy the ptraa, we destroy each ptra, then the ptr array, then the ptraa, and then null the contents of the input ptr.
L_PTRA* ptraaFlattenToPtra | ( | L_PTRAA * | paa | ) |
Input: ptraa Return: ptra, or null on error
Notes: (1) This 'flattens' the ptraa to a ptra, taking the items in each ptra, in order, starting with the first ptra, etc. (2) As a side-effect, the ptra are all removed from the ptraa and destroyed, leaving an empty ptraa.
L_PTRA* ptraaGetPtra | ( | L_PTRAA * | paa, |
l_int32 | index, | ||
l_int32 | accessflag | ||
) |
Input: ptraa index (location in array) accessflag (L_HANDLE_ONLY, L_REMOVE) Return: ptra (at index location), or NULL on error or if there is no ptra there.
Notes: (1) This returns the ptra ptr. If == L_HANDLE_ONLY, the ptra is left on the ptraa. If == L_REMOVE, the ptr in the ptraa is set to NULL, and the caller is responsible for disposing of the ptra (either putting it back on the ptraa, or destroying it). (2) This returns NULL if there is no Ptra at the index location.
l_int32 ptraaGetSize | ( | L_PTRAA * | paa, |
l_int32 * | psize | ||
) |
Input: ptraa &size (<return> size of ptr array) Return: 0 if OK; 1 on error
l_int32 ptraaInsertPtra | ( | L_PTRAA * | paa, |
l_int32 | index, | ||
L_PTRA * | pa | ||
) |
Input: ptraa index (location in array for insertion) ptra (to be inserted) Return: 0 if OK; 1 on error
Notes: (1) Caller should check return value. On success, the Ptra is inserted in the Ptraa and is owned by it. However, on error, the Ptra remains owned by the caller.
l_int32 ptraCompactArray | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
Notes: (1) This compacts the items on the array, filling any empty ptrs. (2) This does not change the size of the array of ptrs.
L_PTRA* ptraCreate | ( | l_int32 | n | ) |
Input: size of ptr array to be alloc'd (0 for default) Return: pa, or null on error
void ptraDestroy | ( | L_PTRA ** | ppa, |
l_int32 | freeflag, | ||
l_int32 | warnflag | ||
) |
Input: &ptra (<to be="" nulled>="">) freeflag (TRUE to free each remaining item in the array) warnflag (TRUE to warn if any remaining items are not destroyed) Return: void
Notes: (1) If == TRUE, frees each item in the array. (2) If == FALSE and warnflag == TRUE, and there are items on the array, this gives a warning and destroys the array. If these items are not owned elsewhere, this will cause a memory leak of all the items that were on the array. So if the items are not owned elsewhere and require their own destroy function, they must be destroyed before the ptra. (3) If warnflag == FALSE, no warnings will be issued. This is useful if the items are owned elsewhere, such as a PixMemoryStore(). (4) To destroy the ptra, we destroy the ptr array, then the ptra, and then null the contents of the input ptr.
l_int32 ptraExtendArray | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
l_int32 ptraGetActualCount | ( | L_PTRA * | pa, |
l_int32 * | pcount | ||
) |
Input: ptra &count (<return> actual number of items on the ptr array) Return: 0 if OK; 1 on error
Notes: (1) The actual number of items on the ptr array, pa->nactual, will be smaller than pa->n if the array is not compacted.
void* ptraGetHandle | ( | L_PTRA * | pa, |
l_int32 | index | ||
) |
Input: ptra index (element to be retrieved) Return: item, or null on error
Notes: (1) This returns a ptr to the item. You must cast it to the type of item. Do not destroy it; the item belongs to the Ptra. (2) This can access all possible items on the ptr array. If an item doesn't exist, it returns null.
l_int32 ptraGetMaxIndex | ( | L_PTRA * | pa, |
l_int32 * | pmaxindex | ||
) |
Input: ptra &maxindex (<return> index of last item in the array); Return: 0 if OK; 1 on error
Notes: (1) The largest index to an item in the array is . is one less than the number of items that would be in the array if there were no null pointers between 0 and - 1. However, because the internal ptr array need not be compacted, there may be null pointers at indices below ; for example, if items have been removed. (2) When an item is added to the end of the array, it goes into pa->array[maxindex + 1], and maxindex is then incremented by 1. (3) If there are no items in the array, this returns = -1.
void* ptraGetPtrToItem | ( | L_PTRA * | pa, |
l_int32 | index | ||
) |
Input: ptra index (element to fetch pointer to) Return: item (just a pointer to it)
Notes: (1) The item remains on the Ptra and is 'owned' by it, so the item must not be destroyed.
l_int32 ptraInsert | ( | L_PTRA * | pa, |
l_int32 | index, | ||
void * | item, | ||
l_int32 | shiftflag | ||
) |
Input: ptra index (location in ptra to insert new value) item (generic ptr to a struct; can be null) shiftflag (L_AUTO_DOWNSHIFT, L_MIN_DOWNSHIFT, L_FULL_DOWNSHIFT) Return: 0 if OK, 1 on error
Notes: (1) This checks first to see if the location is valid, and then if there is presently an item there. If there is not, it is simply inserted into that location. (2) If there is an item at the insert location, items must be moved down to make room for the insert. In the downward shift there are three options, given by .
Input: ptra1 (add to this one) ptra2 (appended to ptra1, and emptied of items; can be null) Return: 0 if OK, 1 on error
void* ptraRemove | ( | L_PTRA * | pa, |
l_int32 | index, | ||
l_int32 | flag | ||
) |
Input: ptra index (element to be removed) flag (L_NO_COMPACTION, L_COMPACTION) Return: item, or null on error
Notes: (1) If flag == L_NO_COMPACTION, this removes the item and nulls the ptr on the array. If it takes the last item in the array, pa->n is reduced to the next item. (2) If flag == L_COMPACTION, this compacts the array for for all i >= index. It should not be used repeatedly on large arrays, because compaction is O(n). (3) The ability to remove without automatic compaction allows removal with cost O(1).
void* ptraRemoveLast | ( | L_PTRA * | pa | ) |
Input: ptra Return: item, or null on error or if the array is empty
void* ptraReplace | ( | L_PTRA * | pa, |
l_int32 | index, | ||
void * | item, | ||
l_int32 | freeflag | ||
) |
Input: ptra index (element to be replaced) item (new generic ptr to a struct; can be null) freeflag (TRUE to free old item; FALSE to return it) Return: item (old item, if it exists and is not freed), or null on error
l_int32 ptraReverse | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
Input: ptra index1 index2 Return: 0 if OK, 1 on error
const l_int32 INITIAL_PTR_ARRAYSIZE = 20 [static] |