/*====================================================================*
 -  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.
 *====================================================================*/

/*!
 * \file  bbuffer.c
 * <pre>
 *
 *      Create/Destroy BBuffer
 *          L_BBUFFER      *bbufferCreate()
 *          void           *bbufferDestroy()
 *          l_uint8        *bbufferDestroyAndSaveData()
 *
 *      Operations to read data TO a BBuffer
 *          l_int32         bbufferRead()
 *          l_int32         bbufferReadStream()
 *          l_int32         bbufferExtendArray()
 *
 *      Operations to write data FROM a BBuffer
 *          l_int32         bbufferWrite()
 *          l_int32         bbufferWriteStream()
 *
 *    The bbuffer is an implementation of a byte queue.
 *    The bbuffer holds a byte array from which bytes are
 *    processed in a first-in/first-out fashion.  As with
 *    any queue, bbuffer maintains two "pointers," one to the
 *    tail of the queue (where you read new bytes onto it)
 *    and one to the head of the queue (where you start from
 *    when writing bytes out of it.
 *
 *    The queue can be visualized:
 *
 * \code
 *  byte 0                                           byte (nalloc - 1)
 *       |                                                |
 *       --------------------------------------------------
 *                 H                             T
 *       [   aw   ][  bytes currently on queue  ][  anr   ]
 *
 *       ---:  all allocated data in bbuffer
 *       H:    queue head (ptr to next byte to be written out)
 *       T:    queue tail (ptr to first byte to be written to)
 *       aw:   already written from queue
 *       anr:  allocated but not yet read to
 * \endcode
 *    The purpose of bbuffer is to allow you to safely read
 *    bytes in, and to sequentially write them out as well.
 *    In the process of writing bytes out, you don't actually
 *    remove the bytes in the array; you just move the pointer
 *    (nwritten) which points to the head of the queue.  In
 *    the process of reading bytes in, you sometimes need to
 *    expand the array size.  If a read is performed after a
 *    write, so that the head of the queue is not at the
 *    beginning of the array, the bytes already written are
 *    first removed by copying the others over them; then the
 *    new bytes are read onto the tail of the queue.
 *
 *    Note that the meaning of "read into" and "write from"
 *    the bbuffer is OPPOSITE to that for a stream, where
 *    you read "from" a stream and write "into" a stream.
 *    As a mnemonic for remembering the direction:
 *        ~ to read bytes from a stream into the bbuffer,
 *          you call fread on the stream
 *        ~ to write bytes from the bbuffer into a stream,
 *          you call fwrite on the stream
 *
 *    See zlibmem.c for an example use of bbuffer, where we
 *    compress and decompress an array of bytes in memory.
 *
 *    We can also use the bbuffer trivially to read from stdin
 *    into memory; e.g., to capture bytes piped from the stdout
 *    of another program.  This is equivalent to repeatedly
 *    calling bbufferReadStream() until the input queue is empty.
 *    This is implemented in l_binaryReadStream().
 * </pre>
 */

#ifdef HAVE_CONFIG_H
#include <config_auto.h>
#endif  /* HAVE_CONFIG_H */

#include <string.h>
#include "allheaders.h"

   /* Bounds on array size */
static const l_uint32  MaxArraySize = 1000000000;   /* 10^9 bytes */
static const l_int32   InitialArraySize = 1024;     /*!< n'importe quoi */

/*--------------------------------------------------------------------------*
 *                         BBuffer create/destroy                           *
 *--------------------------------------------------------------------------*/
/*!
 * \brief   bbufferCreate()
 *
 * \param[in]    indata   address in memory [optional]
 * \param[in]    nalloc   size of byte array to be alloc'd 0 for default
 * \return  bbuffer, or NULL on error
 *
 * <pre>
 * Notes:
 *      (1) If a buffer address is given, you should read all the data in.
 *      (2) Allocates a bbuffer with associated byte array of
 *          the given size.  If a buffer address is given,
 *          it then reads the number of bytes into the byte array.
 * </pre>
 */
L_BBUFFER *
bbufferCreate(const l_uint8  *indata,
              l_int32         nalloc)
{
L_BBUFFER  *bb;

    if (nalloc <= 0 || nalloc > MaxArraySize)
        nalloc = InitialArraySize;

    bb = (L_BBUFFER *)LEPT_CALLOC(1, sizeof(L_BBUFFER));
    if ((bb->array = (l_uint8 *)LEPT_CALLOC(nalloc, sizeof(l_uint8))) == NULL) {
        LEPT_FREE(bb);
        return (L_BBUFFER *)ERROR_PTR("byte array not made", __func__, NULL);
    }
    bb->nalloc = nalloc;
    bb->nwritten = 0;

    if (indata) {
        memcpy(bb->array, indata, nalloc);
        bb->n = nalloc;
    } else {
        bb->n = 0;
    }

    return bb;
}


