ICustomFormatter Интерфейс
Определение
Важно!
Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
Определяет метод, поддерживающий пользовательское форматирование значения объекта.
public interface class ICustomFormatterpublic interface ICustomFormatter[System.Runtime.InteropServices.ComVisible(true)]
public interface ICustomFormattertype ICustomFormatter = interface[<System.Runtime.InteropServices.ComVisible(true)>]
type ICustomFormatter = interfacePublic Interface ICustomFormatter- Атрибуты
Примеры
В следующем примере реализуется ICustomFormatter , чтобы разрешить двоичное, восьмеричное и шестнадцатеричное форматирование целочисленных значений. В этом примере один класс реализует MyFormatterи ICustomFormatterIFormatProvider. Его IFormatProvider.GetFormat метод определяет, представляет ICustomFormatter ли formatType параметр тип. Если это так, MyFormatter возвращается экземпляр самого себя; в противном случае возвращается null. Его ICustomFormatter.Format реализация определяет, является ли параметр format одной из трех поддерживаемых строк формата ("B" для двоичного файла, "O" для восьмеричного и "H" для шестнадцатеричного) и форматирует arg параметр соответствующим образом. В противном случае, если arg значение не nullравно , вызывается arg реализация параметра IFormattable.ToString , если он существует, или его метод без ToString параметров, если он не используется. Если значением параметра arg является null, метод возвращает String.Empty.
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;
}
}
open System
open System.Globalization
open System.Numerics
type MyFormatter() =
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 MyFormatter : 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 MyFormatter).
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
MyFormatterЗатем можно использовать для предоставления настраиваемого форматирования путем передачи MyFormatterFormat объекта в provider качестве параметра метода, как показано в следующем примере.
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)
Console.WindowWidth <- 100
let byteValue = 124uy
String.Format(MyFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", byteValue)
|> printfn "%s"
let intValue = 23045
String.Format(MyFormatter(), "{0} (binary: {0:B}) (hex: {0:H})", intValue)
|> printfn "%s"
let ulngValue = 31906574882uL
String.Format(MyFormatter(), "{0}\n (binary: {0:B})\n (hex: {0:H})", ulngValue)
|> printfn "%s"
let bigIntValue = BigInteger.Multiply(Int64.MaxValue, 2)
String.Format(MyFormatter(), "{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 MyFormatter(), _
"{0} (binary: {0:B}) (hex: {0:H})", byteValue))
Dim intValue As Integer = 23045
Console.WriteLine(String.Format(New MyFormatter(), _
"{0} (binary: {0:B}) (hex: {0:H})", intValue))
Dim ulngValue As ULong = 31906574882
Console.WriteLine(String.Format(New MyFormatter(), _
"{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 MyFormatter(), _
"{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 помощью интерфейса для настройки поведения двух платформа .NET Framework методов форматирования составных строк, включающих IFormatProvider параметр. В частности, интерфейс может предоставлять настраиваемое форматирование значения объекта, ICustomFormatter передаваемого String.Format(IFormatProvider, String, Object[]) в методы и StringBuilder.AppendFormat(IFormatProvider, String, Object[]) .
Чтобы предоставить пользовательское представление значения объекта, необходимо выполнить следующие действия:
Определите класс, реализующий ICustomFormatter интерфейс и его единственный член — Format метод .
Определите класс, реализующий IFormatProvider интерфейс и его единственный член — GetFormat метод . Метод GetFormat возвращает экземпляр реализации ICustomFormatter . Часто один класс реализует и ICustomFormatterIFormatProvider. В этом случае реализация класса
GetFormatпросто возвращает экземпляр самого себя.Передайте реализацию IFormatProvider в
providerкачестве аргумента String.Format(IFormatProvider, String, Object[]) метода или сопоставимого метода.
Затем метод библиотеки .NET будет использовать пользовательское форматирование вместо собственного.
Примечания для тех, кто реализует этот метод
Среда CLR пытается использовать реализацию 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) |
Преобразует значение указанного объекта в эквивалентное ему строковое представление с использованием указанного формата и сведений об особенностях форматирования для данного языка и региональных параметров. |
