KDb

KDbFieldList.h
1/* This file is part of the KDE project
2 Copyright (C) 2003-2010 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_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
30class KDbConnection;
31
32/*! Helper class that stores list of fields. */
33class KDB_EXPORT KDbFieldList
34{
35public:
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(),
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
189private:
190 class Private;
191 Private * const d;
192};
193
194//! Sends information about field list @a list to debug output @a dbg.
195KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbFieldList& list);
196
197#endif
Provides database connection, allowing queries and data modification.
Specialized string for escaping.
Meta-data for a field.
Definition KDbField.h:72
QList< KDbField * >::ConstIterator ListIterator
iterator for list of fields
Definition KDbField.h:79
IdentifierEscapingType
Escaping type for identifiers.
Definition KDbGlobal.h:144
@ DriverEscaping
Identifiers are escaped by driver.
Definition KDbGlobal.h:145
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.