Stroika::Foundation::Time::Duration Class Reference

Duration is a chrono::duration<double> (=. More...

#include <Duration.h>

Inherits chrono::duration< double >.

Public Member Functions
constexpr	Duration ()
nonvirtual Duration &	operator+= (const Duration &rhs)
template<typename T > requires (Common::IAnyOf<T, timeval, Characters::String> or integral<T> or floating_point<T> or Common::IDuration<T> or Common::ITimePoint<T>)
nonvirtual T	As () const
template<typename T > requires (same_as<T, timeval> or integral<T> or floating_point<T> or same_as<T, Characters::String> or Common::IDuration<T> or Common::ITimePoint<T>)
nonvirtual T	AsPinned () const
nonvirtual u8string	AsUTF8 () const
nonvirtual Characters::String	PrettyPrint (const PrettyPrintInfo &prettyPrintInfo=kDefaultPrettyPrintInfo) const
nonvirtual Characters::String	Format (const PrettyPrintInfo &prettyPrintInfo=kDefaultPrettyPrintInfo) const
	like javascript 'humanize' APIs
nonvirtual Characters::String	PrettyPrintAge (const AgePrettyPrintInfo &agePrettyPrintInfo=kDefaultAgePrettyPrintInfo, const PrettyPrintInfo &prettyPrintInfo=kDefaultPrettyPrintInfo) const
nonvirtual Characters::String	ToString () const
nonvirtual Duration	operator- () const

Static Public Member Functions
static constexpr Duration	min ()
static constexpr Duration	max ()

Detailed Description

Duration is a chrono::duration<double> (=.

See also

DurationSeconds) - but adding ISO-8601 string representation support

(basic) support for ISO 8601 Durations http://en.wikipedia.org/wiki/ISO_8601#Durations

Note: according to glibc docs - year is always 365 days, month always 30 days, etc, as far as these duration objects go - at least for conversion to/from time_t. Seek a better reference for this claim!

Note also - there are two iso 8601 duration formats - one date like (YYYY-MM....) and this one P...T...3S). As far as I know - XML always uses the later. For now - this implementation only supports the later.

See also

http://bugzilla/show_bug.cgi?id=468

This class is roughly equivalent to the .Net Timespan class, and also might be called "time period", or "timespan".

Note that a Duration may be negative.

It is best to logically think of Duration as a number of seconds (perhaps lossily) since for comparisons that's how things are normalized. #days etc are dumbed down to number of seconds for comparison sakes.

Note

constexpr not really working (though declared) - see

Note

Reason Duration functionality not merged into DurationSeconds (why two separate types): Duration maintains the ability to recover the original string (in case conversion to float loses precision) - so Duration{"PT2.3M"} always returns that - As<String> () value, even if its converted to something else; DurationSeconds is more lightweight (and constexpr friendly).

Design Note - why no c_str () method In order to implement c_str () - we would need to return an internal pointer. That would constrain the internal implementation, and would need careful definition of lifetime. The simplest way around this is to have the caller pass something in, or to return something whose lifetime is controlled (an object). So now - just call As<String> ().c_str () or As<wstring> ().c_str ()

Comparisons: o static_assert (totally_ordered<Duration>);

Definition at line 96 of file Duration.h.

Constructor & Destructor Documentation

Duration()

constexpr Stroika::Foundation::Time::Duration::Duration ( )

constexpr

The character set of the std::string CTOR is expected to be all ascii, or the code throws FormatException

Throws (FormatException) if bad format

Note

constexpr not really working (though declared) - see

Note

for numeric overloads, require (not isnan (src)) - but allow isinf()

Definition at line 20 of file Duration.inl.

Member Function Documentation

operator+=()

Duration & Duration::operator+=

(

const Duration &

rhs

)

Add the given duration to this (equivalent to *this = *this + rhs;).

Definition at line 65 of file Duration.cpp.

As()

template<typename T >
requires (Common::IAnyOf<T, timeval, Characters::String> or integral<T> or floating_point<T> or Common::IDuration<T> or Common::ITimePoint<T>)

