aboutsummaryrefslogtreecommitdiffstats
path: root/meowpp/Self.h
diff options
context:
space:
mode:
Diffstat (limited to 'meowpp/Self.h')
-rw-r--r--meowpp/Self.h153
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);
};