1 /********************************************************************\ 2 * qofquerycore.h -- API for providing core Query data types * 3 * Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU> * 4 * * 5 * This program is free software; you can redistribute it and/or * 6 * modify it under the terms of the GNU General Public License as * 7 * published by the Free Software Foundation; either version 2 of * 8 * the License, or (at your option) any later version. * 9 * * 10 * This program is distributed in the hope that it will be useful, * 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 13 * GNU General Public License for more details. * 14 * * 15 * You should have received a copy of the GNU General Public License* 16 * along with this program; if not, contact: * 17 * * 18 * Free Software Foundation Voice: +1-617-542-5942 * 19 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 20 * Boston, MA 02110-1301, USA gnu@gnu.org * 21 * * 22 \********************************************************************/ 23 24 /** @addtogroup Query 25 @{ */ 26 27 /** @file qofquerycore.h 28 @brief API for providing core Query data types 29 @author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU> 30 */ 31 32 #ifndef QOF_QUERYCORE_H 33 #define QOF_QUERYCORE_H 34 35 #include "gnc-numeric.h" 36 #include "gnc-date.h" 37 #include "qofclass.h" 38 39 #ifdef __cplusplus 40 extern "C" 41 { 42 #endif 43 44 /** 45 * PREDICATE DATA TYPES: All the predicate data types are rolled up into 46 * the union type PredicateData. The "type" field specifies which type 47 * the union is. 48 */ 49 typedef struct _QofQueryPredData QofQueryPredData; 50 51 /** Standard Query comparators, for how to compare objects in a predicate. 52 * Note that not all core types implement all comparators 53 */ 54 typedef enum 55 { 56 QOF_COMPARE_LT = 1, 57 QOF_COMPARE_LTE, 58 QOF_COMPARE_EQUAL, 59 QOF_COMPARE_GT, 60 QOF_COMPARE_GTE, 61 QOF_COMPARE_NEQ, 62 QOF_COMPARE_CONTAINS, 63 QOF_COMPARE_NCONTAINS 64 } QofQueryCompare; 65 66 /** List of known core query data-types... 67 * Each core query type defines it's set of optional "comparator qualifiers". 68 */ 69 /* Comparisons for QOF_TYPE_STRING */ 70 typedef enum 71 { 72 QOF_STRING_MATCH_NORMAL = 1, 73 QOF_STRING_MATCH_CASEINSENSITIVE 74 } QofStringMatch; 75 76 /** Comparisons for QOF_TYPE_DATE 77 * The QOF_DATE_MATCH_DAY comparison rounds the two time 78 * values to mid-day and then compares these rounded values. 79 * The QOF_DATE_MATCH_NORMAL comparison matches the time values, 80 * down to the second. 81 */ 82 83 typedef enum 84 { 85 QOF_DATE_MATCH_NORMAL = 1, 86 QOF_DATE_MATCH_DAY 87 } QofDateMatch; 88 89 /** Comparisons for QOF_TYPE_NUMERIC, QOF_TYPE_DEBCRED 90 * 91 * XXX Should be deprecated, or at least wrapped up as a convenience 92 * function, this is based on the old bill gribble code, which assumed 93 * the amount was always positive, and then specified a funds-flow 94 * direction (credit, debit, or either). 95 * 96 * The point being that 'match credit' is equivalent to the compound 97 * predicate (amount >= 0) && (amount 'op' value) while the 'match 98 * debit' predicate is equivalent to (amount <= 0) && (abs(amount) 'op' value) 99 */ 100 101 typedef enum 102 { 103 QOF_NUMERIC_MATCH_DEBIT = 1, 104 QOF_NUMERIC_MATCH_CREDIT, 105 QOF_NUMERIC_MATCH_ANY 106 } QofNumericMatch; 107 108 /* Comparisons for QOF_TYPE_GUID */ 109 typedef enum 110 { 111 /** These expect a single object and expect the 112 * QofAccessFunc returns GncGUID* */ 113 QOF_GUID_MATCH_ANY = 1, 114 QOF_GUID_MATCH_NONE, 115 QOF_GUID_MATCH_NULL, 116 /** These expect a GList* of objects and calls the QofAccessFunc routine 117 * on each item in the list to obtain a GncGUID* for each object */ 118 QOF_GUID_MATCH_ALL, 119 /** These expect a single object and expect the QofAccessFunc function 120 * to return a GList* of GncGUID* (the list is the property of the caller) */ 121 QOF_GUID_MATCH_LIST_ANY, 122 } QofGuidMatch; 123 124 /** A CHAR type is for a RECNCell, Comparisons for QOF_TYPE_CHAR 125 * 'ANY' will match any character in the string. 126 * 127 * Match 'ANY' is a convenience/performance-enhanced predicate 128 * for the compound statement (value==char1) || (value==char2) || etc. 129 * Match 'NONE' is equivalent to 130 * (value != char1) && (value != char2) && etc. 131 */ 132 typedef enum 133 { 134 QOF_CHAR_MATCH_ANY = 1, 135 QOF_CHAR_MATCH_NONE 136 } QofCharMatch; 137 138 /** No extended comparisons for QOF_TYPE_INT32, QOF_TYPE_INT64, 139 * QOF_TYPE_DOUBLE, QOF_TYPE_BOOLEAN 140 */ 141 142 /** Head of Predicate Data structures. All PData must start like this. */ 143 struct _QofQueryPredData 144 { 145 QofType type_name; /* QOF_TYPE_* */ 146 QofQueryCompare how; 147 }; 148 149 /** A list of parameters (::QofIdType) used to describe a parameter to 150 * use in a predicate or when sorting */ 151 typedef GSList QofQueryParamList; 152 153 /** @name Core Data Type Predicates 154 @{ */ 155 QofQueryPredData *qof_query_string_predicate (QofQueryCompare how, 156 const gchar *str, 157 QofStringMatch options, 158 gboolean is_regex); 159 160 QofQueryPredData *qof_query_date_predicate (QofQueryCompare how, 161 QofDateMatch options, 162 time64 date); 163 164 QofQueryPredData *qof_query_numeric_predicate (QofQueryCompare how, 165 QofNumericMatch options, 166 gnc_numeric value); 167 168 QofQueryPredData *qof_query_guid_predicate (QofGuidMatch options, GList *guids); 169 QofQueryPredData *qof_query_int32_predicate (QofQueryCompare how, gint32 val); 170 QofQueryPredData *qof_query_int64_predicate (QofQueryCompare how, gint64 val); 171 QofQueryPredData *qof_query_double_predicate (QofQueryCompare how, double val); 172 QofQueryPredData *qof_query_boolean_predicate (QofQueryCompare how, gboolean val); 173 QofQueryPredData *qof_query_char_predicate (QofCharMatch options, 174 const gchar *chars); 175 QofQueryPredData *qof_query_collect_predicate (QofGuidMatch options, 176 QofCollection *coll); 177 QofQueryPredData *qof_query_choice_predicate (QofGuidMatch options, GList *guids); 178 179 /** Copy a predicate. */ 180 QofQueryPredData *qof_query_core_predicate_copy (const QofQueryPredData *pdata); 181 182 /** Destroy a predicate. */ 183 void qof_query_core_predicate_free (QofQueryPredData *pdata); 184 185 /** Retrieve a predicate. */ 186 gboolean qof_query_date_predicate_get_date (const QofQueryPredData *pd, time64 *date); 187 /** Return a printable string for a core data object. Caller needs 188 * to g_free() the returned string. 189 */ 190 char * qof_query_core_to_string (QofType, gpointer object, QofParam *getter); 191 192 /** Compare two parameter(strings) as if they are numbers! 193 * the two objects, a and b, are the objects being compared 194 * this_param is the QofParam for this parameter in the objects 195 */ 196 int qof_string_number_compare_func (gpointer a, gpointer b, gint options, 197 QofParam *this_param); 198 199 200 #ifdef __cplusplus 201 } 202 #endif 203 204 #endif /* QOF_QUERYCORE_H */ 205 /* @} */ 206 /* @} */ 207