Provided by: libbobcat-dev_6.07.01-2_amd64 
NAME
FBB::*Clock - classes wrapping std::chrono::*_clock facilities
SYNOPSIS
#include <bobcat/fileclock>
#include <bobcat/highresolutionclock>
#include <bobcat/steadyclock>
#include <bobcat/systemclock>
Each of these files also includes the std::chrono header file.
DESCRIPTION
The C++ std::chrono namespace defines clock-types and their operations. The bobcat *Clock classes define
wrappers around the four standard C++ clock-types offering interfaces which are easier to handle than the
standard std::chrono clocks.
o FileClock wraps std::chrono::file_clock;
o HighResolutionClock wraps std::chrono::high_resolution_clock;
o SteadyClock wraps std::chrono::steady_clock;
o SystemClock wraps std::chrono::system_clock, and is the commonly used clock type.
Member names of the bobcat clock-classes don’t use underscores. Names consisting of multiple words are
`camel-cased’ (like timePoint).
Note:
The type std::chrono::file_clock (and therefore FileClock) is available since the C++-2a standard:
specify the --std=c++2a (or more recent) compiler option when using FileClock.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the
namespace FBB.
INHERITS FROM
FBB::ClockTypes
FBB::ClockBase
FBB::HighSysClock
these are internally used only classes; their facilities are covered in this man-page.
TYPEDEFS AND ENUMS
o The std::chrono types nanoseconds, microseconds, milliseconds, seconds, minutes and hours are also
available in the namespace FBB;
Clock Types:
o FBB::FileClock provides the std::chrono::file_clock facilities;
o FBB::HighResolutionClock provides the std::chrono::high_resolution_clock facilities;
o FBB::SteadyClock provides the std::chrono::steady_clock facilities;
o FBB::SystemClock provides the std::chrono::system_clock facilities.
Sub-types:
o Duration: each clock type defines the type Duration as std::chrono::duration<int64_t, std::nano>;
o Period: the sub-type period of the Duration type. In practice its subtypes den (DenType) and num
(NumType) are used;
o DenType: the denominator type of the ratio type used by the clock type (see also the static member
den);
o NumType: the numerator type of the ratio type used by the clock type (see also the static member
num);
CONSTRUCTORS
The constructors are illustrated for SystemClock but are also available for the other clock types.
o 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 now member;
o SystemClock(Clock const &otherClock):
each clock type can be initialized with another clock type object (except for a SteadyClock type
object): when constructed they refer to the same points in time.
Copy and move constructors (and assignment operators) are available.
OVERLOADED OPERATORS
Using DurationType to represent std::chrono::duration<int64_t, Ratio>, where Ratio is a std::ratio type
(for clocks Ratio equals nano).
o ClockType &operator+=(DurationType const &amount):
adds amount to the current clock’s TimePoint. E.g.,
SystemClock sc;
sc += 1h;
o ClockType &operator+=(int secs);:
adds secs seconds to the current clock’s TimePoint;
o ClockType &operator-=(DurationType const &amount);:
subtracts amount from the current clock’s TimePoint. Not available for SteadyClock;
o ClockType &operator-=(int secs);:
subtracts secs seconds from the current clock’s TimePoint;
o SteadyClock &operator-=(SteadyClock const &rhs):
only available for class SteadyClock: rhs.elapsed() is subtracted from the current object’s
time-point. See also the functions since and countSince below.
o std::ostream &operator<<(std::ostream &out, ClockType const &clock):
not available for SteadyClock; clock’s (UTC) TimePoint is inserted into out. E.g.,
cout << SystemClock{}; // could insert
// 2025-01-04 08:25:10.035509381
o ClockType operator+(Type1 const &lhs, Type2 const &rhs):
not available for SteadyClock. Either Type1 or Type2 must be an FBB Clock type (like SystemClock).
The other type can either be an int (representing number of seconds) or a DurationType (like
seconds, hours). A clock object of the same type as the Clock argument is returned, whose
TimePoint is initialized to the sum of the argument’s TimePoint and the value of the other
argument;
o ClockType operator-(ClockType const &lhs, Type const &rhs):
both argument types can be SteadyClock. As SteadyClock objects are used for timing purposes this
operator returns a SteadyClock object whose time specification is equal to the difference of the
lhs and rhs time specifications (see also the functions since and countSince below).
Otherwise the lhs argument must be an FBB Clock type (like SystemClock), and Type can either be an
int (representing number of seconds) or a DurationType (like seconds, hours), returning a clock
object whose TimePoint is initialized to the difference of the lhs’s TimePoint and the rhs value;
FREE FUNCTIONS
o auto toClock<DestClock>(ClockType const &clock):
returns the DestClock::TimePoint corresponding to the TimePoint of clock. It is not available for
conversions from or to the SteadyClock type. E.g.,
FileClock fc;
cout << toClock<SystemClock>(fc) << ’\n’;
o double toDouble<Duration>(ClockType const &src):
returns the double value corresponding to ClockType’s std::chrono::duration converted to the
Duration std::chrono::duration. E.g.,
toDouble<hours>(90min); // returns 1.5
o Dest toDuration(Src const &src):
returns src’s Duration converted to the (at least as precise) Dest duration. E.g.,
toDuration<seconds>(1min).count(); // returns 60
ADDITIONAL STEADYCLOCK FREE FUNCTIONS
The SteadyClock type is primarily used for timing purposes. The following two functions are available for
SteadyClock objects:
o SteadyClock::Duration since(SteadyClock const &time0):
The difference in nanoseconds (Durations) of a local SteadyClock object and time0 is returned.
E.g.,
SteadyClock start;
// do something
cout << "Elapsed time: " << since(start) << ’\n’;
o size_t countSince(SteadyClock const &time0):
Same as the previous function, but the number of nanoseconds are returned as a size_t value.
MEMBER FUNCTIONS
All of the following members are available for each of bobcat’s clock types:
o long int count():
returns timePoint’s value. The clock types have members timePoint(): this member returns the
number of nano seconds as an integral value since the beginning of the clock’s era. E.g.,
FileClock{}.clock(); // returns, e.g.,
// -4701673791896351066
o static long int ClockTypes::count(TimePoint const &timePoint):
returns timePoint’s value. This function can also be used for SteadyClock objects. E.g.,
ClockTypes::count(SteadyClock::now()); // returns, e.g.,
// 8310904806233
o static DenType::den():
returns the denominator of the ratio used by the clocks (= 1’000’000’000);
o Duration elapsed() const:
returns the Duration value of the current Clock object (= number of nano-seconds since the
beginning of the clock’s era). E.g.,
SystemClock{}.elapsed(); // returns, e.g.,
// 1735989478991599467ns
o static Duration ClockTypes::elapsed(TimePoint const &timePoint):
returns timePoint’s Duration. Clock types have members timePoint() returning the clock’s time
point;
o static TimePoint max():
returns the TimePoint of the used clock type corresponding to the clock’s maximum (UTC) time.
E.g.,
cout << SystemClock::max(); // inserts:
// 2262-04-11 23:47:16...
o static TimePoint min():
returns the TimePoint of the used clock type corresponding to the clock’s minimum (UTC) time;
o static TimePoint now():
returns the TimePoint of the used clock type corresponding to the current (UTC) time. E.g.,
cout << SystemClock::now() << ’\n’;
o static NumType::num():
returns the numerator of the ratio used by the clocks (= 1);
o static Period period():
returns the clock’s Period (having members den and num);
o TimePoint const &timePoint() const:
returns the object’s TimePoint;
o double toDouble<Dest>() const:
returns the double value corresponding to the object’s std::chrono::duration converted to the Dest
std::chrono::duration. E.g.,
SystemClock{}.toDouble<hours>(); // returns, e.g., 482221
o static Duration zero():
returns the clock’s Duration representing 0 nanoseconds;
ADDITIONAL SYSTEM / HIGHRESOLUTION CLOCK MEMBERS
Primarily for displaying the clock’s time the SystemClock and HighResolutionClock classes support these
members:
o std::time_t timeT() const:
returns the object’s TimePoint converted to time_t (cf. time(3));
o Clock &setTime(std::time_t seconds):
returns the current object after resetting its TimePoint to its time_t argument;
o Clock const &operator()(char const *putTime, bool localTime = true) const:
prepares the current object for the next insertion operator, using the putTime specification to
configure the std::put_time manipulator (cf. 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
false the time is displayed in UTC. When the current object is inserted into a std::ostream after
calling this member the put_time manipulator is used only once. By calling this member again
put_time is repeatedly used. E.g.,
SystemClock sc;
cout << // inserts, e.g.,
sc("%Y") << ’\n’ << // 2025
sc("%y") << ’\n’ << // 25
sc << ’\n’; // 2025-01-04 14:18:47...
EXAMPLE
#include <iostream>
#include <string>
#include <thread>
#include <bobcat/fileclock>
#include <bobcat/highresolutionclock>
#include <bobcat/steadyclock>
#include <bobcat/systemclock>
using namespace std;
using namespace FBB;
int main()
{
SystemClock sysNow{ };
cout << "system clock at " << sysNow << "\n"
"elapsed: " << sysNow.elapsed() << "\n\n";
// same timespec, elapsed ns.
FileClock fileNow{ sysNow }; // is clock-specific
cout << "file clock at " << fileNow << "\n"
"elapsed: " << fileNow.elapsed() << "\n\n";
SystemClock sysNow2{ fileNow };
cout << "system clock at " << sysNow2 << "\n"
"elapsed: " << sysNow2.elapsed() << "\n\n";
cout << sysNow2("%Y %b %d, %H:%M:%S") << "\n"
"\n"
"minimum time: " << sysNow2.min() << "\n"
"maximum time: " << SystemClock::max() << "\n\n";
// conversion to less precise time specification:
cout << "100 minutes is " << toDouble<hours>(100min) << " hours\n\n";
HighResolutionClock hrc{ fileNow };
cout << "high resolution clock at " << hrc << "\n\n";
SteadyClock sc0; // computing ’since’ itself takes several
auto passed = since(sc0); // (variable) hundred nano seconds
cout << "sc0 since: " << passed << ’\n’;
SteadyClock sc;
this_thread::sleep_for(1s);
cout <<
"ELAPSED: " << since(sc) << ’\n’ <<
"(small delay...)\n"
"as count: " << countSince(sc) << "\n\n";
}
FILES
bobcat/fileclock, - the FileClock class interface
bobcat/highresulutionclock - the HighResolutionClock class interface
bobcat/steadyclock - the SteadyClock class interface
bobcat/systemclock - the SystemClock class interface
SEE ALSO
bobcat(7), time(3),
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
Debian Bobcat project files:
o libbobcat6: debian package containing the shared library, changelog and copyright note;
o libbobcat-dev: debian package containing the static library, headers, manual pages, and developer
info;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).
libbobcat-dev_6.07.01 2005-2025 FBB::*Clock(3bobcat)