ceph/src/boost/libs/locale/doc/collation.txt

   1 //
   2 //  Copyright (c) 2009-2011 Artyom Beilis (Tonkikh)
   3 //
   4 //  Distributed under the Boost Software License, Version 1.0. (See
   5 //  accompanying file LICENSE_1_0.txt or copy at
   6 //  http://www.boost.org/LICENSE_1_0.txt)
   7 //
   8
   9
  10 // vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen
  11 /*!
  12 \page collation Collation
  13
  14 Boost.Locale provides a \ref boost::locale::collator "collator" class, derived from \c std::collate, that adds support for
  15 primary, secondary, tertiary, quaternary and identical comparison levels. They can be approximately defined as:
  16
  17 -# Primary -- ignore accents and character case, comparing base letters only. For example "facade" and "Façade" are the same.
  18 -# Secondary -- ignore character case but consider accents. "facade" and "façade" are different but "Façade" and "façade" are the same.
  19 -# Tertiary -- consider both case and accents: "Façade" and "façade" are different. Ignore punctuation.
  20 -# Quaternary -- consider all case, accents, and punctuation. The words must be identical in terms of Unicode representation.
  21 -# Identical -- as quaternary, but compare code points as well.
  22
  23 There are two ways of using the \ref boost::locale::collator "collator" facet: directly, by calling its member functions \ref boost::locale::collator::compare() "compare", \ref boost::locale::collator::transform() "transform" and \ref
  24 boost::locale::collator::hash() "hash", or indirectly by using the \ref boost::locale::comparator "comparator" template
  25 class in STL algorithms.
  26
  27 For example:
  28
  29 \code
  30     wstring a=L"Façade", b=L"facade";
  31     bool eq = 0 == use_facet<collator<wchar_t> >(loc).compare(collator_base::secondary,a,b);
  32     wcout << a <<L" and "<<b<<L" are " << (eq ? L"identical" : L"different")<<endl;
  33 \endcode
  34
  35 \c std::locale is designed to be useful as a comparison class in STL collections and algorithms.
  36 To get similar functionality with comparison levels, you must use the comparator class.
  37
  38 \code
  39     std::map<std::string,std::string,comparator<char,collator_base::secondary> > strings;
  40     // Now strings uses the default system locale for string comparison
  41 \endcode
  42
  43 You can also set a specific locale or level when creating and using the \ref boost::locale::comparator "comparator" class:
  44
  45 \code
  46     comparator<char> comp(some_locale,some_level);
  47     std::map<std::string,std::string,comparator<char> > strings(comp);
  48 \endcode
  49
  50 */
  51
  52