Format Stringهای Enum

در بخش «Enums» در صفحهٔ 154، Formatting و Parsing مقدارهای Enum را توضیح دادیم. جدول 6-6 هر Format String و نتیجهٔ اعمال آن به Expression زیر را فهرست می‌کند:

Console.WriteLine (System.ConsoleColor.Red.ToString (formatString));

سایر Mechanismهای Conversion

در دو بخش قبل، Format Providerها، یعنی Mechanism اصلی .NET برای Formatting و Parsing، را پوشش دادیم. Mechanismهای مهم دیگر Conversion در Typeها و Namespaceهای مختلف پراکنده‌اند. بعضی به String و از String تبدیل می‌کنند و بعضی Conversionهای دیگری انجام می‌دهند. در این بخش موضوع‌های زیر را بررسی می‌کنیم:

• Class با نام Convert و Functionهای آن:
  • Conversion از Real به Integral که به‌جای Truncate کردن Round می‌کند.
  • Parsing عددها در Baseهای 2، 8 و 16.
  • Dynamic Conversionها.
  • Translationهای Base-64.
• XmlConvert و نقش آن در Formatting و Parsing برای XML.
• Type Converterها و نقش آن‌ها در Formatting و Parsing برای Designerها و XAML.
• BitConverter برای Binary Conversionها.

Convert

.NET Typeهای زیر را Base Type می‌نامد:

• bool، char، string، System.DateTime و System.DateTimeOffset.
• تمام Numeric Typeهای C#.

Class Static با نام Convert Methodهایی برای تبدیل هر Base Type به هر Base Type دیگر تعریف می‌کند. متأسفانه بیشتر این Methodها بی‌فایده‌اند: یا Exception Throw می‌کنند یا در کنار Implicit Castها زائد هستند. بااین‌حال، میان این شلوغی Methodهای مفیدی وجود دارند که در بخش‌های بعدی فهرست شده‌اند.

Round کردن Conversionهای Real به Integral

در فصل 2 دیدیم که Implicit و Explicit Castها چگونه Conversion بین Numeric Typeها را ممکن می‌کنند. خلاصه:

• Implicit Castها برای Conversionهای بدون Loss کار می‌کنند؛ برای مثال int به double.
• برای Conversionهای Lossy، مانند double به int، Explicit Cast لازم است.

Castها برای Efficiency بهینه شده‌اند؛ بنابراین Dataای را که جا نمی‌شود Truncate می‌کنند. هنگام تبدیل Real Number به Integer این می‌تواند Problem باشد، زیرا اغلب می‌خواهید به‌جای Truncate کردن، Round کنید. Methodهای Numeric Conversion در Convert دقیقاً همین مشکل را حل می‌کنند؛ آن‌ها همیشه Round می‌کنند:

double d = 3.9;
int i = Convert.ToInt32 (d);        // i == 4

Convert از Banker’s Rounding استفاده می‌کند که Midpointها را به Integerهای زوج Snap می‌کند؛ این کار از Bias مثبت یا منفی جلوگیری می‌کند. اگر Banker’s Rounding Problem ایجاد می‌کند، ابتدا روی Real Number، Math.Round را فراخوانی کنید؛ این Method Argument اضافی‌ای می‌پذیرد که امکان Control کردن Midpoint Rounding را می‌دهد.

Parsing عددها در Baseهای 2، 8 و 16

میان Methodهای To(integral-type) Overloadهایی پنهان شده‌اند که Numberها را در Base دیگری Parse می‌کنند:

int thirty = Convert.ToInt32 ("1E", 16);         // Parse in hexadecimal
uint five = Convert.ToUInt32 ("101", 2);         // Parse in binary

Argument دوم Base را تعیین می‌کند. می‌تواند هر Base دلخواهی باشد، به شرط آنکه 2، 8، 10 یا 16 باشد!

Dynamic Conversionها

گاهی لازم است از یک Type به Type دیگر تبدیل کنید اما تا Runtime نمی‌دانید Typeها چه هستند. Class با نام Convert برای این کار Method با نام ChangeType را فراهم می‌کند:

public static object ChangeType (object value, Type conversionType);

Source Type و Target Type باید یکی از «Base Type»ها باشند. ChangeType همچنین Argument اختیاری از نوع IFormatProvider می‌پذیرد. Example:

