<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
<title>Proposal for new string algorithms in C++0x</title>
<meta name="author" content="Pavol Droba &lt;droba&#64;topmail.sk&gt;" />
<meta name="date" content="2005-08-26" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005-06-06 15:09:07 +0200 (Mon, 06 Jun 2005) $
:Version: $Revision: 3442 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
*/

/* "! important" is used here to override other ``margin-top`` and
   ``margin-bottom`` styles that are later in the stylesheet or 
   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
.first {
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

img.borderless {
  border: 0 }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid thin gray }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid thin black }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="proposal-for-new-string-algorithms-in-c-0x">
<h1 class="title">Proposal for new string algorithms in C++0x</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Pavol Droba &lt;<a class="reference" href="mailto:droba&#64;topmail.sk">droba&#64;topmail.sk</a>&gt;</td></tr>
<tr class="field"><th class="docinfo-name">Co-Author:</th><td class="field-body">Thorsten Ottosen &lt;<a class="reference" href="mailto:nesotto&#64;cs.aau.dk">nesotto&#64;cs.aau.dk</a>&gt;</td>
</tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">N1872=05-0132</td>
</tr>
<tr><th class="docinfo-name">Date:</th>
<td>2005-08-26</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><a name="table-of-contents">Table of Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#abstract" id="id26" name="id26">1&nbsp;&nbsp;&nbsp;Abstract</a></li>
<li><a class="reference" href="#motivation" id="id27" name="id27">2&nbsp;&nbsp;&nbsp;Motivation</a><ul class="auto-toc">
<li><a class="reference" href="#existing-practice" id="id28" name="id28">2.1&nbsp;&nbsp;&nbsp;Existing practice</a></li>
</ul>
</li>
<li><a class="reference" href="#impact-on-the-standard" id="id29" name="id29">3&nbsp;&nbsp;&nbsp;Impact on the standard</a><ul class="auto-toc">
<li><a class="reference" href="#design-issues" id="id30" name="id30">3.1&nbsp;&nbsp;&nbsp;Design issues</a><ul class="auto-toc">
<li><a class="reference" href="#string-representation" id="id31" name="id31">3.1.1&nbsp;&nbsp;&nbsp;String representation</a></li>
<li><a class="reference" href="#differences-from-the-boost-string-algorithms-library" id="id32" name="id32">3.1.2&nbsp;&nbsp;&nbsp;Differences from the Boost String Algorithms Library</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#algorithms" id="id33" name="id33">4&nbsp;&nbsp;&nbsp;Algorithms</a><ul class="auto-toc">
<li><a class="reference" href="#case-conversion" id="id34" name="id34">4.1&nbsp;&nbsp;&nbsp;Case Conversion</a><ul class="auto-toc">
<li><a class="reference" href="#to-lower" id="id35" name="id35">4.1.1&nbsp;&nbsp;&nbsp;to_lower</a></li>
<li><a class="reference" href="#to-upper" id="id36" name="id36">4.1.2&nbsp;&nbsp;&nbsp;to_upper</a></li>
</ul>
</li>
<li><a class="reference" href="#predicates" id="id37" name="id37">4.2&nbsp;&nbsp;&nbsp;Predicates</a><ul class="auto-toc">
<li><a class="reference" href="#starts-with" id="id38" name="id38">4.2.1&nbsp;&nbsp;&nbsp;starts_with</a></li>
<li><a class="reference" href="#ends-with" id="id39" name="id39">4.2.2&nbsp;&nbsp;&nbsp;ends_with</a></li>
<li><a class="reference" href="#contains" id="id40" name="id40">4.2.3&nbsp;&nbsp;&nbsp;contains</a></li>
<li><a class="reference" href="#equals" id="id41" name="id41">4.2.4&nbsp;&nbsp;&nbsp;equals</a></li>
<li><a class="reference" href="#lexicographical-compare" id="id42" name="id42">4.2.5&nbsp;&nbsp;&nbsp;lexicographical_compare</a></li>
<li><a class="reference" href="#all-3" id="id43" name="id43">4.2.6&nbsp;&nbsp;&nbsp;all </a></li>
<li><a class="reference" href="#none-3" id="id44" name="id44">4.2.7&nbsp;&nbsp;&nbsp;none </a></li>
</ul>
</li>
<li><a class="reference" href="#trimming" id="id45" name="id45">4.3&nbsp;&nbsp;&nbsp;Trimming</a><ul class="auto-toc">
<li><a class="reference" href="#trim-left-5" id="id46" name="id46">4.3.1&nbsp;&nbsp;&nbsp;trim_left </a></li>
<li><a class="reference" href="#trim-right-5" id="id47" name="id47">4.3.2&nbsp;&nbsp;&nbsp;trim_right </a></li>
<li><a class="reference" href="#trim" id="id48" name="id48">4.3.3&nbsp;&nbsp;&nbsp;trim</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#id22" id="id49" name="id49">5&nbsp;&nbsp;&nbsp;Predicates</a><ul class="auto-toc">
<li><a class="reference" href="#classification-predicates" id="id50" name="id50">5.1&nbsp;&nbsp;&nbsp;Classification predicates</a><ul class="auto-toc">
<li><a class="reference" href="#predicate-facade" id="id51" name="id51">5.1.1&nbsp;&nbsp;&nbsp;Predicate facade</a></li>
<li><a class="reference" href="#is-classified" id="id52" name="id52">5.1.2&nbsp;&nbsp;&nbsp;is_classified</a></li>
<li><a class="reference" href="#is-any-of" id="id53" name="id53">5.1.3&nbsp;&nbsp;&nbsp;is_any_of</a></li>
<li><a class="reference" href="#is-from-range" id="id54" name="id54">5.1.4&nbsp;&nbsp;&nbsp;is_from_range</a></li>
</ul>
</li>
<li><a class="reference" href="#combinators" id="id55" name="id55">5.2&nbsp;&nbsp;&nbsp;Combinators</a><ul class="auto-toc">
<li><a class="reference" href="#and" id="id56" name="id56">5.2.1&nbsp;&nbsp;&nbsp;and</a></li>
<li><a class="reference" href="#or" id="id57" name="id57">5.2.2&nbsp;&nbsp;&nbsp;or</a></li>
<li><a class="reference" href="#not" id="id58" name="id58">5.2.3&nbsp;&nbsp;&nbsp;not</a></li>
</ul>
</li>
<li><a class="reference" href="#comparison-predicates" id="id59" name="id59">5.3&nbsp;&nbsp;&nbsp;Comparison predicates</a><ul class="auto-toc">
<li><a class="reference" href="#is-equal" id="id60" name="id60">5.3.1&nbsp;&nbsp;&nbsp;is_equal</a></li>
<li><a class="reference" href="#is-iequal" id="id61" name="id61">5.3.2&nbsp;&nbsp;&nbsp;is_iequal</a></li>
<li><a class="reference" href="#is-less" id="id62" name="id62">5.3.3&nbsp;&nbsp;&nbsp;is_less</a></li>
<li><a class="reference" href="#is-iless" id="id63" name="id63">5.3.4&nbsp;&nbsp;&nbsp;is_iless</a></li>
<li><a class="reference" href="#is-not-greater" id="id64" name="id64">5.3.5&nbsp;&nbsp;&nbsp;is_not_greater</a></li>
<li><a class="reference" href="#is-not-igreater" id="id65" name="id65">5.3.6&nbsp;&nbsp;&nbsp;is_not_igreater</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#literal-helpers" id="id66" name="id66">6&nbsp;&nbsp;&nbsp;Literal helpers</a><ul class="auto-toc">
<li><a class="reference" href="#as-literal" id="id67" name="id67">6.1&nbsp;&nbsp;&nbsp;as_literal</a></li>
<li><a class="reference" href="#as-array" id="id68" name="id68">6.2&nbsp;&nbsp;&nbsp;as_array</a></li>
</ul>
</li>
<li><a class="reference" href="#discussion-and-open-issues" id="id69" name="id69">7&nbsp;&nbsp;&nbsp;Discussion and open issues</a><ul class="auto-toc">
<li><a class="reference" href="#string-affinity" id="id70" name="id70">7.1&nbsp;&nbsp;&nbsp;String affinity</a></li>
<li><a class="reference" href="#placement" id="id71" name="id71">7.2&nbsp;&nbsp;&nbsp;Placement</a></li>
<li><a class="reference" href="#range-library-and-char-literals-handling" id="id72" name="id72">7.3&nbsp;&nbsp;&nbsp;Range Library and char literals handling</a><ul class="auto-toc">
<li><a class="reference" href="#explicit-solution" id="id73" name="id73">7.3.1&nbsp;&nbsp;&nbsp;Explicit solution</a></li>
<li><a class="reference" href="#implicit-solution" id="id74" name="id74">7.3.2&nbsp;&nbsp;&nbsp;Implicit solution</a></li>
</ul>
</li>
<li><a class="reference" href="#selection-of-algorithms" id="id75" name="id75">7.4&nbsp;&nbsp;&nbsp;Selection of algorithms</a></li>
</ul>
</li>
<li><a class="reference" href="#id25" id="id76" name="id76">8&nbsp;&nbsp;&nbsp;References</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id26" name="abstract">1&nbsp;&nbsp;&nbsp;Abstract</a></h1>
<p>This proposal introduces several string manipulating algorithms for addition into the C++ standard 
library. Additionaly the paper also proposes a set of predicate classes that might be used together
with the algorithms mentioned here.</p>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id27" name="motivation">2&nbsp;&nbsp;&nbsp;Motivation</a></h1>
<p>String processing is a part of almost every non-trivial program. There is always a need to process
some input, extract some information from a text or format a textual output.
Although the range of operations that need to be performed with strings is almost unlimited, 
some of them are very common. Many of these tend to be reinvented continuously by C++ programmers.</p>
<p>The C++ standard library supports string processing mainly by the <tt class="docutils literal"><span class="pre">basic_string</span></tt> class. In addition
the <tt class="docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt> header contains several algorithms that might by be applied in the string processing
tasks, i.e. <tt class="docutils literal"><span class="pre">search</span></tt>, <tt class="docutils literal"><span class="pre">replace</span></tt>, etc. Compared to other programming languages like perl, 
the options are very limited.</p>
<p>This paper tries to fill this deficiency by introducing some of the often used algorithms into the 
standard library.</p>
<div class="section" id="existing-practice">
<h2><a class="toc-backref" href="#id28" name="existing-practice">2.1&nbsp;&nbsp;&nbsp;Existing practice</a></h2>
<p>The proposal is based on the <a class="reference" href="http://www.boost.org/doc/html/string_algo.html">Boost String Algorithms Library</a>. The library is in Boost since the version 1.32 and
it is well accepted (See <a class="reference" href="http://www.boost.org/doc/html/who_s_using_boost_.html">references</a>).</p>
<p>Algorithms mentioned here are also present in some form in many general-purpose C++ libraries. Among others
<tt class="docutils literal"><span class="pre">CString</span></tt> from MFC or <tt class="docutils literal"><span class="pre">QString</span></tt> from Qt. They are also standard operations in scripting languages like
Perl, Python or Ruby.</p>
</div>
</div>
<div class="section" id="impact-on-the-standard">
<h1><a class="toc-backref" href="#id29" name="impact-on-the-standard">3&nbsp;&nbsp;&nbsp;Impact on the standard</a></h1>
<p>The proposal is directly dependant on other two proposed extensions. Range Library (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>) and rvalue reference
proposal (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1770.html">N1770</a>). No other changes in the core language or in the existing parts of the standard 
library are required.</p>
<div class="section" id="design-issues">
<h2><a class="toc-backref" href="#id30" name="design-issues">3.1&nbsp;&nbsp;&nbsp;Design issues</a></h2>
<div class="section" id="string-representation">
<h3><a class="toc-backref" href="#id31" name="string-representation">3.1.1&nbsp;&nbsp;&nbsp;String representation</a></h3>
<p>While a 'string' if often represented by <tt class="docutils literal"><span class="pre">basic_string</span></tt> class, this is not the only representation.
There are several alternatives that are widely used. Examples are FlexiString from the Loki library or 
<tt class="docutils literal"><span class="pre">rope</span></tt> from the STLPort implementation of the C++ standard library. Algorithms presented here are therefore
designed to work with generic structures that satisfy algorithm requirements, rather than with a 
concrete string class.</p>
<p>To accommodate this design, the Range Library (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>) is used as an interface for accessing the input
strings. The Range Library provides a uniform access to a container structures. This allows virtually
any container to be used with the algorithms presented here. Yet the algorithms are designed to work
efficiently with string-like structures. An implication is that the elements of a string (a.k.a characters) are
values that can be copied and moved around without additional overhead.</p>
</div>
<div class="section" id="differences-from-the-boost-string-algorithms-library">
<h3><a class="toc-backref" href="#id32" name="differences-from-the-boost-string-algorithms-library">3.1.2&nbsp;&nbsp;&nbsp;Differences from the Boost String Algorithms Library</a></h3>
<p>As mentioned earlier, this proposal is based on <a class="reference" href="http://www.boost.org/doc/html/string_algo.html">Boost String Algorithms Library</a>. However it includes only 
a subset of the algorithms contained in the Boost library. Part of the library that deals with find and replace
functionality is intentionally omitted due to several reasons:</p>
<ul class="simple">
<li>This functionality is quite complex and requires several facilities that should be considered separately.</li>
<li>There are several volatile topics that have not been satisfactory solved, therefore they are not
ready for standardization.</li>
<li>There is a possible overlap with <a class="reference" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm">Regex</a> proposal that is part of TR1.</li>
</ul>
<p>Therefore we have decided to exclude these algorithms from this proposal. Yet it is possible that they
might be a part of another proposal in the future.</p>
<p>There are few design differences between the proposal and the Boost library as well.</p>
<ul class="simple">
<li>Mutable variants of algorithms were removed in favor of move semantics (using constructs form the proposal <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1770.html">N1770</a>). 
Now the algorithms usually come in two flavors, a copy (using const &amp;) and a move (using &amp;&amp;) variant. 
We consider this to be another evolutionary step toward functional-oriented programming in C++.
During the review of <a class="reference" href="http://www.boost.org/doc/html/string_algo.html">Boost String Algorithms Library</a> this topic was intensively debated. A strong
opinion was expressed in favor of functional approach, however without the move semantics support, 
it is not possible to implement some of the algorithms in an efficient manner. Therefore mutable version were
retained as a primary interface, accompanied by copy variants.</li>
<li>The definitions are tied to the Range Library proposal (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>) rather than to the <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost Range Library</a>.</li>
</ul>
</div>
</div>
</div>
<div class="section" id="algorithms">
<h1><a class="toc-backref" href="#id33" name="algorithms">4&nbsp;&nbsp;&nbsp;Algorithms</a></h1>
<p>In the following <tt class="docutils literal"><span class="pre">n</span></tt> is an unsigned integer, <tt class="docutils literal"><span class="pre">s[n]</span></tt> denotes n-th element of the sequence <tt class="docutils literal"><span class="pre">s</span></tt>,
<tt class="docutils literal"><span class="pre">v1</span></tt> and <tt class="docutils literal"><span class="pre">v2</span></tt> are variables of type <tt class="docutils literal"><span class="pre">range_value&lt;Range&gt;::type</span></tt> or elements of range <tt class="docutils literal"><span class="pre">r1</span></tt> or <tt class="docutils literal"><span class="pre">r2</span></tt> respectively.
<tt class="docutils literal"><span class="pre">size(s)</span></tt> evaluates to the number of elements in <tt class="docutils literal"><span class="pre">s</span></tt> and finally <tt class="docutils literal"><span class="pre">result</span></tt> denotes the value returned by
the algorithm.</p>
<div class="section" id="case-conversion">
<h2><a class="toc-backref" href="#id34" name="case-conversion">4.1&nbsp;&nbsp;&nbsp;Case Conversion</a></h2>
<p>These algorithms perform case-conversion on all characters in the string.</p>
<div class="section" id="to-lower">
<h3><a class="toc-backref" href="#id35" name="to-lower">4.1.1&nbsp;&nbsp;&nbsp;to_lower</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange to_lower(const CopyableRange&amp; s, const locale&amp; loc=locale());

template&lt;typename CopyableRange&gt;
CopyableRange&amp;&amp; to_lower(CopyableRange&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<p><strong>Requires:</strong> CopyableRange satisfies the requirements of the copyable range (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>) <a class="footnote-reference" href="#id3" id="id1" name="id1">[1]</a>.</p>
<p><strong>Effects:</strong> Converts elements in the input sequence to lower-case using the specified locales.</p>
<p><strong>Returns:</strong> Modified copy of the input</p>
<p><strong>Postcondition:</strong> for each <tt class="docutils literal"><span class="pre">n</span></tt> in <tt class="docutils literal"><span class="pre">[0,</span> <span class="pre">size(s))</span></tt> <tt class="docutils literal"><span class="pre">result[n]</span> <span class="pre">==</span> <span class="pre">tolower(s[n],</span> <span class="pre">loc)</span></tt></p>
</div>
<div class="section" id="to-upper">
<h3><a class="toc-backref" href="#id36" name="to-upper">4.1.2&nbsp;&nbsp;&nbsp;to_upper</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange to_upper(const CopyableRange&amp; s, const locale&amp; loc=locale());

template&lt;typename Sequence&gt;
CopyableRange&amp;&amp; to_upper(CopyableRange&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<p><strong>Requires:</strong> CopyableRange satisfies the requirements of the copyable range (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>) <a class="footnote-reference" href="#id3" id="id2" name="id2">[1]</a>.</p>
<p><strong>Effects:</strong> Converts elements in the input sequence to upper-case.</p>
<p><strong>Returns:</strong> Modified copy of the input.</p>
<p><strong>Postcondition:</strong> for each <tt class="docutils literal"><span class="pre">n</span></tt> in CopyableRange <tt class="docutils literal"><span class="pre">[0,</span> <span class="pre">size(s))</span></tt> <tt class="docutils literal"><span class="pre">result[n]</span> <span class="pre">==</span> <span class="pre">toupper(s[n],</span> <span class="pre">loc)</span></tt></p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id3">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>)</em> An implicit requirement is implied from using <tt class="docutils literal"><span class="pre">tolower</span></tt>. <tt class="docutils literal"><span class="pre">ctype</span></tt> must be specialized
for <tt class="docutils literal"><span class="pre">range_value&lt;CopyableRange&gt;::type</span></tt> and it must be imbued in the specified locales.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="predicates">
<h2><a class="toc-backref" href="#id37" name="predicates">4.2&nbsp;&nbsp;&nbsp;Predicates</a></h2>
<p>These algorithms perform containment checks of various types and string comparison.</p>
<div class="section" id="starts-with">
<h3><a class="toc-backref" href="#id38" name="starts-with">4.2.1&nbsp;&nbsp;&nbsp;starts_with</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range1, typename Range2, typename Pred&gt;
bool starts_with(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool starts_with(const Range1&amp; r1, const Range2&amp; r2);

template&lt;typename Range1, typename Range2, typename Pred&gt;
bool istarts_with(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Range1, Range2 satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li>(Form 1) the expression <tt class="docutils literal"><span class="pre">pred(v1,</span> <span class="pre">v2)</span></tt> is valid.</li>
<li>(Form 2,3) the expression <tt class="docutils literal"><span class="pre">v1==v2</span></tt> is valid <a class="footnote-reference" href="#id12" id="id4" name="id4">[2]</a>.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Checks whether <tt class="docutils literal"><span class="pre">r2</span></tt> is a prefix of <tt class="docutils literal"><span class="pre">r1</span></tt> (Form 3 ignoring the case)</p>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ul class="first last simple">
<li>true if <tt class="docutils literal"><span class="pre">size(r1)&gt;=size(r2)</span></tt> &amp;&amp; for each <tt class="docutils literal"><span class="pre">n&lt;size(r2)</span></tt><ul>
<li>(Form 1) <tt class="docutils literal"><span class="pre">pred(r1[n],r2[n])</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">r1[n]==r2[n]</span></tt></li>
<li>(Form 3) <tt class="docutils literal"><span class="pre">tolower(r1[n],</span> <span class="pre">loc)==tolower(r2[n],</span> <span class="pre">loc)</span></tt></li>
</ul>
</li>
<li>false otherwise</li>
</ul>
</dd>
</dl>
<p><strong>Example:</strong> Function <tt class="docutils literal"><span class="pre">IsURL()</span></tt> checks if the path denotes an url.</p>
<pre class="literal-block">
bool IsURL(const string&amp; strPath)
{
      return 
              istarts_with(strPath, &quot;http://&quot;) ||
              istarts_with(strPath, &quot;https://&quot;) ||
              istarts_with(strPath, &quot;ftp://&quot;);
}
</pre>
</div>
<div class="section" id="ends-with">
<h3><a class="toc-backref" href="#id39" name="ends-with">4.2.2&nbsp;&nbsp;&nbsp;ends_with</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range1, typename Range2, typename Pred&gt;
bool ends_with(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool ends_with(const Range1&amp; r1, const Range2&amp; r2);

template&lt;typename Range1, typename Range2, typename Pred&gt;
bool iends_with(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Range1, Range2 satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li>(Form 1) the expression <tt class="docutils literal"><span class="pre">pred(v1,</span> <span class="pre">v2)</span></tt> is valid</li>
<li>(Form 2,3) the expression <tt class="docutils literal"><span class="pre">v1==v2</span></tt> is valid <a class="footnote-reference" href="#id12" id="id5" name="id5">[2]</a>.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Checks whether <tt class="docutils literal"><span class="pre">r2</span></tt> is a suffix of <tt class="docutils literal"><span class="pre">r1</span></tt> (Form 3 ignoring the case)</p>
<dl class="docutils">
<dt><strong>Returns:</strong> </dt>
<dd><ul class="first last simple">
<li>true if <tt class="docutils literal"><span class="pre">size(r1)&gt;=size(r2)</span></tt> &amp;&amp; for each <tt class="docutils literal"><span class="pre">0&lt;n&lt;=size(r2)</span></tt><ul>
<li>(Form 1) <tt class="docutils literal"><span class="pre">pred(r1[size(r1)-n],r2[size(r2)-n])</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">r1[size(r1)-n]==r2[size(r2)-n]</span></tt></li>
<li>(Form 3) <tt class="docutils literal"><span class="pre">tolower(r1[size(r1)-n],</span> <span class="pre">loc)==tolower(r2[size(r2)-n],</span> <span class="pre">loc)</span></tt></li>
</ul>
</li>
<li>false otherwise</li>
</ul>
</dd>
</dl>
<p><strong>Example:</strong> Function <tt class="docutils literal"><span class="pre">IsExecutable()</span></tt> checks if the extension of the file name denotes an executable.</p>
<pre class="literal-block">
bool IsExecutable(const string&amp; strPath)
{
  return
    iends_with(strPath, &quot;.com&quot;) ||
    iends_with(strPath, &quot;.exe&quot;) ||
    iends_with(strPath, &quot;.bat&quot;);
}
</pre>
</div>
<div class="section" id="contains">
<h3><a class="toc-backref" href="#id40" name="contains">4.2.3&nbsp;&nbsp;&nbsp;contains</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range1, typename Range2, typename Pred&gt;
bool contains(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool contains(const Range1&amp; r1, const Range2&amp; r2);

template&lt;typename Range1, typename Range2, typename Pred&gt;
bool icontains(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Range1, Range2 satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li>(Form 1) the expression <tt class="docutils literal"><span class="pre">pred(v1,</span> <span class="pre">v2)</span></tt> is valid.</li>
<li>(Form 2,3) the expression <tt class="docutils literal"><span class="pre">v1==v2</span></tt> is valid <a class="footnote-reference" href="#id12" id="id6" name="id6">[2]</a>.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Checks whether <tt class="docutils literal"><span class="pre">r2</span></tt> is a substring of <tt class="docutils literal"><span class="pre">r1</span></tt> (Form 3 ignoring the case)</p>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ul class="first last simple">
<li>true if <tt class="docutils literal"><span class="pre">size(r1)&gt;=size(r2)</span></tt> &amp;&amp; there exists <tt class="docutils literal"><span class="pre">i</span></tt> such that for each <tt class="docutils literal"><span class="pre">n&lt;size(r2)</span></tt><ul>
<li>(Form 1) <tt class="docutils literal"><span class="pre">pred(r1[i+n],r2[i+n])</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">r1[i+n]==r2[i+n]</span></tt></li>
<li>(Form 3) <tt class="docutils literal"><span class="pre">tolower(r1[i+n],</span> <span class="pre">loc)==tolower(r2[i+n],</span> <span class="pre">loc)</span></tt></li>
</ul>
</li>
<li>false otherwise</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="equals">
<h3><a class="toc-backref" href="#id41" name="equals">4.2.4&nbsp;&nbsp;&nbsp;equals</a></h3>
<p>Equals algorithm is actually a two-way version of <tt class="docutils literal"><span class="pre">equal</span></tt> available in <tt class="docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt> header.
<tt class="docutils literal"><span class="pre">equal</span></tt> does not check if both operands have the same length. Moreover, it requires that the second
argument is at least as long as the first one. Algorithm presented here fills this gap. In addition,
case-insensitive comparison is provided.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range1, typename Range2, typename Pred&gt;
bool equals(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool equals(const Range1&amp; r1, const Range2&amp; r2);

template&lt;typename Range1, typename Range2, typename Pred&gt;
bool iequals(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale);
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Range1, Range2 satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li>(Form 1) the expression <tt class="docutils literal"><span class="pre">pred(v1,</span> <span class="pre">v2)</span></tt> is valid.</li>
<li>(Form 2,3) the expression <tt class="docutils literal"><span class="pre">v1==v2</span></tt> is valid <a class="footnote-reference" href="#id12" id="id7" name="id7">[2]</a>.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Checks whether <tt class="docutils literal"><span class="pre">r1</span></tt> and <tt class="docutils literal"><span class="pre">r2</span></tt> are element-wise equal (Form 3 ignoring the case)</p>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><ul class="first last simple">
<li>true if <tt class="docutils literal"><span class="pre">size(r1)==size(r2)</span></tt> &amp;&amp; for each <tt class="docutils literal"><span class="pre">n&lt;size(r2)</span></tt><ul>
<li>(Form 1) <tt class="docutils literal"><span class="pre">pred(n],r2[n])</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">r1[n]==r2[n]</span></tt></li>
<li>(Form 3) <tt class="docutils literal"><span class="pre">tolower(r1[n],</span> <span class="pre">loc)==tolower(r2[n],</span> <span class="pre">loc)</span></tt></li>
</ul>
</li>
<li>false otherwise</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="lexicographical-compare">
<h3><a class="toc-backref" href="#id42" name="lexicographical-compare">4.2.5&nbsp;&nbsp;&nbsp;lexicographical_compare</a></h3>
<p>This algorithm has functionality equivalent to lexicographical_compare algorithm already present
in the standard library. It provides simpler, range-oriented interface and case-insensitive
version.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range1, typename Range2, typename Pred&gt;
bool lexicographical_compare(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool lexicographical_compare(const Range1&amp; r1, const Range2&amp; r2);

template&lt;typename Range1, typename Range2, typename Pred&gt;
bool ilexicographical_compare(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Range1, Range2 satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li>(Form 1) the expression <tt class="docutils literal"><span class="pre">pred(v1,</span> <span class="pre">v2)</span></tt> is valid.</li>
<li>(Form 2,3) expression <tt class="docutils literal"><span class="pre">v1&lt;v2</span></tt> is valid <a class="footnote-reference" href="#id12" id="id8" name="id8">[2]</a>.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Performs the lexicographical comparison.</p>
<p><strong>Returns:</strong> true if <tt class="docutils literal"><span class="pre">r1</span></tt> is lexicographically less then <tt class="docutils literal"><span class="pre">r2</span></tt>, false otherwise.</p>
<dl class="docutils">
<dt><strong>Notes:</strong></dt>
<dd>If the two sequences have the same number of elements and their corresponding elements are equivalent,
then neither sequence is lexicographically less than the other. If one sequence is a prefix of the
other, then the shorter sequence is lexicographically less than the longer sequence. Otherwise, the 
lexicographical comparison of the sequences yields the same result as the comparison of the first 
corresponding pair of elements that are not equivalent.</dd>
</dl>
</div>
<div class="section" id="all-3">
<h3><a class="toc-backref" href="#id43" name="all-3">4.2.6&nbsp;&nbsp;&nbsp;all <a class="footnote-reference" href="#id13" id="id9" name="id9">[3]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range, typename Pred&gt;
bool all(const Range&amp; r1, Pred pred);
</pre>
<p><strong>Requires:</strong>  Range satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</p>
<p><strong>Effects:</strong> Check if all the elements of the range satisfy the condition of the predicate <tt class="docutils literal"><span class="pre">pred</span></tt>.</p>
<p><strong>Returns:</strong> true if for each <tt class="docutils literal"><span class="pre">n&lt;size(r1)</span></tt> <tt class="docutils literal"><span class="pre">pred(r1[n])</span></tt>, false otherwise</p>
<p><strong>Example:</strong> Check if all characters in the string are lower case. <a class="footnote-reference" href="#id14" id="id10" name="id10">[4]</a></p>
<pre class="literal-block">
if(all(str, is_lower()))
{ 
  // All characters are lower case
}
</pre>
</div>
<div class="section" id="none-3">
<h3><a class="toc-backref" href="#id44" name="none-3">4.2.7&nbsp;&nbsp;&nbsp;none <a class="footnote-reference" href="#id13" id="id11" name="id11">[3]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range, typename Pred&gt;
bool none(const Range&amp; r1, Pred pred);
</pre>
<p><strong>Requires:</strong>  Range satisfies the requirements of the range concept (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</p>
<p><strong>Effects:</strong> Check if none of the elements in the range satisfy the condition of the predicate <tt class="docutils literal"><span class="pre">pred</span></tt>.</p>
<p><strong>Returns:</strong> true if for each <tt class="docutils literal"><span class="pre">n&lt;size(r1)</span></tt> <tt class="docutils literal"><span class="pre">!pred(r1[n])</span></tt>, false otherwise</p>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id12">[2]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id5">2</a>, <a class="fn-backref" href="#id6">3</a>, <a class="fn-backref" href="#id7">4</a>, <a class="fn-backref" href="#id8">5</a>)</em> An implicit requirement is implied from using <tt class="docutils literal"><span class="pre">tolower</span></tt>. <tt class="docutils literal"><span class="pre">ctype</span></tt> must be specialized
for <tt class="docutils literal"><span class="pre">range_value&lt;Range&gt;::type</span></tt> and it must be imbued in the specified locales.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id13">[3]</a></td><td><em>(<a class="fn-backref" href="#id9">1</a>, <a class="fn-backref" href="#id11">2</a>)</em> The names <tt class="docutils literal"><span class="pre">all</span></tt> and <tt class="docutils literal"><span class="pre">none</span></tt> might be considered too general. Yet they describe the algorithms
very well and we haven't found a better variant so far. If this will be considered a
problem, alternative names might be used.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id10" name="id14">[4]</a></td><td><tt class="docutils literal"><span class="pre">is_lower</span></tt> predicate is presented later in this proposal.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="trimming">
<h2><a class="toc-backref" href="#id45" name="trimming">4.3&nbsp;&nbsp;&nbsp;Trimming</a></h2>
<p>Trimming algorithms remove unnecessary spaces from the beginning and the end of a string.</p>
<div class="section" id="trim-left-5">
<h3><a class="toc-backref" href="#id46" name="trim-left-5">4.3.1&nbsp;&nbsp;&nbsp;trim_left <a class="footnote-reference" href="#id20" id="id15" name="id15">[5]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence trim_left(const Sequence&amp; s, const locale&amp; loc=locale());

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_left(Sequence&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<pre class="literal-block">
template&lt;typename Sequence, typename Pred&gt;
Sequence trim_left_if(const Sequence&amp; s, Pred pred);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_left_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Sequence satisfies the requirement of sequence (par. 23.1.1) <a class="footnote-reference" href="#id21" id="id16" name="id16">[6]</a>.</li>
<li>The expression <tt class="docutils literal"><span class="pre">pred(v1)</span></tt> is valid.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Removes all leading spaces (or characters satisfying pred) from the beginning of the sequence</p>
<p><strong>Returns:</strong> Modified copy of the input</p>
<dl class="docutils">
<dt><strong>Postcondition:</strong></dt>
<dd><ul class="first last simple">
<li>(Form 1) <tt class="docutils literal"><span class="pre">!isspace(result[0],</span> <span class="pre">loc)</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">!pred(result[0])</span></tt></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="trim-right-5">
<h3><a class="toc-backref" href="#id47" name="trim-right-5">4.3.2&nbsp;&nbsp;&nbsp;trim_right <a class="footnote-reference" href="#id20" id="id17" name="id17">[5]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence trim_right(const Sequence&amp; s, const locale&amp; loc=locale);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_right(Sequence&amp;&amp; s, const locale&amp; loc=locale);
</pre>
<pre class="literal-block">
template&lt;typename Sequence, typename Pred&gt;
Sequence trim_right_if(const Sequence&amp; s, Pred pred);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_right_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Sequence satisfies the requirement of sequence (par. 23.1.1) <a class="footnote-reference" href="#id21" id="id18" name="id18">[6]</a>.</li>
<li>The expression <tt class="docutils literal"><span class="pre">pred(v1)</span></tt> is valid.</li>
</ul>
</dd>
</dl>
<p><strong>Effects:</strong> Removes all trailing spaces (or characters satisfying pred) from the end of the sequence</p>
<p><strong>Returns:</strong> Modified copy of the input</p>
<dl class="docutils">
<dt><strong>Postcondition:</strong></dt>
<dd><ul class="first last simple">
<li>(Form 1) <tt class="docutils literal"><span class="pre">!isspace(result[size(result)-1],</span> <span class="pre">loc)</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">!pred(result[size(result)-1])</span></tt></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="trim">
<h3><a class="toc-backref" href="#id48" name="trim">4.3.3&nbsp;&nbsp;&nbsp;trim</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence trim(const Sequence&amp; s, const locale&amp; loc=locale());

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim(Sequence&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<pre class="literal-block">
template&lt;typename Sequence, typename Pred&gt;
Sequence trim_if(const Sequence&amp; s, Pred pred);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong></dt>
<dd><ul class="first last simple">
<li>Sequence satisfies the requirement of sequence (par. 23.1.1) <a class="footnote-reference" href="#id21" id="id19" name="id19">[6]</a>.</li>
<li>The expression <tt class="docutils literal"><span class="pre">pred(v1)</span></tt> is valid.</li>
</ul>
</dd>
<dt><strong>Effects:</strong> Equivalent functionality to</dt>
<dd><ul class="first last simple">
<li>(Form 1) <tt class="docutils literal"><span class="pre">trim_left(trim_right(s))</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">trim_left_if(trim_right_if(s,</span> <span class="pre">pred),</span> <span class="pre">pred)</span></tt></li>
</ul>
</dd>
</dl>
<p><strong>Returns:</strong> Modified copy of the input</p>
<dl class="docutils">
<dt><strong>Postcondition:</strong></dt>
<dd><ul class="first last simple">
<li>(Form 1) <tt class="docutils literal"><span class="pre">!isspace(result[0],</span> <span class="pre">loc)</span>&nbsp; <span class="pre">&amp;&amp;</span> <span class="pre">!isspace(result[size(result)-1],</span> <span class="pre">loc)</span></tt></li>
<li>(Form 2) <tt class="docutils literal"><span class="pre">!pred(result[0])</span> <span class="pre">&amp;&amp;</span> <span class="pre">!pred(result[size(result)-1])</span></tt></li>
</ul>
</dd>
</dl>
<table class="docutils footnote" frame="void" id="id20" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id20">[5]</a></td><td><em>(<a class="fn-backref" href="#id15">1</a>, <a class="fn-backref" href="#id17">2</a>)</em> Alternative names that might be considered are <tt class="docutils literal"><span class="pre">trim_start</span></tt> and <tt class="docutils literal"><span class="pre">trim_end</span></tt>. This would
be more consistent with <tt class="docutils literal"><span class="pre">starts_with</span></tt> and <tt class="docutils literal"><span class="pre">end_withs</span></tt>, however 'TrimLeft/Right' is more
often used term in currently existing libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id21" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id21">[6]</a></td><td><em>(<a class="fn-backref" href="#id16">1</a>, <a class="fn-backref" href="#id18">2</a>, <a class="fn-backref" href="#id19">3</a>)</em> An implicit requirement is implied from using <tt class="docutils literal"><span class="pre">tolower</span></tt>. <tt class="docutils literal"><span class="pre">ctype</span></tt> must be specialized
for <tt class="docutils literal"><span class="pre">range_value&lt;CopyableRange&gt;::type</span></tt> and it must be imbued in the specified locales.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="id22">
<h1><a class="toc-backref" href="#id49" name="id22">5&nbsp;&nbsp;&nbsp;Predicates</a></h1>
<p>Two categories of predicates are given.</p>
<ul class="simple">
<li>Classification predicates are used to recognize if a character belongs to a particular character class. 
These predicated can be used in algorithms like <tt class="docutils literal"><span class="pre">all</span></tt> or <tt class="docutils literal"><span class="pre">trim_if</span></tt>.</li>
<li>Comparison predicates perform comparison of two characters. They are targeted to be used with 
algorithm that require character-level comparison like <tt class="docutils literal"><span class="pre">starts_with</span></tt>, <tt class="docutils literal"><span class="pre">equals</span></tt> and etc.</li>
</ul>
<p>It is noteworthy that the predicates are not staticaly bound to a character type that is to be processed,
rather the operation it templated. This approach simplifies the usage of predicates, since the
types are automaticaly infered from the input without the need to be explicitly specified by
a user.</p>
<div class="section" id="classification-predicates">
<h2><a class="toc-backref" href="#id50" name="classification-predicates">5.1&nbsp;&nbsp;&nbsp;Classification predicates</a></h2>
<div class="section" id="predicate-facade">
<h3><a class="toc-backref" href="#id51" name="predicate-facade">5.1.1&nbsp;&nbsp;&nbsp;Predicate facade</a></h3>
<pre class="literal-block">
template&lt;typename Derived&gt;
struct predicate_facade {};
</pre>
<p>The purpose of the <tt class="docutils literal"><span class="pre">predicate_facade</span></tt> class is to tag classification predicates, so that they
can be used together with the predicate combinators. Without such a facility it would not be possible
to avoid ambiguities with other logical operators.</p>
<p>Every predicate should be therefore derived from <tt class="docutils literal"><span class="pre">predicate_facade</span></tt>.</p>
</div>
<div class="section" id="is-classified">
<h3><a class="toc-backref" href="#id52" name="is-classified">5.1.2&nbsp;&nbsp;&nbsp;is_classified</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_classified_pred : public predicate_facade&lt;is_classified_pred&gt;
{
public:
  // Constructor
  is_classified_pred(ctype_base::mask Type, locale const &amp; Loc = locale());

  // Operation
  template&lt;typename Char&gt; bool operator()(Char Ch) const;
};

is_classified_pred is_classified(ctype_base::mask Type, const locale&amp; Loc=locale());
is_classified_pred is_space(const locale&amp; Loc=locale());
is_classified_pred is_alnum(const locale&amp; Loc=locale());
is_classified_pred is_alpha(const locale&amp; Loc=locale());
is_classified_pred is_cntrl(const locale&amp; Loc=locale());
is_classified_pred is_digit(const locale&amp; Loc=locale());
is_classified_pred is_graph(const locale&amp; Loc=locale());
is_classified_pred is_lower(const locale&amp; Loc=locale());
is_classified_pred is_print(const locale&amp; Loc=locale());
is_classified_pred is_punct(const locale&amp; Loc=locale());
is_classified_pred is_upper(const locale&amp; Loc=locale())
is_classified_pred is_xdigit(const locale&amp; Loc=locale());
</pre>
<p>Class <tt class="docutils literal"><span class="pre">is_classified_pred</span></tt> is a predicate that checks whether a character belongs to 
a character class specified in constructor. Character classes are defined in the <tt class="docutils literal"><span class="pre">ctype_base</span></tt> class.
The given locales are used to perform the actual classification.</p>
<p>The functions <tt class="docutils literal"><span class="pre">is_*</span></tt> are the preferred form of construction for the <tt class="docutils literal"><span class="pre">is_classified_pred</span></tt> class.</p>
</div>
<div class="section" id="is-any-of">
<h3><a class="toc-backref" href="#id53" name="is-any-of">5.1.3&nbsp;&nbsp;&nbsp;is_any_of</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Char&gt; 
class is_any_of_pred : public predicate_facade&lt;is_any_of_pred&lt;Char&gt; &gt;
{
public:
  // Constructor
  template&lt;typename Range&gt; is_any_of_pred(const Range&amp; r);

  // Operation
  template&lt;typename Char2&gt; bool operator()(Char2 c) const;
};

template&lt;typename Range&gt;
is_any_of_pred&lt;typename range_value&lt;Range&gt;::type &gt; is_any_of(const Range&amp; r);
</pre>
<p><tt class="docutils literal"><span class="pre">is_any_of_pred</span></tt> predicate checks whether a character is member of a given set. A range specified
at the construction is used to initialize the control set.</p>
<p><tt class="docutils literal"><span class="pre">is_any_of</span></tt> constructs the <tt class="docutils literal"><span class="pre">is_from_range_pred</span></tt> predicate.</p>
</div>
<div class="section" id="is-from-range">
<h3><a class="toc-backref" href="#id54" name="is-from-range">5.1.4&nbsp;&nbsp;&nbsp;is_from_range</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Char&gt; 
class is_from_range_pred : public predicate_facade&lt;is_from_range_pred&lt;Char&gt; &gt;
{
public:
  // Constructor
  is_from_range_pred(Char from, Char to);

  // Operation
  template&lt;typename Char2&gt; bool operator()(Char2 c) const;
};

template&lt;typename Char&gt;
is_from_range_pred&lt;Char&gt; is_from_range(Char from, Char to);
</pre>
<p><tt class="docutils literal"><span class="pre">is_from_range_pred</span></tt> checks whether a character belongs to a specified range of characters.
In other words, it checks whether <tt class="docutils literal"><span class="pre">from</span> <span class="pre">&lt;=</span> <span class="pre">c</span> <span class="pre">&lt;=</span> <span class="pre">to</span></tt> holds.</p>
<p><strong>Precondition:</strong> <tt class="docutils literal"><span class="pre">from</span> <span class="pre">&lt;=</span> <span class="pre">to</span></tt></p>
</div>
</div>
<div class="section" id="combinators">
<h2><a class="toc-backref" href="#id55" name="combinators">5.2&nbsp;&nbsp;&nbsp;Combinators</a></h2>
<p>Combinators allow to create an expression consisting of several classification predicates.</p>
<p><strong>Example:</strong></p>
<pre class="literal-block">
is_space() || is_any_of(as_literal(&quot;\&quot;_&quot;));
</pre>
<p>The result of this expression is a predicate that recognizes spaces, quotes and underscores.</p>
<div class="section" id="and">
<h3><a class="toc-backref" href="#id56" name="and">5.2.1&nbsp;&nbsp;&nbsp;and</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Pred1, typename Pred2&gt;
class and_pred : public predicate_facade&lt; and_pred&lt;Pred1,Pred2&gt; &gt;
{
public:
  // Constructor
  and_pred(Pred1 p1, Pred2 p2);

  // Operation
  template&lt;typename Char&gt; bool operator()(Char c) const;
};


template&lt;typename Pred1, typename Pred2&gt;
and_pred&lt;Pred1, Pred2&gt; operator&amp;&amp;(Pred1 p1, Pred2 p2);
</pre>
<p>Constructs a predicate that is a logical <em>and</em> of predicates p1 and p2.</p>
</div>
<div class="section" id="or">
<h3><a class="toc-backref" href="#id57" name="or">5.2.2&nbsp;&nbsp;&nbsp;or</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Pred1, typename Pred2&gt;
class or_pred : public predicate_facade&lt;or_pred&lt;Pred1,Pred2&gt; &gt;
{
public:
  // Constructor
  or_pred(Pred1 p1, Pred2 p2);

  // Operation
  template&lt;typename Char&gt; bool operator()(Char c) const;
};

template&lt;typename Pred1, typename Pred2&gt;
or_pred&lt;Pred1, Pred2&gt; operator||(Pred1 p1, Pred2 p2);
</pre>
<p>Constructs a predicate that is a logical <em>or</em> of predicates p1 and p2.</p>
</div>
<div class="section" id="not">
<h3><a class="toc-backref" href="#id58" name="not">5.2.3&nbsp;&nbsp;&nbsp;not</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Pred&gt;
class not_pred : public predicate_facade&lt;not_pred&lt;Pred&gt; &gt;
{
public:
  // Constructor
  not_pred(Pred p);

  // Operation
  template&lt;typename Char&gt; bool operator()(Char c) const;
};

template&lt;typename Pred&gt;
not_pred&lt;Pred&gt; operator!(Pred p);
</pre>
<p>Constructs a predicate that is a logical negation of predicate p.</p>
</div>
</div>
<div class="section" id="comparison-predicates">
<h2><a class="toc-backref" href="#id59" name="comparison-predicates">5.3&nbsp;&nbsp;&nbsp;Comparison predicates</a></h2>
<p>The comparison predicates are primarily designed to be used by algorithms that perform
character-level comparison during their computation <a class="footnote-reference" href="#id24" id="id23" name="id23">[7]</a>.</p>
<p>Unlike the functional objects that are already present in the standard library, these
predicates have a templated function operator. Therefore they are easier to use since
it is not required to explicitly specify the argument type in the construction. Rather,
C++ type matching is used.</p>
<p>So instead of writing:</p>
<pre class="literal-block">
string s1, s2;
...
equals(s1, s2, equal_to&lt;char&gt;());
</pre>
<p>a user can write</p>
<pre class="literal-block">
equals(s1, s2, is_equal());
</pre>
<p>The difference becomes even more apparent when the input types are more complex.</p>
<p>In addition, the old function objects do not directly support comparison between different
argument types (unless they are implicitly convertible to each other).</p>
<p>The proposed predicates do not support type identification facilities provided by <tt class="docutils literal"><span class="pre">unary_function</span></tt>
and <tt class="docutils literal"><span class="pre">binary_function</span></tt>. This is primarily because it is not possible to support it with a dynamic operation
type; secondarily, these facilities (<tt class="docutils literal"><span class="pre">unary_function</span></tt>, etc.) becomes obsolete when <tt class="docutils literal"><span class="pre">auto</span></tt> and <tt class="docutils literal"><span class="pre">decltype</span></tt> 
will become a part of standard.</p>
<div class="section" id="is-equal">
<h3><a class="toc-backref" href="#id60" name="is-equal">5.3.1&nbsp;&nbsp;&nbsp;is_equal</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_equal
{
public:
  // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; arg1, const T2&amp; arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">arg1==arg2</span></tt></p>
</div>
<div class="section" id="is-iequal">
<h3><a class="toc-backref" href="#id61" name="is-iequal">5.3.2&nbsp;&nbsp;&nbsp;is_iequal</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_iequal
{
public:
  // Constructor
  is_iequal(const locale&amp; loc=locale())
  // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; Arg1, const T2&amp; Arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">tolower(arg1,loc)==tolower(arg2,loc)</span></tt></p>
</div>
<div class="section" id="is-less">
<h3><a class="toc-backref" href="#id62" name="is-less">5.3.3&nbsp;&nbsp;&nbsp;is_less</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_less
{
public:
  // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; arg1, const T2&amp; arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">arg1&lt;arg2</span></tt></p>
</div>
<div class="section" id="is-iless">
<h3><a class="toc-backref" href="#id63" name="is-iless">5.3.4&nbsp;&nbsp;&nbsp;is_iless</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_iless
{
public:
  // Constructor
  is_iless(const locale&amp; loc=locale())
   // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; Arg1, const T2&amp; Arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">tolower(arg1,loc)&lt;tolower(arg2,loc)</span></tt></p>
</div>
<div class="section" id="is-not-greater">
<h3><a class="toc-backref" href="#id64" name="is-not-greater">5.3.5&nbsp;&nbsp;&nbsp;is_not_greater</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_not_greater
{
public:
  // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; Arg1, const T2&amp; Arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">arg1&lt;=arg2</span></tt></p>
</div>
<div class="section" id="is-not-igreater">
<h3><a class="toc-backref" href="#id65" name="is-not-igreater">5.3.6&nbsp;&nbsp;&nbsp;is_not_igreater</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
class is_not_igreater
{
public:
  // Constructor
  is_not_igreater(const locale&amp; loc=locale())
  // Operator
  template&lt;typename T1, typename T2&gt;
  bool operator ()(const T1&amp; Arg1, const T2&amp; Arg2) const
};
</pre>
<p><strong>Effects:</strong> <tt class="docutils literal"><span class="pre">operator()</span></tt> returns <tt class="docutils literal"><span class="pre">tolower(arg1,loc)&lt;=tolower(arg2,loc)</span></tt></p>
<table class="docutils footnote" frame="void" id="id24" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id23" name="id24">[7]</a></td><td><p class="first">In this proposal we suggested to add only operators for =, &lt; and &lt;=. These operators should be
sufficient for the purposes they are targeted. Reverse operations can be achieved by simply revering
the arguments in the algorithm call.</p>
<p class="last">Yet it is easy to add the negation operator or simply complete the set if such a requirement arises.</p>
</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="literal-helpers">
<h1><a class="toc-backref" href="#id66" name="literal-helpers">6&nbsp;&nbsp;&nbsp;Literal helpers</a></h1>
<p>The Range library does not have support for character literals and c-style strings. Two utilities
are provided to allow these to be used with string algorithms.</p>
<p>The difference between the two utilities is in the way they handle <tt class="docutils literal"><span class="pre">Char[]</span></tt> literals. <tt class="docutils literal"><span class="pre">as_literal</span></tt>
treats it as an ordinary null-terminated string, while <tt class="docutils literal"><span class="pre">as_array</span></tt> uses the array dimensions 
to determine the length.</p>
<p>In the following example:</p>
<pre class="literal-block">
char str[]=&quot;Hello&quot;;
range&lt;char*&gt; lit=as_literal(str);
range&lt;char*&gt; arr=as_array(str);
</pre>
<p>variable <tt class="docutils literal"><span class="pre">lit</span></tt> will delimit elements <tt class="docutils literal"><span class="pre">'h','e','l','l','o'</span></tt>. <tt class="docutils literal"><span class="pre">arr</span></tt> on the other end will 
point to elements <tt class="docutils literal"><span class="pre">'h','e','l','l','o',0</span></tt> including the terminating zero.</p>
<p>To pass a literal to an algorithm, one of the adapters must be used</p>
<pre class="literal-block">
if( starts_with(str, as_literal(&quot;start&quot;) )
{
  // Do something
}
</pre>
<div class="section" id="as-literal">
<h2><a class="toc-backref" href="#id67" name="as-literal">6.1&nbsp;&nbsp;&nbsp;as_literal</a></h2>
<p><tt class="docutils literal"><span class="pre">as_literal</span></tt> constructs a <tt class="docutils literal"><span class="pre">range</span></tt> that delimits the range specified as parameter.
<tt class="docutils literal"><span class="pre">Char*</span></tt> and <tt class="docutils literal"><span class="pre">Char[]</span></tt> are considered to be null-terminate strings. <tt class="docutils literal"><span class="pre">strlen</span></tt> is used to determine
the length of the string. Other range type are passed unmodified.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range&gt;
range&lt;typename range_value&lt;Range&gt;::type&gt; as_literal(const Range&amp; r);

template&lt;typename Char&gt;
range&lt;Char*&gt; as_literal(Char* pch);

template&lt;typename Char, size_t sz&gt;
range&lt;Char*&gt; as_literal(Char (&amp;arr)[sz])
</pre>
<dl class="docutils">
<dt><strong>Requires:</strong> </dt>
<dd><ul class="first last simple">
<li>Range must satisfy the range concept requirements (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">N1871</a>).</li>
<li><tt class="docutils literal"><span class="pre">Char*</span></tt> must point to a null-terminated string.</li>
<li><tt class="docutils literal"><span class="pre">char_traits&lt;Char&gt;</span></tt> is defined.</li>
</ul>
</dd>
</dl>
<p><strong>Effect:</strong> Construct a <tt class="docutils literal"><span class="pre">range</span></tt> that delimits the input string.</p>
</div>
<div class="section" id="as-array">
<h2><a class="toc-backref" href="#id68" name="as-array">6.2&nbsp;&nbsp;&nbsp;as_array</a></h2>
<p><tt class="docutils literal"><span class="pre">as_array</span></tt> constructs a <tt class="docutils literal"><span class="pre">range</span></tt> that delimits the range specified as parameter.
<tt class="docutils literal"><span class="pre">Char[]</span></tt> literals are considered to be C-arrays. The array dimension is used to determine
the length of the string. Other range types are passed unmodified.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range&gt;
range&lt;typename range_value&lt;Range&gt;::type&gt; as_array(const Range&amp; r);

template&lt;typename Char, size_t sz&gt;
range&lt;Char*&gt; as_array(Char (&amp;arr)[sz])
</pre>
<p><strong>Requires:</strong> Range must satisfy the range concept requirements (Range library proposal)</p>
<p><strong>Effect:</strong> Constructs a <tt class="docutils literal"><span class="pre">range</span></tt> that delimits the input string.</p>
</div>
</div>
<div class="section" id="discussion-and-open-issues">
<h1><a class="toc-backref" href="#id69" name="discussion-and-open-issues">7&nbsp;&nbsp;&nbsp;Discussion and open issues</a></h1>
<div class="section" id="string-affinity">
<h2><a class="toc-backref" href="#id70" name="string-affinity">7.1&nbsp;&nbsp;&nbsp;String affinity</a></h2>
<p>This issue is rather philosophical, but it might have an impact on several issues discussed later.
The proposal declares that it is targeted mainly for string processing. Algorithms are designed
with this as a primary goal in mind. However some of them can be also used outside of this scope.</p>
<p>So the question is if the string affinity should be strongly declared or if on the other hand,
the usage outside of this scope should be encouraged.</p>
</div>
<div class="section" id="placement">
<h2><a class="toc-backref" href="#id71" name="placement">7.2&nbsp;&nbsp;&nbsp;Placement</a></h2>
<p>This proposal does not explicitly state the header files where the algorithms should be located.
There are several possible options.</p>
<ul>
<li><p class="first">Distributed approach</p>
<p>No new headers will be created. Rather, the entities from this
proposal will be distributed among the existing headers. Algorithms will go into <tt class="docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt>
header, predicates to <tt class="docutils literal"><span class="pre">&lt;functional&gt;</span></tt>.</p>
<p>This approach is a good candidate if string affinity (discussed in as the first issue)
is not strongly declared.</p>
</li>
<li><p class="first">Monolithic approach</p>
<p>New header will be created, named <tt class="docutils literal"><span class="pre">&lt;stringalgo&gt;</span></tt> that will encompass all the entities presented here.
Optionally the entities can be added to <tt class="docutils literal"><span class="pre">&lt;string&gt;</span></tt> header.</p>
<p>Again, this approach is the natural choice if the string affinity of the algorithms is strengthened.</p>
</li>
</ul>
</div>
<div class="section" id="range-library-and-char-literals-handling">
<h2><a class="toc-backref" href="#id72" name="range-library-and-char-literals-handling">7.3&nbsp;&nbsp;&nbsp;Range Library and char literals handling</a></h2>
<p>During the writing of this proposal, the Range Library proposal had not been finished. There are some issues that
arise due to the interaction with this library. These issues will have to be solved before adopting these two
proposals together.</p>
<p>Probably the most problematic is the support for character literals. There are two different
views on the literal:</p>
<ul class="simple">
<li>As Null-terminated string</li>
<li>As C-array</li>
</ul>
<p>The compiler treats literals as C-arrays with the length that includes the terminating zero.
In contrast, when using 'null-terminated string' view, zero at the end is only a terminator
and is not considered to be a part of the string. Unfortunately, there is no facility in the 
language that can be used to specify this intention. Therefor the user must know what the algorithm
expects and provide the input in the required form.</p>
<p>Prior versions of <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost Range Library</a> contain a special handling for character literal. 
<tt class="docutils literal"><span class="pre">char[]</span></tt> and <tt class="docutils literal"><span class="pre">wchar_t[]</span></tt> were treated as null-terminated strings. 
There was also support for <tt class="docutils literal"><span class="pre">char*</span></tt> and <tt class="docutils literal"><span class="pre">wchar_t*</span></tt>.
Later this special handling was considered dangerous, since the other C-array types were handled differently
(using the array size for determining the boundaries). 
Current proposal supports only C-arrays and it does so uniformly.</p>
<p>However, this is not natural for string processing. For example <tt class="docutils literal"><span class="pre">contains(str,</span> <span class="pre">&quot;hello&quot;)</span></tt> will look
for <tt class="docutils literal"><span class="pre">'h','e','l','l','o',0</span></tt> rather then for <tt class="docutils literal"><span class="pre">&quot;hello&quot;</span></tt>.</p>
<p>We suggest two possible solutions: <em>explicit</em> and <em>implicit</em>.</p>
<div class="section" id="explicit-solution">
<h3><a class="toc-backref" href="#id73" name="explicit-solution">7.3.1&nbsp;&nbsp;&nbsp;Explicit solution</a></h3>
<p>As the name suggests, all literal handling should be explicit. When using a literal <tt class="docutils literal"><span class="pre">as_literal</span></tt> of <tt class="docutils literal"><span class="pre">as_array</span></tt> 
will have to be used. To avoid problems arising from unexpected behaviour, range library should be adapted to 
disallow implicit usage of C-arrays.</p>
<p>For example:</p>
<pre class="literal-block">
starts_with(str, as_literal(&quot;hello&quot;));

char arr[]={'b','y','e'};
starts_with(str, as_array(arr));
</pre>
<p>The advantage of this approach is clarity and correctness. It is not possible to confuse a C-array and a literal,
because the true intention must be specified explicitly. Passing an argument directly will generate a compiler
error.</p>
<p>Disadvantages are mainly of cosmetic nature. Code becomes more verbose. Using a manipulator at every place might
become tedious.</p>
</div>
<div class="section" id="implicit-solution">
<h3><a class="toc-backref" href="#id74" name="implicit-solution">7.3.2&nbsp;&nbsp;&nbsp;Implicit solution</a></h3>
<p>In this solution, Range Library would support C-arrays directly. However, algorithms will be able to
provide support for literals if appropriate. <tt class="docutils literal"><span class="pre">as_literal</span></tt> is designed in such a way that it processes
only null-terminated strings and C-arrays. For all other range types it is transparent, acting as an
identity function. Therefore it is possible to write an algorithm as follows:</p>
<pre class="literal-block">
template&lt;typename Range&gt;
bool AlgoImpl(const Range&amp; r);

template&lt;typename Range&gt;
bool Algo(const Range&amp; r)
{
  return AlgoImpl(as_literal(r));
} 
</pre>
<p>This simple construct extends the set of accepted types by character literals, even when there is no direct
support for them in the Range Library. In addition null-terminated strings (<tt class="docutils literal"><span class="pre">char*</span></tt> and <tt class="docutils literal"><span class="pre">wchar_t*</span></tt> and 
character based C-arrays will be treated as C-strings.</p>
<p>When this handling is inappropriate, user can explicitly cast the input to array using <tt class="docutils literal"><span class="pre">as_array</span></tt>
construct:</p>
<pre class="literal-block">
char arr[]={'b','y','e'};
Algo(as_array(arr));
</pre>
<p><tt class="docutils literal"><span class="pre">as_array</span></tt> will convert the input to <tt class="docutils literal"><span class="pre">range</span></tt>. Because that is not a type that <tt class="docutils literal"><span class="pre">as_literal</span></tt> directly 
processes, it will be passed through unchanged.</p>
<p>This way, the algorithms will need to be clearly marked, as to what types of arguments they accept and how they process
them in the documentation. String affinity of algorithms will be strengthened.</p>
<p>The advantage of this approach lies mainly in the simplification of code from the user perspective. In majority of
cases the user will not be forced to make explicit specification, implicit handling will work just fine.</p>
<p>On the other hand, there remains the possibility for errors. Different algorithms will use the same arguments
in different ways. Such behaviour might be confusing.</p>
</div>
</div>
<div class="section" id="selection-of-algorithms">
<h2><a class="toc-backref" href="#id75" name="selection-of-algorithms">7.4&nbsp;&nbsp;&nbsp;Selection of algorithms</a></h2>
<p>The choice of algorithms is not based on some rigorous study, rather it comes from programming experience
and various discussions. Even if we believe that the selection covers most essential ones,
there is always place for improvements and possible additions.</p>
<p>This topic is therefore open for discussion.</p>
</div>
</div>
<div class="section" id="id25">
<h1><a class="toc-backref" href="#id76" name="id25">8&nbsp;&nbsp;&nbsp;References</a></h1>
<ol class="arabic simple">
<li>Boost String Algorithms Library,
<a class="reference" href="http://www.boost.org/doc/html/string_algo.html">http://www.boost.org/doc/html/string_algo.html</a></li>
<li>Regular Expressions proposal,
<a class="reference" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm">http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm</a></li>
<li>RValue reference proposal (N1770) and related documents,
<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1770.html">http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1770.html</a></li>
<li>Range Library proposal, 
<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html">http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1871.html</a></li>
<li>Boost Range Library,
<a class="reference" href="http://www.boost.org/libs/range/index.html">http://www.boost.org/libs/range/index.html</a></li>
</ol>
</div>
</div>
</body>
</html>
