timeCodeRange.h

Go to the documentation of this file.

//
// Copyright 2019 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_USD_USD_UTILS_TIME_CODE_RANGE_H
#define PXR_USD_USD_UTILS_TIME_CODE_RANGE_H


#include "pxr/pxr.h"
#include "pxr/usd/usdUtils/api.h"

#include "pxr/base/gf/math.h"
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/staticTokens.h"
#include "pxr/usd/usd/timeCode.h"

#include <iosfwd>
#include <iterator>
#include <string>


PXR_NAMESPACE_OPEN_SCOPE


#define USDUTILS_TIME_CODE_RANGE_TOKENS \
    ((EmptyTimeCodeRange, "NONE")) \
    ((RangeSeparator, ":")) \
    ((StrideSeparator, "x"))

TF_DECLARE_PUBLIC_TOKENS(
    UsdUtilsTimeCodeRangeTokens,
    USDUTILS_API,
    USDUTILS_TIME_CODE_RANGE_TOKENS);


class UsdUtilsTimeCodeRange
{
public:

    class const_iterator
    {
    public:
        using iterator_category = std::forward_iterator_tag;
        using value_type = UsdTimeCode;
        using reference = const UsdTimeCode&;
        using pointer = const UsdTimeCode*;
        using difference_type = std::ptrdiff_t;

        reference operator*() {
            return _currTimeCode;
        }

        pointer operator->() {
            return &_currTimeCode;
        }

        const_iterator& operator++() {
            if (_timeCodeRange) {
                ++_currStep;
                _currTimeCode =
                    UsdTimeCode(
                        _timeCodeRange->_startTimeCode.GetValue() +
                        _timeCodeRange->_stride * _currStep);
            }
            _InvalidateIfExhausted();
            return *this;
        }

        const_iterator operator++(int) {
            const_iterator preAdvanceIter = *this;
            ++(*this);
            return preAdvanceIter;
        }

        bool operator ==(const const_iterator& other) const {
            return _timeCodeRange == other._timeCodeRange &&
                _currStep == other._currStep;
        }

        bool operator !=(const const_iterator& other) const {
            return !(*this == other);
        }

    private:
        friend class UsdUtilsTimeCodeRange;

        const_iterator(const UsdUtilsTimeCodeRange* timeCodeRange) :
            _timeCodeRange(timeCodeRange),
            _currStep(0u),
            _maxSteps(0u),
            _currTimeCode()
        {
            if (_timeCodeRange) {
                const double startVal = _timeCodeRange->_startTimeCode.GetValue();
                const double endVal = _timeCodeRange->_endTimeCode.GetValue();
                const double stride = _timeCodeRange->_stride;

                _maxSteps = static_cast<size_t>(
                    GfFloor((endVal - startVal + stride) / stride));
                _currTimeCode = _timeCodeRange->_startTimeCode;
            }

            _InvalidateIfExhausted();
        }

        void _InvalidateIfExhausted() {
            bool finished = false;
            if (!_timeCodeRange) {
                finished = true;
            } else if (_currStep >= _maxSteps) {
                finished = true;
            }

            if (finished) {
                _timeCodeRange = nullptr;
                _currStep = 0u;
                _maxSteps = 0u;
                _currTimeCode = UsdTimeCode();
            }
        }

        const UsdUtilsTimeCodeRange* _timeCodeRange;
        size_t _currStep;
        size_t _maxSteps;
        UsdTimeCode _currTimeCode;
    };

    using iterator = const_iterator;

    USDUTILS_API
    static UsdUtilsTimeCodeRange CreateFromFrameSpec(
            const std::string& frameSpec);

    UsdUtilsTimeCodeRange()
    {
        _Invalidate();
    }

    UsdUtilsTimeCodeRange(const UsdTimeCode timeCode) :
        UsdUtilsTimeCodeRange(timeCode, timeCode)
    {
    }

    UsdUtilsTimeCodeRange(
            const UsdTimeCode startTimeCode,
            const UsdTimeCode endTimeCode) :
        UsdUtilsTimeCodeRange(
            startTimeCode,
            endTimeCode,
            (endTimeCode >= startTimeCode) ? 1.0 : -1.0)
    {
    }

    UsdUtilsTimeCodeRange(
            const UsdTimeCode startTimeCode,
            const UsdTimeCode endTimeCode,
            const double stride) :
        _startTimeCode(startTimeCode),
        _endTimeCode(endTimeCode),
        _stride(stride)
    {
        if (_startTimeCode.IsEarliestTime()) {
            TF_CODING_ERROR(
                "startTimeCode cannot be UsdTimeCode::EarliestTime()");
            _Invalidate();
            return;
        }
        if (_startTimeCode.IsDefault()) {
            TF_CODING_ERROR(
                "startTimeCode cannot be UsdTimeCode::Default()");
            _Invalidate();
            return;
        }
        if (_endTimeCode.IsEarliestTime()) {
            TF_CODING_ERROR(
                "endTimeCode cannot be UsdTimeCode::EarliestTime()");
            _Invalidate();
            return;
        }
        if (_endTimeCode.IsDefault()) {
            TF_CODING_ERROR(
                "endTimeCode cannot be UsdTimeCode::Default()");
            _Invalidate();
            return;
        }

        if (_stride > 0.0) {
            if (_endTimeCode < _startTimeCode) {
                TF_CODING_ERROR(
                    "endTimeCode cannot be less than startTimeCode with "
                    "positive stride");
                _Invalidate();
                return;
            }
        } else if (_stride < 0.0) {
            if (_endTimeCode > _startTimeCode) {
                TF_CODING_ERROR(
                    "endTimeCode cannot be greater than startTimeCode with "
                    "negative stride");
                _Invalidate();
                return;
            }
        } else {
            TF_CODING_ERROR("stride cannot be zero");
            _Invalidate();
            return;
        }
    }

    UsdTimeCode GetStartTimeCode() const {
        return _startTimeCode;
    }

    UsdTimeCode GetEndTimeCode() const {
        return _endTimeCode;
    }

    double GetStride() const {
        return _stride;
    }

    iterator begin() const {
        return iterator(this);
    }

    const_iterator cbegin() const {
        return const_iterator(this);
    }

    iterator end() const {
        return iterator(nullptr);
    }

    const_iterator cend() const {
        return const_iterator(nullptr);
    }

    bool empty() const {
        return begin() == end();
    }

    bool IsValid() const {
        return !empty();
    }

    explicit operator bool() const {
        return IsValid();
    }

    bool operator ==(const UsdUtilsTimeCodeRange& other) const {
        return _startTimeCode == other._startTimeCode &&
            _endTimeCode == other._endTimeCode &&
            _stride == other._stride;
    }

    bool operator !=(const UsdUtilsTimeCodeRange& other) const {
        return !(*this == other);
    }

private:

    void _Invalidate() {
        _startTimeCode = UsdTimeCode(0.0);
        _endTimeCode = UsdTimeCode(-1.0);
        _stride = 1.0;
    }

    UsdTimeCode _startTimeCode;
    UsdTimeCode _endTimeCode;
    double _stride;
};

// Stream I/O operators.

USDUTILS_API
std::ostream& operator<<(
        std::ostream& os,
        const UsdUtilsTimeCodeRange& timeCodeRange);

USDUTILS_API
std::istream& operator>>(
        std::istream& is,
        UsdUtilsTimeCodeRange& timeCodeRange);


PXR_NAMESPACE_CLOSE_SCOPE


#endif