Type targetType = typeof (int);
object source = "42";

object result = Convert.ChangeType (source, targetType);

Console.WriteLine (result);               // 42
Console.WriteLine (result.GetType());     // System.Int32

یکی از کاربردهای احتمالی آن، نوشتن Deserializerای است که بتواند با چند Type کار کند. همچنین می‌تواند هر Enum را به Integral Type آن Convert کند؛ بخش «Enums» در صفحهٔ 154 را ببینید.

یکی از محدودیت‌های ChangeType این است که نمی‌توانید Format String یا Parsing Flag تعیین کنید.

Conversionهای Base-64

گاهی لازم است Binary Data مانند Bitmap را داخل Text Documentی مانند XML File یا Email Message قرار دهید. Base 64 روشی فراگیر برای Encoding Binary Data به Characterهای قابل‌خواندن است و از 64 Character مجموعهٔ ASCII استفاده می‌کند. Method با نام Convert.ToBase64String از Byte Array به Base 64 تبدیل می‌کند و FromBase64String Operation معکوس را انجام می‌دهد.

XmlConvert

اگر با Dataای سروکار دارید که از XML File آمده یا قرار است به XML File برود، XmlConvert در Namespace با نام System.Xml مناسب‌ترین Methodها را برای Formatting و Parsing فراهم می‌کند. Methodهای XmlConvert ظرافت‌های Formatting مربوط به XML را بدون نیاز به Format Stringهای ویژه مدیریت می‌کنند. برای Example، مقدار True در XML برابر "true" است نه "True". BCL در .NET به‌صورت داخلی به‌طور گسترده از XmlConvert استفاده می‌کند.

XmlConvert برای Serialization عمومی و مستقل از Culture نیز مناسب است. Methodهای Formatting در آن همگی به‌صورت Overloadهای ToString ارائه می‌شوند و Methodهای Parsing نام‌هایی مانند ToBoolean و ToDateTime دارند:

string s = XmlConvert.ToString (true);           // s = "true"
bool isTrue = XmlConvert.ToBoolean (s);

Methodهایی که به DateTime تبدیل می‌کنند یا از آن تبدیل می‌کنند، Argument از نوع XmlDateTimeSerializationMode می‌پذیرند. این Enum Valueهای زیر را دارد:

Unspecified, Local, Utc, RoundtripKind

Local و Utc هنگام Formatting باعث Conversion می‌شوند، اگر DateTime از قبل در آن Time Zone نباشد. سپس Time Zone به String اضافه می‌شود:

2010-02-22T14:08:30.9375            // Unspecified
2010-02-22T14:07:30.9375+09:00      // Local
2010-02-22T05:08:30.9375Z           // Utc

Unspecified قبل از Formatting هر Time-zone Information جاسازی‌شده در DateTime، یعنی DateTimeKind، را حذف می‌کند. RoundtripKind مقدار DateTimeKind مربوط به DateTime را رعایت می‌کند؛ بنابراین وقتی دوباره Parse شود، Struct حاصل از نوع DateTime دقیقاً همان چیزی خواهد بود که در ابتدا بود.

Type Converterها

Type Converterها برای Formatting و Parsing در Design-time Environmentها طراحی شده‌اند. آن‌ها همچنین Valueها را در Documentهای Extensible Application Markup Language یا XAML، همان‌گونه که در Windows Presentation Foundation یا WPF استفاده می‌شود، Parse می‌کنند.

در .NET بیش از 100 Type Converter وجود دارد و چیزهایی مانند Color، Image و URI را پوشش می‌دهند. در مقابل، Format Providerها فقط برای تعداد کمی از Value Typeهای ساده Implement شده‌اند.

Type Converterها معمولاً Stringها را به روش‌های مختلف و بدون نیاز به Hint Parse می‌کنند. برای Example، در یک WPF Application داخل Visual Studio، اگر با تایپ "Beige" در Property Window مربوط، Background Color یک Control را تنظیم کنید، Type Converter مربوط به Color تشخیص می‌دهد که منظور Color Name است نه RGB String یا System Color. این Flexibility گاهی Type Converterها را خارج از Designerها و XAML Documentها نیز مفید می‌کند.

