UT/UT_WorkBuffer.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Luke Moore and Jeff Lait
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_WorkBuffer.h ( Utility Library, C++ )
 *
 * COMMENTS:
 *      A growable string buffer that can be written into.  A UT_String
 *      can be created with the contents of this buffer by calling
 *      copyIntoString().
 *
 *      It's important that a non-const version of the raw buffer is not
 *      accessible since users could write past the end of the allocated
 *      buffer.  Also note that the buffer location can change as it grows,
 *      so don't keep pointers to the buffer around.
 *
 *      Most of the time, you want to allocate an object of this class on
 *      the stack and not on the heap.
 *
 *      The buffer is kept null terminated by default.  Functions exist
 *      to verify this.  Note that the "length" of the buffer is the
 *      same as strlen - ie: it ignores the null termination!!!
 */

#ifndef __UT_WorkBuffer_h__
#define __UT_WorkBuffer_h__

#include "UT_API.h"
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <iostream.h>
#include "UT_Assert.h"
#include "UT_Defines.h"
#include "UT_String.h"

// The default page size on most sytems is 4096 bytes.  We choose a default
// buffer size significantly smaller than that in the hopes that if we have
// functions with 2 work buffers or additional variables on the stack that we
// may not have to allocate multiple stack pages.
#define UT_INITIAL_BUFFER_SIZE  2000

class UT_WorkArgs;
class UT_IStream;

class UT_API UT_WorkBuffer
{
public:
     UT_WorkBuffer();
    ~UT_WorkBuffer();

    // It's important that there is no non-const access method to the buffer.
    // Also note that the pointer to the buffer can change if the buffer
    // grows.
    const char  *buffer() const { return myBuffer; }

    // Having said that, if you need a non-const pointer you must lock
    // the string. This prohibits ANY update which changes the myLength
    // variable (and thus potentially a realloc)
    // You must release the buffer before any such changes.
    // The work buffer continues to own the memory and will free it when
    // it goes out of scope so don't think this is the same as a "steal"
    // in UT_String.
    // Currently, to ensure people couple their locks & releases,
    // it asserts there is no unaccounted locks on death.  This is so
    // people who think it is steal find out otherwise.
    // Offset is where in the string to get the pointer from.
    // This is only to be used when absolutely necessary.
    // When releasing, if you have a string buffer, and you have modified the
    // length, you should set the recomputeLength flag to 1.  This will adjust
    // the internal length variable so that further concatenations will work
    // properly.
    // The reserve_bytes parameter tells the lock to ensure that there are at
    // least that many bytes in the locked buffer.
    char        *lock(int offset = 0, size_t reserve_bytes=0);
    void         release(int recomputeLength=0);
    void         releaseSetLength(int new_length);
    int          getAllocatedSize() const { return myAllocatedSize; }

    void         reserve(size_t bytes=0);

    // This is a read only operator.  We are avoiding the writeable
    // versions as they lead to problems when people do a:
    // foo[pastend] = foo(start)
    // causing an implicit realloc.
    char         operator()(int idx) const
                 {
                     // We allow an index at myLength as if we have a null
                     // terminated buffer that is the null termination.
                     UT_ASSERT_P(idx >= 0 && idx <= myLength);
                     return myBuffer[idx];
                 }

    // This should always be true.  It's here to act as a sanity function.
    int          isNullTerminated() const;

private:
    // Reallocate the buffer until the allocated size is >= the length.  This
    // private method needs to come first so it can be inlined.
    void         growBufferIfNeeded()
    {
        // Using a while loop instead of computing an accurate size the
        // first time is slower, but most of the time the loop will execute
        // at most once.
        // We need to use myLength+1 as we need room for the null.
        while (myLength+1 > myAllocatedSize)    // false most of the time
            reserve(myAllocatedSize * 2);
    }

public:
    // These are standard string operators people tend to use:
    void         strcpy(const char *src)
    {
        clear();
        append(src);
    }
    void         strcpy(const UT_WorkBuffer &src)
    {
        clear();
        append(src);
    }

    void         strncpy(const char *src, int maxlen)
    {
        clear();
        // Ensure we have enough room:
        myLength = maxlen+1;
        growBufferIfNeeded();
        myLength = 0;
        ::strncpy(myBuffer, src, maxlen);
        // While strncat always null terminates, strncpy doesn't.
        myBuffer[maxlen] = 0;
        myLength = (int)::strlen(myBuffer);
    }

