wy_array.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2006
.\"
.TH Wy_Array 3wy "libwy v0.31"
.SH NAME
Wy_Array \- class template of dynamic array
.SH SYNOPSIS
.B #include <wy_array.h>
.PP
Wy_Array<T> is a class template for dynamic array of element type T, facilitating 
elements construction and destruction in the array so that valid position refers to valid element object.

The element class T must be movable by having the move constructor
T(T&,Wy::ByMove_t) defined as described in the public members section.

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

Postcondition for stack unwound by
  Reply : object in equivalent state as the object previously was 
  others: object in valid  state (e.g. normally default state or
          equivalent as previously was)
.SH "PUBLIC MEMBERS"
.SH "template<typename T>"
 class \fBReply\fP : public WyRet
 \fBWy_Array<T>\fP() throw(Reply)
 \fBWy_Array<T>\fP(const Wy_Array<T>&)
 \fBWy_Array<T>\fP(Wy_Array<T>&, Wy::ByMove_t) throw()
 \fBWy_Array<T>\fP(const WySeg<T>&)
 \fBWy_Array<T>\fP(size_t,const T&)
 \fB~Wy_Array<T>\fP()
 bool \fBis_default\fP(void) const throw()
 size_t \fBsize\fP(void) const throw()
 const T* \fBbegin\fP(void) const throw()
 T* \fBbegin\fP(void) throw()
 const T* \fBend\fP(void) const throw()
 T* \fBend\fP(void) throw()
 const T& \fBfront\fP(void) const throw(Reply)
 T& \fBfront\fP(void) throw(Reply)
 const T& \fBback\fP(void) const throw(Reply)
 T& \fBback\fP(void) throw(Reply)
 WySeg<T> \fBsubseg\fP(void) const throw()
 WySeg<T> \fBsubseg\fP(size_t) const throw(Reply)
 WySeg<T> \fBsubseg\fP(size_t, size_t) const throw(Reply)
 const T& \fBoperator []\fP(size_t) const throw(Reply)
 T& \fBoperator []\fP(size_t) throw(Reply)
 void \fBreset\fP(void)
 void \fBreset\fP(const Wy_Array<T>&)
 void \fBreset\fP(const WySeg<T>&)
 void \fBreset\fP(size_t, const T&)
 const Wy_Array<T>& \fBoperator =\fP(const Wy_Array<T>&)
 const Wy_Array<T>& \fBoperator =\fP(const WySeg<T>&)
 void \fBswap\fP(Wy_Array<T>&) throw()
 void \fBpush_back\fP(const T&)
 void \fBpop_back\fP(void)
 void \fBerase\fP(size_t, size_t)
 void \fBinsert\fP(size_t, const T&)
 void \fBinsert\fP(size_t, size_t, const T&)
 void \fBinsert\fP(size_t, const WySeg<T>&)
 void \fBinsert\fP(size_t, const Wy_Array<T>&)
 void \fBreplace\fP(size_t, size_t, size_t, const T&)
 void \fBresize\fP(size_t)
 void \fBresize\fP(size_t,const T&)
 bool \fBoperator ==\fP(const Wy_Array<T>& rhs) const
 bool \fBoperator !=\fP(const Wy_Array<T>& rhs) const

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

 static size_t \fBmax_capacity\fP(void) throw()
 static size_t \fBmin_capacity\fP(void) throw()
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "Wy_Array<T>() throw(Reply)"
.PP
    Construct default object

    [\fBEffect\fP]
            size() = 0
            begin()= Pointer to an allocated dynamic array
            end()  = begin()

            Note: _capacity()>= min_capacity()
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "Wy_Array<T>(const Wy_Array<T>& " "src" ")"
.PP
    Construct object to contain elements copy constructed from \fIsrc\fP

    [\fBEffect\fP]
            size() = \fIsrc\fP.size()
            begin()= Pointer to an allocated dynamic array
            end()  = begin()+size()

            For all valid position i, (*this)[i] is copy constructed
            from \fIsrc\fP[i]

            Note: _capacity()>= \fIsrc\fP.size() and min_capacity()
.PP
    [\fBThrow\fP] from T(const T&)
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "Wy_Array<T>(Wy_Array<T>& " "src" ", Wy::ByMove_t) throw()"
.PP
    Make the object \fIsrc\fP accessible at \fIthis\fP pointed address.

    After function completed, \fIsrc\fP is just regarded non-existant
    without destructor being called and can not be, and the space
    occupied can be recycled. The dummy argument type ByMove_t is
    for function signature, use instance should always be Wy::ByMove.
    This member is supposed to be invoked only via placement new or
    in member initialization list, not to be explicitly called.

    This member is not entirely a real constructor (no new object is
    ever created) but a function in constructor form to support object
    movement in a dynamic array.

    Note: Except in member initialization list, \fIsrc\fP must be
          a whole type, not reference to a base. Otherwise,
          effect is undefined.

    [\fBEffect\fP]
            size() = \fIsrc\fP.size()
            begin()= \fIsrc\fP.begin()
            end()  = \fIsrc\fP.end()

            Note: _capacity()= \fIsrc\fP._capacity()

            At final, object \fIsrc\fP does not exist

    Example:
      class D : public B {      // assume B has the move constructor
           struct timespec _ts;
           char* _ptr;          // pointed to allocated memory
         public:
           D(D& d, Wy::ByMove_t) throw()
            : B(d,Wy::ByMove), _ts(d._ts), _ptr(d._ptr) {};
           // ... others
      };
