Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/regex/doc/concepts.html @ 14

Last change on this file since 14 was 12, checked in by landauf, 17 years ago

added boost
File size: 20.0 KB
RevLine 
[12]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>Boost.Regex: Index</title>
5      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6      <link rel="stylesheet" type="text/css" href="../../../boost.css">
7   </head>
8   <body>
9      <P>
10         <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
11            <TR>
12               <td valign="top" width="300">
13                  <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
14               </td>
15               <TD width="353">
16                  <H1 align="center">Boost.Regex</H1>
17                  <H2 align="center">Concepts</H2>
18               </TD>
19               <td width="50">
20                  <h3><a href="index.html"><img height="45" width="43" alt="Boost.Regex Index" src="uarrow.gif" border="0"></a></h3>
21               </td>
22            </TR>
23         </TABLE>
24      </P>
25      <HR>
26      <p></p>
27      <H3><A name="charT"></A>charT requirements</H3>
28      <P>Type charT used a template argument to <A href="basic_regex.html">class template
29            basic_regex</A>, must have a trivial default constructor, copy constructor,
30         assignment operator, and destructor.&nbsp; In addition the following
31         requirements must be met for objects; c of type charT, c1 and c2 of type charT
32         const, and i of type int:</P>
33      <P>
34         <TABLE id="Table2" cellSpacing="1" cellPadding="1" width="100%" border="1">
35            <TR>
36               <TD><STRONG>Expression</STRONG></TD>
37               <TD><STRONG>Return type</STRONG></TD>
38               <TD><STRONG>Assertion / Note / Pre- / Post-condition</STRONG></TD>
39            </TR>
40            <TR>
41               <TD>charT c</TD>
42               <TD>charT</TD>
43               <TD>Default constructor (must be trivial).</TD>
44            </TR>
45            <TR>
46               <TD>charT c(c1)</TD>
47               <TD>charT</TD>
48               <TD>Copy constructor (must be trivial).</TD>
49            </TR>
50            <TR>
51               <TD>c1 = c2</TD>
52               <TD>charT</TD>
53               <TD>Assignment operator (must be trivial).</TD>
54            </TR>
55            <TR>
56               <TD>c1 == c2</TD>
57               <TD>bool</TD>
58               <TD>true if&nbsp;c1 has the same value&nbsp;as c2.</TD>
59            </TR>
60            <TR>
61               <TD>c1 != c2</TD>
62               <TD>bool</TD>
63               <TD>true if c1 and c2 are not equal.</TD>
64            </TR>
65            <TR>
66               <TD>c1 &lt; c2</TD>
67               <TD>bool</TD>
68               <TD>true if the value of c1 is less than c2.</TD>
69            </TR>
70            <TR>
71               <TD>c1 &gt; c2</TD>
72               <TD>bool</TD>
73               <TD>true if the value of c1 is greater than c2.</TD>
74            </TR>
75            <TR>
76               <TD>c1 &lt;= c2</TD>
77               <TD>bool</TD>
78               <TD>true if c1 is less than or equal to c2.</TD>
79            </TR>
80            <TR>
81               <TD>c1 &gt;= c2</TD>
82               <TD>bool</TD>
83               <TD>true if c1 is greater than or equal to c2.</TD>
84            </TR>
85            <TR>
86               <TD>intmax_t i = c1</TD>
87               <TD>int</TD>
88               <TD>
89                  <P>charT must be convertible to an integral type.</P>
90                  <P>Note: type charT is not required to support this operation, if the traits class
91                     used supports the full Boost-specific interface, rather than&nbsp;the minimal
92                     standardised-interface (see traits class requirements below).</P>
93               </TD>
94            </TR>
95            <TR>
96               <TD>charT c(i);</TD>
97               <TD>charT</TD>
98               <TD>charT must be constructable from an integral type.</TD>
99            </TR>
100         </TABLE>
101      </P>
102      <H3><A name="traits"></A>traits requirements</H3>
103      <P>There are two sets of requirements for the traits template argument to
104         basic_regex: a mininal interface (which is part of the regex standardization
105         proposal), and an optional Boost-specific enhanced interface.</P>
106      <H4>Minimal requirements.</H4>
107      <P>In the following table X denotes a traits class defining types and functions
108         for the character container type charT; u is an object of type X; v is an
109         object of type const X; p is a value of type const charT*; I1 and I2 are Input
110         Iterators; c is a value of type const charT; s is an object of type
111         X::string_type; cs is an object of type const X::string_type; b is a value of
112         type bool; I is a value of type int; F1 and F2 are values of type const charT*;
113         and loc is an object of type X::locale_type.</P>
114      <P>
115         <TABLE id="Table3" cellSpacing="1" cellPadding="7" width="100%" border="1">
116            <TR>
117               <TD vAlign="top" width="28%">
118                  <P><STRONG>Expression</STRONG></P>
119               </TD>
120               <TD vAlign="top" width="28%">
121                  <P><STRONG>Return type</STRONG></P>
122               </TD>
123               <TD vAlign="top" width="45%">
124                  <P><STRONG>Assertion / Note
125                        <BR>
126                        Pre / Post condition</STRONG></P>
127               </TD>
128            </TR>
129            <TR>
130               <TD vAlign="top" width="28%">
131                  <P>X::char_type</P>
132               </TD>
133               <TD vAlign="top" width="28%">
134                  <P>charT</P>
135               </TD>
136               <TD vAlign="top" width="45%">
137                  <P>The character container type used in the implementation of class template <CODE>basic_regex</CODE>.</P>
138               </TD>
139            </TR>
140            <TR>
141               <TD vAlign="top" width="28%">
142                  <P>X::size_type</P>
143               </TD>
144               <TD vAlign="top" width="28%">
145                  <P>&nbsp;</P>
146               </TD>
147               <TD vAlign="top" width="45%">
148                  <P>An unsigned integer type, capable of holding the length of a null-terminated
149                     string of charT's.</P>
150               </TD>
151            </TR>
152            <TR>
153               <TD vAlign="top" width="28%">
154                  <P>X::string_type</P>
155               </TD>
156               <TD vAlign="top" width="28%">
157                  <P>std::basic_string&lt;charT&gt; or std::vector&lt;charT&gt;</P>
158               </TD>
159               <TD vAlign="top" width="45%">
160                  <P>&nbsp;</P>
161               </TD>
162            </TR>
163            <TR>
164               <TD vAlign="top" width="28%">
165                  <P>X::locale_type</P>
166               </TD>
167               <TD vAlign="top" width="28%">
168                  <P>Implementation defined</P>
169               </TD>
170               <TD vAlign="top" width="45%">
171                  <P>A copy constructible type that represents the locale used by the traits class.</P>
172               </TD>
173            </TR>
174            <TR>
175               <TD vAlign="top" width="28%">
176                  <P>X::char_class_type</P>
177               </TD>
178               <TD vAlign="top" width="28%">
179                  <P>Implementation defined</P>
180               </TD>
181               <TD vAlign="top" width="45%">
182                  <P>A bitmask type representing a particular character classification. Multiple
183                     values of this type can be bitwise-or'ed together to obtain a new valid value.</P>
184               </TD>
185            </TR>
186            <TR>
187               <TD vAlign="top" width="28%">
188                  <P>X::length(p)</P>
189               </TD>
190               <TD vAlign="top" width="28%">
191                  <P>X::size_type</P>
192               </TD>
193               <TD vAlign="top" width="45%">
194                  <P>Yields the smallest <CODE>i</CODE> such that <CODE>p[i] == 0</CODE>. Complexity
195                     is linear in <CODE>i</CODE>.</P>
196               </TD>
197            </TR>
198            <TR>
199               <TD vAlign="top" width="28%">
200                  <P>v.translate(c)</P>
201               </TD>
202               <TD vAlign="top" width="28%">
203                  <P>X::char_type</P>
204               </TD>
205               <TD vAlign="top" width="45%">
206                  <P>Returns a character such that for any character d that is to be considered
207                     equivalent to c then v.translate(c) == v.translate(d).</P>
208               </TD>
209            </TR>
210            <TR>
211               <TD vAlign="top" width="28%">
212                  <P>v.translate_nocase(c)</P>
213               </TD>
214               <TD vAlign="top" width="28%">X::char_type</TD>
215               <TD vAlign="top" width="45%">For all characters C that are to be considered
216                  equivalent to c when comparisons are to be performed without regard to case,
217                  then v.translate_- nocase(c) == v.translate_- nocase(C).</TD>
218            </TR>
219            <TR>
220               <TD vAlign="top" width="28%">
221                  <P>v.transform(F1, F2)</P>
222               </TD>
223               <TD vAlign="top" width="28%">
224                  <P>X::string_type</P>
225               </TD>
226               <TD vAlign="top" width="45%">
227                  <P>Returns a sort key for the character sequence designated by the iterator range
228                     [F1, F2) such that if the character sequence [G1, G2) sorts before the
229                     character sequence [H1, H2) then v.transform(G1, G2) &lt; v.transform(H1,
230                     H2).&nbsp;</P>
231               </TD>
232            </TR>
233            <TR>
234               <TD vAlign="top" width="28%">
235                  <P>v.transform_primary(F1, F2)</P>
236               </TD>
237               <TD vAlign="top" width="28%">
238                  <P>X::string_type</P>
239               </TD>
240               <TD vAlign="top" width="45%">
241                  <P>Returns a sort key for the character sequence designated by the iterator range
242                     [F1, F2) such that if the character sequence [G1, G2) sorts before the
243                     character sequence [H1, H2) when character case is not considered then
244                     v.transform_primary(G1, G2) &lt; v.transform_- primary(H1, H2).</P>
245               </TD>
246            </TR>
247            <TR>
248               <TD vAlign="top" width="28%">
249                  <P>v.lookup_classname(F1, F2)</P>
250               </TD>
251               <TD vAlign="top" width="28%">
252                  <P>X::char_class_type</P>
253               </TD>
254               <TD vAlign="top" width="45%">
255                  <P>Converts the character sequence designated by the iterator range [F1,F2) into a
256                     bitmask type that can subsequently be passed to isctype. Values returned from
257                     lookup_classname can be safely bitwise or'ed together. Returns 0 if the
258                     character sequence is not the name of a character class recognized by X. The
259                     value returned shall be independent of the case of the characters in the
260                     sequence.</P>
261               </TD>
262            </TR>
263            <TR>
264               <TD vAlign="top" width="28%">
265                  <P>v.lookup_collatename(F1, F2)</P>
266               </TD>
267               <TD vAlign="top" width="28%">
268                  <P>X::string_type</P>
269               </TD>
270               <TD vAlign="top" width="45%">
271                  <P>Returns a sequence of characters that represents the collating element
272                     consisting of the character sequence designated by the iterator range [F1, F2).
273                     Returns an empty string if the character sequence is not a valid collating
274                     element.</P>
275               </TD>
276            </TR>
277            <TR>
278               <TD vAlign="top" width="28%">
279                  <P>v.isctype(c, v.lookup_classname (F1, F2))</P>
280               </TD>
281               <TD vAlign="top" width="28%">
282                  <P>bool</P>
283               </TD>
284               <TD vAlign="top" width="45%">
285                  <P>Returns true if character c is a member of the character class designated by
286                     the iterator range [F1, F2), false otherwise.</P>
287               </TD>
288            </TR>
289            <TR>
290               <TD vAlign="top" width="28%">
291                  <P>v.value(c, i)</P>
292               </TD>
293               <TD vAlign="top" width="28%">
294                  <P>int</P>
295               </TD>
296               <TD vAlign="top" width="45%">
297                  <P>Returns the value represented by the digit c in base I if the character c is a
298                     valid digit in base I; otherwise returns -1. [Note: the value of I will only be
299                     8, 10, or 16. -end note]</P>
300               </TD>
301            </TR>
302            <TR>
303               <TD vAlign="top" width="28%">
304                  <P>u.imbue(loc)</P>
305               </TD>
306               <TD vAlign="top" width="28%">
307                  <P>X::locale_type</P>
308               </TD>
309               <TD vAlign="top" width="45%">
310                  <P>Imbues <CODE>u</CODE> with the locale <CODE>loc</CODE>, returns the previous
311                     locale used by u if any.&nbsp;</P>
312               </TD>
313            </TR>
314            <TR>
315               <TD vAlign="top" width="28%">
316                  <P>v.getloc()</P>
317               </TD>
318               <TD vAlign="top" width="28%">
319                  <P>X::locale_type</P>
320               </TD>
321               <TD vAlign="top" width="45%">
322                  <P>Returns the current locale used by <CODE>v</CODE> if any.&nbsp;</P>
323               </TD>
324            </TR>
325            <TR>
326               <TD vAlign="top" width="28%">
327                  <P>v.error_string(i)</P>
328               </TD>
329               <TD vAlign="top" width="28%">
330                  <P>std::string</P>
331               </TD>
332               <TD vAlign="top" width="45%">
333                  <P>Returns a human readable error string for the error condition <CODE>i</CODE>,
334                     where <CODE>i</CODE> is one of the values enumerated by type <CODE>regex_constants::error_type</CODE>.&nbsp; 
335                     If the value <CODE>i</CODE> is not recognized then returns the string "Unknown
336                     error" or a localized equivalent.</P>
337               </TD>
338            </TR>
339         </TABLE>
340      </P>
341      <H4>Additional Optional Requirements</H4>
342      <P>The following additional requirements are strictly optional, however in order
343         for basic_regex to take advantage of these additional interfaces, all of the
344         following requirements must be met; basic_regex will detect the presence or
345         absense of member <EM>boost_extensions_tag </EM>and configure itself
346         appropriately.</P>
347      <P>
348         <TABLE id="Table4" cellSpacing="1" cellPadding="1" width="100%" border="1">
349            <TR>
350               <TD><STRONG>Expression</STRONG></TD>
351               <TD width="231"><STRONG>Result</STRONG></TD>
352               <TD>
353                  <P><STRONG>Assertion / Note
354                        <BR>
355                        Pre / Post condition</STRONG></P>
356               </TD>
357            </TR>
358            <TR>
359               <TD>X::boost_extensions_tag</TD>
360               <TD width="231">An unspecified type.</TD>
361               <TD>When present, all of the extensions listed in this table must be present.</TD>
362            </TR>
363            <TR>
364               <TD>
365                  <P>v.syntax_type(c)</P>
366               </TD>
367               <TD width="231"><A href="../../../boost/regex/v4/syntax_type.hpp">regex_constants::syntax_type</A></TD>
368               <TD>
369                  <P>Returns a symbolic value of type <CODE>regex_constants::syntax_type </CODE>that
370                     signifies the meaning of character <CODE>c</CODE> within the regular expression
371                     grammar.</P>
372               </TD>
373            </TR>
374            <TR>
375               <TD>v.escape_syntax_type(c)</TD>
376               <TD width="231"><A href="../../../boost/regex/v4/syntax_type.hpp">regex_constants::escape_syntax_type</A></TD>
377               <TD>
378                  <P>Returns a symbolic value of type <CODE>regex_constants::escape_syntax_type</CODE>,
379                     that signifies the meaning of character <CODE>c</CODE>&nbsp;within the regular
380                     expression grammar, when <CODE>c</CODE> has been preceded by an escape
381                     character. Precondition: if <CODE>b</CODE> is the character preceding <CODE>c</CODE>
382                     in the expression being parsed then: <CODE>v.syntax_type(b) == syntax_escape</CODE></P>
383               </TD>
384            </TR>
385            <TR>
386               <TD>
387                  <P>v.translate(c, b)</P>
388               </TD>
389               <TD width="231">X::char_type</TD>
390               <TD>
391                  <P>Returns a character <CODE>d</CODE> such that: for any character <CODE>d</CODE> that
392                     is to be considered equivalent to <CODE>c</CODE>&nbsp;then <CODE>v.translate(c,false)==v.translate(d,false)</CODE>.
393                     Likewise for all characters <CODE>C</CODE> that are to be considered equivalent
394                     to <CODE>c</CODE> when comparisons are to be performed without regard to case,
395                     then <CODE>v.translate(c,true)==v.translate(C,true)</CODE>.</P>
396               </TD>
397            </TR>
398            <TR>
399               <TD>
400                  <P>v.toi(I1, I2, i)</P>
401               </TD>
402               <TD width="231">An integer type capable of holding either a charT or an int.</TD>
403               <TD>
404                  <P>Behaves as follows: if <CODE>p==q</CODE> or if <CODE>*p </CODE>is not a digit
405                     character then returns -1. Otherwise performs formatted numeric input on the
406                     sequence [p,q) and returns the result as an int. Postcondition: either <CODE>p ==
407                        q</CODE> or <CODE>*p</CODE> is a non-digit character.</P>
408               </TD>
409            </TR>
410            <TR>
411               <TD>
412                  <P>v.error_string(i)</P>
413               </TD>
414               <TD width="231">std::string</TD>
415               <TD>
416                  <P>Returns a human readable error string for the error condition <CODE>i</CODE>,
417                     where <CODE>i</CODE> is one of the values enumerated by type <CODE><A href="error_type.html">
418                           regex_constants::error_type</A></CODE>.&nbsp; If the value <CODE>i</CODE> 
419                     is not recognized then returns the string "Unknown error" or a localized
420                     equivalent.</P>
421               </TD>
422            </TR>
423            <TR>
424               <TD>v.tolower(c)</TD>
425               <TD width="231">X::char_type</TD>
426               <TD>Converts c to lower case, used for Perl-style \l and \L formating operations.</TD>
427            </TR>
428            <TR>
429               <TD>v.toupper(c)</TD>
430               <TD width="231">X::char_type</TD>
431               <TD>Converts c to upper case, used for Perl-style \u and \U formating operations.</TD>
432            </TR>
433         </TABLE>
434      </P>
435      <H3><A name="iterator"></A>Iterator Rrequirements</H3>
436      <P>
437      <P>The regular expression algorithms (and iterators) take all require a
438         Bidirectional-Iterator.</P>
439      <P>
440         <HR>
441      </P>
442      <P></P>
443      <p>Revised
444         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
445         24&nbsp;June 2004&nbsp; 
446         <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
447      <p><i>© Copyright John Maddock&nbsp;1998-
448            <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan -->  2004<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
449      <P><I>Use, modification and distribution are subject to the Boost Software License,
450            Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
451            or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
452   </body>
453</html>
Note: See TracBrowser for help on using the repository browser.