تمام Type Converterها از TypeConverter در System.ComponentModel Subclass می‌شوند. برای گرفتن یک TypeConverter، TypeDescriptor.GetConverter را فراخوانی کنید. کد زیر یک TypeConverter برای Type با نام Color در Namespace با نام System.Drawing می‌گیرد:

TypeConverter cc = TypeDescriptor.GetConverter (typeof (Color));

در میان بسیاری Method دیگر، TypeConverter Methodهایی با نام ConvertToString و ConvertFromString تعریف می‌کند. می‌توانیم آن‌ها را چنین فراخوانی کنیم:

Color beige = (Color) cc.ConvertFromString ("Beige");
Color purple = (Color) cc.ConvertFromString ("#800080");
Color window = (Color) cc.ConvertFromString ("Window");

طبق Convention، نام Type Converterها به Converter ختم می‌شود و معمولاً در همان Namespace مربوط به Typeای قرار دارند که Convert می‌کنند. هر Type از طریق TypeConverterAttribute به Converter خود Link می‌شود و به Designerها امکان می‌دهد Converter را خودکار پیدا کنند.

Type Converterها همچنین می‌توانند Serviceهای Design-time مانند تولید Standard Value List برای پر کردن Drop-down List در Designer یا کمک به Code Serialization را فراهم کنند.

BitConverter

بیشتر Base Typeها را می‌توان با فراخوانی BitConverter.GetBytes به Byte Array تبدیل کرد:

foreach (byte b in BitConverter.GetBytes (3.5))
  Console.Write (b + " ");                              // 0 0 0 0 0 0 12 64

BitConverter همچنین Methodهایی مانند ToDouble برای Conversion در جهت معکوس فراهم می‌کند.

Typeهای decimal و DateTime(Offset) توسط BitConverter پشتیبانی نمی‌شوند. بااین‌حال، می‌توانید با فراخوانی decimal.GetBits یک decimal را به Array از int تبدیل کنید. برای جهت معکوس، decimal Constructorای دارد که Array از int می‌پذیرد.

برای DateTime می‌توانید روی Instance، ToBinary را فراخوانی کنید؛ این Method یک long برمی‌گرداند که سپس می‌توانید روی آن از BitConverter استفاده کنید. Method Static با نام DateTime.FromBinary Operation معکوس را انجام می‌دهد.

Globalization

Internationalize کردن Application دو جنبه دارد: Globalization و Localization.

Globalization با سه Task سروکار دارد، به ترتیب نزولی Importance:

1. اطمینان از اینکه Program هنگام اجرا در Culture دیگر خراب نمی‌شود.
2. رعایت Formatting Ruleهای Culture محلی؛ برای Example هنگام نمایش Dateها.
3. طراحی Program به شکلی که Data و Stringهای Culture-specific را از Satellite Assemblyهایی بردارد که بعداً بتوانید بنویسید و Deploy کنید.

Localization یعنی تکمیل Task آخر با نوشتن Satellite Assembly برای Cultureهای مشخص. می‌توانید این کار را پس از نوشتن Program انجام دهید؛ جزئیات در بخش «Resources and Satellite Assemblies» در صفحهٔ 776 آمده است.

.NET در Task دوم کمک می‌کند، زیرا به‌طور پیش‌فرض Ruleهای Culture-specific را اعمال می‌کند. پیش‌تر دیدیم که فراخوانی ToString روی DateTime یا Number، Formatting Ruleهای محلی را رعایت می‌کند. متأسفانه همین موضوع شکست در Task اول را آسان می‌کند: Program می‌تواند به این دلیل خراب شود که انتظار دارید Dateها یا Numberها مطابق Culture فرض‌شده Format شوند. Solution، همان‌طور که دیدیم، این است که هنگام Formatting و Parsing Culture مشخصی مانند Invariant Culture را تعیین کنید یا از Methodهای مستقل از Culture مانند Methodهای XmlConvert استفاده کنید.

Checklist مربوط به Globalization

نکات مهم را در همین فصل پوشش داده‌ایم. خلاصهٔ کارهای اساسی لازم:

