KDb

KDbFieldList.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2010 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_FIELDLIST_H
21 #define KDB_FIELDLIST_H
22 
23 #include <QList>
24 #include <QHash>
25 
26 #include "KDbGlobal.h"
27 #include "KDbField.h"
28 #include "KDbEscapedString.h"
29 
30 class KDbConnection;
31 
32 /*! Helper class that stores list of fields. */
33 class KDB_EXPORT KDbFieldList
34 {
35 public:
36  /*! Creates empty list of fields. If @a owner is true, the list will be
37  owner of any added field, what means that these field
38  will be removed on the list destruction. Otherwise, the list
39  just points any field that was added.
40  @see isOwner()
41  */
42  explicit KDbFieldList(bool owner = false);
43 
44  /*! Copy constructor.
45  If @a deepCopyFields is true, all fields are deeply copied, else only pointer are copied.
46  Reimplemented in KDbQuerySchema constructor. */
47  explicit KDbFieldList(const KDbFieldList& fl, bool deepCopyFields = true);
48 
49  /*! Destroys the list. If the list owns fields (see constructor),
50  these are also deleted. */
51  virtual ~KDbFieldList();
52 
53  /*! @return number of fields in the list. */
54  int fieldCount() const;
55 
56  /*! @return true if the list is empty. */
57  bool isEmpty() const;
58 
59  /*! Adds @a field at the and of field list. */
60  bool addField(KDbField *field);
61 
62  /*! Inserts @a field into a specified @a index position.
63 
64  @c false is returned if @a field is @c nullptr or @a index is invalid.
65 
66  Note: You can reimplement this method but you should still call
67  this implementation in your subclass. */
68  virtual bool insertField(int index, KDbField *field);
69 
70  /*! Removes field from the field list and deletes it. Use with care.
71 
72  Note: You can reimplement this method but you should still call
73  this implementation in your subclass.
74  @return false if this field does not belong to this list. */
75  virtual bool removeField(KDbField *field);
76 
77  /*! Moves fiels @a field from its current position to new position @a newIndex.
78  If @a newIndex value is greater than fieldCount()-1, it is appended.
79  @return @c false if this field does not belong to this list or is @c nullptr. */
80  virtual bool moveField(KDbField *field, int newIndex);
81 
82  /*! @return field id or @c nullptr if there is no such a field. */
83  virtual KDbField* field(int id);
84 
85  /*! @overload KDbField* field(int id) */
86  virtual const KDbField* field(int id) const;
87 
88  /*! @return field with name @a name or @c nullptr if there is no such a field. */
89  virtual KDbField* field(const QString& name);
90 
91  /*! @overload . DbField* field(const QString& name) const */
92  virtual const KDbField* field(const QString& name) const;
93 
94  /*! @return true if this list contains given @a field. */
95  bool hasField(const KDbField& field) const;
96 
97  /*! @return first occurrence of @a field in the list
98  or -1 if this list does not contain this field. */
99  int indexOf(const KDbField& field) const;
100 
101  /*! @return list of field names for this list. */
102  QStringList names() const;
103 
104  //! @return iterator for fields
105  KDbField::ListIterator fieldsIterator() const;
106 
107  //! @return iterator for fields
108  KDbField::ListIterator fieldsIteratorConstEnd() const;
109 
110  //! @return list of fields
111  KDbField::List *fields();
112 
113  //! @overload
114  const KDbField::List* fields() const;
115 
116  /*! @return list of autoincremented fields. The list is owned by this KDbFieldList object. */
117  KDbField::List* autoIncrementFields() const;
118 
119  /*! @return true if fields in the list are owned by this list. */
120  bool isOwner() const;
121 
122  /*! Removes all fields from the list. */
123  virtual void clear();
124 
125  /*! Creates and returns a list that contain fields selected by name.
126  At least one field (exising on this list) should be selected, otherwise 0 is
127  returned. Returned KDbFieldList object is not owned by any parent (so you need
128  to destroy yourself) and KDbField objects included in it are not owned by it
129  (but still as before, by 'this' object).
130  Returned list can be usable e.g. as argument for KDbConnection::insertRecord().
131  0 is returned if at least one name cannot be found.
132  */
133  Q_REQUIRED_RESULT KDbFieldList *subList(const QString& n1, const QString& n2 = QString(),
134  const QString& n3 = QString(), const QString& n4 = QString(),
135  const QString& n5 = QString(), const QString& n6 = QString(),
136  const QString& n7 = QString(), const QString& n8 = QString(),
137  const QString& n9 = QString(), const QString& n10 = QString(),
138  const QString& n11 = QString(), const QString& n12 = QString(),
139  const QString& n13 = QString(), const QString& n14 = QString(),
140  const QString& n15 = QString(), const QString& n16 = QString(),
141  const QString& n17 = QString(), const QString& n18 = QString()
142  );
143 
144  /*! Like above, but for QStringList. */
145  Q_REQUIRED_RESULT KDbFieldList *subList(const QStringList &list);
146 
147  /*! @overload subList(const QStringList&) */
148  Q_REQUIRED_RESULT KDbFieldList *subList(const QList<QByteArray> &list);
149 
150  /*! Like above, but with a list of field indices */
151  Q_REQUIRED_RESULT KDbFieldList *subList(const QList<int> &list);
152 
153  /*! @return a string that is a result of all field names concatenated
154  and with @a separator. This is usable e.g. as argument like "field1,field2"
155  for "INSERT INTO (xxx) ..". The result of this method is effectively cached,
156  and it is invalidated when set of fields changes (e.g. using clear()
157  or addField()).
158 
159  @a tableOrAlias, if provided is prepended to each field, so the resulting
160  names will be in form tableOrAlias.fieldName. This option is used for building
161  queries with joins, where fields have to be spicified without ambiguity.
162  See @ref KDbConnection::selectStatement() for example use.
163 
164  @a escapingType can be used to alter default escaping type.
165  If @a conn is not provided for DriverEscaping, no escaping is performed.
166  */
167  KDbEscapedString sqlFieldsList(KDbConnection *conn, const QString& separator = QLatin1String(","),
168  const QString& tableOrAlias = QString(),
169  KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
170 
171  /*! Like above, but this is convenient static function, so you can pass any @a list here. */
172  static KDbEscapedString sqlFieldsList(const KDbField::List& list, KDbConnection *conn,
173  const QString& separator = QLatin1String(","),
174  const QString& tableOrAlias = QString(),
176 
177  /*! Renames field @a oldName to @a newName.
178 
179  @c false is returned if field with @a oldName name does not exist or field with @a newName name
180  already exists.
181 
182  @note Do not use this for physical renaming columns. Use KDbAlterTableHandler instead.
183  */
184  bool renameField(const QString& oldName, const QString& newName);
185 
186  //! @overload
187  bool renameField(KDbField *field, const QString& newName);
188 
189 private:
190  class Private;
191  Private * const d;
192 };
193 
194 //! Sends information about field list @a list to debug output @a dbg.
195 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbFieldList& list);
196 
197 #endif
Specialized string for escaping.
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
@ DriverEscaping
Identifiers are escaped by driver.
Definition: KDbGlobal.h:145
QList< KDbField * >::ConstIterator ListIterator
iterator for list of fields
Definition: KDbField.h:79
Meta-data for a field.
Definition: KDbField.h:71
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
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.