1/* Copyright 2019 The TensorFlow Authors. All Rights Reserved.
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7 http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations 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.
26inline void TF_TString_Init(TF_TString *str);
27// Deallocate a tstring.
28inline 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'.
33inline 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.
38inline 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.
45inline 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.
48inline void TF_TString_ReserveAmortized(TF_TString *str, size_t new_cap);
49
50// Returns the size of the string.
51inline 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.
55inline 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).
77inline 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.
81inline 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.
85inline 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'.
92inline 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'.
98inline void TF_TString_Append(TF_TString *dst, const TF_TString *src);
99inline 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'.
113inline 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.
117inline 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.
121inline void TF_TString_Move(TF_TString *dst, TF_TString *src);
122
123#endif // TENSORFLOW_TSL_PLATFORM_CTSTRING_H_
124