uidgenerator.h

// © Copyright 2010 - 2016 BlackTopp Studios Inc.
/* This file is part of The Mezzanine Engine.

    The Mezzanine Engine is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    The Mezzanine Engine 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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with The Mezzanine Engine.  If not, see <http://www.gnu.org/licenses/>.
*/
/* The original authors have included a copy of the license specified above in the
   'Docs' folder. See 'gpl.txt'
*/
/* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
   Build professional software and charge for their product.

   However there are some practical restrictions, so if your project involves
   any of the following you should contact us and we will try to work something
   out:
    - DRM or Copy Protection of any kind(except Copyrights)
    - Software Patents You Do Not Wish to Freely License
    - Any Kind of Linking to Non-GPL licensed Works
    - Are Currently In Violation of Another Copyright Holder's GPL License
    - If You want to change our code and not add a few hundred MB of stuff to
        your distribution

   These and other limitations could cause serious legal problems if you ignore
   them, so it is best to simply contact us or the Free Software Foundation, if
   you have any questions.

   Joseph Toppi - toppij@gmail.com
   John Blackwood - makoenergy02@gmail.com
*/

#ifndef _uidgenerator_h
#define _uidgenerator_h

#include "datatypes.h"
#include "interval.h"

namespace Mezzanine
{
    ///////////////////////////////////////////////////////////////////////////////
    /// @class UIDGenerator
    /// @brief This class will generate keep track of a pool of unique 32-bit ID's that can be used for distinct object instances.
    ///////////////////////////////////////
    class MEZZ_LIB UIDGenerator
    {
    public:
        /// @brief Convenience type for the ID to be used.  Should be some flavor of int.
        typedef UInt32                          IDType;
        /// @brief Convenience type for Intervals used by this class.
        typedef Interval<IDType>                IntervalType;
        /// @brief Basic container type for IDs generated and stored by this class.
        typedef std::vector<IntervalType>       IDContainer;
        /// @brief Iterator type for IDs generated and stored by this class.
        typedef IDContainer::iterator           IDIterator;
        /// @brief Const Iterator type for IDs generated and stored by this class.
        typedef IDContainer::const_iterator     ConstIDIterator;
    protected:
        /// @internal
        /// @brief The container storing all IDs generated and in use by this generator.
        IDContainer FreeIDs;
    public:
        /// @brief Class constructor.
        UIDGenerator();
        /// @brief Class destructor.
        ~UIDGenerator();

        ///////////////////////////////////////////////////////////////////////////////
        // Utility

        /// @brief Generates a new ID unique to the pool made by this generator.
        /// @return Returns a new unique ID, or zero if there was a failure.
        IDType GenerateID();
        /// @brief Checks to see if an ID is in use.
        /// @param ID The ID to check whether or not it is used.
        /// @return Returns true if the specified ID has already been generated and is in use.
        Boole IsIDUsed(const IDType ID) const;
        /// @brief Adds a specific ID to the pool of used IDs.
        /// @param ID The ID to be reserved.
        /// @return Returns true if the ID was successfully reserved, false if it is already generated.
        Boole ReserveID(const IDType ID);
        /// @brief Frees up an ID so that it can be reused.
        /// @param ID The ID to be freed up for reuse.
        /// @return Returns true of the ID was successfully released, false if it was already free.
        Boole ReleaseID(const IDType ID);

        /// @brief Sorts the free IDs stored in this generator.
        void Sort();
    };//UIDGenerator
}//Mezzanine

#endif