eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'TimeDuration':
Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: TimeDuration

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractTime
         |
         +--Time
            |
            +--TimeDuration
Package:
stx:libbasic
Category:
Magnitude-Time
Version:
rev: 1.132 date: 2019/08/09 14:28:17
user: cg
file: TimeDuration.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


Represents a time/timestamp difference.

The resolution is 1 ps.
However, such small timedurations are usually only created by physical computations
(see goodies/physic).
The typical OS-time resolution is in the milli- or microsecond range.
External logging hardware may generate timestamps in the micro- or nanosecond range.
Picosecond resolution should be good enough for almost any application (at least for the near future).

Most timedurations only require/have millisecond resolution,
so the pico instvar is nil/0 and does not require an aditional largeInteger operation.

DefaultFormatForPrinting    if non-nil, allows for the variable printFormat to be overwritten

Class protocol:

class initialization
o  initialize
(comment from inherited method)
called only once - initialize signals

constants
o  zero
return the neutral element for addition (0s)

format strings
o  defaultFormatForPrinting

o  defaultFormatForPrinting: aString

o  formatString12us
return the format string used to format US times (and other areas)

o  formatString24
return the format string used to format european times (and other areas)

instance creation
o  days: d
return a new TimeDuration representing a duration of d days.

usage example(s): 

     TimeDuration days:1

o  days: d hours: h minutes: m seconds: s
return a new TimeDuration representing a duration of d days, h hours, m minutes and s seconds.
See also Time now / Date today / Timestamp now.

usage example(s): 

     TimeDuration days:1  hours:2 minutes:33 seconds:0   
     TimeDuration days:4 hours:100 minutes:33 seconds:0

o  fromHours: hoursInterval
return a new TimeDuration representing a duration of n hours.

usage example(s): 

     TimeDuration fromHours:8

o  fromMicroseconds: n
return a new TimeDuration representing a duration of n microseconds.

usage example(s): 

     TimeDuration fromMicroseconds:500  
     500 microseconds

o  fromMilliseconds: n
return a new TimeDuration representing a duration of n milliseconds.

usage example(s): 

     TimeDuration fromMilliseconds:500  
     500 milliseconds

o  fromMinutes: minutesInterval
return a new TimeDuration representing a duration of n minutes.

usage example(s): 

     TimeDuration fromMinutes:120

o  fromNanoseconds: n
return a new TimeDuration representing a duration of n nanoseconds.

usage example(s): 

     TimeDuration fromNanoseconds:500  
     500 nanoseconds

o  fromPicoseconds: n
return a new TimeDuration representing a duration of n picoseconds.

usage example(s): 

     TimeDuration fromPicoseconds:500  
     500 picoseconds

o  fromSeconds: secondsInterval
return a new TimeDuration representing a duration of n seconds.

usage example(s): 

     TimeDuration fromSeconds:3600

o  hours: h
return a new TimeDuration representing a duration of h hours.
See also Time now / Date today / Timestamp now.

usage example(s): 

     TimeDuration hours:2 
     TimeDuration hours:100

o  hours: h minutes: m seconds: s millis: millis
return a new TimeDuration representing a duration of h hours, m minutes, s seconds and millis milliseconds.
See also Time now / Date today / Timestamp now.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  microseconds: microseconds
return a new TimeDuration representing a duration of microseconds microseconds.
Now we support microseconds (even picoseconds) but we still round to milliseconds for backward
compatibility with the historic interface.

usage example(s): 

     TimeDuration microseconds:2499 
     TimeDuration microseconds:2500 
     TimeDuration microseconds:12345678900

o  milliseconds: m
return a new TimeDuration representing a duration of m millis.
See also Time now / Date today / Timestamp now.

usage example(s): 

     TimeDuration milliseconds:2

o  minutes: m
return a new TimeDuration representing a duration of m minutes.
See also Time now / Date today / Timestamp now.

usage example(s): 

     TimeDuration minutes:2

o  readFrom: aStringOrStream defaultUnit: defaultUnitOrNilArg onError: exceptionBlock
return a new TimeDuration, reading a printed representation from aStream.
The format is either:
[n 'yr'] [n 'mon'] [n 'w'] [n 'd'] [n 'h'] [n 'm'] [n 's']
([n 'ms'] | [n 'us'] | [n 'ns'] | [n 'ps'])
where
yr -> year
mon -> month
w -> week
d -> day
h -> hour
m -> minutes
s -> seconds
ms -> milliseconds (only one of ms,us,ns or ps can follow)
us -> microseconds
ns -> nanoseconds
ps -> picoseconds
or:
h:m:s.<ms2>
h:m:s.<fract>

