numabasic.c

Go to the documentation of this file.

/*====================================================================*
 -  Copyright (C) 2001 Leptonica.  All rights reserved.
 -
 -  Redistribution and use in source and binary forms, with or without
 -  modification, are permitted provided that the following conditions
 -  are met:
 -  1. Redistributions of source code must retain the above copyright
 -     notice, this list of conditions and the following disclaimer.
 -  2. Redistributions in binary form must reproduce the above
 -     copyright notice, this list of conditions and the following
 -     disclaimer in the documentation and/or other materials
 -     provided with the distribution.
 -
 -  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 -  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 -  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 -  A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ANY
 -  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 -  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 -  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 -  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 -  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 -  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 -  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *====================================================================*/
 
#ifdef HAVE_CONFIG_H
#include <config_auto.h>
#endif  /* HAVE_CONFIG_H */
 
#include <string.h>
#include <math.h>
#include "allheaders.h"
#include "array_internal.h"
 
    /* Bounds on initial array size */
static const l_uint32  MaxFloatArraySize = 100000000;  /* for numa */
static const l_uint32  MaxPtrArraySize = 1000000;  /* for numaa */
static const l_int32 InitialArraySize = 50;      
    /* Static functions */
static l_int32 numaExtendArray(NUMA  *na);
static l_int32 numaaExtendArray(NUMAA  *naa);
 
/*--------------------------------------------------------------------------*
 *               Numa creation, destruction, copy, clone, etc.              *
 *--------------------------------------------------------------------------*/
NUMA *
numaCreate(l_int32  n)
{
NUMA  *na;
 
    if (n <= 0 || n > MaxFloatArraySize)
        n = InitialArraySize;
 
    na = (NUMA *)LEPT_CALLOC(1, sizeof(NUMA));
    if ((na->array = (l_float32 *)LEPT_CALLOC(n, sizeof(l_float32))) == NULL) {
        numaDestroy(&na);
        return (NUMA *)ERROR_PTR("number array not made", __func__, NULL);
    }
 
    na->nalloc = n;
    na->n = 0;
    na->refcount = 1;
    na->startx = 0.0;
    na->delx = 1.0;
    return na;
}
 
 
NUMA *
numaCreateFromIArray(l_int32  *iarray,
                     l_int32   size)
{
l_int32  i;
NUMA    *na;
 
    if (!iarray)
        return (NUMA *)ERROR_PTR("iarray not defined", __func__, NULL);
    if (size <= 0)
        return (NUMA *)ERROR_PTR("size must be > 0", __func__, NULL);
 
    na = numaCreate(size);
    for (i = 0; i < size; i++)
        numaAddNumber(na, iarray[i]);
 
    return na;
}
 
 
NUMA *
numaCreateFromFArray(l_float32  *farray,
                     l_int32     size,
                     l_int32     copyflag)
{
l_int32  i;
NUMA    *na;
 
    if (!farray)
        return (NUMA *)ERROR_PTR("farray not defined", __func__, NULL);
    if (size <= 0)
        return (NUMA *)ERROR_PTR("size must be > 0", __func__, NULL);
    if (copyflag != L_INSERT && copyflag != L_COPY)
        return (NUMA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    na = numaCreate(size);
    if (copyflag == L_INSERT) {
        if (na->array) LEPT_FREE(na->array);
        na->array = farray;
        na->n = size;
    } else {  /* just copy the contents */
        for (i = 0; i < size; i++)
            numaAddNumber(na, farray[i]);
    }
 
    return na;
}
 
 
NUMA *
numaCreateFromString(const char  *str)
{
char      *substr;
l_int32    i, n, nerrors;
l_float32  val;
NUMA      *na;
SARRAY    *sa;
 
    if (!str || (strlen(str) == 0))
        return (NUMA *)ERROR_PTR("str not defined or empty", __func__, NULL);
 
    sa = sarrayCreate(0);
    sarraySplitString(sa, str, ",");
    n = sarrayGetCount(sa);
    na = numaCreate(n);
    nerrors = 0;
    for (i = 0; i < n; i++) {
        substr = sarrayGetString(sa, i, L_NOCOPY);
        if (sscanf(substr, "%f", &val) != 1) {
            L_ERROR("substr %d not float\n", __func__, i);
            nerrors++;
        } else {
            numaAddNumber(na, val);
        }
    }
 
    sarrayDestroy(&sa);
    if (nerrors > 0) {
        numaDestroy(&na);
        return (NUMA *)ERROR_PTR("non-floats in string", __func__, NULL);
    }
 
    return na;
}
 
 
void
numaDestroy(NUMA  **pna)
{
NUMA  *na;
 
    if (pna == NULL) {
        L_WARNING("ptr address is NULL\n", __func__);
        return;
    }
 
    if ((na = *pna) == NULL)
        return;
 
        /* Decrement the ref count.  If it is 0, destroy the numa. */
    if (--na->refcount == 0) {
        if (na->array)
            LEPT_FREE(na->array);
        LEPT_FREE(na);
    }
 
    *pna = NULL;
}
 
 
NUMA *
numaCopy(NUMA  *na)
{
l_int32  i;
NUMA    *cna;
 
    if (!na)
        return (NUMA *)ERROR_PTR("na not defined", __func__, NULL);
 
    if ((cna = numaCreate(na->nalloc)) == NULL)
        return (NUMA *)ERROR_PTR("cna not made", __func__, NULL);
    cna->startx = na->startx;
    cna->delx = na->delx;
 
    for (i = 0; i < na->n; i++)
        numaAddNumber(cna, na->array[i]);
 
    return cna;
}
 
 
NUMA *
numaClone(NUMA  *na)
{
    if (!na)
        return (NUMA *)ERROR_PTR("na not defined", __func__, NULL);
 
    ++na->refcount;
    return na;
}
 
 
l_ok
numaEmpty(NUMA  *na)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    na->n = 0;
    return 0;
}
 
 
 