nonvirtual T Stroika::Foundation::Time::Duration::As

(

)

const

Only specifically specialized variants are supported. Defined for o timeval o integral<T> o floating_point<T> o String o Common::IDuration<T> o Common::ITimePoint<T>

Note this implies inclusion of: o time_t o int, float, etc... o std::chrono::milliseconds etc...

Note - if 'empty' - As<> for numeric types returns 0.

Note

Precision - if given - refers to the precision of the seconds part of the ISO-8601 duration string.

Change since before 3.0d12 - with Duration::As<String> () - used to default to full precision, and now defaults to default precision (FloatConversions::Precision{} == 6).

@todo unsafe if value out of range - decode how to handle - probably should throw if out of range, but unclear - see AsPinned()

\note Stroika v2.1 also supported wstring, which was (tentatively) de-supported in Stroika v3.0d5

AsPinned()

template<typename T >
requires (same_as<T, timeval> or integral<T> or floating_point<T> or same_as<T, Characters::String> or Common::IDuration<T> or Common::ITimePoint<T>)

nonvirtual T Stroika::Foundation::Time::Duration::AsPinned

(

)

const

See also

As<T>, but automatically takes care of pinning values so always safe and in range.

Same as As<> - except that it handles overflows, so if you pass in Duration {numeric_limits<long double>::max ()} and convert to seconds, you wont overflow, but get chrono::seconds::max

@todo same requires stuff as we have with As<T>()

AsUTF8()

u8string Stroika::Foundation::Time::Duration::AsUTF8

(

)

const

Shorthand for As<String> ().AsUTF8 ()

Definition at line 103 of file Duration.inl.

PrettyPrint()

String Duration::PrettyPrint

(

const PrettyPrintInfo &

prettyPrintInfo = kDefaultPrettyPrintInfo

)

const

Consider deprecating, and using 'Format'

Definition at line 105 of file Duration.cpp.

Format()

Characters::String Stroika::Foundation::Time::Duration::Format

(

const PrettyPrintInfo &

prettyPrintInfo = kDefaultPrettyPrintInfo

)

const

like javascript 'humanize' APIs

Example Usage

Assert (Duration{3}.Format () == "3 seconds")

Definition at line 276 of file Duration.inl.

PrettyPrintAge()

String Duration::PrettyPrintAge	(	const AgePrettyPrintInfo &	agePrettyPrintInfo = kDefaultAgePrettyPrintInfo,
		const PrettyPrintInfo &	prettyPrintInfo = kDefaultPrettyPrintInfo
	)		const

Inspired by useful JQuery plugin http://ksylvest.github.io/jquery-age/; or https://momentjs.com/

Technically, this isn't an 'age' but just a 'now-centric' pretty printing of durations.

Example Usage

EXPECT_EQ (Duration{"PT1.4S"}.PrettyPrintAge (), "now");
EXPECT_EQ (Duration{"-PT9M"}.PrettyPrintAge (), "now");
EXPECT_EQ (Duration{"-PT20M"}.PrettyPrintAge (), "20 minutes ago");
EXPECT_EQ (Duration{"PT20M"}.PrettyPrintAge (), "20 minutes from now");
EXPECT_EQ (Duration{"PT4H"}.PrettyPrintAge (), "4 hours from now");

Definition at line 282 of file Duration.cpp.

ToString()

Characters::String Stroika::Foundation::Time::Duration::ToString

(

)

const

See also

Characters::ToString ();

Definition at line 280 of file Duration.inl.

min()

constexpr Duration Stroika::Foundation::Time::Duration::min ( )

staticconstexpr

Duration::kMin is the least duration this Duration class supports representing.

Definition at line 284 of file Duration.inl.

max()

constexpr Duration Stroika::Foundation::Time::Duration::max ( )

staticconstexpr

Duration::kMax is the largest duration this Duration class supports representing

Definition at line 288 of file Duration.inl.

operator-()

Duration Duration::operator-

(

)

const

Unary negation

Definition at line 322 of file Duration.cpp.

---

The documentation for this class was generated from the following files:

• Duration.h
• Duration.cpp
• Duration.inl