• Unicode و Text Encodingها را درک کنید؛ بخش «Text Encodings and Unicode» در صفحهٔ 301 را ببینید.
• به یاد داشته باشید Methodهایی مانند ToUpper و ToLower روی char و string Culture-sensitive هستند؛ مگر اینکه Culture Sensitivity بخواهید، از ToUpperInvariant/ToLowerInvariant استفاده کنید.
• برای DateTime و DateTimeOffset Mechanismهای Formatting و Parsing مستقل از Culture مانند ToString("o") و XmlConvert را ترجیح دهید.

• در غیر این صورت، هنگام Formatting/Parsing Numberها یا Date/Timeها Culture را مشخص کنید، مگر اینکه رفتار Local Culture را بخواهید.

Testing

می‌توانید با Reassign کردن Property با نام CurrentCulture مربوط به Thread در System.Threading، Cultureهای مختلف را Test کنید. کد زیر Current Culture را به Turkey تغییر می‌دهد:

Thread.CurrentThread.CurrentCulture = CultureInfo.GetCultureInfo ("tr-TR");

Turkey Test Case بسیار خوبی است، زیرا:

• "i".ToUpper() != "I" و "I".ToLower() != "i".
• Dateها به شکل Day.Month.Year Format می‌شوند؛ به Period Separator توجه کنید.
• Decimal Point Indicator یک Comma است نه Period.

همچنین می‌توانید با تغییر Settingهای Number و Date Formatting در Windows Control Panel آزمایش کنید؛ این Settingها در Culture پیش‌فرض، یعنی CultureInfo.CurrentCulture، منعکس می‌شوند.

CultureInfo.GetCultures() Arrayای از همهٔ Cultureهای موجود برمی‌گرداند.

کار با Numberها

Conversionها

Numeric Conversionها را در فصل‌ها و بخش‌های پیشین پوشش دادیم؛ جدول 6-7 همهٔ Optionها را خلاصه می‌کند.

double d = double.Parse ("3.5");
int i;
bool ok = int.TryParse ("3", out i);

int i = Convert.ToInt32 ("1E", 16);

string hex = 45.ToString ("X");

int i = 23;
double d = i;

double d = 23.5;
int i = (int) d;

double d = 23.5;
int i = Convert.ToInt32 (d);

Math

جدول 6-8 Memberهای کلیدی Class Static با نام Math را فهرست می‌کند. Functionهای Trigonometric Argument از نوع double می‌پذیرند؛ Methodهای دیگر مانند Max Overload شده‌اند تا روی همهٔ Numeric Typeها کار کنند. Class با نام Math همچنین Constantهای ریاضی E (e) و PI را تعریف می‌کند.

Method با نام Round اجازه می‌دهد Number مربوط به Decimal Placeهای Rounding و همچنین نحوهٔ Handling Midpointها، یعنی Away from Zero یا Banker’s Rounding، را مشخص کنید. Floor و Ceiling به نزدیک‌ترین Integer Round می‌کنند: Floor همیشه رو به پایین و Ceiling همیشه رو به بالا Round می‌کند، حتی برای Numberهای منفی.

Max و Min فقط دو Argument می‌پذیرند. اگر Array یا Sequenceای از Numberها دارید، از Extension Methodهای Max و Min در System.Linq.Enumerable استفاده کنید.

BigInteger

Struct با نام BigInteger یک Numeric Type تخصصی است. در Namespace با نام System.Numerics قرار دارد و اجازه می‌دهد Integerای با اندازهٔ دلخواه و بدون Loss of Precision نمایش دهید.

C# پشتیبانی Native برای BigInteger ندارد، بنابراین راهی برای نمایش Literalهای BigInteger وجود ندارد. بااین‌حال، می‌توانید از هر Integral Type دیگر به BigInteger به‌صورت Implicit Convert کنید:

BigInteger twentyFive = 25;            // implicit conversion from integer

برای نمایش Number بزرگ‌تری مانند یک Googol، یعنی 10¹⁰⁰، می‌توانید از یکی از Methodهای Static مربوط به BigInteger مانند Pow، یعنی Raise to the Power، استفاده کنید:

BigInteger googol = BigInteger.Pow (10, 100);

یا می‌توانید یک String را Parse کنید:

BigInteger googol = BigInteger.Parse ("1".PadRight (101, '0'));

فراخوانی ToString() روی آن تمام Digitها را Print می‌کند:

Console.WriteLine (googol.ToString()); // 10000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000000000

