ceph/src/boost/libs/regex/doc/concepts.qbk

   1 [/
   2   Copyright 2006-2007 John Maddock.
   3   Distributed under the Boost Software License, Version 1.0.
   4   (See accompanying file LICENSE_1_0.txt or copy at
   5   http://www.boost.org/LICENSE_1_0.txt).
   6 ]
   7
   8
   9 [section:concepts Concepts]
  10
  11 [section:charT_concept charT Requirements]
  12
  13 Type `charT` used a template argument to class template [basic_regex],
  14 must have a trivial default constructor, copy constructor,
  15 assignment operator, and destructor.  In addition the following requirements
  16 must be met for objects; /c/ of type `charT`, /c1/ and /c2/ of type `charT const`,
  17 and /i/ of type `int`:
  18
  19 [table
  20 [[Expression]   [Return type]   [Assertion / Note / Pre- / Post-condition]]
  21 [[charT c]      [charT]         [Default constructor (must be trivial).]]
  22 [[charT c(c1)]  [charT]         [Copy constructor (must be trivial).]]
  23 [[c1 = c2]      [charT]         [Assignment operator (must be trivial).]]
  24 [[c1 == c2]     [bool]  [true if c1 has the same value as c2.]]
  25 [[c1 != c2]     [bool]  [true if c1 and c2 are not equal.]]
  26 [[c1 < c2]     [bool]   [true if the value of c1 is less than c2.]]
  27 [[c1 > c2]      [bool]  [true if the value of c1 is greater than c2.]]
  28 [[c1 <= c2]     [bool]  [true if c1 is less than or equal to c2.]]
  29 [[c1 >= c2]     [bool]  [true if c1 is greater than or equal to c2.]]
  30 [[intmax_t i = c1]      [int    ] [charT must be convertible to an integral type.
  31
  32 Note: type charT is not required to support this operation, if the traits class used supports the full Boost-specific interface, rather than the minimal standardised-interface (see traits class requirements below).]]
  33 [[charT c(i);]  [charT]         [charT must be constructable from an integral type.]]
  34 ]
  35
  36 [endsect]
  37
  38 [section:traits_concept Traits Class Requirements]
  39
  40 There are two sets of requirements for the `traits` template argument to
  41 [basic_regex]: a minimal interface (which is part of the regex standardization proposal),
  42 and an optional Boost-specific enhanced interface.
  43
  44 [h4 Minimal requirements.]
  45
  46 In the following table `X` denotes a traits class defining types and functions for
  47 the character container type `charT`; /u/ is an object of type `X`; /v/ is
  48 an object of type `const X`; /p/ is a value of type `const charT*`;
  49 /I1/ and /I2/ are Input Iterators; /c/ is a value of type `const charT`;
  50 /s/ is an object of type `X::string_type`; /cs/ is an object of type
  51 `const X::string_type`; /b/ is a value of type `bool`; /I/ is a value of
  52 type `int`; /F1/ and /F2/ are values of type `const charT*`; and /loc/ is
  53 an object of type `X::locale_type`.
  54
  55 [table
  56 [[Expression][Return type][Assertion / Note Pre / Post condition]]
  57 [[X::char_type][charT][The character container type used in the implementation of class template basic_regex.]]
  58 [[X::size_type][][An unsigned integer type, capable of holding the length of a null-terminated string of charT's.]]
  59 [[X::string_type][std::basic_string<charT> or std::vector<charT>][]]
  60 [[X::locale_type][Implementation defined][A copy constructible type that represents the locale used by the traits class.]]
  61 [[X::char_class_type]
  62    [Implementation defined]
  63    [A bitmask type representing a particular character classification. Multiple values of this type can be bitwise-or'ed together to obtain a new valid value.]]
  64 [[X::length(p)][X::size_type][Yields the smallest i such that p\[i\] == 0. Complexity is linear in i.]]
  65 [[v.translate(c)]
  66    [X::char_type]
  67    [Returns a character such that for any character d that is to be considered equivalent to c then v.translate(c) == v.translate(d).]]
  68 [[v.translate_nocase(c)]
  69    [X::char_type]
  70    [For all characters C that are to be considered equivalent to c when comparisons are to be performed without regard to case, then v.translate_nocase(c) == v.translate_nocase(C).]]
  71 [[v.transform(F1, F2)]
  72    [X::string_type]
  73    [Returns a sort key for the character sequence designated by the iterator range \[F1, F2) such that if
  74    the character sequence \[G1, G2) sorts before the character sequence \[H1, H2) then
  75    v.transform(G1, G2) < v.transform(H1, H2). ]]
  76 [[v.transform_primary(F1, F2)]
  77    [X::string_type]
  78    [Returns a sort key for the character sequence designated by the iterator range \[F1, F2) such that if the
  79    character sequence \[G1, G2) sorts before the character sequence \[H1, H2) when character case is not considered
  80    then v.transform_primary(G1, G2) < v.transform_primary(H1, H2).]]
  81 [[v.lookup_classname(F1, F2)]
  82    [X::char_class_type]
  83    [Converts the character sequence designated by the iterator range \[F1,F2) into a bitmask type that can subsequently
  84    be passed to isctype. Values returned from lookup_classname can be safely bitwise or'ed together. Returns 0 if the
  85    character sequence is not the name of a character class recognized by X. The value returned shall be independent
  86    of the case of the characters in the sequence.]]
  87 [[v.lookup_collatename(F1, F2)]
  88    [X::string_type]
  89    [Returns a sequence of characters that represents the collating element consisting of the character sequence designated
  90    by the iterator range \[F1, F2). Returns an empty string if the character sequence is not a valid collating element.]]
  91 [[v.isctype(c, v.lookup_classname (F1, F2))][bool][Returns true if character c is a member of the character class designated by the iterator range \[F1, F2), false otherwise.]]
  92 [[v.value(c, I)]
  93    [int]
  94    [Returns the value represented by the digit c in base I if the character c is a valid digit in base I; otherwise returns -1. \[Note: the value of I will only be 8, 10, or 16. -end note\]]]
  95 [[u.imbue(loc)][X::locale_type][Imbues u with the locale loc, returns the previous locale used by u if any. ]]
  96 [[v.getloc()][X::locale_type][Returns the current locale used by v if any. ]]
  97 ]
  98
  99 [h4 Additional Optional Requirements]
 100
 101 The following additional requirements are strictly optional,
 102 however in order for [basic_regex] to take advantage of these additional
 103 interfaces, all of the following requirements must be met; [basic_regex]
 104 will detect the presence or absence of the member `boost_extensions_tag` and
 105 configure itself appropriately.
 106
 107
 108 [table
 109 [[Expression][Result][Assertion / Note Pre / Post condition]]
 110 [[X::boost_extensions_tag][An unspecified type.][When present, all of the extensions listed in this table must be present.]]
 111 [[v.syntax_type(c)][regex_constants::syntax_type][Returns a symbolic value of type regex_constants::syntax_type that signifies the meaning of character c within the regular expression grammar.]]
 112 [[v.escape_syntax_type(c)][regex_constants::escape_syntax_type][Returns a symbolic value of type regex_constants::escape_syntax_type, that signifies the meaning of character c within the regular expression grammar, when c has been preceded by an escape character. Precondition: if b is the character preceding c in the expression being parsed then: `v.syntax_type(b) == syntax_escape`]]
 113 [[v.translate(c, b)][X::char_type][Returns a character d such that: for any character d that is to be considered equivalent to c then `v.translate(c,false)==v.translate(d,false)`. Likewise for all characters C that are to be considered equivalent to c when comparisons are to be performed without regard to case, then `v.translate(c,true)==v.translate(C,true)`.]]
 114 [[v.toi(I1, I2, i)][An integer type capable of holding either a charT or an int.][Behaves as follows: if `p == q` or if `*p` is not a digit character then returns -1. Otherwise performs formatted numeric input on the sequence \[p,q) and returns the result as an int. Postcondition: either p == q or *p is a non-digit character.]]
 115 [[v.error_string(I)][std::string][Returns a human readable error string for the error condition i, where i is one of the values enumerated by type regex_constants::error_type.  If the value /I/ is not recognized then returns the string "Unknown error" or a localized equivalent.]]
 116 [[v.tolower(c)][X::char_type][Converts c to lower case, used for Perl-style \l and \L formatting operations.]]
 117 [[v.toupper(c)][X::char_type][Converts c to upper case, used for Perl-style \u and \U formatting operations.]]
 118 ]
 119
 120 [endsect]
 121
 122 [section:iterator_concepts Iterator Requirements]
 123
 124 The regular expression algorithms (and iterators) take all require a
 125 Bidirectional-Iterator.
 126
 127 [endsect]
 128
 129 [endsect]
 130
 131