str.doc

C语言库函数的源代码,是C语言学习参考的好文档。

    short removech (char const * clist ="\r\n");

        This member provides a convenient method of removing
        all occurrences of a set of characters from a string.
        The default character list removes end of line
        characters. The value returns represents the number
        of characters removed (ie. the amount by which the
        length has been decreased).

            str mystr = "Testing\n";

            mystr.removech();           // 'Testing'
            mystr.removech("ing");      // 'Test'

    short countch (char const * clist);

        str::countch() returns the number of times any
        character from the supplied character list occurs in
        the string. This can be used to test the presence of
        one or more characters.

            str mystr = "testing\n";

            cout << "The letter 't' appears in '"
                 << mystr << "' " << mystr.countch("t") << " times."
                 << endl;

    bool operator== (str const & s) const;
    bool operator== (char const * s) const;
    bool operator== (unsigned char const * s) const;
    bool operator== (signed char const * s) const;
    bool operator!= (str const & s) const;
    bool operator!= (char const * s) const;
    bool operator!= (unsigned char const * s) const;
    bool operator!= (signed char const * s) const;
    bool operator< (str const & s) const;
    bool operator< (char const * s) const;
    bool operator< (unsigned char const * s) const;
    bool operator< (signed char const * s) const;
    bool operator<= (str const & s) const;
    bool operator<= (char const * s) const;
    bool operator<= (unsigned char const * s) const;
    bool operator<= (signed char const * s) const;
    bool operator> (str const & s) const;
    bool operator> (char const * s) const;
    bool operator> (unsigned char const * s) const;
    bool operator> (signed char const * s) const;
    bool operator>= (str const & s) const;
    bool operator>= (char const * s) const;
    bool operator>= (unsigned char const * s) const;
    bool operator>= (signed char const * s) const;
    int compare (str const & s) const;
    int compare (char const * s) const;
    int compare (unsigned char const * s) const;
    int compare (signed char const * s) const;

            [The 'bool' value returned by these functions
            represents the boolean type passed recently by
            the ANSI C++ committee - if not supported by your
            compiler yet, it must be #defined explicitly. The
            'bool' type has two possible values; False or
            True - False is zero, True is non-zero. Unless
            supported by the compiler, a bool value should
            never be directly tested against 'True' as this
            will often provide erroneous results where 'True'
            has been defined as a specific non-zero value.]

        These functions provide basic string comparison
        functionality. The basic compare() function returns
        values comparable with strcmp() or stricmp(),
        depending on the setting of the internal "case
        sensitivity" flag maintained for each string.

        static void setdefaultcase (bool s = True);

        By default, each string is case sensitive. A static
        member function provides the ability to set the
        default flags for each string (currently only ICASE -
        case insensitivity - is implemented), and will be
        applied to all strings created after this is called.

        void setcase (bool s =True);

        Case sensitivity can be enabled or disabled for
        individual strings by using str::setcase().
        setcase(True) makes the string case sensitive - this
        is normally the default, depending on whether the
        set::setdefaultcase() function has been used - and
        setcase(False) makes the string case INsensitive. In
        comparing strings, if either one of the strings
        compared is flagged as case insensitive, the
        comparison is case insensitive. If both strings are
        flagged as case sensitive, then the comparison is
        case sensitive.

        Any of the str::compare() overloads returns a value <
        0 if the current string is compares less than the
        string argument, 0 if they are equal and >0 if the
        string argument is greater than the current string.
        If the comparison is case insensitive, the precise
        value of comparisons for strings commencing with
        ASCII values between 'Z' and 'a' (not inclusive)
        depend on your vendor library's implementation of
        stricmp(), specifically depending on whether strings
        are converted to upper or lower case before
        comparison of individual characters.

        The comparison operators ==, !=, <, >, >= and <= are
        provided as short-hand notations of the built-in
        str::compare() member.

            str mystr1("Hello WORLD!");
            str mystr2("HELLO world!");

            if (mystr1 != mystr2)
                cout << "Comparison is case sensitive" << endl;
            else
                cout << "Comparison is case insensitive" << endl;

            mystr1.setcase(False);  // Turn case sensitivity off

            if (mystr1 == mystr2)
                cout << mystr1 << " = " << mystr2 << endl;
            if (mystr1 > "abcdef")
                cout << mystr1 << " is greater than abcdef" << endl;

    short strstr (str const & s) const;
    short strstr (char const * s) const;
    short strstr (unsigned char const * s) const;
    short strstr (signed char const * s) const;

        This group of str::strstr() overloads provides a way
        of doing simple substring searches within a str
        object. As with comparison, the case of substrings is
        determined by the case sensitivity of the string
        being searched, and in the case of strstr(str const
        &) also the case sensitivity of the substring being
        searched for.

        While similar to the stdc library strstr, this
        function returns the offset at which the substring is
        found rather than a pointer to the found string - if
        a pointer to the located string is desired, add the
        offset to the return from c_str().

        A return value of -1 indicates that the substring was
        not located - anything else is the offset at which
        the substring starts.


    PROTECTED INTERFACE

    This section deals with functions and data members
    accessible from derived classes.

    In deriving classes from class str, please note the
    comments in the above section "GENERAL STRUCTURE" which
    deal with the issue of class str's virtual (or not)
    destructor, and check the #define at the top of str.h. If
    the destructor is defined as a virtual function, then you
    can freely use and upcast a derived class to a str. If
    not, then you should be careful how you deal with strings
    classes derived from str, and if you upcast to class str,
    ensure either that your derived class needs no destructor
    to clear and deallocate resources, or that you implement
    some means of garbage collecting for your derived class
    (eg. use some form of resource tracking). The choice of
    whether to make the destructor virtual or not is yours -
    it is the only virtual function that is used in class
    str, so consequently derived classes from str will
    normally only add functionality rather than any serious
    attempt at using polymorphism. str was not created with
    polymorphism in mind.

    The protected interface of class str provides complete
    access to the str object, including refstr, internal
    reference string and members. Provided the user obey
    certain rules, there should be no problem with this.
    These rules are:

    o   A refstr is not exclusively "owned" by a string object
        unless the reference count in the refstr is equal to
        1. Mutation or modification of ANY sort of the refstr
        pointed to by the strdata member must be guarded
        against by a call to the protected member _chksize.
        THIS MEANS ANY CHANGE WHATSOEVER NO MATTER HOW TRIVIAL.

    o   If you intend to append or insert data into the current
        string, then you can call _chksize(?), where ? is the
        final size you intend to use. As well as allocating a
        new refstr object if the reference count exceeds on
        and copying the old data to the new refstr,
        _chksize() will ensure that the string data size is
        large enough to accommodate anything that you wish to
        do with it.

    o   When calling _chksize(), _never_ assume that any internal
        pointer to data will remain valid across the call.
        Either work with offsets only instead, or convert any
        pointers to offsets from the previous start of string
        to offsets and back again into pointers. One example
        of this being done can be found in the implementation
        of str::removech() in str.cpp.

    o   If you use _chksize() with a size, add 1 to the size
        requested to ensure that the refstr is at least large
        enough to hold one additional byte beyond the string
        data itself. This additional byte allows for addition
        of a NUL for conversions to char const* without
        causing reallocations.

    o   Avoid calling _chksize() unless you really are going to
        modify the string. Since _chksize() ensures mutually
        exclusive ownership of the string data by the current
        string object, it is pointless to cause loss of CPU
        cycles and memory when in fact nothing is done. Once
        the enclosed refstr is owned by a str object,
        however, calling _chksize() causes little overhead
        except when the string needs to be resized.

    o   _strinit() (either overload) needs to be used with care.
        Don't call these unless you intend deallocating the
        current strdata and have saved it, or have already
        deallocated strdata - it is over-written and never
        deallocated. The deallocation is entirely your
        responsibility.

    static unsigned short default_flags;

        default_flags is the value passed to _strinit() during
        string setup. You can override these flags if you
        need to by calling _strinit() directly.

    refstr * strdata;

        strdata is the member which contains the address of the
        reference string, which is in fact the internal
        string entity which may be shared by multiple 'str'
        objects. Before modifying this, or modifying the
        object it points to, refer to the discussion
        immediately before this.

    int _chksize (short sz =0);

        _chksize() forms pretty much the core of what manages
        refstr() objects (_strinit() creates them, this
        manages). _chksize() is responsible for two things:

            Once called during management of a str, _chksize()
            ensures that the str has it's very own refstr
            pointed to by strdata. This allows code to modify
            the string without causing side- effects on other
            strs which happen to reference the same data.

            _chksize() also does as its name implies - checks
            the size of the refstr to ensure that it is large
            enough to contain at least the number of bytes
            stated by its parameter.

    int _concat (char const * s, short len =-1);

        This is the fundamental string concatenation routine.
        All concatenation operators end up passing through
        this one after conversion to char const*.

        Note that a serious limitation in using this function
        in the previous release of this class has been
        removed - _concat() now checks to see if the pointer
        passed references it's own data (full string or
        substring), and if so, first copies that substring
        before performing the concatenation to ensure that
        the pointer 's' remains valid. It is therefore now
        possible to concatenate a string (or substring
        thereof) it itself.

    int _compare (str const s) const;

        This is the fundamental string compare function.
        Comments regarding the public interface for
        str::compare() above apply.

    short _strstr (str const s) const;

        This is the fundamental substring search function.
        Comments regarding the public interface for
        str::_strstr() apply.

    void _strinit (char const * s =0, short slen =0, short siz =-1,
                               unsigned short flgs =default_flags);
    void _strinit (unsigned long val, bool positive, int radix);

        These functions are the initial allocators for new
        refstr objects. The first is called by the second,
        and optionally allows a string to be initialised or
        set to a specific length according to the caller's
        requirements. The second _strinit() overload is for
        integral conversions. If signed numbers are passed to
        this function, you should already have converted them
        to absolute values and passed the sign in the boolean
        'positive' (True if positive, otherwise negative).
        'radix' is the base of the number used during the
        conversion.

    GLOBAL FUNCTIONS

    str.h contains prototypes for several functions defined at file
    scope with deal with strings. The philosophy used is that member
    functions are generally used to mutate a string, but the global
    equivalents of the same name return a new string, copied from the
    old and mutated, leaving the original str object untouched.

    In addition, iostream insertion and extraction operators provides
    a simple, intuitive and straight-forward interface to the iostreams
    library.

    str left (str s, short len, char padch =' ');
    str right (str s, short len, char padch =' ');
    str mid (str s, short pos, short len, char padch =' ');

        These are inline equivalents for the member functions of the same
        name. Each returns a mutation of the original string. Typically
        these are used for temporary formatting for streams etc.

            str mystream(100);

            cout << "      Cost Total\n"
                 << right(mystream, 10)
                 << ' '
                 << left(mystream, 10)
                 << endl;

    int compare(str s, str b);
    int compare(str s, char const * b);
    int compare(str s, unsigned char const * b);
    int compare(str s, signed char const * b);

        These provide comparison functions, and in some contexts
        may be easier to use than the str.compare() overloads.

    ostream & operator<< (ostream & os, str const & s);
    istream & operator>> (istream & is, str & s);

         These are the iostream interface operators. operator>>
         extracts a line of text from an input stream, removing
         the newline, if any. The string is automatically grown
         to accommodate input but will not shrink for smaller
         lines. Contents of the string prior an extraction
         operation are discarded.

         The insertion operator<< outputs the contents of the
         string, assumed to be a NUL terminated C string, to
         the stream.