Smalltalk/X Webserver

Documentation of class 'TimeDuration':

Class: TimeDuration

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--AbstractChronologyObject
         |
         +--AbstractTime
            |
            +--Time
               |
               +--TimeDuration

Package:: stx:libbasic

Category:: Kernel-Chronology

Version:: rev: 1.204 date: 2024/04/25 13:03:08; user: stefan; file: TimeDuration.st directory: libbasic; module: stx stc-classLibrary: libbasic

Description:

Represents a time/timestamp difference.

The resolution is 1 picosecond.
However, such small timedurations are usually only created by physical computations (see goodies/physic),
or when reading timestamps from external measurement equipment.

The typical OS-time resolution is in the milli- or microsecond range.
External logging hardware may generate timestamps in the micro- or nanosecond range,
and 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 picoseconds are held in a separate instvar (which is often nil or zero) 
and does in most cases not require aditional slow largeInteger operations.

[class variables:]
    DefaultFormatForPrinting    if non-nil, allows for the variable printFormat to be overwritten


[aliases:]
    Duration (ANSI)

copyrightCOPYRIGHT (c) 1989 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

Compatibility-Squeak

milliSeconds: ms

class initialization

initialize: (comment from inherited method)
Modified (comment): / 07-06-2023 / 10:43:03 / alkurz

constants

zero: return the neutral element for addition (0s)

format strings

defaultFormatForPrinting
defaultFormatForPrinting: aString
formatString12us: return the format string used to format US times (and other areas)
formatString24: return the format string used to format european times (and other areas)

instance creation

days: d

return a new TimeDuration representing a duration of d days.

Usage example(s):

     TimeDuration days:1

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

days: d hours: h minutes: m seconds: s nanoSeconds: n

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

Usage example(s):

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

fromHours: hoursInterval

return a new TimeDuration representing a duration of n hours.

Usage example(s):

     TimeDuration fromHours:8

fromMicroseconds: n

return a new TimeDuration representing a duration of n microseconds.

Usage example(s):

     TimeDuration fromMicroseconds:500  
     500 microseconds

fromMilliseconds: n

return a new TimeDuration representing a duration of n milliseconds.

Usage example(s):

     TimeDuration fromMilliseconds:500  
     500 milliseconds

fromMinutes: minutesInterval

return a new TimeDuration representing a duration of n minutes.

Usage example(s):

     TimeDuration fromMinutes:120

fromNanoseconds: n

return a new TimeDuration representing a duration of n nanoseconds.

Usage example(s):

     TimeDuration fromNanoseconds:500  
     500 nanoseconds

fromPicoseconds: n

return a new TimeDuration representing a duration of n picoseconds.

Usage example(s):

     TimeDuration fromPicoseconds:500  
     500 picoseconds  

     TimeDuration fromPicoseconds:1000000000000   
     TimeDuration fromPicoseconds:1000000000500   
     (TimeDuration fromPicoseconds:1000000000000) asPicoSeconds

fromSeconds: secondsInterval

return a new TimeDuration representing a duration of n seconds.

Usage example(s):

     TimeDuration fromSeconds:3600

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

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) **

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

milliseconds: ms

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

Usage example(s):

     TimeDuration milliseconds:2

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

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 (365d) / also: Y
mon -> month (30d) / also: M
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:'1y'     
     TimeDuration readFrom:'1mon'     
     TimeDuration readFrom:'1M'     
     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)

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 / also: Y
mon -> month / also: M
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'

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

weeks: w

return a new TimeDuration representing a duration of w weeks (7 days).

Usage example(s):

     TimeDuration weeks:1

years: y

return a new TimeDuration representing a duration of y years.

Usage example(s):

     TimeDuration years:1

Instance protocol:

Compatibility-Squeak

asDelay

return a delay, which will wait the receiver's timeDuration

Usage example(s):

     1 seconds asDelay wait

wait

wait the receiver's timeDuration

Usage example(s):

     5 seconds wait

accessing

days

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

