1 /* Copyright 2015 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 // #status: RECOMMENDED
17 // #category: operations on strings
18 // #summary: Merges strings or numbers with no delimiter.
19 //
20 #ifndef TENSORFLOW_CORE_LIB_STRINGS_STRCAT_H_
21 #define TENSORFLOW_CORE_LIB_STRINGS_STRCAT_H_
22
23 #include <string>
24
25 #include "tensorflow/core/lib/core/stringpiece.h"
26 #include "tensorflow/core/lib/strings/numbers.h"
27 #include "tensorflow/core/platform/macros.h"
28 #include "tensorflow/core/platform/types.h"
29
30 // The AlphaNum type was designed to be used as the parameter type for StrCat().
31 // Any routine accepting either a string or a number may accept it.
32 // The basic idea is that by accepting a "const AlphaNum &" as an argument
33 // to your function, your callers will automatically convert bools, integers,
34 // and floating point values to strings for you.
35 //
36 // NOTE: Use of AlphaNum outside of the //strings package is unsupported except
37 // for the specific case of function parameters of type "AlphaNum" or "const
38 // AlphaNum &". In particular, instantiating AlphaNum directly as a stack
39 // variable is not supported.
40 //
41 // Conversion from 8-bit values is not accepted because if it were, then an
42 // attempt to pass ':' instead of ":" might result in a 58 ending up in your
43 // result.
44 //
45 // Bools convert to "0" or "1".
46 //
47 // Floating point values are converted to a string which, if passed to strtod(),
48 // would produce the exact same original double (except in case of NaN; all NaNs
49 // are considered the same value). We try to keep the string short but it's not
50 // guaranteed to be as short as possible.
51 //
52 // You can convert to Hexadecimal output rather than Decimal output using Hex.
53 // To do this, pass strings::Hex(my_int) as a parameter to StrCat. You may
54 // specify a minimum field width using a separate parameter, so the equivalent
55 // of Printf("%04x", my_int) is StrCat(Hex(my_int, strings::ZERO_PAD_4))
56 //
57 // This class has implicit constructors.
58 namespace tensorflow {
59 namespace strings {
60
61 enum PadSpec {
62 kNoPad = 1,
63 kZeroPad2,
64 kZeroPad3,
65 kZeroPad4,
66 kZeroPad5,
67 kZeroPad6,
68 kZeroPad7,
69 kZeroPad8,
70 kZeroPad9,
71 kZeroPad10,
72 kZeroPad11,
73 kZeroPad12,
74 kZeroPad13,
75 kZeroPad14,
76 kZeroPad15,
77 kZeroPad16
78 };
79
80 struct Hex {
81 uint64 value;
82 enum PadSpec spec;
83 template <class Int>
specHex84 explicit Hex(Int v, PadSpec s = kNoPad) : spec(s) {
85 // Prevent sign-extension by casting integers to
86 // their unsigned counterparts.
87 static_assert(
88 sizeof(v) == 1 || sizeof(v) == 2 || sizeof(v) == 4 || sizeof(v) == 8,
89 "Unknown integer type");
90 value = sizeof(v) == 1
91 ? static_cast<uint8>(v)
92 : sizeof(v) == 2 ? static_cast<uint16>(v)
93 : sizeof(v) == 4 ? static_cast<uint32>(v)
94 : static_cast<uint64>(v);
95 }
96 };
97
98 class AlphaNum {
99 public:
100 // No bool ctor -- bools convert to an integral type.
101 // A bool ctor would also convert incoming pointers (bletch).
102
AlphaNum(int i32)103 AlphaNum(int i32) // NOLINT(runtime/explicit)
104 : piece_(digits_, FastInt32ToBufferLeft(i32, digits_)) {}
AlphaNum(unsigned int u32)105 AlphaNum(unsigned int u32) // NOLINT(runtime/explicit)
106 : piece_(digits_, FastUInt32ToBufferLeft(u32, digits_)) {}
AlphaNum(long x)107 AlphaNum(long x) // NOLINT(runtime/explicit)
108 : piece_(digits_, FastInt64ToBufferLeft(x, digits_)) {}
AlphaNum(unsigned long x)109 AlphaNum(unsigned long x) // NOLINT(runtime/explicit)
110 : piece_(digits_, FastUInt64ToBufferLeft(x, digits_)) {}
AlphaNum(long long int i64)111 AlphaNum(long long int i64) // NOLINT(runtime/explicit)
112 : piece_(digits_, FastInt64ToBufferLeft(i64, digits_)) {}
AlphaNum(unsigned long long int u64)113 AlphaNum(unsigned long long int u64) // NOLINT(runtime/explicit)
114 : piece_(digits_, FastUInt64ToBufferLeft(u64, digits_)) {}
115
AlphaNum(float f)116 AlphaNum(float f) // NOLINT(runtime/explicit)
117 : piece_(digits_, FloatToBuffer(f, digits_)) {}
AlphaNum(double f)118 AlphaNum(double f) // NOLINT(runtime/explicit)
119 : piece_(digits_, DoubleToBuffer(f, digits_)) {}
120
121 AlphaNum(Hex hex); // NOLINT(runtime/explicit)
122
AlphaNum(const char * c_str)123 AlphaNum(const char *c_str) : piece_(c_str) {} // NOLINT(runtime/explicit)
AlphaNum(const StringPiece & pc)124 AlphaNum(const StringPiece &pc) : piece_(pc) {} // NOLINT(runtime/explicit)
AlphaNum(const tensorflow::string & str)125 AlphaNum(const tensorflow::string &str) // NOLINT(runtime/explicit)
126 : piece_(str) {}
127 template <typename A>
AlphaNum(const std::basic_string<char,std::char_traits<char>,A> & str)128 AlphaNum(const std::basic_string<char, std::char_traits<char>, A> &str)
129 : piece_(str) {} // NOLINT(runtime/explicit)
130
size()131 StringPiece::size_type size() const { return piece_.size(); }
data()132 const char *data() const { return piece_.data(); }
Piece()133 StringPiece Piece() const { return piece_; }
134
135 private:
136 StringPiece piece_;
137 char digits_[kFastToBufferSize];
138
139 // Use ":" not ':'
140 AlphaNum(char c); // NOLINT(runtime/explicit)
141
142 TF_DISALLOW_COPY_AND_ASSIGN(AlphaNum);
143 };
144
145 // ----------------------------------------------------------------------
146 // StrCat()
147 // This merges the given strings or numbers, with no delimiter. This
148 // is designed to be the fastest possible way to construct a string out
149 // of a mix of raw C strings, StringPieces, strings, bool values,
150 // and numeric values.
151 //
152 // Don't use this for user-visible strings. The localization process
153 // works poorly on strings built up out of fragments.
154 //
155 // For clarity and performance, don't use StrCat when appending to a
156 // string. In particular, avoid using any of these (anti-)patterns:
157 // str.append(StrCat(...))
158 // str += StrCat(...)
159 // str = StrCat(str, ...)
160 // where the last is the worse, with the potential to change a loop
161 // from a linear time operation with O(1) dynamic allocations into a
162 // quadratic time operation with O(n) dynamic allocations. StrAppend
163 // is a better choice than any of the above, subject to the restriction
164 // of StrAppend(&str, a, b, c, ...) that none of the a, b, c, ... may
165 // be a reference into str.
166 // ----------------------------------------------------------------------
167
168 // For performance reasons, we have specializations for <= 4 args.
169 string StrCat(const AlphaNum &a) TF_MUST_USE_RESULT;
170 string StrCat(const AlphaNum &a, const AlphaNum &b) TF_MUST_USE_RESULT;
171 string StrCat(const AlphaNum &a, const AlphaNum &b,
172 const AlphaNum &c) TF_MUST_USE_RESULT;
173 string StrCat(const AlphaNum &a, const AlphaNum &b, const AlphaNum &c,
174 const AlphaNum &d) TF_MUST_USE_RESULT;
175
176 namespace internal {
177
178 // Do not call directly - this is not part of the public API.
179 string CatPieces(std::initializer_list<StringPiece> pieces);
180 void AppendPieces(string *dest, std::initializer_list<StringPiece> pieces);
181
182 } // namespace internal
183
184 // Support 5 or more arguments
185 template <typename... AV>
186 string StrCat(const AlphaNum &a, const AlphaNum &b, const AlphaNum &c,
187 const AlphaNum &d, const AlphaNum &e,
188 const AV &... args) TF_MUST_USE_RESULT;
189
190 template <typename... AV>
StrCat(const AlphaNum & a,const AlphaNum & b,const AlphaNum & c,const AlphaNum & d,const AlphaNum & e,const AV &...args)191 string StrCat(const AlphaNum &a, const AlphaNum &b, const AlphaNum &c,
192 const AlphaNum &d, const AlphaNum &e, const AV &... args) {
193 return internal::CatPieces({a.Piece(), b.Piece(), c.Piece(), d.Piece(),
194 e.Piece(),
195 static_cast<const AlphaNum &>(args).Piece()...});
196 }
197
198 // ----------------------------------------------------------------------
199 // StrAppend()
200 // Same as above, but adds the output to the given string.
201 // WARNING: For speed, StrAppend does not try to check each of its input
202 // arguments to be sure that they are not a subset of the string being
203 // appended to. That is, while this will work:
204 //
205 // string s = "foo";
206 // s += s;
207 //
208 // This will not (necessarily) work:
209 //
210 // string s = "foo";
211 // StrAppend(&s, s);
212 //
213 // Note: while StrCat supports appending up to 26 arguments, StrAppend
214 // is currently limited to 9. That's rarely an issue except when
215 // automatically transforming StrCat to StrAppend, and can easily be
216 // worked around as consecutive calls to StrAppend are quite efficient.
217 // ----------------------------------------------------------------------
218
219 void StrAppend(string *dest, const AlphaNum &a);
220 void StrAppend(string *dest, const AlphaNum &a, const AlphaNum &b);
221 void StrAppend(string *dest, const AlphaNum &a, const AlphaNum &b,
222 const AlphaNum &c);
223 void StrAppend(string *dest, const AlphaNum &a, const AlphaNum &b,
224 const AlphaNum &c, const AlphaNum &d);
225
226 // Support 5 or more arguments
227 template <typename... AV>
StrAppend(string * dest,const AlphaNum & a,const AlphaNum & b,const AlphaNum & c,const AlphaNum & d,const AlphaNum & e,const AV &...args)228 inline void StrAppend(string *dest, const AlphaNum &a, const AlphaNum &b,
229 const AlphaNum &c, const AlphaNum &d, const AlphaNum &e,
230 const AV &... args) {
231 internal::AppendPieces(dest,
232 {a.Piece(), b.Piece(), c.Piece(), d.Piece(), e.Piece(),
233 static_cast<const AlphaNum &>(args).Piece()...});
234 }
235
236 } // namespace strings
237 } // namespace tensorflow
238
239 #endif // TENSORFLOW_CORE_LIB_STRINGS_STRCAT_H_
240