string_.gml

开放源码的编译器open watcom 1.6.0版的源代码

:P.
This class is used to store arbitrarily long sequences of characters in
memory.
Objects of this type may be concatenated, substringed, compared and
searched without the need for memory management by the user.
Unlike a C string, this object has no delimiting character, so any character
in the collating sequence, or character set, may be stored in an object.
:P.
The class documented here is the Open Watcom legacy string class. It
is not related to the
:MONO.std::basic_string
class template nor to its corresponding specialization
:MONO.std::string.
.*
:CLFNM.String
:CMT.========================================================================
:LIBF fmt='hdr'.String
:HFILE.string.hpp
:CLSS.
The &cls. is used to store arbitrarily long sequences of characters in memory.
Objects of this type may be concatenated, substringed, compared and
searched without the need for memory management by the user.
Unlike a C string, a &obj. has no delimiting character, so any character
in the collating sequence, or character set, may be stored in a &obj.:PERIOD.
:HDG.Public Functions
The following constructors and destructors are declared:
:MFNL.
:MFCD cd_idx='c'.String();
:MFCD cd_idx='c'.String( size_t, capacity );
:MFCD cd_idx='c'.String( String const &, size_t = 0, size_t = NPOS );
:MFCD cd_idx='c'.String( char const *, size_t = NPOS );
:MFCD cd_idx='c'.String( char, size_t = 1 );
:MFCD cd_idx='d' .~~String();
:eMFNL.
The following member functions are declared:
:MFNL.
:MFN index='operator char const *'.operator char const *();
:MFN index='operator char'        .operator char() const;
:MFN index='operator ='           .String     &amp.operator  =( String const & );
:MFN index='operator ='           .String     &amp.operator  =( char const * );
:MFN index='operator +='          .String     &amp.operator +=( String const & );
:MFN index='operator +='          .String     &amp.operator +=( char const * );
:MFN index='operator ()'          .String      operator ()( size_t, size_t ) const;
:MFN index='operator ()'          .char       &amp.operator ()( size_t );
:MFN index='operator []'          .char const &amp.operator []( size_t ) const;
:MFN index='operator []'          .char       &amp.operator []( size_t );
:MFN index='operator !'           .int         operator  !() const;
:MFN index='length'               .size_t length() const;
:MFN index='get_at'               .char const &amp.get_at( size_t ) const;
:MFN index='put_at'               .void        put_at( size_t, char );
:MFN index='match'                .int    match( String const & ) const;
:MFN index='match'                .int    match( char const * ) const;
:MFN index='index'                .int    index( String const &, size_t = 0 ) const;
:MFN index='index'                .int    index( char const *, size_t = 0 ) const;
:MFN index='upper'                .String upper() const;
:MFN index='lower'                .String lower() const;
:MFN index='valid'                .int    valid() const;
:MFN index='alloc_mult_size'      .int    alloc_mult_size() const;
:MFN index='alloc_mult_size'      .int    alloc_mult_size( int );
:eMFNL.
The following friend functions are declared:
:RFNL.
:RFN index='operator =='          .friend int    operator ==( String const &, String const & );
:RFN index='operator =='          .friend int    operator ==( String const &,   char const * );
:RFN index='operator =='          .friend int    operator ==(   char const *, String const & );
:RFN index='operator =='          .friend int    operator ==( String const &,   char         );
:RFN index='operator =='          .friend int    operator ==(   char        , String const & );
:RFN index='operator !='          .friend int    operator !=( String const &, String const & );
:RFN index='operator !='          .friend int    operator !=( String const &,   char const * );
:RFN index='operator !='          .friend int    operator !=(   char const *, String const & );
:RFN index='operator !='          .friend int    operator !=( String const &,   char         );
:RFN index='operator !='          .friend int    operator !=(   char        , String const & );
:RFN index='operator <'           .friend int    operator  <( String const &, String const & );
:RFN index='operator <'           .friend int    operator  <( String const &,   char const * );
:RFN index='operator <'           .friend int    operator  <(   char const *, String const & );
:RFN index='operator <'           .friend int    operator  <( String const &,   char         );
:RFN index='operator <'           .friend int    operator  <(   char        , String const & );
:RFN index='operator <='          .friend int    operator <=( String const &, String const & );
:RFN index='operator <='          .friend int    operator <=( String const &,   char const * );
:RFN index='operator <='          .friend int    operator <=(   char const *, String const & );
:RFN index='operator <='          .friend int    operator <=( String const &,   char         );
:RFN index='operator <='          .friend int    operator <=(   char        , String const & );
:RFN index='operator >'           .friend int    operator  >( String const &, String const & );
:RFN index='operator >'           .friend int    operator  >( String const &,   char const * );
:RFN index='operator >'           .friend int    operator  >(   char const *, String const & );
:RFN index='operator >'           .friend int    operator  >( String const &,   char         );
:RFN index='operator >'           .friend int    operator  >(   char        , String const & );
:RFN index='operator >='          .friend int    operator >=( String const &, String const & );
:RFN index='operator >='          .friend int    operator >=( String const &,   char const * );
:RFN index='operator >='          .friend int    operator >=(   char const *, String const & );
:RFN index='operator >='          .friend int    operator >=( String const &,   char         );
:RFN index='operator >='          .friend int    operator >=(   char        , String const & );
:RFN index='operator +'           .friend String operator  +(       String &, String const & );
:RFN index='operator +'           .friend String operator  +(       String &,   char const * );
:RFN index='operator +'           .friend String operator  +(   char const *, String const & );
:RFN index='operator +'           .friend String operator  +(       String &,   char         );
:RFN index='operator +'           .friend String operator  +(   char        , String const & );
:RFN index='valid'                .friend int valid( String const & );
:eRFNL.
The following I/O Stream inserter and extractor functions are declared:
:RFNL.
:RFN index='operator >>'.friend istream &amp.operator >>( istream &, String & );
:RFN index='operator <<'.friend ostream &amp.operator <<( ostream &, String const & );
:eRFNL.
:eCLSS.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.alloc_mult_size
:SNPL.
:SNPFLF                      .#include <string.hpp>
:SNPFLF                      .public:
:SNPF index='alloc_mult_size'.int String::alloc_mult_size() const;
:SNPF index='alloc_mult_size'.int String::alloc_mult_size( int mult );
:eSNPL.
:SMTICS.
The &fn. is used to query and/or change the allocation multiple size.
:P.
The first form of the &fn. queries the current setting.
:P.
The second form of the &fn. sets the value to a multiple of 8 based on the
:ARG.mult
parameter. The value of
:ARG.mult
is rounded down to a multiple of 8 characters. If
:ARG.mult
is less than 8, the new multiple size is 1 and allocation sizes are exact.
:P.
The scheme used to store a &obj. allocates the memory for the characters in
multiples of some size. By default, this size is 8 characters. A &obj.
with a length of 10 actually has 16 characters of storage allocated
for it. Concatenating more characters on the end of the &obj. only
allocates a new storage block if more than 6 (16-10) characters are
appended. This scheme tries to find a balance between reallocating
frequently (multiples of a small value) and creating a large amount of
unused space (multiples of a large value).
:RSLTS.
The &fn. returns the previous allocation multiple size.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.get_at
:SNPL.
:SNPFLF             .#include <string.hpp>
:SNPFLF             .public:
:SNPF index='get_at'.char const &amp.String::get_at( size_t pos );
:eSNPL.
:SMTICS.
.'se str_sub_pm='constant'
:INCLUDE file='str_subs'.
:SALSO.
:SAL typ='mfun'.put_at
:SAL typ='mfun'.operator~b[]
:SAL typ='mfun'.operator~b()
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.index
:SNPL.
:SNPFLF            .#include <string.hpp>
:SNPFLF            .public:
:SNPF index='index'.int String::index( String const &amp.str, size_t pos = 0 ) const;
:SNPF index='index'.int String::index( char const   *pch, size_t pos = 0 ) const;
:eSNPL.
:SMTICS.
The &fn. computes the offset at which a sequence of characters in the &obj.
is found.
:P.
The first form searches the &obj. for the contents of the
:ARG.str
&obj.:PERIOD.
:P.
The second form searches the &obj. for the sequence of characters pointed
at by
:ARG.pch
:PERIOD.
:P.
If
:ARG.pos
is specified, the search begins at that offset from the start of the
&obj.:PERIOD.
Otherwise, the search begins at offset zero (the first character).
:P.
The &fn. treats upper and lower case letters as not equal.
:RSLTS.
The &fn. returns the offset at which the sequence of characters is found.
If the substring is not found, -1 is returned.
:SALSO.
:SAL typ='mfun'.lower
:SAL typ='mfun'.operator~b!=
:SAL typ='mfun'.operator~b==
:SAL typ='mfun'.match
:SAL typ='mfun'.upper
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.length
:SNPL.
:SNPFLF             .#include <string.hpp>
:SNPFLF             .public:
:SNPF index='length'.size_t String::length() const;
:eSNPL.
:SMTICS.
The &fn. computes the number of characters contained in the &obj.:PERIOD.
:RSLTS.
The &fn. returns the number of characters contained in the &obj.:PERIOD.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.lower
:SNPL.
:SNPFLF            .#include <string.hpp>
:SNPFLF            .public:
:SNPF index='lower'.String String::lower() const;
:eSNPL.
:SMTICS.
The &fn. creates a &obj. whose value is the same as the original
object's value, except that all upper-case letters have been converted
to lower-case.
:RSLTS.
The &fn. returns a lower-case &obj.:PERIOD.
:SALSO.
:SAL typ='mfun'.upper
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.match
:SNPL.
:SNPFLF            .#include <string.hpp>
:SNPFLF            .public:
:SNPF index='match'.int String::match( String const &amp.str ) const;
:SNPF index='match'.int String::match( char const   *pch ) const;
:eSNPL.
:SMTICS.
The &fn. compares two character sequences to find the offset
where they differ.
:P.
The first form compares the &obj. to the
:ARG.str
&obj.:PERIOD.
:P.
The second form compares the &obj. to the
:ARG.pch
C string.
:P.
The first character is at offset zero.
The &fn. treats upper and lower case letters as not equal.
:RSLTS.
The &fn. returns the offset at which the two character sequences differ.
If the character sequences are equal, -1 is returned.
:SALSO.
:SAL typ='mfun'.index
:SAL typ='mfun'.lower
:SAL typ='mfun'.operator~b!=
:SAL typ='mfun'.operator~b==
:SAL typ='mfun'.upper
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator !
:SNPL.
:SNPFLF                 .#include <string.hpp>
:SNPFLF                 .public:
:SNPF index='operator !'.int String::operator !() const;
:eSNPL.
:SMTICS.
The &fn. tests the validity of the &obj.:PERIOD.
:RSLTS.
The &fn. returns a non-zero value if the &obj. is invalid,
otherwise zero is returned.
:SALSO.
:SAL typ='mfun'.valid
:SAL typ='fun'.valid
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='fun'.operator !=
:SNPL.
:SNPFLF                  .#include <string.hpp>
:SNPFLF                  .public:
:SNPR index='operator !='.friend int operator !=( String const &amp.lft,
:SNPFLF                  .                        String const &amp.rht );
:SNPR index='operator !='.friend int operator !=( String const &amp.lft,
:SNPFLF                  .                        char const   *rht );
:SNPR index='operator !='.friend int operator !=( char const   *lft,
:SNPFLF                  .                        String const &amp.rht );
:SNPR index='operator !='.friend int operator !=( String const &amp.lft,
:SNPFLF                  .                        char          rht );
:SNPR index='operator !='.friend int operator !=( char          lft,
:SNPFLF                  .                        String const &amp.rht );
:eSNPL.
:SMTICS.
The &fn. compares two sequences of characters in terms of an
:ITALICS.inequality
relationship.
:P.
A &obj. is different from another &obj. if the lengths are
different or they contain different sequences of characters.
A &obj. and a C
string are different if their lengths are different or they contain a
different sequence of characters.  A C string is terminated by a null
character.
A &obj. and a character are different if the &obj. does not contain
only the character.
Upper-case and lower-case characters are considered different.
:RSLTS.
The &fn. returns a non-zero value if the
lengths or sequences of characters in the
:ARG.lft
and
:ARG.rht
parameter are different, otherwise zero is returned.
:SALSO.
:SAL typ='mfun'.operator~b==
:SAL typ='mfun'.operator~b<
:SAL typ='mfun'.operator~b<=
:SAL typ='mfun'.operator~b>
:SAL typ='mfun'.operator~b>=
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator ()
:SNPL.
:SNPFLF                  .#include <string.hpp>
:SNPFLF                  .public:
:SNPF index='operator ()'.char &amp.String::operator ()( size_t pos );
:eSNPL.
:SMTICS.
.'se str_sub_pm='dynamic'
:INCLUDE file='str_subs'.
:SALSO.
:SAL typ='mfun'.operator~b[]
:SAL typ='mfun'.operator~bchar
:SAL typ='mfun'.operator~bchar~bconst~b*
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator ()
:SNPL.
:SNPFLF                  .#include <string.hpp>
:SNPFLF                  .public:
:SNPF index='operator ()'.String String::operator ()( size_t pos, size_t len ) const;
:eSNPL.
:SMTICS.
This form of the &fn. extracts a sub-sequence of characters from the &obj.:PERIOD.
A new &obj. is created that contains the sub-sequence of characters.
The sub-sequence begins at offset
:ARG.pos
within the &obj. and continues for
:ARG.len
characters.
The first character of a &obj. is at position zero.
:P.
If
:ARG.pos
is greater than or equal to the length of the &obj.,
the result is empty.
:P.
If
:ARG.len
is such that
:ARG.pos