fixed-buffer.h

Go to the documentation of this file.

/*
 * fixed-buffer.h
 *
 * Copyright (C) 2009  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * 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.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''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 THOMAS A. VAUGHAN 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.
 *
 *
 * Templates to support fixed-size string buffers.
 */

#ifndef WAVEPACKET_UTIL_FIXED_BUFFER_H__
#define WAVEPACKET_UTIL_FIXED_BUFFER_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "common/wave_ex.h"


/// \ingroup util
/*@{*/



/// Template that supports strings of a fixed buffer size.
/// This class is most useful when you want to add a string to a struct or
/// class with a set size, and don't want to deal with memory allocations
/// using std::string.
///
/// You have to provide two classes to use a FixedBuffer template:
///  - \b Sizer This class contains the actual buffer, and a static
///             method named getBufferSize() which returns the full
///             buffer size (including null terminator).
///  - \b Validator This class contains a single static method, isValid().
///             This is used to validate each character during string
///             assignments.
///
/// Some example Sizers and Validators are included in this file.
template <class Sizer, class Validator>
class FixedBuffer {
public:
        // typedef
        typedef FixedBuffer<Sizer, Validator> buff_type_t;

        // constructors
        FixedBuffer(void) throw() { this->clear(); }
        FixedBuffer(IN const buff_type_t& inbuf) throw() { m_t = inbuf.m_t; }
        FixedBuffer(IN const char * input) {
                        this->clear();
                        this->set(input); 
                }

        // manipulators and accessors
        void clear(void) throw() {
                        m_t.buffer[0] = 0; 
                        int Nmax = Sizer::getBufferSize() - 1;
                        m_t.buffer[Nmax] = 0;   // also put zero at end!
                }
        bool isEmpty(void) const throw() { return !m_t.buffer[0]; }
        bool operator ! () const throw() { return this->isEmpty(); }
        operator const char * () const throw() { return m_t.buffer; }
        operator bool () const throw() { return !this->isEmpty(); }

        /// set() will take an arbitrary string, and assign it to the fixed
        ///  buffer.
        /// There are two passes over the input string: once to validate, and
        ///  once to copy.  This is slightly inefficient, but guarantees that
        ///  the fixed buffer string is never corrupted by bad input.
        /// An input string is considered invalid if it is longer than the
        ///  fixed buffer can hold, or if it contains invalid characters.
        /// If the input is invalid, this routine will throw an exception.
        void set(IN const char * val) {
                        ASSERT(val, "null");

                        const char * q = val;   // source
                        int Nmax = Sizer::getBufferSize() - 1;

                        // first pass: check validity of input
                        for (int i = 0; i < Nmax; ++i, ++q) {
                                if (!*q)
                                        break;          // end of input
                                if (!Validator::isValid(*q)) {
                                        WAVE_EX(wex);
                                        wex << "input string contains ";
                                        wex << "invalid characters: '";
                                        wex << val << "'";
                                }
                        }
                        if (*q) {
                                WAVE_EX(wex);
                                wex << "input string too long! '" << val << "'";
                        }

                        // second pass: input is valid, so copy
                        char * p = m_t.buffer;  // destination
                        q = val;                // source (reset)
                        for (; *q; ++p, ++q) {
                                *p = *q;
                        }
                        *p = 0;         // force null-termination
                }
 
private:
        Sizer   m_t;
};



/// a validator that allows anything
class NullValidator {
public:
        static bool isValid(IN char a) throw() { return true; }
};



/// a validator that allows alphanumerics only
class AlphanumericValidator {
public:
        static bool isValid(IN char a) throw() {
                        return ((a >= 'a' && a <= 'z') ||
                                (a >= 'A' && a <= 'Z') ||
                                (a >= '0' && a <= '9'));
                }
};



/// a validator that allows a subset of characters thought
/// to be useful in filepaths.  Note that this is somewhat
/// restrictive.
class CommonFileValidator {
public:
        static bool isValid(IN char a) throw() {
                        return ((a >= 'a' && a <= 'z') ||
                                (a >= 'A' && a <= 'Z') ||
                                (a >= '0' && a <= '9') ||
                                '/' == a || '.' == a ||
                                '-' == a || '_' == a);
                }
};



/// an example sizer that allows strings of up to 31 characters
/// (so the buffer itself is 32 characters)
class ThirtyTwoCharacterSizer {
public:
        static int getBufferSize(void) throw() { return 32; }
        char buffer[32];
};



#endif  // WAVEPACKET_UTIL_FIXED_BUFFER_H__