libkdb3-dev 3.1.0-2 / usr / include / KDb3 / KDbOrderByColumn.h

/* This file is part of the KDE project
   Copyright (C) 2003-2016 Jarosław Staniek <staniek@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   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
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/

#ifndef KDB_ORDERBYCOLUMN_H
#define KDB_ORDERBYCOLUMN_H

#include "KDbEscapedString.h"
#include "KDbGlobal.h"

class KDbConnection;
class KDbField;
class KDbQueryColumnInfo;
class KDbQuerySchema;

//! @short KDbOrderByColumn provides information about a single query column used for sorting
/*! The column can be expression or table field. */
class KDB_EXPORT KDbOrderByColumn
{
public:
    //! Column sort order
    //! @since 3.1
    enum class SortOrder {
        Ascending = Qt::AscendingOrder,
        Descending = Qt::DescendingOrder
    };

    //! Creates an empty information about a single query column.
    KDbOrderByColumn();

    //! Creates a copy of the @a other
    //! @since 3.1
    KDbOrderByColumn(const KDbOrderByColumn &other);

    //! Creates information about a single query column @a column used for sorting.
    explicit KDbOrderByColumn(KDbQueryColumnInfo* column,
                              SortOrder order = SortOrder::Ascending, int pos = -1);

    //! Like above but used when the field @a field is not present on the list of columns.
    //! (e.g. SELECT a FROM t ORDER BY b; where T is a table with fields (a,b)).
    explicit KDbOrderByColumn(KDbField* field, SortOrder order = SortOrder::Ascending);

    ~KDbOrderByColumn();

    /*! @return copy of this KDbOrderByColumn object.
     In @a fromQuery and @a toQuery is needed if column() is assigned to this info.
     Then, column info within @a toQuery will be assigned to the new KDbOrderByColumn object,
     corresponding to column() from "this" KDbOrderByColumn object. */
    KDbOrderByColumn *copy(KDbConnection *conn, KDbQuerySchema *fromQuery,
                           KDbQuerySchema *toQuery) const Q_REQUIRED_RESULT;

    //! A column to sort.
    KDbQueryColumnInfo* column() const;

    /*! A helper for column() that allows you to know that sorting column
     was defined by providing its position. -1 by default.
     Example query: SELECT a, b FROM T ORDER BY 2 */
    int position() const;

    //! A field to sort, used only in case when the second constructor was used.
    KDbField *field() const;

    //! @return sort order for the column
    KDbOrderByColumn::SortOrder sortOrder() const;

    //! Assigns @a other to this object returns a reference to this object.
    //! @since 3.1
    KDbOrderByColumn& operator=(const KDbOrderByColumn &other);

    //! @return true if this column is the same as @a col
    bool operator==(const KDbOrderByColumn& col) const;

    //! @return @c true if this object is not equal to @a other; otherwise returns @c false.
    //! @since 3.1
    inline bool operator!=(const KDbOrderByColumn &other) const { return !operator==(other); }

    /*! @return a string like "name ASC" usable for building an SQL statement.
     If @a includeTableNames is true (the default) field is output in a form
     of "tablename.fieldname" (but only if fieldname is not a name of alias).

     @a escapingType can be used to alter default escaping type.
     If @a conn is not provided for DriverEscaping, no escaping is performed. */
    KDbEscapedString toSqlString(bool includeTableName = true,
                                 KDbConnection *conn = nullptr,
                                 KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;

    //! Converts @a order to Qt::SortOrder type
    inline static Qt::SortOrder toQt(SortOrder order) { return static_cast<Qt::SortOrder>(order); }

    //! Converts @a order to SortOrder type
    inline static SortOrder fromQt(Qt::SortOrder order) { return static_cast<SortOrder>(order); }

private:
    class Private;
    Private * const d;
};

//! @short KDbOrderByColumnList provides list of sorted columns for a query schema
class KDB_EXPORT KDbOrderByColumnList
{
public:
    /*! Constructs empty list of ordered columns. */
    KDbOrderByColumnList();

    /*! A copy constructor. */
    KDbOrderByColumnList(const KDbOrderByColumnList& other, KDbConnection *conn,
                         KDbQuerySchema* fromQuery, KDbQuerySchema* toQuery);

    ~KDbOrderByColumnList();

