str.doc

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

            str         tempstr;
            ifstream    input("myfile.txt");

            while(!input.rdstate())
            {
                    // Clear the string and read next line
                input >> tempstr.clear();
                    // Process the string ...

    str & operator= (str const & s);
    str & operator= (char const * s);
    str & operator= (char c);
    str & operator= (unsigned char const * s);
    str & operator= (signed char const * s);

        Assignment operators do pretty much the same as the
        constructors noted above.

        Assignment operators for integral conversions are not
        provided simply because this is already taken care of
        by constructors, and their functionality would be
        otherwise duplicated. To assign an integral type,
        therefore, simply cast the right hand side first:

            str     myintstr;

            myintstr = str(10);

        This also allows specification of a radix if desired
        and does pretty much what would otherwise occur
        internally anyway.

    short length (void) const;

        Returns the length of the string, simply by reading
        the field in the contained reference string.

            str result = "The string 'rest' is exactly ";
            str rest   = " characters long";

            result << rest.length() << rest;
            // 'The string 'rest' is exactly 16 characters long'

    short size (void) const;

        This returns the internal size of the string - ie.
        the maximum number of characters (less 1) which can
        be assigned to the string before it needs to be
        reallocated.

        This is usually of little or no value to the user of
        the str class as strings are grown to accommodate.
        However, it may be helpful in some circumstances for
        optimisation purposes.

    str & operator<< (char const * s);
    str & operator<< (unsigned char const * s);
    str & operator<< (signed char const * s);
    str & operator<< (str const & s);
    str & operator<< (int val);
    str & operator<< (unsigned int val);
    str & operator<< (short val);
    str & operator<< (unsigned short val);
    str & operator<< (long val);
    str & operator<< (unsigned long val);
    str & operator<< (char c);
    str & operator<< (unsigned char c);
    str & operator<< (signed char c);

        These operators provide string concatenation. Values
        on the right hand side of a << operation are appended
        to the end of the string, much like stream insertion
        operators. Integral types larger than char may also
        be concatenated and are automatically converted to
        str prior concatenation.

            str mystr "Now is the ";

            mystr << "time for all good men.\n"
                  << 10 << " times " << 10 << '=' << 100;


    char const & operator[] (short pos) const;
    char & operator[] (short pos);

        The subscript operators provides a way of referencing
        individual characters within a str object, similar to
        usual C string semantics. There are, however, some
        differences:

            Negative indices in the range -length() to -1
            allows reference to character positions
            calculated from the end of the string, for
            example mystr[-1] addresses the last character in
            the string, mystr[-2] addresses the character
            previous to that etc.

            For the const operator (used on the rhs of an
            expression) indices specified which are outside
            of the allowed range of -length() to length()
            return a reference to the character position at
            length(), ie. the end of the string.

            The non-const operator (used on the lhs of an
            assignment) indices specified which are outside
            the range of -length() to length() cause the
            string to be extended and space padded.

    char * c_ptr() const;
    char const * c_str() const;
    unsigned char const * u_str() const;
    signed char const * s_str() const;

        These members provide direct pointers to the string
        data itself. They are only guaranteed to remain valid
        while the string itself remains unmodified!

        c_ptr() does not NUL terminate the string and returns
        a non-const pointer, and therefore may be used to
        modify the string. The responsibility for ensuring
        that memory outside of that owned by the string is
        entirely the programmers'. This function is
        particularly useful in manipulation of binary strings.

            str     mybinstr;

            mybinstr.left(10,0);
                // Grows string to 10 bytes, zero filled.
            mybinstr.c_ptr()[3] = 6;
                // places 6 (^F) into the 4th position
                // This is equivalent to mybinstr[3] = 6,
                // however in some contexts, c_ptr() may
                // be simpler to deal with (for example when
                // using memcpy() to fill the string

        c_str(), u_str() and s_str() provide const pointers
        to the string in order to allow its use as a normal C
        string. c_str() returns a const pointer to char, the
        sign of which is implementation defined, u_str()
        returns a pointer to unsigned char, and s_str()
        returns a pointer to signed char.

        It cannot be emphasised enough that care must be
        taken by the user of these members that a string is
        NOT TO BE MODIFIED IN ANY WAY while a pointer
        returned by any of them is in use. Modification of
        the string may well cause it's relocation in memory,
        and any pointer will be left undefined. To avoid this
        deficiency, a method of 'freezing' the string (a la
        strstreams) was considered; however, this is
        generally less convenient and leads to clumsy syntax
        in most situations, and the existence of this caveat
        was considered to be the best compromise. For this
        reason also no automatic conversion to "char const *"
        has been implemented since the compiler would then be
        provided with a means of extracting a "char const *"
        whenever it wished, making it much less easy to guard
        against.

            void
            func(str mystr);
            {
                char    myarray[128];

                strncpy(myarray, mystr.c_str(), 127);
                myarray[127] = '\0';
                // ...


    int copy(char * dest, short maxlen =-1) const;

        This member allows a convenient way of copying a str
        object into a char array. 'maxlen' specifies the
        maximum length of the destination array - you would
        be well advised to use this. The default value of -1
        causes the length to be disregarded and the length of
        the contained string used instead.

        After copying, the destination string is guaranteed
        to be NUL terminated. If maxlen is specified, then up
        to maxlen-1 characters are copied to the memory
        location pointed to by 'dest' and a terminating NUL
        added. If the str object is less than (maxlen-1)
        characters long, the terminating NULL will be placed
        at dest+length().

        str::copy() should be used in preference to
        str(n)copy and str::c_str() as it will almost always
        be more efficient, and provides the functionality of
        strncpy() without the need to explicitly terminate
        the string with NUL. Compare the following to the
        previous example for c_str().

            void
            func(str mystr)
            {
                char    myarray[128];

                mystr.copy(myarray, 128);
                // ...

    short insert (short pos, char const * s, short len =-1);
    short insert (short pos, str const & s);
    short insert (short pos, unsigned char const * s, short len =-1);
    short insert (short pos, signed char const * s, short len =-1);
    short insert (short pos, char c);
    short insert (short pos, unsigned char c);
    short insert (short pos, signed char c);

        Insertion operators provide a way to safely insert
        other strings (C strings or str objects) into a str
        object. 'pos' is specified as the number of bytes
        offset from the start of the string. Any negative
        value of pos or values which exceed the current
        length of the string causes concatenation to the end
        (ie. insertion after the last character).

        For insertion of C strings, the len argument provides
        the ability to insert only a portion of a string. If
        the default argument or -1 is used, the NUL
        terminator will be used instead to determine the
        source string length.

            str mystr("time for all good men.");

            mystr.insert(0,"Now is the ");
                // 'Now is the time for all good men.'

    short remove (short pos =0, short len =-1);

        The str::remove() member provides the ability to
        excise a portion of a string. If used with the
        default arguments, the string is entirely cleared
        (but not reallocated so, like str::clear(), the
        memory allocated to the string is left the same).
        'pos' defaults to 0, being the start of the string.
        len's default value of -1 causes the string's length
        to be used, in which case all characters at and
        following the position 'pos' are removed.

            str mystr = "The quick brown fox jumps over the lazy dog";

            mystr.remove(10, 6);
                // 'The quick fox jumps over the lazy dog'
            mystr.remove(19);
                // 'The quick fox jumps'
            mystr.remove();
                // '' - blank.

    short replace (short pos, char const * s, short clen =-1, 
                                                          short len =-1);
    short replace (short pos, str & s, short clen =-1);
    short replace (short pos, unsigned char const * s, short clen =-1, 
                                                          short len =-1);
    short replace (short pos, signed char const * s, short clen =-1,
                                                          short len =-1);
    short replace (short pos, char c, short clen =-1);
    short replace (short pos, unsigned char c, short clen =-1);
    short replace (short pos, signed char c, short clen =-1);

        These members do the equivalent of str::remove() and
        str::insert() in one operation. 'pos' specifies the
        position at which replacement is to start, 'clen'
        specifies the number of characters to replace in the
        original string (ie. how many to remove before
        inserting), 's' (or 'c') is the string to insert, and
        where applicable, 'len' is the number of characters
        from 's' which are to replace the characters removed.
        If 'len' is -1, then the number of characters used is
        determined by the NUL terminator in 's' (ie. the
        result of strlen()). If 'clen' is -1, then all
        characters up until the end of the string are replaced.

        Using str::replace() is far more efficient than using
        remove() then insert().

            str mystr = "The quick brown fox jumps over the lazy dog".

            mystr.replace(10, "black", 5);
                // 'The quick black fox jumps over the lazy dog'

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

        These members mutate the string and provide string
        truncation and padding.

        Firstly, please note that these functions do NOT work
        in the same manner as the BASIC style string
        functions of the same name. The functionality is
        similar, but certainly not identical.

        These functions, left() and right() in particular,
        will probably be used mostly for string formatting.
        There are non-member functions of the same name
        ::left(str, len, pad) and ::right(str, len pad) which
        provide the same functionality, but rather than
        mutating the string itself, instead returns a copy of
        the original string appropriately modified.

        While these functions will truncate a string if the
        string()'s length exceeds 'len', they will also pad
        the string with 'padch' to extend it to 'len' if it
        is shorter. The left() member extends the string on
        the right hand side while the right() member extends
        it to the left(). mid() removes any characters to the
        left of the starting position and from that point
        works pretty much like left(), padding on the right
        if required.

            str mystr = 2000;

            cout << "There are " << mystr.right(8) << " pieces;
                // Output:
                // 'There are     2000 pieces'
            str name = "David Nugent"
            str addr = "[e-mail]"
            str fund = 0;

            cout << left(name, 25)
                 << left(addr, 32)
                 << right(fund, 8)
                 << endl;
                    // Output padded appropriately.
                    // Note that by using the global functions,
                    // the original string remains unmodified

    str substr(short start, short len =-1) const;

        substr() returns a substring, much like mid() except
        that no padding is provided. substr() in fact
        provides similar functionality to BASICS's left(),
        right() and mid() in one function.

        If 'start' is negative, the actual starting position
        is calculated from the end of the string, otherwise
        the offset is from the left. If 'len' is negative or
        larger than the length of the string, all characters
        to the right of the specified start position are
        returned in the resulting string. The returned string
        is never padded.

            str mystr = "This shows how the str::substr() member works";

            cout << "mystr.substr(19,13)=" << mystr.substr(19,13)
                 << '\n'                    // 'str::substr()'
                 << "mystr.substr(41)=" << mystr.substr(41)
                 << '\n'                    // 'works'
                 << "mystr.substr(-5)=" << mystr.substr(-5)
                 << endl;                   // 'works'