KDb

KDbOrderByColumn.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2018 JarosÅ‚aw Staniek <[email protected]>
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 
26 class KDbConnection;
27 class KDbField;
28 class KDbQueryColumnInfo;
29 class KDbQuerySchema;
30 
31 //! @short KDbOrderByColumn provides information about a single query column used for sorting
32 /*! The column can be expression or table field. */
33 class KDB_EXPORT KDbOrderByColumn
34 {
35 public:
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
48  KDbOrderByColumn(const KDbOrderByColumn &other);
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,
105  KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
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,
113  KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
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 
121 private:
122  class Private;
123  Private * const d;
124 };
125 
126 //! @short KDbOrderByColumnList provides list of sorted columns for a query schema
127 class KDB_EXPORT KDbOrderByColumnList
128 {
129 public:
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. */
210  QList<KDbOrderByColumn*>::ConstIterator constBegin() const;
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,
230  KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
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,
238  KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
239 
240 private:
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.
247 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumn& order);
248 
249 //! Sends order-by-column-list information @a list to debug output @a dbg.
250 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumnList& list);
251 
252 #endif
KDbOrderByColumn provides information about a single query column used for sorting.
bool operator!=(const KDbOrderByColumn &other) const
Specialized string for escaping.
AscendingOrder
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
static Qt::SortOrder toQt(SortOrder order)
Converts order to Qt::SortOrder type.
@ DriverEscaping
Identifiers are escaped by driver.
Definition: KDbGlobal.h:145
static SortOrder fromQt(Qt::SortOrder order)
Converts order to SortOrder type.
bool operator!=(const KDbOrderByColumnList &other) const
KDbQuerySchema provides information about database query.
Meta-data for a field.
Definition: KDbField.h:71
SortOrder
Column sort order.
KDbOrderByColumnList provides list of sorted columns for a query schema.
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
Helper class that assigns additional information for the column in a query.
IdentifierEscapingType
Escaping type for identifiers.
Definition: KDbGlobal.h:144
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.