ICustomFormatter 接口

定义

定义一个方法,该方法支持自定义对象值的格式。

public interface class ICustomFormatter
public interface ICustomFormatter
[System.Runtime.InteropServices.ComVisible(true)]
public interface ICustomFormatter
type ICustomFormatter = interface
[<System.Runtime.InteropServices.ComVisible(true)>]
type ICustomFormatter = interface
Public Interface ICustomFormatter
属性

示例

下面的示例实现 ICustomFormatter 允许整数值的二进制、八进制和十六进制格式。 在此示例中,单个类 IBinaryFormatter实现这两个类 ICustomFormatterIFormatProvider。 其 IFormatProvider.GetFormat 方法确定参数是否 formatType 表示类型 ICustomFormatter 。 如果这样做, BinaryFormatter 则返回自身的实例;否则返回 null。 它的 ICustomFormatter.Format 实现确定格式参数是否为三个受支持的格式字符串之一, (“B”用于二进制,“O”表示八进制,对于十六进制) 为“H”,并适当设置参数的格式 arg 。 否则,如果 arg 不存在 null,则调用 arg 参数的 IFormattable.ToString 实现(如果存在)或其无 ToString 参数方法(如果不存在)。 如果 argnull,则此方法返回 String.Empty

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

public class BinaryFormatter : 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;
   }
}
open System
open System.Globalization
open System.Numerics

type BinaryFormatter() =
    interface IFormatProvider with
        // IFormatProvider.GetFormat implementation.
        member this.GetFormat(formatType: Type) =
            // Determine whether custom formatting object is requested.
            if formatType = typeof<ICustomFormatter> then
                this
            else
                null

    interface ICustomFormatter with
        // Format number in binary (B), octal (O), or hexadecimal (H).
        member this.Format(format, arg: obj, formatProvider: IFormatProvider) =
            // Handle null or empty format string, string with precision specifier.
            let thisFmt =
                // Extract first character of format string (precision specifiers
                // are not supported).
                if String.IsNullOrEmpty format |> not then
                    if format.Length > 1 then 
                        format.Substring(0, 1) 
                    else 
                        format
                else
                    String.Empty

            // Get a byte array representing the numeric value.
            let bytes =
                match arg with
                | :? sbyte as arg ->
                    let byteString = arg.ToString "X2"
                    Some [| Byte.Parse(byteString, NumberStyles.HexNumber) |]
                | :? byte as arg ->
                    Some [| arg |]
                | :? int16 as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? int as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? int64 as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? uint16 as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? uint as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? uint64 as arg ->
                    BitConverter.GetBytes arg
                    |> Some
                | :? bigint as arg ->
                    arg.ToByteArray()
                    |> Some
                | _ ->
                    None
            let baseNumber =
                match thisFmt.ToUpper() with
                    // Binary formatting.
                    | "B" -> Some 2
                    | "O" -> Some 8
                    | "H" -> Some 16
                    // Handle unsupported format strings.
                    | _ -> None

            match bytes, baseNumber with
            | Some bytes, Some baseNumber ->
                // Return a formatted string.
                let mutable numericString = String.Empty
                for i = bytes.GetUpperBound 0 to bytes.GetLowerBound 0 do
                    let byteString = Convert.ToString(bytes[i], baseNumber)
                    let byteString =
                        match baseNumber with
                        | 2 ->
                            String('0', 8 - byteString.Length) + byteString
                        | 8 ->
                            String('0', 4 - byteString.Length) + byteString
                        // Base is 16.
                        | _ ->
                            String('0', 2 - byteString.Length) + byteString
                    numericString <- numericString + byteString + " "
                numericString.Trim()
            | _ ->
                try
                    this.HandleOtherFormats(format, arg)
                with :? FormatException as e ->
                    raise (FormatException($"The format of '{format}' is invalid.", e))
                    
    member private this.HandleOtherFormats(format, arg: obj) =
        match arg with
        | :? IFormattable as arg ->
            arg.ToString(format, CultureInfo.CurrentCulture)
        | null ->
            String.Empty
        | _ ->
            string arg
Imports System.Globalization
Imports System.Numerics

