QxNullable

From qtnode

QxNullable is a lightweight wrapper around any data type that has the ability to store a distinct null value. A common use is to provide a way to allow a programmer to skip an optional parameter but specify a later one.

Contents 1 Public Member Functions 1.1 QxNullable<T>() 1.2 QxNullable<T>(const T& value) 1.3 QxNullable<T>(const QxNull& p) 1.4 bool isNull() const 1.5 void nullify() const 1.6 T& value() const 1.7 operator T&() const 1.8 const T& operator=(const T& p) 1.9 const QxNull& operator=(const QxNull& p) 2 Related Non-Members 2.1 QxNull QXNULL 2.2 qxNullable(t, n) 3 Header File qxnullable.h 4 Example Usage 5 Licensing

Public Member Functions

QxNullable<T>()

Creates a null QxNullable object of type T.

QxNullable<T>(const T& value)

Creates a QxNullable object of type T containing the specified value.

QxNullable<T>(const QxNull& p)

Creates a null QxNullable object of type T.

bool isNull() const

Returns true if the QxNullable object refers to a null value, otherwise returns false.

void nullify() const

Forces the contents to be null. The original value is discarded.

T& value() const

Returns a modifiable reference to the contained value. If the contents are null, the return value is undefined.

operator T&() const

Returns a modifiable reference to the contained value. If the contents are null, the return value is undefined.

const T& operator=(const T& p)

Sets the contents to the specified value. Returns a reference to the value.

const QxNull& operator=(const QxNull& p)

Forces the contents to be null. The original value is discarded. Returns a reference to the null object.

Related Non-Members

QxNull QXNULL

A predefined null value that can be assigned to a QxNullable of any type. Defined in qxnull.h.

qxNullable(t, n)

This macro is equivalent to QxNullable<t> n = QxNullable<t>() and is provided as a shortcut for specifying a nullable function parameter.

Header File qxnullable.h

#include "qxnull.h"

#ifndef QX_NO_MACROS
#define qxNullable(t,n) QxNullable<t> n = QxNullable<t>()
#endif

template<typename T>
class QxNullable {
public:
    QxNullable(QxNull p);
    QxNullable(const T& p);
    QxNullable();
    bool isNull() const;
    void nullify();
    T& value() const;
    operator T() const;
    const T& operator=(const T& p);
    const QxNull& operator=(const QxNull& p);
private:
    T* val;
};

template<typename T>
QxNullable<T>::QxNullable(QxNull) {
    val = 0;
}

template<typename T>
QxNullable<T>::QxNullable(const T& p) {
    val = const_cast<T*>(&p);
}

template<typename T>
QxNullable<T>::QxNullable() {
    val = 0;
}

template<typename T>
inline QxNullable<T>::operator T() const {
    return *val;
}

template<typename T>
inline T& QxNullable<T>::value() const {
    return *val;
}

template<typename T>
inline bool QxNullable<T>::isNull() const {
    return (val==0);
}

template<typename T>
inline void QxNullable<T>::nullify() {
    val = 0;
}

template<typename T>
inline const T& QxNullable<T>::operator=(const T& p) {
    return (*val = p);
}

template<typename T>
inline const QxNull& QxNullable<T>::operator=(const QxNull& p) {
    val = 0;
    return p;
}

Example Usage

QString generateQuery(qxNullable(int, id), qxNullable(float, cost)) {
    QString r = "SELECT id, name, cost FROM myTable WHERE ";
    if(!id.isNull())
        r += "id=" + QString::number(id);
    if(!id.isNull() && !value.isNull()) 
        r += " AND ";
    if(!value.isNull())
        r += "cost="+QString::number(value);
    else if(id.isNull())
        r += "cost IS NULL";
    return r;
}

generateQuery(QXNULL, 2.8);    // returns "SELECT id, name, cost FROM myTable WHERE cost=2.8"

This example shows how you might generate a SQL query with nullable parameters. In this example, all entries must have an ID, so if a null ID value is passed in, it is ignored. However, an entry might have a null cost (that is, it may not have a cost specified in the database), or it might have a zero cost, so the function is capable of distinguishing between the parameters provided to it.

Licensing

QxNullable is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, version 2.1 or greater, or under the terms of the Q Public Library as published by Trolltech.

QxNullable 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 appropriate license agreement for more details.