Add first/last accessors to QMap

QMap explicitly sorts its entries by key value. For an ordered container
it's (often?) useful to access the first or last entry, for instance to
quickly compute the next key of the mapping. The first entry is easily
accessible by the STL begin() method, but for accessing the last entry
pretty ugly iterator arithmetics must be applied: *(end() - 1). With
their first() and last() accessors the container classes QList and
QVector provide a much nicer method of accessing extrema, so for
consistency this syntactical sugar also should be applied to QMap.

Change-Id: Ibd544acbad8c3ac16f12a1e74362207ea1694375
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Thorbjørn Lund Martsum <tmartsum@gmail.com>

1 files changed, 42 insertions, 0 deletions

diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index e5de4a1bfd..71b90bcada 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -879,6 +879,48 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa constBegin(), end()
 */
 
+/*! \fn const Key &QMap::firstKey() const
+
+    Returns a reference to the smallest key in the map.
+    This function assumes that the map is not empty.
+
+    \sa lastKey(), first(), isEmpty()
+*/
+
+/*! \fn const Key &QMap::lastKey() const
+
+    Returns a reference to the largest key in the map.
+    This function assumes that the map is not empty.
+
+    \sa firstKey(), last(), isEmpty()
+*/
+
+/*! \fn T &QMap::first()
+
+    Returns a reference to the first value in the map, that is the value mapped
+    to the smallest key. This function assumes that the map is not empty.
+
+    \sa last(), firstKey(), isEmpty()
+*/
+
+/*! \fn const T &QMap::first() const
+
+    \overload
+*/
+
+/*! \fn T &QMap::last()
+
+    Returns a reference to the last value in the map, that is the value mapped
+    to the largest key. This function assumes that the map is not empty.
+
+    \sa first(), lastKey(), isEmpty()
+*/
+
+/*! \fn const T &QMap::last() const
+
+    \overload
+*/
+
 /*! \fn QMap::iterator QMap::erase(iterator pos)
 
     Removes the (key, value) pair pointed to by the iterator \a pos