ICustomFormatter Interface
Definição
Importante
Algumas informações dizem respeito a um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.
Define um método que suporta formatação personalizada do valor de um objeto.
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- Atributos
Exemplos
O exemplo seguinte implementa ICustomFormatter a formatação binária, octal e hexadecimal de valores integrais. Neste exemplo, uma única classe, MyFormatter, implementa tanto ICustomFormatter como IFormatProvider. O seu IFormatProvider.GetFormat método determina se o formatType parâmetro representa um ICustomFormatter tipo. Se o fizer, MyFormatter devolve uma instância de si próprio; caso contrário, devolve null. A sua implementação determina se o parâmetro de formato é uma das três cadeias de formato suportadas ("B" para binário, "O" para octal e "H" para hexadecimal) e formata ICustomFormatter.Format o arg parâmetro de forma adequada. Caso contrário, se arg não nullfor , chama a arg implementação do IFormattable.ToString parâmetro, se existir, ou o seu método sem ToString parâmetros, se não existir. Se arg for null, o método devolve 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 pode então ser usado para fornecer formatação personalizada ao passar um MyFormatter objeto como provider parâmetro do Format método, como mostra o exemplo seguinte.
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)
Observações
A ICustomFormatter interface inclui um único método, ICustomFormatter.Format. Quando esta interface é implementada por um tipo de referência ou valor, o Format método devolve uma representação de strings formatada e personalizada do valor de um objeto.
Normalmente, a interface ICustomFormatter é implementada com a interface IFormatProvider para personalizar o comportamento de dois métodos de formatação de strings compostas .NET Framework que incluem um parâmetro IFormatProvider. Especificamente, a ICustomFormatter interface pode fornecer formatação personalizada do valor de um objeto passado para os String.Format(IFormatProvider, String, Object[]) métodos e.StringBuilder.AppendFormat(IFormatProvider, String, Object[])
Fornecer uma representação personalizada do valor de um objeto requer que faça o seguinte:
Defina uma classe que implemente a ICustomFormatter interface e o seu único elemento, o Format método.
Defina uma classe que implemente a IFormatProvider interface e o seu único elemento, o GetFormat método. O GetFormat método devolve uma instância da sua ICustomFormatter implementação. Frequentemente, uma única classe implementa tanto ICustomFormatter como IFormatProvider. Nesse caso, a implementação da
GetFormatclasse apenas devolve uma instância de si própria.Passe a IFormatProvider implementação como argumento
providerdo String.Format(IFormatProvider, String, Object[]) método ou de um método comparável.
O método da biblioteca .NET usará então a sua formatação personalizada em vez da sua própria.
Notas para Implementadores
O runtime da linguagem comum tenta usar a sua ICustomFormatter implementação para cada item de formato numa cadeia de formatos composta. Como resultado, deve esperar que a sua ICustomFormatter implementação seja chamada para fornecer serviços de formatação a objetos ou valores para os quais não foi concebida. Nestes casos, o seu Format(String, Object, IFormatProvider) método deve chamar o método de formatação apropriado para esse objeto ou valor.
Existem dois tipos de ICustomFormatter implementações: intrínsecas e de extensão.
Implementações intrínsecas são implementações que fornecem formatação personalizada para um objeto definido pela aplicação. Neste caso, a sua implementação deve incluir o seguinte:
Uma definição de cadeias de formato que definem a formatação do objeto. As strings de formato são opcionais. Normalmente, uma cadeia de formato "G" ou "g" define o formato geral (ou mais comum). No entanto, é livre de definir quaisquer strings de formato que escolher. Também é livre de decidir se são sensíveis a maiúsculas ou minúsculas.
Um teste para garantir que o tipo do objeto passado para o seu Format(String, Object, IFormatProvider) método é o tipo definido pela aplicação. Se não estiver, deve chamar a implementação do IFormattable objeto, se existir, ou o seu ToString() método, caso não exista. Deve estar preparado para lidar com quaisquer exceções que estas chamadas de método possam lançar.
Código para lidar com uma cadeia de formato nulo, se a sua implementação suportar cadeias de formato. A abordagem mais comum é substituir uma cadeia de formato nulo pelo especificador geral de formato.
Código para lidar com quaisquer strings de formato que a tua implementação suporte.
Código para lidar com strings de formato que não suportas. A abordagem mais comum é lançar um FormatException, embora possa fornecer a formatação padrão.
Implementações de extensões são implementações que fornecem formatação personalizada para um tipo que já tem suporte de formatação. Por exemplo, pode definir um CustomerNumberFormatter que formate um tipo integral com hífens entre dígitos específicos. Neste caso, a sua implementação deve incluir o seguinte:
Uma definição de strings de formato que estende a formatação do objeto. Estas strings de formato são obrigatórias, mas não devem entrar em conflito com as strings de formato existentes do tipo. Por exemplo, se estiver a estender a formatação para o Int32 tipo, não deve implementar os especificadores de formato "C", "D", "E", "F" e "G", entre outros.
Um teste de que o tipo do objeto passado ao teu Format(String, Object, IFormatProvider) método é um tipo cuja formatação a tua extensão suporta. Se não for, chama-se a implementação do IFormattable objeto, se existir, ou o método sem ToString() parâmetros do objeto, caso não exista. Deve estar preparado para lidar com quaisquer exceções que estas chamadas de método possam lançar.
Código para lidar com quaisquer strings de formato que a sua extensão suporte.
Código para lidar com quaisquer strings de formato que a sua extensão não suporte. Estes devem ser transmitidos à implementação do IFormattable tipo. Deve estar preparado para lidar com quaisquer exceções que estas chamadas de método possam lançar.
Métodos
| Name | Description |
|---|---|
| Format(String, Object, IFormatProvider) |
Converte o valor de um objeto especificado para uma representação de cadeia equivalente usando formato especificado e informação de formatação específica para cultura. |