The yr and mon specifiers stand for 365d and 30d respectively.
If defaultUnitOrNil is non-nil, a plain number is treated as that;
otherwise, a plain number raises an error.
Individual components may be negative, as in '1h -10m', which gives 50m
or the whole duration may be negative, as in '-(1h 10m)'

usage example(s): 

     TimeDuration readFrom:'2' defaultUnit:$h onError:nil -> 2h
     TimeDuration readFrom:'100' defaultUnit:$m onError:nil -> 1h 40m
     TimeDuration readFrom:'100' defaultUnit:$s onError:nil -> 1m 40s
     TimeDuration readFrom:'0200' defaultUnit:$h onError:nil -> 1w 1d 8h

     TimeDuration readFrom:'1h'      
     TimeDuration readFrom:'1h 35m'     
     TimeDuration readFrom:'25h'     
     TimeDuration readFrom:'3d'     
     TimeDuration readFrom:'1w'     
     TimeDuration readFrom:'120s'     
     TimeDuration readFrom:'1500ms'    
     TimeDuration readFrom:'3ms'     
     TimeDuration readFrom:'1yr 5d'     
     TimeDuration readFrom:'1mon'     
     TimeDuration readFrom:'05:10'     
     TimeDuration readFrom:'05:10:5'     
     TimeDuration readFrom:'05:10:5.150'  

     TimeDuration readFrom:'-1h'
     TimeDuration readFrom:'-1h 10m'
     TimeDuration readFrom:'1h -10m'
     TimeDuration readFrom:'-(1h 10m)' 

     TimeDuration readFrom:'1ms' -> 1ms 
     TimeDuration readFrom:'5us' 
     TimeDuration readFrom:'5µs' 
     TimeDuration readFrom:'5ns' 
     TimeDuration readFrom:'5ps' 
     TimeDuration readFrom:'5005 ps' 
     TimeDuration readFrom:'1.01 s' -> 1.010s 
     TimeDuration readFrom:'1.001 s' -> 1.001s 
     TimeDuration readFrom:'1.0001 s' -> 1.0001s 
     TimeDuration readFrom:'1s 5ns' -> 1.000000005s
     (TimeDuration readFrom:'1s 5ns') = (TimeDuration fromNanoseconds:(5+1000000000))

     TimeDuration readFrom:(TimeDuration new storeString)

o  readFrom: aStringOrStream onError: exceptionBlock
return a new TimeDuration, reading a printed representation from aStream.
The format is [n 'yr'] [n 'mon'] [n 'w'] [n 'd'] [n 'h'] [n 'm'] [n 's'] [n 'ms']
where
yr -> year
mon -> month
w -> week
d -> day
h -> hour
m -> minutes
s -> seconds
ms -> milliseconds
The yr and mon specifiers stand for 365d and 30d respectively.
If no unit is given (i.e. a plain number string is given), assume seconds.

usage example(s): 

     TimeDuration readFrom:'100' onError:nil      
     TimeDuration readFrom:'100' defaultUnit:$m onError:nil 

     TimeDuration readFrom:'1h'      
     TimeDuration readFrom:'1h 35m'     
     TimeDuration readFrom:'25h'     
     TimeDuration readFrom:'3d'     
     TimeDuration readFrom:'1w'     
     TimeDuration readFrom:'120s'     
     TimeDuration readFrom:'1500ms    
     TimeDuration readFrom:'3ms'     
     TimeDuration readFrom:'1yr 5d'     
     TimeDuration readFrom:'1mon'

o  seconds: s
return a new TimeDuration representing a duration of s seconds.
See also Time now / Date today / Timestamp now.

usage example(s): 

     TimeDuration seconds:2

o  weeks: w
return a new TimeDuration representing a duration of w weeks.

usage example(s): 

     TimeDuration weeks:1

o  years: y
return a new TimeDuration representing a duration of y years.

usage example(s): 

     TimeDuration years:1

timing evaluation
o  toRun: aBlock
return the TimeDuration it takes to execute aBlock.
A modern variant of Time millisecondsToRun: (which prints itself nicely)

