KDb

KDbOrderByColumn.h
1/* This file is part of the KDE project
2 Copyright (C) 2003-2018 Jarosław Staniek <staniek@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KDB_ORDERBYCOLUMN_H
21#define KDB_ORDERBYCOLUMN_H
22
23#include "KDbEscapedString.h"
24#include "KDbGlobal.h"
25
26class KDbConnection;
27class KDbField;
29class KDbQuerySchema;
30
31//! @short KDbOrderByColumn provides information about a single query column used for sorting
32/*! The column can be expression or table field. */
33class KDB_EXPORT KDbOrderByColumn
34{
35public:
36 //! Column sort order
37 //! @since 3.1
38 enum class SortOrder {
39 Ascending = Qt::AscendingOrder,
40 Descending = Qt::DescendingOrder
41 };
42
43 //! Creates an empty information about a single query column.
45
46 //! Creates a copy of the @a other
47 //! @since 3.1
49
50 //! Creates information about a single query column @a column used for sorting.
51 explicit KDbOrderByColumn(KDbQueryColumnInfo* column,
52 SortOrder order = SortOrder::Ascending, int pos = -1);
53
54 //! Like above but used when the field @a field is not present on the list of columns.
55 //! (e.g. SELECT a FROM t ORDER BY b; where T is a table with fields (a,b)).
56 explicit KDbOrderByColumn(KDbField* field, SortOrder order = SortOrder::Ascending);
57
59
60 /*! @return copy of this KDbOrderByColumn object.
61 @a fromQuery and @a toQuery is needed if column() is assigned to this info.
62 Then, column info within @a toQuery will be assigned to the new KDbOrderByColumn object,
63 corresponding to column() from "this" KDbOrderByColumn object. */
64 Q_REQUIRED_RESULT KDbOrderByColumn *copy(KDbConnection *conn, KDbQuerySchema *fromQuery,
65 KDbQuerySchema *toQuery) const;
66
67 //! A column to sort.
68 KDbQueryColumnInfo* column() const;
69
70 /*! A helper for column() that allows you to know that sorting column
71 was defined by providing its position. -1 by default.
72 Example query: SELECT a, b FROM T ORDER BY 2 */
73 int position() const;
74
75 //! A field to sort, used only in case when the second constructor was used.
76 KDbField *field() const;
77
78 //! @return sort order for the column
79 KDbOrderByColumn::SortOrder sortOrder() const;
80
81 //! Assigns @a other to this object returns a reference to this object.
82 //! @since 3.1
83 KDbOrderByColumn& operator=(const KDbOrderByColumn &other);
84
85 //! @return true if this column is the same as @a col
86 bool operator==(const KDbOrderByColumn& col) const;
87
88 //! @return @c true if this object is not equal to @a other; otherwise returns @c false.
89 //! @since 3.1
90 inline bool operator!=(const KDbOrderByColumn &other) const { return !operator==(other); }
91
92 /** Return an SQL string like "name ASC" or "2 DESC" usable for building an SQL statement
93 *
94 * If @a includeTableNames is @c true fields that are related to a table are
95 * printed as "tablename.fieldname".
96 *
97 * @a escapingType can be used to alter default escaping type.
98 * If @a conn is not provided for DriverEscaping, no escaping is performed.
99 * If @a query is provided, it can be used to obtain alias information.
100 *
101 * @since 3.2
102 */
103 KDbEscapedString toSqlString(bool includeTableName,
104 KDbConnection *conn, KDbQuerySchema *query,
106
107 /*! @overload
108
109 @deprecated since 3.2, use overload that also takes query schema
110 */
111 KDB_DEPRECATED KDbEscapedString toSqlString(bool includeTableName = true,
112 KDbConnection *conn = nullptr,
114
115 //! Converts @a order to Qt::SortOrder type
116 inline static Qt::SortOrder toQt(SortOrder order) { return static_cast<Qt::SortOrder>(order); }
117
118 //! Converts @a order to SortOrder type
119 inline static SortOrder fromQt(Qt::SortOrder order) { return static_cast<SortOrder>(order); }
120
121private:
122 class Private;
123 Private * const d;
124};
125
126//! @short KDbOrderByColumnList provides list of sorted columns for a query schema
127class KDB_EXPORT KDbOrderByColumnList
128{
129public:
130 /*! Constructs empty list of ordered columns. */
132
133 /*! A copy constructor. */
135 KDbQuerySchema* fromQuery, KDbQuerySchema* toQuery);
136
138
139 //! @return @c true if this object is equal to @a other; otherwise returns @c false.
140 //! @since 3.1
141 bool operator==(const KDbOrderByColumnList &other) const;
142
143 //! @return @c true if this object is not equal to @a other; otherwise returns @c false.
144 //! @since 3.1
145 inline bool operator!=(const KDbOrderByColumnList &other) const { return !operator==(other); }
146
147 //! Returns column with given index.
148 //! @since 3.1
149 const KDbOrderByColumn* value(int index) const;
150
151 //! @overload
152 KDbOrderByColumn* value(int index);
153
154 /*! Appends multiple fields for sorting. @a querySchema
155 is used to find appropriate field or alias name.
156 @return false if there is at least one name for which a field or alias name does not exist
157 (all the newly appended fields are removed in this case)
158 Returns @c false if @a querySchema is @c nullptr. */
159 bool appendFields(KDbConnection *conn, KDbQuerySchema* querySchema,
160 const QString& field1, KDbOrderByColumn::SortOrder order1 = KDbOrderByColumn::SortOrder::Ascending,
161 const QString& field2 = QString(), KDbOrderByColumn::SortOrder order2 = KDbOrderByColumn::SortOrder::Ascending,
162 const QString& field3 = QString(), KDbOrderByColumn::SortOrder order3 = KDbOrderByColumn::SortOrder::Ascending,
163 const QString& field4 = QString(), KDbOrderByColumn::SortOrder order4 = KDbOrderByColumn::SortOrder::Ascending,
164 const QString& field5 = QString(), KDbOrderByColumn::SortOrder order5 = KDbOrderByColumn::SortOrder::Ascending);
165
166 /*! Appends column @a columnInfo.
167 Does nothing if @a columnInfo is @c nullptr. */
168 void appendColumn(KDbQueryColumnInfo* columnInfo,
169 KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);
170
171 /*! Appends a field @a field.
172 Read documentation of @ref KDbOrderByColumn(KDbField* field, SortOrder order)
173 for more info.
174 Does nothing if @a field is @c nullptr. */
175 void appendField(KDbField* field,
176 KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);
177
178 /*! Appends field with a name @a field.
179 @return @c true on successful appending, and @c false if there is no such field or alias
180 name in the @a querySchema.
181 Returns @c false if @a querySchema is @c nullptr. */
182 bool appendField(KDbConnection *conn, KDbQuerySchema* querySchema, const QString& fieldName,
183 KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);
184
185 /*! Appends a column that is at position @a pos (counted from 0).
186 @return true on successful adding and false if there is no such position @a pos.
187 Returns @c false if @a querySchema is @c nullptr. */
188 bool appendColumn(KDbConnection *conn, KDbQuerySchema* querySchema,
189 KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending,
190 int pos = -1);
191
192 /*! @return true if the list is empty. */
193 bool isEmpty() const;
194
195 /*! @return number of elements of the list. */
196 int count() const;
197
198 /*! Removes all elements from the list (deletes them). */
199 void clear();
200
201 /*! Returns an STL-style iterator pointing to the first column in the list. */
203
204 /*! Returns an STL-style iterator pointing to the imaginary item after the last column
205 * in the list.
206 */
208
209 /*! Returns an const STL-style iterator pointing to the first column in the list. */
211
212 /*! Returns a const STL-style iterator pointing to the imaginary item after the last column
213 * in the list.
214 */
216
217 /** Return an SQL string like "name ASC, 2 DESC" usable for building an SQL statement
218 *
219 * If @a includeTableNames is @c true (the default) fields that are related to a table are
220 * printed as "tablename.fieldname".
221 *
222 * @a escapingType can be used to alter default escaping type.
223 * If @a conn is not provided for DriverEscaping, no escaping is performed.
224 * If @a query is provided, it can be used to obtain alias information.
225 *
226 * @since 3.2
227 */
228 KDbEscapedString toSqlString(bool includeTableNames,
229 KDbConnection *conn, KDbQuerySchema *query,
231
232 /*! @overload
233
234 @deprecated since 3.2, use overload that also takes query schema
235 */
236 KDB_DEPRECATED KDbEscapedString toSqlString(bool includeTableNames = true,
237 KDbConnection *conn = nullptr,
239
240private:
241 class Private;
242 Private * const d;
243 Q_DISABLE_COPY(KDbOrderByColumnList)
244};
245
246//! Sends order-by-column information @a order to debug output @a dbg.
247KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumn& order);
248
249//! Sends order-by-column-list information @a list to debug output @a dbg.
250KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumnList& list);
251
252#endif
Provides database connection, allowing queries and data modification.
Specialized string for escaping.
Meta-data for a field.
Definition KDbField.h:72
KDbOrderByColumnList provides list of sorted columns for a query schema.
bool operator!=(const KDbOrderByColumnList &other) const
KDbOrderByColumn provides information about a single query column used for sorting.
SortOrder
Column sort order.
static Qt::SortOrder toQt(SortOrder order)
Converts order to Qt::SortOrder type.
bool operator!=(const KDbOrderByColumn &other) const
static SortOrder fromQt(Qt::SortOrder order)
Converts order to SortOrder type.
Helper class that assigns additional information for the column in a query.
KDbQuerySchema provides information about database query.
IdentifierEscapingType
Escaping type for identifiers.
Definition KDbGlobal.h:144
@ DriverEscaping
Identifiers are escaped by driver.
Definition KDbGlobal.h:145
QDebug operator<<(QDebug dbg, const PerceptualColor::LchaDouble &value)
AscendingOrder
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.