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 `HeapString` (a heap allocated string).
32  */
33 
34 #ifndef HEAP_STRING_HPP_
35 #define HEAP_STRING_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include "common/equatable.hpp"
40 #include "common/error.hpp"
41 
42 namespace ot {
43 
44 /**
45  * This class represents a heap allocated string.
46  *
47  * The buffer to store the string is allocated from heap and is manged by the `HeapString` class itself, e.g., it may
48  * be reused and/or freed and reallocated when the string is set. The `HeapString` destructor will always free the
49  * allocated buffer.
50  *
51  */
52 class HeapString : public Unequatable<HeapString>
53 {
54 public:
55     /**
56      * This constructor initializes the `HeapString` as null (or empty).
57      *
58      */
HeapString(void)59     HeapString(void)
60         : mStringBuffer(nullptr)
61     {
62     }
63 
64     /**
65      * This is the move constructor for `HeapString`.
66      *
67      * `HeapString` is non-copyable (copy constructor is deleted) but move constructor is provided to allow it to to be
68      * used as return type (return by value) from functions/methods (which will then use move semantics).
69      *
70      */
HeapString(HeapString && aString)71     HeapString(HeapString &&aString)
72         : mStringBuffer(aString.mStringBuffer)
73     {
74         aString.mStringBuffer = nullptr;
75     }
76 
77     /**
78      * This is the destructor for `HealString` object
79      *
80      */
~HeapString(void)81     ~HeapString(void) { Free(); }
82 
83     /**
84      * This method indicates whether or not the `HeapString` is null (i.e., it was never successfully set or it was
85      * freed).
86      *
87      * @retval TRUE  The `HeapString` is null.
88      * @retval FALSE The `HeapString` is not null.
89      *
90      */
IsNull(void) const91     bool IsNull(void) const { return (mStringBuffer == nullptr); }
92 
93     /**
94      * This method returns the `HeapString` as a C string.
95      *
96      * @returns A pointer to C string buffer or `nullptr` if the `HeapString` is null (never set or freed).
97      *
98      */
AsCString(void) const99     const char *AsCString(void) const { return mStringBuffer; }
100 
101     /**
102      * This method sets the string from a given C string.
103      *
104      * @param[in] aCString   A pointer to c string buffer. Can be `nullptr` which then frees the `HeapString`.
105      *
106      * @retval kErrorNone     Successfully set the string.
107      * @retval kErrorNoBufs   Failed to allocate buffer for string.
108      *
109      */
110     Error Set(const char *aCString);
111 
112     /**
113      * This method sets the string from another `HeapString`.
114      *
115      * @param[in] aString   The other `HeapString` to set from.
116      *
117      * @retval kErrorNone     Successfully set the string.
118      * @retval kErrorNoBufs   Failed to allocate buffer for string.
119      *
120      */
Set(const HeapString & aString)121     Error Set(const HeapString &aString) { return Set(aString.AsCString()); }
122 
123     /**
124      * This method sets the string from another `HeapString`.
125      *
126      * @param[in] aString     The other `HeapString` to set from (rvalue reference using move semantics).
127      *
128      * @retval kErrorNone     Successfully set the string.
129      * @retval kErrorNoBufs   Failed to allocate buffer for string.
130      *
131      */
132     Error Set(HeapString &&aString);
133 
134     /**
135      * This method frees any buffer allocated by the `HeapString`.
136      *
137      * The `HeapString` destructor will automatically call `Free()`. This method allows caller to free buffer
138      * explicitly.
139      *
140      */
141     void Free(void);
142 
143     /**
144      * This method overloads operator `==` to evaluate whether or not the `HeapString` is equal to a given C string.
145      *
146      * @param[in]  aCString  A C string to compare with. Can be `nullptr` which then checks if `HeapString` is null.
147      *
148      * @retval TRUE   If the two strings are equal.
149      * @retval FALSE  If the two strings are not equal.
150      *
151      */
152     bool operator==(const char *aCString) const;
153 
154     /**
155      * This method overloads operator `!=` to evaluate whether or not the `HeapString` is unequal to a given C string.
156      *
157      * @param[in]  aCString  A C string to compare with. Can be `nullptr` which then checks if `HeapString` is not null.
158      *
159      * @retval TRUE   If the two strings are not equal.
160      * @retval FALSE  If the two strings are equal.
161      *
162      */
operator !=(const char * aCString) const163     bool operator!=(const char *aCString) const { return !(*this == aCString); }
164 
165     /**
166      * This method overloads operator `==` to evaluate whether or not two `HeapString` are equal.
167      *
168      * @param[in]  aString  The other string to compare with.
169      *
170      * @retval TRUE   If the two strings are equal.
171      * @retval FALSE  If the two strings are not equal.
172      *
173      */
operator ==(const HeapString & aString) const174     bool operator==(const HeapString &aString) const { return (*this == aString.AsCString()); }
175 
176     HeapString(const HeapString &) = delete;
177     HeapString &operator=(const HeapString &) = delete;
178 
179 private:
180     char *mStringBuffer;
181 };
182 
183 } // namespace ot
184 
185 #endif // HEAP_STRING_HPP_
186