Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / read_until.hpp @ 2486

History | View | Annotate | Download (36.4 kB)

1
//
2
// read_until.hpp
3
// ~~~~~~~~~~~~~~
4
//
5
// Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6
//
7
// Distributed under the Boost Software License, Version 1.0. (See accompanying
8
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9
//
10

    
11
#ifndef BOOST_ASIO_READ_UNTIL_HPP
12
#define BOOST_ASIO_READ_UNTIL_HPP
13

    
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15
# pragma once
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17

    
18
#include <boost/asio/detail/config.hpp>
19

    
20
#if !defined(BOOST_ASIO_NO_IOSTREAM)
21

    
22
#include <cstddef>
23
#include <string>
24
#include <boost/asio/async_result.hpp>
25
#include <boost/asio/basic_streambuf.hpp>
26
#include <boost/asio/detail/regex_fwd.hpp>
27
#include <boost/asio/detail/type_traits.hpp>
28
#include <boost/asio/error.hpp>
29

    
30
#include <boost/asio/detail/push_options.hpp>
31

    
32
namespace boost {
33
namespace asio {
34

    
35
namespace detail
36
{
37
  char (&has_result_type_helper(...))[2];
38

    
39
  template <typename T>
40
  char has_result_type_helper(T*, typename T::result_type* = 0);
41

    
42
  template <typename T>
43
  struct has_result_type
44
  {
45
    enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) };
46
  };
47
} // namespace detail
48

    
49
/// Type trait used to determine whether a type can be used as a match condition
50
/// function with read_until and async_read_until.
51
template <typename T>
52
struct is_match_condition
53
{
54
#if defined(GENERATING_DOCUMENTATION)
55
  /// The value member is true if the type may be used as a match condition.
56
  static const bool value;
57
#else
58
  enum
59
  {
60
    value = boost::asio::is_function<
61
        typename boost::asio::remove_pointer<T>::type>::value
62
      || detail::has_result_type<T>::value
63
  };
64
#endif
65
};
66

    
67
/**
68
 * @defgroup read_until boost::asio::read_until
69
 *
70
 * @brief Read data into a streambuf until it contains a delimiter, matches a
71
 * regular expression, or a function object indicates a match.
72
 */
73
/*@{*/
74

    
75
/// Read data into a streambuf until it contains a specified delimiter.
76
/**
77
 * This function is used to read data into the specified streambuf until the
78
 * streambuf's get area contains the specified delimiter. The call will block
79
 * until one of the following conditions is true:
80
 *
81
 * @li The get area of the streambuf contains the specified delimiter.
82
 *
83
 * @li An error occurred.
84
 *
85
 * This operation is implemented in terms of zero or more calls to the stream's
86
 * read_some function. If the streambuf's get area already contains the
87
 * delimiter, the function returns immediately.
88
 *
89
 * @param s The stream from which the data is to be read. The type must support
90
 * the SyncReadStream concept.
91
 *
92
 * @param b A streambuf object into which the data will be read.
93
 *
94
 * @param delim The delimiter character.
95
 *
96
 * @returns The number of bytes in the streambuf's get area up to and including
97
 * the delimiter.
98
 *
99
 * @throws boost::system::system_error Thrown on failure.
100
 *
101
 * @note After a successful read_until operation, the streambuf may contain
102
 * additional data beyond the delimiter. An application will typically leave
103
 * that data in the streambuf for a subsequent read_until operation to examine.
104
 *
105
 * @par Example
106
 * To read data into a streambuf until a newline is encountered:
107
 * @code boost::asio::streambuf b;
108
 * boost::asio::read_until(s, b, '\n');
109
 * std::istream is(&b);
110
 * std::string line;
111
 * std::getline(is, line); @endcode
112
 * After the @c read_until operation completes successfully, the buffer @c b
113
 * contains the delimiter:
114
 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
115
 * The call to @c std::getline then extracts the data up to and including the
116
 * delimiter, so that the string @c line contains:
117
 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
118
 * The remaining data is left in the buffer @c b as follows:
119
 * @code { 'd', 'e', ... } @endcode
120
 * This data may be the start of a new line, to be extracted by a subsequent
121
 * @c read_until operation.
122
 */
123
template <typename SyncReadStream, typename Allocator>
124
std::size_t read_until(SyncReadStream& s,
125
    boost::asio::basic_streambuf<Allocator>& b, char delim);