Public Class BinaryFormatter : Implements IFormatProvider, ICustomFormatter
   ' IFormatProvider.GetFormat implementation.
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      ' Determine whether custom formatting object is requested.
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      Else
         Return Nothing
      End If
   End Function   

   ' Format number in binary (B), octal (O), or hexadecimal (H).
   Public Function Format(fmt As String, arg As Object, _
                          formatProvider As IFormatProvider) As String _
                   Implements ICustomFormatter.Format

     ' Handle format string.
      Dim base As Integer
      ' Handle null or empty format string, string with precision specifier.
      Dim thisFmt As String = String.Empty
      ' Extract first character of format string (precision specifiers
      ' are not supported by BinaryFormatter).
      If Not String.IsNullOrEmpty(fmt) Then
         thisFmt = CStr(IIf(fmt.Length > 1, fmt.Substring(0, 1), fmt))
      End If
         


      ' Get a byte array representing the numeric value.
      Dim bytes() As Byte
      If TypeOf(arg) Is SByte Then
         Dim byteString As String = CType(arg, SByte).ToString("X2")
         bytes = New Byte(0) { Byte.Parse(byteString, System.Globalization.NumberStyles.HexNumber ) }
      ElseIf TypeOf(arg) Is Byte Then
         bytes = New Byte(0) { CType(arg, Byte) }
      ElseIf TypeOf(arg) Is Int16 Then
         bytes = BitConverter.GetBytes(CType(arg, Int16))
      ElseIf TypeOf(arg) Is Int32 Then
         bytes = BitConverter.GetBytes(CType(arg, Int32))
      ElseIf TypeOf(arg) Is Int64 Then
         bytes = BitConverter.GetBytes(CType(arg, Int64))
      ElseIf TypeOf(arg) Is UInt16 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt16))
      ElseIf TypeOf(arg) Is UInt32 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt64))
      ElseIf TypeOf(arg) Is UInt64 Then
         bytes = BitConverter.GetBytes(CType(arg, UInt64))                  
      ElseIf TypeOf(arg) Is BigInteger Then
         bytes = CType(arg, BigInteger).ToByteArray()
      Else
         Try 
            Return HandleOtherFormats(fmt, arg) 
         Catch e As FormatException 
            Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
         End Try
      End If

      Select Case thisFmt.ToUpper()
         ' Binary formatting.
         Case "B"
            base = 2        
         Case "O"
            base = 8
         Case "H"
            base = 16
         ' Handle unsupported format strings.
         Case Else
            Try 
               Return HandleOtherFormats(fmt, arg) 
            Catch e As FormatException 
               Throw New FormatException(String.Format("The format of '{0}' is invalid.", fmt), e)
            End Try
      End Select
      
      ' Return a formatted string.
      Dim numericString As String = String.Empty
      For ctr As Integer = bytes.GetUpperBound(0) To bytes.GetLowerBound(0) Step -1
         Dim byteString As String = Convert.ToString(bytes(ctr), base)
         If base = 2 Then
            byteString = New String("0"c, 8 - byteString.Length) + byteString
         ElseIf base = 8 Then
            byteString = New String("0"c, 4 - byteString.Length) + byteString
         ' Base is 16.
         Else     
            byteString = New String("0"c, 2 - byteString.Length) + byteString
         End If
         numericString +=  byteString + " "
      Next
      Return numericString.Trim()
   End Function
   
   Private Function HandleOtherFormats(fmt As String, arg As Object) As String
      If TypeOf arg Is IFormattable Then
         Return DirectCast(arg, IFormattable).ToString(fmt, CultureInfo.CurrentCulture)
      ElseIf arg IsNot Nothing Then
         Return arg.ToString()
      Else
         Return String.Empty
      End If
   End Function
End Class

BinaryFormatter然后,可以通过将对象作为provider方法的参数Format传递BinaryFormatter来提供自定义格式,如以下示例所示。

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

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

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

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

      BigInteger bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2);
      Console.WriteLine(String.Format(new BinaryFormatter(),
                                      "{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)
Console.WindowWidth <- 100

let byteValue = 124uy
String.Format(BinaryFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", byteValue)
|> printfn "%s"

let intValue = 23045
String.Format(BinaryFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", intValue)
|> printfn "%s"

let ulngValue = 31906574882uL
String.Format(BinaryFormatter(), "{0}\n   (binary: {0:B})\n   (hex: {0:H})", ulngValue)
|> printfn "%s"

let bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2)
String.Format(BinaryFormatter(), "{0}\n   (binary: {0:B})\n   (hex: {0:H})", bigIntValue)
|> printfn "%s"

// 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)
Public Module Example
   Public Sub Main
      Console.WindowWidth = 100
      
      Dim byteValue As Byte = 124
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} (binary: {0:B}) (hex: {0:H})", byteValue))
      
      Dim intValue As Integer = 23045
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} (binary: {0:B}) (hex: {0:H})", intValue))
      
      Dim ulngValue As ULong = 31906574882
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} {1}   (binary: {0:B}) {1}   (hex: {0:H})", _
                                      ulngValue, vbCrLf))

      Dim bigIntValue As BigInteger = BigInteger.Multiply(Int64.MaxValue, 2)
      Console.WriteLine(String.Format(New BinaryFormatter(), _
                                      "{0} {1}   (binary: {0:B}) {1}   (hex: {0:H})", _
                                      bigIntValue, vbCrLf))
   End Sub
End Module
' 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 包含单个方法 ICustomFormatter.Format。 当此接口由引用或值类型实现时,该方法 Format 将返回对象的值的自定义格式字符串表示形式。

通常,接口ICustomFormatter是通过接口实现IFormatProvider的,用于自定义包含IFormatProvider参数的两种.NET Framework复合字符串格式方法的行为。 具体而言,接口 ICustomFormatter 可以提供传递给 String.Format(IFormatProvider, String, Object[])StringBuilder.AppendFormat(IFormatProvider, String, Object[]) 方法的对象值的自定义格式。

提供对象的值的自定义表示形式需要执行以下操作:

  1. 定义实现接口及其单个成员的方法的FormatICustomFormatter

  2. 定义实现接口及其单个成员的方法的GetFormatIFormatProvider。 该方法 GetFormat 返回实现的 ICustomFormatter 实例。 通常,单个类实现这两个类 ICustomFormatterIFormatProvider。 在这种情况下,类的 GetFormat 实现只返回本身的实例。

  3. IFormatProvider 实现作为 provider 方法的参数 String.Format(IFormatProvider, String, Object[]) 或可比较的方法传递。

然后,.NET Framework方法将使用自定义格式而不是自己的格式设置。

实施者说明

公共语言运行时尝试对复合格式字符串中的每个格式项使用 ICustomFormatter 实现。 因此,应该会调用 ICustomFormatter 实现,以便为它不设计用于处理的对象或值提供格式设置服务。 在这些情况下,你的 Format(String, Object, IFormatProvider) 方法必须为该对象或值调用适当的格式设置方法。

有两种类型的 ICustomFormatter 实现:内部实现和扩展。

内部实现是为应用程序定义对象提供自定义格式的实现。 在这种情况下,实现应包括以下内容:

  • 定义用于定义对象格式的格式字符串的定义。 格式字符串是可选的。 通常,“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)

使用指定的格式和区域性特定格式信息将指定对象的值转换为它的等效字符串表示形式。

适用于

另请参阅