.\" ident @(#)search.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH search 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2search\fP, \f2search_n\fP

\ - Finds a sub-sequence within a sequence of values that is element-wise equal to the values in an indicated range.



.SH  SYNOPSIS


.RE
.RS 0
#include <algorithm>
.br
template <class ForwardIterator1, class ForwardIterator2>
.br
ForwardIterator1 search (ForwardIterator1 first1,
.RE
.RS 25
ForwardIterator1 last1,
.br
ForwardIterator2 first2,
.br
ForwardIterator2 last2);
.RE
.RS 0

.br
template <class ForwardIterator1,
.RE
.RS 9
class ForwardIterator2,
.br
class BinaryPredicate>
.RE
.RS 0
ForwardIterator1 search (ForwardIterator1 first1,
.RE
.RS 25
ForwardIterator1 last1,
.br
ForwardIterator2 first2,
.br
ForwardIterator2 last2,
.br
BinaryPredicate binary_pred);
.RE
.RS 0

.br
template <class ForwardIterator, 
.RE
.RS 9
class Size, 
.br
class T>
.RE
.RS 0
ForwardIterator search_n (ForwardIterator first, 
.RE
.RS 25
ForwardIterator last,
.br
Size count, const T& value);
.RE
.RS 0

.br
template <class ForwardIterator, 
.RE
.RS 9
class Size, 
.br
class T, 
.br
class BinaryPredicate>
.RE
.RS 0
ForwardIterator search_n (ForwardIterator first, 
.RE
.RS 25
ForwardIterator last,
.br
Size count, const T& value,
.br
BinaryPredicate pred)



.SH  DESCRIPTION


The search and search_n algorithms search for a sub-sequence within a sequence. The search algorithm searches for a sub-sequence \f2[first2, last2) \fPwithin a sequence \f2[first1, last1)\fP, and returns the beginning location of the sub-sequence.   If it does not find the sub-sequence, search returns \f2last1\fP. The first version of search uses the equality (\f2==\fP) operator as a default, and the second version allows you to specify a binary predicate to perform the comparison.

The search_n_algorithm searches for the sub-sequence composed of \f2count\fP occurrences of \f2value\fP within a sequence \f2[first, last)\fP, and returns \f2first\fP if this sub-sequence is found. If it does not find the sub-sequence, search_n_returns \f2last\fP. The first version of search_n uses the equality (\f2==\fP) operator as a default, and the second version allows you to specify a binary predicate to perform the comparison.



.SH  COMPLEXITY


search performs at most \f2(last1 - first1)*(last2-first2) \fPapplications of the corresponding predicate.

search_n performs at most\f2 (last - first)* count\fP applications of the corresponding predicate.



.SH  EXAMPLE



.RE
.RS 0
//
.br
// search.cpp
.br
//
.RE
.RS 1
#include <algorithm>
.br
#include <list>
.br
#include <iostream>
.RE
.RS 0
using namespace std;
.br

.br
int main()
.RE
.RS 1
{
.RE
.RS 3
// Initialize a list sequence and 
.br
// sub-sequence with characters
.RE
.RS 2
char seq[40] = "Here's a string with a substring in it";
.br
char subseq[10] = "substring";
.br
list<char> sequence(seq, seq+39);
.br
list<char> subseqnc(subseq, subseq+9);
.RE
.RS 0

.RE
.RS 3
//Print out the original sequence
.RE
.RS 2
cout << endl << "The sub-sequence, " << subseq 
.RE
.RS 8
<< ", was found at the ";
.RE
.RS 2
cout << endl << "location identified by a '*'" 
.RE
.RS 8
<< endl << "     ";
.RE
.RS 0

.RE
.RS 3
// Create an iterator to identify the location of 
.br
// sub-sequence within sequence
.RE
.RS 2
list<char>::iterator place;
.RE
.RS 0

.RE
.RS 3
//Do search
.RE
.RS 2
place = search(sequence.begin(), sequence.end(),
.RE
.RS 17
subseqnc.begin(), subseqnc.end());
.RE
.RS 0

.RE
.RS 3
//Identify result by marking first character with a '*'
.br
*place = '*';
.RE
.RS 0

.RE
.RS 3
//Output sequence to display result
.RE
.RS 2
for(list<char>::iterator i = sequence.begin(); 
.RE
.RS 10
i != sequence.end(); i++)
.RE
.RS 4
cout << *i;
.RE
.RS 2
cout << endl;
.RE
.RS 0

.RE
.RS 2
return 0;
.RE
.RS 1
}

.br
.RE
.RS 0
Program Output



.RE
.RS 0

.br
The sub-sequence, substring, was found at the
.br
location identified by a '*'
.RE
.RS 4
Here's a string with a *substring in it



.SH  WARNINGS


If your compiler does not support default template parameters, then you always need to supply the \f2Allocator\fP template argument. For instance, you need to write:

\f2list<char, allocator<char> >\fP

instead of:

\f2list<char>\fP

If your compiler does not support namespaces, then you do not need the using declaration for \f2std\fP.

<ENDNOTES>
</ENDNOTES>