1 /*
2  *  Copyright (c) 2021, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  *   This file includes definitions for a pointer wrapper.
32  */
33 
34 #ifndef PTR_WRAPPER_HPP_
35 #define PTR_WRAPPER_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include <stdbool.h>
40 #include <stdint.h>
41 
42 namespace ot {
43 
44 /**
45  * This template class represents a wrapper over a pointer.
46  *
47  * This is intended as base class of `OwnedPtr` or `RetainPtr` providing common simple methods.
48  *
49  * @tparam Type  The pointer type.
50  *
51  */
52 template <class Type> class Ptr
53 {
54 public:
55     /**
56      * This is the default constructor for `Ptr` initializing it as null.
57      *
58      */
Ptr(void)59     Ptr(void)
60         : mPointer(nullptr)
61     {
62     }
63 
64     /**
65      * This constructor initializes the `Ptr` with a given pointer.
66      *
67      * @param[in] aPointer  A pointer to initialize with.
68      *
69      */
Ptr(Type * aPointer)70     explicit Ptr(Type *aPointer)
71         : mPointer(aPointer)
72     {
73     }
74 
75     /**
76      * This method indicates whether the `Ptr` is null or not.
77      *
78      * @retval TRUE   The `Ptr` is null.
79      * @retval FALSE  The `Ptr` is not null.
80      *
81      */
IsNull(void) const82     bool IsNull(void) const { return (mPointer == nullptr); }
83 
84     /**
85      * This method gets the wrapped pointer.
86      *
87      * @returns The wrapped pointer.
88      *
89      */
Get(void)90     Type *Get(void) { return mPointer; }
91 
92     /**
93      * This method gets the wrapped pointer.
94      *
95      * @returns The wrapped pointer.
96      *
97      */
Get(void) const98     const Type *Get(void) const { return mPointer; }
99 
100     /**
101      * This method overloads the `->` dereference operator and returns the pointer.
102      *
103      * @returns The wrapped pointer.
104      *
105      */
operator ->(void)106     Type *operator->(void) { return mPointer; }
107 
108     /**
109      * This method overloads the `->` dereference operator and returns the pointer.
110      *
111      * @returns The wrapped pointer.
112      *
113      */
operator ->(void) const114     const Type *operator->(void) const { return mPointer; }
115 
116     /**
117      * This method overloads the `*` dereference operator and returns a reference to the pointed object.
118      *
119      * The behavior is undefined if `IsNull() == true`.
120      *
121      * @returns A reference to the pointed object.
122      *
123      */
operator *(void)124     Type &operator*(void) { return *mPointer; }
125 
126     /**
127      * This method overloads the `*` dereference operator and returns a reference to the pointed object.
128      *
129      * The behavior is undefined if `IsNull() == true`.
130      *
131      * @returns A reference to the pointed object.
132      *
133      */
operator *(void) const134     const Type &operator*(void) const { return *mPointer; }
135 
136     /**
137      * This method overloads the operator `==` to compare the `Ptr` with a given pointer.
138      *
139      * @param[in] aPointer   The pointer to compare with.
140      *
141      * @retval TRUE   If `Ptr` is equal to @p aPointer.
142      * @retval FALSE  If `Ptr` is not equal to @p aPointer.
143      *
144      */
operator ==(const Type * aPointer) const145     bool operator==(const Type *aPointer) const { return (mPointer == aPointer); }
146 
147     /**
148      * This method overloads the operator `!=` to compare the `Ptr` with a given pointer.
149      *
150      * @param[in] aPointer   The pointer to compare with.
151      *
152      * @retval TRUE   If `Ptr` is not equal to @p aPointer.
153      * @retval FALSE  If `Ptr` is equal to @p aPointer.
154      *
155      */
operator !=(const Type * aPointer) const156     bool operator!=(const Type *aPointer) const { return (mPointer != aPointer); }
157 
158     /**
159      * This method overloads the operator `==` to compare the `Ptr` with another `Ptr`.
160      *
161      * @param[in] aOther   The other `Ptr` to compare with.
162      *
163      * @retval TRUE   If `Ptr` is equal to @p aOther.
164      * @retval FALSE  If `Ptr` is not equal to @p aOther.
165      *
166      */
operator ==(const Ptr & aOther) const167     bool operator==(const Ptr &aOther) const { return (mPointer == aOther.mPointer); }
168 
169     /**
170      * This method overloads the operator `!=` to compare the `Ptr` with another `Ptr`.
171      *
172      * @param[in] aOther   The other `Ptr` to compare with.
173      *
174      * @retval TRUE   If `Ptr` is not equal to @p aOther.
175      * @retval FALSE  If `Ptr` is equal to @p aOther.
176      *
177      */
operator !=(const Ptr & aOther) const178     bool operator!=(const Ptr &aOther) const { return (mPointer != aOther.mPointer); }
179 
180 protected:
181     Type *mPointer;
182 };
183 
184 } // namespace ot
185 
186 #endif // PTR_WRAPPER_HPP_
187