Usage example(s):

     (Duration fromString:'1wk 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

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.
asTruncatedHours or asExactHours is probably what you want

Usage example(s):

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

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

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
     (Duration fromString:'0.001s') getMilliseconds 
     (Duration fromString:'0.00201s') getMilliseconds 
     (Duration fromString:'0.00201s') getMicroseconds

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.
asTruncatedMinutes or asExactMinutes is probably what you want

Usage example(s):

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

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

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.
asPicoSeconds is probably what you want

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 or asExactSeconds is probably what you want

Usage example(s):

     (TimeDuration fromString:'1m 5s 10ms') seconds     
     (TimeDuration fromString:'1m 1s 10ms') asSeconds  
     (TimeDuration fromString:'1m 1s 10ms') asExactSeconds  

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

weeks

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

Usage example(s):

     (Duration fromString:'3wk 1d 4h 3m 5s 10ms') weeks  => 3
     (Duration fromString:'3wk 1d 4h 3m 5s 10ms') days   => 22

years

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

Usage example(s):

     (Duration fromString:'4yr 3wk 1d 4h 3m 5s 10ms') years  => 4
     (Duration fromString:'4yr 3wk 1d 4h 3m 5s 10ms') weeks  => 211
     (Duration fromString:'4yr 3wk 1d 4h 3m 5s 10ms') days   => 1482

arithmetic

* aNumberOrTimeDuration

return a new scaled timeDuration or a squared timeDuration

Usage example(s):

     5 seconds * 5           -> 25s
     5 * 5 seconds           -> 25s
     5 seconds * 5 seconds   -> 25 s²

     5 * (TimeDuration fromString:'10s') -> 50s
     (TimeDuration fromString:'10s') * 5 -> 50s

     (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      -> 50ms
     (TimeDuration fromString:'10ms') * 1000   -> 10s
     (TimeDuration fromString:'10us') * 5      -> 50µs
     (TimeDuration fromString:'10ns') * 5      -> 50ns
     (TimeDuration fromString:'10ps') * 5      -> 50ps
     (TimeDuration fromString:'10ps') * 1000   -> 10ns

     10 pico seconds * 1000   -> 10ns

** aNumberOrTimeDuration

return a new scaled timeDuration or a squared timeDuration

Usage example(s):

     5 seconds ** 2          -> 25 s²
     5 * 5 seconds           -> 25s
     5 seconds * 5           -> 25s
     5 seconds * 5 seconds   -> 25 s²

+ aTimeDurationOrNumberOfSeconds

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

Usage example(s):

     (10 seconds) + (20 seconds)     -> 30s
     (10 seconds) + 20               -> 30s
     10 + (20 seconds)               -> 30s

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

     (TimeDuration fromString:'1m') + 10 
     10 + (TimeDuration fromString:'1m')

- aTimeDurationOrNumberOfSeconds

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

Usage example(s):

     20 seconds - 10 seconds   -> 10s
     20 seconds - 10           -> 10s
     20 - 10 seconds           -> 10s

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

     (TimeDuration fromString:'1m') - 10    
     100 - (TimeDuration fromString:'1m')

/ 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:'5s')
     (TimeDuration fromString:'10s') / 5  

     (TimeDuration fromString:'1m') / 2    

     (10 seconds) / (5 seconds)        -> 2
     (10 seconds) / 2                  -> 5s
     (10 seconds) / 2.0                -> 5s
     (10 seconds squared) / 10 seconds -> 10s

Usage example(s):

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

// 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

abs

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

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

negated

50 nanoseconds negated asNanoseconds
1 seconds negated asSeconds

raisedTo: aNumber

notice: although noone seems to implement it (currently),

Usage example(s):

     (TimeDuration fromString:'10s') raisedTo:2

squared

answer a squared time (unit: s^2).
Do NOT return a scalar here, because this breaks computations such as
1 meter / 1 seconds squared
(I hope, no one uses it yet )

Usage example(s):

     50 nanoseconds squared 
     1 seconds squared
     ObjectMemory traceSendsIn:[
        1 meter / 1 seconds squared
     ]

squaredSeconds

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

Usage example(s):

     50 nanoseconds squaredSeconds 
     1 seconds squaredSeconds

comparing

< aTimeDuration: 3.0 seconds < 3.1 seconds
3.0 seconds < 3 seconds
<= aTimeDuration: 3.0 seconds <= 3.1 seconds
3.0 seconds <= 3 seconds
= something: (comment from inherited method)
return true if the receiver is the same time or duration as the argument
> aTimeDuration: 3.0 seconds > 3.1 seconds
3.1 seconds > 3 seconds
>= aTimeDuration: 3.0 seconds >= 3 seconds
3.1 seconds >= 3 seconds
hash: (comment from inherited method)
return an integer useful for hashing on times
negative: return true if the receiver is negative (< 0).
(i.e. when adding the receiver to a timeStamp, we get a time in the past)
positive: return true if the receiver is >= 0
(i.e. when adding the receiver to a timeStamp, we get a time in the future)

converting

asExactDays

answer the duration as days.
This may return a non-integer value.

Usage example(s):

     (2 hours + 10 minutes + 30 seconds) asExactDays asFloat 
     (44 hours + 10 minutes + 30 seconds) asExactDays asFloat
     (24 hours) asExactDays asFloat

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

asExactMicroSeconds

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

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

asExactMilliSeconds

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

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

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

asExactNanoSeconds

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

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

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 milliSeconds asExactSeconds    
     1.5 seconds asExactSeconds    
     40 seconds asExactSeconds
     40 milliseconds asExactSeconds
     40 microseconds asExactSeconds
     40 nanoseconds asExactSeconds

asExactWeeks

answer the duration as weeks.
This may return a non-integer value.

Usage example(s):

     (2 hours + 10 minutes + 30 seconds) asExactWeeks asFloat  
     (44 hours + 10 minutes + 30 seconds) asExactWeeks asFloat 
     (244 hours + 10 minutes + 30 seconds) asExactWeeks asFloat

asExactYears

answer the duration as years.
This may return a non-integer value.
Takes non-leapYear as divisor (365 days)

Usage example(s):

average livetime of a human (in europe):

     27000 days asExactYears asFloat

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 secondsAsScaledDecimal

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

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 secondsAsScaledDecimal

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

asFloat

answer the duration in seconds as a float.
Better use secondsAsFloat when sending only to TimeDuration values.
But you can use this method for a common protocol with Numbers.

Usage example(s):

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

asFraction

answer the duration in seconds as a fraction
(might return an integer, if the duration is an exact multiple
of millis).
Better use secondsAsFraction when sending only to TimeDuration values.
But you can use this method for a common protocol with Numbers.

Usage example(s):

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

asInteger

answer the duration as (truncated) integer seconds.
Better use the explicit asTruncatedSeconds.
But you can use this method for a common protocol with Numbers.

Usage example(s):

     10 milliseconds asInteger

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) **