/*--------------------------------------------------------------------------*
 *                 Number array: add number and extend array                *
 *--------------------------------------------------------------------------*/
l_ok
numaAddNumber(NUMA      *na,
              l_float32  val)
{
l_int32  n;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    n = numaGetCount(na);
    if (n >= na->nalloc) {
        if (numaExtendArray(na))
            return ERROR_INT("extension failed", __func__, 1);
    }
    na->array[n] = val;
    na->n++;
    return 0;
}
 
 
static l_int32
numaExtendArray(NUMA  *na)
{
size_t  oldsize, newsize;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    if (na->nalloc > MaxFloatArraySize)  /* belt & suspenders */
        return ERROR_INT("na has too many ptrs", __func__, 1);
    oldsize = na->nalloc * sizeof(l_float32);
    newsize = 2 * oldsize;
    if (newsize > 4 * MaxFloatArraySize)
        return ERROR_INT("newsize > 400 MB; too large", __func__, 1);
 
    if ((na->array = (l_float32 *)reallocNew((void **)&na->array,
                                             oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
 
    na->nalloc *= 2;
    return 0;
}
 
 
l_ok
numaInsertNumber(NUMA      *na,
                 l_int32    index,
                 l_float32  val)
{
l_int32  i, n;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    n = numaGetCount(na);
    if (index < 0 || index > n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n);
        return 1;
    }
 
    if (n >= na->nalloc) {
        if (numaExtendArray(na))
            return ERROR_INT("extension failed", __func__, 1);
    }
    for (i = n; i > index; i--)
        na->array[i] = na->array[i - 1];
    na->array[index] = val;
    na->n++;
    return 0;
}
 
 
l_ok
numaRemoveNumber(NUMA    *na,
                 l_int32  index)
{
l_int32  i, n;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    n = numaGetCount(na);
    if (index < 0 || index >= n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n - 1);
        return 1;
    }
 
    for (i = index + 1; i < n; i++)
        na->array[i - 1] = na->array[i];
    na->n--;
    return 0;
}
 
 
l_ok
numaReplaceNumber(NUMA      *na,
                  l_int32    index,
                  l_float32  val)
{
l_int32  n;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    n = numaGetCount(na);
    if (index < 0 || index >= n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n - 1);
        return 1;
    }
 
    na->array[index] = val;
    return 0;
}
 
 
/*----------------------------------------------------------------------*
 *                            Numa accessors                            *
 *----------------------------------------------------------------------*/
