# mruby-time

mruby-time is an mrbgem that provides a `Time` class for mruby, offering functionalities for time manipulation and representation. It is designed to be largely compatible with the Time class found in standard Ruby, following the ISO Ruby Time class specification.

## Purpose

The primary purpose of `mruby-time` is to enable mruby applications to:

- Work with specific points in time.
- Handle timezones, primarily UTC and the local system timezone.
- Perform time arithmetic.
- Format time information into human-readable strings.

## Functionality

### Creating Time Objects

You can create `Time` objects in several ways:

- **`Time.now`**: Returns a `Time` object representing the current time based on the system's clock.

  ```ruby
  t = Time.now
  ```

- **`Time.at(seconds_with_fraction)`**: Creates a `Time` object for the time `seconds_with_fraction` since the Epoch (January 1, 1970, 00:00:00 UTC). You can provide seconds as an integer or a float for sub-second precision.

  ```ruby
  t1 = Time.at(1678886400)       # Integer seconds
  t2 = Time.at(1678886400.5)   # Seconds with microseconds
  ```

- **`Time.local(year, month, day, hour, min, sec, usec)`** (or **`Time.mktime`**): Creates a `Time` object from the given components in the local timezone. Arguments beyond `year` are optional and default to minimum values (e.g., month 1, day 1, hour 0, etc.).

  ```ruby
  t = Time.local(2023, 3, 15, 12, 30, 0) # March 15, 2023, 12:30:00 local time
  ```

- **`Time.gm(year, month, day, hour, min, sec, usec)`** (or **`Time.utc`**): Creates a `Time` object from the given components in UTC. Arguments are optional similar to `Time.local`.

  ```ruby
  t = Time.gm(2023, 3, 15, 12, 30, 0)    # March 15, 2023, 12:30:00 UTC
  ```

### Getting Time Components

Once you have a `Time` object, you can extract its components:

- `t.year`: Returns the year.
- `t.month` (or `t.mon`): Returns the month of the year (1-12).
- `t.day` (or `t.mday`): Returns the day of the month (1-31).
- `t.hour`: Returns the hour of the day (0-23).
- `t.min`: Returns the minute of the hour (0-59).
- `t.sec`: Returns the second of the minute (0-59).
- `t.usec`: Returns the microsecond of the second (0-999999).
- `t.wday`: Returns the day of the week (0 for Sunday, 1 for Monday, ..., 6 for Saturday).
- `t.yday`: Returns the day of the year (1-366).
- `t.zone`: Returns the timezone name ("UTC" or local timezone offset like "+0900").

### Timezone Conversions

- `t.utc?` (or `t.gmt?`): Returns `true` if the `Time` object is in UTC.
- `t.utc` (or `t.gmtime`): Converts the `Time` object to UTC and returns `self`.
- `t.getutc` (or `t.getgm`): Returns a new `Time` object representing the same point in time as `t`, but in UTC.
- `t.localtime`: Converts the `Time` object to the local timezone and returns `self`.
- `t.getlocal`: Returns a new `Time` object representing the same point in time as `t`, but in the local timezone.

### Time Arithmetic

- **Addition (`+`)**: Adds a duration (in seconds) to a `Time` object, returning a new `Time` object.

  ```ruby
  t1 = Time.now
  t2 = t1 + 60 # 60 seconds later
  ```

- **Subtraction (`-`)**:
  - Subtracting a duration (in seconds) from a `Time` object returns a new `Time` object.
  - Subtracting another `Time` object returns the difference in seconds as a Float.

  ```ruby
  t1 = Time.now
  t_earlier = t1 - 3600 # One hour earlier

  t2 = Time.local(2023, 1, 1)
  t3 = Time.local(2023, 1, 2)
  difference_seconds = t3 - t2 # Returns 86400.0
  ```

### Formatting Time

- **`t.to_s`**: Returns a string representation of the time (e.g., "2023-03-15 10:30:00 +0000"). The format may vary slightly.
- **`t.inspect`**: Similar to `to_s`, provides a string representation.
- **`t.asctime`** (or **`t.ctime`**): Returns a canonical string representation (e.g., "Wed Mar 15 10:30:00 2023").
- **`t.to_i`**: Returns the number of seconds since the Epoch as an integer.
- **`t.to_f`**: Returns the number of seconds since the Epoch as a float (including microseconds).

## Compatibility

`mruby-time` aims to be compatible with the standard Ruby `Time` class as defined by ISO/IEC 30170:2012 (Ruby Language Specification). However, due to the nature of embedded systems and the mruby environment, there might be minor differences or limitations, especially concerning timezone data complexity beyond UTC and local system time.

Refer to the source code and tests for detailed behavior.