asMicroSeconds

marked as obsolete by Stefan Vogel at 25-Apr-2024

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

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

asMilliSeconds

marked as obsolete by Stefan Vogel at 25-Apr-2024

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

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

asNanoSeconds

marked as obsolete by Stefan Vogel at 25-Apr-2024

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

asNanoseconds

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

asNumber

answer the duration as seconds.
Better use sTruncatedSeconds or
asExactSeconds when sending only to TimeDuration values.
But you can use this method for a common protocol with Numbers.

asPicoSeconds

marked as obsolete by Stefan Vogel at 25-Apr-2024

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

asPicoseconds

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

Usage example(s):

     10 milliseconds asPicoseconds
     10 seconds asPicoseconds

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)

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

asTimeDuration

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

asTruncatedDays

answer the duration as days (truncated).
Values smaller than 1 d will be returned as 0.
This is the total number of days - not just the fractional part.
To get the exact number, use asExactDays.

Usage example(s):

     (2 hours + 10 minutes + 30 seconds) asTruncatedDays        
     (2 hours + 10 minutes + 30 seconds) asExactDays asFloat    
     (23 hours + 59 minutes + 59 seconds) asTruncatedDays        
     (23 hours + 59 minutes + 59 seconds) asExactDays asFloat    

     (44 hours + 10 minutes + 30 seconds) asTruncatedDays     
     (44 hours + 10 minutes + 30 seconds) asExactDays asFloat 

     (48 hours) asTruncatedDays       
     (48 hours) asExactDays asFloat

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

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

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

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

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

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

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

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

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