    // Note we can't just return myLength as there may be embedded NULLs.
    int          strlen() const
    {
        UT_ASSERT_P(isNullTerminated());
        return (int)::strlen(myBuffer);
    }

    int          length() const
    {
        return myLength;
    }

    void         strcat(const char *src)
    {
        append(src);
    }

    // protectedStrcat() will quote the string in double quotes if required and
    // protect any enclosed double quotes or backslashes in the source.  It
    // will not escape any other characters.
    void         protectedStrcat(const char *str, bool force_quote=false);

    // fullyProtected*Strcat() is similar to protectedStrcat, except it escapes
    // any non-printable characters.  It will not escape single quotes, and if
    // force_quote is true, it will add double-quotes.  It will work with
    // arbitrary binary data and uses the \xNN syntax to encode bytes.
    // UT_IStream::read() is capable of loading strings encoded with this
    // method, and these strings can also be decoded in Python.  If
    // fullyProtectedBinaryStrcat is called, this method can handle data
    // containing null characters.
    void         fullyProtectedStrcat(const char *str, bool force_quote=false);
    void         fullyProtectedBinaryStrcat(
                        const char *str, int size, bool force_quote=false);

    void         strncat(const char *src, int len)
    {
        UT_ASSERT_P(isNullTerminated());
        // Ensure we have at least len+1 characters (include null term)
        myLength += len+1;
        growBufferIfNeeded();
        myLength -= len+1;
        ::strncat(myBuffer, src, len);
        myLength = (int)::strlen(myBuffer);
    }

    // Extract the first argument from the src and append it to the work
    // buffer.  This does NOT handle quotes properly (i.e. if the first word
    // is quoted with spaces).
    void         strcatFirstWord(const char *src);

    int          strcmp(const char *src) const
    {
        UT_ASSERT_P(isNullTerminated());
        return ::strcmp(myBuffer, src);
    }

    int          strncmp(const char *src, int n) const
    {
        UT_ASSERT_P(isNullTerminated());
        return ::strncmp(myBuffer, src, n);
    }

    char        *strdup() const
    {
        UT_ASSERT(isNullTerminated());
        return ::strdup(myBuffer);
    }