    //! @return @c true if this object is equal to @a other; otherwise returns @c false.
    //! @since 3.1
    bool operator==(const KDbOrderByColumnList &other) const;

    //! @return @c true if this object is not equal to @a other; otherwise returns @c false.
    //! @since 3.1
    inline bool operator!=(const KDbOrderByColumnList &other) const { return !operator==(other); }

    //! Returns column with given index.
    //! @since 3.1
    const KDbOrderByColumn* value(int index) const;

    //! @overload
    KDbOrderByColumn* value(int index);

    /*! Appends multiple fields for sorting. @a querySchema
     is used to find appropriate field or alias name.
     @return false if there is at least one name for which a field or alias name does not exist
     (all the newly appended fields are removed in this case)
     Returns @c false if @a querySchema is @c nullptr. */
    bool appendFields(KDbConnection *conn, KDbQuerySchema* querySchema,
                      const QString& field1, KDbOrderByColumn::SortOrder order1 = KDbOrderByColumn::SortOrder::Ascending,
                      const QString& field2 = QString(), KDbOrderByColumn::SortOrder order2 = KDbOrderByColumn::SortOrder::Ascending,
                      const QString& field3 = QString(), KDbOrderByColumn::SortOrder order3 = KDbOrderByColumn::SortOrder::Ascending,
                      const QString& field4 = QString(), KDbOrderByColumn::SortOrder order4 = KDbOrderByColumn::SortOrder::Ascending,
                      const QString& field5 = QString(), KDbOrderByColumn::SortOrder order5 = KDbOrderByColumn::SortOrder::Ascending);

    /*! Appends column @a columnInfo.
     Does nothing if @a columnInfo is @c nullptr. */
    void appendColumn(KDbQueryColumnInfo* columnInfo,
                      KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);

    /*! Appends a field @a field.
     Read documentation of @ref KDbOrderByColumn(KDbField* field, SortOrder order)
     for more info.
     Does nothing if @a field is @c nullptr. */
    void appendField(KDbField* field,
                     KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);

    /*! Appends field with a name @a field.
     @return @c true on successful appending, and @c false if there is no such field or alias
     name in the @a querySchema.
     Returns @c false if @a querySchema is @c nullptr. */
    bool appendField(KDbConnection *conn, KDbQuerySchema* querySchema, const QString& fieldName,
                     KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);

    /*! Appends a column that is at position @a pos (counted from 0).
     @return true on successful adding and false if there is no such position @a pos.
     Returns @c false if @a querySchema is @c nullptr. */
    bool appendColumn(KDbConnection *conn, KDbQuerySchema* querySchema,
                      KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending,
                      int pos = -1);

    /*! @return true if the list is empty. */
    bool isEmpty() const;

    /*! @return number of elements of the list. */
    int count() const;

    /*! Removes all elements from the list (deletes them). */
    void clear();

    /*! Returns an STL-style iterator pointing to the first column in the list. */
    QList<KDbOrderByColumn*>::Iterator begin();

    /*! Returns an STL-style iterator pointing to the imaginary item after the last column
     * in the list.
     */
    QList<KDbOrderByColumn*>::Iterator end();

    /*! Returns an const STL-style iterator pointing to the first column in the list. */
    QList<KDbOrderByColumn*>::ConstIterator constBegin() const;

    /*! Returns a const STL-style iterator pointing to the imaginary item after the last column
     * in the list.
     */
    QList<KDbOrderByColumn*>::ConstIterator constEnd() const;

    /*! @return an SQL string like "name ASC, 2 DESC" usable for building an SQL statement.
     If @a includeTableNames is true (the default) fields are output in a form
     of "tablename.fieldname".

     @a escapingType can be used to alter default escaping type.
     If @a conn is not provided for DriverEscaping, no escaping is performed. */
    KDbEscapedString toSqlString(bool includeTableNames = true,
                                 KDbConnection *conn = nullptr,
                                 KDb::IdentifierEscapingType escapingType = KDb::DriverEscaping) const;
private:
    class Private;
    Private * const d;
    Q_DISABLE_COPY(KDbOrderByColumnList)
};

//! Sends order-by-column information @a order to debug output @a dbg.
KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumn& order);

//! Sends order-by-column-list information @a list to debug output @a dbg.
KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbOrderByColumnList& list);

#endif