Data.UnixTime

unix-time-0.3.6: Unix time parser/formatter and utilities

Safe Haskell | None
Language | Haskell2010

Data.UnixTime

Contents

- Data structure
- Getting time
- Parsing and formatting time
- Format
- Difference time
- Translating time

Synopsis

- data UnixTime = UnixTime {
  - utSeconds :: !CTime
  - utMicroSeconds :: !Int32
  }
- getUnixTime :: IO UnixTime
- parseUnixTime :: Format -> ByteString -> UnixTime
- parseUnixTimeGMT :: Format -> ByteString -> UnixTime
- formatUnixTime :: Format -> UnixTime -> IO ByteString
- formatUnixTimeGMT :: Format -> UnixTime -> ByteString
- type Format = ByteString
- webDateFormat :: Format
- mailDateFormat :: Format
- data UnixDiffTime = UnixDiffTime {
  - udtSeconds :: !CTime
  - udtMicroSeconds :: !Int32
  }
- diffUnixTime :: UnixTime -> UnixTime -> UnixDiffTime
- addUnixDiffTime :: UnixTime -> UnixDiffTime -> UnixTime
- secondsToUnixDiffTime :: Integral a => a -> UnixDiffTime
- microSecondsToUnixDiffTime :: Integral a => a -> UnixDiffTime
- fromEpochTime :: EpochTime -> UnixTime
- toEpochTime :: UnixTime -> EpochTime
- fromClockTime :: ClockTime -> UnixTime
- toClockTime :: UnixTime -> ClockTime

# Data structure

data UnixTime

Data structure for Unix time.

Please note that this uses GHC-derived `Eq` and `Ord` instances. Notably

    >>> UnixTime 1 0 > UnixTime 0 999999999
    True

You should instead use `UnixDiffTime` along with its helpers such as `microSecondsToUnixDiffTime` which will ensure that such unusual values are never created.

Constructors

UnixTime |
Fields utSeconds :: !CTime Seconds from 1st Jan 1970 utMicroSeconds :: !Int32 Micro seconds (i.e. 10^(-6))

Instances

Eq UnixTime |
Ord UnixTime |
Show UnixTime |
Storable UnixTime |
Binary UnixTime |

# Getting time

getUnixTime :: IO UnixTime

Getting `UnixTime` from OS.

# Parsing and formatting time

parseUnixTime :: Format -> ByteString -> UnixTime

Parsing `ByteString` to `UnixTime` interpreting as localtime. This is a wrapper for strptime_l(). Many implementations of strptime_l() do not support %Z and some implementations of strptime_l() do not support %z, either.

parseUnixTimeGMT :: Format -> ByteString -> UnixTime

Parsing `ByteString` to `UnixTime` interpreting as GMT. This is a wrapper for strptime_l().

    >>> parseUnixTimeGMT webDateFormat "Thu, 01 Jan 1970 00:00:00 GMT"
    UnixTime {utSeconds = 0, utMicroSeconds = 0}

formatUnixTime :: Format -> UnixTime -> IO ByteString

Formatting `UnixTime` to `ByteString` in local time. This is a wrapper for strftime_l().

formatUnixTimeGMT :: Format -> UnixTime -> ByteString

Formatting `UnixTime` to `ByteString` in GMT. This is a wrapper for strftime_l().

    >>> formatUnixTimeGMT webDateFormat $ UnixTime 0 0
    "Thu, 01 Jan 1970 00:00:00 GMT"

# Format

type Format = ByteString

Format of the strptime()/strftime() style.

webDateFormat :: Format

Format for web (RFC 2616). The value is "%a, %d %b %Y %H:%M:%S GMT". This should be used with `formatUnixTimeGMT` and `parseUnixTimeGMT`.

mailDateFormat :: Format

Format for e-mail (RFC 5322). The value is "%a, %d %b %Y %H:%M:%S %z". This should be used with `formatUnixTime` and `parseUnixTime`.

# Difference time

data UnixDiffTime

Data structure for UnixTime diff.

It is up to the user to ensure that ``udtMicroSeconds` < 1000000`. Helpers such as `microSecondsToUnixDiffTime` can help you to create valid values. For example, it's a mistake to use `addUnixDiffTime` with a value `UnixDiffTime 0 9999999` as it will produce an incorrect value back. You should instead use functions such as `microSecondsToUnixDiffTime` to create values that are in-range. This avoids any gotchas when then doing comparisons.

Constructors

UnixDiffTime |
Fields udtSeconds :: !CTime Seconds from 1st Jan 1970 udtMicroSeconds :: !Int32 Micro seconds (i.e. 10^(-6))

Instances

Eq UnixDiffTime |
Ord UnixDiffTime |
Show UnixDiffTime |

diffUnixTime :: UnixTime -> UnixTime -> UnixDiffTime

Calculating difference between two `UnixTime`.

    >>> UnixTime 100 2000 `diffUnixTime` UnixTime 98 2100
    UnixDiffTime {udtSeconds = 1, udtMicroSeconds = 999900}

addUnixDiffTime :: UnixTime -> UnixDiffTime -> UnixTime

Adding difference to `UnixTime`.

    >>> UnixTime 100 2000 `addUnixDiffTime` microSecondsToUnixDiffTime (-1003000)
    UnixTime {utSeconds = 98, utMicroSeconds = 999000}

secondsToUnixDiffTime :: Integral a => a -> UnixDiffTime

Creating difference from seconds.

    >>> secondsToUnixDiffTime 100
    UnixDiffTime {udtSeconds = 100, udtMicroSeconds = 0}

microSecondsToUnixDiffTime :: Integral a => a -> UnixDiffTime

Creating difference from micro seconds.

    >>> microSecondsToUnixDiffTime 12345678
    UnixDiffTime {udtSeconds = 12, udtMicroSeconds = 345678}

    >>> microSecondsToUnixDiffTime (-12345678)
    UnixDiffTime {udtSeconds = -12, udtMicroSeconds = -345678}

# Translating time

fromEpochTime :: EpochTime -> UnixTime

From `EpochTime` to `UnixTime` setting `utMicroSeconds` to 0.

toEpochTime :: UnixTime -> EpochTime

From `UnixTime` to `EpochTime` ignoring `utMicroSeconds`.

fromClockTime :: ClockTime -> UnixTime

From `ClockTime` to `UnixTime`.

toClockTime :: UnixTime -> ClockTime

From `UnixTime` to `ClockTime`.