سلسلة net. للمحترفين تحليل التاريخ والوقت في dot NET

التابع ParseExact

يَستقبِل التابع DateTime.ParseExact مُعامِلًا ثالثًا، والذي يُحدِّد مَحلّيّة (Culture/Locale) صِيْغة سلسلة التنسيق (Format String)، مما يُمكِنك من تمرير قيمة مَحلّيّة مُحدّدة. يُؤدي تمرير القيمة الفارغة (null) أو القيمة CultureInfo.CurrentCulture إلى استخدام مَحلّيّة النظام.

var dateString = "2015-11-24";


var date = DateTime.ParseExact(dateString, "yyyy-MM-dd", null);
Console.WriteLine(date);

11/24/2015 12:00:00 AM

صِيْغ سلسلة التنسيق (Format Strings)

لابّد أن تَتَّلائَم السلسلة النصية المُعطاة مع صِيْغة سلسلة التنسيق (Format String).

var date = DateTime.ParseExact("24|201511", "dd|yyyyMM", null);
Console.WriteLine(date);

11/24/2015 12:00:00 AM

إذا احتوت صِيْغة سلسلة التنسيق (Format String) على أيّة حروف غير مُحدِّدة للتنسيق (Format Specifiers)، فإنها تُعامَل كـسلسلة نصية مُجردَّة.

var date = DateTime.ParseExact("2015|11|24", "yyyy|MM|dd", null);
Console.WriteLine(date);

11/24/2015 12:00:00 AM

يُفرّق مُحدِّد التنسيق (Format Specifiers) بين حالات الحرف (Case). فمثلًا، في المثال التالي، حُلّلت قيم كلًا من الشهر والدقيقة إلى مَقاصِد خاطئة.

var date = DateTime.ParseExact("2015-01-24 11:11:30", "yyyy-mm-dd hh:MM:ss", null);
Console.WriteLine(date);

11/24/2015 11:01:30 AM

لابّد لصِيْغ سلسلة التنسيق (Format Strings) المُكونّة من حرف وحيد أن تكون قِياسية.

var date = DateTime.ParseExact("11/24/2015", "d", new CultureInfo("en-US"));
var date = DateTime.ParseExact("2015-11-24T10:15:45", "s", null);
var date = DateTime.ParseExact("2015-11-24 10:15:45Z", "u", null);

الاعتراضات (Exceptions)

يُبَلَّغ عن اعتراض من النوع ArgumentNullException عند تمرير قيمة فارغة (null).

var date = DateTime.ParseExact(null, "yyyy-MM-dd", null);
var date = DateTime.ParseExact("2015-11-24", null, null);

يُبَلَّغ عن اعتراض من النوع FormatException، إمِا لِكَوْن صِيغة سلسلة التنسيق غير صالحة، أو لعدم تَلاؤمها مع السلسلة النصية المُعطاة.

var date = DateTime.ParseExact("", "yyyy-MM-dd", null);
var date = DateTime.ParseExact("2015-11-24", "", null);
var date = DateTime.ParseExact("2015-0C-24", "yyyy-MM-dd", null);
var date = DateTime.ParseExact("2015-11-24", "yyyy-QQ-dd", null);


// Single-character format strings must be one of the standard formats
var date = DateTime.ParseExact("2015-11-24", "q", null);


// Format strings must match the input exactly* (see next section)
var date = DateTime.ParseExact("2015-11-24", "d", null); // Expects 11/24/2015 or 24/11/2015 for most cultures

معالجة أكثر من صيغة سلسلة تنسيق محتملة

var date = DateTime.ParseExact("2015-11-24T10:15:45",
new [] { "s", "t", "u", "yyyy-MM-dd" }, // Will succeed as long as input matches one of these
CultureInfo.CurrentCulture, DateTimeStyles.None);

معالجة الاختلافات المحلية لصيغ سلسلة التنسيق

var dateString = "10/11/2015";
var date = DateTime.ParseExact(dateString, "d", new CultureInfo("en-US"));
Console.WriteLine("Day: {0}; Month: {1}", date.Day, date.Month);

Day: 11; Month: 10

date = DateTime.ParseExact(dateString, "d", new CultureInfo("en-GB"));
Console.WriteLine("Day: {0}; Month: {1}", date.Day, date.Month);

Day: 10; Month: 11

التابع TryParse

تَستَقبِل البصمة TryParse(string, out DateTime)‎ كلًا من السلسلة النصية المراد تحليلها كمُعامِل دخْل، بالإضافة إلى مُتغير آخر كمُعامِل خْرج. يُحِاول التابع تحليل السلسلة النصية المُعطاة إلى النوع DateTime، ثم يُعيد قيمة منطقية Boolean تُحدِّد إذا ما نجح أم لا.

تُسند نتيجة التحليل إلى مُتغير الخْرج إذا ما نجحت العملية، بينما تُسنَد القيمة الافتراضية DateTime.MinValue للمُتغير في حالة الفشل.

DateTime parsedValue;
if (DateTime.TryParse("monkey", out parsedValue))
{
        Console.WriteLine("Apparently, 'monkey' is a date/time value. Who knew?");
}

