//////////////////////////////////////
// START of File: C0_DYSTR.HPP
//////////////////////////////////////

#ifndef C0_DYSTR_HPP
#define C0_DYSTR_HPP    TRUE    // Std C++ multiple include protection...

//-------------------------------------------------------------------
// COPYRIGHT NOTICE:  This code is protected by Copyright!
//
// Copyright (c) 1994 through 1997 by DPC Technology Corporation.
// All rights reserved. 
//
// See files "cf_copyr.txt" and "cf_licen.txt" for details of 
// copyright and license specifications, and contact information.
//-------------------------------------------------------------------

//-----------------------------
// Master Header File Listing:
//-----------------------------
// Usage:   #include    <api/include/c0_dystr.hpp>
            // "Dynamic String" objects (independent of any base framework).


//---------------------------------------------------------
// Specify use of ANY base class, framework, or libraries:
//---------------------------------------------------------
#include    <stdio.h>
            // cpp source file calls sprintf(), etc functions...

#include    <string.h>
            // cpp source file calls strcmp(), strcpy(), etc. functions...

//-------------------------------------------------------------------
// Specify applicable constants, typedefs, etc. used by this object:
//-------------------------------------------------------------------
#define     C0_DYSTR_BUFFSIZE        10
            // Define default array size(s) for char array
            // buffers associated with printf operations, etc.
            // You can tweak this if you need to, but you should
            // really use the preferBuffSize(...) method below...


class CF_EXPORT   cf_String
//================================================================
// ...a dynamic-string object INDEPENDENT of any Base Framework.
// This object WILL use the std C lib's sprintf() functionality,
// and will have auto-formatting capabilities that mirror std
// sprintf() functionality.  This object will also use other
// std C lib string functions such as strcpy, strcat, etc.
//================================================================
{

public:

    cf_String();// Default c-tor for dynamic arrays. etc.

    cf_String(  cf_String &cr_cfsSource );  // Copy-ctor.

    cf_String(  const char *p_cSource );
    // Makes a dynamic-string from a constant char* null-terminated
    // string param like "my string" into an encapsulated null-
    // terminated char array string.

    cf_String(  const double    dUserVal,
                const char*     ca_cFormatString = "%g",
                const int       iBufferSize = C0_DYSTR_BUFFSIZE );
    // Makes a dynamic-string by converting a constant double param
    // such as 1.2 to a null-terminated string constant like "1.2".
    // User can also specify the sprintf() conversion format of the value.
    // User can also over-ride the buffer size allocation (if neccessary).

    cf_String(  const int       iUserVal,
                const char*     ca_cFormatString = "%d",
                const int       iBufferSize = C0_DYSTR_BUFFSIZE );
    // Makes a dynamic-string by converting a constant int param
    // such as 10 to a null-terminated string constant like "10".
    // User can also specify the sprintf() conversion format of the value.
    // User can also over-ride the buffer size allocation (if neccessary).

    ~cf_String();// Std (non-virtual) d-tor.

    operator    char*() const;
		        // Yields this dynamic string's char*
                // Note that "const" implements a "read-only" method
                // and ALSO allows this method to be called on this
                // object when it gets passed as a const ref param
                // (e.g.in this object's operator=()...

    void        operator=( const cf_String  &cr_cfsSource );
    void        operator=( const char       *a_cNullTerminatedString );
                // These assigments ops mirror their respective c-tor
                // counterparts, and attempt to isolate ALL sprintf()
                // functionality into this single class.

    void        operator&=( const char *a_cNullTerminatedString );
                // String append operator are widely used throughout
                // the framework.  Value append ops are specified below...

    void        cf_append(  const double    dUserVal,
                            const char*     ca_cFormatString = "%g",
                            const int       iBufferSize = C0_DYSTR_BUFFSIZE );
                // Appends onto the dynamic-string by using standard string
                // library sprintf() functionality to convert a constant
                // double param such as 1.2 to a null-terminated string
                // constant like "1.2".  Note that these method(s) also
                // enable a RESET sequence via: op="", and cf_append(...).

    void        cf_append(  const int       iUserVal,
                            const char*     ca_cFormatString = "%d",
                            const int       iBufferSize = C0_DYSTR_BUFFSIZE );
                // Appends onto the dynamic-string by using standard string
                // library sprintf() functionality to convert a constant
                // int param such as 10 to a null-terminated string constant
                // like "10".  Note that these method(s) also enable a
                // RESET sequence via: op="", and cf_append(...).

    int         cf_strlen() const;
                // User classes will want to know the length of
                // this string (especially if it == "" or not)...
                // Note that "const" implements a "read-only" method
                // and ALSO allows this method to be called on this
                // object when it gets passed as a const ref param
                // (e.g. in this object's operator=()...).  Note also
                // that strlen() returns a value equal to the current
                // buffer size minus one.

    void        reset();
                // Resets this dynamic string to "".  Any current conversion
                // buffer size specification (via preferBuffSize(...) above)
                // remains in effect.

private:

    char        *p_cContent_;       // Where we start from -- points to...
    int         iCurrBuffSize_;     // ...what we REALLY have allocated!
    int         iCurrStrLen_;       // ...of which PART (indeed maybe up to
                                    // all!) is the strings "text content".

};  //  End of cf_String Declaration.

#endif

//////////////////////////////////////
// END of File: C0_DYSTR.HPP
//////////////////////////////////////

