hledger-lib-1.41: A library providing the core functionality of hledger

Safe Haskell | None
Language | Haskell2010

Hledger.Data.Period

Description

Manipulate the time periods typically used for reports with Period, a richer abstraction than DateSpan. See also Types and Dates.

Synopsis

- periodAsDateSpan :: Period -> DateSpan
- dateSpanAsPeriod :: DateSpan -> Period
- simplifyPeriod :: Period -> Period
- isLastDayOfMonth :: (Eq a1, Eq a2, Num a1, Num a2) => Year -> a1 -> a2 -> Bool
- isStandardPeriod :: Period -> Bool
- periodTextWidth :: Period -> Int
- showPeriod :: Period -> Text
- showPeriodAbbrev :: Period -> Text
- periodStart :: Period -> Maybe Day
- periodEnd :: Period -> Maybe Day
- periodNext :: Period -> Period
- periodPrevious :: Period -> Period
- periodNextIn :: DateSpan -> Period -> Period
- periodPreviousIn :: DateSpan -> Period -> Period
- periodMoveTo :: Day -> Period -> Period
- periodGrow :: Period -> Period
- periodShrink :: Day -> Period -> Period
- mondayBefore :: Day -> Day
- yearMonthContainingWeekStarting :: Day -> (Year, MonthOfYear)
- quarterContainingMonth :: Integral a => a -> a
- firstMonthOfQuarter :: Num a => a -> a
- startOfFirstWeekInMonth :: Year -> MonthOfYear -> Day

# Documentation

periodAsDateSpan :: Period -> DateSpan #

Convert Periods to exact DateSpans.

    >>> periodAsDateSpan (MonthPeriod 2000 1) == DateSpan (Just $ Flex $ fromGregorian 2000 1 1) (Just $ Flex $ fromGregorian 2000 2 1)
    True

dateSpanAsPeriod :: DateSpan -> Period #

Convert DateSpans to Periods.

    >>> dateSpanAsPeriod $ DateSpan (Just $ Exact $ fromGregorian 2000 1 1) (Just $ Exact $ fromGregorian 2000 2 1)
    MonthPeriod 2000 1

simplifyPeriod :: Period -> Period #

Convert PeriodBetweens to a more abstract period where possible.

    >>> simplifyPeriod $ PeriodBetween (fromGregorian 1 1 1) (fromGregorian 2 1 1)
    YearPeriod 1
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 10 1) (fromGregorian 2001 1 1)
    QuarterPeriod 2000 4
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 1) (fromGregorian 2000 3 1)
    MonthPeriod 2000 2
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2016 7 25) (fromGregorian 2016 8 1)
    WeekPeriod 2016-07-25
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 1 1) (fromGregorian 2000 1 2)
    DayPeriod 2000-01-01
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 28) (fromGregorian 2000 3 1)
    PeriodBetween 2000-02-28 2000-03-01
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 2 29) (fromGregorian 2000 3 1)
    DayPeriod 2000-02-29
    >>> simplifyPeriod $ PeriodBetween (fromGregorian 2000 12 31) (fromGregorian 2001 1 1)
    DayPeriod 2000-12-31

isLastDayOfMonth :: (Eq a1, Eq a2, Num a1, Num a2) => Year -> a1 -> a2 -> Bool #

isStandardPeriod :: Period -> Bool #

Is this period a "standard" period, referencing a particular day, week, month, quarter, or year ? Periods of other durations, or infinite duration, or not starting on a standard period boundary, are not.

periodTextWidth :: Period -> Int #

The width of a period of this type when displayed.

showPeriod :: Period -> Text #

Render a period as a compact display string suitable for user output.

    >>> showPeriod (WeekPeriod (fromGregorian 2016 7 25))
    "2016-W30"

showPeriodAbbrev :: Period -> Text #

Like showPeriod, but if it's a month or week period show an abbreviated form. >>> showPeriodAbbrev (WeekPeriod (fromGregorian 2016 7 25)) W30

periodStart :: Period -> Maybe Day #

periodEnd :: Period -> Maybe Day #

periodNext :: Period -> Period #

Move a standard period to the following period of same duration. Non-standard periods are unaffected.

periodPrevious :: Period -> Period #

Move a standard period to the preceding period of same duration. Non-standard periods are unaffected.

periodNextIn :: DateSpan -> Period -> Period #

Move a standard period to the following period of same duration, staying within enclosing dates. Non-standard periods are unaffected.

periodPreviousIn :: DateSpan -> Period -> Period #

Move a standard period to the preceding period of same duration, staying within enclosing dates. Non-standard periods are unaffected.

periodMoveTo :: Day -> Period -> Period #

Move a standard period stepwise so that it encloses the given date. Non-standard periods are unaffected.

periodGrow :: Period -> Period #

Enlarge a standard period to the next larger enclosing standard period, if there is one. Eg, a day becomes the enclosing week. A week becomes whichever month the week's thursday falls into. A year becomes all (unlimited). Non-standard periods (arbitrary dates, or open-ended) are unaffected.

periodShrink :: Day -> Period -> Period #

Shrink a period to the next smaller standard period inside it, choosing the subperiod which contains today's date if possible, otherwise the first subperiod. It goes like this: unbounded periods and nonstandard periods (between two arbitrary dates) -> current year -> current quarter if it's in selected year, otherwise first quarter of selected year -> current month if it's in selected quarter, otherwise first month of selected quarter -> current week if it's in selected month, otherwise first week of selected month -> today if it's in selected week, otherwise first day of selected week, unless that's in previous month, in which case first day of month containing selected week. Shrinking a day has no effect.

mondayBefore :: Day -> Day #

yearMonthContainingWeekStarting :: Day -> (Year, MonthOfYear) #

quarterContainingMonth :: Integral a => a -> a #

firstMonthOfQuarter :: Num a => a -> a #

startOfFirstWeekInMonth :: Year -> MonthOfYear -> Day #