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