Drizzled Public API Documentation

dtcollation.h
00001 /* -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-
00002  *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
00003  *
00004  *  Copyright (C) 2008 Sun Microsystems, Inc.
00005  *
00006  *  This program is free software; you can redistribute it and/or modify
00007  *  it under the terms of the GNU General Public License as published by
00008  *  the Free Software Foundation; version 2 of the License.
00009  *
00010  *  This program is distributed in the hope that it will be useful,
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  *  GNU General Public License for more details.
00014  *
00015  *  You should have received a copy of the GNU General Public License
00016  *  along with this program; if not, write to the Free Software
00017  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00018  */
00019 
00020 #pragma once
00021 
00022 #include <drizzled/definitions.h>
00023 #include <drizzled/visibility.h>
00024 
00025 namespace drizzled
00026 {
00027 
00028 class Item;
00029 struct charset_info_st;
00030 
00031 class DRIZZLED_API DTCollation
00032 {
00033 public:
00034   const charset_info_st *collation;
00035   enum Derivation derivation;
00036 
00037   DRIZZLED_LOCAL DTCollation();
00038   DRIZZLED_LOCAL DTCollation(const charset_info_st * const collation_arg,
00039                              Derivation derivation_arg);
00040   void set(DTCollation &dt);
00041   void set(const charset_info_st * const collation_arg,
00042            Derivation derivation_arg);
00043   void set(const charset_info_st * const collation_arg);
00044   void set(Derivation derivation_arg);
00045   bool set(DTCollation &dt1, DTCollation &dt2, uint32_t flags= 0);
00046 
00083   DRIZZLED_LOCAL bool aggregate(DTCollation &dt, uint32_t flags= 0);
00084 
00085   DRIZZLED_LOCAL const char *derivation_name() const;
00086 
00087 };
00088 
00089 
00090 bool agg_item_collations(DTCollation &c, const char *name,
00091                          Item **items, uint32_t nitems,
00092                          uint32_t flags, int item_sep);
00093 bool agg_item_collations_for_comparison(DTCollation &c, const char *name,
00094                                         Item **items, uint32_t nitems,
00095                                         uint32_t flags);
00096 
00097 /*
00098 
00099  @note In Drizzle we have just one charset, so no conversion is required (though collation may).
00100 
00101   Collect arguments' character sets together.
00102 
00103   We allow to apply automatic character set conversion in some cases.
00104   The conditions when conversion is possible are:
00105   - arguments A and B have different charsets
00106   - A wins according to coercibility rules
00107     (i.e. a column is stronger than a string constant,
00108      an explicit COLLATE clause is stronger than a column)
00109   - character set of A is either superset for character set of B,
00110     or B is a string constant which can be converted into the
00111     character set of A without data loss.
00112 
00113   If all of the above is true, then it's possible to convert
00114   B into the character set of A, and then compare according
00115   to the collation of A.
00116 
00117   For functions with more than two arguments:
00118   @code
00119     collect(A,B,C) ::= collect(collect(A,B),C)
00120   @endcode
00121   Since this function calls Session::change_item_tree() on the passed Item **
00122   pointers, it is necessary to pass the original Item **'s, not copies.
00123   Otherwise their values will not be properly restored (see BUG#20769).
00124   If the items are not consecutive (eg. args[2] and args[5]), use the
00125   item_sep argument, ie.
00126   @code
00127     agg_item_charsets(coll, fname, &args[2], 2, flags, 3)
00128   @endcode
00129 */
00130 bool agg_item_charsets(DTCollation &c, const char *name,
00131                        Item **items, uint32_t nitems, uint32_t flags,
00132                        int item_sep);
00133 
00134 
00135 void my_coll_agg_error(DTCollation &c1, DTCollation &c2, const char *fname);
00136 void my_coll_agg_error(DTCollation &c1, DTCollation &c2, DTCollation &c3,
00137                        const char *fname);
00138 void my_coll_agg_error(Item** args, uint32_t count, const char *fname,
00139                        int item_sep);
00140 
00141 } /* namespace drizzled */
00142