/*!
 * \brief   bbufferDestroy()
 *
 * \param[in,out]   pbb   will be set to null before returning
 * \return  void
 *
 * <pre>
 * Notes:
 *      (1) Destroys the byte array in the bbuffer and then the bbuffer;
 *          then nulls the contents of the input ptr.
 * </pre>
 */
void
bbufferDestroy(L_BBUFFER  **pbb)
{
L_BBUFFER  *bb;

    if (pbb == NULL) {
        L_WARNING("ptr address is NULL\n", __func__);
        return;
    }

    if ((bb = *pbb) == NULL)
        return;

    if (bb->array)
        LEPT_FREE(bb->array);
    LEPT_FREE(bb);
    *pbb = NULL;
}


/*!
 * \brief   bbufferDestroyAndSaveData()
 *
 * \param[in,out]   pbb       input data buffer; will be nulled
 * \param[out]      pnbytes   number of bytes saved in array
 * \return  barray newly allocated array of data
 *
 * <pre>
 * Notes:
 *      (1) Copies data to newly allocated array; then destroys the bbuffer.
 * </pre>
 */
l_uint8 *
bbufferDestroyAndSaveData(L_BBUFFER  **pbb,
                          size_t      *pnbytes)
{
l_uint8    *array;
size_t      nbytes;
L_BBUFFER  *bb;

    if (pbb == NULL) {
        L_WARNING("ptr address is NULL\n", __func__);
        return NULL;
    }
    if (pnbytes == NULL) {
        L_WARNING("&nbytes is NULL\n", __func__);
        bbufferDestroy(pbb);
        return NULL;
    }

    if ((bb = *pbb) == NULL)
        return NULL;

        /* write all unwritten bytes out to a new array */
    nbytes = bb->n - bb->nwritten;
    *pnbytes = nbytes;
    if ((array = (l_uint8 *)LEPT_CALLOC(nbytes, sizeof(l_uint8))) == NULL) {
        L_WARNING("calloc failure for array\n", __func__);
        return NULL;
    }
    memcpy(array, bb->array + bb->nwritten, nbytes);

    bbufferDestroy(pbb);
    return array;
}


/*--------------------------------------------------------------------------*
 *                   Operations to read data INTO a BBuffer                 *
 *--------------------------------------------------------------------------*/
/*!
 * \brief   bbufferRead()
 *
 * \param[in]    bb       bbuffer
 * \param[in]    src      source memory buffer from which bytes are read
 * \param[in]    nbytes   bytes to be read
 * \return  0 if OK, 1 on error
 *
 * <pre>
 * Notes:
 *      (1) For a read after write, first remove the written
 *          bytes by shifting the unwritten bytes in the array,
 *          then check if there is enough room to add the new bytes.
 *          If not, realloc with bbufferExpandArray(), resulting
 *          in a second writing of the unwritten bytes.  While less
 *          efficient, this is simpler than making a special case
 *          of reallocNew().
 * </pre>
 */
l_ok
bbufferRead(L_BBUFFER  *bb,
            l_uint8    *src,
            l_int32     nbytes)
{
l_int32  navail, nadd, nwritten;

    if (!bb)
        return ERROR_INT("bb not defined", __func__, 1);
    if (!src)
        return ERROR_INT("src not defined", __func__, 1);
    if (nbytes == 0)
        return ERROR_INT("no bytes to read", __func__, 1);

    if ((nwritten = bb->nwritten)) {  /* move the unwritten bytes over */
        memmove(bb->array, bb->array + nwritten, bb->n - nwritten);
        bb->nwritten = 0;
        bb->n -= nwritten;
    }

        /* If necessary, expand the allocated array.  Do so by
         * by at least a factor of two. */
    navail = bb->nalloc - bb->n;
    if (nbytes > navail) {
        nadd = L_MAX(bb->nalloc, nbytes);
        if (bbufferExtendArray(bb, nadd))
            return ERROR_INT("extension failed", __func__, 1);
    }

        /* Read in the new bytes */
    memcpy(bb->array + bb->n, src, nbytes);
    bb->n += nbytes;
    return 0;
}


/*!
 * \brief   bbufferReadStream()
 *
 * \param[in]    bb       bbuffer
 * \param[in]    fp       source stream from which bytes are read
 * \param[in]    nbytes   bytes to be read
 * \return  0 if OK, 1 on error
 */
