Ugly, not-to-be-pushed sucking in of all of Boost to get windows to work.
[dyninst.git] / external / boost / algorithm / string / erase.hpp
1 //  Boost string_algo library erase.hpp header file  ---------------------------//
2
3 //  Copyright Pavol Droba 2002-2003. Use, modification and
4 //  distribution is subject to the Boost Software License, Version
5 //  1.0. (See accompanying file LICENSE_1_0.txt or copy at
6 //  http://www.boost.org/LICENSE_1_0.txt)
7
8 //  See http://www.boost.org for updates, documentation, and revision history.
9
10 #ifndef BOOST_STRING_ERASE_HPP
11 #define BOOST_STRING_ERASE_HPP
12
13 #include <boost/algorithm/string/config.hpp>
14
15 #include <boost/range/iterator_range.hpp>
16 #include <boost/range/begin.hpp>
17 #include <boost/range/end.hpp>
18 #include <boost/range/iterator.hpp>
19 #include <boost/range/const_iterator.hpp>
20
21 #include <boost/algorithm/string/find_format.hpp>
22 #include <boost/algorithm/string/finder.hpp>
23 #include <boost/algorithm/string/formatter.hpp>
24
25 /*! \file
26     Defines various erase algorithms. Each algorithm removes
27     part(s) of the input according to a searching criteria.
28 */
29
30 namespace boost {
31     namespace algorithm {
32
33 //  erase_range -------------------------------------------------------//
34
35         //! Erase range algorithm
36         /*!
37             Remove the given range from the input. The result is a modified copy of 
38             the input. It is returned as a sequence or copied to the output iterator.
39     
40             \param Output An output iterator to which the result will be copied
41             \param Input An input sequence
42             \param SearchRange A range in the input to be removed
43             \return An output iterator pointing just after the last inserted character or
44                 a modified copy of the input
45
46             \note The second variant of this function provides the strong exception-safety guarantee
47         */
48         template<typename OutputIteratorT, typename RangeT>
49         inline OutputIteratorT erase_range_copy(
50             OutputIteratorT Output,
51             const RangeT& Input,
52             const iterator_range<
53                 BOOST_STRING_TYPENAME 
54                     range_const_iterator<RangeT>::type>& SearchRange )
55         {
56             return find_format_copy(
57                 Output,
58                 Input,
59                 range_finder(SearchRange),
60                 empty_formatter(Input) );
61         }
62
63         //! Erase range algorithm
64         /*!
65             \overload
66         */
67         template<typename SequenceT>
68         inline SequenceT erase_range_copy( 
69             const SequenceT& Input,
70             const iterator_range<
71                 BOOST_STRING_TYPENAME 
72                     range_const_iterator<SequenceT>::type>& SearchRange )
73         {
74             return find_format_copy( 
75                 Input,
76                 range_finder(SearchRange),
77                 empty_formatter(Input) );
78         }
79
80         //! Erase range algorithm
81         /*!
82             Remove the given range from the input.
83             The input sequence is modified in-place.
84
85             \param Input An input sequence
86             \param SearchRange A range in the input to be removed
87         */
88         template<typename SequenceT>
89         inline void erase_range( 
90             SequenceT& Input,
91             const iterator_range<
92                 BOOST_STRING_TYPENAME 
93                     range_iterator<SequenceT>::type>& SearchRange )
94         {
95             find_format( 
96                 Input, 
97                 range_finder(SearchRange),
98                 empty_formatter(Input) );
99         }
100
101 //  erase_first  --------------------------------------------------------//
102
103         //! Erase first algorithm
104         /*!
105             Remove the first occurrence of the substring from the input.
106             The result is a modified copy of the input. It is returned as a sequence 
107             or copied to the output iterator.
108
109             \param Output An output iterator to which the result will be copied
110             \param Input An input string
111             \param Search A substring to be searched for 
112             \return An output iterator pointing just after the last inserted character or
113                 a modified copy of the input
114             
115             \note The second variant of this function provides the strong exception-safety guarantee
116         */
117         template<
118             typename OutputIteratorT,
119             typename Range1T, 
120             typename Range2T>
121         inline OutputIteratorT erase_first_copy(
122             OutputIteratorT Output,
123             const Range1T& Input,
124             const Range2T& Search )
125         {
126             return find_format_copy(
127                 Output,
128                 Input,
129                 first_finder(Search),
130                 empty_formatter(Input) );
131         }
132
133         //! Erase first algorithm
134         /*!
135             \overload
136         */
137         template<typename SequenceT, typename RangeT>
138         inline SequenceT erase_first_copy( 
139             const SequenceT& Input,
140             const RangeT& Search )
141         {
142             return find_format_copy( 
143                 Input, 
144                 first_finder(Search),
145                 empty_formatter(Input) );
146         }
147
148         //! Erase first algorithm
149         /*!
150             Remove the first occurrence of the substring from the input. 
151             The input sequence is modified in-place.
152
153             \param Input An input string
154             \param Search A substring to be searched for. 
155         */
156         template<typename SequenceT, typename RangeT>
157         inline void erase_first( 
158             SequenceT& Input,
159             const RangeT& Search )
160         {
161             find_format( 
162                 Input, 
163                 first_finder(Search),
164                 empty_formatter(Input) );
165         }
166
167 //  erase_first ( case insensitive ) ------------------------------------//
168
169         //! Erase first algorithm ( case insensitive )
170         /*!
171             Remove the first occurrence of the substring from the input. 
172             The result is a modified copy of the input. It is returned as a sequence 
173             or copied to the output iterator.
174             Searching is case insensitive.
175
176             \param Output An output iterator to which the result will be copied
177             \param Input An input string
178             \param Search A substring to be searched for 
179             \param Loc A locale used for case insensitive comparison
180             \return An output iterator pointing just after the last inserted character or
181                 a modified copy of the input
182
183             \note The second variant of this function provides the strong exception-safety guarantee
184         */
185         template<
186             typename OutputIteratorT,
187             typename Range1T, 
188             typename Range2T>
189         inline OutputIteratorT ierase_first_copy(
190             OutputIteratorT Output,
191             const Range1T& Input,
192             const Range2T& Search,
193             const std::locale& Loc=std::locale() )
194         {
195             return find_format_copy(
196                 Output,
197                 Input,
198                 first_finder(Search, is_iequal(Loc)),
199                 empty_formatter(Input) );
200         }
201
202         //! Erase first algorithm ( case insensitive )
203         /*!
204             \overload
205         */
206         template<typename SequenceT, typename RangeT>
207         inline SequenceT ierase_first_copy( 
208             const SequenceT& Input,
209             const RangeT& Search,
210             const std::locale& Loc=std::locale() )
211         {
212             return find_format_copy( 
213                 Input, 
214                 first_finder(Search, is_iequal(Loc)),
215                 empty_formatter(Input) );
216         }
217
218         //! Erase first algorithm ( case insensitive )
219         /*!
220             Remove the first occurrence of the substring from the input. 
221             The input sequence is modified in-place. Searching is case insensitive.
222
223             \param Input An input string
224             \param Search A substring to be searched for
225             \param Loc A locale used for case insensitive comparison
226         */
227         template<typename SequenceT, typename RangeT>
228         inline void ierase_first( 
229             SequenceT& Input,
230             const RangeT& Search,
231             const std::locale& Loc=std::locale() )
232         {
233             find_format( 
234                 Input, 
235                 first_finder(Search, is_iequal(Loc)),
236                 empty_formatter(Input) );
237         }
238
239 //  erase_last  --------------------------------------------------------//
240
241         //! Erase last algorithm
242         /*!
243             Remove the last occurrence of the substring from the input. 
244             The result is a modified copy of the input. It is returned as a sequence 
245             or copied to the output iterator.
246
247             \param Output An output iterator to which the result will be copied
248             \param Input An input string
249             \param Search A substring to be searched for.
250             \return An output iterator pointing just after the last inserted character or
251                 a modified copy of the input
252
253              \note The second variant of this function provides the strong exception-safety guarantee
254         */
255         template<
256             typename OutputIteratorT,
257             typename Range1T, 
258             typename Range2T>
259         inline OutputIteratorT erase_last_copy(
260             OutputIteratorT Output,
261             const Range1T& Input,
262             const Range2T& Search )
263         {
264             return find_format_copy(
265                 Output,
266                 Input,
267                 last_finder(Search),
268                 empty_formatter(Input) );
269         }
270
271         //! Erase last algorithm
272         /*!
273             \overload
274         */
275         template<typename SequenceT, typename RangeT>
276         inline SequenceT erase_last_copy( 
277             const SequenceT& Input,
278             const RangeT& Search )
279         {
280             return find_format_copy( 
281                 Input, 
282                 last_finder(Search),
283                 empty_formatter(Input) );
284         }
285
286         //! Erase last algorithm
287         /*!
288             Remove the last occurrence of the substring from the input. 
289             The input sequence is modified in-place.
290
291             \param Input An input string
292             \param Search A substring to be searched for 
293         */
294         template<typename SequenceT, typename RangeT>
295         inline void erase_last( 
296             SequenceT& Input,
297             const RangeT& Search )
298         {
299             find_format( 
300                 Input, 
301                 last_finder(Search),
302                 empty_formatter(Input) );
303         }
304
305 //  erase_last ( case insensitive ) ------------------------------------//
306
307         //! Erase last algorithm ( case insensitive )
308         /*!
309             Remove the last occurrence of the substring from the input. 
310             The result is a modified copy of the input. It is returned as a sequence 
311             or copied to the output iterator.
312             Searching is case insensitive.
313
314             \param Output An output iterator to which the result will be copied
315             \param Input An input string
316             \param Search A substring to be searched for
317             \param Loc A locale used for case insensitive comparison
318             \return An output iterator pointing just after the last inserted character or
319                 a modified copy of the input
320
321              \note The second variant of this function provides the strong exception-safety guarantee
322         */
323         template<
324             typename OutputIteratorT,
325             typename Range1T, 
326             typename Range2T>
327         inline OutputIteratorT ierase_last_copy(
328             OutputIteratorT Output,
329             const Range1T& Input,
330             const Range2T& Search,
331             const std::locale& Loc=std::locale() )
332         {
333             return find_format_copy(
334                 Output,
335                 Input,
336                 last_finder(Search, is_iequal(Loc)),
337                 empty_formatter(Input) );
338         }
339
340         //! Erase last algorithm ( case insensitive )
341         /*!
342             \overload
343         */
344         template<typename SequenceT, typename RangeT>
345         inline SequenceT ierase_last_copy( 
346             const SequenceT& Input,
347             const RangeT& Search,
348             const std::locale& Loc=std::locale() )
349         {
350             return find_format_copy( 
351                 Input, 
352                 last_finder(Search, is_iequal(Loc)),
353                 empty_formatter(Input) );
354         }
355
356         //! Erase last algorithm ( case insensitive )
357         /*!
358             Remove the last occurrence of the substring from the input. 
359             The input sequence is modified in-place. Searching is case insensitive.
360
361             \param Input An input string
362             \param Search A substring to be searched for
363             \param Loc A locale used for case insensitive comparison
364         */
365         template<typename SequenceT, typename RangeT>
366         inline void ierase_last( 
367             SequenceT& Input,
368             const RangeT& Search,
369             const std::locale& Loc=std::locale() )
370         {
371             find_format( 
372                 Input, 
373                 last_finder(Search, is_iequal(Loc)),
374                 empty_formatter(Input) );
375         }
376
377 //  erase_nth --------------------------------------------------------------------//
378
379         //! Erase nth algorithm
380         /*!
381             Remove the Nth occurrence of the substring in the input.
382             The result is a modified copy of the input. It is returned as a sequence 
383             or copied to the output iterator.
384             
385
386             \param Output An output iterator to which the result will be copied
387             \param Input An input string
388             \param Search A substring to be searched for
389             \param Nth An index of the match to be replaced. The index is 0-based.
390             \return An output iterator pointing just after the last inserted character or
391                 a modified copy of the input
392
393              \note The second variant of this function provides the strong exception-safety guarantee
394         */
395         template<
396             typename OutputIteratorT,
397             typename Range1T, 
398             typename Range2T>
399         inline OutputIteratorT erase_nth_copy(
400             OutputIteratorT Output,
401             const Range1T& Input,
402             const Range2T& Search,
403             unsigned int Nth )
404         {
405             return find_format_copy(
406                 Output,
407                 Input,
408                 nth_finder(Search, Nth),
409                 empty_formatter(Input) );
410         }
411
412         //! Erase nth algorithm
413         /*!
414             \overload
415         */
416         template<typename SequenceT, typename RangeT>
417         inline SequenceT erase_nth_copy( 
418             const SequenceT& Input,
419             const RangeT& Search,
420             unsigned int Nth )
421         {
422             return find_format_copy( 
423                 Input, 
424                 nth_finder(Search, Nth),
425                 empty_formatter(Input) );
426         }
427
428         //! Erase nth algorithm
429         /*!
430             Remove the Nth occurrence of the substring in the input.
431             The input sequence is modified in-place.
432
433             \param Input An input string
434             \param Search A substring to be searched for. 
435             \param Nth An index of the match to be replaced. The index is 0-based.
436         */
437         template<typename SequenceT, typename RangeT>
438         inline void erase_nth( 
439             SequenceT& Input,
440             const RangeT& Search,
441             unsigned int Nth )
442         {
443             find_format( 
444                 Input, 
445                 nth_finder(Search, Nth),
446                 empty_formatter(Input) );
447         }
448
449 //  erase_nth ( case insensitive ) ---------------------------------------------//
450
451         //! Erase nth algorithm ( case insensitive )
452         /*!
453             Remove the Nth occurrence of the substring in the input.
454             The result is a modified copy of the input. It is returned as a sequence 
455             or copied to the output iterator. 
456             Searching is case insensitive.
457
458             \param Output An output iterator to which the result will be copied
459             \param Input An input string
460             \param Search A substring to be searched for.
461             \param Nth An index of the match to be replaced. The index is 0-based.
462             \param Loc A locale used for case insensitive comparison
463             \return An output iterator pointing just after the last inserted character or
464                 a modified copy of the input
465
466             \note The second variant of this function provides the strong exception-safety guarantee
467         */
468         template<
469             typename OutputIteratorT,
470             typename Range1T, 
471             typename Range2T>
472         inline OutputIteratorT ierase_nth_copy(
473             OutputIteratorT Output,
474             const Range1T& Input,
475             const Range2T& Search,
476             unsigned int Nth,
477             const std::locale& Loc=std::locale() )
478         {
479             return find_format_copy(
480                 Output,
481                 Input,
482                 nth_finder(Search, Nth, is_iequal(Loc)),
483                 empty_formatter(Input) );
484         }
485
486         //! Erase nth algorithm
487         /*!
488             \overload
489         */
490         template<typename SequenceT, typename RangeT>
491         inline SequenceT ierase_nth_copy( 
492             const SequenceT& Input,
493             const RangeT& Search,
494             unsigned int Nth,
495             const std::locale& Loc=std::locale() )
496         {
497             return find_format_copy( 
498                 Input, 
499                 nth_finder(Search, Nth, is_iequal(Loc)),
500                 empty_formatter(Input) );
501         }
502
503         //! Erase nth algorithm
504         /*!
505             Remove the Nth occurrence of the substring in the input.
506             The input sequence is modified in-place. Searching is case insensitive.
507
508             \param Input An input string
509             \param Search A substring to be searched for. 
510             \param Nth An index of the match to be replaced. The index is 0-based.
511             \param Loc A locale used for case insensitive comparison
512         */
513         template<typename SequenceT, typename RangeT>
514         inline void ierase_nth( 
515             SequenceT& Input,
516             const RangeT& Search,
517             unsigned int Nth,
518             const std::locale& Loc=std::locale() )
519         {
520             find_format( 
521                 Input, 
522                 nth_finder(Search, Nth, is_iequal(Loc)),
523                 empty_formatter(Input) );
524         }
525
526
527 //  erase_all  --------------------------------------------------------//
528
529         //! Erase all algorithm
530         /*!
531             Remove all the occurrences of the string from the input. 
532             The result is a modified copy of the input. It is returned as a sequence 
533             or copied to the output iterator.
534                         
535
536             \param Output An output iterator to which the result will be copied
537             \param Input An input sequence
538             \param Search A substring to be searched for. 
539             \return An output iterator pointing just after the last inserted character or
540                     a modified copy of the input
541
542             \note The second variant of this function provides the strong exception-safety guarantee
543         */
544         template<
545             typename OutputIteratorT,
546             typename Range1T, 
547             typename Range2T>
548         inline OutputIteratorT erase_all_copy(
549             OutputIteratorT Output,
550             const Range1T& Input,
551             const Range2T& Search )
552         {
553             return find_format_all_copy(
554                 Output,
555                 Input,
556                 first_finder(Search),
557                 empty_formatter(Input) );
558         }
559
560         //! Erase all algorithm
561         /*!
562             \overload
563         */  
564         template<typename SequenceT, typename RangeT>
565         inline SequenceT erase_all_copy( 
566             const SequenceT& Input,
567             const RangeT& Search )
568         {
569             return find_format_all_copy( 
570                 Input, 
571                 first_finder(Search),
572                 empty_formatter(Input) );
573         }
574
575         //! Erase all algorithm
576         /*!
577             Remove all the occurrences of the string from the input. 
578             The input sequence is modified in-place.
579
580             \param Input An input string
581             \param Search A substring to be searched for. 
582         */
583         template<typename SequenceT, typename RangeT>
584         inline void erase_all( 
585             SequenceT& Input,
586             const RangeT& Search )
587         {
588             find_format_all( 
589                 Input, 
590                 first_finder(Search),
591                 empty_formatter(Input) );
592         }
593
594 //  erase_all ( case insensitive ) ------------------------------------//
595
596         //! Erase all algorithm ( case insensitive )
597         /*!
598             Remove all the occurrences of the string from the input. 
599             The result is a modified copy of the input. It is returned as a sequence 
600             or copied to the output iterator. 
601             Searching is case insensitive.
602
603             \param Output An output iterator to which the result will be copied
604             \param Input An input string
605             \param Search A substring to be searched for
606             \param Loc A locale used for case insensitive comparison
607             \return An output iterator pointing just after the last inserted character or
608                     a modified copy of the input
609
610               \note The second variant of this function provides the strong exception-safety guarantee
611         */
612         template<
613             typename OutputIteratorT,
614             typename Range1T, 
615             typename Range2T>
616         inline OutputIteratorT ierase_all_copy(
617             OutputIteratorT Output,
618             const Range1T& Input,
619             const Range2T& Search,
620             const std::locale& Loc=std::locale() )
621         {
622             return find_format_all_copy(
623                 Output,
624                 Input,
625                 first_finder(Search, is_iequal(Loc)),
626                 empty_formatter(Input) );
627         }
628
629         //! Erase all algorithm ( case insensitive )
630         /*!
631             \overload
632         */
633         template<typename SequenceT, typename RangeT>
634         inline SequenceT ierase_all_copy( 
635             const SequenceT& Input,
636             const RangeT& Search,
637             const std::locale& Loc=std::locale() )
638         {
639             return find_format_all_copy( 
640                 Input, 
641                 first_finder(Search, is_iequal(Loc)),
642                 empty_formatter(Input) );
643         }
644
645         //! Erase all algorithm ( case insensitive )
646         /*!
647             Remove all the occurrences of the string from the input. 
648             The input sequence is modified in-place. Searching is case insensitive.
649
650             \param Input An input string
651             \param Search A substring to be searched for. 
652             \param Loc A locale used for case insensitive comparison
653         */
654         template<typename SequenceT, typename RangeT>
655         inline void ierase_all( 
656             SequenceT& Input,
657             const RangeT& Search,
658             const std::locale& Loc=std::locale() )
659         {
660             find_format_all( 
661                 Input, 
662                 first_finder(Search, is_iequal(Loc)),
663                 empty_formatter(Input) );
664         }
665
666 //  erase_head --------------------------------------------------------------------//
667
668         //! Erase head algorithm
669         /*!
670             Remove the head from the input. The head is a prefix of a sequence of given size. 
671             If the sequence is shorter then required, the whole string is 
672             considered to be the head. The result is a modified copy of the input. 
673             It is returned as a sequence or copied to the output iterator.
674             
675
676             \param Output An output iterator to which the result will be copied
677             \param Input An input string
678             \param N Length of the head
679             \return An output iterator pointing just after the last inserted character or
680                 a modified copy of the input
681
682              \note The second variant of this function provides the strong exception-safety guarantee
683         */
684         template<
685             typename OutputIteratorT,
686             typename RangeT>
687         inline OutputIteratorT erase_head_copy(
688             OutputIteratorT Output,
689             const RangeT& Input,
690             unsigned int N )
691         {
692             return find_format_copy(
693                 Output,
694                 Input,
695                 head_finder(N),
696                 empty_formatter( Input ) );
697         }
698
699         //! Erase head algorithm
700         /*!
701             \overload
702         */
703         template<typename SequenceT>
704         inline SequenceT erase_head_copy( 
705             const SequenceT& Input,
706             unsigned int N )
707         {
708             return find_format_copy( 
709                 Input,
710                 head_finder(N),
711                 empty_formatter( Input ) );
712         }
713
714         //! Erase head algorithm
715         /*!
716             Remove the head from the input. The head is a prefix of a sequence of given size. 
717             If the sequence is shorter then required, the whole string is 
718             considered to be the head. The input sequence is modified in-place.
719
720             \param Input An input string
721             \param N Length of the head
722         */
723         template<typename SequenceT>
724         inline void erase_head( 
725             SequenceT& Input,
726             unsigned int N )
727         {
728             find_format( 
729                 Input, 
730                 head_finder(N),
731                 empty_formatter( Input ) );
732         }
733
734 //  erase_tail --------------------------------------------------------------------//
735
736         //! Erase tail algorithm
737         /*!
738             Remove the tail from the input. The tail is a suffix of a sequence of given size. 
739             If the sequence is shorter then required, the whole string is 
740             considered to be the tail. 
741             The result is a modified copy of the input. It is returned as a sequence 
742             or copied to the output iterator.
743
744             \param Output An output iterator to which the result will be copied
745             \param Input An input string
746             \param N Length of the head
747             \return An output iterator pointing just after the last inserted character or
748                 a modified copy of the input
749             
750              \note The second variant of this function provides the strong exception-safety guarantee
751         */
752         template<
753             typename OutputIteratorT,
754             typename RangeT>
755         inline OutputIteratorT erase_tail_copy(
756             OutputIteratorT Output,
757             const RangeT& Input,
758             unsigned int N )
759         {
760             return find_format_copy(
761                 Output,
762                 Input,
763                 tail_finder(N),
764                 empty_formatter( Input ) );
765         }
766
767         //! Erase tail algorithm
768         /*!
769             \overload
770         */
771         template<typename SequenceT>
772         inline SequenceT erase_tail_copy( 
773             const SequenceT& Input,
774             unsigned int N )
775         {
776             return find_format_copy( 
777                 Input,
778                 tail_finder(N),
779                 empty_formatter( Input ) );
780         }
781
782         //! Erase tail algorithm
783         /*!
784             Remove the tail from the input. The tail is a suffix of a sequence of given size. 
785             If the sequence is shorter then required, the whole string is
786             considered to be the tail. The input sequence is modified in-place.
787
788             \param Input An input string
789             \param N Length of the head
790         */
791         template<typename SequenceT>
792         inline void erase_tail( 
793             SequenceT& Input,
794             unsigned int N )
795         {
796             find_format( 
797                 Input, 
798                 tail_finder(N),
799                 empty_formatter( Input ) );
800         }
801
802     } // namespace algorithm
803
804     // pull names into the boost namespace
805     using algorithm::erase_range_copy;
806     using algorithm::erase_range;
807     using algorithm::erase_first_copy;
808     using algorithm::erase_first;
809     using algorithm::ierase_first_copy;
810     using algorithm::ierase_first;
811     using algorithm::erase_last_copy;
812     using algorithm::erase_last;
813     using algorithm::ierase_last_copy;
814     using algorithm::ierase_last;
815     using algorithm::erase_nth_copy;
816     using algorithm::erase_nth;
817     using algorithm::ierase_nth_copy;
818     using algorithm::ierase_nth;
819     using algorithm::erase_all_copy;
820     using algorithm::erase_all;
821     using algorithm::ierase_all_copy;
822     using algorithm::ierase_all;
823     using algorithm::erase_head_copy;
824     using algorithm::erase_head;
825     using algorithm::erase_tail_copy;
826     using algorithm::erase_tail;
827
828 } // namespace boost
829
830
831 #endif  // BOOST_ERASE_HPP