126

    
127
/// Read data into a streambuf until it contains a specified delimiter.
128
/**
129
 * This function is used to read data into the specified streambuf until the
130
 * streambuf's get area contains the specified delimiter. The call will block
131
 * until one of the following conditions is true:
132
 *
133
 * @li The get area of the streambuf contains the specified delimiter.
134
 *
135
 * @li An error occurred.
136
 *
137
 * This operation is implemented in terms of zero or more calls to the stream's
138
 * read_some function. If the streambuf's get area already contains the
139
 * delimiter, the function returns immediately.
140
 *
141
 * @param s The stream from which the data is to be read. The type must support
142
 * the SyncReadStream concept.
143
 *
144
 * @param b A streambuf object into which the data will be read.
145
 *
146
 * @param delim The delimiter character.
147
 *
148
 * @param ec Set to indicate what error occurred, if any.
149
 *
150
 * @returns The number of bytes in the streambuf's get area up to and including
151
 * the delimiter. Returns 0 if an error occurred.
152
 *
153
 * @note After a successful read_until operation, the streambuf may contain
154
 * additional data beyond the delimiter. An application will typically leave
155
 * that data in the streambuf for a subsequent read_until operation to examine.
156
 */
157
template <typename SyncReadStream, typename Allocator>
158
std::size_t read_until(SyncReadStream& s,
159
    boost::asio::basic_streambuf<Allocator>& b, char delim,
160
    boost::system::error_code& ec);
161

    
162
/// Read data into a streambuf until it contains a specified delimiter.
163
/**
164
 * This function is used to read data into the specified streambuf until the
165
 * streambuf's get area contains the specified delimiter. The call will block
166
 * until one of the following conditions is true:
167
 *
168
 * @li The get area of the streambuf contains the specified delimiter.
169
 *
170
 * @li An error occurred.
171
 *
172
 * This operation is implemented in terms of zero or more calls to the stream's
173
 * read_some function. If the streambuf's get area already contains the
174
 * delimiter, the function returns immediately.
175
 *
176
 * @param s The stream from which the data is to be read. The type must support
177
 * the SyncReadStream concept.
178
 *
179
 * @param b A streambuf object into which the data will be read.
180
 *
181
 * @param delim The delimiter string.
182
 *
183
 * @returns The number of bytes in the streambuf's get area up to and including
184
 * the delimiter.
185
 *
186
 * @throws boost::system::system_error Thrown on failure.
187
 *
188
 * @note After a successful read_until operation, the streambuf may contain
189
 * additional data beyond the delimiter. An application will typically leave
190
 * that data in the streambuf for a subsequent read_until operation to examine.
191
 *
192
 * @par Example
193
 * To read data into a streambuf until a newline is encountered:
194
 * @code boost::asio::streambuf b;
195
 * boost::asio::read_until(s, b, "\r\n");
196
 * std::istream is(&b);
197
 * std::string line;
198
 * std::getline(is, line); @endcode
199
 * After the @c read_until operation completes successfully, the buffer @c b
200
 * contains the delimiter:
201
 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
202
 * The call to @c std::getline then extracts the data up to and including the
203
 * delimiter, so that the string @c line contains:
204
 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
205
 * The remaining data is left in the buffer @c b as follows:
206
 * @code { 'd', 'e', ... } @endcode
207
 * This data may be the start of a new line, to be extracted by a subsequent
208
 * @c read_until operation.
209
 */
210
template <typename SyncReadStream, typename Allocator>
211
std::size_t read_until(SyncReadStream& s,
212
    boost::asio::basic_streambuf<Allocator>& b, const std::string& delim);
213

    
214
/// Read data into a streambuf until it contains a specified delimiter.
215
/**
216
 * This function is used to read data into the specified streambuf until the
217
 * streambuf's get area contains the specified delimiter. The call will block
218
 * until one of the following conditions is true:
219
 *
220
 * @li The get area of the streambuf contains the specified delimiter.
221
 *
222
 * @li An error occurred.
223
 *
224
 * This operation is implemented in terms of zero or more calls to the stream's
225
 * read_some function. If the streambuf's get area already contains the
226
 * delimiter, the function returns immediately.
227
 *
228
 * @param s The stream from which the data is to be read. The type must support
229
 * the SyncReadStream concept.
230
 *
231
 * @param b A streambuf object into which the data will be read.
232
 *
233
 * @param delim The delimiter string.
234
 *
235
 * @param ec Set to indicate what error occurred, if any.
236
 *
237
 * @returns The number of bytes in the streambuf's get area up to and including
238
 * the delimiter. Returns 0 if an error occurred.
239
 *
240
 * @note After a successful read_until operation, the streambuf may contain
241
 * additional data beyond the delimiter. An application will typically leave
242
 * that data in the streambuf for a subsequent read_until operation to examine.
243
 */
