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 `Heap::String` (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 #include "common/heap.hpp" 42 43 namespace ot { 44 namespace Heap { 45 46 /** 47 * Represents a heap allocated string. 48 * 49 * The buffer to store the string is allocated from heap and is managed by the `Heap::String` class itself, e.g., it may 50 * be reused and/or freed and reallocated when the string is set. The `Heap::String` destructor will always free the 51 * allocated buffer. 52 */ 53 class String : public Unequatable<String> 54 { 55 public: 56 /** 57 * Initializes the `String` as null (or empty). 58 */ String(void)59 String(void) 60 : mStringBuffer(nullptr) 61 { 62 } 63 64 /** 65 * This is the move constructor for `String`. 66 * 67 * `String` 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 */ String(String && aString)70 String(String &&aString) 71 : mStringBuffer(aString.mStringBuffer) 72 { 73 aString.mStringBuffer = nullptr; 74 } 75 76 /** 77 * This is the destructor for `HealString` object 78 */ ~String(void)79 ~String(void) { Free(); } 80 81 /** 82 * Indicates whether or not the `String` is null (i.e., it was never successfully set or it was 83 * freed). 84 * 85 * @retval TRUE The `String` is null. 86 * @retval FALSE The `String` is not null. 87 */ IsNull(void) const88 bool IsNull(void) const { return (mStringBuffer == nullptr); } 89 90 /** 91 * Returns the `String` as a C string. 92 * 93 * @returns A pointer to C string buffer or `nullptr` if the `String` is null (never set or freed). 94 */ AsCString(void) const95 const char *AsCString(void) const { return mStringBuffer; } 96 97 /** 98 * Sets the string from a given C string. 99 * 100 * @param[in] aCString A pointer to c string buffer. Can be `nullptr` which then frees the `String`. 101 * 102 * @retval kErrorNone Successfully set the string. 103 * @retval kErrorNoBufs Failed to allocate buffer for string. 104 */ 105 Error Set(const char *aCString); 106 107 /** 108 * Sets the string from another `String`. 109 * 110 * @param[in] aString The other `String` to set from. 111 * 112 * @retval kErrorNone Successfully set the string. 113 * @retval kErrorNoBufs Failed to allocate buffer for string. 114 */ Set(const String & aString)115 Error Set(const String &aString) { return Set(aString.AsCString()); } 116 117 /** 118 * Sets the string from another `String`. 119 * 120 * @param[in] aString The other `String` to set from (rvalue reference using move semantics). 121 * 122 * @retval kErrorNone Successfully set the string. 123 * @retval kErrorNoBufs Failed to allocate buffer for string. 124 */ 125 Error Set(String &&aString); 126 127 /** 128 * Frees any buffer allocated by the `String`. 129 * 130 * The `String` destructor will automatically call `Free()`. This method allows caller to free buffer 131 * explicitly. 132 */ 133 void Free(void); 134 135 /** 136 * Overloads operator `==` to evaluate whether or not the `String` is equal to a given C string. 137 * 138 * @param[in] aCString A C string to compare with. Can be `nullptr` which then checks if `String` is null. 139 * 140 * @retval TRUE If the two strings are equal. 141 * @retval FALSE If the two strings are not equal. 142 */ 143 bool operator==(const char *aCString) const; 144 145 /** 146 * Overloads operator `!=` to evaluate whether or not the `String` is unequal to a given C string. 147 * 148 * @param[in] aCString A C string to compare with. Can be `nullptr` which then checks if `String` is not null. 149 * 150 * @retval TRUE If the two strings are not equal. 151 * @retval FALSE If the two strings are equal. 152 */ operator !=(const char * aCString) const153 bool operator!=(const char *aCString) const { return !(*this == aCString); } 154 155 /** 156 * Overloads operator `==` to evaluate whether or not two `String` are equal. 157 * 158 * @param[in] aString The other string to compare with. 159 * 160 * @retval TRUE If the two strings are equal. 161 * @retval FALSE If the two strings are not equal. 162 */ operator ==(const String & aString) const163 bool operator==(const String &aString) const { return (*this == aString.AsCString()); } 164 165 String(const String &) = delete; 166 String &operator=(const String &) = delete; 167 168 private: 169 char *mStringBuffer; 170 }; 171 172 } // namespace Heap 173 } // namespace ot 174 175 #endif // HEAP_STRING_HPP_ 176