Standard C++ LibraryCopyright 1996, Rogue Wave Software, Inc.

NAME

  collate, collate_byname - String collation, comparison, and hashing facet.

SYNOPSIS

  #include <locale>
  template <class charT> class collate;
  template <class charT> class collate_byname;

DESCRIPTION

  The collate and collate_byname facets provides string collation,
  comparison, and hashing facilities.   collate provides these facilities for
  the "C" locale, while collate_byname provides the same thing for named
  locales.

INTERFACE

  template <class charT>
  class collate : public locale::facet {
  public:
   typedef charT               char_type;
   typedef basic_string<charT> string_type;
   explicit collate(size_t refs = 0);
   int compare(const charT*, const charT*,
               const charT*, const charT*) const;
   string_type transform(const charT*, const charT*) const;
   long hash(const charT*, const charT*) const;
   static locale::id id;
  protected:
    ~collate();  // virtual
   virtual int do_compare(const charT*, const charT*,
                          const charT*, const charT*) const;
   virtual string_type do_transform(const charT*, const charT*) const;
   virtual long do_hash (const charT*, const charT*) const;
  };

  template <class charT>
  class collate_byname : public collate<charT> {
  public:
   explicit collate_byname(const char*, size_t = 0);
  protected:
    ~collate_byname();  // virtual
   virtual int do_compare(const charT*, const charT*,
                          const charT*, const charT*) const;
   virtual string_type do_transform(const charT*, const charT*) const;
   virtual long do_hash(const charT*, const charT*) const;
  };

TYPES

  char_type
     Type of character the facet is instantiated on.

  string_type
     Type of character string returned by member functions.

CONSTRUCTORS AND DESTRUCTORS

  explicit collate(size_t refs = 0)
     Construct a collate facet.  If the refs argument is 0, destruction of
     the object is delegated to the locale, or locales, containing it. This
     allows the user to ignore lifetime management issues.  On the other had,
     if refs  is 1, the object must be explicitly deleted:  the locale will
     not do so.  In this case, the object can be maintained across the
     lifetime of multiple locales.

  explicit collate_byname(const char* name, size_t refs = 0);
     Construct a collate_byname facet.  Use the named locale specified by the
     name argument.  The refs argument serves the same purpose as it does for
     the collate constructor.

  ~collate();  // virtual and protected
  ~collate_byname();  // virtual and protected
     Destroy the facet

FACET ID

  static locale::id id;
     Unique identifier for this type of facet.

PUBLIC MEMBER FUNCTIONS

  The public members of the collate facet provide an interface to protected
  members.  Each public member xxx has a corresponding virtual protected
  member do_xxx.  All work is delagated to these protected members.   For
  instance, the long version of the public grouping function simply calls its
  protected cousin do_grouping.

  int
  compare(const charT* low1, const charT* high1,
         const charT* low2, const charT* high2) const;

  long
  hash(const charT* low, const charT* high) const;

  string_type
  transform(const charT* low, const charT* high) const;
     Each of these public member functions xxx simply call the corresponding
     protected do_xxx function.

PROTECTED MEMBER FUNCTIONS

  virtual int
  do_compare(const charT* low1, const charT* high1,
            const charT* low2, const charT* high2) const;
     Returns 1 if the character string represented by the range [low1,high1)
     is greater than the character string represented by the range
     [low2,high2), -1 if first string is less than the second, or 0 if the
     two are equal.  collate uses a lexicographical comparison.

  virtual long
  do_hash( const charT* low, const charT* high)
     Generate a has value from a string defined by the range of characters
     [low,high).  Given two strings that compare equal (i.e. do_compare
     returns 0), do_hash returns an integer value that is the same for both
     strings.  For differing strings the probability that the return value
     will be equal is approximately 1.0/numeric_limits<unsigned
     long>::max().

  virtual string_type
  do_transform(const charT* low, const charT* high) const;
     Returns a string that will yield the same result in a lexicographical
     comparison with another string returned from transform as does the
     do_compare function applied to the original strings.  In other words,
     the result of  applying a lexicographical comparison to two strings
     returned from transform will be the same as applying do_compare to the
     original strings passed to transform.

EXAMPLE

  //
  // collate.cpp
  //
  #include <iostream>

  int main ()
  {
   using namespace std;
   locale loc;
   string s1("blue");
   string s2("blues");
    // Get a reference to the collate<char> facet
   const collate<char>& co =
  #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<collate<char> >(loc);
  #else
       use_facet(loc,(collate<char>*)0);
  #endif
    // Compare two strings
   cout << co.compare(s1.begin(),s1.end(),
                      s2.begin(),s2.end()-1) << endl;
   cout << co.compare(s1.begin(),s1.end(),
                      s2.begin(),s2.end()) << endl;
    // Retrieve hash values for two strings
   cout << co.hash(s1.begin(),s1.end()) << endl;
   cout << co.hash(s2.begin(),s2.end()) << endl;
   return 0;
  }

SEE ALSO

  locale, facets, ctype

STANDARDS CONFORMANCE

  ANSI X3J16/ISO WG21 Joint C++ Committee



privacy and legal statement