1 /* Copyright 2019 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 #ifndef TENSORFLOW_CORE_PLATFORM_CTSTRING_H_ 17 #define TENSORFLOW_CORE_PLATFORM_CTSTRING_H_ 18 19 #include <stdint.h> 20 #include <stdlib.h> 21 22 #include "tensorflow/core/platform/ctstring_internal.h" 23 24 // Initialize a new tstring. This must be called before using any function 25 // below. 26 inline void TF_TString_Init(TF_TString *str); 27 // Deallocate a tstring. 28 inline void TF_TString_Dealloc(TF_TString *str); 29 30 // Resizes `str' to `new_size'. This function will appropriately grow or shrink 31 // the string buffer to fit a `new_size' string. Grown regions of the string 32 // will be initialized with `c'. 33 inline char *TF_TString_Resize(TF_TString *str, size_t new_size, char c); 34 // Similar to TF_TString_Resize, except the newly allocated regions will remain 35 // uninitialized. This is useful if you plan on overwriting the newly grown 36 // regions immediately after allocation; doing so will elide a superfluous 37 // initialization of the new buffer. 38 inline char *TF_TString_ResizeUninitialized(TF_TString *str, size_t new_size); 39 // Reserves a string buffer with a capacity of at least `new_cap'. 40 // ResizeUninitialized will not change the size, or the contents of the existing 41 // string. This is useful if you have a rough idea of `str's upperbound in 42 // size, and want to avoid allocations as you append to `str'. It should not be 43 // considered safe to write in the region between size and capacity; explicitly 44 // resize before doing so. 45 inline void TF_TString_Reserve(TF_TString *str, size_t new_cap); 46 47 // Returns the size of the string. 48 inline size_t TF_TString_GetSize(const TF_TString *str); 49 // Returns the capacity of the string buffer. It should not be considered safe 50 // to write in the region between size and capacity---call Resize or 51 // ResizeUninitialized before doing so. 52 inline size_t TF_TString_GetCapacity(const TF_TString *str); 53 // Returns the underlying type of the tstring: 54 // TF_TSTR_SMALL: 55 // Small string optimization; the contents of strings 56 // less than 22-bytes are stored in the TF_TString struct. This avoids any 57 // heap allocations. 58 // TF_TSTR_LARGE: 59 // Heap allocated string. 60 // TF_TSTR_OFFSET: (currently unused) 61 // An offset defined string. The string buffer begins at an internally 62 // defined little-endian offset from `str'; i.e. GetDataPointer() = str + 63 // offset. This type is useful for memory mapping or reading string tensors 64 // directly from file, without the need to deserialize the data. For 65 // security reasons, it is imperative that OFFSET based string tensors are 66 // validated before use, or are from a trusted source. 67 // TF_TSTR_VIEW: 68 // A view into an unowned character string. 69 // 70 // NOTE: 71 // VIEW and OFFSET types are immutable, so any modifcation via Append, 72 // AppendN, or GetMutableDataPointer of a VIEW/OFFSET based tstring will 73 // result in a conversion to an owned type (SMALL/LARGE). 74 inline TF_TString_Type TF_TString_GetType(const TF_TString *str); 75 76 // Returns a const char pointer to the start of the underlying string. The 77 // underlying character buffer may not be null-terminated. 78 inline const char *TF_TString_GetDataPointer(const TF_TString *str); 79 // Returns a char pointer to a mutable representation of the underlying string. 80 // In the case of VIEW and OFFSET types, `src' is converted to an owned type 81 // (SMALL/LARGE). The underlying character buffer may not be null-terminated. 82 inline char *TF_TString_GetMutableDataPointer(TF_TString *str); 83 84 // Sets `dst' as a VIEW type to `src'. `dst' will not take ownership of `src'. 85 // It is the user's responsibility to ensure that the lifetime of `src' exceeds 86 // `dst'. Any mutations to `dst' via Append, AppendN, or GetMutableDataPointer, 87 // will result in a copy into an owned SMALL or LARGE type, and will not modify 88 // `src'. 89 inline void TF_TString_AssignView(TF_TString *dst, const char *src, 90 size_t size); 91 92 // Appends `src' onto `dst'. If `dst' is a VIEW or OFFSET type, it will first 93 // be converted to an owned LARGE or SMALL type. `dst' should not point to 94 // memory owned by `src'. 95 inline void TF_TString_Append(TF_TString *dst, const TF_TString *src); 96 inline void TF_TString_AppendN(TF_TString *dst, const char *src, size_t size); 97 98 // Copy/Move/Assign semantics 99 // 100 // | src | dst | complexity 101 // Copy | * | SMALL/LARGE | fixed/O(size) 102 // Assign | SMALL | SMALL | fixed 103 // Assign | OFFSET | VIEW | fixed 104 // Assign | VIEW | VIEW | fixed 105 // Assign | LARGE | LARGE | O(size) 106 // Move | * | same as src | fixed 107 108 // Copies `src' to `dst'. `dst' will be an owned type (SMALL/LARGE). `src' 109 // should not point to memory owned by `dst'. 110 inline void TF_TString_Copy(TF_TString *dst, const char *src, size_t size); 111 // Assigns a `src' tstring to `dst'. An OFFSET `src' type will yield a `VIEW' 112 // `dst'. LARGE `src' types will be copied to a new buffer; all other `src' 113 // types will incur a fixed cost. 114 inline void TF_TString_Assign(TF_TString *dst, const TF_TString *src); 115 // Moves a `src' tstring to `dst'. Moving a LARGE `src' to `dst' will result in 116 // a valid but unspecified `src'. This function incurs a fixed cost for all 117 // inputs. 118 inline void TF_TString_Move(TF_TString *dst, TF_TString *src); 119 120 #endif // TENSORFLOW_CORE_PLATFORM_CTSTRING_H_ 121