    // Reset the buffer to an empty buffer.
    void         clear()
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        myLength = 0;
        myBuffer[0] = '\0';
    }

    // Write into the buffer at a specific place.
    // This WILL expand the buffer if it is required and keep it null
    // terminated.
    void         write(int offset, char c)
    {
        UT_ASSERT(offset >= 0);
        if (offset < 0) return;
        if (offset >= myLength)
        {
            if (myLockCount) { UT_ASSERT(0); return; }
            myLength = offset+1;
            growBufferIfNeeded();
            myBuffer[myLength] = '\0';
        }
        myBuffer[offset] = c;
        if (c == '\0')
            myLength = offset;
    }

    // This does NOT write out the trailing NULL of src, but the buffer will
    // still be null-terminated.
    void         write(int offset, const char *src)
    {
        while (*src)
        {
            write(offset, *src);
            src++;
            offset++;
        }
    }

    // Read a line from an istream -- no matter how long the line is
    // Returns 0 if the stream read failed or 1 otherwise
    bool         getline(istream &is);
    bool         getline(FILE *fp);

    // Much like getline() except that it has more features. The string itself
    // is tokenized which the UT_WorkArgs points into.
    //   line_num is incremented for each line read.
    //   comment_chars is list of characters to treat as comments.
    //     this can be NULL if we don't want this feature.
    // Returns false if the stream read failed.
    bool         cmdGetLine(istream &is, UT_WorkArgs &args, int &line_num,
                            const char *comment_chars = "#",
                            const char *separators = " \t\n\r");
    bool         cmdGetLine(UT_IStream &is, UT_WorkArgs &args, int &line_num,
                            const char *comment_chars = "#",
                            const char *separators = " \t\n\r");
    bool         cmdGetLine(FILE *fp, UT_WorkArgs &args, int &line_num,
                            const char *comment_chars = "#",
                            const char *separators = " \t\n\r");

    int          sprintf(const char *fmt, ...)
                    SYS_PRINTF_CHECK_ATTRIBUTE(2, 3);
    int          appendSprintf(const char *fmt, ...)
                    SYS_PRINTF_CHECK_ATTRIBUTE(2, 3);

    int          vsprintf(const char *fmt, va_list ap);

    // These tack stuff to the end of the buffer.
    void         append(char character)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(isNullTerminated());
        myLength++;
        growBufferIfNeeded();
        myBuffer[myLength - 1] = character;
        myBuffer[myLength] = '\0';
    }

    void         append(const char *data, int size)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(data);
        UT_ASSERT_P(isNullTerminated());
        myLength += size;
        growBufferIfNeeded();
        ::memcpy(myBuffer + myLength - size, data, size);
        myBuffer[myLength] = '\0';
    }

    void         append(const char *str)
    {
        if( UTisstring(str) )
            append(str, (int)::strlen(str));
    }

    void         append(const UT_String &str)
    {
        if (str.isstring())
            append((const char *)str);
    }

    void         append(const UT_WorkBuffer &wb)
    {
        append( wb.buffer(), wb.length() );
    }

    void        prepend(char character)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(isNullTerminated());
        myLength++;
        growBufferIfNeeded();
        ::memmove(myBuffer+1, myBuffer, myLength+1);
        myBuffer[0] = character;
    }
    void        prepend(const char *data, int size)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(data);
        UT_ASSERT_P(isNullTerminated());
        myLength += size;
        growBufferIfNeeded();
        ::memmove(myBuffer+size, myBuffer, myLength+1);
        ::memcpy(myBuffer, data, size);
    }
    void         prepend(const char *str)
    {
        UT_ASSERT_P(str);
        prepend(str, (int)::strlen(str));
    }

    void         prepend(const UT_String &str)
    {
        if (str.isstring())
            prepend((const char *)str);
    }

    void         rewind()       { backup(myLength); }

    void         backup(int by_length)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(isNullTerminated());
        UT_ASSERT_P(by_length >= 0);
        myLength -= by_length;
        UT_ASSERT(myLength >= 0);
        myBuffer[myLength] = '\0';
    }

    // Delete characters off the end of the string until we hit the
    // requested character.
    void         backupTo(char c)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(isNullTerminated());
        while( myLength > 0 && myBuffer[myLength-1] != c )
            myLength--;
        myBuffer[myLength] = '\0';
    }

    void         advance(int by_length)
    {
        if (myLockCount) { UT_ASSERT(0); return; }
        UT_ASSERT_P(isNullTerminated());
        UT_ASSERT_P(by_length >= 0);
        myLength -= by_length;
        UT_ASSERT(myLength >= 0);
        for (int i=0; i<myLength; i++)
            myBuffer[i] = myBuffer[by_length+i];
        myBuffer[myLength] = '\0';
    }

    const char *findChar(char c, int occurance_number = 1) const
    {
        // finds the first (or 'occurance_number'-th) char in the string.
        if (myLockCount) { UT_ASSERT(0); return NULL; }
        UT_ASSERT_P(isNullTerminated());
        int i;
        for(i=0; i<myLength; i++)
            if(c == myBuffer[i])
            {
                occurance_number--;
                if(occurance_number <= 0)
                    return myBuffer+i;
            }
        return NULL;
    }

    // Get the next token pointed at by string and advance string past the
    // token. Returns whether or not a token was retrieved successfully.
    // Note that string is modified!!!
    bool         getNextToken(const char *(&string),
                                const UT_String separators = " \t\n");

    // Harden the contents of the buffer into a UT_String.
    void         copyIntoString(UT_String &str);

    // Copy the contents into a fixed length buffer.
    // TODO: Get rid of this method, since it encourages fixed-length buffers.
    void         copyIntoString(char *str, int max_length);

    // Return a string containing the contents of this work buffer, preserving
    // any null characters in it.
    std::string toStdString() const
    { return std::string(buffer(), length()); }

    // Strips the characters after comment_char from the buffer.  This method
    // goes to some effort to enusre that the comment_char is not preceded by
    // a backslash or is not in a quoted string.  Returns true if it found a 
    // comment and modified the buffer, and false otherwise.
    bool         stripComments(char comment_char = '#');

    // Remove trailing whitespace lines
    void         removeTrailingSpaceLines();

    /// Convert string to lower case
    void         lower();

    /// Convert string to upper case
    void         upper();

    /// Create a string of tabs & spaces which represents the given indent
    void        makeIndentString(int indent, int tabstop=8);

private:
    friend UT_API ostream       &operator<<(ostream &os,
                                            const UT_WorkBuffer &buffer);

private:    // Data:

    char        *myBuffer;      // Do not make an access method to the data
    int          myAllocatedSize;
    int          myLength;

    int          myLockCount;

    char         myStackBuffer[UT_INITIAL_BUFFER_SIZE];
};

#endif

---