NAME

Sidef::Time::Time - Representation of time as Unix epoch seconds

DESCRIPTION

This class represents a point in time as Unix epoch seconds (the number of seconds since January 1, 1970, 00:00:00 UTC). It provides methods to retrieve the current time, convert between different time representations (local time and GMT/UTC), and obtain high-resolution timestamps with microsecond precision.

The Time class is useful for timestamping events, measuring elapsed time, and working with date/time conversions through its integration with the Date class.

SYNOPSIS

# Create a Time object for the current moment
var current_time = Time()
say current_time              #=> Time(1735401600)

# Create a Time object from a specific Unix timestamp
var past_time = Time(1234567890)
say past_time                 #=> Time(1234567890)

# Get the current Unix epoch seconds
var now = Time.now
say now                       #=> 1735401600

# Convert to local time representation
var local_date = current_time.local
say local_date                #=> Date object in local timezone

# Convert to GMT/UTC representation
var gmt_date = current_time.gmt
say gmt_date                  #=> Date object in GMT/UTC

# Get high-resolution time with microseconds
var precise_time = Time.micro
say precise_time              #=> 1735401600.123456

# Convert to string
say current_time.to_s         #=> "1735401600"

# Get the underlying seconds value
say current_time.sec          #=> 1735401600

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

new

Time.new
Time.new(seconds)

Creates a new Time object. If seconds is provided, it uses that value as the Unix epoch timestamp (seconds since January 1, 1970, 00:00:00 UTC). If called without arguments, it initializes the object with the current time.

Parameters:

• seconds (optional) - A Number representing Unix epoch seconds

Returns: A new Time object

Examples:

var t1 = Time.new              # Current time
var t2 = Time.new(1234567890)  # Specific timestamp
var t3 = Time()                # Also current time (using call alias)

Aliases: call

now

Time.now

Returns the current Unix epoch time as a Number. This is a class method that provides the current timestamp without creating a Time object.

Returns: The current Unix epoch seconds as a Number

Examples:

var timestamp = Time.now
say timestamp                  #=> 1735401600

# Useful for benchmarking
var start = Time.now
# ... some operation ...
var elapsed = Time.now - start
say "Operation took #{elapsed} seconds"

sec

time_obj.sec

Returns the Unix epoch seconds stored in this Time object as a Number. This provides access to the underlying timestamp value.

Returns: Unix epoch seconds as a Number

Examples:

var t = Time(1234567890)
say t.sec                      #=> 1234567890

# Compare two times
var t1 = Time(1000000)
var t2 = Time(2000000)
say (t2.sec - t1.sec)          #=> 1000000

Aliases: time

micro

Time.micro

Returns the current time as a Number with microsecond precision. This uses high-resolution timing mechanisms to provide fractional seconds with microsecond accuracy, useful for precise time measurements and benchmarking.

Returns: Current time as a Number with microseconds (e.g., 1735401600.123456)

Examples:

var precise_start = Time.micro
# ... some fast operation ...
var precise_end = Time.micro
var microseconds = (precise_end - precise_start) * 1e6
say "Operation took #{microseconds} microseconds"

# High-precision timestamp
say Time.micro                 #=> 1735401600.123456

Aliases: micro_sec, micro_seconds

local

time_obj.local

Converts this Time object to a Date object representing the same moment in the local timezone. The returned Date object provides access to individual date/time components (year, month, day, hour, minute, second) adjusted for the system's local timezone.

Returns: A Date object in the local timezone

Examples:

var t = Time(1234567890)
var local_date = t.local
say local_date.hour            # Hour in local timezone
say local_date.mday            # Day of month in local timezone

# Current time in local representation
var now_local = Time().local
say now_local

Aliases: localtime

gmt

time_obj.gmt

Converts this Time object to a Date object representing the same moment in GMT (Greenwich Mean Time) / UTC (Coordinated Universal Time). The returned Date object provides access to individual date/time components in the UTC timezone, which is useful for standardized time representations.

Returns: A Date object in GMT/UTC timezone

Examples:

var t = Time(1234567890)
var gmt_date = t.gmt
say gmt_date.hour              # Hour in GMT/UTC
say gmt_date.year              # Year in GMT/UTC

# Compare local and GMT times
var now = Time()
say "Local: #{now.local}"
say "GMT: #{now.gmt}"

Aliases: gmtime

to_s

time_obj.to_s

Returns a String representation of the Unix epoch seconds stored in this Time object. This is useful for displaying the timestamp or using it in string contexts.

Returns: Unix epoch seconds as a String

Examples:

var t = Time(1234567890)
say t.to_s                     #=> "1234567890"

# String interpolation
var msg = "Timestamp: #{t}"    # Calls to_s automatically

Aliases: to_str

dump

time_obj.dump

Returns a String representation of the Time object in the format Time(seconds). This format is useful for debugging, logging, and serialization purposes as it clearly shows both the class type and the value.

Returns: A String in the format Time(seconds)

Examples:

var t = Time(1234567890)
say t.dump                     #=> "Time(1234567890)"

# Useful for debugging
var times = [Time(1000), Time(2000), Time(3000)]
say times.map{.dump}           #=> ["Time(1000)", "Time(2000)", "Time(3000)"]

SEE ALSO

• Sidef::Types::Date::Date - For working with structured date/time representations

• Sidef::Object::Object - The parent class

AUTHOR

Daniel "Trizen" Șuteu

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Sidef itself.

cpanm Sidef

perl -MCPAN -e shell
install Sidef