wystr.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH WyStr 3wy "libwy v0.31"
.SH NAME
WyStr \- class of contiguous characters
.SH SYNOPSIS
.B #include <wystr.h>
.PP
WyStr is a class for dynamic array of element type char, these elements 
in whole is referred to as data or string.

The array is an allocation unit acquired from dynamic store.
Reallocation of the array (and hence the Wym_ENOMEM report) occurres only
when non-const member operation causes the resultant data length to exceed
the capacity. Thus, array address is dynamic.
If reallocation occurred, the previously output data pointer and 
reference are implicitly undefined.

Members are not atomic of concurrent access from different threads. 
No member is the thread cancellation point.
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWyStr\fP() throw(Reply)
 \fBWyStr\fP(const WyStr&) throw(Reply)
 \fBWyStr\fP(const WyCSeg&) throw(Reply)
 \fBWyStr\fP(size_t,char) throw(Reply)
 \fBWyStr\fP(WyStr&, Wy::ByMove_t) throw()
 \fB~WyStr\fP() throw()
 bool \fBis_default\fP(void) const throw()
 void \fBreset\fP(void) throw()
 WyRet \fBreset\fP(const WyStr&) throw()
 WyRet \fBreset\fP(const WyCSeg&) throw()
 WyRet \fBreset\fP(size_t,char) throw()
 size_t \fBsize\fP(void) const throw()
 const char& \fBoperator []\fP(size_t pos) const throw()
 char& \fBoperator []\fP(size_t pos) throw()
 const char& \fBat\fP(size_t pos) const throw(Reply)
 char& \fBat\fP(size_t pos) throw(Reply)
 const char* \fBdata\fP(void) const throw()
 const char* \fBc_str\fP(void) const throw()
 const char* \fBbegin\fP(void) const throw()
 const char* \fBend\fP(void) const throw()
 const WyStr& \fBoperator =\fP(const WyStr&) throw(Reply)
 const WyStr& \fBoperator =\fP(const WyCSeg&) throw(Reply)
 void \fBswap\fP(WyStr&) throw()
 WyRet \fBappend\fP(char) throw()
 WyRet \fBappend\fP(const WyStr&) throw()
 WyRet \fBappend\fP(const WyCSeg&) throw()
 WyRet \fBappend\fP(size_t,char) throw()
 const WyStr& \fBoperator +=\fP(char) throw(Reply)
 const WyStr& \fBoperator +=\fP(const WyStr&) throw(Reply)
 const WyStr& \fBoperator +=\fP(const WyCSeg&) throw(Reply)
 WyRet \fBinsert\fP(size_t,const WyStr&) throw()
 WyRet \fBinsert\fP(size_t,const WyCSeg&) throw()
 WyRet \fBinsert\fP(size_t,size_t,char) throw()
 WyRet \fBerase\fP(size_t) throw()
 WyRet \fBerase\fP(size_t,size_t) throw()
 WyRet \fBresize\fP(size_t) throw()
 WyRet \fBresize\fP(size_t,char) throw()
 WyRet \fBreplace\fP(size_t,size_t,const WyStr&) throw()
 WyRet \fBreplace\fP(size_t,size_t,const WyCSeg&) throw()
 WyRet \fBreplace\fP(size_t,size_t,size_t,char) throw()
 WyRet \fBcopyto\fP(size_t*,char*,size_t,size_t) const throw()
 bool \fBfind\fP(size_t*,char) const throw()
 bool \fBfind\fP(size_t*,const WyCSeg&) const throw()
 bool \fBfind\fP(size_t*,size_t,char) const throw()
 bool \fBfind\fP(size_t*,size_t,const WyCSeg&) const throw()
 bool \fBrfind\fP(size_t*,char) const throw()
 bool \fBrfind\fP(size_t*,const WyCSeg&) const throw()
 bool \fBrfind\fP(size_t*,size_t,char) const throw()
 bool \fBrfind\fP(size_t*,size_t,const WyCSeg&) const throw()
 bool \fBfind_not\fP(size_t*,size_t,char) const throw()
 bool \fBrfind_not\fP(size_t*,size_t,char) const throw()