usage example(s): 

     TimeDuration toRun:[ 20000 factorial ]     
     TimeDuration toRun:[ 2000 factorial ]     
     TimeDuration toRun:[ 900 factorial ]

Instance protocol:

Compatibility-Squeak
o  wait
wait the receiver's timeDuration

usage example(s): 

     5 seconds wait

accessing
o  days
get the (truncated) total number of days.
Use this only for printing.
Sigh: this is inconsistent: hours, minutes, seconds etc.
return the fraction, not the total

usage example(s): 

     (Duration fromString:'1mon 1d 4h 3m 5s 10ms') days

     (Duration days:9 hours:1 minutes:2 seconds:3) days   
     (Duration days:-9 hours:-1 minutes:-2 seconds:-3) days

o  hours
get the (truncated) number of hours.
notice: that is NOT the total number of hours,
but the fractional part only.
Use this only for printing

usage example(s): 

     (Duration fromString:'1d 4h 3m 5s 10ms') hours
     (Duration fromString:'1d 4h 3m 1s 10ms') getHours

     (Duration days: 9 hours: 1 minutes: 2 seconds: 3) hours
     (Duration days: -9 hours: -1 minutes: -2 seconds: -3) hours

o  milliseconds
get the milliseconds part
notice: that is NOT the total number of millis,
but the fractional part (within the second) only.
Use this only for printing.
asMilliseconds is probably what you want

usage example(s): 

     (Duration milliseconds:10) milliseconds
     (Duration milliseconds:-10) milliseconds

     (Duration fromString:'1s 10ms') milliseconds
     (Duration fromString:'1s 10ms') getMilliseconds

o  minutes
get the number of minutes.
notice: that is NOT the total number of minutes,
but the fractional part only.
Use this only for printing

usage example(s): 

     (Duration fromString:'1h 3m 5s 10ms') minutes
     (Duration fromString:'1h 3m 1s 10ms') getMinutes

     (Duration days: 9 hours: 1 minutes: 2 seconds: 3) minutes
     (Duration days: -9 hours: -1 minutes: -2 seconds: -3) minutes

o  picoseconds
get the optional additional picoseconds (0..999999999)
notice: that is NOT the total number of picoseconds,
but the fractional part (within the second) only.
Use this only for printing.

o  seconds
get the number of seconds.
notice: that is NOT the total number of seconds,
but the fractional part only.
Use this only for printing.
asSeconds is probably what you want

usage example(s): 

     (Duration fromString:'1m 5s 10ms') seconds
     (Duration fromString:'1m 1s 10ms') getSeconds

     (Duration days: 9 hours: 1 minutes: 2 seconds: 3) seconds
     (Duration days: -9 hours: -1 minutes: -2 seconds: -3) seconds

arithmetic
o  * aNumber
return a new scaled timeDuration

usage example(s): 

     5 c* (TimeDuration fromString:'10s')

     (TimeDuration fromString:'10s') * 5
     (TimeDuration fromString:'10s') * 10
     (TimeDuration fromString:'10s') * 100
     (TimeDuration fromString:'10s') * 1000
     (TimeDuration fromString:'-10s') * 1000
     (TimeDuration fromString:'10s') * (TimeDuration fromString:'10s')

     (TimeDuration fromString:'10ms') * 5
     (TimeDuration fromString:'10us') * 5

o  + aTimeDurationOrNumberOfSeconds
return a new timeDuration.
The argument may be a timeDuration or
a number, which is interpreted as seconds.

usage example(s): 

     (TimeDuration fromString:'1m') + (TimeDuration fromString:'10s') 
     1 minutes - 10 seconds

o  - aTimeDurationOrNumberOfSeconds
return a new timeDuration.
The argument may be a timeDuration or
a number, which is interpreted as seconds.

usage example(s): 

     (TimeDuration fromString:'1m') - (TimeDuration fromString:'10s') 
     1 minutes - 10 seconds

o  / aTimeDurationOrNumberOfSeconds
if the argument is a number, return a new timeDuration.
Otherwise, return the quotient as a number.

usage example(s): 

there are additional packages which add support (i.e. goodies/physic),

usage example(s): 

     (TimeDuration fromString:'10s') / (TimeDuration fromString:'5s')
     (TimeDuration fromString:'10s') / 5

usage example(s): 

Modified (format): / 27-07-2018 / 10:38:07 / Stefan Vogel

