[OpenSource] Moda-Time 時間套件

前言
過去開發時常常都會需要處理關於時間顯示問題，C# 日期輸出格式可以透過 DateTime.ToString() 方式來自訂顯示輸出內容，舉例來說取得時間後對於輸出內容格式化、指定日期是一周中的星期幾等資訊，都會在 ToString() 時候加上 format 來定義，這些格式化的內容讓代碼在閱讀上會有些小混亂，且不容易記住需要查文件才知道，因此我利用一點時間整理過去在 C# 處理時間時常用到的方法，於是乎  Moda-Time  Library 就誕生了，希望可以讓開發者在處理時間上更方便，此篇就簡單介紹此套件所提供的 API 使用及簡單範例，若有問題或是錯誤的地方歡迎各位前輩一起討論指導。

使用方式
Moda-Time 所提供的 API 是使用 C# 3.0 開始有的擴充方法 (Extension Method) 為基礎，並參考 Java 著名的時間套件 joda-Time 提供的 API，在原有的 C# DateTime 中加入新的方法簽章，以下根據此套件的方簽章做簡單的介紹與範例

日期時間信息
取得有關指定日期的顯示資訊，代碼如下

var now = DateTime.Now;

Console.WriteLine($"現在時間是:{now.ToString()}...");
Console.WriteLine($" - DayNameOfWeek: {now.DayNameOfWeek()}");
Console.WriteLine($" - ShortDayNameOfWeek: {now.ShortDayNameOfWeek()}");
Console.WriteLine($" - ShortDayNameOfWeek (指定 Culture): {now.ShortDayNameOfWeek(new CultureInfo("en-us"))}");
Console.WriteLine($" - MonthNameOfYear: {now.MonthNameOfYear()}");
Console.WriteLine($" - MonthNameOfYear (指定 Culture): {now.MonthNameOfYear(new CultureInfo("en-us"))}");
Console.WriteLine($" - ShortMonthNameOfYear: {now.ShortMonthNameOfYear()}");
Console.WriteLine($" - ShortMonthNameOfYear (指定 Culture): {now.ShortMonthNameOfYear(new CultureInfo("en-us"))}");
Console.WriteLine($" - GetWeekOfYear: {now.GetWeekOfYear()}");
Console.WriteLine($" - GetWeekOfMonth: {now.GetWeekOfMonth()}");
Console.WriteLine($" - GetEndDayOfMonth: {now.GetEndDayOfMonth()}");

輸出如下:
現在時間是:2019/8/10 上午 06:53:42...
 - DayNameOfWeek: 星期六
 - ShortDayNameOfWeek: 六
 - ShortDayNameOfWeek (指定 Culture): Sat
 - MonthNameOfYear: 八月
 - MonthNameOfYear (指定 Culture): August
 - ShortMonthNameOfYear: 八月
 - ShortMonthNameOfYear (指定 Culture): Aug
 - GetWeekOfYear: 32
 - GetWeekOfMonth: 2
 - GetEndDayOfMonth: 31 

日期比較
取得有關指定日期的顯示資訊，代碼如下

var t1 = new DateTime(2019,1,2,3,4,5);
var t2 = t1.AddMinutes(-1);
var t3 = t1.AddMinutes(1);
var t4 = new DateTime(2019, 1, 2, 3, 4, 5);

Console.WriteLine($" - t1 IsAfter t2: {t1.IsAfter(t2)}");
Console.WriteLine($" - t1 IsBefore t3: {t1.IsBefore(t3)}");
Console.WriteLine($" - t1 IsEqual t4: {t1.IsEqual(t4)}");

輸出如下:
 - t1 IsAfter t2: True
 - t1 IsBefore t3: True
 - t1 IsEqual t4: True 

日期比較 
日期比較 API 是我個人比較愛的部分，過去在計算兩個日期的差異時都需要先做日期相減取得 timespan，在取得透過 timespan 去看差異的天數、或是時分秒等需要的數字，過去往往代碼都要寫 3 行以上，但透過此 Library 僅需要一行，範例如下

var t1 = new DateTime(2019, 1, 1, 1, 1, 1, 1);
var t2 = new DateTime(2019, 1, 2, 3, 4, 5, 6);

Console.WriteLine($"t1 : {t1.ToString()}");
Console.WriteLine($"t2 : {t2.ToString()}");
Console.WriteLine($" - compare two date - timespan: {t1.Compare(t2)}");
Console.WriteLine($" - compare two date - totalDay: {t1.GetCompareTotalDays(t2)}");
Console.WriteLine($" - compare two date - TotalHours: {t1.GetCompareTotalHours(t2)}");
Console.WriteLine($" - compare two date - TotalMinute: {t1.GetCompareTotalMinute(t2)}");
Console.WriteLine($" - compare two date - TotalSecond: {t1.GetCompareTotalSecond(t2)}");
Console.WriteLine($" - compare two date - TotalMilliseconds: {t1.GetCompareTotalMilliseconds(t2)}"); 

輸出如下:
t1 : 2019/1/1 上午 01:01:01
t2 : 2019/1/2 上午 03:04:05
 - compare two date - Timespan: -1.02:03:04.0050000
 - compare two date - TotalDay: -1.0854630208333333
 - compare two date - TotalHours: -26.0511125
 - compare two date - TotalMinute: -1563.06675
 - compare two date - TotalSecond: -93784.00499999999
 - compare two date - TotalMilliseconds: -93784005

另外 API 中還有提供 plus 日期相關方法，但用法和 DateTime.Add 差異不大，這裡就不在特別另外說明與附上範例程式碼，需要可自行使用。

感想
最後附上 Github 連結，歡迎提供建議、或直接修改程式碼（修改完成後請發 pull request），覺得不錯也請給我顆星星鼓勵，希望這篇介紹可以有幫助到有需要的朋友，Happy Coding :)
Github : https://github.com/marcustung/Moda-Time

參考

DateTime.ToString