l_int32
numaGetCount(NUMA  *na)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 0);
    return na->n;
}
 
 
l_ok
numaSetCount(NUMA    *na,
             l_int32  newcount)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    if (newcount > na->nalloc) {
        if ((na->array = (l_float32 *)reallocNew((void **)&na->array,
                         sizeof(l_float32) * na->nalloc,
                         sizeof(l_float32) * newcount)) == NULL)
            return ERROR_INT("new ptr array not returned", __func__, 1);
        na->nalloc = newcount;
    }
    na->n = newcount;
    return 0;
}
 
 
l_ok
numaGetFValue(NUMA       *na,
              l_int32     index,
              l_float32  *pval)
{
    if (!pval)
        return ERROR_INT("&val not defined", __func__, 1);
    *pval = 0.0;
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    if (index < 0 || index >= na->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    *pval = na->array[index];
    return 0;
}
 
 
l_ok
numaGetIValue(NUMA     *na,
              l_int32   index,
              l_int32  *pival)
{
l_float32  val;
 
    if (!pival)
        return ERROR_INT("&ival not defined", __func__, 1);
    *pival = 0;
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    if (index < 0 || index >= na->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    val = na->array[index];
    *pival = (l_int32)(val + L_SIGN(val) * 0.5);
    return 0;
}
 
 
l_ok
numaSetValue(NUMA      *na,
             l_int32    index,
             l_float32  val)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    if (index < 0 || index >= na->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    na->array[index] = val;
    return 0;
}
 
 
l_ok
numaShiftValue(NUMA      *na,
               l_int32    index,
               l_float32  diff)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    if (index < 0 || index >= na->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    na->array[index] += diff;
    return 0;
}
 
 
l_int32 *
numaGetIArray(NUMA  *na)
{
l_int32   i, n, ival;
l_int32  *array;
 
    if (!na)
        return (l_int32 *)ERROR_PTR("na not defined", __func__, NULL);
 
    if ((n = numaGetCount(na)) == 0)
        return (l_int32 *)ERROR_PTR("na is empty", __func__, NULL);
    if ((array = (l_int32 *)LEPT_CALLOC(n, sizeof(l_int32))) == NULL)
        return (l_int32 *)ERROR_PTR("array not made", __func__, NULL);
    for (i = 0; i < n; i++) {
        numaGetIValue(na, i, &ival);
        array[i] = ival;
    }
 
    return array;
}
 
 
l_float32 *
numaGetFArray(NUMA    *na,
              l_int32  copyflag)
{
l_int32     i, n;
l_float32  *array;
 
    if (!na)
        return (l_float32 *)ERROR_PTR("na not defined", __func__, NULL);
 
    if (copyflag == L_NOCOPY) {
        array = na->array;
    } else {  /* copyflag == L_COPY */
        if ((n = numaGetCount(na)) == 0)
            return (l_float32 *)ERROR_PTR("na is empty", __func__, NULL);
        if ((array = (l_float32 *)LEPT_CALLOC(n, sizeof(l_float32))) == NULL)
            return (l_float32 *)ERROR_PTR("array not made", __func__, NULL);
        for (i = 0; i < n; i++)
            array[i] = na->array[i];
    }
 
    return array;
}
 
 
l_ok
numaGetParameters(NUMA       *na,
                  l_float32  *pstartx,
                  l_float32  *pdelx)
{
    if (!pdelx && !pstartx)
        return ERROR_INT("no return val requested", __func__, 1);
    if (pstartx) *pstartx = 0.0;
    if (pdelx) *pdelx = 1.0;
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    if (pstartx) *pstartx = na->startx;
    if (pdelx) *pdelx = na->delx;
    return 0;
}
 
 
l_ok
numaSetParameters(NUMA      *na,
                  l_float32  startx,
                  l_float32  delx)
{
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    na->startx = startx;
    na->delx = delx;
    return 0;
}
 
 
l_ok
numaCopyParameters(NUMA  *nad,
                   NUMA  *nas)
{
l_float32  start, binsize;
 
    if (!nas || !nad)
        return ERROR_INT("nas and nad not both defined", __func__, 1);
 
    numaGetParameters(nas, &start, &binsize);
    numaSetParameters(nad, start, binsize);
    return 0;
}
 
 
/*----------------------------------------------------------------------*
 *                      Convert to string array                         *
 *----------------------------------------------------------------------*/
SARRAY *
numaConvertToSarray(NUMA    *na,
                    l_int32  size1,
                    l_int32  size2,
                    l_int32  addzeros,
                    l_int32  type)
{
char       fmt[32], strbuf[64];
l_int32    i, n, ival;
l_float32  fval;
SARRAY    *sa;
 
    if (!na)
        return (SARRAY *)ERROR_PTR("na not defined", __func__, NULL);
    if (type != L_INTEGER_VALUE && type != L_FLOAT_VALUE)
        return (SARRAY *)ERROR_PTR("invalid type", __func__, NULL);
 
    if (type == L_INTEGER_VALUE) {
        if (addzeros)
            snprintf(fmt, sizeof(fmt), "%%0%dd", size1);
        else
            snprintf(fmt, sizeof(fmt), "%%%dd", size1);
    } else {  /* L_FLOAT_VALUE */
        snprintf(fmt, sizeof(fmt), "%%%d.%df", size1, size2);
    }
 
    n = numaGetCount(na);
    if ((sa = sarrayCreate(n)) == NULL)
        return (SARRAY *)ERROR_PTR("sa not made", __func__, NULL);
 
    for (i = 0; i < n; i++) {
        if (type == L_INTEGER_VALUE) {
            numaGetIValue(na, i, &ival);
            snprintf(strbuf, sizeof(strbuf), fmt, ival);
        } else {  /* L_FLOAT_VALUE */
            numaGetFValue(na, i, &fval);
            snprintf(strbuf, sizeof(strbuf), fmt, fval);
        }
        sarrayAddString(sa, strbuf, L_COPY);
    }
 
    return sa;
}
 
 
/*----------------------------------------------------------------------*
 *                       Serialize numa for I/O                         *
 *----------------------------------------------------------------------*/
NUMA *
numaRead(const char  *filename)
{
FILE  *fp;
NUMA  *na;
 
    if (!filename)
        return (NUMA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (NUMA *)ERROR_PTR_1("stream not opened",
                                   filename, __func__, NULL);
    na = numaReadStream(fp);
    fclose(fp);
    if (!na)
        return (NUMA *)ERROR_PTR_1("na not read",
                                   filename, __func__, NULL);
    return na;
}
 
 
NUMA *
numaReadStream(FILE  *fp)
{
l_int32    i, n, index, ret, version;
l_float32  val, startx, delx;
NUMA      *na;
 
    if (!fp)
        return (NUMA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    ret = fscanf(fp, "\nNuma Version %d\n", &version);
    if (ret != 1)
        return (NUMA *)ERROR_PTR("not a numa file", __func__, NULL);
    if (version != NUMA_VERSION_NUMBER)
        return (NUMA *)ERROR_PTR("invalid numa version", __func__, NULL);
    if (fscanf(fp, "Number of numbers = %d\n", &n) != 1)
        return (NUMA *)ERROR_PTR("invalid number of numbers", __func__, NULL);
 
    if (n > MaxFloatArraySize) {
        L_ERROR("n = %d > %d\n", __func__, n, MaxFloatArraySize);
        return NULL;
    }
    if ((na = numaCreate(n)) == NULL)
        return (NUMA *)ERROR_PTR("na not made", __func__, NULL);
 
    for (i = 0; i < n; i++) {
        if (fscanf(fp, "  [%d] = %f\n", &index, &val) != 2) {
            numaDestroy(&na);
            return (NUMA *)ERROR_PTR("bad input data", __func__, NULL);
        }
        numaAddNumber(na, val);
    }
 
        /* Optional data */
    if (fscanf(fp, "startx = %f, delx = %f\n", &startx, &delx) == 2)
        numaSetParameters(na, startx, delx);
 
    return na;
}
 
 
NUMA *
numaReadMem(const l_uint8  *data,
            size_t          size)
{
FILE  *fp;
NUMA  *na;
 
    if (!data)
        return (NUMA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (NUMA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    na = numaReadStream(fp);
    fclose(fp);
    if (!na) L_ERROR("numa not read\n", __func__);
    return na;
}
 
 
l_ok
numaWriteDebug(const char  *filename,
               NUMA        *na)
{
    if (LeptDebugOK) {
        return numaWrite(filename, na);
    } else {
        L_INFO("write to named temp file %s is disabled\n", __func__, filename);
        return 0;
    }
}
 
 
l_ok
numaWrite(const char  *filename,
          NUMA        *na)
{
l_int32  ret;
FILE    *fp;
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "w")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = numaWriteStream(fp, na);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("na not written to stream", filename, __func__, 1);
    return 0;
}
 
 
l_ok
numaWriteStream(FILE  *fp,
                NUMA  *na)
{
l_int32    i, n;
l_float32  startx, delx;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    if (!fp)
        return numaWriteStderr(na);
 
    n = numaGetCount(na);
    fprintf(fp, "\nNuma Version %d\n", NUMA_VERSION_NUMBER);
    fprintf(fp, "Number of numbers = %d\n", n);
    for (i = 0; i < n; i++)
        fprintf(fp, "  [%d] = %f\n", i, na->array[i]);
    fprintf(fp, "\n");
 
        /* Optional data */
    numaGetParameters(na, &startx, &delx);
    if (startx != 0.0 || delx != 1.0)
        fprintf(fp, "startx = %f, delx = %f\n", startx, delx);
 
    return 0;
}
 
 
l_ok
numaWriteStderr(NUMA  *na)
{
l_int32    i, n;
l_float32  startx, delx;
 
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    n = numaGetCount(na);
    lept_stderr("\nNuma Version %d\n", NUMA_VERSION_NUMBER);
    lept_stderr("Number of numbers = %d\n", n);
    for (i = 0; i < n; i++)
        lept_stderr("  [%d] = %f\n", i, na->array[i]);
    lept_stderr("\n");
 
        /* Optional data */
    numaGetParameters(na, &startx, &delx);
    if (startx != 0.0 || delx != 1.0)
        lept_stderr("startx = %f, delx = %f\n", startx, delx);
 
    return 0;
}
 
 
l_ok
numaWriteMem(l_uint8  **pdata,
             size_t    *psize,
             NUMA      *na)
{
l_int32  ret;
FILE    *fp;
 
    if (pdata) *pdata = NULL;
    if (psize) *psize = 0;
    if (!pdata)
        return ERROR_INT("&data not defined", __func__, 1);
    if (!psize)
        return ERROR_INT("&size not defined", __func__, 1);
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = numaWriteStream(fp, na);
    fputc('\0', fp);
    fclose(fp);
    if (*psize > 0) *psize = *psize - 1;
#else
    L_INFO("no fmemopen API --> work-around: write to temp file\n", __func__);
  #ifdef _WIN32
    if ((fp = fopenWriteWinTempfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #else
    if ((fp = tmpfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #endif  /* _WIN32 */
    ret = numaWriteStream(fp, na);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}
 
 
/*--------------------------------------------------------------------------*
 *                     Numaa creation, destruction                          *
 *--------------------------------------------------------------------------*/
NUMAA *
numaaCreate(l_int32  n)
{
NUMAA  *naa;
 
    if (n <= 0 || n > MaxPtrArraySize)
        n = InitialArraySize;
 
    naa = (NUMAA *)LEPT_CALLOC(1, sizeof(NUMAA));
    if ((naa->numa = (NUMA **)LEPT_CALLOC(n, sizeof(NUMA *))) == NULL) {
        numaaDestroy(&naa);
        return (NUMAA *)ERROR_PTR("numa ptr array not made", __func__, NULL);
    }
 
    naa->nalloc = n;
    naa->n = 0;
    return naa;
}
 
 
NUMAA *
numaaCreateFull(l_int32  nptr,
                l_int32  n)
{
l_int32  i;
NUMAA   *naa;
NUMA    *na;
 
    naa = numaaCreate(nptr);
    for (i = 0; i < nptr; i++) {
        na = numaCreate(n);
        numaaAddNuma(naa, na, L_INSERT);
    }
 
    return naa;
}
 
 
l_ok
numaaTruncate(NUMAA  *naa)
{
l_int32  i, n, nn;
NUMA    *na;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
 
    n = numaaGetCount(naa);
    for (i = n - 1; i >= 0; i--) {
        na = numaaGetNuma(naa, i, L_CLONE);
        if (!na)
            continue;
        nn = numaGetCount(na);
        numaDestroy(&na);
        if (nn == 0)
            numaDestroy(&naa->numa[i]);
        else
            break;
    }
    naa->n = i + 1;
    return 0;
}
 
 
void
numaaDestroy(NUMAA  **pnaa)
{
l_int32  i;
NUMAA   *naa;
 
    if (pnaa == NULL) {
        L_WARNING("ptr address is NULL!\n", __func__);
        return;
    }
 
    if ((naa = *pnaa) == NULL)
        return;
 
    for (i = 0; i < naa->n; i++)
        numaDestroy(&naa->numa[i]);
    LEPT_FREE(naa->numa);
    LEPT_FREE(naa);
    *pnaa = NULL;
}
 
 
 
/*--------------------------------------------------------------------------*
 *                              Add Numa to Numaa                           *
 *--------------------------------------------------------------------------*/
l_ok
numaaAddNuma(NUMAA   *naa,
             NUMA    *na,
             l_int32  copyflag)
{
l_int32  n;
NUMA    *nac;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
 
    if (copyflag == L_INSERT) {
        nac = na;
    } else if (copyflag == L_COPY) {
        if ((nac = numaCopy(na)) == NULL)
            return ERROR_INT("nac not made", __func__, 1);
    } else if (copyflag == L_CLONE) {
        nac = numaClone(na);
    } else {
        return ERROR_INT("invalid copyflag", __func__, 1);
    }
 
    n = numaaGetCount(naa);
    if (n >= naa->nalloc) {
        if (numaaExtendArray(naa)) {
            if (copyflag != L_INSERT)
                numaDestroy(&nac);
            return ERROR_INT("extension failed", __func__, 1);
        }
    }
    naa->numa[n] = nac;
    naa->n++;
    return 0;
}
 
 
static l_int32
numaaExtendArray(NUMAA  *naa)
{
size_t  oldsize, newsize;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
    if (naa->nalloc > MaxPtrArraySize)  /* belt & suspenders */
        return ERROR_INT("naa has too many ptrs", __func__, 1);
    oldsize = naa->nalloc * sizeof(NUMA *);
    newsize = 2 * oldsize;
    if (newsize > 8 * MaxPtrArraySize)
        return ERROR_INT("newsize > 8 MB; too large", __func__, 1);
 
    if ((naa->numa = (NUMA **)reallocNew((void **)&naa->numa,
                                         oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
 
    naa->nalloc *= 2;
    return 0;
}
 
 
/*----------------------------------------------------------------------*
 *                           Numaa accessors                            *
 *----------------------------------------------------------------------*/
l_int32
numaaGetCount(NUMAA  *naa)
{
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 0);
    return naa->n;
}
 
 
l_int32
numaaGetNumaCount(NUMAA   *naa,
                  l_int32  index)
{
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 0);
    if (index < 0 || index >= naa->n)
        return ERROR_INT("invalid index into naa", __func__, 0);
    return numaGetCount(naa->numa[index]);
}
 
 
l_int32
numaaGetNumberCount(NUMAA  *naa)
{
NUMA    *na;
l_int32  n, sum, i;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 0);
 
    n = numaaGetCount(naa);
    for (sum = 0, i = 0; i < n; i++) {
        na = numaaGetNuma(naa, i, L_CLONE);
        sum += numaGetCount(na);
        numaDestroy(&na);
    }
 
    return sum;
}
 
 
NUMA **
numaaGetPtrArray(NUMAA  *naa)
{
    if (!naa)
        return (NUMA **)ERROR_PTR("naa not defined", __func__, NULL);
 
    naa->n = naa->nalloc;
    return naa->numa;
}
 
 
NUMA *
numaaGetNuma(NUMAA   *naa,
             l_int32  index,
             l_int32  accessflag)
{
    if (!naa)
        return (NUMA *)ERROR_PTR("naa not defined", __func__, NULL);
    if (index < 0 || index >= naa->n)
        return (NUMA *)ERROR_PTR("index not valid", __func__, NULL);
 
    if (accessflag == L_COPY)
        return numaCopy(naa->numa[index]);
    else if (accessflag == L_CLONE)
        return numaClone(naa->numa[index]);
    else
        return (NUMA *)ERROR_PTR("invalid accessflag", __func__, NULL);
}
 
 
l_ok
numaaReplaceNuma(NUMAA   *naa,
                 l_int32  index,
                 NUMA    *na)
{
l_int32  n;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
    if (!na)
        return ERROR_INT("na not defined", __func__, 1);
    n = numaaGetCount(naa);
    if (index < 0 || index >= n)
        return ERROR_INT("index not valid", __func__, 1);
 
    numaDestroy(&naa->numa[index]);
    naa->numa[index] = na;
    return 0;
}
 
 
l_ok
numaaGetValue(NUMAA      *naa,
              l_int32     i,
              l_int32     j,
              l_float32  *pfval,
              l_int32    *pival)
{
l_int32  n;
NUMA    *na;
 
    if (!pfval && !pival)
        return ERROR_INT("no return val requested", __func__, 1);
    if (pfval) *pfval = 0.0;
    if (pival) *pival = 0;
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
    n = numaaGetCount(naa);
    if (i < 0 || i >= n)
        return ERROR_INT("invalid index into naa", __func__, 1);
    na = naa->numa[i];
    if (j < 0 || j >= na->n)
        return ERROR_INT("invalid index into na", __func__, 1);
    if (pfval) *pfval = na->array[j];
    if (pival) *pival = (l_int32)(na->array[j]);
    return 0;
}
 
 
l_ok
numaaAddNumber(NUMAA     *naa,
               l_int32    index,
               l_float32  val)
{
l_int32  n;
NUMA    *na;
 
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
    n = numaaGetCount(naa);
    if (index < 0 || index >= n)
        return ERROR_INT("invalid index in naa", __func__, 1);
 
    na = numaaGetNuma(naa, index, L_CLONE);
    numaAddNumber(na, val);
    numaDestroy(&na);
    return 0;
}
 
 
/*----------------------------------------------------------------------*
 *                      Serialize numaa for I/O                         *
 *----------------------------------------------------------------------*/
NUMAA *
numaaRead(const char  *filename)
{
FILE   *fp;
NUMAA  *naa;
 
    if (!filename)
        return (NUMAA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (NUMAA *)ERROR_PTR_1("stream not opened",
                                    filename, __func__, NULL);
    naa = numaaReadStream(fp);
    fclose(fp);
    if (!naa)
        return (NUMAA *)ERROR_PTR_1("naa not read",
                                    filename, __func__, NULL);
    return naa;
}
 
 
NUMAA *
numaaReadStream(FILE  *fp)
{
l_int32    i, n, index, ret, version;
NUMA      *na;
NUMAA     *naa;
 
    if (!fp)
        return (NUMAA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    ret = fscanf(fp, "\nNumaa Version %d\n", &version);
    if (ret != 1)
        return (NUMAA *)ERROR_PTR("not a numa file", __func__, NULL);
    if (version != NUMA_VERSION_NUMBER)
        return (NUMAA *)ERROR_PTR("invalid numaa version", __func__, NULL);
    if (fscanf(fp, "Number of numa = %d\n\n", &n) != 1)
        return (NUMAA *)ERROR_PTR("invalid number of numa", __func__, NULL);
 
    if (n > MaxPtrArraySize) {
        L_ERROR("n = %d > %d\n", __func__, n, MaxPtrArraySize);
        return NULL;
    }
    if ((naa = numaaCreate(n)) == NULL)
        return (NUMAA *)ERROR_PTR("naa not made", __func__, NULL);
 
    for (i = 0; i < n; i++) {
        if (fscanf(fp, "Numa[%d]:", &index) != 1) {
            numaaDestroy(&naa);
            return (NUMAA *)ERROR_PTR("invalid numa header", __func__, NULL);
        }
        if ((na = numaReadStream(fp)) == NULL) {
            numaaDestroy(&naa);
            return (NUMAA *)ERROR_PTR("na not made", __func__, NULL);
        }
        numaaAddNuma(naa, na, L_INSERT);
    }
 
    return naa;
}
 
 
NUMAA *
numaaReadMem(const l_uint8  *data,
             size_t          size)
{
FILE   *fp;
NUMAA  *naa;
 
    if (!data)
        return (NUMAA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (NUMAA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    naa = numaaReadStream(fp);
    fclose(fp);
    if (!naa) L_ERROR("naa not read\n", __func__);
    return naa;
}
 
 
l_ok
numaaWrite(const char  *filename,
           NUMAA       *naa)
{
l_int32  ret;
FILE    *fp;
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "w")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = numaaWriteStream(fp, naa);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("naa not written to stream", filename, __func__, 1);
    return 0;
}
 
 
l_ok
numaaWriteStream(FILE   *fp,
                 NUMAA  *naa)
{
l_int32  i, n;
NUMA    *na;
 
    if (!fp)
        return ERROR_INT("stream not defined", __func__, 1);
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
 
    n = numaaGetCount(naa);
    fprintf(fp, "\nNumaa Version %d\n", NUMA_VERSION_NUMBER);
    fprintf(fp, "Number of numa = %d\n\n", n);
    for (i = 0; i < n; i++) {
        if ((na = numaaGetNuma(naa, i, L_CLONE)) == NULL)
            return ERROR_INT("na not found", __func__, 1);
        fprintf(fp, "Numa[%d]:", i);
        numaWriteStream(fp, na);
        numaDestroy(&na);
    }
 
    return 0;
}
 
 
l_ok
numaaWriteMem(l_uint8  **pdata,
              size_t    *psize,
              NUMAA     *naa)
{
l_int32  ret;
FILE    *fp;
 
    if (pdata) *pdata = NULL;
    if (psize) *psize = 0;
    if (!pdata)
        return ERROR_INT("&data not defined", __func__, 1);
    if (!psize)
        return ERROR_INT("&size not defined", __func__, 1);
    if (!naa)
        return ERROR_INT("naa not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = numaaWriteStream(fp, naa);
    fputc('\0', fp);
    fclose(fp);
    if (*psize > 0) *psize = *psize - 1;
#else
    L_INFO("no fmemopen API --> work-around: write to temp file\n", __func__);
  #ifdef _WIN32
    if ((fp = fopenWriteWinTempfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #else
    if ((fp = tmpfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #endif  /* _WIN32 */
    ret = numaaWriteStream(fp, naa);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}