o  // aTimeDurationOrNumberOfSeconds
if the argument is a number, return a new timeDuration.
Otherwise, return the quotient as a number.

usage example(s): 

     (TimeDuration fromString:'10s') // (TimeDuration fromString:'3')
     (TimeDuration fromString:'10s') // 3

     (TimeDuration fromString:'10s') / (TimeDuration fromString:'3')
     (TimeDuration fromString:'10s') / 3

o  abs
(TimeDuration fromSeconds:3600) abs
(TimeDuration fromSeconds:-3600) abs

(TimeDuration fromSeconds:20000) abs
(TimeDuration fromSeconds:-20000) abs

o  negated
50 nanoseconds negated asNanoseconds
1 seconds negated asSeconds

o  squared
answer a float representing my value in seconds - squared.
Used to compute e.g. variance and standard deviation.

usage example(s): 

     50 nanoseconds squared 
     1 seconds squared

comparing
o  < something
(comment from inherited method)
return true if the receiver is before the argument

o  = something
(comment from inherited method)
return true if the receiver is before or the same time as the argument

o  hash
(comment from inherited method)
return an integer useful for hashing on times

converting
o  asExactHours
answer the duration as hours.
In contrast to asTruncatedHours, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     (2 hours + 10 minutes + 30 seconds) asExactHours
     (2 hours + 10 minutes + 30 seconds) asExactHours asFloat
     (2 hours + 10 minutes + 30 seconds) asTruncatedHours
     (2 hours + 10 minutes) asExactHours asFloat
     (2 hours + 10 minutes) asTruncatedHours
     10 milliseconds asExactHours 
     10 milliseconds asExactHours asFloat

o  asExactMicroseconds
return the exact number of mcroseconds.
In contrast to asMicroSeconds, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     40 milliseconds asExactMicroseconds
     40 microseconds asExactMicroseconds
     40 nanoseconds asExactMicroseconds
     40 picoseconds asExactMicroseconds

o  asExactMilliseconds
return the exact number of milliseconds.
In contrast to asMilliSeconds, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     40 milliseconds asExactMilliseconds
     40 microseconds asExactMilliseconds
     40 nanoseconds asExactMilliseconds
     40 picoseconds asExactMilliseconds

o  asExactMinutes
answer the duration as minutes.
In contrast to asTruncatedMinutes, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     (2 hours + 10 minutes + 30 seconds) asExactMinutes
     (2 hours + 10 minutes + 30 seconds) asExactMinutes asFloat
     (2 hours + 10 minutes + 30 seconds) asTruncatedMinutes
     (2 hours + 10 minutes) asExactMinutes
     (2 hours + 10 minutes) asTruncatedMinutes
     10 milliseconds asExactMinutes 
     10 milliseconds asExactMinutes asFloat

o  asExactNanoseconds
return the exact number of nanoseconds.
In contrast to asNanoSeconds, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     40 milliseconds asExactNanoseconds
     40 microseconds asExactNanoseconds
     40 nanoseconds asExactNanoseconds
     40 picoseconds asExactNanoseconds

o  asExactSeconds
return the exact number of seconds.
In contrast to asSeconds, which returns them truncated,
this may return a non-integer value.

usage example(s): 

     1.5 seconds asExactSeconds
     40 seconds asExactSeconds
     40 milliseconds asExactSeconds
     40 microseconds asExactSeconds
     40 nanoseconds asExactSeconds

o  asFixedPoint
answer the duration in seconds as a fixedPoint number.
This method has a bad name (a historic leftover);
Please change any sender to use secondsAsFixedPoint

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asFixedPoint: scale
answer the duration in seconds as a fixedPoint number with given scale.
This method has a bad name (a historic leftover);
Please change any sender to use secondsAsFixedPoint

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asFloat
answer the duration in seconds as a float.
This method has a bad name (a historic leftover);
Please change any sender to use secondsAsFloat

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asFraction
answer the duration in seconds as a fraction
(might return an integer, if the duration is an exact multiple
of millis).
This method has a bad name (a historic leftover);
Please change any sender to use secondsAsFraction

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asInteger
answer the duration as (truncated) integer seconds.
Better use the explicit asTruncatedSeconds

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asLongFloat
answer the duration as longfloat seconds.
This method has a bad name (a historic leftover);
Please change any sender to use secondsAsFloat

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asMicroseconds
answer the duration as microseconds (truncated).
Values smaller than 1 us will be returned as 0

