Most visited

Recently visited

Results for

Added in API level 1
Summary: Protected Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

CharsetEncoder

public abstract class CharsetEncoder
extends Object

java.lang.Object
   ↳ java.nio.charset.CharsetEncoder

一个引擎，可以将16位Unicode字符序列转换为特定字符集中的字节序列。

The input character sequence is provided in a character buffer or a series of such buffers. The output byte sequence is written to a byte buffer or a series of such buffers. An encoder should always be used by making the following sequence of method invocations, hereinafter referred to as an encoding operation:

  1. 通过 reset方法重置编码器，除非它之前没有使用;

  2. 只要额外的输入可用，调用 encode方法零次或多次，为 endOfInput参数传递 101617021285701并填充输入缓冲区并在调用之间清空输出缓冲区;

  3. 最后一次调用encode方法，通过endOfInput传递endOfInput参数; 接着

  4. 调用 flush方法，以便编码器可以将任何内部状态清除到输出缓冲区。

Each invocation of the encode method will encode as many characters as possible from the input buffer, writing the resulting bytes to the output buffer. The encode method returns when more input is required, when there is not enough room in the output buffer, or when an encoding error has occurred. In each case a CoderResult object is returned to describe the reason for termination. An invoker can examine this object and fill the input buffer, flush the output buffer, or attempt to recover from an encoding error, as appropriate, and try again.

There are two general types of encoding errors. If the input character sequence is not a legal sixteen-bit Unicode sequence then the input is considered malformed. If the input character sequence is legal but cannot be mapped to a valid byte sequence in the given charset then an unmappable character has been encountered.

How an encoding error is handled depends upon the action requested for that type of error, which is described by an instance of the CodingErrorAction班。 的可能的错误操作是 ignore错误输入， report经由返回错误给调用CoderResult对象，或 replace与替换字节数组的电流值的错误输入。 该替换最初设置为编码器的默认替换，其经常（但不总是）具有初始值{ (byte)'?' } ; 其值可能会通过replaceWith方法更改。

对于错误输入和不可映射字符错误的默认操作是 report 。 格式错误的输入错误操作可能通过onMalformedInput方法更改; 可以通过onUnmappableCharacter方法更改不可映射字符动作。

该类旨在处理编码过程的许多细节，包括错误操作的实现。 一个特定字符集的编码器，它是这个类的具体子类，只需要实现抽象的encodeLoop方法，它封装了基本的编码循环。 另外，保持内部状态的子类应该覆盖implFlush和implReset方法。

这个类的实例对于多个并发线程不安全。

也可以看看：

Summary

Protected constructors
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)

初始化一个新的编码器。
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)

初始化一个新的编码器。

Public methods
final float averageBytesPerChar()

返回将为每个输入字符生成的平均字节数。
boolean canEncode(char c)

告诉这个编码器是否可以编码给定的字符。
boolean canEncode(CharSequence cs)

告诉该编码器是否可以编码给定的字符序列。
final Charset charset()

返回创建此编码器的字符集。
final ByteBuffer encode(CharBuffer in)

将单个输入字符缓冲区的剩余内容编码为新分配的字节缓冲区的便捷方法。
final CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)

从给定的输入缓冲区编码尽可能多的字符，将结果写入给定的输出缓冲区。
final CoderResult flush(ByteBuffer out)

刷新该编码器。
boolean isLegalReplacement(byte[] repl)

告诉给定的字节数组是否是该编码器的合法替换值。
CodingErrorAction malformedInputAction()

返回此编码器针对错误输入错误的当前操作。
final float maxBytesPerChar()

返回将为每个输入字符生成的最大字节数。
final CharsetEncoder onMalformedInput(CodingErrorAction newAction)

更改此编码器对错误输入错误的操作。
final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

更改此编码器对不可映射字符错误的操作。
final CharsetEncoder replaceWith(byte[] newReplacement)

更改此编码器的替换值。
final byte[] replacement()

返回此编码器的替换值。
final CharsetEncoder reset()

重置此编码器，清除任何内部状态。
CodingErrorAction unmappableCharacterAction()

返回此编码器对无法映射字符错误的当前操作。

Protected methods
abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)

将一个或多个字符编码为一个或多个字节。
CoderResult implFlush(ByteBuffer out)

刷新该编码器。
void implOnMalformedInput(CodingErrorAction newAction)

报告对此编码器的格式错误输入操作的更改。
void implOnUnmappableCharacter(CodingErrorAction newAction)

报告对此编码器的无法映射字符操作的更改。
void implReplaceWith(byte[] newReplacement)

报告此编码器重置值的更改。
void implReset()