asTruncatedYears

answer the duration as years (truncated).
Values smaller than 1 y will be returned as 0.
This is the total number of years - not just the fractional part.
To get the exact number, use asExactYears.

Usage example(s):

     1 years asExactYears            
     1 years asTruncatedYears        

     (1 years + 1 hours) asExactYears     asFloat
     (1 years + 1 hours) asTruncatedYears

secondsAsFixedPoint

marked as obsolete by exept MBP at 18-09-2021

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

secondsAsFixedPoint: scale

marked as obsolete by exept MBP at 18-09-2021

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

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

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

secondsAsLongFloat

answer the duration as longfloat seconds.

Usage example(s):

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

secondsAsScaledDecimal

answer the duration in seconds as a scaled decimal number.

Usage example(s):

     (10 milliseconds) secondsAsScaledDecimal
     (10 milliseconds) secondsAsScaledDecimal asScaledDecimal:3

secondsAsScaledDecimal: scale

answer the duration in seconds as a scaled decimal number with given scale.

double dispatching

differenceFromFloat: aFloat: treat the float as a number of seconds.
Might be questionable, but adding numbers to timeDurations is also allowed,
and addition is commutative...
...maybe mixing should be forbidden.
differenceFromInteger: anInteger: treat the integer as a number of seconds.
Might be questionable, but adding integers to timeDurations is also allowed,
and addition is commutative...
...maybe mixing should be forbidden.
differenceFromTimeDuration: aTimeDuration: return a new timeDuration
differenceFromTimestamp: aTimestamp: return the timestamp this timeDuration before aTimestamp
productFromFloat: aFloat: sent when aFloat does not know how to multiply the receiver.
Return a new timeDuration
productFromFraction: aFraction: sent when aFraction does not know how to multiply the receiver.
Return a new timeDuration
productFromInteger: anInteger: sent when an integer does not know how to multiply the receiver
productFromNumber: aNumber: sent when an integer does not know how to multiply the receiver.
Return a new timeDuration
productFromTimeDuration: aTimeDuration: return a new timeDuration
quotientFromTimeDuration: aTimeDuration: Return aTimeDuration / self
sumFromFloat: aFloat: treat the float as a number of seconds.
Might be questionable, but adding floats to timeDurations is also allowed,
and addition is commutative...
...maybe mixing should be forbidden.
sumFromInteger: anInteger: treat the integer as a number of seconds.
Might be questionable, but adding integers to timeDurations is also allowed,
and addition is commutative...
...maybe mixing should be forbidden.
sumFromTimeDuration: aTimeDuration: return a new timeDuration
sumFromTimestamp: aTimestamp: return the timestamp this timeDuration after aTimestamp

inspecting

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

printing & storing

addPrintBindingsTo: aDictionary language: languageOrNil

marked as obsolete by exept MBP at 04-12-2021

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

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.

formatForPrinting

Return the format for printing