می‌توانید با Explicit Cast Operator بین BigInteger و Numeric Typeهای Standard Conversionهایی انجام دهید که بالقوه Lossy هستند:

double g2 = (double) googol;          // Explicit cast
BigInteger g3 = (BigInteger) g2;      // Explicit cast
Console.WriteLine (g3);

Output زیر Loss of Precision را نشان می‌دهد:

9999999999999999673361688041166912...

BigInteger همهٔ Arithmetic Operatorها، شامل Remainder با علامت %، و همچنین Comparison و Equality Operatorها را Overload می‌کند.

همچنین می‌توانید BigInteger را از Byte Array بسازید. کد زیر یک Random Number سی‌ودوبایتی مناسب Cryptography تولید و سپس آن را به BigInteger Assign می‌کند:

// This uses the System.Security.Cryptography namespace:
RandomNumberGenerator rand = RandomNumberGenerator.Create();
byte[] bytes = new byte [32];
rand.GetBytes (bytes);
var bigRandomNumber = new BigInteger (bytes);   // Convert to BigInteger

مزیت ذخیرهٔ چنین Numberی در BigInteger نسبت به Byte Array این است که Value-type Semantics دریافت می‌کنید. فراخوانی ToByteArray یک BigInteger را دوباره به Byte Array تبدیل می‌کند.

Half

Struct با نام Half یک Floating-point Type شانزده‌بیتی است و همراه .NET 5 معرفی شد. Half عمدتاً برای Interoperate کردن با Processorهای Graphics Card در نظر گرفته شده و در بیشتر CPUها Native Support ندارد.

می‌توانید از طریق Explicit Cast بین Half و float یا double تبدیل کنید:

Half h = (Half) 123.456;
Console.WriteLine (h);       // 123.44   (note loss of precision)

هیچ Arithmetic Operationای برای این Type تعریف نشده است، بنابراین برای انجام Calculation باید به Type دیگری مانند float یا double Convert کنید.

Half Rangeای از -65500 تا 65500 دارد:

Console.WriteLine (Half.MinValue);     // -65500
Console.WriteLine (Half.MaxValue);     // 65500

به Loss of Precision در Maximum Range توجه کنید:

Console.WriteLine ((Half)65500);       // 65500
Console.WriteLine ((Half)65490);       // 65500
Console.WriteLine ((Half)65480);       // 65470

Complex

Struct با نام Complex Numeric Type تخصصی دیگری است که Complex Numberها را با Real و Imaginary Component از نوع double نمایش می‌دهد. Complex همراه BigInteger در Namespace با نام System.Numerics قرار دارد.

برای استفاده از Complex، Struct را Instantiate و Real و Imaginary Valueها را مشخص کنید:

var c1 = new Complex (2, 3.5);
var c2 = new Complex (3, 0);

Implicit Conversionهایی از Numeric Typeهای Standard نیز وجود دارند.

Struct با نام Complex Propertyهایی برای Real و Imaginary Value و همچنین Phase و Magnitude ارائه می‌کند:

Console.WriteLine (c1.Real);         // 2
Console.WriteLine (c1.Imaginary);    // 3.5
Console.WriteLine (c1.Phase);        // 1.05165021254837
Console.WriteLine (c1.Magnitude);    // 4.03112887414927

همچنین می‌توانید Complex Number را با مشخص کردن Magnitude و Phase بسازید:

Complex c3 = Complex.FromPolarCoordinates (1.3, 5);

Arithmetic Operatorهای Standard برای کار با Complex Numberها Overload شده‌اند:

Console.WriteLine (c1 + c2);       // (5, 3.5)
Console.WriteLine (c1 * c2);       // (6, 10.5)

Struct با نام Complex Methodهای Static برای Functionهای پیشرفته‌تر ارائه می‌کند، از جمله:

• Trigonometric مانند Sin، Asin، Sinh، Tan و غیره.
• Logarithm و Exponentiation.
• Conjugate.

Random

Class با نام Random Sequenceای Pseudorandom از Random Byteها، Integerها یا Doubleها تولید می‌کند.