重置此编码器，清除任何字符集特定的内部状态。

Inherited methods
From class java.lang.Object

Protected constructors

CharsetEncoder

Added in API level 1 
CharsetEncoder (Charset cs, 
                float averageBytesPerChar, 
                float maxBytesPerChar, 
                byte[] replacement)

初始化一个新的编码器。 新的编码器将具有给定的每字节字节和替换值。

Parameters
cs Charset
averageBytesPerChar float: A positive float value indicating the expected number of bytes that will be produced for each input character
maxBytesPerChar float: A positive float value indicating the maximum number of bytes that will be produced for each input character
replacement byte: The initial replacement; must not be null, must have non-zero length, must not be longer than maxBytesPerChar, and must be legal
Throws
IllegalArgumentException If the preconditions on the parameters do not hold

CharsetEncoder

Added in API level 1 
CharsetEncoder (Charset cs, 
                float averageBytesPerChar, 
                float maxBytesPerChar)

初始化一个新的编码器。 新的编码器将具有给定的每字节字节数，其替换将是字节数组{ (byte)'?' } 。

Parameters
cs Charset
averageBytesPerChar float: A positive float value indicating the expected number of bytes that will be produced for each input character
maxBytesPerChar float: A positive float value indicating the maximum number of bytes that will be produced for each input character
Throws
IllegalArgumentException If the preconditions on the parameters do not hold

Public methods

averageBytesPerChar

Added in API level 1 
float averageBytesPerChar ()

返回将为每个输入字符生成的平均字节数。 该启发式值可以用于估计给定输入序列所需的输出缓冲器的大小。

Returns
float The average number of bytes produced per character of input

canEncode

Added in API level 1 
boolean canEncode (char c)

告诉这个编码器是否可以编码给定的字符。

如果给定字符是替代字符，则此方法返回false ; 这样的人物只有在他们是由高代理人跟随低代理人组成的一对成员时才能被解释。 可以使用canEncode(CharSequence)方法来测试字符序列是否可以被编码。

该方法可以修改该编码器的状态; 因此如果encoding operation已经在进行中，它不应该被调用。

此方法的默认实现不是非常有效; 通常应该改写为提高性能。

Parameters
c char
Returns
boolean true if, and only if, this encoder can encode the given character
Throws
IllegalStateException If an encoding operation is already in progress

canEncode

Added in API level 1 
boolean canEncode (CharSequence cs)

告诉该编码器是否可以编码给定的字符序列。

如果此方法为特定字符序列返回 false ，则可以通过执行完整的 encoding operation来获得有关为什么无法编码序列的更多信息。

该方法可以修改该编码器的状态; 因此如果编码操作已在进行中，则不应调用它。

此方法的默认实现不是非常有效; 通常应该改写为提高性能。

Parameters
cs CharSequence
Returns
boolean true if, and only if, this encoder can encode the given character without throwing any exceptions and without performing any replacements
Throws
IllegalStateException If an encoding operation is already in progress

charset

Added in API level 1 
Charset charset ()

返回创建此编码器的字符集。

Returns
Charset This encoder's charset

encode

Added in API level 1 
ByteBuffer encode (CharBuffer in)

将单个输入字符缓冲区的剩余内容编码为新分配的字节缓冲区的便捷方法。

This method implements an entire encoding operation; that is, it resets this encoder, then it encodes the characters in the given character buffer, and finally it flushes this encoder. This method should therefore not be invoked if an encoding operation is already in progress.

Parameters
in CharBuffer: The input character buffer
Returns
ByteBuffer A newly-allocated byte buffer containing the result of the encoding operation. The buffer's position will be zero and its limit will follow the last byte written.
Throws
IllegalStateException If an encoding operation is already in progress
MalformedInputException If the character sequence starting at the input buffer's current position is not a legal sixteen-bit Unicode sequence and the current malformed-input action is REPORT
UnmappableCharacterException If the character sequence starting at the input buffer's current position cannot be mapped to an equivalent byte sequence and the current unmappable-character action is REPORT
CharacterCodingException

encode

Added in API level 1 
CoderResult encode (CharBuffer in, 
                ByteBuffer out, 
                boolean endOfInput)

从给定的输入缓冲区编码尽可能多的字符，将结果写入给定的输出缓冲区。

从当前位置开始读取和写入缓冲区。 最多可以读取in.remaining()字符，最多可以写入out.remaining()个字节。 缓冲区的位置将被提前以反映读取的字符和写入的字节，但其标记和限制不会被修改。