Usage example(s):

     (TimeDuration readFrom:'10h 3s') formatForPrinting    => '%(H)h %(M)m %(S) s'
     (TimeDuration readFrom:'3s') formatForPrinting        => '%(S) s'
     (TimeDuration readFrom:'1d 2ms') formatForPrinting    => '%(d) d %(I) ms'  
     (TimeDuration readFrom:'1 week') formatForPrinting    => '%(w) w'

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              => '%(w)w %(dw)d'
     (TimeDuration fromString:'1w 3d') printString                    => '1w 3d'
     (TimeDuration fromString:'7d') printString                       => '1 w'
     (TimeDuration fromString:'6d') printString                       => '6 d'  

     10 microSeconds formatForPrinting:false
     1 microSeconds formatForPrinting:false

     (TimeDuration fromMilliseconds:0.5) printString                  => '500 µs'
     (TimeDuration fromMilliseconds:0.05) printString                 => '50 µs'
     (TimeDuration fromMilliseconds:0.005) printString                => '5 µs'
     (TimeDuration fromMilliseconds:0.0005) printString               => '500 ns'
     (TimeDuration fromMilliseconds:0.00005) printString              => '50 ns'
     (TimeDuration fromMilliseconds:0.000005) printString             => '5 ns'
     (TimeDuration fromMilliseconds:0.0000005) printString            => '500 ps'
     (TimeDuration fromMilliseconds:0.00000005) printString           => '50 ps'
     (TimeDuration fromMilliseconds:0.000000005) printString          => '5 ps'

     (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'

     (TimeDuration fromString:'0.00101s') formatForPrinting  
     (TimeDuration fromString:'0.00201s') formatForPrinting  
     (TimeDuration fromString:'0.00601s') formatForPrinting  
     (TimeDuration fromString:'0.01001s') formatForPrinting  
     (TimeDuration fromString:'0.01101s') formatForPrinting  
     (TimeDuration microseconds:1500) formatForPrinting  
     (TimeDuration microseconds:5500) formatForPrinting  
     (TimeDuration microseconds:10500) formatForPrinting  
     (TimeDuration microseconds:20500) formatForPrinting  
     (TimeDuration microseconds:120500) formatForPrinting  

     (TimeDuration fromNanoseconds:100) printString     => '100 ns' 
     (TimeDuration fromNanoseconds:200) printString     => '200 ns' 
     (TimeDuration fromNanoseconds:900) printString     => '900 ns' 
     (TimeDuration fromNanoseconds:1000) printString    => '1 µs' 
     (TimeDuration fromNanoseconds:1100) printString    => '1100 ns'
     (TimeDuration fromNanoseconds:2000) printString    => '2 µs'
     (TimeDuration fromNanoseconds:2100) printString    => '2100 ns'' 
     (TimeDuration fromNanoseconds:3100) printString    => '3.1 µs'
     (TimeDuration fromNanoseconds:3110) printString    => '3.11 µs' 
     (TimeDuration fromNanoseconds:3111) printString    => '3.111 µs'' 
     (TimeDuration fromNanoseconds:5011) printString    => '5.011 µs'
     (TimeDuration fromNanoseconds:10010) printString   => '10.01 µs' 
     (TimeDuration fromNanoseconds:100010) printString  => '100.01 µs'
     (TimeDuration fromNanoseconds:1000010) printString => '1000.01 µs'
     (TimeDuration fromNanoseconds:10000010) printString => '10.000 ms' 
     (TimeDuration fromNanoseconds:10001010) printString => '10.001 ms'

formatForShortPrinting

Return the short format for printing (without ms)

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

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.

printShortOn: aStream

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

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

printStringHumanFriendly

generate a human friendly timeduration printString.
Similar to but different than printStringForApproximation

Usage example(s):

     3 seconds printStringHumanFriendly         => '3 s'
     3.54 seconds printStringHumanFriendly      => '3.6 s'
     30.0 seconds printStringHumanFriendly      => '30 s' 
     1000 seconds printStringHumanFriendly      => '16.7 m'
     10000 seconds printStringHumanFriendly     => '2.8 h'
     100000 seconds printStringHumanFriendly    => '1.2 d' 
     1000000 seconds printStringHumanFriendly   => '11.6 d' 

     12 days printStringHumanFriendly           => '12 d'
     120 days printStringHumanFriendly          => '120 d'
     350 days printStringHumanFriendly          => '350 d'
     400 days printStringHumanFriendly          => '400 d' 
     2 years printStringHumanFriendly           => '2 yr' 
     4 years printStringHumanFriendly           => '4 yr'
     10 years printStringHumanFriendly          => '10 yr'
     10000 years printStringHumanFriendly       => '10000 yr' 
     1000000 years printStringHumanFriendly     => '1000000 yr'
     2 giga years printStringHumanFriendly      => '2000 mio yr' 
     2.1 mega years printStringHumanFriendly    => '2.1 mio yr'

     1 nano seconds printStringHumanFriendly    => '1 ns'
     1 micro seconds printStringHumanFriendly   => '1 µs'
     1 milli seconds printStringHumanFriendly   => '1 ms'
     0.4 seconds printStringHumanFriendly       => '400 ms'

     3 seconds printStringHumanFriendly         => '3 s'
     30 seconds printStringHumanFriendly        => '30 s'
     1000 seconds printStringHumanFriendly      => '16 m' 
     10000 seconds printStringHumanFriendly     => '2.8 h'
     100000 seconds printStringHumanFriendly    => '1d 3h'
     1000000 seconds printStringHumanFriendly   => '11.6 d'
     4000 days printStringHumanFriendly         => '11.0 yr'

storeOn: aStream

TimeDuration readFrom:( (TimeDuration fromPicoseconds:500) storeString ) => 500ps

TimeDuration readFrom: (TimeDuration fromPicoseconds:1000000000000) storeString => 1s
TimeDuration readFrom: (TimeDuration fromPicoseconds:1001000000000) storeString => 1.001s
TimeDuration readFrom: (TimeDuration fromPicoseconds:1000010000000) storeString => 1.000s
TimeDuration readFrom: (TimeDuration fromPicoseconds:1000000000500) storeString => 1.000s

private

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.

additionalPicoseconds: picosecondPart

set the optional additional picoseconds (0..999999999)

getHours

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

getMicroseconds

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

getMilliseconds

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

getMinutes

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

getNanoseconds

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

getPicoseconds

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

getSeconds

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

possiblyNegatedValueFromTimeEncodingInto: aBlock

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) **