usage example(s): 

     100 nanoseconds asTruncatedMicroseconds
     100 nanoseconds asExactMicroseconds

     10 milliseconds asMicroseconds
     1.5 milliseconds asMicroseconds
     10 seconds asMicroseconds

o  asMilliseconds
answer the duration as milliseconds (truncated).
Values smaller than 1 ms will be returned as 0

usage example(s): 

     10 microseconds asTruncatedMilliseconds
     10 microseconds asExactMilliseconds
     10 microseconds asMilliseconds

     10 milliseconds asMilliseconds
     10 seconds asMilliseconds

o  asNanoseconds
answer the duration as nanoseconds (truncated).
Values smaller than 1 ns will be returned as 0

o  asNumber
answer the duration as seconds.
This method has a bad name (a historic leftover);
Please change any sender to use asTruncatedSeconds or
asExactSeconds, depending on what is wanted.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  asPicoseconds
answer the duration as picoseconds (truncated).
Because the smallest representable timeDuration is 1ps,
there is no distinction between truncated and exact picos.

o  asSeconds
answer the duration as seconds (truncated).
Values smaller than 1 s will be returned as 0.

To get the exact number, use asExactSeconds.
Please change senders to use asTruncatedSeconds
to make this truncation explicit (and obvious when reading code).
For compatibility (both backward and with other smalltalks),
asSeconds returns the TRUNCATED integer value
(many senders assume that an integer is returned)

usage example(s): 

     10 milliseconds asSeconds
     10 nanoseconds asSeconds
     10 milliseconds asExactSeconds
     10 nanoseconds asExactSeconds
     2 minutes asSeconds

o  asTimeDuration
return a TimeDuration object from the receiver - that's the receiver.

o  asTruncatedHours
answer the duration as hours (truncated).
Values smaller than 1 h will be returned as 0.

To get the exact number, use asExactHours.

usage example(s): 

     (2 hours + 10 minutes) asTruncatedHours
     (2 hours + 10 minutes + 30 seconds) asTruncatedHours
     2 minutes asTruncatedHours
     10 milliseconds asTruncatedHours

o  asTruncatedMicroseconds
answer the duration as microseconds (truncated).
Values smaller than 1 us will be returned as 0.
This is the total number of microseconds - not just the fractional part

usage example(s): 

     100 nanoseconds asTruncatedMicroseconds
     100 nanoseconds asExactMicroseconds

     10 milliseconds asTruncatedMicroseconds
     10 seconds asTruncatedMicroseconds

o  asTruncatedMilliseconds
answer the duration as milliseconds (truncated).
Values smaller than 1 ms will be returned as 0.
This is the total number of milliseconds - not just the fractional part

usage example(s): 

     0.1 milliseconds asTruncatedMilliseconds
     0.1 milliseconds asExactMilliseconds

     10 milliseconds asMilliseconds
     10 seconds asMilliseconds

o  asTruncatedMinutes
answer the duration as minutes (truncated).
Values smaller than 1 m will be returned as 0.

To get the exact number, use asExactMinutes.

usage example(s): 

     (2 hours + 10 minutes) asTruncatedMinutes
     (2 hours + 10 minutes + 30 seconds) asTruncatedMinutes
     2 minutes asTruncatedMinutes
     10 milliseconds asTruncatedMinutes

o  asTruncatedNanoseconds
answer the duration as nanoseconds (truncated).
Values smaller than 1 ns will be returned as 0.
This is the total number of nanoseconds - not just the fractional part

usage example(s): 

     10 picoseconds asTruncatedNanoseconds
     10 picoseconds asExactNanoseconds

     10 milliseconds asTruncatedNanoseconds
     10 seconds asTruncatedNanoseconds

o  asTruncatedSeconds
answer the duration as seconds (truncated).
Values smaller than 1 s will be returned as 0.
This is the total number of seconds - not just the fractional part.
To get the exact number, use asExactSeconds.

usage example(s): 

     10 milliseconds asTruncatedSeconds
     10 milliseconds asExactSeconds
     2 minutes asTruncatedSeconds

o  secondsAsFixedPoint
answer the duration in seconds as a fixedPoint number.

usage example(s): 

     (10 milliseconds) secondsAsFixedPoint
     (10 milliseconds) secondsAsFixedPoint asFixedPoint:3

