encode

Encodes as many characters as possible from the given input buffer, writing the results to the given output buffer.

The buffers are read from, and written to, starting at their current positions. At most Buffer.remaining characters will be read and at most Buffer.remaining bytes will be written. The buffers' positions will be advanced to reflect the characters read and the bytes written, but their marks and limits will not be modified.

In addition to reading characters from the input buffer and writing bytes to the output buffer, this method returns a CoderResult object to describe its reason for termination:

CoderResult.UNDERFLOW indicates that as much of the input buffer as possible has been encoded. If there is no further input then the invoker can proceed to the next step of the #steps. Otherwise this method should be invoked again with further input.

CoderResult.OVERFLOW indicates that there is insufficient space in the output buffer to encode any more characters. This method should be invoked again with an output buffer that has more Buffer.remaining bytes. This is typically done by draining any encoded bytes from the output buffer.

A malformed-input result indicates that a malformed-input error has been detected. The malformed characters begin at the input buffer's (possibly incremented) position; the number of malformed characters may be determined by invoking the result object's method. This case applies only if the .onMalformedInput of this encoder is CodingErrorAction.REPORT; otherwise the malformed input will be ignored or replaced, as requested.

An unmappable-character result indicates that an unmappable-character error has been detected. The characters that encode the unmappable character begin at the input buffer's (possibly incremented) position; the number of such characters may be determined by invoking the result object's length method. This case applies only if the .onUnmappableCharacter of this encoder is ; otherwise the unmappable character will be ignored or replaced, as requested.

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.

The endOfInput parameter advises this method as to whether the invoker can provide further input beyond that contained in the given input buffer. If there is a possibility of providing additional input then the invoker should pass false for this parameter; if there is no possibility of providing further input then the invoker should pass true. It is not erroneous, and in fact it is quite common, to pass false in one invocation and later discover that no further input was actually available. It is critical, however, that the final invocation of this method in a sequence of invocations always pass true so that any remaining unencoded input will be treated as being malformed.

This method works by invoking the .encodeLoop method, interpreting its results, handling error conditions, and reinvoking it as necessary.

Parameters

Throws

Convenience method that encodes the remaining content of a single input character buffer into a newly-allocated byte buffer.

This method implements an entire #steps; 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

Throws