setHours: h minutes: m seconds: s milliseconds: millis

set my time given individual values

setHours: h minutes: m seconds: s nanoseconds: nanos

set my time given individual values

setMicroseconds: micros

set my duration given microseconds.
Duration can be longer than a day;
but not shorter than 1 picoSecond, with 1 pico resolution

Usage example(s):

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

setMilliseconds: millis

set my duration given milliseconds.
Duration can be longer than a day;
but not shorter than 1 picoSecond, with 1 pico resolution

setMilliseconds: millis additionalPicoseconds: picos

set my duration given milliseconds and addon picos.
Duration can be longer than a day;
but not shorter than 1 picoSecond, with 1 pico resolution;
values may be negative (eg. if resulting from a subtraction)

setNanoseconds: nanos

set my duration given nanoseconds.
Duration can be longer than a day;
but not shorter than 1 picoSecond, with 1 pico resolution

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

setPicoseconds: picos

set my duration given picoseconds.
Duration can be longer than a day;
but not shorter than 1 picoSecond, with 1 pico resolution

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) .

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;
but not shorter than 1 picoSecond, with 1 pico resolution

testing

isTimeDuration
isZero: return true, if the receiver is zero (the neutral element wrt. addition)
Here, check for a zero time duration
respondsToArithmetic: return true, if the receiver responds to arithmetic messages.
This should return true for any object which represents a scalar,
matrix, point, physical value or similar object
which can add, subtract, etc.

truncation & rounding

roundTo: aTimeDuration

round the receiver to the next multiple of a TimeDuration.
Bad name: should be called roundedTo: because it returns a new instance

Usage example(s):

      (TimeDuration fromMicroseconds:25234) roundTo:2 milliSeconds  => 26s
      (TimeDuration fromMilliseconds:25234) roundTo:10 milliSeconds  => 25.23s
      (TimeDuration fromMilliseconds:25234) roundTo:100 milliSeconds => 25.2s
      (TimeDuration fromPicoseconds:25234) roundTo:0.2 nanoSeconds   => 25.2ns
      Time now roundTo:10 minutes                                   => 21:30:00
      Timestamp now roundTo:10 minutes                              => 2023-06-06 21:30:00

truncateTo: aTimeDuration

truncate the receiver to the previous multiple of a TimeDuration.
Bad name: should be called truncatedTo: because it returns a new instance

Usage example(s):

      (TimeDuration fromMilliseconds:25234) truncateTo:2 seconds           => 24s
      (TimeDuration fromMilliseconds:25234) truncateTo:10 milliseconds     => 25.23s
      (TimeDuration fromMilliseconds:25234) truncateTo:100 milliseconds    => 25.2s
      (TimeDuration fromMicroseconds:25234.150) truncateTo:100 picoseconds => 25.234ms
      Time now truncateTo:10 minutes                                => 21:20:00
      Timestamp now truncateTo:10 minutes                           => 2023-06-06 21:20:00
      Time now asTimeDuration truncateTo:10 minutes                 => 13h 10m

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Fri, 22 Nov 2024 13:51:53 GMT