ICustomFormatter インターフェイス

定義

名前空間:

System

アセンブリ:

netstandard.dll, System.Runtime.dll

オブジェクトの値のカスタム書式設定をサポートするメソッドを定義します。

C#

public interface ICustomFormatter

例

次の例では、 ICustomFormatter を実装して、整数値のバイナリ、8 進数、および 16 進数の書式設定を許可します。 この例では、1 つのクラス MyFormatterである が と IFormatProviderの両方ICustomFormatterを実装しています。 その IFormatProvider.GetFormat メソッドは、パラメーターが型を formatType 表 ICustomFormatter すかどうかを決定します。 の場合は、 MyFormatter それ自体のインスタンスを返します。それ以外の場合は を返します null。 その ICustomFormatter.Format 実装では、format パラメーターが、サポートされている 3 つの書式指定文字列 (バイナリの場合は "B"、8 進数の場合は "O"、16 進数の場合は "H" ) の 1 つであるかどうかを判断し、パラメーターの書式を適切に設定します arg 。 それ以外の場合、 が でないnull場合argは、存在するarg場合はパラメーターのIFormattable.ToString実装を呼び出し、存在しない場合はパラメーターなしのToStringメソッドを呼び出します。 arg が null の場合、メソッドは String.Empty を返します。

C#

using System;
using System.Globalization;
using System.Numerics;

public class MyFormatter : IFormatProvider, ICustomFormatter
{
    // IFormatProvider.GetFormat implementation.
    public object GetFormat(Type formatType)
    {
        // Determine whether custom formatting object is requested.
        if (formatType == typeof(ICustomFormatter))
            return this;
        else
            return null;
    }

    // Format number in binary (B), octal (O), or hexadecimal (H).
    public string Format(string format, object arg, IFormatProvider formatProvider)
    {
        // Handle format string.
        int baseNumber;
        // Handle null or empty format string, string with precision specifier.
        string thisFmt = String.Empty;
        // Extract first character of format string (precision specifiers
        // are not supported).
        if (!String.IsNullOrEmpty(format))
            thisFmt = format.Length > 1 ? format.Substring(0, 1) : format;

        // Get a byte array representing the numeric value.
        byte[] bytes;
        if (arg is sbyte)
        {
            string byteString = ((sbyte)arg).ToString("X2");
            bytes = new byte[1] { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber) };
        }
        else if (arg is byte)
        {
            bytes = new byte[1] { (byte)arg };
        }
        else if (arg is short)
        {
            bytes = BitConverter.GetBytes((short)arg);
        }
        else if (arg is int)
        {
            bytes = BitConverter.GetBytes((int)arg);
        }
        else if (arg is long)
        {
            bytes = BitConverter.GetBytes((long)arg);
        }
        else if (arg is ushort)
        {
            bytes = BitConverter.GetBytes((ushort)arg);
        }
        else if (arg is uint)
        {
            bytes = BitConverter.GetBytes((uint)arg);
        }
        else if (arg is ulong)
        {
            bytes = BitConverter.GetBytes((ulong)arg);
        }
        else if (arg is BigInteger)
        {
            bytes = ((BigInteger)arg).ToByteArray();
        }
        else
        {
            try
            {
                return HandleOtherFormats(format, arg);
            }
            catch (FormatException e)
            {
                throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
            }
        }

        switch (thisFmt.ToUpper())
        {
            // Binary formatting.
            case "B":
                baseNumber = 2;
                break;
            case "O":
                baseNumber = 8;
                break;
            case "H":
                baseNumber = 16;
                break;
            // Handle unsupported format strings.
            default:
                try
                {
                    return HandleOtherFormats(format, arg);
                }
                catch (FormatException e)
                {
                    throw new FormatException(String.Format("The format of '{0}' is invalid.", format), e);
                }
        }

        // Return a formatted string.
        string numericString = String.Empty;
        for (int ctr = bytes.GetUpperBound(0); ctr >= bytes.GetLowerBound(0); ctr--)
        {
            string byteString = Convert.ToString(bytes[ctr], baseNumber);
            if (baseNumber == 2)
                byteString = new String('0', 8 - byteString.Length) + byteString;
            else if (baseNumber == 8)
                byteString = new String('0', 4 - byteString.Length) + byteString;
            // Base is 16.
            else
                byteString = new String('0', 2 - byteString.Length) + byteString;

            numericString += byteString + " ";
        }
        return numericString.Trim();
    }

    private string HandleOtherFormats(string format, object arg)
    {
        if (arg is IFormattable)
            return ((IFormattable)arg).ToString(format, CultureInfo.CurrentCulture);
        else if (arg != null)
            return arg.ToString();
        else
            return String.Empty;
    }
}

MyFormatter次の例に示すように、 オブジェクトを メソッドのFormatパラメーターとしてprovider渡MyFormatterすことで、カスタム書式設定を提供するために使用できます。

C#

public class Example
{
    public static void Main()
    {
        Console.WindowWidth = 100;

        byte byteValue = 124;
        Console.WriteLine(String.Format(new MyFormatter(),
                                        "{0} (binary: {0:B}) (hex: {0:H})", byteValue));

        int intValue = 23045;
        Console.WriteLine(String.Format(new MyFormatter(),
                                        "{0} (binary: {0:B}) (hex: {0:H})", intValue));

        ulong ulngValue = 31906574882;
        Console.WriteLine(String.Format(new MyFormatter(),
                                        "{0}\n   (binary: {0:B})\n   (hex: {0:H})",
                                        ulngValue));

        BigInteger bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2);
        Console.WriteLine(String.Format(new MyFormatter(),
                                        "{0}\n   (binary: {0:B})\n   (hex: {0:H})",
                                        bigIntValue));
    }
}
// The example displays the following output:
//    124 (binary: 01111100) (hex: 7c)
//    23045 (binary: 00000000 00000000 01011010 00000101) (hex: 00 00 5a 05)
//    31906574882
//       (binary: 00000000 00000000 00000000 00000111 01101101 11000111 10110010 00100010)
//       (hex: 00 00 00 07 6d c7 b2 22)
//    18446744073709551614
//       (binary: 00000000 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110)
//       (hex: 00 ff ff ff ff ff ff ff fe)

