1/* This file is part of the KDE libraries
2 Copyright (C) 2001 Carsten Pfeiffer <pfeiffer@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 KSORTABLELIST_H
21#define KSORTABLELIST_H
22
23#include <kdecore_export.h>
24
25#include <QtCore/QPair>
26#include <QtCore/QList>
27
28/**
29 * \class KSortableItem ksortablelist.h <KSortableItem>
30 *
31 * KSortableItem is a QPair that provides several operators
32 * for sorting.
33 * @see KSortableList
34 */
35template<typename T, typename Key = int> class KSortableItem : public QPair<Key,T>
36{
37public:
38 /**
39 * Creates a new KSortableItem with the given values.
40 * @param i the first value (the key)
41 * @param t the second value (the item)
42 */
43 KSortableItem( Key i, const T& t ) : QPair<Key, T>( i, t ) {}
44 /**
45 * Creates a new KSortableItem that copies another one.
46 * @param rhs the other item to copy
47 */
48 KSortableItem( const KSortableItem<T, Key> &rhs )
49 : QPair<Key,T>( rhs.first, rhs.second ) {}
50
51 /**
52 * Creates a new KSortableItem with uninitialized values.
53 */
54 KSortableItem() {}
55
56 /**
57 * Assignment operator, just copies the item.
58 */
59 KSortableItem<T, Key> &operator=( const KSortableItem<T, Key>& i ) {
60 this->first = i.first;
61 this->second = i.second;
62 return *this;
63 }
64
65 // operators for sorting
66 /**
67 * Compares the two items. This implementation only compares
68 * the first value.
69 */
70 bool operator> ( const KSortableItem<T, Key>& i2 ) const {
71 return (i2.first < this->first);
72 }
73 /**
74 * Compares the two items. This implementation only compares
75 * the first value.
76 */
77 bool operator< ( const KSortableItem<T, Key>& i2 ) const {
78 return (this->first < i2.first);
79 }
80 /**
81 * Compares the two items. This implementation only compares
82 * the first value.
83 */
84 bool operator>= ( const KSortableItem<T, Key>& i2 ) const {
85 return (this->first >= i2.first);
86 }
87 /**
88 * Compares the two items. This implementation only compares
89 * the first value.
90 */
91 bool operator<= ( const KSortableItem<T, Key>& i2 ) const {
92 return !(i2.first < this->first);
93 }
94 /**
95 * Compares the two items. This implementation only compares
96 * the first value.
97 */
98 bool operator== ( const KSortableItem<T, Key>& i2 ) const {
99 return (this->first == i2.first);
100 }
101 /**
102 * Compares the two items. This implementation only compares
103 * the first value.
104 */
105 bool operator!= ( const KSortableItem<T, Key>& i2 ) const {
106 return (this->first != i2.first);
107 }
108
109 /**
110 * @return the second value (the item)
111 */
112 T& value() { return this->second; }
113
114 /**
115 * @return the second value (the item)
116 */
117 const T& value() const { return this->second; }
118
119 /**
120 * @return the first value (the key)
121 * @deprecated use key()
122 */
123#ifndef KDE_NO_DEPRECATED
124 KDE_DEPRECATED Key index() const { return this->first; }
125#endif
126 /**
127 * @return the first value.
128 */
129 Key key() const { return this->first; }
130};
131
132
133/**
134 * \class KSortableList ksortablelist.h <KSortableList>
135 *
136 * KSortableList is a QList which associates a key with each item in the list.
137 * This key is used for sorting when calling sort().
138 *
139 * This allows to temporarily calculate a key and use it for sorting, without having
140 * to store that key in the items, or calculate that key many times for the same item
141 * during sorting if that calculation is expensive.
142 */
143template <typename T, typename Key = int>
144class KSortableList : public QList<KSortableItem<T, Key> >
145{
146public:
147 /**
148 * Insert a KSortableItem with the given values.
149 * @param i the first value
150 * @param t the second value
151 */
152 void insert( Key i, const T& t ) {
153 QList<KSortableItem<T, Key> >::append( KSortableItem<T, Key>( i, t ) );
154 }
155 // add more as you please...
156
157 /**
158 * Returns the first value of the KSortableItem at the given position.
159 * @return the first value of the KSortableItem
160 */
161 T& operator[]( Key i ) {
162 return QList<KSortableItem<T, Key> >::operator[]( i ).value();
163 }
164
165 /**
166 * Returns the first value of the KSortableItem at the given position.
167 * @return the first value of the KSortableItem
168 */
169 const T& operator[]( Key i ) const {
170 return QList<KSortableItem<T, Key> >::operator[]( i ).value();
171 }
172
173 /**
174 * Sorts the KSortableItems.
175 */
176 void sort() {
177 qSort( *this );
178 }
179};
180
181
182#ifdef Q_CC_MSVC
183template<class T, class K>
184inline uint qHash(const KSortableItem<T,K>&) { Q_ASSERT(0); return 0; }
185#endif
186
187
188#endif // KSORTABLELIST_H
189