.\"--------------------------------------------
.PP
.BI "Wy_Array<T>(const WySeg<T>& " "src" ")"
.PP
    Construct object to contain elements copy constructed from \fIsrc\fP

    [\fBEffect\fP]
            size() = \fIsrc\fP.size()
            begin()= Pointer to an allocated dynamic array
            end()  = begin()+size()

            Note: _capacity()>= \fIsrc\fP.size() and min_capacity()
.PP
    [\fBThrow\fP] from T(const T&)
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "Wy_Array<T>(size_t " "n_elem" ", const T& " "elem" ")"
.PP
    Construct object containing number \fIn_elem\fP of elements T(\fIelem\fP)

    [\fBEffect\fP]
            size() = \fIn_elem\fP
            begin()= Pointer to an allocated dynamic array
            end()  = begin()+size()

            Note: _capacity()>= \fIn_elem\fP and min_capacity()
.PP
    [\fBThrow\fP] from T(const T&)
.PP
    [\fBThrow\fP] Reply
            Wym_EFBIG       Capacity would exceed the maximum
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "~Wy_Array<T>()"
.PP
    Destruct *this and applying ~T() for each element in the array
.PP
    [\fBThrow\fP] from ~T()
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const throw()"
.PP
    Is *this equivalent to the default object

    Note: Capacity is irrelevant to object equivalence.
.PP
    [\fBRet\fP] true= object is equivalent to Wy_Array<T>()
         false= otherwise
.\"--------------------------------------------
.PP
.BI "size_t size(void) const throw()"
.PP
    Get the number of elements in the dynamic array

    Note: Valid position of *this is from 0 to size()-1.
          If size()==0, no position is valid for access.
.PP
    [\fBRet\fP] The number of elements in the dynaic array
.\"--------------------------------------------
.PP
.BI "const T* begin(void) const throw()"
.PP
.BI "T* begin(void) throw()"
.PP
    Get the begining pointer of the dynamic array 

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

    Note: Equivalent objects do not mean the pointer value and
          capacity are equal.
.PP
    [\fBRet\fP] pointer of the dynamic array
.\"--------------------------------------------
.PP
.BI "const T* end(void) const throw()"
.PP
.BI "T* end(void) throw()"
.PP
    Get the one-past-the-last pointer of element in the dynamic array

    For any Wy_Array<T> object v, v.end()==v.begin()+v.size()
    Dereferencing the end pointer is never valid.

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

    Note: Equivalent objects do not mean the pointer value and
          capacity are equal.
.PP
    [\fBRet\fP] one-past-the-last element pointer
.\"--------------------------------------------
.PP
.BI "const T& front(void) const throw(Reply)"
.PP
.BI "T& front(void) throw(Reply)"
.PP
    Get the reference of the first element

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

    Note: Equivalent objects do not mean the pointer value and
          capacity are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_ENOENT      this->size()==0
.PP
    [\fBRet\fP] Reference of the element at position 0.
.\"--------------------------------------------
.PP
.BI "const T& back(void) const throw(Reply)"
.PP
.BI "T& back(void) throw(Reply)"
.PP
    Get the reference of the last element

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

    Note: Equivalent objects do not mean the pointer value and
          capacity are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_ENOENT      this->size()==0
.PP
    [\fBRet\fP] Reference of the element at position size()-1
.\"--------------------------------------------
.PP
.BI "WySeg<T> subseg(void) const throw()"
.PP
    Get the sub-segment of *this
.PP
    [\fBRet\fP] WySeg<T> of the array
.\"--------------------------------------------
.PP
.BI "WySeg<T> subseg(size_t " "idx" ") const throw()"
.PP
    Get the sub-segment of *this from position \fIidx\fP till the last
.PP
    [\fBThrow\fP] Reply
            Wym_EINVAL      \fIidx\fP > this->size()
.PP
    [\fBRet\fP] WySeg<T> of the specified array segment
.\"--------------------------------------------
.PP
.BI "WySeg<T> subseg(size_t " "idx" ", size_t " "num" ") const throw(Reply)"
.PP
    Get the sub-segment of *this from position \fIidx\fP, at most \fInum\fP
    of size
.PP
    [\fBThrow\fP] Reply
            Wym_EINVAL      \fIidx\fP > this->size()
.PP
    [\fBRet\fP] WySeg<T> of the specified array segment
.\"--------------------------------------------
.PP
.BI "const T& operator [](size_t " "idx" ") const throw(Reply)"
.PP
.BI "T& operator [](size_t " "idx" ") throw(Reply)"
.PP
    Get the element reference at position \fIidx\fP

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

    Note: Equivalent objects do not mean the pointer value and
          capacity are equal.
.PP
    [\fBThrow\fP] Reply
            Wym_EINVAL      \fIidx\fP>=this->size()
.PP
    [\fBRet\fP] Element reference at position \fIidx\fP
.\"--------------------------------------------
.PP
.BI "void reset(void)" 
.PP
    Reconstruct *this to the state as Wy_Array<T>()
    All existing elements in the array are destroyed.
.PP
    [\fBThrow\fP] from ~T()
.\"--------------------------------------------
.PP
.BI "void reset(const Wy_Array<T>& " "src" ")" 
.PP
    Reconstruct *this to the state as Wy_Array<T>(\fIsrc\fP).