o  secondsAsFixedPoint: scale
answer the duration in seconds as a fixedPoint number with given scale.

o  secondsAsFloat
answer the duration in seconds as a float.

usage example(s): 

     (1000 milliseconds) secondsAsFloat
     (10 milliseconds) secondsAsFloat
     (10 microseconds) secondsAsFloat
     (10 nanoseconds) secondsAsFloat
     (1000001 microseconds) secondsAsFloat

o  secondsAsFraction
answer the duration in seconds as a fraction
(might return an integer, if the duration is an exact multiple
of millis).

usage example(s): 

     (1000 milliseconds) secondsAsFraction
     (10 milliseconds) secondsAsFraction
     (10 microseconds) secondsAsFraction
     (10 nanoseconds) secondsAsFraction
     (1000001 microseconds) secondsAsFraction asFloat

o  secondsAsLongFloat
answer the duration as longfloat seconds.

usage example(s): 

     (10 milliseconds) secondsAsLongFloat
     (10 microseconds) secondsAsLongFloat
     (10 nanoseconds) secondsAsLongFloat
     (1000001 microseconds) secondsAsLongFloat

double dispatching
o  differenceFromInteger: anInteger
treat the integer as a number of seconds.
Might be questionable, but adding integers to timeDurations is also allowed,
and addition is kommutative...
...maybe mixing should be forbidden.

o  differenceFromTimeDuration: aTimeDuration
return a new timeDuration

o  differenceFromTimestamp: aTimestamp
return the timestamp this timeDuration before aTimestamp

o  productFromFloat: aFloat
sent when aFloat does not know how to multiply the receiver.
Return a new timeDuration

o  productFromFraction: aFraction
sent when aFraction does not know how to multiply the receiver.
Return a new timeDuration

o  productFromInteger: anInteger
sent when an integer does not know how to multiply the receiver

o  productFromNumber: aNumber
sent when an integer does not know how to multiply the receiver.
Return a new timeDuration

o  productFromTimeDuration: aTimeDuration
return a new timeDuration

o  sumFromInteger: anInteger
treat the integer as a number of seconds.
Might be questionable, but adding integers to timeDurations is also allowed,
and addition is kommutative...
...maybe mixing should be forbidden.

o  sumFromTimeDuration: aTimeDuration
return a new timeDuration

o  sumFromTimestamp: aTimestamp
return the timestamp this timeDuration after aTimestamp

inspecting
o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

printing
o  addPrintBindingsTo: aDictionary language: languageOrNil
private print support: add bindings for printing to aDictionary.
languageOrNil can only be #en or nil for the current language.

Additional formats available here (for timeDuration) are:
%(Hd) hours in day (i.e. 0..23)
%(hd) hours in day padded to 2 chars (i.e. 00..23)

%(yrR) years rounded (i.e. for 730 days, we get 2 asFixedPoint:1 )
%(monR) month rounded (i.e. for 45 days, we get 1.5 asFixedPoint:1 )
%(w) weeks
%(wR) weeks rounded (i.e. for 45 days, we get 6.xxx asFixedPoint:1 )
%(dR) days rounded (i.e. for 36 hours, we get 1.5 asFixedPoint:1 )
%(dw) days in week (rest days after taking out the weeks)
%(hR) hours rounded (i.e. for 3h 30m, we get 3.5 asFixedPoint:1 )
%(mR) minutes rounded (i.e. for 2m 30s, we get 2.5 asFixedPoint:1 )
%(sR) seconds rounded to 1 postDecimal (i.e. for 2s 100ms, we get 2.1 asFixedPoint:1 )

o  formatForApproximatePrinting
Return a format which is suitable for a human - not meant to be read back.
In contrast to the regular format, this one only gives a rounded approximation
of the time duration as useful in information-dialogs or other user-hint-GUI elements.
For example, in a timeDuration of more than 2hours, the user might not be interested in
individual seconds or even milliseconds.
The way this is done is pure magic heuristics - let me know, if you have a better algorithm.

o  formatForPrinting
Return the format for printing

usage example(s): 

     (TimeDuration readFrom:'10h 3s') formatForPrinting  
     (TimeDuration readFrom:'3s') formatForPrinting      
     (TimeDuration readFrom:'1d 2ms') formatForPrinting      
     (TimeDuration readFrom:'1 week') formatForPrinting

