string-buffer.h

Go to the documentation of this file.
00001 /*
00002  * string-buffer.h
00003  *
00004  * Copyright (C) 2010 Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * A way to store many strings all in a single contiguous buffer.
00032  */
00033 
00034 #ifndef WAVEPACKET_STRING_BUFFER_H__
00035 #define WAVEPACKET_STRING_BUFFER_H__
00036 
00037 
00038 // includes --------------------------------------------------------------------
00039 #include "common/common.h"
00040 #include "threadsafe/smart_ptr.h"
00041 
00042 
00043 /// \ingroup util
00044 /*@{*/
00045 
00046 
00047 ////////////////////////////////////////////////////////////////////////////////
00048 //
00049 //      StringBuffer interface
00050 //
00051 //      The use case is to repeatedly call appendString() to add strings to the
00052 //      buffer, and keep track of the offsets as they are returned.  You can
00053 //      always look up appended strings again using their offset.  The internal
00054 //      buffer will be resized as needed.
00055 //
00056 ////////////////////////////////////////////////////////////////////////////////
00057 class StringBuffer {
00058 public:
00059         // public structs and typedefs -----------------------------------------
00060         struct iterator_t {
00061                 byte_t  opaque[8];
00062         };
00063 
00064         // virtual destructor --------------------------------------------------
00065         virtual ~StringBuffer(void) throw();
00066 
00067         // StringBuffer class interface methods --------------------------------
00068 
00069         /// appends the given string to the end of the buffer, and returns the
00070         ///     offset into the buffer.
00071         virtual int appendString(IN const char * string) = 0;
00072 
00073         /// given an offset, returns the string
00074         virtual const char * getString(IN int offset) const throw() = 0;
00075 
00076         /// initialize an iterator to the beginning of the list of strings
00077         virtual void getIterator(OUT iterator_t& i) const throw() = 0;
00078 
00079         /// retrieve the current string, and advance the iterator.  Returns NULL
00080         ///     at the end.  Note that iterators remain valid even if
00081         ///     appendString() is repeatedly called and increases the buffer.
00082         /// However, iteration is NOT threadsafe.
00083         virtual const char * getNextString(IO iterator_t& i) const throw() = 0;
00084 
00085         /// for diagnostics: runs through and writes all strings to stream
00086         virtual void dumpStrings(IO std::ostream& stream) const = 0;
00087 
00088         // static factory methods ----------------------------------------------
00089         static smart_ptr<StringBuffer> create(IN int initialBytes = 4096);
00090 };
00091 
00092 
00093 #endif  // WAVEPACKET_STRING_BUFFER_H__
00094