في المثال التالي، يُحاول التابع تَحليل السلسلة النصية المُعطاة وفقًا لكُلًا من صِيْغ التنسيق (Formats) الشائعة مِثْل ISO 8601، وإعدادات مَحلّيّة النظام.

DateTime.TryParse("11/24/2015 14:28:42", out parsedValue); // true
DateTime.TryParse("2015-11-24 14:28:42", out parsedValue); // true
DateTime.TryParse("2015-11-24T14:28:42", out parsedValue); // true
DateTime.TryParse("Sat, 24 Nov 2015 14:28:42", out parsedValue); // true

لمّا كان هذا التابع لا يَستقبِل قيمة تُحدِّد مَحلّيّة (Culture/Locale) صيْغة التنسيق (Format)، لذا فإنه يَعتمِد على إعدادات مَحلّيّة النظام، مما قد يُؤدي إلى نتائج غير متوقعة.

في الأمثلة التالية، لاحظ كيف تُؤثِر مَحلّيّة النظام على قيمة الخُرج.

// System set to en-US culture
bool result = DateTime.TryParse("24/11/2015", out parsedValue);
Console.WriteLine(result);

False

// System set to en-GB culture
bool result = DateTime.TryParse("11/24/2015", out parsedValue);
Console.WriteLine(result);

False

// System set to en-GB culture
bool result = DateTime.TryParse("10/11/2015", out parsedValue);
Console.WriteLine(result);

True

في المثال اﻷخير، لاحظ أنه إذا كنت تَمكُث في الولايات المتحدة الأمريكية بينما إعدادات مَحلّيّة نِظامك مَضبْوطة على en-GB، فقد تُفاجئ بأن النتيجة هي 10 نوفمبر وليس 11 أكتوبر.

تَستقبِل بصمة اخرى من نفس التابع TryParse(string, IFormatProvider, DateTimeStyles, out DateTime)‎ مُعامِلًا من النوع IFormatProvider بِخِلاف تابعه الشقيق، وذلك لتحديد مَحلّيّة (Culture) صِيْغة التنسيق (Format)، والتي تَؤول إلى مَحلّيّة النظام في حالة تمرير قيمة فارغة null. يَسمَح هذا التابع أيضًا بتحديد صِيْغة التنسيق من خلال مُعامِل من النوع تِعداد (Enum) من الصنف DateTimeStyles.

if (DateTime.TryParse(" monkey ", new CultureInfo("en-GB"),
DateTimeStyles.AllowLeadingWhite | DateTimeStyles.AllowTrailingWhite, out parsedValue)
{
    Console.WriteLine("Apparently, ' monkey ' is a date/time value. Who knew?");
}

اعتراضات (Exceptions)

في بعض الحالات المُحدَّدة، قد يُبَلِّغ هذا التابع عن إعتراضات (Exceptions)، تَتَّعلّق بمُعامِلات الدخْل التي أُضيفت خلال التحميل الزائد للتابع (Method Overloading). بالتحديد مُعامِل الواجهة IFormatProvider ومُعامِل التعداد من الصنف DateTimeStyles.

الاعتراضات المُحتملة:

• اعتراض من النوع NotSupportedException: إذا كانت قيمة وسيط المُعامِل IFormatProvider مُحايدة.

• اعتراض من النوع ArgumentException: إمّا لعدم صلاحية قيمة وسيط المُعامِل DateTimeStyles أو لاحِتواءُه على قيم مُتعارِضة مثل AssumeUniversal وAssumeLocal.

التابع TryParseExact

يُعدّ هذا التابع تَجميِعة لكلًا من التابعين TryParse وParseExact؛ فهو يَسمَح - مثل التابع ParseExact - بتحديد صِيْغ سلسلة التنسيق (Format Strings) مُخصصة، كما يُعِيد - مثل التابع TryParse - قيمة منطقية Boolean تُحدد إذا ما حُللّت السلسلة النصية بنجاح أم لا، بدلًا من التبلّيغ عن إعتراض (Exception) في حالة الفشل.

تحاول البصمة TryParseExact(string, string, IFormatProvider, DateTimeStyles, out DateTime)‎ من التابع تحليل السلسلة النصية المُعطاة وِفقًا لصِيْغة سلسلة التنسيق (Format String) مُحددة. لابّد للسلسلة النصية أن تَتَلائَم مع الصِيْغة لِضمان تحليل ناجح.

DateTime.TryParseExact("11242015", "MMddyyyy", null, DateTimeStyles.None, out parsedValue); // true

تحاول البصمة TryParseExact(string, string[], IFormatProvider, DateTimeStyles, out DateTime)‎ من التابع تحليل السلسلة النصية المُعطاة وِفقًا لمصفوفة من صِيْغ سلسلة التنسيق (Format Strings). لابّد للسلسلة النصية أن تَتَلائَم مع صِيْغة واحدة على الأقل لِضمان تحليل ناجح.

DateTime.TryParseExact("11242015", new [] { "yyyy-MM-dd", "MMddyyyy" }, null, DateTimeStyles.None, out parsedValue); // true

ترجمة -وبتصرف- للفصل DateTime parsing من كتاب ‎.NET Framework Notes for Professionals