]>
Commit | Line | Data |
---|---|---|
412da427 | 1 | /* |
412da427 FC |
2 | * SQUID Web Proxy Cache http://www.squid-cache.org/ |
3 | * ---------------------------------------------------------- | |
4 | * | |
5 | * Squid is the result of efforts by numerous individuals from | |
6 | * the Internet community; see the CONTRIBUTORS file for full | |
7 | * details. Many organizations have provided support for Squid's | |
8 | * development; see the SPONSORS file for full details. Squid is | |
9 | * Copyrighted (C) 2001 by the Regents of the University of | |
10 | * California; see the COPYRIGHT file for full details. Squid | |
11 | * incorporates software developed and/or copyrighted by other | |
12 | * sources; see the CREDITS file for full details. | |
13 | * | |
14 | * This program is free software; you can redistribute it and/or modify | |
15 | * it under the terms of the GNU General Public License as published by | |
16 | * the Free Software Foundation; either version 2 of the License, or | |
17 | * (at your option) any later version. | |
18 | * | |
19 | * This program is distributed in the hope that it will be useful, | |
20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
22 | * GNU General Public License for more details. | |
23 | * | |
24 | * You should have received a copy of the GNU General Public License | |
25 | * along with this program; if not, write to the Free Software | |
26 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. | |
27 | */ | |
28 | ||
29 | #ifndef SQUID_SBUF_H | |
30 | #define SQUID_SBUF_H | |
31 | ||
32 | #include "base/InstanceId.h" | |
412da427 | 33 | #include "MemBlob.h" |
62842d40 | 34 | #include "SBufExceptions.h" |
412da427 FC |
35 | #include "SquidString.h" |
36 | ||
62842d40 FC |
37 | #if HAVE_CLIMITS |
38 | #include <climits> | |
39 | #elif HAVE_LIMITS_H | |
40 | #include <limits.h> | |
41 | #endif | |
412da427 FC |
42 | #if HAVE_UNISTD_H |
43 | #include <unistd.h> | |
44 | #endif | |
45 | #if HAVE_STDARG_H | |
46 | #include <stdarg.h> | |
47 | #endif | |
48 | #if HAVE_IOSFWD | |
49 | #include <iosfwd> | |
50 | #endif | |
51 | ||
496a9e97 | 52 | /* SBuf placeholder for printf */ |
412da427 FC |
53 | #ifndef SQUIDSBUFPH |
54 | #define SQUIDSBUFPH "%.*s" | |
55 | #define SQUIDSBUFPRINT(s) (s).plength(),(s).rawContent() | |
56 | #endif /* SQUIDSBUFPH */ | |
57 | ||
6a17a36d | 58 | // TODO: move within SBuf and rename |
412da427 FC |
59 | typedef enum { |
60 | caseSensitive, | |
61 | caseInsensitive | |
62 | } SBufCaseSensitive; | |
63 | ||
64 | /** | |
65 | * Container for various SBuf class-wide statistics. | |
66 | * | |
67 | * The stats are not completely accurate; they're mostly meant to | |
68 | * understand whether Squid is leaking resources | |
69 | * and whether SBuf is paying off the expected gains. | |
70 | */ | |
71 | class SBufStats | |
72 | { | |
73 | public: | |
7cbd3256 FC |
74 | uint64_t alloc; ///<number of calls to SBuf constructors |
75 | uint64_t allocCopy; ///<number of calls to SBuf copy-constructor | |
76 | uint64_t allocFromString; ///<number of copy-allocations from Strings | |
77 | uint64_t allocFromCString; ///<number of copy-allocations from c-strings | |
78 | uint64_t assignFast; ///<number of no-copy assignment operations | |
79 | uint64_t clear; ///<number of clear operations | |
80 | uint64_t append; ///<number of append operations | |
81 | uint64_t toStream; ///<number of write operations to ostreams | |
82 | uint64_t setChar; ///<number of calls to setAt | |
83 | uint64_t getChar; ///<number of calls to at() and operator[] | |
84 | uint64_t compareSlow; ///<number of comparison operations requiring data scan | |
85 | uint64_t compareFast; ///<number of comparison operations not requiring data scan | |
86 | uint64_t copyOut; ///<number of data-copies to other forms of buffers | |
87 | uint64_t rawAccess; ///<number of accesses to raw contents | |
88 | uint64_t chop; ///<number of chop operations | |
89 | uint64_t trim; ///<number of trim operations | |
90 | uint64_t find; ///<number of find operations | |
91 | uint64_t scanf; ///<number of scanf operations | |
92 | uint64_t caseChange; ///<number of toUpper and toLower operations | |
93 | uint64_t cowFast; ///<number of cow operations not actually requiring a copy | |
94 | uint64_t cowSlow; ///<number of cow operations requiring a copy | |
95 | uint64_t live; ///<number of currently-allocated SBuf | |
412da427 | 96 | |
496a9e97 | 97 | ///Dump statistics to an ostream. |
412da427 FC |
98 | std::ostream& dump(std::ostream &os) const; |
99 | SBufStats(); | |
100 | ||
101 | SBufStats& operator +=(const SBufStats&); | |
102 | }; | |
103 | ||
4685b0c4 FC |
104 | class CharacterSet; |
105 | ||
412da427 FC |
106 | /** |
107 | * A String or Buffer. | |
108 | * Features: refcounted backing store, cheap copy and sub-stringing | |
109 | * operations, copy-on-write to isolate change operations to each instance. | |
110 | * Where possible, we're trying to mimic std::string's interface. | |
111 | */ | |
112 | class SBuf | |
113 | { | |
114 | public: | |
7cbd3256 | 115 | typedef MemBlob::size_type size_type; |
50827187 | 116 | static const size_type npos = 0xffffffff; // max(uint32_t) |
412da427 FC |
117 | |
118 | /// Maximum size of a SBuf. By design it MUST be < MAX(size_type)/2. Currently 256Mb. | |
119 | static const size_type maxSize = 0xfffffff; | |
120 | ||
121 | /// create an empty (zero-size) SBuf | |
122 | SBuf(); | |
123 | SBuf(const SBuf &S); | |
124 | ||
125 | /** Constructor: import c-style string | |
126 | * | |
127 | * Create a new SBuf containing a COPY of the contents of the | |
128 | * c-string | |
129 | * \param S the c string to be copied | |
7cbd3256 | 130 | * \param n how many bytes to import into the SBuf. If it is npos |
412da427 FC |
131 | * or unspecified, imports to end-of-cstring |
132 | * \note it is the caller's responsibility not to go out of bounds | |
50827187 | 133 | * \note bounds is 0 <= pos < length(); caller must pay attention to signedness |
412da427 | 134 | */ |
7cbd3256 | 135 | explicit SBuf(const char *S, size_type n = npos); |
412da427 FC |
136 | |
137 | /** Constructor: import SquidString, copying contents. | |
138 | * | |
139 | * This method will be removed once SquidString has gone. | |
140 | */ | |
496a9e97 FC |
141 | explicit SBuf(const String &S); |
142 | ||
143 | /// Constructor: import std::string. Contents are copied. | |
144 | explicit SBuf(const std::string &s); | |
412da427 FC |
145 | |
146 | ~SBuf(); | |
62842d40 | 147 | |
412da427 FC |
148 | /** Explicit assignment. |
149 | * | |
150 | * Current SBuf will share backing store with the assigned one. | |
151 | */ | |
152 | SBuf& assign(const SBuf &S); | |
62842d40 | 153 | |
412da427 FC |
154 | /** Assignment operator. |
155 | * | |
156 | * Current SBuf will share backing store with the assigned one. | |
157 | */ | |
62842d40 | 158 | SBuf& operator =(const SBuf & S) {return assign(S);} |
412da427 FC |
159 | |
160 | /** Import a c-string into a SBuf, copying the data. | |
161 | * | |
162 | * It is the caller's duty to free the imported string, if needed. | |
163 | * \param S the c string to be copied | |
7cbd3256 | 164 | * \param n how many bytes to import into the SBuf. If it is npos |
412da427 FC |
165 | * or unspecified, imports to end-of-cstring |
166 | * \note it is the caller's responsibility not to go out of bounds | |
7cbd3256 FC |
167 | * \note to assign a std::string use the pattern: |
168 | * assign(stdstr.data(), stdstd.length()) | |
412da427 | 169 | */ |
7cbd3256 | 170 | SBuf& assign(const char *S, size_type n = npos); |
412da427 FC |
171 | |
172 | /** Assignment operator. Copy a NULL-terminated c-style string into a SBuf. | |
173 | * | |
174 | * Copy a c-style string into a SBuf. Shortcut for SBuf.assign(S) | |
175 | * It is the caller's duty to free the imported string, if needed. | |
7cbd3256 | 176 | * \note not \0-clean |
412da427 | 177 | */ |
62842d40 | 178 | SBuf& operator =(const char *S) {return assign(S);} |
412da427 | 179 | |
412da427 FC |
180 | /** reset the SBuf as if it was just created. |
181 | * | |
182 | * Resets the SBuf to empty, memory is freed lazily. | |
183 | */ | |
184 | void clear(); | |
185 | ||
186 | /** Append operation | |
187 | * | |
188 | * Append the supplied SBuf to the current one; extend storage as needed. | |
189 | */ | |
190 | SBuf& append(const SBuf & S); | |
191 | ||
192 | /** Append operation for C-style strings. | |
193 | * | |
194 | * Append the supplied c-string to the SBuf; extend storage | |
195 | * as needed. | |
196 | * | |
197 | * \param S the c string to be copied. Can be NULL. | |
a452bc8b FC |
198 | * \param Ssize how many bytes to import into the SBuf. If it is npos |
199 | * or unspecified, imports to end-of-cstring. If S is NULL, | |
200 | * Ssize is ignored. | |
7cbd3256 FC |
201 | * \note to append a std::string use the pattern |
202 | * cstr_append(stdstr.data(), stdstd.length()) | |
412da427 | 203 | */ |
7cbd3256 | 204 | SBuf& append(const char * S, size_type Ssize = npos); |
412da427 FC |
205 | |
206 | /** Assignment operation with printf(3)-style definition | |
207 | * \note arguments may be evaluated more than once, be careful | |
208 | * of side-effects | |
209 | */ | |
210 | SBuf& Printf(const char *fmt, ...); | |
211 | ||
212 | /** Append operation with printf-style arguments | |
213 | * \note arguments may be evaluated more than once, be careful | |
214 | * of side-effects | |
215 | */ | |
216 | SBuf& appendf(const char *fmt, ...); | |
496a9e97 | 217 | |
412da427 FC |
218 | /** Append operation, with vsprintf(3)-style arguments. |
219 | * \note arguments may be evaluated more than once, be careful | |
220 | * of side-effects | |
221 | */ | |
222 | SBuf& vappendf(const char *fmt, va_list vargs); | |
223 | ||
496a9e97 | 224 | /// print the SBuf contents to the supplied ostream |
412da427 FC |
225 | std::ostream& print(std::ostream &os) const; |
226 | ||
496a9e97 | 227 | /** print SBuf contents and debug information about the SBuf to an ostream |
412da427 FC |
228 | * |
229 | * Debug function, dumps to a stream informations on the current SBuf, | |
230 | * including low-level details and statistics. | |
231 | */ | |
232 | std::ostream& dump(std::ostream &os) const; | |
233 | ||
234 | /** random-access read to any char within the SBuf | |
235 | * | |
236 | * does not check access bounds. If you need that, use at() | |
237 | */ | |
fdd1982c | 238 | char operator [](size_type pos) const {++stats.getChar; return store_->mem[off_+pos];} |
412da427 FC |
239 | |
240 | /** random-access read to any char within the SBuf. | |
241 | * | |
242 | * \throw OutOfBoundsException when access is out of bounds | |
50827187 | 243 | * \note bounds is 0 <= pos < length(); caller must pay attention to signedness |
412da427 | 244 | */ |
fdd1982c | 245 | char at(size_type pos) const {checkAccessBounds(pos); return operator[](pos);} |
412da427 FC |
246 | |
247 | /** direct-access set a byte at a specified operation. | |
248 | * | |
249 | * \param pos the position to be overwritten | |
250 | * \param toset the value to be written | |
251 | * \throw OutOfBoundsException when pos is of bounds | |
50827187 | 252 | * \note bounds is 0 <= pos < length(); caller must pay attention to signedness |
412da427 FC |
253 | * \note performs a copy-on-write if needed. |
254 | */ | |
255 | void setAt(size_type pos, char toset); | |
256 | ||
257 | /** compare to other SBuf, str(case)cmp-style | |
258 | * | |
259 | * \param isCaseSensitive one of caseSensitive or caseInsensitive | |
7cbd3256 | 260 | * \param n compare up to this many bytes. if npos (default), compare whole SBufs |
412da427 FC |
261 | * \retval >0 argument of the call is greater than called SBuf |
262 | * \retval <0 argument of the call is smaller than called SBuf | |
263 | * \retval 0 argument of the call has the same contents of called SBuf | |
264 | */ | |
7cbd3256 FC |
265 | int compare(const SBuf &S, SBufCaseSensitive isCaseSensitive, size_type n = npos) const; |
266 | ||
267 | /// shorthand version for compare | |
268 | inline int cmp(const SBuf &S, size_type n = npos) const { | |
269 | return compare(S,caseSensitive,n); | |
270 | } | |
271 | ||
272 | /// shorthand version for case-insensitive comparison | |
273 | inline int caseCmp(const SBuf &S, size_type n = npos) const { | |
274 | return compare(S,caseInsensitive,n); | |
275 | } | |
412da427 FC |
276 | |
277 | /** check whether the entire supplied argument is a prefix of the SBuf. | |
278 | * \param S the prefix to match against | |
279 | * \param isCaseSensitive one of caseSensitive or caseInsensitive | |
280 | * \retval true argument is a prefix of the SBuf | |
281 | */ | |
282 | bool startsWith(const SBuf &S, SBufCaseSensitive isCaseSensitive = caseSensitive) const; | |
283 | ||
412da427 FC |
284 | bool operator ==(const SBuf & S) const; |
285 | bool operator !=(const SBuf & S) const; | |
7cbd3256 FC |
286 | bool operator <(const SBuf &S) const {return (cmp(S) < 0);} |
287 | bool operator >(const SBuf &S) const {return (cmp(S) > 0);} | |
288 | bool operator <=(const SBuf &S) const {return (cmp(S) <= 0);} | |
289 | bool operator >=(const SBuf &S) const {return (cmp(S) >= 0);} | |
412da427 FC |
290 | |
291 | /** Consume bytes at the head of the SBuf | |
292 | * | |
293 | * Consume N chars at SBuf head, or to SBuf's end, | |
294 | * whichever is shorter. If more bytes are consumed than available, | |
295 | * the SBuf is emptied | |
296 | * \param n how many bytes to remove; could be zero. | |
7cbd3256 | 297 | * npos (or no argument) means 'to the end of SBuf' |
412da427 FC |
298 | * \return a new SBuf containing the consumed bytes. |
299 | */ | |
300 | SBuf consume(size_type n = npos); | |
301 | ||
496a9e97 | 302 | /// gets global statistic informations |
412da427 FC |
303 | static const SBufStats& GetStats(); |
304 | ||
305 | /** Copy SBuf contents into user-supplied C buffer. | |
306 | * | |
307 | * Export a copy of the SBuf's contents into the user-supplied | |
308 | * buffer, up to the user-supplied-length. No zero-termination is performed | |
309 | * \return num the number of actually-copied chars. | |
310 | */ | |
311 | size_type copy(char *dest, size_type n) const; | |
312 | ||
313 | /** exports a pointer to the SBuf internal storage. | |
314 | * \warning ACCESSING RAW STORAGE IS DANGEROUS! | |
315 | * | |
496a9e97 FC |
316 | * Returns a ead-only pointer to SBuf's content. No terminating null |
317 | * character is appended (use c_str() for that). | |
412da427 FC |
318 | * The returned value points to an internal location whose contents |
319 | * are guaranteed to remain unchanged only until the next call | |
320 | * to a non-constant member function of the SBuf object. Such a | |
321 | * call may be implicit (e.g., when SBuf is destroyed | |
322 | * upon leaving the current context). | |
323 | * This is a very UNSAFE way of accessing the data. | |
324 | * This call never returns NULL. | |
325 | * \see c_str | |
326 | * \note the memory management system guarantees that the exported region | |
327 | * of memory will remain valid if the caller keeps holding | |
328 | * a valid reference to the SBuf object and does not write or append to | |
329 | * it. For example: | |
330 | * \code | |
331 | * SBuf foo("some string"); | |
332 | * const char *bar = foo.rawContent(); | |
333 | * doSomething(bar); //safe | |
334 | * foo.append(" other string"); | |
335 | * doSomething(bar); //unsafe | |
336 | * \endcode | |
337 | */ | |
338 | const char* rawContent() const; | |
339 | ||
340 | /** Exports a writable pointer to the SBuf internal storage. | |
341 | * \warning Use with EXTREME caution, this is a dangerous operation. | |
342 | * | |
343 | * Returns a pointer to the first unused byte in the SBuf's storage, | |
ac7947fd FC |
344 | * which can be be used for appending. At least minSize bytes will |
345 | * be available for writing. | |
346 | * The returned pointer must not be stored by the caller, as it will | |
496a9e97 | 347 | * be invalidated by the first call to a non-const method call |
412da427 | 348 | * on the SBuf. |
ac7947fd | 349 | * This call guarantees to never return NULL. |
8aa34dad FC |
350 | * \see reserveSpace |
351 | * \note Unlike reserveSpace(), this method does not guarantee exclusive | |
352 | * buffer ownership. It is instead optimized for a one writer | |
353 | * (appender), many readers scenario by avoiding unnecessary | |
354 | * copying and allocations. | |
412da427 FC |
355 | * \throw SBufTooBigException if the user tries to allocate too big a SBuf |
356 | */ | |
ac7947fd | 357 | char *rawSpace(size_type minSize); |
412da427 | 358 | |
50827187 | 359 | /** Obtain how much free space is available in the backing store. |
8aa34dad | 360 | * |
50827187 FC |
361 | * \note: unless the client just cow()ed, it is not guaranteed that |
362 | * the free space can be used. | |
8aa34dad FC |
363 | */ |
364 | size_type spaceSize() const { return store_->spaceSize(); } | |
365 | ||
412da427 FC |
366 | /** Force a SBuf's size |
367 | * \warning use with EXTREME caution, this is a dangerous operation | |
368 | * | |
369 | * Adapt the SBuf internal state after external interference | |
370 | * such as writing into it via rawSpace. | |
7cbd3256 FC |
371 | * \throw TextException if SBuf doesn't have exclusive ownership of store |
372 | * \throw SBufTooBigException if new size is bigger than available store space | |
412da427 FC |
373 | */ |
374 | void forceSize(size_type newSize); | |
375 | ||
376 | /** exports a null-terminated reference to the SBuf internal storage. | |
377 | * \warning ACCESSING RAW STORAGE IS DANGEROUS! DO NOT EVER USE | |
378 | * THE RETURNED POINTER FOR WRITING | |
379 | * | |
380 | * The returned value points to an internal location whose contents | |
381 | * are guaranteed to remain unchanged only until the next call | |
382 | * to a non-constant member function of the SBuf object. Such a | |
383 | * call may be implicit (e.g., when SBuf is destroyed | |
384 | * upon leaving the current context). | |
385 | * This is a very UNSAFE way of accessing the data. | |
386 | * This call never returns NULL. | |
387 | * \see rawContent | |
388 | * \note the memory management system guarantees that the exported region | |
496a9e97 FC |
389 | * of memory will remain valid will remain valid only if the |
390 | * caller keeps holding a valid reference to the SBuf object and | |
391 | * does not write or append to it | |
412da427 FC |
392 | */ |
393 | const char* c_str(); | |
394 | ||
496a9e97 | 395 | /// Returns the number of bytes stored in SBuf. |
62842d40 | 396 | size_type length() const {return len_;} |
412da427 FC |
397 | |
398 | /** Get the length of the SBuf, as a signed integer | |
399 | * | |
400 | * Compatibility function for printf(3) which requires a signed int | |
401 | * \throw SBufTooBigException if the SBuf is too big for a signed integer | |
402 | */ | |
62842d40 FC |
403 | int plength() const { |
404 | if (length()>INT_MAX) | |
405 | throw SBufTooBigException(__FILE__, __LINE__); | |
406 | return static_cast<int>(length()); | |
407 | } | |
412da427 FC |
408 | |
409 | /** Check whether the SBuf is empty | |
410 | * | |
411 | * \return true if length() == 0 | |
412 | */ | |
62842d40 | 413 | bool isEmpty() const {return (len_==0);} |
412da427 | 414 | |
8aa34dad | 415 | /** Request to guarantee the SBuf's free store space. |
412da427 FC |
416 | * |
417 | * After the reserveSpace request, the SBuf is guaranteed to have at | |
7cbd3256 | 418 | * least minSpace bytes of unused backing store following the currently |
ac7947fd | 419 | * used portion and single ownership of the backing store. |
412da427 FC |
420 | * \throw SBufTooBigException if the user tries to allocate too big a SBuf |
421 | */ | |
e842ecce | 422 | void reserveSpace(size_type minSpace) { |
6fd0701a | 423 | Must(minSpace <= maxSize); |
a44b8b80 | 424 | Must(length() <= maxSize - minSpace); |
e842ecce FC |
425 | reserveCapacity(length()+minSpace); |
426 | } | |
412da427 | 427 | |
8aa34dad | 428 | /** Request to guarantee the SBuf's store capacity |
412da427 FC |
429 | * |
430 | * After this method is called, the SBuf is guaranteed to have at least | |
7cbd3256 | 431 | * minCapacity bytes of total buffer size, including the currently-used |
577bcebc FC |
432 | * portion; it is also guaranteed that after this call this SBuf |
433 | * has unique ownership of the underlying memory store. | |
412da427 FC |
434 | * \throw SBufTooBigException if the user tries to allocate too big a SBuf |
435 | */ | |
436 | void reserveCapacity(size_type minCapacity); | |
437 | ||
438 | /** slicing method | |
439 | * | |
496a9e97 FC |
440 | * Removes SBuf prefix and suffix, leaving a sequence of 'n' |
441 | * bytes starting from position 'pos', first byte is at pos 0. | |
442 | * It is an in-place-modifying version of substr. | |
412da427 | 443 | * \param pos start sub-stringing from this byte. If it is |
496a9e97 | 444 | * npos or it is greater than the SBuf length, the SBuf is cleared and |
50827187 | 445 | * an empty SBuf is returned. |
412da427 | 446 | * \param n maximum number of bytes of the resulting SBuf. |
7cbd3256 | 447 | * npos means "to end of SBuf". |
496a9e97 | 448 | * if it is 0, the SBuf is cleared and an empty SBuf is returned. |
496a9e97 FC |
449 | * if it overflows the end of the SBuf, it is capped to the end of SBuf |
450 | * \see substr, trim | |
412da427 FC |
451 | */ |
452 | SBuf& chop(size_type pos, size_type n = npos); | |
453 | ||
454 | /** Remove characters in the toremove set at the beginning, end or both | |
455 | * | |
456 | * \param toremove characters to be removed. Stops chomping at the first | |
457 | * found char not in the set | |
458 | * \param atBeginning if true (default), strips at the beginning of the SBuf | |
459 | * \param atEnd if true (default), strips at the end of the SBuf | |
460 | */ | |
461 | SBuf& trim(const SBuf &toRemove, bool atBeginning = true, bool atEnd = true); | |
462 | ||
463 | /** Extract a part of the current SBuf. | |
464 | * | |
496a9e97 FC |
465 | * Return a fresh a fresh copy of a portion the current SBuf, which is |
466 | * left untouched. The same parameter convetions apply as for chop. | |
467 | * \see trim, chop | |
412da427 FC |
468 | */ |
469 | SBuf substr(size_type pos, size_type n = npos) const; | |
470 | ||
471 | /** Find first occurrence of character in SBuf | |
472 | * | |
473 | * Returns the index in the SBuf of the first occurrence of char c. | |
7cbd3256 | 474 | * \return npos if the char was not found |
412da427 | 475 | * \param startPos if specified, ignore any occurrences before that position |
496a9e97 | 476 | * if startPos is npos or greater than length() npos is always returned |
7cbd3256 | 477 | * if startPos is less than zero, it is ignored |
412da427 FC |
478 | */ |
479 | size_type find(char c, size_type startPos = 0) const; | |
480 | ||
481 | /** Find first occurrence of SBuf in SBuf. | |
482 | * | |
483 | * Returns the index in the SBuf of the first occurrence of the | |
484 | * sequence contained in the str argument. | |
485 | * \param startPos if specified, ignore any occurrences before that position | |
496a9e97 | 486 | * if startPos is npos or greater than length() npos is always returned |
7cbd3256 | 487 | * \return npos if the SBuf was not found |
412da427 FC |
488 | */ |
489 | size_type find(const SBuf & str, size_type startPos = 0) const; | |
490 | ||
491 | /** Find last occurrence of character in SBuf | |
492 | * | |
493 | * Returns the index in the SBuf of the last occurrence of char c. | |
7cbd3256 | 494 | * \return npos if the char was not found |
412da427 | 495 | * \param endPos if specified, ignore any occurrences after that position. |
496a9e97 | 496 | * if npos or greater than length(), the whole SBuf is considered |
412da427 FC |
497 | */ |
498 | size_type rfind(char c, size_type endPos = npos) const; | |
499 | ||
500 | /** Find last occurrence of SBuf in SBuf | |
501 | * | |
502 | * Returns the index in the SBuf of the last occurrence of the | |
503 | * sequence contained in the str argument. | |
7cbd3256 | 504 | * \return npos if the sequence was not found |
412da427 | 505 | * \param endPos if specified, ignore any occurrences after that position |
496a9e97 | 506 | * if npos or greater than length(), the whole SBuf is considered |
412da427 FC |
507 | */ |
508 | size_type rfind(const SBuf &str, size_type endPos = npos) const; | |
509 | ||
510 | /** Find first occurrence of character of set in SBuf | |
511 | * | |
512 | * Finds the first occurrence of ANY of the characters in the supplied set in | |
513 | * the SBuf. | |
7cbd3256 | 514 | * \return npos if no character in the set could be found |
412da427 | 515 | * \param startPos if specified, ignore any occurrences before that position |
7cbd3256 | 516 | * if npos, then npos is always returned |
c8046ec7 FC |
517 | * |
518 | * TODO: rename to camelCase | |
412da427 | 519 | */ |
3c1106a0 FC |
520 | size_type find_first_of(const CharacterSet &set, size_type startPos = 0) const; |
521 | ||
522 | /** Find first occurrence character NOT in character set | |
523 | * | |
c8046ec7 | 524 | * \return npos if all characters in the SBuf are from set |
3c1106a0 FC |
525 | * \param startPos if specified, ignore any occurrences before that position |
526 | * if npos, then npos is always returned | |
c8046ec7 FC |
527 | * |
528 | * TODO: rename to camelCase | |
3c1106a0 FC |
529 | */ |
530 | size_type find_first_not_of(const CharacterSet &set, size_type startPos = 0) const; | |
412da427 FC |
531 | |
532 | /** sscanf-alike | |
533 | * | |
534 | * sscanf re-implementation. Non-const, and not \0-clean. | |
535 | * \return same as sscanf | |
536 | * \see man sscanf(3) | |
537 | */ | |
538 | int scanf(const char *format, ...); | |
539 | ||
540 | /** Lower-case SBuf | |
541 | * | |
542 | * Returns a lower-cased COPY of the SBuf | |
543 | * \see man tolower(3) | |
544 | */ | |
545 | SBuf toLower() const; | |
546 | ||
547 | /** Upper-case SBuf | |
548 | * | |
549 | * Returns an upper-cased COPY of the SBuf | |
550 | * \see man toupper(3) | |
551 | */ | |
552 | SBuf toUpper() const; | |
553 | ||
554 | /** String export function | |
496a9e97 FC |
555 | * converts the SBuf to a legacy String, by copy. |
556 | * \deprecated | |
412da427 FC |
557 | */ |
558 | String toString() const; | |
559 | ||
7cbd3256 FC |
560 | /// std::string export function |
561 | std::string toStdString() const { return std::string(buf(),length()); } | |
562 | ||
496a9e97 FC |
563 | // TODO: possibly implement erase() similar to std::string's erase |
564 | // TODO: possibly implement a replace() call | |
412da427 FC |
565 | private: |
566 | ||
567 | MemBlob::Pointer store_; ///< memory block, possibly shared with other SBufs | |
568 | size_type off_; ///< our content start offset from the beginning of shared store_ | |
569 | size_type len_; ///< number of our content bytes in shared store_ | |
570 | static SBufStats stats; ///< class-wide statistics | |
571 | ||
7cbd3256 FC |
572 | /// SBuf object identifier; does not change when contents do, |
573 | /// including during assignment | |
574 | const InstanceId<SBuf> id; | |
412da427 | 575 | |
62842d40 FC |
576 | /** obtain prototype store |
577 | * | |
578 | * Just-created SBufs all share to the same MemBlob. | |
579 | * This call instantiates and returns it. | |
580 | */ | |
581 | static MemBlob::Pointer GetStorePrototype(); | |
582 | ||
583 | /** | |
584 | * obtains a char* to the beginning of this SBuf in memory. | |
585 | * \note the obtained string is NOT null-terminated. | |
586 | */ | |
587 | char * buf() const {return (store_->mem+off_);} | |
588 | ||
589 | /** returns the pointer to the first char after this SBuf end | |
590 | * | |
591 | * No checks are made that the space returned is safe, checking that is | |
592 | * up to the caller. | |
593 | */ | |
594 | char * bufEnd() const {return (store_->mem+off_+len_);} | |
595 | ||
596 | /** | |
597 | * Try to guesstimate how big a MemBlob to allocate. | |
598 | * The result is guarranteed to be to be at least the desired size. | |
599 | */ | |
fdd1982c | 600 | size_type estimateCapacity(size_type desired) const {return (2*desired);} |
412da427 | 601 | |
412da427 FC |
602 | void reAlloc(size_type newsize); |
603 | ||
a452bc8b | 604 | void cow(size_type minsize = npos); |
412da427 FC |
605 | |
606 | void checkAccessBounds(size_type pos) const; | |
62842d40 | 607 | |
7cbd3256 FC |
608 | /** Low-level append operation |
609 | * | |
610 | * Takes as input a contiguous area of memory and appends its contents | |
611 | * to the SBuf, taking care of memory management. Does no bounds checking | |
612 | * on the supplied memory buffer, it is the duty of the caller to ensure | |
613 | * that the supplied area is valid. | |
614 | */ | |
615 | SBuf& lowAppend(const char * memArea, size_type areaSize); | |
412da427 FC |
616 | }; |
617 | ||
496a9e97 | 618 | /// ostream output operator |
62842d40 FC |
619 | inline std::ostream & |
620 | operator <<(std::ostream& os, const SBuf& S) | |
621 | { | |
622 | return S.print(os); | |
623 | } | |
412da427 FC |
624 | |
625 | #endif /* SQUID_SBUF_H */ |