diff options
Diffstat (limited to 'meowpp/Self.h')
| -rw-r--r-- | meowpp/Self.h | 153 |
1 files changed, 95 insertions, 58 deletions
diff --git a/meowpp/Self.h b/meowpp/Self.h index 7de568b..aefc7a3 100644 --- a/meowpp/Self.h +++ b/meowpp/Self.h @@ -6,64 +6,109 @@ namespace meow { /*! - *@brief 具有copy on write, 且擁有比C++更靈活的reference機制 + *@brief A little class use for packing the data part of another class. + * With this technique, it can achieve Copy-On-Write(COR) mechanism at + * background and have a reference mechanism which much more flexible + * then the one C++ has. * - *使用上就是把所有成員變數包到一個class/structure裡, 送給Self \n - *例如以下 + * Sample code: *@code{.cpp} * class A { * private: * struct Myself { * int data; - * Myself() { // 必要 + * + * Myself() { // Necessary * data = 0; * } - * Myself(Myself const& b): data(b.data) { // 必要, copy constructor + * + * Myself(Myself const& b): data(b.data) { // Necessary, copy constructor * } + * * ~Myself() { * } - * bool operator==(Myself const& b) const { // 不一定需要(有用到equal()才要) + * + * bool operator==(Myself const& b) const { // Optional (this method will + * // be called only if you use + * // Self::equal() method) * return (data == b.data); * } * }; * - * Self<Myself> const self; + * Self<Myself> const self; // Here we use 'constant' data type in + * // order to have a coutious coding style + * // and allow the COR mechanism to clone + * // data only when we really want to + * // modify them. * public: - * A(): self() { } // 預設呼叫Myself() - * A(A const& a): self(a.self, COPY_FROM) { } // 用Myself(b)做到copyFrom + * A(): self() { } // Default constructor + * + * A(A const& a): self(a.self, COPY_FROM) { } // Copy constructor. You must + * // tell me which way of + * // duplicating should I use. + * // It strongly recommended you + * // use COYP_FROM for keeping the + * // C++'s original behavior. * ~A() { } - * void setMemeber(int k) { - * self()->data = k; // self()->?? 可以有write權限 - * } + * * int getMemember(int wh) const { - * return self->data; // self->?? 只有const + * return self->data; // Use 'operator->()' to get the pointer of the data + * // The pointer is constant or not will depend on + * // whether the left side variable of '->' is + * // constant or not. + * // If we just want to read the data, use + * // 'self' instead of 'self()' * } + * void setMemeber(int k) { + * self()->data = k; // As a result of 'self()' returning a non-constant + * // reference of itself, here we get the permission + * // for modiying data. + * // So now we can observe that if you type + * // 'Self<Myself> self' instead of the one above, + * // 'self' and 'self()' will become the same one and + * // both of them allow you using '->' for getting + * // writing permission. At the same time, the COR + * // machanism will become useless because everytime + * // you want to access the date, Self will copy the + * // data to prevent you to modify it no matter that + * // you might just want to read it. + * } + * * A referenceFrom(A const& a) { * self.referenceFrom(a.self); * } + * * A copyFrom(A const& a) { * self.copyFrom(a.self); * } - * A& operator=(A const& b) { // for std::swap + * + * A& operator=(A const& b) { // If you really like to use operator=, it + * // strongly recommended you use 'copyFrom()' for + * // keeping C++'s original behavior. * copyFrom(b); * } * }; - * @endcode + *@endcode + * Note that 'referenceFrom()' will cause the two object become the same one, + * Which means that if you do something like '\c a.referenceFrom(b); + * \c a.copyFrom(c); ', the result is that the value of \c a,b,c will all the + * same one. * - * @author cathook + *@author cathook * - * @warning \c Self 這個class會把\c operator= 給disable掉, 所以使用它當 - * kernel的class預設的 \c operator= 都會無法使用 + *@warning This class disabled the method \c operator= and copy constructor + * in order to prevent upexplicit default behavior, so if you want + * to have one of them (or both), you must implement yourself */ template<class Data> class Self { public: /*! - * @brief 複製資料的方法 + * @brief Kind of ways of duplicating */ enum DuplicateType { - COPY_FROM, //!< 跟一般的複製一樣 - REFERENCE_FROM //!< 參照, 執行完兩個Self會完全等效 + COPY_FROM, //!< Normal copy operation + REFERENCE_FROM //!< By reference, much like pointer's copy operation }; private: class Body { @@ -123,27 +168,24 @@ private: } public: /*! - *@brief constructor, 並宣告一個實體 + * @brief constructor with a real entity */ Self(): body_(new Body()) { } /*! - * @brief connstructor, 宣告一個實體, 其中該實體的constructor用copy - * constructor + * @brief connstructor with a real entity with it using its copy constructor * * @param [in] d Inital data - * */ Self(Data const& d): body_(new Body(d)) { } /*! - * @brief constructor, 使用給定的Self當作init value, 並且可以指定要用 - * reference還是copy + * @brief constructor with given another Self * - * @param [in] b 給定的Self - * @param [in] d 指定要用copy還是reference + * @param [in] b Another Self object. + * @param [in] d To indicate type of way of duplicating */ Self(Self const& b, DuplicateType d) { switch(d) { @@ -160,34 +202,33 @@ public: //! @brief Disallow copy constructor Self(Self const& b); - //! @brief 解構子 + //! @brief destructor ~Self() { clear(); } - //! @brief 回傳指向 Data const 的指標 + //! @brief Return the constant pointer to the data Data const* operator->() const { return body_->access(); } - //! @brief 回傳指向 Data 的指標, 如有需要, 這邊會做資料的duplicate + /*! @brief Return the non-constant pointer to the data (COR's clone might + * occure here. + */ Data* operator->() { return body_->modify(); } - //! @brief 回傳非const型態的自己 + //! @brief Return the non-constant reference of \c *this Self& operator()() const { return *((Self*)this); } /*! - * @brief 將給定的 \c Self 的資料複製到自己這裡 + * @brief Copy the gived \c Self to myself * - * @param [in] s 給定的\c Self + * @param [in] s gived \c Self * @return *this - * - * @note 與reference的差別是, copy之後若該給定的 \c Self 有資料修改, - * this 這邊 \b 不會 被改到 */ Self const& copyFrom(Self const& s) { if (body_->access() != s.body_->access()) { @@ -197,14 +238,10 @@ public: } /*! - * @brief 將自己reference 到給定的 \c Self + * @brief Reference myself from given \c Self object. * - * @param [in] s 給定的\c Self + * @param [in] s given \c Self * @return *this - * - * @note 把reference想像成指標會比較容易思考, 譬如 \c a.referenceFrom(b) - * \c b.referenceFrom(c) 相當於 \b a指向b原本指的記憶體位置, - * \b b指向c原本指的記憶體位置 , 之後更動c時, 只有b會被牽連 */ Self const& referenceFrom(Self const& s) { if (body_ != s.body_) { @@ -216,10 +253,10 @@ public: } /*! - * @brief 依據給定DuplicateType選擇要呼叫copyFrom還是referenceFrom + * @brief call \c copyFrom() or \c referenceFrom() depend on your instruction * - * @param [in] s 給定的 \c Self - * @param [in] t 給定的 \c DuplicateType + * @param [in] s gived \c Self object + * @param [in] t instruction * @return *this */ Self const& duplicateFrom(Self const& s, DuplicateType t) { @@ -231,22 +268,23 @@ public: } /*! - * @brief 比對兩個 \c Self 是否指向同一個reference + * @brief Compare tht if the gived \c Self object is reference from the same + * object of me * - * @param [in] s 另一個 \c Self - * @return \c true/false 表示是否為同一個reference + * @param [in] s gived \c Self object + * @return \c true if we are referenced to the same object. */ bool same(Self const& s) const { return (body_ == s.body_); } /*! - * @brief 比對兩個 \c Self 的內容是否一樣 + * @brief Compare that the data are the same. * - * @param [in] s 另一個 \c Self - * @return \c true/false 表示兩個內容是否一樣 + * @param [in] s another \c Self object + * @return \c true if the data are same. * - * @note 需要用到 Data的equal() + * @note This will need the method 'Data::equal()' */ bool equal(Self const& s) const { if (same(s) || body_->access() == s.body_->access()) return true; @@ -254,16 +292,15 @@ public: } /*! - * @brief 以reference作為判斷依據的小於判斷 + * @brief Order compare by reference pointer. * - * @param [in] s 另一個 \c Self - * @return \c true/false 表示自己是否小於另一個 \c Self + * @param [in] s another \c Self object */ bool referenceLess(Self const& s) const { return (body_ < s.body_); } - //! @brief 將 \c operator= 給disable掉 + //! @brief Disallow default \c 'operator=' void operator=(Self const& a); }; |