Skip to content

Commit 1d6bae4

Browse files
shahabfarshahabfar
authored
Add files via upload
1 parent 3760d4d commit 1d6bae4

File tree

1 file changed

+213
-1
lines changed

1 file changed

+213
-1
lines changed

‎README.md

Lines changed: 213 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,213 @@
1-
# Persia.Net
1+
# Persia.Net
2+
3+
[![Publish to NuGet](https://github.com/shahabfar/Persia.Net/actions/workflows/publish.yml/badge.svg)](https://github.com/shahabfar/Persia.Net/actions/workflows/publish.yml)
4+
5+
Persia.Net is a robust class library, meticulously designed to facilitate seamless conversion between Persian, Gregorian, and Arabic (Hijri) dates. Originally crafted with .NET, it has evolved to ensure compatibility with .NET 6.0, 7.0, and the latest 8.0, making it a versatile tool for a wide range of .NET applications.
6+
7+
![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
8+
9+
## Install via NuGet
10+
11+
To install Persia.Net, run the following command in the Package Manager Console:
12+
13+
[![Nuget](https://img.shields.io/nuget/v/Persia.Net)](https://www.nuget.org/packages/Persia.Net/)
14+
15+
```
16+
PM> Install-Package Persia.Net
17+
```
18+
19+
You can also view the [package page](https://www.nuget.org/packages/Persia.Net/) on NuGet.
20+
21+
22+
# Using Persia.Net
23+
24+
Persia.Net is a versatile class library designed to seamlessly convert dates between Persian, Gregorian, and Arabic (Hijri) calendars. This guide will show you how to use Persia.Net to convert dates.
25+
26+
## Converting Dates
27+
28+
You can convert both nullable and non-nullable `DateTime` objects to Persian dates using the `ToPersianDateTime()` extension method.
29+
30+
Here's an example:
31+
32+
```csharp
33+
DateTime? nullableDate = new DateTime(2024, 03, 10);
34+
DateTime nonNullableDate = new DateTime(2024, 03, 10);
35+
36+
var convertedNullableDate = nullableDate.ToPersianDateTime();
37+
var convertedNonNullableDate = nonNullableDate.ToPersianDateTime();
38+
```
39+
In this example, both nullableDate and nonNullableDate are converted to Persian dates.
40+
41+
### Accessing Date Components
42+
After converting a date, you can access the day, month, and year components of the Persian date like this:
43+
```csharp
44+
int day = convertedNullableDate.Day;
45+
int month = convertedNullableDate.Month;
46+
int year = convertedNullableDate.Year;
47+
```
48+
In this example, day, month, and year will hold the day, month, and year of the Persian date, respectively.
49+
50+
When you run this code, it will print:
51+
```
52+
Day: 20
53+
Month: 12
54+
Year: 1402
55+
```
56+
## PersianDateTime Class
57+
58+
The `PersianDateTime` class in the Persia.Net library is a comprehensive utility designed for handling and manipulating dates in the Persian calendar. Here's a brief overview of its capabilities:
59+
60+
| Property | Description |
61+
| --- | --- |
62+
| `Year` | Gets the year component of the date. |
63+
| `Month` | Gets the month component of the date. |
64+
| `Day` | Gets the day component of the date. |
65+
| `Hour` | Gets the hour component of the time. |
66+
| `Minute` | Gets the minute component of the time. |
67+
| `Second` | Gets the second component of the time. |
68+
| `Millisecond` | Gets the millisecond component of the time. |
69+
| `Ticks` | Gets the number of ticks that represent the time. |
70+
| `DayOfWeek` | Gets the day number of the week. This number is zero based. |
71+
| `DaysInMonth` | Gets the days of the month. |
72+
| `WeekOfMonth` | Gets the week number of the month. |
73+
| `WeekOfYear` | Gets the week number of the year. |
74+
| `MonthName` | Gets the name of the current month. |
75+
| `DayOfWeekName` | Gets the day name of the week in the Persian Calendar. |
76+
| `IsLeapYear` | Gets a value indicating whether the current Persian year is a leap year. |
77+
| `DayOfYear` | Gets the number of days that have passed since the beginning of the current year in the Persian calendar. |
78+
| `DaysRemainingInYear` | Gets the number of days remaining until the end of the current year in the Persian calendar. |
79+
| `Now` | Gets the current date and time in the Persian calendar. |
80+
| `UtcNow` | Gets the current date and time in the Persian calendar in Coordinated Universal Time (UTC). |
81+
| `Today` | Gets the current date in the Persian calendar.|
82+
83+
84+
### Converting Gregorian Date to Persian Date
85+
86+
The provided code snippet is a simple example of converting a Gregorian date to a Persian date using `ToPersianDateTime()` extension method.
87+
88+
```csharp
89+
var date = new DateTime(2024, 03, 10); // Define a Gregorian date
90+
91+
// Convert the Gregorian date to a Persian date
92+
var convertedDateString = date.ToPersianDateTime().ToString();
93+
Console.WriteLine(convertedDateString);
94+
95+
// The result of the conversion is "1402/12/20"
96+
```
97+
98+
In addition to date conversion, the `PersianDateTime` class also includes built-in string generation methods. These methods transform the converted DateTime into a human-readable Persian string, providing a more intuitive representation of the date and time in Persian. The following table outlines these methods:
99+
100+
| Method | Description |
101+
| --- | --- |
102+
| `ToShortPersianString` | Converts the date to a string in the format "yyyy/MM/dd" with Persian numbers.<br>برای مثال, ۱۴۰۲/۱۲/۲۰|
103+
| `ToPersianString` | Converts the date to a string in the Persian format with Year and Day in digit and Month in word.<br>برای مثال, ۲۰ اسفند ۱۴۰۲|
104+
| `ToLongPersianString` | Converts the date to a string in the Persian format with Year and Day in digit and Month in word as well as weekday name and time.<br>برای مثال, یکشنبه ۲۰ اسفند ۱۴۰۲|
105+
| `ToPersianDayMonthString` | Converts the date to a string in the Persian format with Year in digit and Day and Month in words.<br>برای مثال, بیستم اسفند ۱۴۰۲|
106+
| `ToPersianWeekdayString` | Converts the date to a string in the Persian as well as week day name.<br>برای مثال, یکشنبه ۱۴۰۲/۱۲/۲۰|
107+
| `ToLongPersianOrdinalWords` |Converts the date to a string in the Persian format with Year in digit and Day and Month in words as well as weekday name.<br>برای مثال, یکشنبه بیستم اسفند ۱۴۰۲|
108+
109+
## Converting Persian Date to Gregorian DateTime
110+
In .NET, the `PersianDateTime` class provides straightforward methods for converting Persian dates to Gregorian dates or `DateTime`. Specifically, the `ToDateTime` and `ToDateOnly` methods can be utilized for this purpose. Both of these methods are available as static and instance methods within the `PersianDateTime` class. This allows for flexible usage depending on the specific requirements of your code.
111+
112+
The `ToDateTime` method in the `PersianDateTime` class allows you to convert a Persian date to a Gregorian `DateTime`. This method is static and takes three parameters: `year`, `month`, and `day`.
113+
114+
#### Method Signature
115+
116+
```csharp
117+
public static DateTime ToDateTime(int year, int month, int day)
118+
```
119+
#### Parameters
120+
* `year`: The year component of the Persian date.
121+
* `month`: The month component of the Persian date.
122+
* `day`: The day component of the Persian date.
123+
#### Return Value
124+
This method returns a `DateTime` object representing the equivalent Gregorian date and the current time of day.
125+
126+
Here’s an example of how to use this method:
127+
128+
```csharp
129+
// Define a Persian date
130+
int year = 1403;
131+
int month = 1;
132+
int day = 1;
133+
134+
// Convert the Persian date to a Gregorian DateTime
135+
DateTime gregorianDate = PersianDateTime.ToDateTime(year, month, day);
136+
137+
// Output the result
138+
Console.WriteLine(gregorianDate);
139+
```
140+
In the previous example, the time components (hour, minute, second, and millisecond) of the converted DateTime are derived from the system clock. However, if you wish to specify your own time values for the conversion, you can do so using the overloaded ToDateTime methods. These methods allow you to pass in the hour, minute, second, and optionally, the millisecond, along with the year, month, and day.
141+
142+
Here is the method signature for this overload:
143+
```csharp
144+
DateTime ToDateTime(int year, int month, int day, int hour, int minute, int second, int millisecond = 0)
145+
```
146+
If you're only interested in the date portion of the converted `DateTime`, you can use the `ToDateOnly` method. This method returns a `DateOnly` object, which represents the converted Persian date without any time values.
147+
148+
Here's the method signature for your reference:
149+
```csharp
150+
DateOnly ToDateOnly(int year, int month, int day)
151+
```
152+
153+
### Human-Readable Time Difference Conversion
154+
The `HumanizePersianDateTimePassed` method in the `PersianDateTime` class allows you to convert the time difference between the current date and a provided date into a human-readable format.
155+
156+
#### Method Signature
157+
158+
```csharp
159+
string HumanizePersianDateTimePassed(int partsToPrint = 3)
160+
string HumanizePassedPersianDateTime(TimeUnit timeUnit)
161+
```
162+
By default, this method generates a human-readable format with three components. However, if you prefer a more detailed output, you can specify up to six components. To do this, simply pass the desired number of components as an argument to this method.
163+
164+
Here's the example:
165+
```csharp
166+
// Define a DateTime
167+
var date = new DateTime(2023, 12, 21);
168+
169+
// Humanize the time difference between the current date and the provided date
170+
var humanizedPersian = date.HumanizePersianDateTimePassed();
171+
172+
// Output the result
173+
Console.WriteLine(humanizedPersian);
174+
175+
// The result of the conversion is "‫۱۱ ماه و ۳۶۲ روز و ۲ ساعت پیش‬"
176+
```
177+
Additionally, if you prefer to display the elapsed time in terms of a single time unit, you can specify this as an argument to the method. For instance, if you want to express the elapsed time solely in terms of days, you can pass TimeUnit.Days as an argument to the method.
178+
179+
Here’s how you can do this:
180+
```csharp
181+
var humanizedPersian = date.HumanizePassedPersianDateTime(TimeUnit.Days);
182+
```
183+
In this example, `HumanizePassedPersianDateTime` will return the elapsed time since the specified date, expressed solely in terms of days. This allows for a more focused representation of the elapsed time.
184+
Here is the enumerable `TimeUnit` values:
185+
186+
```Years
187+
Months
188+
Days
189+
Hours
190+
Minutes
191+
Seconds
192+
```
193+
### Retrieving Detailed Week and Month Data in the Persian Calendar
194+
If you're interested in obtaining information about the current week or month in the Persian calendar, this library offers specific `DateTime` extension methods designed for this purpose. These methods include:
195+
196+
- `CurrentPersianWeek`: Retrieves the current week.
197+
- `NextPersianWeek`: Retrieves the next week.
198+
- `PreviousPersianWeek`: Retrieves the previous week.
199+
- `CurrentPersianMonth`: Retrieves the current month.
200+
- `NextPersianMonth`: Retrieves the next month.
201+
- `PreviousPersianMonth`: Retrieves the previous month.
202+
203+
These methods provide a convenient way to navigate through the Persian calendar, allowing you to easily access and manipulate date-related data.
204+
205+
![](https://github.com/shahabfar/persia.net/blob/master/screenshot_1.jpg)
206+
207+
These methods return an array of `PersianDateTime` objects, each containing detailed information about the requested week or month.
208+
209+
In the above image you can see the date-related data for the next week of given date as `PersianDateTime` array.
210+
211+
## Converting Arabic (Islamic) Date to Persian Date
212+
I'm actively working on this feature and it will be available in the near future. Stay tuned!
213+

0 commit comments

Comments
 (0)