244
template <typename SyncReadStream, typename Allocator>
245
std::size_t read_until(SyncReadStream& s,
246
    boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
247
    boost::system::error_code& ec);
248

    
249
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
250
  || defined(GENERATING_DOCUMENTATION)
251

    
252
/// Read data into a streambuf until some part of the data it contains matches
253
/// a regular expression.
254
/**
255
 * This function is used to read data into the specified streambuf until the
256
 * streambuf's get area contains some data that matches a regular expression.
257
 * The call will block until one of the following conditions is true:
258
 *
259
 * @li A substring of the streambuf's get area matches the regular expression.
260
 *
261
 * @li An error occurred.
262
 *
263
 * This operation is implemented in terms of zero or more calls to the stream's
264
 * read_some function. If the streambuf's get area already contains data that
265
 * matches the regular expression, the function returns immediately.
266
 *
267
 * @param s The stream from which the data is to be read. The type must support
268
 * the SyncReadStream concept.
269
 *
270
 * @param b A streambuf object into which the data will be read.
271
 *
272
 * @param expr The regular expression.
273
 *
274
 * @returns The number of bytes in the streambuf's get area up to and including
275
 * the substring that matches the regular expression.
276
 *
277
 * @throws boost::system::system_error Thrown on failure.
278
 *
279
 * @note After a successful read_until operation, the streambuf may contain
280
 * additional data beyond that which matched the regular expression. An
281
 * application will typically leave that data in the streambuf for a subsequent
282
 * read_until operation to examine.
283
 *
284
 * @par Example
285
 * To read data into a streambuf until a CR-LF sequence is encountered:
286
 * @code boost::asio::streambuf b;
287
 * boost::asio::read_until(s, b, boost::regex("\r\n"));
288
 * std::istream is(&b);
289
 * std::string line;
290
 * std::getline(is, line); @endcode
291
 * After the @c read_until operation completes successfully, the buffer @c b
292
 * contains the data which matched the regular expression:
293
 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
294
 * The call to @c std::getline then extracts the data up to and including the
295
 * match, so that the string @c line contains:
296
 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
297
 * The remaining data is left in the buffer @c b as follows:
298
 * @code { 'd', 'e', ... } @endcode
299
 * This data may be the start of a new line, to be extracted by a subsequent
300
 * @c read_until operation.
301
 */
302
template <typename SyncReadStream, typename Allocator>
303
std::size_t read_until(SyncReadStream& s,
304
    boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr);
305

    
306
/// Read data into a streambuf until some part of the data it contains matches
307
/// a regular expression.
308
/**
309
 * This function is used to read data into the specified streambuf until the
310
 * streambuf's get area contains some data that matches a regular expression.
311
 * The call will block until one of the following conditions is true:
312
 *
313
 * @li A substring of the streambuf's get area matches the regular expression.
314
 *
315
 * @li An error occurred.
316
 *
317
 * This operation is implemented in terms of zero or more calls to the stream's
318
 * read_some function. If the streambuf's get area already contains data that
319
 * matches the regular expression, the function returns immediately.
320
 *
321
 * @param s The stream from which the data is to be read. The type must support
322
 * the SyncReadStream concept.
323
 *
324
 * @param b A streambuf object into which the data will be read.
325
 *
326
 * @param expr The regular expression.
327
 *
328
 * @param ec Set to indicate what error occurred, if any.
329
 *
330
 * @returns The number of bytes in the streambuf's get area up to and including
331
 * the substring that matches the regular expression. Returns 0 if an error
332
 * occurred.
333
 *
334
 * @note After a successful read_until operation, the streambuf may contain
335
 * additional data beyond that which matched the regular expression. An
336
 * application will typically leave that data in the streambuf for a subsequent
337
 * read_until operation to examine.
338
 */
339
template <typename SyncReadStream, typename Allocator>
340
std::size_t read_until(SyncReadStream& s,
341
    boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
342
    boost::system::error_code& ec);
343

    
344
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
345
       // || defined(GENERATING_DOCUMENTATION)