o  formatForShortPrinting
Return the short format for printing (without ms)

o  printAsApproximationOn: aStream
append a human readable printed representation of the receiver to aStream.
The format is meant for a human and does not give all information;
especially, useless detail is hidden.
This means, that seconds are rounded or hidden, if the dT is more than a few minutes;
minutes rounded into the hour or hidden, if it's more than a few hours etc.
The way this is done is pure magic heuristics - let me know, if you have a better algorithm.

usage example(s): 

     (TimeDuration hours:0 minutes:0 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:0 minutes:0 seconds:10 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:0 minutes:33 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:2 minutes:0 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:2 minutes:33 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:100 minutes:33 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:10000 minutes:33 seconds:0 milliseconds:123) printAsApproximationOn:Transcript
     (TimeDuration hours:1000000 minutes:33 seconds:0 milliseconds:123) printAsApproximationOn:Transcript

     (TimeDuration hours:2 minutes:33 seconds:0) printAsApproximationOn:Transcript
     (TimeDuration hours:2 minutes:0 seconds:0) printAsApproximationOn:Transcript
     (TimeDuration hours:24 minutes:0 seconds:0) printAsApproximationOn:Transcript

o  printOn: aStream
append a human readable printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

o  printShortOn: aStream
append a human readable printed representation
of the receiver to aStream (without milliseconds)

o  printStringForApproximation
return a human readable printed representation of the receiver to aStream.
The format is meant for a human and does not give all information;
especially, useless detail is hidden.
This means, that seconds are rounded or hidden, if the dT is more than a few minutes;
minutes rounded into the hour or hidden, if it's more than a few hours etc.
The way this is done is pure magic heuristics - let me know, if you have a better algorithm.

usage example(s): 

     (TimeDuration hours:0 minutes:0 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:0 minutes:0 seconds:10 milliseconds:123) printStringForApproximation
     (TimeDuration hours:0 minutes:33 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:2 minutes:0 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:2 minutes:33 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:100 minutes:33 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:10000 minutes:33 seconds:0 milliseconds:123) printStringForApproximation
     (TimeDuration hours:1000000 minutes:33 seconds:0 milliseconds:123) printStringForApproximation

     (TimeDuration hours:2 minutes:33 seconds:0) printStringForApproximation
     (TimeDuration hours:2 minutes:0 seconds:0) printStringForApproximation
     (TimeDuration hours:24 minutes:0 seconds:0) printStringForApproximation

private
o  additionalPicoseconds
get the optional additional picoseconds (0..999999999)
notice: that is NOT the total number of picoseconds,
but the fractional part only.
Use this only for printing.

o  additionalPicoseconds: picosecondPart
set the optional additional picoseconds (0..999999999)