./ bool \fBfind_in\fP(size_t*,size_t,const WyCSeg&) const throw()
./ bool \fBfind_not\fP(size_t*,size_t,const WyCSeg&) const throw()
./ bool \fBrfind_in\fP(size_t*,size_t,const WyCSeg&) const throw()
./ bool \fBrfind_not\fP(size_t*,size_t,const WyCSeg&) const throw()
 WyCSeg \fBcseg\fP(void) const throw()
 WyCSeg \fBcseg\fP(size_t) const throw(Reply)
 WyCSeg \fBcseg\fP(size_t,size_t) const throw(Reply)
 bool \fBoperator ==\fP(const WyStr&) const throw()
 bool \fBoperator !=\fP(const WyStr&) const throw()
 bool \fBoperator ==\fP(const WyCSeg&) const throw()
 bool \fBoperator !=\fP(const WyCSeg&) const throw()
 bool \fBoperator ==\fP(const char*) const throw(WyCSeg::Reply)
 bool \fBoperator !=\fP(const char*) const throw(WyCSeg::Reply)

 int \fB_strcmp\fP(const WyStr&) const throw()
 int \fB_strcmp\fP(const WyCSeg&) const throw()
 int \fB_strcmp\fP(const char*) const throw(WyCSeg::Reply)

 size_t \fB_capacity\fP(void) const throw()
 WyRet \fB_reserve\fP(size_t) throw()
 WyRet \fB_setsize\fP(size_t) throw()

 static size_t \fBmax_capacity\fP(void) throw()
 static size_t \fBmin_capacity\fP(void) throw()
.SH "AUXILIARY FUNCTIONS"
 WyStr \fBoperator +\fP(const WyStr&,const WyStr&) throw(WyStr::Reply)
 WyStr \fBoperator +\fP(const WyStr&,const WyCSeg&) throw(WyStr::Reply)
 WyStr \fBoperator +\fP(const WyCSeg&,const WyStr&) throw(WyStr::Reply)
 WyStr \fBoperator +\fP(const WyStr&,char) throw(WyStr::Reply)
 WyStr \fBoperator +\fP(char,const WyStr&) throw(WyStr::Reply)
 bool \fBoperator ==\fP(const WyCSeg&,const WyStr&) throw()
 bool \fBoperator !=\fP(const WyCSeg&,const WyStr&) throw()
 bool \fBoperator ==\fP(const char*,const WyStr&) throw(WyCSeg::Reply)
 bool \fBoperator !=\fP(const char*,const WyStr&) throw(WyCSeg::Reply)
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet"
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "WyStr() throw(Reply)"
.PP
    Construct default object

      data() = dynamic array with the first element set to char(0)
      size() = 0

    Note: _capacity()>= min_capacity()

    Note: The value returned from members \fBdata\fP(), \fBc_str\fP(),
          \fBbegin\fP(), and by &\fBat\fP(0), &\fBoperator[]\fP(0) are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyStr(const WyStr& " "str" ") throw(Reply)"
.PP
    Construct object to contain data copied from \fIstr\fP

      data() = dynamic array with all elements copied from \fIstr\fP
      size() = \fIstr\fP.size()

    Note: _capacity()>= \fIsrc\fP.size() and min_capacity()

    Note: The value returned from members \fBdata\fP(), \fBc_str\fP(),
          \fBbegin\fP(), and by &\fBat\fP(0), &\fBoperator[]\fP(0) are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyStr(const WyCSeg& " "cs" ") throw(Reply)"
.PP
    Construct object to contain data copied from \fIcs\fP pointed
    character array

      data() = dynamic array with all elements copied from \fIcs\fP
               pointed array
      size() = \fIcs\fP.size()

    Note: _capacity()>= \fIcs\fP.size() and min_capacity()

    Note: The value returned from members \fBdata\fP(), \fBc_str\fP(),
          \fBbegin\fP(), and by &\fBat\fP(0), &\fBoperator[]\fP(0) are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_EFBIG       Data size exceeds the maximum
            Wym_ENOMEM      Not enough memory

    Note: Construction of \fIcs\fP may throw WyCSeg::Reply