注釈

インターフェイスには ICustomFormatter 、 という 1 つのメソッドが ICustomFormatter.Format含まれています。 このインターフェイスが参照型または値型によって実装されている場合、 Format メソッドはオブジェクトの値のカスタム形式の文字列表現を返します。

通常、インターフェイスは インターフェイスと共IFormatProviderに実装され、ICustomFormatterパラメーターを含む 2 つの.NET Framework複合文字列書式設定メソッドの動作をIFormatProviderカスタマイズします。 具体的には、 インターフェイスはICustomFormatter、 メソッドと StringBuilder.AppendFormat(IFormatProvider, String, Object[]) メソッドに渡されるオブジェクトの値のカスタム書式設定をString.Format(IFormatProvider, String, Object[])提供できます。

オブジェクトの値のカスタム表現を指定するには、次の操作を行う必要があります。

1. インターフェイスとその 1 つのメンバーである メソッドを ICustomFormatter 実装するクラスを Format 定義します。

2. インターフェイスとその 1 つのメンバーである メソッドを IFormatProvider 実装するクラスを GetFormat 定義します。 メソッドは GetFormat 、実装のインスタンスを ICustomFormatter 返します。 多くの場合、1 つのクラスは と IFormatProviderの両方ICustomFormatterを実装します。 その場合、クラスの GetFormat 実装はそれ自体のインスタンスを返すだけです。

3. 実装を IFormatProvider メソッドの引数または同等のString.Format(IFormatProvider, String, Object[])メソッドとしてprovider渡します。

その後、.NET ライブラリ メソッドでは、独自の書式ではなくカスタム書式が使用されます。

注意 (実装者)

共通言語ランタイムは、複合書式指定文字列内のすべての書式指定項目に対して ICustomFormatter 実装の使用を試みます。 その結果、処理するように設計されていないオブジェクトまたは値に書式設定サービスを提供するために、実装が呼び出されることを期待 ICustomFormatter する必要があります。 このような場合、メソッドは、 Format(String, Object, IFormatProvider) そのオブジェクトまたは値に対して適切な書式設定メソッドを呼び出す必要があります。

実装には、組み込みと拡張の ICustomFormatter 2 種類があります。

組み込み実装は、アプリケーション定義オブジェクトのカスタム書式を提供する実装です。 この場合、実装には次のものが含まれている必要があります。

• オブジェクトの書式設定を定義する書式指定文字列の定義。 書式指定文字列は省略可能です。 通常、"G" または "g" の書式指定文字列は、一般的な (または最も一般的に使用される) 形式を定義します。 ただし、任意の書式指定文字列を自由に定義できます。 また、大文字と小文字を区別するか、大文字と小文字を区別するかを自由に決定できます。

• メソッドに渡されるオブジェクトの型がアプリケーション定義型であることを確認する Format(String, Object, IFormatProvider) テスト。 存在しない場合は、オブジェクトの IFormattable 実装 (存在する場合)、または存在しない場合はそのメソッドを ToString() 呼び出す必要があります。 これらのメソッド呼び出しでスローされる可能性がある例外を処理する準備が整う必要があります。

• 実装で書式指定文字列がサポートされている場合は、null 書式指定文字列を処理するコード。 最も一般的な方法は、null 書式指定文字列を一般的な書式指定子に置き換えることです。

• 実装でサポートされている書式指定文字列を処理するコード。

• サポートされていない書式指定文字列を処理するコード。 最も一般的な方法は、 を FormatExceptionスローすることですが、既定の書式設定を指定できます。

拡張機能の実装は、書式設定が既にサポートされている型のカスタム書式を提供する実装です。 たとえば、整数型を特定の CustomerNumberFormatter 数字の間にハイフンで書式設定する を定義できます。 この場合、実装には次のものが含まれている必要があります。

• オブジェクトの書式設定を拡張する書式指定文字列の定義。 これらの書式指定文字列は必須ですが、型の既存の書式指定文字列と競合してはなりません。 たとえば、型の書式設定を Int32 拡張する場合は、特に "C"、"D"、"E"、"F"、および "G" 書式指定子を実装しないでください。

• メソッドに渡されるオブジェクトの型が、拡張機能でサポートされている Format(String, Object, IFormatProvider) 書式を持つ型であることをテストします。 存在しない場合は、オブジェクトの IFormattable 実装 (存在する場合) を呼び出すか、存在しない場合はオブジェクトのパラメーターなしの ToString() メソッドを呼び出します。 これらのメソッド呼び出しでスローされる可能性がある例外を処理する準備が整う必要があります。

• 拡張機能でサポートされている書式指定文字列を処理するコード。

• 拡張機能でサポートされていない書式指定文字列を処理するコード。 これらは型 IFormattable の実装に渡す必要があります。 これらのメソッド呼び出しでスローされる可能性がある例外を処理する準備が整う必要があります。

メソッド

Format(String, Object, IFormatProvider)

指定した形式およびカルチャ固有の書式設定情報を使用して、指定したオブジェクトの値をそれと等価の文字列形式に変換します。

適用対象

こちらもご覧ください

• IFormatProvider