346

    
347
/// Read data into a streambuf until a function object indicates a match.
348
/**
349
 * This function is used to read data into the specified streambuf until a
350
 * user-defined match condition function object, when applied to the data
351
 * contained in the streambuf, indicates a successful match. The call will
352
 * block until one of the following conditions is true:
353
 *
354
 * @li The match condition function object returns a std::pair where the second
355
 * element evaluates to true.
356
 *
357
 * @li An error occurred.
358
 *
359
 * This operation is implemented in terms of zero or more calls to the stream's
360
 * read_some function. If the match condition function object already indicates
361
 * a match, the function returns immediately.
362
 *
363
 * @param s The stream from which the data is to be read. The type must support
364
 * the SyncReadStream concept.
365
 *
366
 * @param b A streambuf object into which the data will be read.
367
 *
368
 * @param match_condition The function object to be called to determine whether
369
 * a match exists. The signature of the function object must be:
370
 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
371
 * @endcode
372
 * where @c iterator represents the type:
373
 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
374
 * @endcode
375
 * The iterator parameters @c begin and @c end define the range of bytes to be
376
 * scanned to determine whether there is a match. The @c first member of the
377
 * return value is an iterator marking one-past-the-end of the bytes that have
378
 * been consumed by the match function. This iterator is used to calculate the
379
 * @c begin parameter for any subsequent invocation of the match condition. The
380
 * @c second member of the return value is true if a match has been found, false
381
 * otherwise.
382
 *
383
 * @returns The number of bytes in the streambuf's get area that have been fully
384
 * consumed by the match function.
385
 *
386
 * @throws boost::system::system_error Thrown on failure.
387
 *
388
 * @note After a successful read_until operation, the streambuf may contain
389
 * additional data beyond that which matched the function object. An application
390
 * will typically leave that data in the streambuf for a subsequent
391
 *
392
 * @note The default implementation of the @c is_match_condition type trait
393
 * evaluates to true for function pointers and function objects with a
394
 * @c result_type typedef. It must be specialised for other user-defined
395
 * function objects.
396
 *
397
 * @par Examples
398
 * To read data into a streambuf until whitespace is encountered:
399
 * @code typedef boost::asio::buffers_iterator<
400
 *     boost::asio::streambuf::const_buffers_type> iterator;
401
 *
402
 * std::pair<iterator, bool>
403
 * match_whitespace(iterator begin, iterator end)
404
 * {
405
 *   iterator i = begin;
406
 *   while (i != end)
407
 *     if (std::isspace(*i++))
408
 *       return std::make_pair(i, true);
409
 *   return std::make_pair(i, false);
410
 * }
411
 * ...
412
 * boost::asio::streambuf b;
413
 * boost::asio::read_until(s, b, match_whitespace);
414
 * @endcode
415
 *
416
 * To read data into a streambuf until a matching character is found:
417
 * @code class match_char
418
 * {
419
 * public:
420
 *   explicit match_char(char c) : c_(c) {}
421
 *
422
 *   template <typename Iterator>
423
 *   std::pair<Iterator, bool> operator()(
424
 *       Iterator begin, Iterator end) const
425
 *   {
426
 *     Iterator i = begin;
427
 *     while (i != end)
428
 *       if (c_ == *i++)
429
 *         return std::make_pair(i, true);
430
 *     return std::make_pair(i, false);
431
 *   }
432
 *
433
 * private:
434
 *   char c_;
435
 * };
436
 *
437
 * namespace asio {
438
 *   template <> struct is_match_condition<match_char>
439
 *     : public boost::true_type {};
440
 * } // namespace asio
441
 * ...
442
 * boost::asio::streambuf b;
443
 * boost::asio::read_until(s, b, match_char('a'));
444
 * @endcode
445
 */