.\"--------------------------------------------
.PP
.BI "WyStr(size_t " "cnum" ", char " "ch" ") throw(Reply)"
.PP
    Construct object to contain \fIcnum\fP of character \fIch\fP

      data() = dynamic array with the first \fIcnum\fP of elements
               set to \fIch\fP
      size() = \fIcnum\fP

    Note: _capacity()>= \fIcnum\fP and min_capacity()

    Note: The value returned from members \fBdata\fP(), \fBc_str\fP(),
          \fBbegin\fP(), and by &\fBat\fP(0), &\fBoperator[]\fP(0) are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_EFBIG       Data size exceeds the maximum
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyStr(WyStr& " "src" ", Wy::ByMove_t) throw()"
.PP
    See Wy_Array(Wy_Array&, Wy::ByMove_t) in wy_array(3wy)
    for definition of the move constructor.
.\"--------------------------------------------
.PP
.BI "~WyStr() throw()"
.PP
    Destruct *this
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const throw()"
.PP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= object is equivalent to WyStr()
         false= otherwise
.\"--------------------------------------------
.PP
.BI "void reset(void) throw()" 
.PP
    Reconstruct *this to the state as WyStr()
.\"--------------------------------------------
.PP
.BI "WyRet reset(const WyStr& " "str" ") throw()"
.PP
    Reconstruct *this to the state as WyStr(\fIstr\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_ELOOP       *this and \fIstr\fP would overlap
          Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyRet reset(const WyCSeg& " "cs" ") throw()"
.PP
    Reconstruct *this to the state as WyStr(\fIcs\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_ELOOP       *this and \fIcs\fP pointed string overlap
          Wym_EFBIG       Data size exceeds the maximum
          Wym_ENOMEM      Not enough memory

    Note: Construction of \fIcs\fP may throw WyCSeg::Reply
.\"--------------------------------------------
.PP
.BI "WyRet reset(size_t " "cnum" ", char " "ch" ") throw()"
.PP
    Reconstruct *this to the state as WyStr(\fIcnum\fP,\fIch\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EFBIG       Data size exceeds the maximum
          Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "size_t size(void) const throw()"
.PP
    Get the number of characters of data
.PP
    [\fBRet\fP] number of characters data contains
.\"--------------------------------------------
.PP
.BI "const char& operator [](size_t " "idx" ") const throw()"
.PP
    Get the character reference at position \fIidx\fP of the data

    Note: Reading with \fIidx\fP>=size() is invalid.
          For explicit faster access, use: 

            const char *p=this->data(); p[?]...;
.PP
    [\fBRet\fP] const reference of the character at position \fIidx\fP
.\"--------------------------------------------
.PP
.BI "char& operator [](size_t " "idx" ") throw()"
.PP
    Get the character reference at position \fIidx\fP of the data

    Note: Reading/Writing with \fIidx\fP>=size() is invalid.
          For explicit faster access, use: 

          char *p=&(*this)[0]; p[?]...;
.PP
    [\fBRet\fP] reference of the character at position \fIidx\fP
.\"--------------------------------------------
.PP
.BI "const char& at(size_t " "idx" ") const throw(Reply)"
.PP
    Get the character reference at position \fIidx\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EINVAL      \fIidx\fP >= this->size()
.PP
    [\fBRet\fP] const reference of the character at position \fIidx\fP
.\"--------------------------------------------
.PP
.BI "char& at(size_t " "idx" ") throw(Reply)"
.PP
    Get the character reference at position \fIidx\fP
.PP
    [\fBThrow\fP] Reply
            Wym_EINVAL      \fIidx\fP >= this->size()
.PP
    [\fBRet\fP] reference of the character at position \fIidx\fP
.\"--------------------------------------------
.PP
.BI "const char* data(void) const throw()"
.PP
    Get const object pointer of data. 

    Note: Non-const members may cause reallocation. Reallocation 
          invalidates dereference of the returned pointer.

    Note: The pointed object is meant to return, which is a 
          dynamically allocated character array.

    Note: Equivalent objects do not mean data address and capacity 
          are equal.
.PP
    [\fBRet\fP] const object pointer of the data
          ,or points to char(0) if object is default
.\"--------------------------------------------
.PP
.BI "const char* c_str(void) const throw()"
.PP
    Get const object pointer of data.

    The returned pointer is the same as that data() returns. But