cvrObject.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998-2004
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */


/**
 * \file   cvrObject.h
 *         Defines the parent class of most classes in the CVR-Lib
 * \author Pablo Alvarado
 * \date   01.04.99
 *
 * $Id: cvrObject.h,v 1.7 2005/03/29 13:09:52 doerfler Exp $
 */

#ifndef _CVR_OBJECT_H_
#define _CVR_OBJECT_H_

#include <string>

/**
 * Macro used to simplify the efficient "computation" of the class name
 */
#undef _CVR_RETURN_CLASS_NAME
#define _CVR_RETURN_CLASS_NAME \
  static const std::string theName = this->buildName(); \
  return theName;

/**
 * Namespace in which all classes, functions and constants of the CVR-Lib
 * are defined.
 */
namespace cvr {
  /**
   * Base class for most objects in the CVR-Lib.
   *
   * All classes inherited from cvr::object have three important methods:
   * - name() returns a const reference to a std::string with the name
   *   of the class (see cvr::className for more information).
   * - clone() a new instance of the object is created and a pointer to
   *   this instance is returned.  The internal state of the instance is
   *   a copy of the original.
   * - newInstance() a new instance of the same object class is created
   *   using the default constructor.
   *
   * Note that there are many classes in the library which are not inherited
   * from this class, but most complex objects are (functors, classifiers,
   * containers, etc.).  The simplest decision rule to decide if a class
   * should inherit from cvr::object is the question, should the objects be
   * "clonable"?
   *
   * The CVR-Libmakes extensive use of the C++ feature which allows to change
   * the type of overloaded virtual methods.  This feature was not supported
   * in old compilers like Visual C++ 6.0 or early GCC compilers, and is a
   * reason why they are not supported.
   *
   * In all inherited classes the method name() has to be overloaded.
   * The content of those methods can be easily implemented with the
   * macro _CVR_RETURN_CLASS_NAME.  For example:
   *
   * \code
   * const std::string& yourClass::name() {
   *   _CVR_RETURN_CLASS_NAME
   * }
   * \endcode
   */
  class object {
  public:
    /**
     * Default constructor.
     *
     * Initializes the complete library
     */
    object();

    /**
     * Destructor
     */
    virtual ~object();

    /**
     * Return the fully qualified name of this class.
     *
     * Each class has to overload this function and return its name. The
     * returned string is system-independent.  It uses cvr::className to
     * generate the class name but uses an internal singleton to avoid
     * building the class name more than once.
     *
     * Note that the factories of the CVR-Libcan use the name given by
     * name() to create instances of a class at runtime (see cvr::factory).
     *
     * This method must be overloaded in all derived classes.  You can
     * use the macro _CVR_RETURN_CLASS_NAME to produce the desired
     * behaviour.  For example:
     *
     * \code
     * const std::string& yourClass::name() {
     *   _CVR_RETURN_CLASS_NAME
     * }
     * \endcode
     *
     * The returned strings do not have any spaces, even if the
     * resulting name is not anymore C++ compliant.  This rule is
     * easier to remember as a rule to specify when the spaces are
     * required!  For example, a type "cvr::list< cvr::point<double> >" 
     * will produce the name "cvr::list<cvr::point<double>>".
     * Remember that the space between the last two angle brackets "> >" is
     * in C++ necessary to avoid syntactic confusion with the
     * operator ">>".
     *
     * @return The fully qualified name of this class without any spaces.
     *
     * This method replaces the old method getTypeName() in older versions of
     * the CVR-Lib.  Since the results are totally different, a new name
     * has been chosen to make this difference clear!
     */
    virtual const std::string& name() const = 0;

    /**
     * Clone method.
     *
     * You can create an identical instance of the current cvr::object using
     * this method.
     *
     * The difference with the method newInstance() is that here the internal
     * state is kept in the copies while newInstance() creates always an
     * object with the default parameters.
     *
     * Usually, the implementation of the overloaded method in an inherited
     * class will make use of the copy constructor:
     * \code
     *   yourClass* yourClass::clone() const {
     *     return new yourClass(*this);
     *   }
     * \endcode
     *
     * @return a pointer to the new instance.
     *
     * \warning You have to take care of the memory management of the returned
     * instance and delete it when you don't need it any more.  Otherwise you
     * will have some memory leaks.
     */
    virtual object* clone() const = 0;

    /**
     * New instance method.
     *
     * You can create a new instance of the current object, using the
     * default constructor.
     *
     * Note that the difference with the clone() method is that the latter
     * also copies the internal state of the object, while this method just
     * uses the default constructor.
     *
     * Usually, the implementation of the overloaded method in an inherited
     * class will make use of the default constructor:
     * \code
     *   yourClass* yourClass::newInstance() const {
     *     return new yourClass();
     *   }
     * \endcode
     *
     * @return a pointer to the new instance.
     *
     * \warning You have to take care of the memory management of the returned
     * instance and delete it when you don't need it any more.  Otherwise you
     * will have some memory leaks.
     */
    virtual object* newInstance() const = 0;

  protected:

    /**
     * Build for the name of the current class.
     *
     * Note that the same string is returned by the method name(), but
     * in a MUCH more efficient way.  This method has to demangle the
     * output of typeid().name() which takes some time.  The method
     * cvr::object::name() calls the buildName() only once and stores
     * the result in a static variable which is just returned in
     * successive calls, taking much less time.
     *
     * You should NEVER EVER use this method directly, use name() instead.
     */
    virtual std::string buildName() const;
  };

  /**
   * Check if the given pointer is NULL
   */
  inline bool isNull(const void* p) {return p == 0;}

  /**
   * Check if the given pointer is not NULL
   */
  inline bool notNull(const void* p) {return p != 0;}

}

#endif