446
template <typename SyncReadStream, typename Allocator, typename MatchCondition>
447
std::size_t read_until(SyncReadStream& s,
448
    boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition,
449
    typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
450

    
451
/// Read data into a streambuf until a function object indicates a match.
452
/**
453
 * This function is used to read data into the specified streambuf until a
454
 * user-defined match condition function object, when applied to the data
455
 * contained in the streambuf, indicates a successful match. The call will
456
 * block until one of the following conditions is true:
457
 *
458
 * @li The match condition function object returns a std::pair where the second
459
 * element evaluates to true.
460
 *
461
 * @li An error occurred.
462
 *
463
 * This operation is implemented in terms of zero or more calls to the stream's
464
 * read_some function. If the match condition function object already indicates
465
 * a match, the function returns immediately.
466
 *
467
 * @param s The stream from which the data is to be read. The type must support
468
 * the SyncReadStream concept.
469
 *
470
 * @param b A streambuf object into which the data will be read.
471
 *
472
 * @param match_condition The function object to be called to determine whether
473
 * a match exists. The signature of the function object must be:
474
 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
475
 * @endcode
476
 * where @c iterator represents the type:
477
 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
478
 * @endcode
479
 * The iterator parameters @c begin and @c end define the range of bytes to be
480
 * scanned to determine whether there is a match. The @c first member of the
481
 * return value is an iterator marking one-past-the-end of the bytes that have
482
 * been consumed by the match function. This iterator is used to calculate the
483
 * @c begin parameter for any subsequent invocation of the match condition. The
484
 * @c second member of the return value is true if a match has been found, false
485
 * otherwise.
486
 *
487
 * @param ec Set to indicate what error occurred, if any.
488
 *
489
 * @returns The number of bytes in the streambuf's get area that have been fully
490
 * consumed by the match function. Returns 0 if an error occurred.
491
 *
492
 * @note After a successful read_until operation, the streambuf may contain
493
 * additional data beyond that which matched the function object. An application
494
 * will typically leave that data in the streambuf for a subsequent
495
 *
496
 * @note The default implementation of the @c is_match_condition type trait
497
 * evaluates to true for function pointers and function objects with a
498
 * @c result_type typedef. It must be specialised for other user-defined
499
 * function objects.
500
 */
501
template <typename SyncReadStream, typename Allocator, typename MatchCondition>
502
std::size_t read_until(SyncReadStream& s,
503
    boost::asio::basic_streambuf<Allocator>& b,
504
    MatchCondition match_condition, boost::system::error_code& ec,
505
    typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
506

    
507
/*@}*/
508
/**
509
 * @defgroup async_read_until boost::asio::async_read_until
510
 *
511
 * @brief Start an asynchronous operation to read data into a streambuf until it
512
 * contains a delimiter, matches a regular expression, or a function object
513
 * indicates a match.
514
 */
515
/*@{*/
516

    
517
/// Start an asynchronous operation to read data into a streambuf until it
518
/// contains a specified delimiter.
519
/**
520
 * This function is used to asynchronously read data into the specified
521
 * streambuf until the streambuf's get area contains the specified delimiter.
522
 * The function call always returns immediately. The asynchronous operation
523
 * will continue until one of the following conditions is true:
524
 *
525
 * @li The get area of the streambuf contains the specified delimiter.
526
 *
527
 * @li An error occurred.
528
 *
529
 * This operation is implemented in terms of zero or more calls to the stream's
530
 * async_read_some function, and is known as a <em>composed operation</em>. If
531
 * the streambuf's get area already contains the delimiter, this asynchronous
532
 * operation completes immediately. The program must ensure that the stream
533
 * performs no other read operations (such as async_read, async_read_until, the
534
 * stream's async_read_some function, or any other composed operations that
535
 * perform reads) until this operation completes.
536
 *
537
 * @param s The stream from which the data is to be read. The type must support
538
 * the AsyncReadStream concept.
539
 *
540
 * @param b A streambuf object into which the data will be read. Ownership of
541
 * the streambuf is retained by the caller, which must guarantee that it remains
542
 * valid until the handler is called.
543
 *
544
 * @param delim The delimiter character.
545
 *
546
 * @param handler The handler to be called when the read operation completes.
547
 * Copies will be made of the handler as required. The function signature of the
548
 * handler must be:
549
 * @code void handler(
550
 *   // Result of operation.
551
 *   const boost::system::error_code& error,
552
 *
553
 *   // The number of bytes in the streambuf's get
554
 *   // area up to and including the delimiter.
555
 *   // 0 if an error occurred.
556
 *   std::size_t bytes_transferred
557
 * ); @endcode
558
 * Regardless of whether the asynchronous operation completes immediately or
559
 * not, the handler will not be invoked from within this function. Invocation of
560
 * the handler will be performed in a manner equivalent to using
561
 * boost::asio::io_service::post().
562
 *
563
 * @note After a successful async_read_until operation, the streambuf may
564
 * contain additional data beyond the delimiter. An application will typically
565
 * leave that data in the streambuf for a subsequent async_read_until operation
566
 * to examine.
567
 *
568
 * @par Example
569
 * To asynchronously read data into a streambuf until a newline is encountered:
570
 * @code boost::asio::streambuf b;
571
 * ...
572
 * void handler(const boost::system::error_code& e, std::size_t size)
573
 * {
574
 *   if (!e)
575
 *   {
576
 *     std::istream is(&b);
577
 *     std::string line;
578
 *     std::getline(is, line);
579
 *     ...
580
 *   }
581
 * }
582
 * ...
583
 * boost::asio::async_read_until(s, b, '\n', handler); @endcode
584
 * After the @c async_read_until operation completes successfully, the buffer
585
 * @c b contains the delimiter:
586
 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode
587
 * The call to @c std::getline then extracts the data up to and including the
588
 * delimiter, so that the string @c line contains:
589
 * @code { 'a', 'b', ..., 'c', '\n' } @endcode
590
 * The remaining data is left in the buffer @c b as follows:
591
 * @code { 'd', 'e', ... } @endcode
592
 * This data may be the start of a new line, to be extracted by a subsequent
593
 * @c async_read_until operation.
594
 */
595
template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
596
BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
597
    void (boost::system::error_code, std::size_t))
598
async_read_until(AsyncReadStream& s,
599
    boost::asio::basic_streambuf<Allocator>& b,
600
    char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
601

    
602
/// Start an asynchronous operation to read data into a streambuf until it
603
/// contains a specified delimiter.
604
/**
605
 * This function is used to asynchronously read data into the specified
606
 * streambuf until the streambuf's get area contains the specified delimiter.
607
 * The function call always returns immediately. The asynchronous operation
608
 * will continue until one of the following conditions is true:
609
 *
610
 * @li The get area of the streambuf contains the specified delimiter.
611
 *
612
 * @li An error occurred.
613
 *
614
 * This operation is implemented in terms of zero or more calls to the stream's
615
 * async_read_some function, and is known as a <em>composed operation</em>. If
616
 * the streambuf's get area already contains the delimiter, this asynchronous
617
 * operation completes immediately. The program must ensure that the stream
618
 * performs no other read operations (such as async_read, async_read_until, the
619
 * stream's async_read_some function, or any other composed operations that
620
 * perform reads) until this operation completes.
621
 *
622
 * @param s The stream from which the data is to be read. The type must support
623
 * the AsyncReadStream concept.
624
 *
625
 * @param b A streambuf object into which the data will be read. Ownership of
626
 * the streambuf is retained by the caller, which must guarantee that it remains
627
 * valid until the handler is called.
628
 *
629
 * @param delim The delimiter string.
630
 *
631
 * @param handler The handler to be called when the read operation completes.
632
 * Copies will be made of the handler as required. The function signature of the
633
 * handler must be:
634
 * @code void handler(
635
 *   // Result of operation.
636
 *   const boost::system::error_code& error,
637
 *
638
 *   // The number of bytes in the streambuf's get
639
 *   // area up to and including the delimiter.
640
 *   // 0 if an error occurred.
641
 *   std::size_t bytes_transferred
642
 * ); @endcode
643
 * Regardless of whether the asynchronous operation completes immediately or
644
 * not, the handler will not be invoked from within this function. Invocation of
645
 * the handler will be performed in a manner equivalent to using
646
 * boost::asio::io_service::post().
647
 *
648
 * @note After a successful async_read_until operation, the streambuf may
649
 * contain additional data beyond the delimiter. An application will typically
650
 * leave that data in the streambuf for a subsequent async_read_until operation
651
 * to examine.
652
 *
653
 * @par Example
654
 * To asynchronously read data into a streambuf until a newline is encountered:
655
 * @code boost::asio::streambuf b;
656
 * ...
657
 * void handler(const boost::system::error_code& e, std::size_t size)
658
 * {
659
 *   if (!e)
660
 *   {
661
 *     std::istream is(&b);
662
 *     std::string line;
663
 *     std::getline(is, line);
664
 *     ...
665
 *   }
666
 * }
667
 * ...
668
 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode
669
 * After the @c async_read_until operation completes successfully, the buffer
670
 * @c b contains the delimiter:
671
 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
672
 * The call to @c std::getline then extracts the data up to and including the
673
 * delimiter, so that the string @c line contains:
674
 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
675
 * The remaining data is left in the buffer @c b as follows:
676
 * @code { 'd', 'e', ... } @endcode
677
 * This data may be the start of a new line, to be extracted by a subsequent
678
 * @c async_read_until operation.
679
 */
680
template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
681
BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
682
    void (boost::system::error_code, std::size_t))
683
async_read_until(AsyncReadStream& s,
684
    boost::asio::basic_streambuf<Allocator>& b, const std::string& delim,
685
    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
686

    
687
#if defined(BOOST_ASIO_HAS_BOOST_REGEX) \
688
  || defined(GENERATING_DOCUMENTATION)
689

    
690
/// Start an asynchronous operation to read data into a streambuf until some
691
/// part of its data matches a regular expression.
692
/**
693
 * This function is used to asynchronously read data into the specified
694
 * streambuf until the streambuf's get area contains some data that matches a
695
 * regular expression. The function call always returns immediately. The
696
 * asynchronous operation will continue until one of the following conditions
697
 * is true:
698
 *
699
 * @li A substring of the streambuf's get area matches the regular expression.
700
 *
701
 * @li An error occurred.
702
 *
703
 * This operation is implemented in terms of zero or more calls to the stream's
704
 * async_read_some function, and is known as a <em>composed operation</em>. If
705
 * the streambuf's get area already contains data that matches the regular
706
 * expression, this asynchronous operation completes immediately. The program
707
 * must ensure that the stream performs no other read operations (such as
708
 * async_read, async_read_until, the stream's async_read_some function, or any
709
 * other composed operations that perform reads) until this operation
710
 * completes.
711
 *
712
 * @param s The stream from which the data is to be read. The type must support
713
 * the AsyncReadStream concept.
714
 *
715
 * @param b A streambuf object into which the data will be read. Ownership of
716
 * the streambuf is retained by the caller, which must guarantee that it remains
717
 * valid until the handler is called.
718
 *
719
 * @param expr The regular expression.
720
 *
721
 * @param handler The handler to be called when the read operation completes.
722
 * Copies will be made of the handler as required. The function signature of the
723
 * handler must be:
724
 * @code void handler(
725
 *   // Result of operation.
726
 *   const boost::system::error_code& error,
727
 *
728
 *   // The number of bytes in the streambuf's get
729
 *   // area up to and including the substring
730
 *   // that matches the regular. expression.
731
 *   // 0 if an error occurred.
732
 *   std::size_t bytes_transferred
733
 * ); @endcode
734
 * Regardless of whether the asynchronous operation completes immediately or
735
 * not, the handler will not be invoked from within this function. Invocation of
736
 * the handler will be performed in a manner equivalent to using
737
 * boost::asio::io_service::post().
738
 *
739
 * @note After a successful async_read_until operation, the streambuf may
740
 * contain additional data beyond that which matched the regular expression. An
741
 * application will typically leave that data in the streambuf for a subsequent
742
 * async_read_until operation to examine.
743
 *
744
 * @par Example
745
 * To asynchronously read data into a streambuf until a CR-LF sequence is
746
 * encountered:
747
 * @code boost::asio::streambuf b;
748
 * ...
749
 * void handler(const boost::system::error_code& e, std::size_t size)
750
 * {
751
 *   if (!e)
752
 *   {
753
 *     std::istream is(&b);
754
 *     std::string line;
755
 *     std::getline(is, line);
756
 *     ...
757
 *   }
758
 * }
759
 * ...
760
 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode
761
 * After the @c async_read_until operation completes successfully, the buffer
762
 * @c b contains the data which matched the regular expression:
763
 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode
764
 * The call to @c std::getline then extracts the data up to and including the
765
 * match, so that the string @c line contains:
766
 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode
767
 * The remaining data is left in the buffer @c b as follows:
768
 * @code { 'd', 'e', ... } @endcode
769
 * This data may be the start of a new line, to be extracted by a subsequent
770
 * @c async_read_until operation.
771
 */
772
template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
773
BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
774
    void (boost::system::error_code, std::size_t))
775
async_read_until(AsyncReadStream& s,
776
    boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr,
777
    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
778

    
779
#endif // defined(BOOST_ASIO_HAS_BOOST_REGEX)
780
       // || defined(GENERATING_DOCUMENTATION)
781

    
782
/// Start an asynchronous operation to read data into a streambuf until a
783
/// function object indicates a match.
784
/**
785
 * This function is used to asynchronously read data into the specified
786
 * streambuf until a user-defined match condition function object, when applied
787
 * to the data contained in the streambuf, indicates a successful match. The
788
 * function call always returns immediately. The asynchronous operation will
789
 * continue until one of the following conditions is true:
790
 *
791
 * @li The match condition function object returns a std::pair where the second
792
 * element evaluates to true.
793
 *
794
 * @li An error occurred.
795
 *
796
 * This operation is implemented in terms of zero or more calls to the stream's
797
 * async_read_some function, and is known as a <em>composed operation</em>. If
798
 * the match condition function object already indicates a match, this
799
 * asynchronous operation completes immediately. The program must ensure that
800
 * the stream performs no other read operations (such as async_read,
801
 * async_read_until, the stream's async_read_some function, or any other
802
 * composed operations that perform reads) until this operation completes.
803
 *
804
 * @param s The stream from which the data is to be read. The type must support
805
 * the AsyncReadStream concept.
806
 *
807
 * @param b A streambuf object into which the data will be read.
808
 *
809
 * @param match_condition The function object to be called to determine whether
810
 * a match exists. The signature of the function object must be:
811
 * @code pair<iterator, bool> match_condition(iterator begin, iterator end);
812
 * @endcode
813
 * where @c iterator represents the type:
814
 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type>
815
 * @endcode
816
 * The iterator parameters @c begin and @c end define the range of bytes to be
817
 * scanned to determine whether there is a match. The @c first member of the
818
 * return value is an iterator marking one-past-the-end of the bytes that have
819
 * been consumed by the match function. This iterator is used to calculate the
820
 * @c begin parameter for any subsequent invocation of the match condition. The
821
 * @c second member of the return value is true if a match has been found, false
822
 * otherwise.
823
 *
824
 * @param handler The handler to be called when the read operation completes.
825
 * Copies will be made of the handler as required. The function signature of the
826
 * handler must be:
827
 * @code void handler(
828
 *   // Result of operation.
829
 *   const boost::system::error_code& error,
830
 *
831
 *   // The number of bytes in the streambuf's get
832
 *   // area that have been fully consumed by the
833
 *   // match function. O if an error occurred.
834
 *   std::size_t bytes_transferred
835
 * ); @endcode
836
 * Regardless of whether the asynchronous operation completes immediately or
837
 * not, the handler will not be invoked from within this function. Invocation of
838
 * the handler will be performed in a manner equivalent to using
839
 * boost::asio::io_service::post().
840
 *
841
 * @note After a successful async_read_until operation, the streambuf may
842
 * contain additional data beyond that which matched the function object. An
843
 * application will typically leave that data in the streambuf for a subsequent
844
 * async_read_until operation to examine.
845
 *
846
 * @note The default implementation of the @c is_match_condition type trait
847
 * evaluates to true for function pointers and function objects with a
848
 * @c result_type typedef. It must be specialised for other user-defined
849
 * function objects.
850
 *
851
 * @par Examples
852
 * To asynchronously read data into a streambuf until whitespace is encountered:
853
 * @code typedef boost::asio::buffers_iterator<
854
 *     boost::asio::streambuf::const_buffers_type> iterator;
855
 *
856
 * std::pair<iterator, bool>
857
 * match_whitespace(iterator begin, iterator end)
858
 * {
859
 *   iterator i = begin;
860
 *   while (i != end)
861
 *     if (std::isspace(*i++))
862
 *       return std::make_pair(i, true);
863
 *   return std::make_pair(i, false);
864
 * }
865
 * ...
866
 * void handler(const boost::system::error_code& e, std::size_t size);
867
 * ...
868
 * boost::asio::streambuf b;
869
 * boost::asio::async_read_until(s, b, match_whitespace, handler);
870
 * @endcode
871
 *
872
 * To asynchronously read data into a streambuf until a matching character is
873
 * found:
874
 * @code class match_char
875
 * {
876
 * public:
877
 *   explicit match_char(char c) : c_(c) {}
878
 *
879
 *   template <typename Iterator>
880
 *   std::pair<Iterator, bool> operator()(
881
 *       Iterator begin, Iterator end) const
882
 *   {
883
 *     Iterator i = begin;
884
 *     while (i != end)
885
 *       if (c_ == *i++)
886
 *         return std::make_pair(i, true);
887
 *     return std::make_pair(i, false);
888
 *   }
889
 *
890
 * private:
891
 *   char c_;
892
 * };
893
 *
894
 * namespace asio {
895
 *   template <> struct is_match_condition<match_char>
896
 *     : public boost::true_type {};
897
 * } // namespace asio
898
 * ...
899
 * void handler(const boost::system::error_code& e, std::size_t size);
900
 * ...
901
 * boost::asio::streambuf b;
902
 * boost::asio::async_read_until(s, b, match_char('a'), handler);
903
 * @endcode
904
 */
905
template <typename AsyncReadStream, typename Allocator,
906
    typename MatchCondition, typename ReadHandler>
907
BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
908
    void (boost::system::error_code, std::size_t))
909
async_read_until(AsyncReadStream& s,
910
    boost::asio::basic_streambuf<Allocator>& b,
911
    MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
912
    typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0);
913

    
914
/*@}*/
915

    
916
} // namespace asio
917
} // namespace boost
918

    
919
#include <boost/asio/detail/pop_options.hpp>
920

    
921
#include <boost/asio/impl/read_until.hpp>
922

    
923
#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
924

    
925
#endif // BOOST_ASIO_READ_UNTIL_HPP