Data.UnixTime

unix-time-0.3.7: 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 # |
Methods (==) :: UnixTime -> UnixTime -> Bool # (/=) :: UnixTime -> UnixTime -> Bool #
Ord UnixTime # |
Methods compare :: UnixTime -> UnixTime -> Ordering # (<) :: UnixTime -> UnixTime -> Bool # (<=) :: UnixTime -> UnixTime -> Bool # (>) :: UnixTime -> UnixTime -> Bool # (>=) :: UnixTime -> UnixTime -> Bool # max :: UnixTime -> UnixTime -> UnixTime # min :: UnixTime -> UnixTime -> UnixTime #
Show UnixTime # |
Methods showsPrec :: Int -> UnixTime -> ShowS # show :: UnixTime -> String # showList :: [UnixTime] -> ShowS #
Storable UnixTime # |
Methods sizeOf :: UnixTime -> Int # alignment :: UnixTime -> Int # peekElemOff :: Ptr UnixTime -> Int -> IO UnixTime # pokeElemOff :: Ptr UnixTime -> Int -> UnixTime -> IO () # peekByteOff :: Ptr b -> Int -> IO UnixTime # pokeByteOff :: Ptr b -> Int -> UnixTime -> IO () # peek :: Ptr UnixTime -> IO UnixTime # poke :: Ptr UnixTime -> UnixTime -> IO () #
Binary UnixTime # |
Methods put :: UnixTime -> Put # get :: Get UnixTime # putList :: [UnixTime] -> Put #

# 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. `utMicroSeconds` is always set to 0.

parseUnixTimeGMT :: Format -> ByteString -> UnixTime #

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

    >>> 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(). `utMicroSeconds` is ignored. The result depends on the TZ environment variable.

formatUnixTimeGMT :: Format -> UnixTime -> ByteString #

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

    >>> formatUnixTimeGMT webDateFormat $ UnixTime 0 0
    "Thu, 01 Jan 1970 00:00:00 GMT"
    >>> let ut = UnixTime 100 200
    >>> let str = formatUnixTimeGMT "%s" ut
    >>> let ut' = parseUnixTimeGMT "%s" str
    >>> ((==) `on` utSeconds) ut ut'
    True
    >>> ((==) `on` utMicroSeconds) ut ut'
    False

# 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 # |
Methods (==) :: UnixDiffTime -> UnixDiffTime -> Bool # (/=) :: UnixDiffTime -> UnixDiffTime -> Bool #
Ord UnixDiffTime # |
Methods compare :: UnixDiffTime -> UnixDiffTime -> Ordering # (<) :: UnixDiffTime -> UnixDiffTime -> Bool # (<=) :: UnixDiffTime -> UnixDiffTime -> Bool # (>) :: UnixDiffTime -> UnixDiffTime -> Bool # (>=) :: UnixDiffTime -> UnixDiffTime -> Bool # max :: UnixDiffTime -> UnixDiffTime -> UnixDiffTime # min :: UnixDiffTime -> UnixDiffTime -> UnixDiffTime #
Show UnixDiffTime # |
Methods showsPrec :: Int -> UnixDiffTime -> ShowS # show :: UnixDiffTime -> String # showList :: [UnixDiffTime] -> ShowS #

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