Abseil Code Review · 41/79

absl::CivilTime 분석

2026년 6월 11일 · Hawk · 2분 읽기

#CivilTime이 푸는 문제

“3월 31일에 한 달을 더하면 4월 31일?” — 달력 산술은 자연스러워 보이지만 윤년, 30일/31일 월, DST 같은 잡일이 숨어 있다. Abseil의 CivilTime 계열은 시간대를 모르는 달력 좌표만 다루어 이 잡일을 압축한다.

1
#include "absl/time/civil_time.h"
2

3
absl::CivilDay d(2026, 3, 31);
4
d += 1;             // 2026-04-01
5

6
absl::CivilMonth m(2026, 3);
7
m += 1;             // 2026-04
8
absl::CivilDay end_of_april(m.year(), m.month() + 1, 1);
9
--end_of_april;     // 2026-04-30

핵심 원칙은 시간대가 없다는 점이다. CivilDay는 “어떤 달력 좌표”일 뿐 “어느 순간”이 아니다.

#여섯 가지 정밀도

타입	의미	산술 단위
`CivilSecond`	YYYY-MM-DD hh:mm	1초
`CivilMinute`	YYYY-MM-DD hh	1분
`CivilHour`	YYYY-MM-DD hh	1시간
`CivilDay`	YYYY-MM-DD	1일
`CivilMonth`	YYYY-MM	1월
`CivilYear`	YYYY	1년

각 타입의 operator++/+=가 해당 단위로 진행한다. 정밀도가 낮은 타입은 시작 시점 으로 truncate된다.

1
absl::CivilSecond cs(2026, 5, 24, 16, 23, 45);
2

3
absl::CivilDay   cd(cs);   // 2026-05-24 00:00:00
4
absl::CivilMonth cm(cs);   // 2026-05-01 00:00:00
5
absl::CivilYear  cy(cs);   // 2026-01-01 00:00:00

암묵 변환이 높은 정밀도 → 낮은 정밀도 방향으로만 동작한다. 반대는 명시 변환만 허용한다.

#산술 — 정규화가 자동

이상한 입력을 넣어도 정규화된다.

1
absl::CivilDay d(2026, 13, 32);  // ❓ 13월 32일?
2
// → 정규화: 2027-02-01

명시적으로 잘못된 날짜를 만들 수 없으므로 if (month <= 12 && day <= 31) 같은 가드가 사라진다.

윤년도 자연스럽다.

1
absl::CivilDay leap(2024, 2, 29);   // OK
2
absl::CivilDay nope(2025, 2, 29);   // 정규화 → 2025-03-01

월말 산술도 직관적이다.

1
absl::CivilMonth m(2026, 1);
2
for (int i = 0; i < 12; ++i) {
3
    absl::CivilDay last = absl::CivilDay(m + 1, 1) - 1;
4
    std::cout << m << " ends on " << last << "\n";
5
    ++m;
6
}

#TimeZone과의 결합 — FromCivil / ToCivil

CivilTime만으로는 절대 시간을 만들 수 없다. TimeZone과 결합해야 absl::Time이 된다.

1
absl::TimeZone seoul;
2
absl::LoadTimeZone("Asia/Seoul", &seoul);
3

4
absl::CivilSecond cs(2026, 5, 24, 9, 0, 0);
5
absl::Time t = absl::FromCivil(cs, seoul);    // 2026-05-24 09:00:00 KST
6
                                              //     = 2026-05-24 00:00:00 UTC

반대도 가능하다.

1
absl::Time now = absl::Now();
2
absl::CivilSecond cs_seoul = absl::ToCivilSecond(now, seoul);
3
absl::CivilSecond cs_utc   = absl::ToCivilSecond(now, absl::UTCTimeZone());

DST 전환점에 있는 모호한 시각은 TimeZone::At이 자세한 분기 정보를 준다.

1
auto info = seoul.At(cs);
2
// info.kind: UNIQUE / SKIPPED / REPEATED
3
// info.pre / info.trans / info.post

대부분의 코드는 FromCivil이면 충분하다(SKIPPED·REPEATED 모두 합리적 기본값을 고른다).

#요일 계산 — GetWeekday

1
absl::CivilDay d(2026, 5, 24);
2
absl::Weekday wd = absl::GetWeekday(d);  // absl::Weekday::sunday
3

4
// 다음 월요일
5
absl::CivilDay next_mon = absl::NextWeekday(d, absl::Weekday::monday);
6
absl::CivilDay prev_mon = absl::PrevWeekday(d, absl::Weekday::monday);

NextWeekday(d, wd)는 오늘이 wd라도 7일 후를 반환한다. 오늘 포함이 필요하면 d - 1부터 시작한다.

#두 날짜 사이 일수

1
absl::CivilDay start(2026, 1, 1);
2
absl::CivilDay end(2026, 5, 24);
3

4
int64_t days = end - start;   // 143

operator-는 해당 단위 개수를 반환한다. CivilMonth 끼리 빼면 월 차이, CivilSecond는 초 차이.

#흔한 함정

#1. CivilDay가 곧 자정인 줄 알기

CivilDay는 좌표일 뿐 순간이 아니다. FromCivil(CivilDay(...), tz)가 자정이 되는 것이지, CivilDay 자체는 시간대가 없다.

#2. 시간대 잊고 빼기

1
// 회피 — 다른 사용자의 "오늘"이 같다고 가정
2
auto today = absl::ToCivilDay(absl::Now(), absl::UTCTimeZone());
3

4
// Good — 사용자 TZ를 함께
5
auto today_for_user = absl::ToCivilDay(absl::Now(), user_tz);

#3. 윤초 처리

CivilSecond는 60초 분을 모르는 SI 시간이다. POSIX 시간과 동일하게 윤초가 흡수된다. 천체·물리 계산이 아니라면 신경 쓸 필요 없다.

#작은 예시 — 청구서 주기

1
struct BillingCycle {
2
    absl::CivilDay start;
3
    absl::CivilDay end;  // 마지막 날 포함
4
};
5

6
BillingCycle MonthlyCycle(absl::CivilDay any_day_in_month) {
7
    absl::CivilMonth m(any_day_in_month);
8
    absl::CivilDay start(m, 1);
9
    absl::CivilDay end = absl::CivilDay(m + 1, 1) - 1;
10
    return {start, end};
11
}
12

13
// 청구 기간이 30일 이상 떨어졌는지
14
bool LongerThanMonth(BillingCycle a, BillingCycle b) {
15
    return (b.start - a.end) > 30;
16
}