A natural and useful extension of the API is a way to limit the number of search results. FilteredView then can stop checking more candidates, which avoids excessive CPU (and to some extend, memory) usage when many contacts match a filter.
One corner case is when one of the matched contacts falls out of the result list (removed, updated): then the number of results is reduced and more candidates must be checked to reach the desired number again.
Implemented, pending review and further testing:
A 'limit' search term with a number as parameter (formatted as string)
can be added to a 'phone' or 'any-contains' search term to truncate the
search results after a certain number of contacts. Example:
Search([['any-contains', 'Joe'], ['limit', '10']])
=> return the first 10 Joes.
As with any other search, the resulting view will be updated if
contact data changes.
The limit must not be changed in a RefineSearch(). A 'limit' term may
(but doesn't have to) be given. If it is given, its value must match
the value set when creating the search. This limitation simplifies the
implementation and its testing. The limitation could be removed if
there is sufficient demand.