除了从输入缓冲区读取字符并将字节写入输出缓冲区外，此方法还会返回一个 CoderResult对象来描述其终止的原因：

  • UNDERFLOW表示尽可能多的输入缓冲区已被编码。 如果没有进一步的输入，则调用者可以继续进行encoding operation的下一步 。 否则，应该再次调用该方法并进一步输入。

  • OVERFLOW表示输出缓冲区中没有足够的空间来编码更多字符。 应该再次使用具有更多remaining字节的输出缓冲区调用此方法。 这通常是通过从输出缓冲区中排除任何编码字节来完成的。

  • malformed-input结果表示检测到格式错误的输入错误。 格式错误的字符从输入缓冲区（可能增加）的位置开始; 通过调用结果对象的方法length可以确定格式不正确的字符的数量。 这种情况只适用于该编码器的 malformed action为REPORT ; 否则根据要求，格式错误的输入将被忽略或替换。

  • unmappable-character结果表示已检测到无法映射的字符错误。 编码不可映射字符的字符从输入缓冲区（可能增加）开始; 这样的字符的数目可以通过调用结果对象的确定length方法。 这种情况只适用于该编码器的 unmappable action为REPORT ; 否则根据要求，不可映射的字符将被忽略或替换。

In any case, if this method is to be reinvoked in the same encoding operation then care should be taken to preserve any characters remaining in the input buffer so that they are available to the next invocation.

endOfInput参数建议此方法，以确定调用程序是否可以提供超出给定输入缓冲区中所包含输入的输入。 如果有可能提供额外的输入，那么调用者应该通过false这个参数; 如果没有提供进一步输入的可能性，则调用者应该通过true 。 这并不是错误的，实际上很常见的情况是，在一次调用中传递false ，然后发现没有其他输入实际可用。 但是，最重要的是，在调用序列中最后调用此方法总是通过true，以便任何剩余的未编码输入将被视为格式错误。

此方法通过调用 encodeLoop方法，解释其结果，处理错误条件以及根据需要重新调用它来起作用。

Parameters
in CharBuffer: The input character buffer
out ByteBuffer: The output byte buffer
endOfInput boolean: true if, and only if, the invoker can provide no additional input characters beyond those in the given buffer
Returns
CoderResult A coder-result object describing the reason for termination
Throws
IllegalStateException If an encoding operation is already in progress and the previous step was an invocation neither of the reset method, nor of this method with a value of false for the endOfInput parameter, nor of this method with a value of true for the endOfInput parameter but a return value indicating an incomplete encoding operation
CoderMalfunctionError If an invocation of the encodeLoop method threw an unexpected exception

flush

Added in API level 1 
CoderResult flush (ByteBuffer out)

刷新该编码器。

一些编码器保持内部状态，并且一旦读取了整个输入序列，可能需要将一些最终字节写入输出缓冲器。

任何额外的输出都会从当前位置开始写入输出缓冲区。 最多将写入out.remaining()个字节。 缓冲区的位置将被适当地推进，但其标记和限制不会被修改。

如果此方法成功完成，则返回UNDERFLOW 。 如果输出缓冲区的空间不足，则返回OVERFLOW 。 如果发生这种情况，则必须再次调用此方法，并使用输出缓冲区具有更多空间，以完成当前的encoding operation 。

如果此编码器已被刷新，则调用此方法不起作用。

该方法调用 implFlush方法来执行实际的冲洗操作。

Parameters
out ByteBuffer: The output byte buffer
Returns
CoderResult A coder-result object, either UNDERFLOW or OVERFLOW
Throws
IllegalStateException If the previous step of the current encoding operation was an invocation neither of the flush method nor of the three-argument encode method with a value of true for the endOfInput parameter

isLegalReplacement

Added in API level 1 
boolean isLegalReplacement (byte[] repl)

告诉给定的字节数组是否是该编码器的合法替换值。

当且仅当在编码器的字符集中是合法的字节序列时，替换才是合法的; 也就是说，必须能够将替换解码为一个或多个16位Unicode字符。

The default implementation of this method is not very efficient; it should generally be overridden to improve performance.

Parameters
repl byte: The byte array to be tested
Returns
boolean true if, and only if, the given byte array is a legal replacement value for this encoder

malformedInputAction

Added in API level 1 
CodingErrorAction malformedInputAction ()

返回此编码器针对错误输入错误的当前操作。

Returns
CodingErrorAction The current malformed-input action, which is never null

maxBytesPerChar

Added in API level 1 
float maxBytesPerChar ()

返回将为每个输入字符生成的最大字节数。 此值可用于计算给定输入序列所需的输出缓冲区的最差情况大小。

Returns
float The maximum number of bytes that will be produced per character of input

onMalformedInput

