includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::*Clock)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
       (Classes wrapping std::*_clock)

manpagename(FBB::*Clock)
            (classes wrapping std::chrono::*_clock facilities)

manpagesynopsis()
    bf(#include <bobcat/fileclock>)nl()
    bf(#include <bobcat/highresolutionclock>)nl()
    bf(#include <bobcat/steadyclock>)nl()
    bf(#include <bobcat/systemclock>)nl()

    Each of these files also includes the tt(std::chrono) header file.

manpagedescription()
    The bf(C++) tt(std::chrono) namespace defines clock-types and their
operations. The bf(bobcat) tt(*Clock) classes define wrappers around the four
standard bf(C++) clock-types offering interfaces which are easier to handle
than the standard tt(std::chrono) clocks.

    itemization(
    it() bf(FileClock) wraps tt(std::chrono::file_clock);
    it()bf(HighResolutionClock) wraps tt(std::chrono::high_resolution_clock);nl()
    it()bf(SteadyClock) wraps tt(std::chrono::steady_clock);nl()
    it()bf(SystemClock) wraps tt(std::chrono::system_clock)), and is the
        commonly used clock type.  

Member names of the bf(bobcat) clock-classes don't use underscores. Names
consisting of multiple words are `camel-cased' (like tt(timePoint)).

Note:
    quote(The type tt(std::chrono::file_clock) (and therefore bf(FileClock)) is
        available since the tt(C++-2a) standard: specify the tt(--std=c++2a)
        (or more recent) compiler option when using bf(FileClock).)

includefile(include/namespace)

manpagesection(INHERITS FROM)
    tt(FBB::ClockTypes)nl()
    tt(FBB::ClockBase)nl()
    tt(FBB::HighSysClock)nl()
    quote(these are internally used only classes; their facilities are covered
        in this man-page.)

manpagesection(TYPEDEFS AND ENUMS)

    itemization(
    it() The tt(std::chrono) types tt(nanoseconds, microseconds, milliseconds,
        seconds, minutes) and tt(hours) are also available in the namespace
        tt(FBB);
    )

bf(Clock Types:)
    itemization(
    itt(FBB::FileClock) provides the tt(std::chrono::file_clock) facilities;

    itt(FBB::HighResolutionClock) provides the 
        tt(std::chrono::high_resolution_clock) facilities; 

    itt(FBB::SteadyClock) provides the tt(std::chrono::steady_clock)
        facilities;

    itt(FBB::SystemClock) provides the tt(std::chrono::system_clock)
        facilities. 
    )

bf(Sub-types:)
    itemization(
    itt(Duration): each clock type defines the type tt(Duration) as
        tt(std::chrono::duration<int64_t, std::nano>);

    itt(Period): the sub-type tt(period) of the tt(Duration) type. In practice
        its subtypes tt(den (DenType)) and tt(num (NumType)) are used;

    itt(DenType): the denominator type of the tt(ratio) type used by the clock
        type (see also the static member tt(den)); 

    itt(NumType): the numerator type of the tt(ratio) type used by the clock
        type (see also the static member tt(num)); 
    )

manpagesection(CONSTRUCTORS)

    The constructors are illustrated for tt(SystemClock) but are also
available for the other clock types.

    itemization(
    itb(SystemClock(SystemClock::TimePoint = SystemClock::now()))
       each clock-constructor can be initialized with a time point. By default
        the clock's time point is initialized by the time point returned by
        the clock type's static tt(now) member;

    itb(SystemClock(Clock const &otherClock))
       each clock type can be initialized with another clock type object
        (except for a tt(SteadyClock) type object): when constructed they
        refer to the same points in time.
    )

    Copy and move constructors (and assignment operators) are available.

manpagesection(OVERLOADED OPERATORS)
    Using tt(DurationType) to represent
    tt(std::chrono::duration<int64_t, Ratio>), where tt(Ratio) is a
        tt(std::ratio) type (for clocks tt(Ratio) equals tt(nano)).

    itemization(
    itb(ClockType &operator+=(DurationType const &amount))
       adds tt(amount) to the current clock's tt(TimePoint). E.g.,
 verb(
    SystemClock sc;
    sc += 1h;
 )

    itb(ClockType &operator+=(int secs);)
       adds tt(secs) seconds to the current clock's tt(TimePoint);

    itb(ClockType &operator-=(DurationType const &amount);)
       subtracts tt(amount) from the current clock's tt(TimePoint). 
        Not available for tt(SteadyClock);

    itb(ClockType &operator-=(int secs);)
       subtracts tt(secs) seconds from the current clock's tt(TimePoint);

    itb(SteadyClock &operator-=(SteadyClock const &rhs))
       only available for class tt(SteadyClock): tt(rhs.elapsed()) is
        subtracted from the current object's time-point. See also the
        functions tt(since) and tt(countSince) below.

    itb(std::ostream &operator<<(std::ostream &out, ClockType const &clock))
       not available for tt(SteadyClock); tt(clock's) (UTC)
        tt(TimePoint) is inserted into tt(out). E.g.,
 verb(
    cout << SystemClock{};  // could insert 
                            // 2025-01-04 08:25:10.035509381
 )

    itb(ClockType operator+(Type1 const &lhs, Type2 const &rhs))
       not available for tt(SteadyClock). Either tt(Type1) or tt(Type2) must
        be an bf(FBB) Clock type (like tt(SystemClock)). The other type can
        either be an tt(int) (representing number of seconds) or a
        tt(DurationType) (like tt(seconds, hours)). A clock object of the same
        type as the tt(Clock) argument is returned, whose tt(TimePoint) is
        initialized to the sum of the argument's tt(TimePoint) and the value
        of the other argument;

    itb(ClockType operator-(ClockType const &lhs, Type const &rhs))
       both argument types can be tt(SteadyClock). As tt(SteadyClock) objects
        are used for timing purposes this operator returns a tt(SteadyClock)
        object whose time specification is equal to the difference of the
        tt(lhs) and tt(rhs) time specifications (see also the functions
        tt(since) and tt(countSince) below).nl()
       Otherwise the tt(lhs) argument must be an bf(FBB) Clock type (like
        tt(SystemClock)), and tt(Type) can either be
        an tt(int) (representing number of seconds) or a tt(DurationType)
        (like tt(seconds, hours)), returning a clock object whose
        tt(TimePoint) is initialized to the difference of the tt(lhs's
        TimePoint) and the tt(rhs) value;
    )

manpagesection(FREE FUNCTIONS)

    itemization(
    itb(auto toClock<DestClock>(ClockType const &clock))
       returns the tt(DestClock::TimePoint) corresponding to the tt(TimePoint)
        of tt(clock). It is not available for conversions from or to the
        tt(SteadyClock) type. E.g., 
 verb(
    FileClock fc;
    cout << toClock<SystemClock>(fc) << '\n';
 )

    itb(double toDouble<Duration>(ClockType const &src))
       returns the tt(double) value corresponding to tt(ClockType's
        std::chrono::duration) converted to the tt(Duration
        std::chrono::duration). E.g., 
 verb(    
    toDouble<hours>(90min); // returns 1.5
 )

    itb(Dest toDuration(Src const &src))
       returns tt(src's Duration) converted to the (at least as precise)
        tt(Dest) duration. E.g.,
 verb(    
    toDuration<seconds>(1min).count(); // returns 60
 )
    )

manpagesection(ADDITIONAL STEADYCLOCK FREE FUNCTIONS)

    The tt(SteadyClock) type is primarily used for timing purposes. The
following two functions are available for tt(SteadyClock) objects:
    itemization(
    itb(SteadyClock::Duration since(SteadyClock const &time0))
       The difference in nanoseconds (tt(Durations)) of a local
        tt(SteadyClock) object and tt(time0) is returned. E.g.,
 verb(
    SteadyClock start;
    // do something
    cout << "Elapsed time: " << since(start) << '\n';
 )

    itb(size_t countSince(SteadyClock const &time0))
       Same as the previous function, but the number of nanoseconds are
        returned as a tt(size_t) value.
    )


manpagesection(MEMBER FUNCTIONS)
     All of the following members are available for each of bf(bobcat's) clock
types:
    itemization(
    itb(long int count())
       returns tt(timePoint's value). The clock types have members
        tt(timePoint()): this member returns the number of nano seconds as an
        integral value since the beginning of the clock's era. E.g.,
 verb(
    FileClock{}.clock();  // returns, e.g., 
                          // -4701673791896351066
 )

    itb(static long int ClockTypes::count(TimePoint const &timePoint))
       returns tt(timePoint's value). This function can also be used for
        tt(SteadyClock) objects. E.g.,
 verb(
    ClockTypes::count(SteadyClock::now());  // returns, e.g., 
                                            // 8310904806233
 )

    itb(static DenType::den())
       returns the denominator of the tt(ratio) used by the clocks (=
        1'000'000'000);

    itb(Duration elapsed() const)
       returns the tt(Duration) value of the current tt(Clock) object (=
        number of nano-seconds since the beginning of the clock's era). E.g.,
 verb(
    SystemClock{}.elapsed();    // returns, e.g., 
                                // 1735989478991599467ns
 )

    itb(static Duration ClockTypes::elapsed(TimePoint const &timePoint))
       returns tt(timePoint's Duration). Clock types have members
        tt(timePoint()) returning the clock's time point;

    itb(static TimePoint max())
       returns the tt(TimePoint) of the used clock type corresponding to the
        clock's maximum (UTC) time. E.g.,
 verb(
    cout << SystemClock::max();     // inserts:
                                    // 2262-04-11 23:47:16...
 )

    itb(static TimePoint min())
       returns the tt(TimePoint) of the used clock type corresponding to the
        clock's minimum (UTC) time;

    itb(static TimePoint now())
       returns the tt(TimePoint) of the used clock type corresponding to the
        current (UTC) time. E.g.,
 verb(
    cout << SystemClock::now() << '\n';
 )

    itb(static NumType::num())
       returns the numerator of the tt(ratio) used by the clocks (= 1);

    itb(static Period period())
       returns the clock's tt(Period) (having members tt(den) and tt(num));

    itb(TimePoint const &timePoint() const)
       returns the object's tt(TimePoint);

    itb(double toDouble<Dest>() const)
       returns the tt(double) value corresponding to the object's
        tt(std::chrono::duration) converted to the tt(Dest
        std::chrono::duration). E.g., 
 verb(
    SystemClock{}.toDouble<hours>(); // returns, e.g., 482221
 )

    itb(static Duration zero())
       returns the clock's tt(Duration) representing 0 nanoseconds;
    )

manpagesection(ADDITIONAL SYSTEM / HIGHRESOLUTION CLOCK MEMBERS)

    Primarily for displaying the clock's time the tt(SystemClock) and
tt(HighResolutionClock) classes support these members:
    itemization(
    itb(std::time_t timeT() const)
       returns the object's tt(TimePoint) converted to tt(time_t)
        (cf. bf(time)(3));

    itb(Clock &setTime(std::time_t seconds))
       returns the current object after resetting its tt(TimePoint) to its
        tt(time_t) argument;

    itb(Clock const &operator()(char const *putTime, 
                                bool localTime = true) const)
       prepares the current object for the next insertion operator, using
        the tt(putTime) specification to configure the tt(std::put_time)
        manipulator (cf. tt(C++ Annotations), section 6.4.4 (The `put_time'
        manipulator)). By default the time is displayed using the local
        time. When the 2nd argument is tt(false) the time is displayed in
        tt(UTC). When the current object is inserted into a tt(std::ostream)
        after calling this member the tt(put_time) manipulator is used only
        once. By calling this member again tt(put_time) is repeatedly
        used. E.g.,
 verb(
    SystemClock sc;
    cout <<                     // inserts, e.g.,
        sc("%Y") << '\n' <<     // 2025
        sc("%y") << '\n' <<     // 25
        sc << '\n';             // 2025-01-04 14:18:47...
 )
    )

manpagesection(EXAMPLE)
    verbinclude(../../systemclock/driver/main.cc)

manpagefiles()

    em(bobcat/fileclock),   - the tt(FileClock) class interface+nl()
    em(bobcat/highresulutionclock) - the tt(HighResolutionClock)
        class interface+nl()
    em(bobcat/steadyclock)  - the tt(SteadyClock) class interface+nl()
    em(bobcat/systemclock) - the tt(SystemClock) class interface+nl()

manpageseealso()
    bf(bobcat)(7), bf(time)(3),

manpagebugs()
    None Reported.

includefile(include/trailer)