o  formatForPrinting: shortFlag
Return a format which is suitable for a human (i.e. not ISO8601)
(not meant to be read back because it will not print tiny fractions,
but instead round it heuristically.
However, the reader can read that format, but you'll loose some precision if you do).
If shortFlag is true, some millisecond-info is omitted for longer times.
For timeDurations to be read back exactly, use iso8601 format.

usage example(s): 

     3001 seconds formatForPrinting:false
     3001 seconds formatForPrinting:true

     (TimeDuration fromString:'1w 3d') formatForPrinting
     (TimeDuration fromString:'1w 3d') printString
     (TimeDuration fromString:'7d') printString
     (TimeDuration fromString:'6d') printString

     (TimeDuration fromMilliseconds:0.5) printString
     (TimeDuration fromMilliseconds:0.05) printString
     (TimeDuration fromMilliseconds:0.005) printString
     (TimeDuration fromMilliseconds:0.0005) printString
     (TimeDuration fromMilliseconds:0.00005) printString
     (TimeDuration fromMilliseconds:0.000005) printString
     (TimeDuration fromMilliseconds:0.0000005) printString
     (TimeDuration fromMilliseconds:0.00000005) printString
     (TimeDuration fromMilliseconds:0.000000005) printString

     (TimeDuration hours:0 minutes:0 seconds:0 milliseconds:12) formatForPrinting
     (TimeDuration hours:0 minutes:0 seconds:2 milliseconds:12) formatForPrinting 
     (TimeDuration hours:0 minutes:0 seconds:8 milliseconds:12) formatForPrinting  
     (TimeDuration hours:0 minutes:0 seconds:10 milliseconds:12) formatForPrinting  

     (TimeDuration hours:0 minutes:0 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:0 minutes:0 seconds:10 milliseconds:123) formatForPrinting
     (TimeDuration hours:0 minutes:33 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:2 minutes:0 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:2 minutes:33 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:100 minutes:33 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:10000 minutes:33 seconds:0 milliseconds:123) formatForPrinting
     (TimeDuration hours:1000000 minutes:33 seconds:0 milliseconds:123) formatForPrinting

     (TimeDuration hours:0 minutes:38 seconds:22 milliseconds:123) formatForPrinting:true

     (TimeDuration hours:2 minutes:33 seconds:0 milliseconds:0) formatForPrinting
     (TimeDuration hours:2 minutes:0 seconds:0 milliseconds:0) formatForPrinting
     (TimeDuration hours:24 minutes:0 seconds:0 milliseconds:0) formatForPrinting

     (TimeDuration hours:0 minutes:0 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:0 minutes:0 seconds:10 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:0 minutes:33 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:2 minutes:33 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:100 minutes:33 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:10000 minutes:33 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'
     (TimeDuration hours:1000000 minutes:33 seconds:0 milliseconds:123) printStringFormat:'%h:%m:%s'

o  getHours
return the number of hours (truncated).
This is the total number of hours - not just the fractional part

o  getMicroseconds
return the number of microseconds (truncated).
This is the total number of microseconds - not just the fractional part

o  getMilliseconds
return the number of milliseconds (truncated).
This is the total number of milliseconds - not just the fractional part

o  getMinutes
return the number of minutes (truncated).
This is the total number of minutes - not just the fractional part

o  getPicoseconds
return the number of picoseconds (truncated).
This is the total number of picoseconds - not just the fractional part

o  getSeconds
return the number of seconds (truncated).
This is the total number of seconds - not just the fractional part

o  possiblyNegatedValueFromTimeEncodingInto: aBlock

o  setHours: h minutes: m seconds: s millis: millis
set my time given individual values

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  setHours: h minutes: m seconds: s milliseconds: millis
set my time given individual values

o  setMicroseconds: micros
set my duration given microseconds.

usage example(s): 

     self new setMicroseconds:100
     self new setMicroseconds:2
     self new setMicroseconds:1.5
     self new setMicroseconds:0.1

o  setMilliseconds: millis
set my duration given milliseconds.
Duration can be longer than a day

o  setMilliseconds: millis additionalPicoseconds: picos
set my duration given milliseconds and addon picos.
Duration can be longer than a day;
values may be negative (eg. if resulting from a subtraction)

o  setNanoseconds: nanos
set my duration given nanoseconds.

usage example(s): 

     self new setMicroseconds:4
     self new setNanoseconds:4
     self new setNanoseconds:4000
     self new setNanoseconds:4000000
     self new setNanoseconds:40000000
     self new setNanoseconds:0.1

o  setPicoseconds: picos
set my duration given picoseconds.

usage example(s): 

     self new setMicroseconds:4
     self new setNanoseconds:4
     self new setPicoseconds:4
     self new setPicoseconds:4.5

     self assert: (self new setPicoseconds:4000) = (self new setNanoseconds:4) .
     self assert: (self new setPicoseconds:4000000) = (self new setNanoseconds:4000) .
     self assert: (self new setPicoseconds:4000000) = (self new setMicroseconds:4) .
     self assert: (self new setPicoseconds:4000000000) = (self new setNanoseconds:4000000) .
     self assert: (self new setPicoseconds:4000000000) = (self new setMicroseconds:4000) .
     self assert: (self new setPicoseconds:4000000000) = (self new setMilliseconds:4) .
     self assert: (self new setPicoseconds:4000000000000) = (self new setMilliseconds:4000) .
     self assert: (self new setPicoseconds:4000000000000) = (self new setMicroseconds:4000000) .
     self assert: (self new setPicoseconds:4000000000000) = (self new setNanoseconds:4000000000) .
     self assert: (self new setPicoseconds:4000000000000) = (self new setSeconds:4) .

o  setSeconds: secs
set my timeduration given seconds.
Notice that (in contrast to Time), there is no modulu operation here.
Duration can be longer than a day, and (much) smaller than a second

testing
o  isTimeDuration

o  isZero

o  negative


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 05 Dec 2023 16:16:52 GMT