271 lines
7.7 KiB
C++
271 lines
7.7 KiB
C++
/***************************************************************************
|
|
copyright : (C) 2002 - 2008 by Scott Wheeler
|
|
email : wheeler@kde.org
|
|
***************************************************************************/
|
|
|
|
/***************************************************************************
|
|
* This library is free software; you can redistribute it and/or modify *
|
|
* it under the terms of the GNU Lesser General Public License version *
|
|
* 2.1 as published by the Free Software Foundation. *
|
|
* *
|
|
* This library is distributed in the hope that it will be useful, but *
|
|
* WITHOUT ANY WARRANTY; without even the implied warranty of *
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
|
|
* Lesser General Public License for more details. *
|
|
* *
|
|
* You should have received a copy of the GNU Lesser General Public *
|
|
* License along with this library; if not, write to the Free Software *
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
|
|
* 02110-1301 USA *
|
|
* *
|
|
* Alternatively, this file is available under the Mozilla Public *
|
|
* License Version 1.1. You may obtain a copy of the License at *
|
|
* http://www.mozilla.org/MPL/ *
|
|
***************************************************************************/
|
|
|
|
#ifndef TAGLIB_LIST_H
|
|
#define TAGLIB_LIST_H
|
|
|
|
#include "taglib.h"
|
|
|
|
#include <list>
|
|
|
|
namespace TagLib {
|
|
|
|
//! A generic, implicitly shared list.
|
|
|
|
/*!
|
|
* This is basic generic list that's somewhere between a std::list and a
|
|
* QValueList. This class is implicitly shared. For example:
|
|
*
|
|
* \code
|
|
*
|
|
* TagLib::List<int> l = someOtherIntList;
|
|
*
|
|
* \endcode
|
|
*
|
|
* The above example is very cheap. This also makes lists suitable for the
|
|
* return types of functions. The above example will just copy a pointer rather
|
|
* than copying the data in the list. When your \e shared list's data changes,
|
|
* only \e then will the data be copied.
|
|
*/
|
|
|
|
template <class T> class List
|
|
{
|
|
public:
|
|
#ifndef DO_NOT_DOCUMENT
|
|
typedef typename std::list<T>::iterator Iterator;
|
|
typedef typename std::list<T>::const_iterator ConstIterator;
|
|
#endif
|
|
|
|
/*!
|
|
* Constructs an empty list.
|
|
*/
|
|
List();
|
|
|
|
/*!
|
|
* Make a shallow, implicitly shared, copy of \a l. Because this is
|
|
* implicitly shared, this method is lightweight and suitable for
|
|
* pass-by-value usage.
|
|
*/
|
|
List(const List<T> &l);
|
|
|
|
/*!
|
|
* Destroys this List instance. If auto deletion is enabled and this list
|
|
* contains a pointer type all of the members are also deleted.
|
|
*/
|
|
virtual ~List();
|
|
|
|
/*!
|
|
* Returns an STL style iterator to the beginning of the list. See
|
|
* std::list::const_iterator for the semantics.
|
|
*/
|
|
Iterator begin();
|
|
|
|
/*!
|
|
* Returns an STL style constant iterator to the beginning of the list. See
|
|
* std::list::iterator for the semantics.
|
|
*/
|
|
ConstIterator begin() const;
|
|
|
|
/*!
|
|
* Returns an STL style iterator to the end of the list. See
|
|
* std::list::iterator for the semantics.
|
|
*/
|
|
Iterator end();
|
|
|
|
/*!
|
|
* Returns an STL style constant iterator to the end of the list. See
|
|
* std::list::const_iterator for the semantics.
|
|
*/
|
|
ConstIterator end() const;
|
|
|
|
/*!
|
|
* Inserts a copy of \a value before \a it.
|
|
*/
|
|
Iterator insert(Iterator it, const T &value);
|
|
|
|
/*!
|
|
* Inserts the \a value into the list. This assumes that the list is
|
|
* currently sorted. If \a unique is true then the value will not
|
|
* be inserted if it is already in the list.
|
|
*/
|
|
List<T> &sortedInsert(const T &value, bool unique = false);
|
|
|
|
/*!
|
|
* Appends \a item to the end of the list and returns a reference to the
|
|
* list.
|
|
*/
|
|
List<T> &append(const T &item);
|
|
|
|
/*!
|
|
* Appends all of the values in \a l to the end of the list and returns a
|
|
* reference to the list.
|
|
*/
|
|
List<T> &append(const List<T> &l);
|
|
|
|
/*!
|
|
* Prepends \a item to the beginning list and returns a reference to the
|
|
* list.
|
|
*/
|
|
List<T> &prepend(const T &item);
|
|
|
|
/*!
|
|
* Prepends all of the items in \a l to the beginning list and returns a
|
|
* reference to the list.
|
|
*/
|
|
List<T> &prepend(const List<T> &l);
|
|
|
|
/*!
|
|
* Clears the list. If auto deletion is enabled and this list contains a
|
|
* pointer type the members are also deleted.
|
|
*
|
|
* \see setAutoDelete()
|
|
*/
|
|
List<T> &clear();
|
|
|
|
/*!
|
|
* Returns the number of elements in the list.
|
|
*
|
|
* \see isEmpty()
|
|
*/
|
|
unsigned int size() const;
|
|
|
|
/*!
|
|
* Returns whether or not the list is empty.
|
|
*
|
|
* \see size()
|
|
*/
|
|
bool isEmpty() const;
|
|
|
|
/*!
|
|
* Find the first occurrence of \a value.
|
|
*/
|
|
Iterator find(const T &value);
|
|
|
|
/*!
|
|
* Find the first occurrence of \a value.
|
|
*/
|
|
ConstIterator find(const T &value) const;
|
|
|
|
/*!
|
|
* Returns true if the list contains \a value.
|
|
*/
|
|
bool contains(const T &value) const;
|
|
|
|
/*!
|
|
* Erase the item at \a it from the list.
|
|
*/
|
|
Iterator erase(Iterator it);
|
|
|
|
/*!
|
|
* Returns a reference to the first item in the list.
|
|
*/
|
|
const T &front() const;
|
|
|
|
/*!
|
|
* Returns a reference to the first item in the list.
|
|
*/
|
|
T &front();
|
|
|
|
/*!
|
|
* Returns a reference to the last item in the list.
|
|
*/
|
|
const T &back() const;
|
|
|
|
/*!
|
|
* Returns a reference to the last item in the list.
|
|
*/
|
|
T &back();
|
|
|
|
/*!
|
|
* Auto delete the members of the list when the last reference to the list
|
|
* passes out of scope. This will have no effect on lists which do not
|
|
* contain a pointer type.
|
|
*
|
|
* \note This relies on partial template instantiation -- most modern C++
|
|
* compilers should now support this.
|
|
*/
|
|
void setAutoDelete(bool autoDelete);
|
|
|
|
/*!
|
|
* Returns a reference to item \a i in the list.
|
|
*
|
|
* \warning This method is slow. Use iterators to loop through the list.
|
|
*/
|
|
T &operator[](unsigned int i);
|
|
|
|
/*!
|
|
* Returns a const reference to item \a i in the list.
|
|
*
|
|
* \warning This method is slow. Use iterators to loop through the list.
|
|
*/
|
|
const T &operator[](unsigned int i) const;
|
|
|
|
/*!
|
|
* Make a shallow, implicitly shared, copy of \a l. Because this is
|
|
* implicitly shared, this method is lightweight and suitable for
|
|
* pass-by-value usage.
|
|
*/
|
|
List<T> &operator=(const List<T> &l);
|
|
|
|
/*!
|
|
* Exchanges the content of this list by the content of \a l.
|
|
*/
|
|
void swap(List<T> &l);
|
|
|
|
/*!
|
|
* Compares this list with \a l and returns true if all of the elements are
|
|
* the same.
|
|
*/
|
|
bool operator==(const List<T> &l) const;
|
|
|
|
/*!
|
|
* Compares this list with \a l and returns true if the lists differ.
|
|
*/
|
|
bool operator!=(const List<T> &l) const;
|
|
|
|
protected:
|
|
/*
|
|
* If this List is being shared via implicit sharing, do a deep copy of the
|
|
* data and separate from the shared members. This should be called by all
|
|
* non-const subclass members.
|
|
*/
|
|
void detach();
|
|
|
|
private:
|
|
#ifndef DO_NOT_DOCUMENT
|
|
template <class TP> class ListPrivate;
|
|
ListPrivate<T> *d;
|
|
#endif
|
|
};
|
|
|
|
}
|
|
|
|
// Since GCC doesn't support the "export" keyword, we have to include the
|
|
// implementation.
|
|
|
|
#include "tlist.tcc"
|
|
|
|
#endif
|