<?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.4: http://docutils.sourceforge.net/" />
<title>Proposal for new string algorithms in TR2</title>
<meta name="author" content="Pavol Droba &lt;droba&#64;topmail.sk&gt;" />
<meta name="date" content="2006-09-08" />
<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-tr2">
<h1 class="title">Proposal for new string algorithms in TR2</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">Number:</th><td class="field-body">N2059=06-0129</td>
</tr>
<tr><th class="docinfo-name">Date:</th>
<td>2006-09-08</td></tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#abstract" id="id18" name="id18">1&nbsp;&nbsp;&nbsp;Abstract</a></li>
<li><a class="reference" href="#motivation" id="id19" name="id19">2&nbsp;&nbsp;&nbsp;Motivation</a><ul class="auto-toc">
<li><a class="reference" href="#existing-practice" id="id20" name="id20">2.1&nbsp;&nbsp;&nbsp;Existing practice</a></li>
</ul>
</li>
<li><a class="reference" href="#impact-on-the-standard" id="id21" name="id21">3&nbsp;&nbsp;&nbsp;Impact on the standard</a></li>
<li><a class="reference" href="#design-issues" id="id22" name="id22">4&nbsp;&nbsp;&nbsp;Design issues</a><ul class="auto-toc">
<li><a class="reference" href="#algorithm-selection" id="id23" name="id23">4.1&nbsp;&nbsp;&nbsp;Algorithm selection</a><ul class="auto-toc">
<li><a class="reference" href="#string-manipulation-and-construction" id="id24" name="id24">4.1.1&nbsp;&nbsp;&nbsp;String manipulation and construction</a></li>
<li><a class="reference" href="#substring-extraction" id="id25" name="id25">4.1.2&nbsp;&nbsp;&nbsp;Substring extraction</a></li>
<li><a class="reference" href="#search-and-replace" id="id26" name="id26">4.1.3&nbsp;&nbsp;&nbsp;Search and replace</a></li>
<li><a class="reference" href="#transformation" id="id27" name="id27">4.1.4&nbsp;&nbsp;&nbsp;Transformation</a></li>
<li><a class="reference" href="#parsing-and-formatting" id="id28" name="id28">4.1.5&nbsp;&nbsp;&nbsp;Parsing and formatting</a></li>
<li><a class="reference" href="#trimming-and-padding" id="id29" name="id29">4.1.6&nbsp;&nbsp;&nbsp;Trimming and padding</a></li>
<li><a class="reference" href="#string-predicates" id="id30" name="id30">4.1.7&nbsp;&nbsp;&nbsp;String predicates</a></li>
<li><a class="reference" href="#others" id="id31" name="id31">4.1.8&nbsp;&nbsp;&nbsp;Others</a></li>
</ul>
</li>
<li><a class="reference" href="#string-representation" id="id32" name="id32">4.2&nbsp;&nbsp;&nbsp;String representation</a></li>
<li><a class="reference" href="#differences-from-the-boost-string-algorithms-library" id="id33" name="id33">4.3&nbsp;&nbsp;&nbsp;Differences from the Boost String Algorithms Library</a></li>
</ul>
</li>
<li><a class="reference" href="#character-literals-handling" id="id34" name="id34">5&nbsp;&nbsp;&nbsp;Character literals handling</a><ul class="auto-toc">
<li><a class="reference" href="#literal-helpers" id="id35" name="id35">5.1&nbsp;&nbsp;&nbsp;Literal helpers</a><ul class="auto-toc">
<li><a class="reference" href="#as-literal" id="id36" name="id36">5.1.1&nbsp;&nbsp;&nbsp;as_literal</a></li>
<li><a class="reference" href="#as-array" id="id37" name="id37">5.1.2&nbsp;&nbsp;&nbsp;as_array</a></li>
</ul>
</li>
<li><a class="reference" href="#implementation" id="id38" name="id38">5.2&nbsp;&nbsp;&nbsp;Implementation</a></li>
</ul>
</li>
<li><a class="reference" href="#algorithms" id="id39" name="id39">6&nbsp;&nbsp;&nbsp;Algorithms</a><ul class="auto-toc">
<li><a class="reference" href="#case-conversion" id="id40" name="id40">6.1&nbsp;&nbsp;&nbsp;Case Conversion</a><ul class="auto-toc">
<li><a class="reference" href="#to-lower" id="id41" name="id41">6.1.1&nbsp;&nbsp;&nbsp;to_lower</a></li>
<li><a class="reference" href="#to-upper" id="id42" name="id42">6.1.2&nbsp;&nbsp;&nbsp;to_upper</a></li>
</ul>
</li>
<li><a class="reference" href="#predicates" id="id43" name="id43">6.2&nbsp;&nbsp;&nbsp;Predicates</a><ul class="auto-toc">
<li><a class="reference" href="#starts-with" id="id44" name="id44">6.2.1&nbsp;&nbsp;&nbsp;starts_with</a></li>
<li><a class="reference" href="#ends-with" id="id45" name="id45">6.2.2&nbsp;&nbsp;&nbsp;ends_with</a></li>
<li><a class="reference" href="#contains" id="id46" name="id46">6.2.3&nbsp;&nbsp;&nbsp;contains</a></li>
<li><a class="reference" href="#equals" id="id47" name="id47">6.2.4&nbsp;&nbsp;&nbsp;equals</a></li>
<li><a class="reference" href="#lexicographical-compare" id="id48" name="id48">6.2.5&nbsp;&nbsp;&nbsp;lexicographical_compare</a></li>
<li><a class="reference" href="#all-3" id="id49" name="id49">6.2.6&nbsp;&nbsp;&nbsp;all </a></li>
<li><a class="reference" href="#none-3" id="id50" name="id50">6.2.7&nbsp;&nbsp;&nbsp;none </a></li>
</ul>
</li>
<li><a class="reference" href="#trimming" id="id51" name="id51">6.3&nbsp;&nbsp;&nbsp;Trimming</a><ul class="auto-toc">
<li><a class="reference" href="#trim-left-6" id="id52" name="id52">6.3.1&nbsp;&nbsp;&nbsp;trim_left </a></li>
<li><a class="reference" href="#trim-right-6" id="id53" name="id53">6.3.2&nbsp;&nbsp;&nbsp;trim_right </a></li>
<li><a class="reference" href="#trim" id="id54" name="id54">6.3.3&nbsp;&nbsp;&nbsp;trim</a></li>
</ul>
</li>
<li><a class="reference" href="#padding" id="id55" name="id55">6.4&nbsp;&nbsp;&nbsp;Padding</a><ul class="auto-toc">
<li><a class="reference" href="#pad-left" id="id56" name="id56">6.4.1&nbsp;&nbsp;&nbsp;pad_left</a></li>
<li><a class="reference" href="#pad-right" id="id57" name="id57">6.4.2&nbsp;&nbsp;&nbsp;pad_right</a></li>
<li><a class="reference" href="#pad" id="id58" name="id58">6.4.3&nbsp;&nbsp;&nbsp;pad</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#placement" id="id59" name="id59">7&nbsp;&nbsp;&nbsp;Placement</a></li>
<li><a class="reference" href="#discussion-and-open-issues" id="id60" name="id60">8&nbsp;&nbsp;&nbsp;Discussion and open issues</a><ul class="auto-toc">
<li><a class="reference" href="#c-string-support" id="id61" name="id61">8.1&nbsp;&nbsp;&nbsp;C-string support</a></li>
</ul>
</li>
<li><a class="reference" href="#references" id="id62" name="id62">9&nbsp;&nbsp;&nbsp;References</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id18" id="abstract" name="abstract">1&nbsp;&nbsp;&nbsp;Abstract</a></h1>
<p>This proposal introduces several string manipulating algorithms for addition into the C++ standard
library.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id19" id="motivation" 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 and they 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 be applied in 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,
these options are very limited.</p>
<p>This paper tries to address this deficiency by introducing some of the often used algorithms into the
standard library.</p>
<div class="section">
<h2><a class="toc-backref" href="#id20" id="existing-practice" name="existing-practice">2.1&nbsp;&nbsp;&nbsp;Existing practice</a></h2>
<p>This 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>The 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">
<h1><a class="toc-backref" href="#id21" id="impact-on-the-standard" name="impact-on-the-standard">3&nbsp;&nbsp;&nbsp;Impact on the standard</a></h1>
<p>The proposal is directly dependent on other two proposed extensions: Range Library (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2006/n2068.html">N2068</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 existing parts of the standard
library are required.</p>
<p>Both requirements can be refined/relaxed to be compatible with C++2003 version of the standard. Range library can be, with
some restrictions, redefined to use the current standard. The <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost Range Library</a> implementation is a direct proof the of this claim.
Algorithms that use rvalue reference to perform move semantics can also be altered to do simple
in-place mutation. The main functionality of algorithms will be still maintained <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>.</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>This is actually how the Boost String Algorithm Library is implemented. Instead of version that takes a <tt class="docutils literal"><span class="pre">&amp;&amp;</span></tt> parameter,
there is a version that takes a <tt class="docutils literal"><span class="pre">&amp;</span></tt> parameter and mutates the argument directly.</td></tr>
</tbody>
</table>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id22" id="design-issues" name="design-issues">4&nbsp;&nbsp;&nbsp;Design issues</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="algorithm-selection" name="algorithm-selection">4.1&nbsp;&nbsp;&nbsp;Algorithm selection</a></h2>
<p>String processing is a wide application area. Therefore there is also a large quantity of various
related algorithms. Obviously, not all of them are suitable for a general purpose library like the C++ Standard Library.
Our goal is to provide the essential algorithms that are not available in the standard by other or require nontrivial
effort to implemenent.</p>
<p>In the search for the 'essential ones' we have considered some general purpose C++ libraries and standard libraries
for mainstream languages comparable to the C++ in the area of application. Each of these representatives have
one or more string classes, each with a set of operations bound to them.</p>
<p>Here is the list of representatives:</p>
<ul class="simple">
<li>STL, <a class="reference" href="http://www.sgi.com/tech/stl/basic_string.html">std::basic_string</a></li>
<li>MFC, <a class="reference" href="http://msdn2.microsoft.com/en-us/library/5bzxfsea.aspx">CString class</a></li>
<li>Qt, <a class="reference" href="http://doc.trolltech.com/4.2/qstring.html">QString class</a></li>
<li>Java, <a class="reference" href="http://java.sun.com/j2se/1.3/docs/api/java/lang/String.html">String and StringBuffer classes</a></li>
<li>C#, <a class="reference" href="http://msdn2.microsoft.com/en-us/library/system.string.aspx">System.String and StringBuilder classes</a></li>
</ul>
<p>Scripting languages have naturally been strong in the string processing. We include two representatives in our comparison.
We have chosen these two because they are object oriented and widely used.</p>
<ul class="simple">
<li><a class="reference" href="http://docs.python.org/lib/string-methods.html">Python</a></li>
<li>Ruby, <a class="reference" href="http://www.ruby-doc.org/core/classes/String.html">Ruby.String class</a></li>
</ul>
<p>Algorithms presented in these libraries can be divided into the following categories:</p>
<ul class="simple">
<li>String manipulation and construction</li>
<li>Substring extraction</li>
<li>Search and replace</li>
<li>Transformation</li>
<li>Parsing and formatting</li>
<li>Trimming and padding</li>
<li>Predicates</li>
<li>Others</li>
</ul>
<div class="section">
<h3><a class="toc-backref" href="#id24" id="string-manipulation-and-construction" name="string-manipulation-and-construction">4.1.1&nbsp;&nbsp;&nbsp;String manipulation and construction</a></h3>
<p>This category consists of algorithms that directly modify a string. Operations include construction,
concatenation, insertion and erasure.</p>
<p><strong>Representatives</strong>:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">basic_string</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">assign</span></tt></li>
<li><tt class="docutils literal"><span class="pre">append</span></tt></li>
<li><tt class="docutils literal"><span class="pre">operator+=</span></tt></li>
<li><tt class="docutils literal"><span class="pre">insert</span></tt></li>
<li><tt class="docutils literal"><span class="pre">erase</span></tt></li>
<li>...</li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">CString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">Append</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Delete</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Insert</span></tt></li>
<li><tt class="docutils literal"><span class="pre">operator+=</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">Ruby.String</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">concat</span></tt></li>
<li><tt class="docutils literal"><span class="pre">delete</span></tt></li>
<li><tt class="docutils literal"><span class="pre">insert</span></tt></li>
</ul>
</li>
</ul>
<p>All of the mentioned libraries including STL <tt class="docutils literal"><span class="pre">basic_string</span></tt> implement this to a reasonable extend.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id25" id="substring-extraction" name="substring-extraction">4.1.2&nbsp;&nbsp;&nbsp;Substring extraction</a></h3>
<p><strong>Representatives:</strong></p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">basic_string::substr</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">Left</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Mid</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Right</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">Java.String.substring</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Ruby.String[]</span></tt></li>
</ul>
<p>Strongly-typed languages offer methods that extract a substring between a specified indexes. Some libraries
have also methods for simple extraction from the start or the end of a string. Scripting languages like ruby combine all
this functionality into the <tt class="docutils literal"><span class="pre">operator[]</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">basic_string</span></tt> is limited to one extraction method. It can perform all of the required operations at the cost of
slightly more verbose code.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id26" id="search-and-replace" name="search-and-replace">4.1.3&nbsp;&nbsp;&nbsp;Search and replace</a></h3>
<p>Searching for a substring in a string and replacing it with something else is one of the fundamental string
operations.</p>
<p><strong>Representatives:</strong></p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">basic_string::find</span></tt></li>
<li><tt class="docutils literal"><span class="pre">QString::indexOf</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CString::Find</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Java.String.indexOf</span></tt></li>
</ul>
<p>Libraries offer various levels of flexibility for these operations. The basic level allows to search for the exact
string. An improvement is the ability to ignore the case. Most powerful is searching using an expression that
describes the substring. Regular expressions are the de facto standard in the last category.</p>
<p>Current C++ standard is limited to the basic level of functionality. Fortunately, this state was radically changed by
accepting the <a class="reference" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1429.htm">Regex</a> Library into TR1.</p>
<p>Note: <tt class="docutils literal"><span class="pre">split</span></tt> and its variant can be also considered to be a part of this category.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id27" id="transformation" name="transformation">4.1.4&nbsp;&nbsp;&nbsp;Transformation</a></h3>
<p>Probably the most frequently used operation from this category is the case conversion.</p>
<p><strong>Representatives:</strong></p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">CString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">MakeUpper</span></tt></li>
<li><tt class="docutils literal"><span class="pre">MakeLower</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">QString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">toLower</span></tt></li>
<li><tt class="docutils literal"><span class="pre">toUpper</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">Java</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">toUpperCase</span></tt></li>
<li><tt class="docutils literal"><span class="pre">toLowerCase</span></tt></li>
</ul>
</li>
</ul>
<p>It is present in all the mentioned libraries, except for STL. Being one of the most basic operation, its absence in
the Standard Library is problematic at least. Therefore it is part of this proposal.</p>
<p>Other transformations found in the libraries are usually domain-specific and not universally accepted.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id28" id="parsing-and-formatting" name="parsing-and-formatting">4.1.5&nbsp;&nbsp;&nbsp;Parsing and formatting</a></h3>
<p>We will omit these two categories from the scope of this proposal. Both are rather complex and require
more elaboration to give some reasonable results. Separate proposals should be considered for this domain.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id29" id="trimming-and-padding" name="trimming-and-padding">4.1.6&nbsp;&nbsp;&nbsp;Trimming and padding</a></h3>
<p>Strings are often printed with spaces on either side to improve the readability on the screen. These spaces
have usually no semantic value and must be removed prior to processing. This removal is called trimming.
The converse operation, when spaces are added to the front or the end of string, is called padding.</p>
<p>Both operations can be found in most of the mentioned libraries.</p>
<p><strong>Representatives:</strong></p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">QString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">trimmed</span></tt></li>
<li><tt class="docutils literal"><span class="pre">leftJustified</span></tt></li>
<li><tt class="docutils literal"><span class="pre">rightJustified</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">CString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">Trim</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TrimLeft</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TrimRight</span></tt></li>
</ul>
</li>
<li>C# <tt class="docutils literal"><span class="pre">System.String</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">TrimStart</span></tt></li>
<li><tt class="docutils literal"><span class="pre">TrimEnd</span></tt></li>
<li><tt class="docutils literal"><span class="pre">PadLeft</span></tt></li>
<li><tt class="docutils literal"><span class="pre">PadRight</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">Ruby.String</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">strip</span></tt></li>
<li><tt class="docutils literal"><span class="pre">center</span></tt></li>
<li><tt class="docutils literal"><span class="pre">rjust</span></tt></li>
<li><tt class="docutils literal"><span class="pre">ljust</span></tt></li>
</ul>
</li>
</ul>
<p>This functionality is completely missing in the Standard Library, therefore it is part of this proposal.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id30" id="string-predicates" name="string-predicates">4.1.7&nbsp;&nbsp;&nbsp;String predicates</a></h3>
<p>Even if this category is quite broad there is a relatively small number of algorithms that are used frequently.
We have focused on predicates that examine relationship between the two strings. Relation operators (<tt class="docutils literal"><span class="pre">&lt;,=,&gt;</span></tt>) that fall in
this category are present in all libraries. Additionally, we have containment checks and advanced forms of comparison.</p>
<p><strong>Representatives:</strong></p>
<ul class="simple">
<li>STL<ul>
<li><tt class="docutils literal"><span class="pre">lexicographical_compare</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">QString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">compare</span></tt></li>
<li><tt class="docutils literal"><span class="pre">startsWith</span></tt></li>
<li><tt class="docutils literal"><span class="pre">endsWith</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">Java.String</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">compareTo</span></tt></li>
<li><tt class="docutils literal"><span class="pre">startsWith</span></tt></li>
<li><tt class="docutils literal"><span class="pre">endsWith</span></tt></li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">CString</span></tt><ul>
<li><tt class="docutils literal"><span class="pre">Compare</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CompareNoCase</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Collate</span></tt></li>
<li><tt class="docutils literal"><span class="pre">CollateNoCase</span></tt></li>
</ul>
</li>
</ul>
<p>This area is not sufficiently covered in the Standard Library. The predicates presented here are
therefore a useful addition.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id31" id="others" name="others">4.1.8&nbsp;&nbsp;&nbsp;Others</a></h3>
<p>Algorithms that do not fall to any of the above categories are usually domain-specific or too narrow-defined.
Therefore they are not suitable for the context of this proposal.</p>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id32" id="string-representation" name="string-representation">4.2&nbsp;&nbsp;&nbsp;String representation</a></h2>
<p>While a 'string' is 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 FlexString 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/2006/n2068.html">N2068</a>) is used as the interface for accessing the input
strings. The Range Library provides 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 (i.e. characters) are
values that can be copied and moved around without additional overhead.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id33" id="differences-from-the-boost-string-algorithms-library" name="differences-from-the-boost-string-algorithms-library">4.3&nbsp;&nbsp;&nbsp;Differences from the Boost String Algorithms Library</a></h2>
<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. The 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 a 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 a 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 towards 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 intensely debated. A strong
opinion was expressed in favor of functional approach, however without the move semantics support,
it is not possible to implement certain 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/2006/n2068.html">N2068</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 class="section">
<h1><a class="toc-backref" href="#id34" id="character-literals-handling" name="character-literals-handling">5&nbsp;&nbsp;&nbsp;Character literals handling</a></h1>
<p>The Range library proposal (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2006/n2068.html">N2068</a>) does not contain direct support for handling of the character literals.
This support was present in <a class="reference" href="http://www.boost.org/libs/range/index.html">Boost Range Library</a>, but it was deprecated due to the inconsistencies in
usage of the built-in arrays. Character literals are typed as C-arrays of <tt class="docutils literal"><span class="pre">char</span></tt> (s) or <tt class="docutils literal"><span class="pre">wchar_t</span></tt> (s).
The problematic isssue is the zero terminator at the end. For string processing, this terminator should not be a part
of the range, on the other hand, generic array usage requires that the entire array is considered to be a part
of range.</p>
<p>A hybrid solution that uses literal helpers is therefore suggested. The default behaviour of range is
defined in the range proposal. Algorithms, specifically in the domain of string processing, can override this
default by applying <tt class="docutils literal"><span class="pre">as_literal</span></tt> to the input arguments.</p>
<p>Please note, that there is no support planned for null terminated C-strings. Unlike literals, these have
type <tt class="docutils literal"><span class="pre">char*</span></tt> or <tt class="docutils literal"><span class="pre">wchar_t*</span></tt>. Usage of plain C-strings is discouraged due to their inherently unsafe nature.
A user can still convert C-string to a <tt class="docutils literal"><span class="pre">range</span></tt> prior to usage.</p>
<div class="section">
<h2><a class="toc-backref" href="#id35" id="literal-helpers" name="literal-helpers">5.1&nbsp;&nbsp;&nbsp;Literal helpers</a></h2>
<p>Both helpers convert a character literal to a range. 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 addition, they behave neutrally to the other ranges. That means they return the same range as the input
(modulo <tt class="docutils literal"><span class="pre">range</span></tt> wrapping).</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>
<div class="section">
<h3><a class="toc-backref" href="#id36" id="as-literal" name="as-literal">5.1.1&nbsp;&nbsp;&nbsp;as_literal</a></h3>
<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 the parameter.
<tt class="docutils literal"><span class="pre">Char[]</span></tt> (s) are considered to be null-terminated 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_iterator&lt;Range&gt;::type&gt; as_literal(const Range&amp; r);

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/2006/n2068.html">N2068</a>).</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">
<h3><a class="toc-backref" href="#id37" id="as-array" name="as-array">5.1.2&nbsp;&nbsp;&nbsp;as_array</a></h3>
<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>Note, this is actually the default behaviour for the range library.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename Range&gt;
range&lt;typename range_iterator&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>
<dl class="docutils">
<dt><strong>Note:</strong> This is actually the default behaviour for the range library. Therefore an implementation</dt>
<dd>can simply forward call to <tt class="docutils literal"><span class="pre">make_range</span></tt>.</dd>
</dl>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id38" id="implementation" name="implementation">5.2&nbsp;&nbsp;&nbsp;Implementation</a></h2>
<p>An algorithm that wants to allow a user to pass a character literal in its parameter
needs to use <tt class="docutils literal"><span class="pre">as_literal</span></tt> to convert the input parameter.</p>
<p><strong>Example:</strong></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>Alternatively, if a user requires to pass an argument as an array rather then literal, she can override
the <tt class="docutils literal"><span class="pre">as_literal</span></tt> conversion in the algorithm by using <tt class="docutils literal"><span class="pre">as_array</span></tt>.</p>
<p><strong>Example:</strong></p>
<pre class="literal-block">
char arr[6]={ 'h', 'e', 'l', 'l', 'o' };
Algo(as_array(arr));
</pre>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id39" id="algorithms" name="algorithms">6&nbsp;&nbsp;&nbsp;Algorithms</a></h1>
<p>Unless stated otherwise, types of arguments passed to the template functions must satisfy the requirements
defined by the concept of the same name as the corresponding template argument. The used concepts are either defined in
the Standard Library Reference or they are part of the Range Library Proposal (<a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2006/n2068.html">N2068</a>).</p>
<p>In addition, all parameters of <tt class="docutils literal"><span class="pre">Range</span></tt> type shall be converted using <tt class="docutils literal"><span class="pre">as_literal</span></tt> helper as described above.</p>
<div class="section">
<h2><a class="toc-backref" href="#id40" id="case-conversion" name="case-conversion">6.1&nbsp;&nbsp;&nbsp;Case Conversion</a></h2>
<p>These algorithms perform case-conversion on all characters in the string.</p>
<div class="section">
<h3><a class="toc-backref" href="#id41" id="to-lower" name="to-lower">6.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());
</pre>
<p><strong>Returns:</strong> A modification of <tt class="docutils literal"><span class="pre">s</span></tt> such that each element <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">tolower(y,</span> <span class="pre">loc)</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is a corresponding element in the original <tt class="docutils literal"><span class="pre">s</span></tt>. <a class="footnote-reference" href="#id5" id="id3" name="id3">[2]</a></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange&amp;&amp; to_lower(CopyableRange&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<p><strong>Returns:</strong> <tt class="docutils literal"><span class="pre">to_lower(</span> <span class="pre">CopyableRange(s),</span> <span class="pre">loc)</span></tt></p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id42" id="to-upper" name="to-upper">6.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());
</pre>
<p><strong>Returns:</strong> A modification of <tt class="docutils literal"><span class="pre">s</span></tt> such that each element <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">toupper(y,</span> <span class="pre">loc)</span></tt> where <tt class="docutils literal"><span class="pre">y</span></tt> is a corresponding element in the original <tt class="docutils literal"><span class="pre">s</span></tt>. <a class="footnote-reference" href="#id5" id="id4" name="id4">[2]</a></p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
CopyableRange&amp;&amp; to_upper(CopyableRange&amp;&amp; s, const locale&amp; loc=locale());
</pre>
<p><strong>Returns:</strong> <tt class="docutils literal"><span class="pre">to_upper(</span> <span class="pre">CopyableRange(s),</span> <span class="pre">loc)</span></tt></p>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id5">[2]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>)</em> An implicit requirement is implied from using <tt class="docutils literal"><span class="pre">toupper</span></tt> and <tt class="docutils literal"><span class="pre">tolower</span></tt>. <tt class="docutils literal"><span class="pre">ctype</span></tt> must be specialised
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">
<h2><a class="toc-backref" href="#id43" id="predicates" name="predicates">6.2&nbsp;&nbsp;&nbsp;Predicates</a></h2>
<p>These algorithms perform containment checks of various types and the string comparison.</p>
<div class="section">
<h3><a class="toc-backref" href="#id44" id="starts-with" name="starts-with">6.2.1&nbsp;&nbsp;&nbsp;starts_with</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
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 starts_with(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool istarts_with(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><p class="first">The predicate checks if <tt class="docutils literal"><span class="pre">r2</span></tt> is a prefix of <tt class="docutils literal"><span class="pre">r1</span></tt>. In other words,
it holds when <tt class="docutils literal"><span class="pre">size(r1)&gt;=size(r2)</span></tt> and each element from <tt class="docutils literal"><span class="pre">r2</span></tt> is equal to
corresponding element in <tt class="docutils literal"><span class="pre">r1</span></tt>, beginning from the start of <tt class="docutils literal"><span class="pre">r1</span></tt>.</p>
<p class="last">The first form uses <tt class="docutils literal"><span class="pre">operator==</span></tt> for comparison, second one uses the given predicate and
the last one is comparing using the expression <tt class="docutils literal"><span class="pre">tolower(x,</span> <span class="pre">loc)==tolower(y,</span> <span class="pre">loc)</span></tt></p>
</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">
<h3><a class="toc-backref" href="#id45" id="ends-with" name="ends-with">6.2.2&nbsp;&nbsp;&nbsp;ends_with</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
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 ends_with(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool iends_with(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>The predicate checks if <tt class="docutils literal"><span class="pre">r2</span></tt> is a suffix of <tt class="docutils literal"><span class="pre">r1</span></tt>. Equals to <tt class="docutils literal"><span class="pre">istarts_with(reverse(r1),</span> <span class="pre">reverse(r2))</span></tt>.</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">
<h3><a class="toc-backref" href="#id46" id="contains" name="contains">6.2.3&nbsp;&nbsp;&nbsp;contains</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
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 contains(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool icontains(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><p class="first">The predicate checks if <tt class="docutils literal"><span class="pre">r2</span></tt> is contained within <tt class="docutils literal"><span class="pre">r1</span></tt>.
It returns true if <tt class="docutils literal"><span class="pre">size(r1)&gt;=size(r2)</span></tt> and there exists an index <tt class="docutils literal"><span class="pre">n</span></tt> such that
<tt class="docutils literal"><span class="pre">r2[i]==r1[i+n]</span></tt> for all indexes <tt class="docutils literal"><span class="pre">i</span></tt> in <tt class="docutils literal"><span class="pre">r1</span></tt>,</p>
<p class="last">The first form uses <tt class="docutils literal"><span class="pre">operator==</span></tt> for comparison, second one uses the given predicate and
the last one is comparing using expression <tt class="docutils literal"><span class="pre">tolower(x,</span> <span class="pre">loc)==tolower(y,</span> <span class="pre">loc)</span></tt></p>
</dd>
</dl>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id47" id="equals" name="equals">6.2.4&nbsp;&nbsp;&nbsp;equals</a></h3>
<p>The <tt class="docutils literal"><span class="pre">equals</span></tt> algorithm is actually a two-way version of <tt class="docutils literal"><span class="pre">equal</span></tt> available in the <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&gt;
bool equals(const Range1&amp; r1, const Range2&amp; r2);

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 iequals(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd><p class="first">The predicate checks if <tt class="docutils literal"><span class="pre">r1</span></tt> and <tt class="docutils literal"><span class="pre">r2</span></tt> are equal element wise. It returns true
<tt class="docutils literal"><span class="pre">size(r1)==size(r2)</span></tt> and each element <tt class="docutils literal"><span class="pre">r1[n]</span></tt> from <tt class="docutils literal"><span class="pre">r1</span></tt> is equal to corresponding elements
<tt class="docutils literal"><span class="pre">r2[n]</span></tt> from <tt class="docutils literal"><span class="pre">r2</span></tt>.</p>
<p class="last">First form uses <tt class="docutils literal"><span class="pre">operator==</span></tt> for comparison, second one uses the given predicate and
the last one is comparing using expression <tt class="docutils literal"><span class="pre">tolower(x,</span> <span class="pre">loc)==tolower(y,</span> <span class="pre">loc)</span></tt></p>
</dd>
</dl>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id48" id="lexicographical-compare" name="lexicographical-compare">6.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 a simpler, range-oriented interface and a case-insensitive
version.</p>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
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 lexicographical_compare(const Range1&amp; r1, const Range2&amp; r2, Pred pred);

template&lt;typename Range1, typename Range2&gt;
bool ilexicographical_compare(const Range1&amp; r1, const Range2&amp; r2, const locale&amp; loc=locale());
</pre>
<p><strong>Returns:</strong> true if <tt class="docutils literal"><span class="pre">r1</span></tt> is lexicographically less than <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">
<h3><a class="toc-backref" href="#id49" id="all-3" name="all-3">6.2.6&nbsp;&nbsp;&nbsp;all <a class="footnote-reference" href="#id8" id="id6" name="id6">[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>Returns:</strong> Returns true if for each element <tt class="docutils literal"><span class="pre">x</span></tt>, <tt class="docutils literal"><span class="pre">pred(x)==true</span></tt>, <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id50" id="none-3" name="none-3">6.2.7&nbsp;&nbsp;&nbsp;none <a class="footnote-reference" href="#id8" id="id7" name="id7">[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>Returns:</strong> Returns true if for each element <tt class="docutils literal"><span class="pre">x</span></tt>, <tt class="docutils literal"><span class="pre">pred(x)==false</span></tt>, <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id8">[3]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">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 is considered a
problem, alternative names might be used.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id51" id="trimming" name="trimming">6.3&nbsp;&nbsp;&nbsp;Trimming</a></h2>
<p>Trimming algorithms remove unnecessary spaces from the beginning and the end of a string. <a class="footnote-reference" href="#id12" id="id9" name="id9">[5]</a></p>
<div class="section">
<h3><a class="toc-backref" href="#id52" id="trim-left-6" name="trim-left-6">6.3.1&nbsp;&nbsp;&nbsp;trim_left <a class="footnote-reference" href="#id13" id="id10" name="id10">[6]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange trim_left(const CopyableRange&amp; s, const locale&amp; loc=locale());

template&lt;typename CopyableRange, typename Pred&gt;
CopyableRange trim_left_if(const Sequence&amp; s, Pred pred);
</pre>
<p><strong>Return:</strong> A copy of the input range where all leading spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.</p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_left(Sequence&amp;&amp; s, const locale&amp; loc=locale());

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_left_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<p><strong>Return:</strong> A modified version of <tt class="docutils literal"><span class="pre">s</span></tt> where all leading spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id53" id="trim-right-6" name="trim-right-6">6.3.2&nbsp;&nbsp;&nbsp;trim_right <a class="footnote-reference" href="#id13" id="id11" name="id11">[6]</a></a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange trim_right(const CopyableRange&amp; s, const locale&amp; loc=locale);

template&lt;typename CopyableRange, typename Pred&gt;
CopyableRange trim_right_if(const Sequence&amp; s, Pred pred);
</pre>
<p><strong>Returns:</strong> A copy of the input range where all trailing spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.</p>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_right(Sequence&amp;&amp; s, const locale&amp; loc=locale);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_right_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<p><strong>Returns:</strong> A modified version of <tt class="docutils literal"><span class="pre">s</span></tt> where all trailing spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.</p>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id54" id="trim" name="trim">6.3.3&nbsp;&nbsp;&nbsp;trim</a></h3>
<p><strong>Synopsis:</strong></p>
<pre class="literal-block">
template&lt;typename CopyableRange&gt;
CopyableRange trim(const CopyableRange&amp; s, const locale&amp; loc=locale());

template&lt;typename CopyableRange, typename Pred&gt;
CopyableRange trim_if(const Sequence&amp; s, Pred pred);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>A copy of the input range where all leading and trailing trailing spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.
Function have the same effect as <tt class="docutils literal"><span class="pre">trim_left(trim_right(s))</span></tt></dd>
</dl>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim(Sequence&amp;&amp; s, const locale&amp; loc=locale());

template&lt;typename Sequence&gt;
Sequence&amp;&amp; trim_if(Sequence&amp;&amp; s, Pred pred);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>A modified version of <tt class="docutils literal"><span class="pre">s</span></tt> where all leading and trailing trailing spaces (characters satisfying <tt class="docutils literal"><span class="pre">pred</span></tt>) have been removed.
Function have same the effect as <tt class="docutils literal"><span class="pre">trim_left(trim_right(s))</span></tt></dd>
</dl>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9" name="id12">[5]</a></td><td>The <tt class="docutils literal"><span class="pre">_if</span></tt> suffix has to be added to the variants that have the predicate argument, to avoid name collisions.
Since the predicate is a generic template argument, it cannot be distinguished from <tt class="docutils literal"><span class="pre">loc</span></tt> argument
during the template instantiation stage.</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">[6]</a></td><td><em>(<a class="fn-backref" href="#id10">1</a>, <a class="fn-backref" href="#id11">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">ends_with</span></tt>, however 'TrimLeft/Right' is more
often used term in currently existing libraries.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id55" id="padding" name="padding">6.4&nbsp;&nbsp;&nbsp;Padding</a></h2>
<p>As the opposite to trimming, padding algorithms add a certain number of spaces to the one or both ends of
the string, so that the string has the specified length.</p>
<p>All algorithms presented here can fill the gap with spaces or using the specified pattern.
The pattern is used as follows: To fill the gap of <tt class="docutils literal"><span class="pre">n</span></tt> elements, pattern is repeated so that a sequence with at
least <tt class="docutils literal"><span class="pre">n</span></tt> elements is created. After that, beginning of this sequence is used to fill the gap.</p>
<div class="section">
<h3><a class="toc-backref" href="#id56" id="pad-left" name="pad-left">6.4.1&nbsp;&nbsp;&nbsp;pad_left</a></h3>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence pad_left(const Sequence&amp; s, unsigned int len);

template&lt;typename Sequence, typename Range&gt;
Sequence pad_left(const Sequence&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt> an identical copy of <tt class="docutils literal"><span class="pre">s</span></tt> is returned. Otherwise the sequence is prepended with spaces
or the repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters.</dd>
</dl>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad_left(Sequence&amp;&amp; s, unsigned int len);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad_left(Sequence&amp;&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt>, the original sequence is returned unaltered. Otherwise the sequence is prepended with spaces
or the repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters.</dd>
</dl>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id57" id="pad-right" name="pad-right">6.4.2&nbsp;&nbsp;&nbsp;pad_right</a></h3>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence pad_right(const Sequence&amp; s, unsigned int len);

template&lt;typename Sequence, typename Range&gt;
Sequence pad_right(const Sequence&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt>, an identical copy of <tt class="docutils literal"><span class="pre">s</span></tt> is returned. Otherwise the sequence is extended with spaces
or the repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters.</dd>
</dl>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad_right(Sequence&amp;&amp; s, unsigned int len);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad_right(Sequence&amp;&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt>, the original sequence is returned unaltered. Otherwise the sequence is extended with spaces
or the repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters.</dd>
</dl>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id58" id="pad" name="pad">6.4.3&nbsp;&nbsp;&nbsp;pad</a></h3>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence pad(const Sequence&amp; s, unsigned int len);

template&lt;typename Sequence, typename Range&gt;
Sequence pad(const Sequence&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt>, an identical copy of <tt class="docutils literal"><span class="pre">s</span></tt> is returned. Otherwise, the sequence is extended on both sides with spaces
or repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters <a class="footnote-reference" href="#id16" id="id14" name="id14">[7]</a>.</dd>
</dl>
<pre class="literal-block">
template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad(Sequence&amp;&amp; s, unsigned int len);

template&lt;typename Sequence&gt;
Sequence&amp;&amp; pad(Sequence&amp;&amp; s, unsigned int len, const Range&amp; pattern);
</pre>
<dl class="docutils">
<dt><strong>Returns:</strong></dt>
<dd>If <tt class="docutils literal"><span class="pre">size(s)&gt;=len</span></tt>, the original sequence is returned unaltered. Otherwise, the sequence is extended on both sides with spaces
or repeated pattern to have the size of <tt class="docutils literal"><span class="pre">len</span></tt> characters <a class="footnote-reference" href="#id16" id="id15" name="id15">[7]</a>.</dd>
</dl>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id16">[7]</a></td><td><em>(<a class="fn-backref" href="#id14">1</a>, <a class="fn-backref" href="#id15">2</a>)</em> The filling characters are distributed evenly to the front and the back. If the difference is of odd length,
the front gap is larger by one character. Both gaps are filled independently as if <tt class="docutils literal"><span class="pre">pad_left</span></tt> and <tt class="docutils literal"><span class="pre">pad_right</span></tt>
were applied in sequence.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id59" id="placement" name="placement">7&nbsp;&nbsp;&nbsp;Placement</a></h1>
<p>The algorithms should be placed into the <tt class="docutils literal"><span class="pre">&lt;stringalgorithm&gt;</span></tt> header. Although <tt class="docutils literal"><span class="pre">&lt;algorithm&gt;</span></tt> header might
be also considered as an option, we have chosen to use a separate header due to dependency on the locales.</p>
<p>Since the scope of literal helpers is larger than this proposal, they shall be placed together with the Range Library.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id60" id="discussion-and-open-issues" name="discussion-and-open-issues">8&nbsp;&nbsp;&nbsp;Discussion and open issues</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id61" id="c-string-support" name="c-string-support">8.1&nbsp;&nbsp;&nbsp;C-string support</a></h2>
<p>Even if this issue is abandoned in the proposal, it could be considered. To support <tt class="docutils literal"><span class="pre">char*</span></tt> and <tt class="docutils literal"><span class="pre">wchar_t*</span></tt>
null-terminated strings, the following extensions must be incorporated:</p>
<ul class="simple">
<li>In the Range Library proposal, range decomposition metafunctions, namely <tt class="docutils literal"><span class="pre">range_iterator</span></tt>, <tt class="docutils literal"><span class="pre">range_reverse_iterator</span></tt>,
<tt class="docutils literal"><span class="pre">range_value</span></tt> and <tt class="docutils literal"><span class="pre">range_difference</span></tt>, must be specialized for <tt class="docutils literal"><span class="pre">Char*</span></tt> types.</li>
<li><tt class="docutils literal"><span class="pre">as_literal</span></tt> helper must be extended for <tt class="docutils literal"><span class="pre">Char*</span></tt>. The specialization will work exactly as for <tt class="docutils literal"><span class="pre">Char[]</span></tt>.</li>
</ul>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id62" id="references" name="references">9&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/2006/n2068.html">http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2006/n2068.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>
