From e042ad5ea923da8360e35c90c5de0ec22c19afbd Mon Sep 17 00:00:00 2001 From: aj Date: Fri, 12 Nov 2010 00:05:57 -0800 Subject: [PATCH] updated some comments to be more accurate, more descriptive --- src/ezic_date.erl | 13 ++++++++++--- src/ezic_flatten.erl | 28 ++++++++++++++++------------ 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/src/ezic_date.erl b/src/ezic_date.erl index f419e30..43c3341 100644 --- a/src/ezic_date.erl +++ b/src/ezic_date.erl @@ -51,7 +51,8 @@ normalize(R={{_,_,_}, #tztime{}}) -> R. -% returns RELATIVE {Y,M,D} for a rule and Year +%% returns RELATIVE datetime for a rule and Year +%% -> {{Y,M,D},#tztime{}} | {{Y,M,D},{HH,MM,SS}} for_rule(#rule{in=M, on=D, at=At}, Y) when is_integer(D) -> {{Y,M,D}, At}; for_rule(#rule{in=M, on={last, D}, at=At}, Y) -> @@ -60,12 +61,14 @@ for_rule(#rule{in=M, on=#tzon{day=Day, filter=Filter}, at=At}, Y) -> {first_day_limited(Day, Filter, Y,M), At}. +%% returns set of ALL datetimes for a rule, given the gmt offset and +%% current dst offset. for_rule_all(Rule, Offset, DSTOffset, Year) -> DT= for_rule(Rule, Year), all_times(DT, Offset, DSTOffset). -% returns UTC datetime for rule, offset, and year +% returns UTC datetime for rule, offset, dst offset, and year for_rule_utc(Rule, Offset, DSTOffset, Year) -> {_,_,UTCDatetime} = for_rule_all(Rule, Offset, DSTOffset, Year), UTCDatetime. @@ -278,16 +281,20 @@ add_days_in_month(Days, Date={Y,M,D}) -> - +%% subtracts 1 second from a single datetime +% @todo type checking m1s(Date= {{Y,M,D},{HH,MM,SS}}) when is_integer(Y), is_integer(M), is_integer(D) , is_integer(HH), is_integer(MM), is_integer(SS) -> calendar:gregorian_seconds_to_datetime(calendar:datetime_to_gregorian_seconds(Date) - 1); +%% subtracts 1 second from all datetimes +% @todo type checking m1s({WD, SD, UD}) -> {m1s(WD), m1s(SD), m1s(UD)}. +%% subtracts 1 second from all datetimes % @todo type checking m1s(W,S,U) when is_tuple(W), is_tuple(S), is_tuple(U) -> {m1s(W), m1s(S), m1s(U)}. diff --git a/src/ezic_flatten.erl b/src/ezic_flatten.erl index 81ef3e2..6d96c20 100644 --- a/src/ezic_flatten.erl +++ b/src/ezic_flatten.erl @@ -45,9 +45,10 @@ flatten_all_zones([Z1|_]= AllZones, Flats) -> -% takes zones one-by-one, gathering relevant rules and creating flat -% periods of the same gmt offset (#flatzone). This is a recursive -% solution, eliminating Zones until they've been exhausted +%% takes zones one-by-one from a list of zones of the same name. It +%% gathers relevant rules and creates flat periods of the same gmt +%% offset (#flatzone). This is a recursive solution, eliminating Zones +%% from the list until it's been exhausted flatten_zone_set(Zones) -> flatten_zone_set(?MINFLAT, Zones, []). @@ -67,16 +68,17 @@ flatten_zone_set(FromTimeStub=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset} [Zone | _RestZones] = ezic_zone:next(Zones, UTCFrom, DSTOffset), #zone{rule=RuleName, until=_UntilTime, gmtoff=Offset}=Zone, - %% we have a flatzone with start times, we populate the base offset + %% we have a flatzone with start times; must populate the base gmt offset FromTime= FromTimeStub#flatzone{offset=Offset}, - %% note that dst offset default to {0,0,0} in #flatzone{} + %% if this is the first run, DST offset is {0,0,0} + %% if this is a recursion, DST offset is the previous zone's DST offset %% we gather all rules that _may_ apply (same year) Rules= ezic_db:rules(RuleName), - %% tack the date onto the zone, so we can see if it ends before a rule does + %% tack the date onto the zone, so we can see if the zone ends before a rule does ZoneWithDate= {ezic_zone:project_end_utc(Zone, DSTOffset), Zone}, @@ -117,10 +119,11 @@ flatten_zone_set(FromTimeStub=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset} flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offset=Offset} , ZoneWithDate, Rules, Flats) -> - %% and add normalized (possibly inaccurate) dates for sorting purposes - %% note this may be empty - %% also note this MUST (I think) be done in the loop, since UTCFrom and DSTOffset - %% can potentially change which rule comes next (however unlikely) + %% add normalized (possibly inaccurate) dates for sorting + %% purposes. note this may be empty. also note this MUST (I think) + %% be done in the loop, since UTCFrom and DSTOffset can + %% potentially change which rule comes next (however unlikely that + %% case may be in real life) RulesWithDates= lists:foldl( fun(R, Acc)-> case ezic_rule:project_next(R, Offset, DSTOffset, UTCFrom) of @@ -145,7 +148,7 @@ flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offs NewFlats= [EndFlat | Flats], flatten_rule_set(NextFlat, ZoneWithDate, Rules, NewFlats); false -> - %% new zone is handled in calling function: flatten_zone_set + %% new zone is handled in the caller: flatten_zone_set Flats end. @@ -154,8 +157,9 @@ flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offs finish_and_start_flat(FlatStub=#flatzone{utc_from=_UTCFrom}, EndingRule=#rule{}, _EndingRuleDate={{ERDY,_,_},_}, Offset, DSTOffset) -> + %% @todo for_rule_all was already called in a loop earlier. use those values instead. NewFlatStartDates={WD, SD, UD}= ezic_date:for_rule_all(EndingRule, Offset, DSTOffset, ERDY), - _FlatEndDates={WDm, SDm, UDm}= ezic_date:m1s(NewFlatStartDates), + {WDm, SDm, UDm}= ezic_date:m1s(NewFlatStartDates), EndFlat= ?ENDFLAT(FlatStub, WDm, SDm, UDm, DSTOffset), NewFlat1= ?FLAT(WD, SD, UD),