openfoam/src/OpenFOAM/db/Time/timeSelector.H

/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   \\    /   O peration     |
    \\  /    A nd           | www.openfoam.com
     \\/     M anipulation  |
-------------------------------------------------------------------------------
    Copyright (C) 2011-2015 OpenFOAM Foundation
    Copyright (C) 2018 OpenCFD Ltd.
-------------------------------------------------------------------------------
License
    This file is part of OpenFOAM.

    OpenFOAM 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.

    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.

Class
    Foam::timeSelector

Description
    A List of scalarRange for selecting times.

    The timeSelector provides a convenient means of selecting multiple
    times. A typical use would be the following:

    \verbatim
    timeSelector::addOptions();
    // add other options
    #include "setRootCase.H"
    #include "createTime.H"
    instantList timeDirs = timeSelector::select0(runTime, args);
    ...
    forAll(timeDirs, timei)
    {
        ...
    }
    \endverbatim

    The result program would receive \b -time, \b -latestTime, \b -constant
    and \b -noZero options. The \b -constant option explicitly includes the
    \c constant/ directory in the time list and the \b -noZero option
    explicitly excludes the \c 0/ directory from the time list.

    There may however also be many cases in which neither the \c constant/
    directory nor the \c 0/ directory contain particularly relevant
    information. This might occur, for example, when post-processing
    results. In this case, addOptions is called with optional boolean
    arguments.

    \verbatim
    timeSelector::addOptions(false, true);
    \endverbatim

    The first argument avoids adding the \b -constant option. The second
    argument adds an additional \b -withZero option and also prevents the
    \c 0/ directory from being included in the default time range and in the
    \b -latestTime selection.

SourceFiles
    timeSelector.C

\*---------------------------------------------------------------------------*/

#ifndef timeSelector_H
#define timeSelector_H

#include "scalarRanges.H"
#include "instantList.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

namespace Foam
{

// Forward declarations
class argList;
class Time;

/*---------------------------------------------------------------------------*\
                        Class timeSelector Declaration
\*---------------------------------------------------------------------------*/

class timeSelector
:
    private scalarRanges
{
public:

    // Constructors

        //- Construct null
        timeSelector();

        //- Construct by parsing string for time ranges
        timeSelector(const std::string& str);


    // Member Functions

        //- Return true if the given instant is within the ranges
        bool selected(const instant& value) const;

        //- Return the set of selected instants in the given list that are
        //- within the ranges
        List<bool> selected(const instantList& times) const;

        //- Select a list of Time values that are within the ranges
        instantList select(const instantList& times) const;

        //- Select a list of Time values that are within the ranges
        void inplaceSelect(instantList& times) const;


    // Static Member Functions

        //- Add timeSelector options to argList::validOptions
        //
        // \param constant
        //   Add the \b -constant option to include the \c constant/ directory
        //
        // \param withZero
        //   Enable the \b -withZero option and alter the normal time selection
        //   behaviour (and \b -latestTime behaviour) to exclude the \c 0/
        //   directory. The \c 0/ directory will only be included when
        //   \b -withZero is specified.
        //   The \b -noZero option has precedence over the \b -withZero option.
        static void addOptions
        (
            const bool constant=true,
            const bool withZero=false
        );

        //- Return the set of times selected based on the argList options
        static instantList select
        (
            const instantList& times,
            const argList& args,
            const word& constantName = "constant"
        );

        //- Return the set of times selected based on the argList options
        //- and also set the runTime to the first instance or the
        //- \c constant/ directory if no instances are specified or available
        static instantList select0
        (
            Time& runTime,
            const argList& args
        );

        //- If any time option provided return the set of times (as select0)
        //- otherwise return just the current time.
        //  Also set the runTime to the first instance
        static instantList selectIfPresent
        (
            Time& runTime,
            const argList& args
        );

};


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

} // End namespace Foam

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// ************************************************************************* //