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_TSL_PLATFORM_CTSTRING_H_ |
17 | #define TENSORFLOW_TSL_PLATFORM_CTSTRING_H_ |
18 | |
19 | #include <stdint.h> |
20 | #include <stdlib.h> |
21 | |
22 | #include "tensorflow/tsl/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 | // Reserve 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 | // Similar to TF_TString_Reserve, except that we ensure amortized growth, i.e. |
47 | // that we grow the capacity by at least a constant factor >1. |
48 | inline void TF_TString_ReserveAmortized(TF_TString *str, size_t new_cap); |
49 | |
50 | // Returns the size of the string. |
51 | inline size_t TF_TString_GetSize(const TF_TString *str); |
52 | // Returns the capacity of the string buffer. It should not be considered safe |
53 | // to write in the region between size and capacity---call Resize or |
54 | // ResizeUninitialized before doing so. |
55 | inline size_t TF_TString_GetCapacity(const TF_TString *str); |
56 | // Returns the underlying type of the tstring: |
57 | // TF_TSTR_SMALL: |
58 | // Small string optimization; the contents of strings |
59 | // less than 22-bytes are stored in the TF_TString struct. This avoids any |
60 | // heap allocations. |
61 | // TF_TSTR_LARGE: |
62 | // Heap allocated string. |
63 | // TF_TSTR_OFFSET: (currently unused) |
64 | // An offset defined string. The string buffer begins at an internally |
65 | // defined little-endian offset from `str'; i.e. GetDataPointer() = str + |
66 | // offset. This type is useful for memory mapping or reading string tensors |
67 | // directly from file, without the need to deserialize the data. For |
68 | // security reasons, it is imperative that OFFSET based string tensors are |
69 | // validated before use, or are from a trusted source. |
70 | // TF_TSTR_VIEW: |
71 | // A view into an unowned character string. |
72 | // |
73 | // NOTE: |
74 | // VIEW and OFFSET types are immutable, so any modifcation via Append, |
75 | // AppendN, or GetMutableDataPointer of a VIEW/OFFSET based tstring will |
76 | // result in a conversion to an owned type (SMALL/LARGE). |
77 | inline TF_TString_Type TF_TString_GetType(const TF_TString *str); |
78 | |
79 | // Returns a const char pointer to the start of the underlying string. The |
80 | // underlying character buffer may not be null-terminated. |
81 | inline const char *TF_TString_GetDataPointer(const TF_TString *str); |
82 | // Returns a char pointer to a mutable representation of the underlying string. |
83 | // In the case of VIEW and OFFSET types, `src' is converted to an owned type |
84 | // (SMALL/LARGE). The underlying character buffer may not be null-terminated. |
85 | inline char *TF_TString_GetMutableDataPointer(TF_TString *str); |
86 | |
87 | // Sets `dst' as a VIEW type to `src'. `dst' will not take ownership of `src'. |
88 | // It is the user's responsibility to ensure that the lifetime of `src' exceeds |
89 | // `dst'. Any mutations to `dst' via Append, AppendN, or GetMutableDataPointer, |
90 | // will result in a copy into an owned SMALL or LARGE type, and will not modify |
91 | // `src'. |
92 | inline void TF_TString_AssignView(TF_TString *dst, const char *src, |
93 | size_t size); |
94 | |
95 | // Appends `src' onto `dst'. If `dst' is a VIEW or OFFSET type, it will first |
96 | // be converted to an owned LARGE or SMALL type. `dst' should not point to |
97 | // memory owned by `src'. |
98 | inline void TF_TString_Append(TF_TString *dst, const TF_TString *src); |
99 | inline void TF_TString_AppendN(TF_TString *dst, const char *src, size_t size); |
100 | |
101 | // Copy/Move/Assign semantics |
102 | // |
103 | // | src | dst | complexity |
104 | // Copy | * | SMALL/LARGE | fixed/O(size) |
105 | // Assign | SMALL | SMALL | fixed |
106 | // Assign | OFFSET | VIEW | fixed |
107 | // Assign | VIEW | VIEW | fixed |
108 | // Assign | LARGE | LARGE | O(size) |
109 | // Move | * | same as src | fixed |
110 | |
111 | // Copies `src' to `dst'. `dst' will be an owned type (SMALL/LARGE). `src' |
112 | // should not point to memory owned by `dst'. |
113 | inline void TF_TString_Copy(TF_TString *dst, const char *src, size_t size); |
114 | // Assigns a `src' tstring to `dst'. An OFFSET `src' type will yield a `VIEW' |
115 | // `dst'. LARGE `src' types will be copied to a new buffer; all other `src' |
116 | // types will incur a fixed cost. |
117 | inline void TF_TString_Assign(TF_TString *dst, const TF_TString *src); |
118 | // Moves a `src' tstring to `dst'. Moving a LARGE `src' to `dst' will result in |
119 | // a valid but unspecified `src'. This function incurs a fixed cost for all |
120 | // inputs. |
121 | inline void TF_TString_Move(TF_TString *dst, TF_TString *src); |
122 | |
123 | #endif // TENSORFLOW_TSL_PLATFORM_CTSTRING_H_ |
124 | |