mirror of
https://github.com/boostorg/date_time.git
synced 2026-02-22 03:12:24 +00:00
311 lines
9.6 KiB
XML
311 lines
9.6 KiB
XML
<section id="date_time.posix_time.time_duration">
|
|
<title>Time Duration</title>
|
|
|
|
<link linkend="time_duration_intro">Introduction</link> --
|
|
<link linkend="time_duration_header">Header</link> --
|
|
<link linkend="time_duration_constr">Construction</link> --
|
|
<link linkend="time_duration_count_constr">Count Based Construction</link> --
|
|
<link linkend="time_duration_from_string">Construct from String</link> --
|
|
<link linkend="time_duration_accessors">Accessors</link> --
|
|
<link linkend="time_duration_to_string">Conversion To String</link> --
|
|
<link linkend="time_duration_operators">Operators</link>
|
|
|
|
<anchor id="time_duration_intro" />
|
|
<bridgehead renderas="sect3">Introduction</bridgehead>
|
|
<para>
|
|
The class boost::posix_time::time_duration the base type responsible for representing a length of time. A duration can be either positive or negative. The general time_duration class provides a constructor that takes a count of the number of hours, minutes, seconds, and fractional seconds count as shown in the code fragment below. The resolution of the time_duration is configureable at compile time. See <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
|
|
</para>
|
|
<para>
|
|
<programlisting>
|
|
using namespace boost::posix_time;
|
|
time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds
|
|
time_duration td(1,2,3,4); //01:02:03.000004 when resolution is micro seconds
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Several small helper classes that derive from a base time_duration, as shown below, to adjust for different resolutions. These classes can shorten code and make the intent clearer.
|
|
</para>
|
|
<imagedata fileref="../../libs/date_time/doc/time_duration_inherit.png" />
|
|
<para>
|
|
As an example:
|
|
<programlisting>
|
|
using namespace boost::posix_time;
|
|
|
|
time_duration td = hours(1) + seconds(10); //01:00:01
|
|
td = hours(1) + nanosec(5); //01:00:00.000000005
|
|
</programlisting>
|
|
Note that the existence of the higher resolution classes (eg: nanosec) depends on the installation of the library. See <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
|
|
</para>
|
|
|
|
<anchor id="time_duration_header" />
|
|
<bridgehead renderas="sect3">Header</bridgehead>
|
|
<para>
|
|
<programlisting>
|
|
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
|
|
or
|
|
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
|
|
</programlisting>
|
|
</para>
|
|
|
|
<anchor id="time_duration_constr" />
|
|
<bridgehead renderas="sect3">Construction</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>time_duration(hours,minutes,seconds,fractional_seconds)</entry>
|
|
<entry>Construct ad duration from the counts</entry>
|
|
<entry>time_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanoseconds</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<anchor id="time_duration_count_constr" />
|
|
<bridgehead renderas="sect3">Count Based Construction</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>hours(long)</entry>
|
|
<entry>Number of hours</entry>
|
|
<entry>time_duration td = hours(3);</entry>
|
|
</row>
|
|
<row>
|
|
<entry>minutes(long)</entry>
|
|
<entry>Number of minutes</entry>
|
|
<entry>time_duration td = minutes(3);</entry>
|
|
</row>
|
|
<row>
|
|
<entry>seconds(long)</entry>
|
|
<entry> Number of seconds</entry>
|
|
<entry>time_duration td = seconds(3);</entry>
|
|
</row>
|
|
<row>
|
|
<entry>millisec(long)</entry>
|
|
<entry>Number of milliseconds.</entry>
|
|
<entry>time_duration td = millisec(3);</entry>
|
|
</row>
|
|
<row>
|
|
<entry>microsec(long)</entry>
|
|
<entry>Number of microseconds.</entry>
|
|
<entry>time_duration td = microsec(3);</entry>
|
|
</row>
|
|
<row>
|
|
<entry>nanosec(long)</entry>
|
|
<entry>Number of nanoseconds.</entry>
|
|
<entry>time_duration td = nanosec(3);</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<anchor id="time_duration_from_string" />
|
|
<bridgehead renderas="sect3">Construct from String</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>time_duration duration_from_string(const std::string&)</entry>
|
|
<entry>From delimited string.</entry>
|
|
<entry>
|
|
std::string ts("23:59:59.000");
|
|
time_duraton td(duration_from_string(ts))
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<anchor id="time_duration_accessors" />
|
|
<bridgehead renderas="sect3">Accessors</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>long hours() const</entry>
|
|
<entry>Get the number of normalized hours.</entry>
|
|
<entry>time_duration td(1,2,3); td.hours() --> 1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>long minutes() const</entry>
|
|
<entry>Get the number of minutes normalized (0..59).</entry>
|
|
<entry>time_duration td(1,2,3); td.minutes() --> 2</entry>
|
|
</row>
|
|
<row>
|
|
<entry>long seconds() const</entry>
|
|
<entry>Get the normalized number of second (0..59).</entry>
|
|
<entry>time_duration td(1,2,3); td.seconds() --> 3</entry>
|
|
</row>
|
|
<row>
|
|
<entry>long total_seconds() const</entry>
|
|
<entry>Get the total number of seconds truncating any fractional seconds.</entry>
|
|
<entry>
|
|
time_duration td(1,2,3,10);
|
|
td.total_seconds() --> (1*3600) + (2*60) + 3 == 3723
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>long fractional_seconds() const</entry>
|
|
<entry>Get the number of fractional seconds.</entry>
|
|
<entry>time_duration td(1,2,3, 1000); td.fractional_seconds() --> 1000</entry>
|
|
</row>
|
|
<row>
|
|
<entry>bool is_negative() const</entry>
|
|
<entry>True if duration is negative.</entry>
|
|
<entry>time_duration td(-1,0,0); td.is_negative() --> true</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time_duration invert_sign() const</entry>
|
|
<entry>Generate a new duration with the sign inverted/</entry>
|
|
<entry>time_duration td(-1,0,0); td.invert_sign() --> 01:00:00</entry>
|
|
</row>
|
|
<row>
|
|
<entry>static boost::date_time::time_resolutions resolution()</entry>
|
|
<entry>Describes the resolution capability of the time_duration class.</entry>
|
|
<entry>time_duration::resolution() --> nano</entry>
|
|
</row>
|
|
<row>
|
|
<entry>boost::int64_t ticks()</entry>
|
|
<entry>Return the raw count of the duration type.</entry>
|
|
<entry>time_duration td(0,0,0, 1000); td.ticks() --> 1000</entry>
|
|
</row>
|
|
<row>
|
|
<entry>static time_duration unit()</entry>
|
|
<entry>Return smallest possible unit of duration type (1 nanosecond).</entry>
|
|
<entry>time_duration::unit() --> time_duration(0,0,0,1)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<anchor id="time_duration_to_string" />
|
|
<bridgehead renderas="sect3">Conversion To String</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>std::string to_simple_string(time_duration)</entry>
|
|
<entry>To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero.</entry>
|
|
<entry>10:00:01.123456789</entry>
|
|
</row>
|
|
<row>
|
|
<entry>std::string to_iso_string(time_duration)</entry>
|
|
<entry>Convert to form HHMMSS,fffffffff.</entry>
|
|
<entry>100001,123456789</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<anchor id="time_duration_operators" />
|
|
<bridgehead renderas="sect3">Operators</bridgehead>
|
|
<para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
operator==, operator!=,
|
|
operator>, operator<
|
|
operator>=, operator<=
|
|
</entry>
|
|
<entry>A full complement of comparison operators</entry>
|
|
<entry>dd1 == dd2, etc</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time_duration operator+(time_duration) const</entry>
|
|
<entry>Add durations.</entry>
|
|
<entry>
|
|
time_duration td1(hours(1)+minutes(2));
|
|
time_duration td2(seconds(10));
|
|
time_duration td3 = td1 + td2;
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time_duration operator-(time_duration) const</entry>
|
|
<entry>Subtract durations.</entry>
|
|
<entry>
|
|
time_duration td1(hours(1)+nanosec(2));
|
|
time_duration td2 = td1 - minutes(1);
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time_duration operator/(int) const</entry>
|
|
<entry>Divide the length of a duration by an integer value. Discards any remainder.</entry>
|
|
<entry>
|
|
hours(3)/2 == time_duration(1,30,0);
|
|
nanosec(3)/2 == nanosec(1)
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time_duration operator*(int) const</entry>
|
|
<entry>Multiply the length of a duration by an integer value.</entry>
|
|
<entry>hours(3)*2 == hours(6);</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
|
|
<link linkend="top">top</link>
|
|
</section>
|