1 // Boost string_algo library replace.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_REPLACE_HPP
12 #define BOOST_STRING_REPLACE_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>
25 #include <boost/algorithm/string/compare.hpp>
28 Defines various replace algorithms. Each algorithm replaces
29 part(s) of the input according to set of searching and replace criteria.
35 // replace_range --------------------------------------------------------------------//
37 //! Replace range algorithm
39 Replace the given range in the input string.
40 The result is a modified copy of the input. It is returned as a sequence
41 or copied to the output iterator.
43 \param Output An output iterator to which the result will be copied
44 \param Input An input string
45 \param SearchRange A range in the input to be substituted
46 \param Format A substitute string
47 \return An output iterator pointing just after the last inserted character or
48 a modified copy of the input
50 \note The second variant of this function provides the strong exception-safety guarantee
53 typename OutputIteratorT,
56 inline OutputIteratorT replace_range_copy(
57 OutputIteratorT Output,
61 range_const_iterator<Range1T>::type>& SearchRange,
62 const Range2T& Format)
64 return ::boost::algorithm::find_format_copy(
67 ::boost::algorithm::range_finder(SearchRange),
68 ::boost::algorithm::const_formatter(Format));
71 //! Replace range algorithm
75 template<typename SequenceT, typename RangeT>
76 inline SequenceT replace_range_copy(
77 const SequenceT& Input,
80 range_const_iterator<SequenceT>::type>& SearchRange,
83 return ::boost::algorithm::find_format_copy(
85 ::boost::algorithm::range_finder(SearchRange),
86 ::boost::algorithm::const_formatter(Format));
89 //! Replace range algorithm
91 Replace the given range in the input string.
92 The input sequence is modified in-place.
94 \param Input An input string
95 \param SearchRange A range in the input to be substituted
96 \param Format A substitute string
98 template<typename SequenceT, typename RangeT>
99 inline void replace_range(
101 const iterator_range<
102 BOOST_STRING_TYPENAME
103 range_iterator<SequenceT>::type>& SearchRange,
104 const RangeT& Format)
106 ::boost::algorithm::find_format(
108 ::boost::algorithm::range_finder(SearchRange),
109 ::boost::algorithm::const_formatter(Format));
112 // replace_first --------------------------------------------------------------------//
114 //! Replace first algorithm
116 Replace the first match of the search substring in the input
117 with the format string.
118 The result is a modified copy of the input. It is returned as a sequence
119 or copied to the output iterator.
121 \param Output An output iterator to which the result will be copied
122 \param Input An input string
123 \param Search A substring to be searched for
124 \param Format A substitute string
125 \return An output iterator pointing just after the last inserted character or
126 a modified copy of the input
128 \note The second variant of this function provides the strong exception-safety guarantee
131 typename OutputIteratorT,
135 inline OutputIteratorT replace_first_copy(
136 OutputIteratorT Output,
137 const Range1T& Input,
138 const Range2T& Search,
139 const Range3T& Format)
141 return ::boost::algorithm::find_format_copy(
144 ::boost::algorithm::first_finder(Search),
145 ::boost::algorithm::const_formatter(Format) );
148 //! Replace first algorithm
152 template<typename SequenceT, typename Range1T, typename Range2T>
153 inline SequenceT replace_first_copy(
154 const SequenceT& Input,
155 const Range1T& Search,
156 const Range2T& Format )
158 return ::boost::algorithm::find_format_copy(
160 ::boost::algorithm::first_finder(Search),
161 ::boost::algorithm::const_formatter(Format) );
164 //! Replace first algorithm
166 replace the first match of the search substring in the input
167 with the format string. The input sequence is modified in-place.
169 \param Input An input string
170 \param Search A substring to be searched for
171 \param Format A substitute string
173 template<typename SequenceT, typename Range1T, typename Range2T>
174 inline void replace_first(
176 const Range1T& Search,
177 const Range2T& Format )
179 ::boost::algorithm::find_format(
181 ::boost::algorithm::first_finder(Search),
182 ::boost::algorithm::const_formatter(Format) );
185 // replace_first ( case insensitive ) ---------------------------------------------//
187 //! Replace first algorithm ( case insensitive )
189 Replace the first match of the search substring in the input
190 with the format string.
191 The result is a modified copy of the input. It is returned as a sequence
192 or copied to the output iterator.
193 Searching is case insensitive.
195 \param Output An output iterator to which the result will be copied
196 \param Input An input string
197 \param Search A substring to be searched for
198 \param Format A substitute string
199 \param Loc A locale used for case insensitive comparison
200 \return An output iterator pointing just after the last inserted character or
201 a modified copy of the input
203 \note The second variant of this function provides the strong exception-safety guarantee
206 typename OutputIteratorT,
210 inline OutputIteratorT ireplace_first_copy(
211 OutputIteratorT Output,
212 const Range1T& Input,
213 const Range2T& Search,
214 const Range3T& Format,
215 const std::locale& Loc=std::locale() )
217 return ::boost::algorithm::find_format_copy(
220 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
221 ::boost::algorithm::const_formatter(Format) );
224 //! Replace first algorithm ( case insensitive )
228 template<typename SequenceT, typename Range2T, typename Range1T>
229 inline SequenceT ireplace_first_copy(
230 const SequenceT& Input,
231 const Range2T& Search,
232 const Range1T& Format,
233 const std::locale& Loc=std::locale() )
235 return ::boost::algorithm::find_format_copy(
237 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
238 ::boost::algorithm::const_formatter(Format) );
241 //! Replace first algorithm ( case insensitive )
243 Replace the first match of the search substring in the input
244 with the format string. Input sequence is modified in-place.
245 Searching is case insensitive.
247 \param Input An input string
248 \param Search A substring to be searched for
249 \param Format A substitute string
250 \param Loc A locale used for case insensitive comparison
252 template<typename SequenceT, typename Range1T, typename Range2T>
253 inline void ireplace_first(
255 const Range1T& Search,
256 const Range2T& Format,
257 const std::locale& Loc=std::locale() )
259 ::boost::algorithm::find_format(
261 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
262 ::boost::algorithm::const_formatter(Format) );
265 // replace_last --------------------------------------------------------------------//
267 //! Replace last algorithm
269 Replace the last match of the search string in the input
270 with the format string.
271 The result is a modified copy of the input. It is returned as a sequence
272 or copied to the output iterator.
274 \param Output An output iterator to which the result will be copied
275 \param Input An input string
276 \param Search A substring to be searched for
277 \param Format A substitute string
278 \return An output iterator pointing just after the last inserted character or
279 a modified copy of the input
281 \note The second variant of this function provides the strong exception-safety guarantee
284 typename OutputIteratorT,
288 inline OutputIteratorT replace_last_copy(
289 OutputIteratorT Output,
290 const Range1T& Input,
291 const Range2T& Search,
292 const Range3T& Format )
294 return ::boost::algorithm::find_format_copy(
297 ::boost::algorithm::last_finder(Search),
298 ::boost::algorithm::const_formatter(Format) );
301 //! Replace last algorithm
305 template<typename SequenceT, typename Range1T, typename Range2T>
306 inline SequenceT replace_last_copy(
307 const SequenceT& Input,
308 const Range1T& Search,
309 const Range2T& Format )
311 return ::boost::algorithm::find_format_copy(
313 ::boost::algorithm::last_finder(Search),
314 ::boost::algorithm::const_formatter(Format) );
317 //! Replace last algorithm
319 Replace the last match of the search string in the input
320 with the format string. Input sequence is modified in-place.
322 \param Input An input string
323 \param Search A substring to be searched for
324 \param Format A substitute string
326 template<typename SequenceT, typename Range1T, typename Range2T>
327 inline void replace_last(
329 const Range1T& Search,
330 const Range2T& Format )
332 ::boost::algorithm::find_format(
334 ::boost::algorithm::last_finder(Search),
335 ::boost::algorithm::const_formatter(Format) );
338 // replace_last ( case insensitive ) -----------------------------------------------//
340 //! Replace last algorithm ( case insensitive )
342 Replace the last match of the search string in the input
343 with the format string.
344 The result is a modified copy of the input. It is returned as a sequence
345 or copied to the output iterator.
346 Searching is case insensitive.
348 \param Output An output iterator to which the result will be copied
349 \param Input An input string
350 \param Search A substring to be searched for
351 \param Format A substitute string
352 \param Loc A locale used for case insensitive comparison
353 \return An output iterator pointing just after the last inserted character or
354 a modified copy of the input
356 \note The second variant of this function provides the strong exception-safety guarantee
359 typename OutputIteratorT,
363 inline OutputIteratorT ireplace_last_copy(
364 OutputIteratorT Output,
365 const Range1T& Input,
366 const Range2T& Search,
367 const Range3T& Format,
368 const std::locale& Loc=std::locale() )
370 return ::boost::algorithm::find_format_copy(
373 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
374 ::boost::algorithm::const_formatter(Format) );
377 //! Replace last algorithm ( case insensitive )
381 template<typename SequenceT, typename Range1T, typename Range2T>
382 inline SequenceT ireplace_last_copy(
383 const SequenceT& Input,
384 const Range1T& Search,
385 const Range2T& Format,
386 const std::locale& Loc=std::locale() )
388 return ::boost::algorithm::find_format_copy(
390 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
391 ::boost::algorithm::const_formatter(Format) );
394 //! Replace last algorithm ( case insensitive )
396 Replace the last match of the search string in the input
397 with the format string.The input sequence is modified in-place.
398 Searching is case insensitive.
400 \param Input An input string
401 \param Search A substring to be searched for
402 \param Format A substitute string
403 \param Loc A locale used for case insensitive comparison
405 template<typename SequenceT, typename Range1T, typename Range2T>
406 inline void ireplace_last(
408 const Range1T& Search,
409 const Range2T& Format,
410 const std::locale& Loc=std::locale() )
412 ::boost::algorithm::find_format(
414 ::boost::algorithm::last_finder(Search, is_iequal(Loc)),
415 ::boost::algorithm::const_formatter(Format) );
418 // replace_nth --------------------------------------------------------------------//
420 //! Replace nth algorithm
422 Replace an Nth (zero-indexed) match of the search string in the input
423 with the format string.
424 The result is a modified copy of the input. It is returned as a sequence
425 or copied to the output iterator.
427 \param Output An output iterator to which the result will be copied
428 \param Input An input string
429 \param Search A substring to be searched for
430 \param Nth An index of the match to be replaced. The index is 0-based.
431 For negative N, matches are counted from the end of string.
432 \param Format A substitute string
433 \return An output iterator pointing just after the last inserted character or
434 a modified copy of the input
436 \note The second variant of this function provides the strong exception-safety guarantee
439 typename OutputIteratorT,
443 inline OutputIteratorT replace_nth_copy(
444 OutputIteratorT Output,
445 const Range1T& Input,
446 const Range2T& Search,
448 const Range3T& Format )
450 return ::boost::algorithm::find_format_copy(
453 ::boost::algorithm::nth_finder(Search, Nth),
454 ::boost::algorithm::const_formatter(Format) );
457 //! Replace nth algorithm
461 template<typename SequenceT, typename Range1T, typename Range2T>
462 inline SequenceT replace_nth_copy(
463 const SequenceT& Input,
464 const Range1T& Search,
466 const Range2T& Format )
468 return ::boost::algorithm::find_format_copy(
470 ::boost::algorithm::nth_finder(Search, Nth),
471 ::boost::algorithm::const_formatter(Format) );
474 //! Replace nth algorithm
476 Replace an Nth (zero-indexed) match of the search string in the input
477 with the format string. Input sequence is modified in-place.
479 \param Input An input string
480 \param Search A substring to be searched for
481 \param Nth An index of the match to be replaced. The index is 0-based.
482 For negative N, matches are counted from the end of string.
483 \param Format A substitute string
485 template<typename SequenceT, typename Range1T, typename Range2T>
486 inline void replace_nth(
488 const Range1T& Search,
490 const Range2T& Format )
492 ::boost::algorithm::find_format(
494 ::boost::algorithm::nth_finder(Search, Nth),
495 ::boost::algorithm::const_formatter(Format) );
498 // replace_nth ( case insensitive ) -----------------------------------------------//
500 //! Replace nth algorithm ( case insensitive )
502 Replace an Nth (zero-indexed) match of the search string in the input
503 with the format string.
504 The result is a modified copy of the input. It is returned as a sequence
505 or copied to the output iterator.
506 Searching is case insensitive.
508 \param Output An output iterator to which the result will be copied
509 \param Input An input string
510 \param Search A substring to be searched for
511 \param Nth An index of the match to be replaced. The index is 0-based.
512 For negative N, matches are counted from the end of string.
513 \param Format A substitute string
514 \param Loc A locale used for case insensitive comparison
515 \return An output iterator pointing just after the last inserted character or
516 a modified copy of the input
518 \note The second variant of this function provides the strong exception-safety guarantee
521 typename OutputIteratorT,
525 inline OutputIteratorT ireplace_nth_copy(
526 OutputIteratorT Output,
527 const Range1T& Input,
528 const Range2T& Search,
530 const Range3T& Format,
531 const std::locale& Loc=std::locale() )
533 return ::boost::algorithm::find_format_copy(
536 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc) ),
537 ::boost::algorithm::const_formatter(Format) );
540 //! Replace nth algorithm ( case insensitive )
544 template<typename SequenceT, typename Range1T, typename Range2T>
545 inline SequenceT ireplace_nth_copy(
546 const SequenceT& Input,
547 const Range1T& Search,
549 const Range2T& Format,
550 const std::locale& Loc=std::locale() )
552 return ::boost::algorithm::find_format_copy(
554 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc)),
555 ::boost::algorithm::const_formatter(Format) );
558 //! Replace nth algorithm ( case insensitive )
560 Replace an Nth (zero-indexed) match of the search string in the input
561 with the format string. Input sequence is modified in-place.
562 Searching is case insensitive.
564 \param Input An input string
565 \param Search A substring to be searched for
566 \param Nth An index of the match to be replaced. The index is 0-based.
567 For negative N, matches are counted from the end of string.
568 \param Format A substitute string
569 \param Loc A locale used for case insensitive comparison
571 template<typename SequenceT, typename Range1T, typename Range2T>
572 inline void ireplace_nth(
574 const Range1T& Search,
576 const Range2T& Format,
577 const std::locale& Loc=std::locale() )
579 ::boost::algorithm::find_format(
581 ::boost::algorithm::nth_finder(Search, Nth, is_iequal(Loc)),
582 ::boost::algorithm::const_formatter(Format) );
585 // replace_all --------------------------------------------------------------------//
587 //! Replace all algorithm
589 Replace all occurrences of the search string in the input
590 with the format string.
591 The result is a modified copy of the input. It is returned as a sequence
592 or copied to the output iterator.
594 \param Output An output iterator to which the result will be copied
595 \param Input An input string
596 \param Search A substring to be searched for
597 \param Format A substitute string
598 \return An output iterator pointing just after the last inserted character or
599 a modified copy of the input
601 \note The second variant of this function provides the strong exception-safety guarantee
604 typename OutputIteratorT,
608 inline OutputIteratorT replace_all_copy(
609 OutputIteratorT Output,
610 const Range1T& Input,
611 const Range2T& Search,
612 const Range3T& Format )
614 return ::boost::algorithm::find_format_all_copy(
617 ::boost::algorithm::first_finder(Search),
618 ::boost::algorithm::const_formatter(Format) );
621 //! Replace all algorithm
625 template<typename SequenceT, typename Range1T, typename Range2T>
626 inline SequenceT replace_all_copy(
627 const SequenceT& Input,
628 const Range1T& Search,
629 const Range2T& Format )
631 return ::boost::algorithm::find_format_all_copy(
633 ::boost::algorithm::first_finder(Search),
634 ::boost::algorithm::const_formatter(Format) );
637 //! Replace all algorithm
639 Replace all occurrences of the search string in the input
640 with the format string. The input sequence is modified in-place.
642 \param Input An input string
643 \param Search A substring to be searched for
644 \param Format A substitute string
646 template<typename SequenceT, typename Range1T, typename Range2T>
647 inline void replace_all(
649 const Range1T& Search,
650 const Range2T& Format )
652 ::boost::algorithm::find_format_all(
654 ::boost::algorithm::first_finder(Search),
655 ::boost::algorithm::const_formatter(Format) );
658 // replace_all ( case insensitive ) -----------------------------------------------//
660 //! Replace all algorithm ( case insensitive )
662 Replace all occurrences of the search string in the input
663 with the format string.
664 The result is a modified copy of the input. It is returned as a sequence
665 or copied to the output iterator.
666 Searching is case insensitive.
668 \param Output An output iterator to which the result will be copied
669 \param Input An input string
670 \param Search A substring to be searched for
671 \param Format A substitute string
672 \param Loc A locale used for case insensitive comparison
673 \return An output iterator pointing just after the last inserted character or
674 a modified copy of the input
676 \note The second variant of this function provides the strong exception-safety guarantee
679 typename OutputIteratorT,
683 inline OutputIteratorT ireplace_all_copy(
684 OutputIteratorT Output,
685 const Range1T& Input,
686 const Range2T& Search,
687 const Range3T& Format,
688 const std::locale& Loc=std::locale() )
690 return ::boost::algorithm::find_format_all_copy(
693 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
694 ::boost::algorithm::const_formatter(Format) );
697 //! Replace all algorithm ( case insensitive )
701 template<typename SequenceT, typename Range1T, typename Range2T>
702 inline SequenceT ireplace_all_copy(
703 const SequenceT& Input,
704 const Range1T& Search,
705 const Range2T& Format,
706 const std::locale& Loc=std::locale() )
708 return ::boost::algorithm::find_format_all_copy(
710 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
711 ::boost::algorithm::const_formatter(Format) );
714 //! Replace all algorithm ( case insensitive )
716 Replace all occurrences of the search string in the input
717 with the format string.The input sequence is modified in-place.
718 Searching is case insensitive.
720 \param Input An input string
721 \param Search A substring to be searched for
722 \param Format A substitute string
723 \param Loc A locale used for case insensitive comparison
725 template<typename SequenceT, typename Range1T, typename Range2T>
726 inline void ireplace_all(
728 const Range1T& Search,
729 const Range2T& Format,
730 const std::locale& Loc=std::locale() )
732 ::boost::algorithm::find_format_all(
734 ::boost::algorithm::first_finder(Search, is_iequal(Loc)),
735 ::boost::algorithm::const_formatter(Format) );
738 // replace_head --------------------------------------------------------------------//
740 //! Replace head algorithm
742 Replace the head of the input with the given format string.
743 The head is a prefix of a string of given size.
744 If the sequence is shorter then required, whole string if
745 considered to be the head.
746 The result is a modified copy of the input. It is returned as a sequence
747 or copied to the output iterator.
749 \param Output An output iterator to which the result will be copied
750 \param Input An input string
751 \param N Length of the head.
752 For N>=0, at most N characters are extracted.
753 For N<0, size(Input)-|N| characters are extracted.
754 \param Format A substitute string
755 \return An output iterator pointing just after the last inserted character or
756 a modified copy of the input
758 \note The second variant of this function provides the strong exception-safety guarantee
761 typename OutputIteratorT,
764 inline OutputIteratorT replace_head_copy(
765 OutputIteratorT Output,
766 const Range1T& Input,
768 const Range2T& Format )
770 return ::boost::algorithm::find_format_copy(
773 ::boost::algorithm::head_finder(N),
774 ::boost::algorithm::const_formatter(Format) );
777 //! Replace head algorithm
781 template<typename SequenceT, typename RangeT>
782 inline SequenceT replace_head_copy(
783 const SequenceT& Input,
785 const RangeT& Format )
787 return ::boost::algorithm::find_format_copy(
789 ::boost::algorithm::head_finder(N),
790 ::boost::algorithm::const_formatter(Format) );
793 //! Replace head algorithm
795 Replace the head of the input with the given format string.
796 The head is a prefix of a string of given size.
797 If the sequence is shorter then required, the whole string is
798 considered to be the head. The input sequence is modified in-place.
800 \param Input An input string
801 \param N Length of the head.
802 For N>=0, at most N characters are extracted.
803 For N<0, size(Input)-|N| characters are extracted.
804 \param Format A substitute string
806 template<typename SequenceT, typename RangeT>
807 inline void replace_head(
810 const RangeT& Format )
812 ::boost::algorithm::find_format(
814 ::boost::algorithm::head_finder(N),
815 ::boost::algorithm::const_formatter(Format) );
818 // replace_tail --------------------------------------------------------------------//
820 //! Replace tail algorithm
822 Replace the tail of the input with the given format string.
823 The tail is a suffix of a string of given size.
824 If the sequence is shorter then required, whole string is
825 considered to be the tail.
826 The result is a modified copy of the input. It is returned as a sequence
827 or copied to the output iterator.
829 \param Output An output iterator to which the result will be copied
830 \param Input An input string
831 \param N Length of the tail.
832 For N>=0, at most N characters are extracted.
833 For N<0, size(Input)-|N| characters are extracted.
834 \param Format A substitute string
835 \return An output iterator pointing just after the last inserted character or
836 a modified copy of the input
838 \note The second variant of this function provides the strong exception-safety guarantee
841 typename OutputIteratorT,
844 inline OutputIteratorT replace_tail_copy(
845 OutputIteratorT Output,
846 const Range1T& Input,
848 const Range2T& Format )
850 return ::boost::algorithm::find_format_copy(
853 ::boost::algorithm::tail_finder(N),
854 ::boost::algorithm::const_formatter(Format) );
857 //! Replace tail algorithm
861 template<typename SequenceT, typename RangeT>
862 inline SequenceT replace_tail_copy(
863 const SequenceT& Input,
865 const RangeT& Format )
867 return ::boost::algorithm::find_format_copy(
869 ::boost::algorithm::tail_finder(N),
870 ::boost::algorithm::const_formatter(Format) );
873 //! Replace tail algorithm
875 Replace the tail of the input with the given format sequence.
876 The tail is a suffix of a string of given size.
877 If the sequence is shorter then required, the whole string is
878 considered to be the tail. The input sequence is modified in-place.
880 \param Input An input string
881 \param N Length of the tail.
882 For N>=0, at most N characters are extracted.
883 For N<0, size(Input)-|N| characters are extracted.
884 \param Format A substitute string
886 template<typename SequenceT, typename RangeT>
887 inline void replace_tail(
890 const RangeT& Format )
892 ::boost::algorithm::find_format(
894 ::boost::algorithm::tail_finder(N),
895 ::boost::algorithm::const_formatter(Format) );
898 } // namespace algorithm
900 // pull names to the boost namespace
901 using algorithm::replace_range_copy;
902 using algorithm::replace_range;
903 using algorithm::replace_first_copy;
904 using algorithm::replace_first;
905 using algorithm::ireplace_first_copy;
906 using algorithm::ireplace_first;
907 using algorithm::replace_last_copy;
908 using algorithm::replace_last;
909 using algorithm::ireplace_last_copy;
910 using algorithm::ireplace_last;
911 using algorithm::replace_nth_copy;
912 using algorithm::replace_nth;
913 using algorithm::ireplace_nth_copy;
914 using algorithm::ireplace_nth;
915 using algorithm::replace_all_copy;
916 using algorithm::replace_all;
917 using algorithm::ireplace_all_copy;
918 using algorithm::ireplace_all;
919 using algorithm::replace_head_copy;
920 using algorithm::replace_head;
921 using algorithm::replace_tail_copy;
922 using algorithm::replace_tail;
926 #endif // BOOST_REPLACE_HPP