برای استفاده از Random، ابتدا آن را Instantiate می‌کنید و به‌صورت اختیاری Seedای برای شروع Random Number Series می‌دهید. استفاده از Seed یکسان، در صورت اجرا زیر همان CLR Version، Series یکسانی از Numberها را تضمین می‌کند؛ گاهی زمانی که Reproducibility می‌خواهید مفید است:

Random r1 = new Random (1);
Random r2 = new Random (1);
Console.WriteLine (r1.Next (100) + ", " + r1.Next (100));              // 24, 11
Console.WriteLine (r2.Next (100) + ", " + r2.Next (100));              // 24, 11

اگر Reproducibility نمی‌خواهید، می‌توانید Random را بدون Seed بسازید؛ در این حالت Current System Time را برای ساخت Seed به کار می‌گیرد.

فراخوانی Next(n) Random Integerای بین 0 و n-1 تولید می‌کند. NextDouble Random Doubleای بین 0 و 1 تولید می‌کند. NextBytes یک Byte Array را با Random Valueها پر می‌کند.

از .NET 8، Class با نام Random Method با نام GetItems دارد که n Item تصادفی از Collection انتخاب می‌کند. کد زیر دو Random Number از Collection پنج‌تایی برمی‌گزیند:

int[] numbers = { 10, 20, 30, 40, 50 };
int[] randomTwo = new Random().GetItems (numbers, 2);

از .NET 8، Method با نام Shuffle نیز برای Randomize کردن Order مربوط به Itemها داخل Array یا Span وجود دارد.

Random برای Applicationهای High-security مانند Cryptography به اندازهٔ کافی Random در نظر گرفته نمی‌شود. برای این کار، .NET یک Cryptographically Strong Random Number Generator در Namespace با نام System.Security.Cryptography فراهم می‌کند. روش استفاده:

var rand = System.Security.Cryptography.RandomNumberGenerator.Create();
byte[] bytes = new byte [32];
rand.GetBytes (bytes);        // Fill the byte array with random numbers.

نقطه‌ضعف این است که Flexibility کمتری دارد: پر کردن Byte Array تنها راه گرفتن Random Number است. برای گرفتن Integer باید از BitConverter استفاده کنید:

byte[] bytes = new byte [4];
rand.GetBytes (bytes);
int i = BitConverter.ToInt32 (bytes, 0);

BitOperations

Class با نام System.Numerics.BitOperations که از .NET 6 وجود دارد، Methodهای زیر را برای کمک به Operationهای Base-2 ارائه می‌کند:

IsPow2

اگر Number توان 2 باشد true برمی‌گرداند.

LeadingZeroCount/TrailingZeroCount

تعداد Zeroهای ابتدایی یا انتهایی را هنگامی که Number به شکل Unsigned Integer سی‌ودوبیتی یا شصت‌وچهاربیتی در Base 2 Format شده باشد برمی‌گرداند.

Log2

Integer Base-2 Log یک Unsigned Integer را برمی‌گرداند.

PopCount

تعداد Bitهایی را که روی 1 تنظیم شده‌اند در یک Unsigned Integer برمی‌گرداند.

RotateLeft/RotateRight

Bitwise Rotation به چپ یا راست انجام می‌دهد.

RoundUpToPowerOf2

Unsigned Integer را رو به بالا به نزدیک‌ترین Power of 2 Round می‌کند.

Enums

در فصل 3، Enum Type در C# را توضیح دادیم و نشان دادیم چگونه Memberها را Combine کنیم، Equality را Test کنیم، Logical Operatorها را به کار ببریم و Conversion انجام دهیم. .NET پشتیبانی C# از Enumها را از طریق Type با نام System.Enum گسترش می‌دهد. این Type دو Role دارد:

• فراهم کردن Type Unification برای همهٔ Enum Typeها.
• تعریف Static Utility Methodها.

Type Unification یعنی می‌توانید هر Enum Member را به‌صورت Implicit به Instance از System.Enum Cast کنید:

Display (Nut.Macadamia);          // Nut.Macadamia
Display (Size.Large);             // Size.Large

void Display (Enum value)
{
  Console.WriteLine (value.GetType().Name + "." + value.ToString());
}

enum Nut { Walnut, Hazelnut, Macadamia }
enum Size { Small, Medium, Large }

Static Utility Methodهای System.Enum عمدتاً به انجام Conversion و گرفتن List از Memberها مربوط می‌شوند.