Added in API level 1 
CharsetEncoder onMalformedInput (CodingErrorAction newAction)

更改此编码器对错误输入错误的操作。

此方法调用 implOnMalformedInput方法，传递新的操作。

Parameters
newAction CodingErrorAction: The new action; must not be null
Returns
CharsetEncoder This encoder
Throws
IllegalArgumentException If the precondition on the parameter does not hold

onUnmappableCharacter

Added in API level 1 
CharsetEncoder onUnmappableCharacter (CodingErrorAction newAction)

更改此编码器对不可映射字符错误的操作。

此方法调用 implOnUnmappableCharacter方法，传递新操作。

Parameters
newAction CodingErrorAction: The new action; must not be null
Returns
CharsetEncoder This encoder
Throws
IllegalArgumentException If the precondition on the parameter does not hold

replaceWith

Added in API level 1 
CharsetEncoder replaceWith (byte[] newReplacement)

更改此编码器的替换值。

This method invokes the implReplaceWith method, passing the new replacement, after checking that the new replacement is acceptable.

Parameters
newReplacement byte: The new replacement; must not be null, must have non-zero length, must not be longer than the value returned by the maxBytesPerChar method, and must be legal
Returns
CharsetEncoder This encoder
Throws
IllegalArgumentException If the preconditions on the parameter do not hold

replacement

Added in API level 1 
byte[] replacement ()

返回此编码器的替换值。

Returns
byte[] This encoder's current replacement, which is never null and is never empty

reset

Added in API level 1 
CharsetEncoder reset ()

重置此编码器，清除任何内部状态。

This method resets charset-independent state and also invokes the implReset method in order to perform any charset-specific reset actions.

Returns
CharsetEncoder This encoder

unmappableCharacterAction

Added in API level 1 
CodingErrorAction unmappableCharacterAction ()

返回此编码器对无法映射字符错误的当前操作。

Returns
CodingErrorAction The current unmappable-character action, which is never null

Protected methods

encodeLoop

Added in API level 1 
CoderResult encodeLoop (CharBuffer in, 
                ByteBuffer out)

将一个或多个字符编码为一个或多个字节。

这个方法封装了基本的编码循环，编码尽可能多的字符，直到它的输入用完，输出缓冲区的空间不足，或遇到编码错误。 该方法由encode方法调用，该方法处理结果解释和错误恢复。

从当前位置开始读取和写入缓冲区。 最多可读取in.remaining()字符，最多可写入out.remaining()个字节。 缓冲区的位置将被提前以反映读取的字符和写入的字节，但其标记和限制不会被修改。

此方法返回一个CoderResult对象来描述其终止的原因，方法与encode方法相同。 此方法的大多数实现将通过返回适当的结果对象以解决encode方法的处理来处理编码错误。 优化的实现可能会检查相关的错误操作并实施该操作本身。

该方法的实现可以通过返回 UNDERFLOW来执行任意前瞻，直到它接收到足够的输入。

Parameters
in CharBuffer: The input character buffer
out ByteBuffer: The output byte buffer
Returns
CoderResult A coder-result object describing the reason for termination

implFlush

Added in API level 1 
CoderResult implFlush (ByteBuffer out)

刷新该编码器。

此方法的默认实现不执行任何操作，并始终返回UNDERFLOW 。 应该由编码器覆盖该方法，一旦整个输入序列被读取，该编码器可能需要将最终字节写入输出缓冲器。

Parameters
out ByteBuffer: The output byte buffer
Returns
CoderResult A coder-result object, either UNDERFLOW or OVERFLOW

implOnMalformedInput

Added in API level 1 
void implOnMalformedInput (CodingErrorAction newAction)

报告对此编码器的格式错误输入操作的更改。

The default implementation of this method does nothing. This method should be overridden by encoders that require notification of changes to the malformed-input action.

Parameters
newAction CodingErrorAction

implOnUnmappableCharacter

Added in API level 1 
void implOnUnmappableCharacter (CodingErrorAction newAction)

报告对此编码器的无法映射字符操作的更改。

此方法的默认实现不做任何事情。 该方法应该由需要通知对无法映射字符操作进行更改的编码器覆盖。

Parameters
newAction CodingErrorAction

implReplaceWith

Added in API level 1 
void implReplaceWith (byte[] newReplacement)

报告此编码器重置值的更改。

此方法的默认实现不做任何事情。 该方法应该由需要通知更换的更改的编码器覆盖。

implReset

Added in API level 1 
void implReset ()

重置此编码器，清除任何字符集特定的内部状态。

此方法的默认实现不做任何事情。 该方法应该由维持内部状态的编码器覆盖。

Android开发手册

Hooray!