l_ok
bbufferReadStream(L_BBUFFER  *bb,
                  FILE       *fp,
                  l_int32     nbytes)
{
l_int32  navail, nadd, nread, nwritten;

    if (!bb)
        return ERROR_INT("bb not defined", __func__, 1);
    if (!fp)
        return ERROR_INT("fp not defined", __func__, 1);
    if (nbytes == 0)
        return ERROR_INT("no bytes to read", __func__, 1);

    if ((nwritten = bb->nwritten)) {  /* move any unwritten bytes over */
        memmove(bb->array, bb->array + nwritten, bb->n - nwritten);
        bb->nwritten = 0;
        bb->n -= nwritten;
    }

        /* If necessary, expand the allocated array.  Do so by
         * by at least a factor of two. */
    navail = bb->nalloc - bb->n;
    if (nbytes > navail) {
        nadd = L_MAX(bb->nalloc, nbytes);
        if (bbufferExtendArray(bb, nadd))
            return ERROR_INT("extension failed", __func__, 1);
    }

        /* Read in the new bytes */
    nread = fread(bb->array + bb->n, 1, nbytes, fp);
    bb->n += nread;

    return 0;
}


/*!
 * \brief   bbufferExtendArray()
 *
 * \param[in]    bb       bbuffer
 * \param[in]    nbytes   number of bytes to extend array size
 * \return  0 if OK, 1 on error
 *
 * <pre>
 * Notes:
 *      (1) reallocNew() copies all bb->nalloc bytes, even though
 *          only bb->n are data.
 * </pre>
 */
l_ok
bbufferExtendArray(L_BBUFFER  *bb,
                   l_int32     nbytes)
{
    if (!bb)
        return ERROR_INT("bb not defined", __func__, 1);

    if ((bb->array = (l_uint8 *)reallocNew((void **)&bb->array,
                                bb->nalloc,
                                bb->nalloc + nbytes)) == NULL)
            return ERROR_INT("new ptr array not returned", __func__, 1);

    bb->nalloc += nbytes;
    return 0;
}


/*--------------------------------------------------------------------------*
 *                  Operations to write data FROM a BBuffer                 *
 *--------------------------------------------------------------------------*/
/*!
 * \brief   bbufferWrite()
 *
 * \param[in]    bb       bbuffer
 * \param[in]    dest     dest memory buffer to which bytes are written
 * \param[in]    nbytes   bytes requested to be written
 * \param[out]   pnout    bytes actually written
 * \return  0 if OK, 1 on error
 */
l_ok
bbufferWrite(L_BBUFFER  *bb,
             l_uint8    *dest,
             size_t      nbytes,
             size_t     *pnout)
{
size_t  nleft, nout;

    if (!bb)
        return ERROR_INT("bb not defined", __func__, 1);
    if (!dest)
        return ERROR_INT("dest not defined", __func__, 1);
    if (nbytes <= 0)
        return ERROR_INT("no bytes requested to write", __func__, 1);
    if (!pnout)
        return ERROR_INT("&nout not defined", __func__, 1);

    nleft = bb->n - bb->nwritten;
    nout = L_MIN(nleft, nbytes);
    *pnout = nout;

    if (nleft == 0) {   /* nothing to write; reinitialize the buffer */
        bb->n = 0;
        bb->nwritten = 0;
        return 0;
    }

        /* nout > 0; transfer the data out */
    memcpy(dest, bb->array + bb->nwritten, nout);
    bb->nwritten += nout;

        /* If all written; "empty" the buffer */
    if (nout == nleft) {
        bb->n = 0;
        bb->nwritten = 0;
    }

    return 0;
}


/*!
 * \brief   bbufferWriteStream()
 *
 * \param[in]    bb       bbuffer
 * \param[in]    fp       dest stream to which bytes are written
 * \param[in]    nbytes   bytes requested to be written
 * \param[out]   pnout    bytes actually written
 * \return  0 if OK, 1 on error
 */
l_ok
bbufferWriteStream(L_BBUFFER  *bb,
                   FILE       *fp,
                   size_t      nbytes,
                   size_t     *pnout)
{
size_t  nleft, nout;

    if (!bb)
        return ERROR_INT("bb not defined", __func__, 1);
    if (!fp)
        return ERROR_INT("output stream not defined", __func__, 1);
    if (nbytes <= 0)
        return ERROR_INT("no bytes requested to write", __func__, 1);
    if (!pnout)
        return ERROR_INT("&nout not defined", __func__, 1);

    nleft = bb->n - bb->nwritten;
    nout = L_MIN(nleft, nbytes);
    *pnout = nout;

    if (nleft == 0) {   /* nothing to write; reinitialize the buffer */
        bb->n = 0;
        bb->nwritten = 0;
        return 0;
    }

        /* nout > 0; transfer the data out */
    fwrite(bb->array + bb->nwritten, 1, nout, fp);
    bb->nwritten += nout;

        /* If all written; "empty" the buffer */
    if (nout == nleft) {
        bb->n = 0;
        bb->nwritten = 0;
    }

    return 0;
}