/*!
* ptraaDestroy()
*
* 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 @freeflag and @warnflag.
* (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.
*/
void
ptraaDestroy(L_PTRAA **ppaa,
l_int32 freeflag,
l_int32 warnflag)
{
l_int32 i, n;
L_PTRA *pa;
L_PTRAA *paa;
PROCNAME("ptraaDestroy");
if (ppaa == NULL) {
L_WARNING("ptr address is NULL\n", procName);
return;
}
if ((paa = *ppaa) == NULL)
return;
ptraaGetSize(paa, &n);
for (i = 0; i < n; i++) {
pa = ptraaGetPtra(paa, i, L_REMOVE);
ptraDestroy(&pa, freeflag, warnflag);
}
FREE(paa->ptra);
FREE(paa);
*ppaa = NULL;
return;
}
/*!
* ptraaFlattenToPtra()
*
* 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 *
ptraaFlattenToPtra(L_PTRAA *paa) {
l_int32 i, n;
L_PTRA *pat, *pad;
PROCNAME("ptraaFlattenToPtra");
if (!paa)
return (L_PTRA *) ERROR_PTR("paa not defined", procName, NULL);
pad = ptraCreate(0);
ptraaGetSize(paa, &n);
for (i = 0; i < n; i++) {
pat = ptraaGetPtra(paa, i, L_REMOVE);
if (!pat) continue;
ptraJoin(pad, pat);
ptraDestroy(&pat, FALSE, FALSE); /* they're all empty */
}
return pad;
}
/*!
* ptraaInsertPtra()
*
* 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
ptraaInsertPtra(L_PTRAA *paa,
l_int32 index,
L_PTRA *pa) {
l_int32 n;
PROCNAME("ptraaInsertPtra");
if (!paa)
return ERROR_INT("paa not defined", procName, 1);
if (!pa)
return ERROR_INT("pa not defined", procName, 1);
ptraaGetSize(paa, &n);
if (index < 0 || index >= n)
return ERROR_INT("invalid index", procName, 1);
if (paa->ptra[index] != NULL)
return ERROR_INT("ptra alread stored at index", procName, 1);
paa->ptra[index] = pa;
return 0;
}
/*!
* ptraaGetPtra()
*
* 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 @accessflag == L_HANDLE_ONLY,
* the ptra is left on the ptraa. If @accessflag == 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_PTRA *
ptraaGetPtra(L_PTRAA *paa,
l_int32 index,
l_int32 accessflag) {
l_int32 n;
L_PTRA *pa;
PROCNAME("ptraaGetPtra");
if (!paa)
return (L_PTRA *) ERROR_PTR("paa not defined", procName, NULL);
ptraaGetSize(paa, &n);
if (index < 0 || index >= n)
return (L_PTRA *) ERROR_PTR("invalid index", procName, NULL);
if (accessflag != L_HANDLE_ONLY && accessflag != L_REMOVE)
return (L_PTRA *) ERROR_PTR("invalid accessflag", procName, NULL);
pa = paa->ptra[index];
if (accessflag == L_REMOVE)
paa->ptra[index] = NULL;
return pa;
}
