1 // Boost string_algo library erase.hpp header file ---------------------------//
3 // Copyright Pavol Droba 2002-2006.
5 // Distributed under the Boost Software License, Version 1.0.
6 // (See accompanying file LICENSE_1_0.txt or copy at
7 // http://www.boost.org/LICENSE_1_0.txt)
9 // See http://www.boost.org/ for updates, documentation, and revision history.
11 #ifndef BOOST_STRING_ERASE_HPP
12 #define BOOST_STRING_ERASE_HPP
14 #include <boost/algorithm/string/config.hpp>
16 #include <boost/range/iterator_range_core.hpp>
17 #include <boost/range/begin.hpp>
18 #include <boost/range/end.hpp>
19 #include <boost/range/iterator.hpp>
20 #include <boost/range/const_iterator.hpp>
22 #include <boost/algorithm/string/find_format.hpp>
23 #include <boost/algorithm/string/finder.hpp>
24 #include <boost/algorithm/string/formatter.hpp>
27 Defines various erase algorithms. Each algorithm removes
28 part(s) of the input according to a searching criteria.
34 // erase_range -------------------------------------------------------//
36 //! Erase range algorithm
38 Remove the given range from the input. The result is a modified copy of
39 the input. It is returned as a sequence or copied to the output iterator.
41 \param Output An output iterator to which the result will be copied
42 \param Input An input sequence
43 \param SearchRange A range in the input to be removed
44 \return An output iterator pointing just after the last inserted character or
45 a modified copy of the input
47 \note The second variant of this function provides the strong exception-safety guarantee
49 template<typename OutputIteratorT, typename RangeT>
50 inline OutputIteratorT erase_range_copy(
51 OutputIteratorT Output,
55 range_const_iterator<RangeT>::type>& SearchRange )
57 return ::boost::algorithm::find_format_copy(
60 ::boost::algorithm::range_finder(SearchRange),
61 ::boost::algorithm::empty_formatter(Input) );
64 //! Erase range algorithm
68 template<typename SequenceT>
69 inline SequenceT erase_range_copy(
70 const SequenceT& Input,
73 range_const_iterator<SequenceT>::type>& SearchRange )
75 return ::boost::algorithm::find_format_copy(
77 ::boost::algorithm::range_finder(SearchRange),
78 ::boost::algorithm::empty_formatter(Input) );
81 //! Erase range algorithm
83 Remove the given range from the input.
84 The input sequence is modified in-place.
86 \param Input An input sequence
87 \param SearchRange A range in the input to be removed
89 template<typename SequenceT>
90 inline void erase_range(
94 range_iterator<SequenceT>::type>& SearchRange )
96 ::boost::algorithm::find_format(
98 ::boost::algorithm::range_finder(SearchRange),
99 ::boost::algorithm::empty_formatter(Input) );
102 // erase_first --------------------------------------------------------//
104 //! Erase first algorithm
106 Remove the first occurrence of the substring from the input.
107 The result is a modified copy of the input. It is returned as a sequence
108 or copied to the output iterator.
110 \param Output An output iterator to which the result will be copied
111 \param Input An input string
112 \param Search A substring to be searched for
113 \return An output iterator pointing just after the last inserted character or
114 a modified copy of the input
116 \note The second variant of this function provides the strong exception-safety guarantee
119 typename OutputIteratorT,
122 inline OutputIteratorT erase_first_copy(
123 OutputIteratorT Output,
124 const Range1T& Input,
125 const Range2T& Search )
127 return ::boost::algorithm::find_format_copy(
130 ::boost::algorithm::first_finder(Search),
131 ::boost::algorithm::empty_formatter(Input) );
134 //! Erase first algorithm
138 template<typename SequenceT, typename RangeT>
139 inline SequenceT erase_first_copy(
140 const SequenceT& Input,
141 const RangeT& Search )
143 return ::boost::algorithm::find_format_copy(
145 ::boost::algorithm::first_finder(Search),
146 ::boost::algorithm::empty_formatter(Input) );
149 //! Erase first algorithm
151 Remove the first occurrence of the substring from the input.
152 The input sequence is modified in-place.
154 \param Input An input string
155 \param Search A substring to be searched for.
157 template<typename SequenceT, typename RangeT>
158 inline void erase_first(
160 const RangeT& Search )
162 ::boost::algorithm::find_format(
164 ::boost::algorithm::first_finder(Search),
165 ::boost::algorithm::empty_formatter(Input) );
168 // erase_first ( case insensitive ) ------------------------------------//
170 //! Erase first algorithm ( case insensitive )
172 Remove the first occurrence of the substring from the input.
173 The result is a modified copy of the input. It is returned as a sequence
174 or copied to the output iterator.
175 Searching is case insensitive.
177 \param Output An output iterator to which the result will be copied
178 \param Input An input string
179 \param Search A substring to be searched for
180 \param Loc A locale used for case insensitive comparison
181 \return An output iterator pointing just after the last inserted character or
182 a modified copy of the input
184 \note The second variant of this function provides the strong exception-safety guarantee
187 typename OutputIteratorT,
190 inline OutputIteratorT ierase_first_copy(
191 OutputIteratorT Output,
192 const Range1T& Input,
193 const Range2T& Search,
194 const std::locale& Loc=std::locale() )
196 return ::boost::algorithm::find_format_copy(
199 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
200 ::boost::algorithm::empty_formatter(Input) );
203 //! Erase first algorithm ( case insensitive )
207 template<typename SequenceT, typename RangeT>
208 inline SequenceT ierase_first_copy(
209 const SequenceT& Input,
210 const RangeT& Search,
211 const std::locale& Loc=std::locale() )
213 return ::boost::algorithm::find_format_copy(
215 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
216 ::boost::algorithm::empty_formatter(Input) );
219 //! Erase first algorithm ( case insensitive )
221 Remove the first occurrence of the substring from the input.
222 The input sequence is modified in-place. Searching is case insensitive.
224 \param Input An input string
225 \param Search A substring to be searched for
226 \param Loc A locale used for case insensitive comparison
228 template<typename SequenceT, typename RangeT>
229 inline void ierase_first(
231 const RangeT& Search,
232 const std::locale& Loc=std::locale() )
234 ::boost::algorithm::find_format(
236 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
237 ::boost::algorithm::empty_formatter(Input) );
240 // erase_last --------------------------------------------------------//
242 //! Erase last algorithm
244 Remove the last occurrence of the substring from the input.
245 The result is a modified copy of the input. It is returned as a sequence
246 or copied to the output iterator.
248 \param Output An output iterator to which the result will be copied
249 \param Input An input string
250 \param Search A substring to be searched for.
251 \return An output iterator pointing just after the last inserted character or
252 a modified copy of the input
254 \note The second variant of this function provides the strong exception-safety guarantee
257 typename OutputIteratorT,
260 inline OutputIteratorT erase_last_copy(
261 OutputIteratorT Output,
262 const Range1T& Input,
263 const Range2T& Search )
265 return ::boost::algorithm::find_format_copy(
268 ::boost::algorithm::last_finder(Search),
269 ::boost::algorithm::empty_formatter(Input) );
272 //! Erase last algorithm
276 template<typename SequenceT, typename RangeT>
277 inline SequenceT erase_last_copy(
278 const SequenceT& Input,
279 const RangeT& Search )
281 return ::boost::algorithm::find_format_copy(
283 ::boost::algorithm::last_finder(Search),
284 ::boost::algorithm::empty_formatter(Input) );
287 //! Erase last algorithm
289 Remove the last occurrence of the substring from the input.
290 The input sequence is modified in-place.
292 \param Input An input string
293 \param Search A substring to be searched for
295 template<typename SequenceT, typename RangeT>
296 inline void erase_last(
298 const RangeT& Search )
300 ::boost::algorithm::find_format(
302 ::boost::algorithm::last_finder(Search),
303 ::boost::algorithm::empty_formatter(Input) );
306 // erase_last ( case insensitive ) ------------------------------------//
308 //! Erase last algorithm ( case insensitive )
310 Remove the last occurrence of the substring from the input.
311 The result is a modified copy of the input. It is returned as a sequence
312 or copied to the output iterator.
313 Searching is case insensitive.
315 \param Output An output iterator to which the result will be copied
316 \param Input An input string
317 \param Search A substring to be searched for
318 \param Loc A locale used for case insensitive comparison
319 \return An output iterator pointing just after the last inserted character or
320 a modified copy of the input
322 \note The second variant of this function provides the strong exception-safety guarantee
325 typename OutputIteratorT,
328 inline OutputIteratorT ierase_last_copy(
329 OutputIteratorT Output,
330 const Range1T& Input,
331 const Range2T& Search,
332 const std::locale& Loc=std::locale() )
334 return ::boost::algorithm::find_format_copy(
337 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
338 ::boost::algorithm::empty_formatter(Input) );
341 //! Erase last algorithm ( case insensitive )
345 template<typename SequenceT, typename RangeT>
346 inline SequenceT ierase_last_copy(
347 const SequenceT& Input,
348 const RangeT& Search,
349 const std::locale& Loc=std::locale() )
351 return ::boost::algorithm::find_format_copy(
353 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
354 ::boost::algorithm::empty_formatter(Input) );
357 //! Erase last algorithm ( case insensitive )
359 Remove the last occurrence of the substring from the input.
360 The input sequence is modified in-place. Searching is case insensitive.
362 \param Input An input string
363 \param Search A substring to be searched for
364 \param Loc A locale used for case insensitive comparison
366 template<typename SequenceT, typename RangeT>
367 inline void ierase_last(
369 const RangeT& Search,
370 const std::locale& Loc=std::locale() )
372 ::boost::algorithm::find_format(
374 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
375 ::boost::algorithm::empty_formatter(Input) );
378 // erase_nth --------------------------------------------------------------------//
380 //! Erase nth algorithm
382 Remove the Nth occurrence of the substring in the input.
383 The result is a modified copy of the input. It is returned as a sequence
384 or copied to the output iterator.
387 \param Output An output iterator to which the result will be copied
388 \param Input An input string
389 \param Search A substring to be searched for
390 \param Nth An index of the match to be replaced. The index is 0-based.
391 For negative N, matches are counted from the end of string.
392 \return An output iterator pointing just after the last inserted character or
393 a modified copy of the input
395 \note The second variant of this function provides the strong exception-safety guarantee
398 typename OutputIteratorT,
401 inline OutputIteratorT erase_nth_copy(
402 OutputIteratorT Output,
403 const Range1T& Input,
404 const Range2T& Search,
407 return ::boost::algorithm::find_format_copy(
410 ::boost::algorithm::nth_finder(Search, Nth),
411 ::boost::algorithm::empty_formatter(Input) );
414 //! Erase nth algorithm
418 template<typename SequenceT, typename RangeT>
419 inline SequenceT erase_nth_copy(
420 const SequenceT& Input,
421 const RangeT& Search,
424 return ::boost::algorithm::find_format_copy(
426 ::boost::algorithm::nth_finder(Search, Nth),
427 ::boost::algorithm::empty_formatter(Input) );
430 //! Erase nth algorithm
432 Remove the Nth occurrence of the substring in the input.
433 The input sequence is modified in-place.
435 \param Input An input string
436 \param Search A substring to be searched for.
437 \param Nth An index of the match to be replaced. The index is 0-based.
438 For negative N, matches are counted from the end of string.
440 template<typename SequenceT, typename RangeT>
441 inline void erase_nth(
443 const RangeT& Search,
446 ::boost::algorithm::find_format(
448 ::boost::algorithm::nth_finder(Search, Nth),
449 ::boost::algorithm::empty_formatter(Input) );
452 // erase_nth ( case insensitive ) ---------------------------------------------//
454 //! Erase nth algorithm ( case insensitive )
456 Remove the Nth occurrence of the substring in the input.
457 The result is a modified copy of the input. It is returned as a sequence
458 or copied to the output iterator.
459 Searching is case insensitive.
461 \param Output An output iterator to which the result will be copied
462 \param Input An input string
463 \param Search A substring to be searched for.
464 \param Nth An index of the match to be replaced. The index is 0-based.
465 For negative N, matches are counted from the end of string.
466 \param Loc A locale used for case insensitive comparison
467 \return An output iterator pointing just after the last inserted character or
468 a modified copy of the input
470 \note The second variant of this function provides the strong exception-safety guarantee
473 typename OutputIteratorT,
476 inline OutputIteratorT ierase_nth_copy(
477 OutputIteratorT Output,
478 const Range1T& Input,
479 const Range2T& Search,
481 const std::locale& Loc=std::locale() )
483 return ::boost::algorithm::find_format_copy(
486 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc)),
487 ::boost::algorithm::empty_formatter(Input) );
490 //! Erase nth algorithm
494 template<typename SequenceT, typename RangeT>
495 inline SequenceT ierase_nth_copy(
496 const SequenceT& Input,
497 const RangeT& Search,
499 const std::locale& Loc=std::locale() )
501 return ::boost::algorithm::find_format_copy(
503 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc)),
504 empty_formatter(Input) );
507 //! Erase nth algorithm
509 Remove the Nth occurrence of the substring in the input.
510 The input sequence is modified in-place. Searching is case insensitive.
512 \param Input An input string
513 \param Search A substring to be searched for.
514 \param Nth An index of the match to be replaced. The index is 0-based.
515 For negative N, matches are counted from the end of string.
516 \param Loc A locale used for case insensitive comparison
518 template<typename SequenceT, typename RangeT>
519 inline void ierase_nth(
521 const RangeT& Search,
523 const std::locale& Loc=std::locale() )
525 ::boost::algorithm::find_format(
527 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc)),
528 ::boost::algorithm::empty_formatter(Input) );
532 // erase_all --------------------------------------------------------//
534 //! Erase all algorithm
536 Remove all the occurrences of the string from the input.
537 The result is a modified copy of the input. It is returned as a sequence
538 or copied to the output iterator.
541 \param Output An output iterator to which the result will be copied
542 \param Input An input sequence
543 \param Search A substring to be searched for.
544 \return An output iterator pointing just after the last inserted character or
545 a modified copy of the input
547 \note The second variant of this function provides the strong exception-safety guarantee
550 typename OutputIteratorT,
553 inline OutputIteratorT erase_all_copy(
554 OutputIteratorT Output,
555 const Range1T& Input,
556 const Range2T& Search )
558 return ::boost::algorithm::find_format_all_copy(
561 ::boost::algorithm::first_finder(Search),
562 ::boost::algorithm::empty_formatter(Input) );
565 //! Erase all algorithm
569 template<typename SequenceT, typename RangeT>
570 inline SequenceT erase_all_copy(
571 const SequenceT& Input,
572 const RangeT& Search )
574 return ::boost::algorithm::find_format_all_copy(
576 ::boost::algorithm::first_finder(Search),
577 ::boost::algorithm::empty_formatter(Input) );
580 //! Erase all algorithm
582 Remove all the occurrences of the string from the input.
583 The input sequence is modified in-place.
585 \param Input An input string
586 \param Search A substring to be searched for.
588 template<typename SequenceT, typename RangeT>
589 inline void erase_all(
591 const RangeT& Search )
593 ::boost::algorithm::find_format_all(
595 ::boost::algorithm::first_finder(Search),
596 ::boost::algorithm::empty_formatter(Input) );
599 // erase_all ( case insensitive ) ------------------------------------//
601 //! Erase all algorithm ( case insensitive )
603 Remove all the occurrences of the string from the input.
604 The result is a modified copy of the input. It is returned as a sequence
605 or copied to the output iterator.
606 Searching is case insensitive.
608 \param Output An output iterator to which the result will be copied
609 \param Input An input string
610 \param Search A substring to be searched for
611 \param Loc A locale used for case insensitive comparison
612 \return An output iterator pointing just after the last inserted character or
613 a modified copy of the input
615 \note The second variant of this function provides the strong exception-safety guarantee
618 typename OutputIteratorT,
621 inline OutputIteratorT ierase_all_copy(
622 OutputIteratorT Output,
623 const Range1T& Input,
624 const Range2T& Search,
625 const std::locale& Loc=std::locale() )
627 return ::boost::algorithm::find_format_all_copy(
630 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
631 ::boost::algorithm::empty_formatter(Input) );
634 //! Erase all algorithm ( case insensitive )
638 template<typename SequenceT, typename RangeT>
639 inline SequenceT ierase_all_copy(
640 const SequenceT& Input,
641 const RangeT& Search,
642 const std::locale& Loc=std::locale() )
644 return ::boost::algorithm::find_format_all_copy(
646 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
647 ::boost::algorithm::empty_formatter(Input) );
650 //! Erase all algorithm ( case insensitive )
652 Remove all the occurrences of the string from the input.
653 The input sequence is modified in-place. Searching is case insensitive.
655 \param Input An input string
656 \param Search A substring to be searched for.
657 \param Loc A locale used for case insensitive comparison
659 template<typename SequenceT, typename RangeT>
660 inline void ierase_all(
662 const RangeT& Search,
663 const std::locale& Loc=std::locale() )
665 ::boost::algorithm::find_format_all(
667 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
668 ::boost::algorithm::empty_formatter(Input) );
671 // erase_head --------------------------------------------------------------------//
673 //! Erase head algorithm
675 Remove the head from the input. The head is a prefix of a sequence of given size.
676 If the sequence is shorter then required, the whole string is
677 considered to be the head. The result is a modified copy of the input.
678 It is returned as a sequence or copied to the output iterator.
681 \param Output An output iterator to which the result will be copied
682 \param Input An input string
683 \param N Length of the head.
684 For N>=0, at most N characters are extracted.
685 For N<0, size(Input)-|N| characters are extracted.
686 \return An output iterator pointing just after the last inserted character or
687 a modified copy of the input
689 \note The second variant of this function provides the strong exception-safety guarantee
692 typename OutputIteratorT,
694 inline OutputIteratorT erase_head_copy(
695 OutputIteratorT Output,
699 return ::boost::algorithm::find_format_copy(
702 ::boost::algorithm::head_finder(N),
703 ::boost::algorithm::empty_formatter( Input ) );
706 //! Erase head algorithm
710 template<typename SequenceT>
711 inline SequenceT erase_head_copy(
712 const SequenceT& Input,
715 return ::boost::algorithm::find_format_copy(
717 ::boost::algorithm::head_finder(N),
718 ::boost::algorithm::empty_formatter( Input ) );
721 //! Erase head algorithm
723 Remove the head from the input. The head is a prefix of a sequence of given size.
724 If the sequence is shorter then required, the whole string is
725 considered to be the head. The input sequence is modified in-place.
727 \param Input An input string
728 \param N Length of the head
729 For N>=0, at most N characters are extracted.
730 For N<0, size(Input)-|N| characters are extracted.
732 template<typename SequenceT>
733 inline void erase_head(
737 ::boost::algorithm::find_format(
739 ::boost::algorithm::head_finder(N),
740 ::boost::algorithm::empty_formatter( Input ) );
743 // erase_tail --------------------------------------------------------------------//
745 //! Erase tail algorithm
747 Remove the tail from the input. The tail is a suffix of a sequence of given size.
748 If the sequence is shorter then required, the whole string is
749 considered to be the tail.
750 The result is a modified copy of the input. It is returned as a sequence
751 or copied to the output iterator.
753 \param Output An output iterator to which the result will be copied
754 \param Input An input string
755 \param N Length of the tail.
756 For N>=0, at most N characters are extracted.
757 For N<0, size(Input)-|N| characters are extracted.
758 \return An output iterator pointing just after the last inserted character or
759 a modified copy of the input
761 \note The second variant of this function provides the strong exception-safety guarantee
764 typename OutputIteratorT,
766 inline OutputIteratorT erase_tail_copy(
767 OutputIteratorT Output,
771 return ::boost::algorithm::find_format_copy(
774 ::boost::algorithm::tail_finder(N),
775 ::boost::algorithm::empty_formatter( Input ) );
778 //! Erase tail algorithm
782 template<typename SequenceT>
783 inline SequenceT erase_tail_copy(
784 const SequenceT& Input,
787 return ::boost::algorithm::find_format_copy(
789 ::boost::algorithm::tail_finder(N),
790 ::boost::algorithm::empty_formatter( Input ) );
793 //! Erase tail algorithm
795 Remove the tail from the input. The tail is a suffix of a sequence of given size.
796 If the sequence is shorter then required, the whole string is
797 considered to be the tail. The input sequence is modified in-place.
799 \param Input An input string
800 \param N Length of the tail
801 For N>=0, at most N characters are extracted.
802 For N<0, size(Input)-|N| characters are extracted.
804 template<typename SequenceT>
805 inline void erase_tail(
809 ::boost::algorithm::find_format(
811 ::boost::algorithm::tail_finder(N),
812 ::boost::algorithm::empty_formatter( Input ) );
815 } // namespace algorithm
817 // pull names into the boost namespace
818 using algorithm::erase_range_copy;
819 using algorithm::erase_range;
820 using algorithm::erase_first_copy;
821 using algorithm::erase_first;
822 using algorithm::ierase_first_copy;
823 using algorithm::ierase_first;
824 using algorithm::erase_last_copy;
825 using algorithm::erase_last;
826 using algorithm::ierase_last_copy;
827 using algorithm::ierase_last;
828 using algorithm::erase_nth_copy;
829 using algorithm::erase_nth;
830 using algorithm::ierase_nth_copy;
831 using algorithm::ierase_nth;
832 using algorithm::erase_all_copy;
833 using algorithm::erase_all;
834 using algorithm::ierase_all_copy;
835 using algorithm::ierase_all;
836 using algorithm::erase_head_copy;
837 using algorithm::erase_head;
838 using algorithm::erase_tail_copy;
839 using algorithm::erase_tail;
844 #endif // BOOST_ERASE_HPP