Source Code

This module allows you to convert between text and binary forms of data.

For efficiency of I/O (see the ceylon.io module), Buffers are the core representation which Codecs output from the encode/decode operations, but it's still easy to get more general types like Arrays and Strings. Input to the operations can be any stream type.

Codecs are symmetrical, as any data that is encoded then decoded (or vice versa) with the same codec will be at least semantically equivalent to the starting data, and usually exactly equal.

Codecs come in four flavours: ByteToByte, ByteToCharacter, CharacterToByte, and CharacterToCharacter. The middle two are similar, yet kept seperate to support differing conventions around what encode and decode mean in particular codec families. To enhance efficiency, ByteToByteCodecs are offered as variants of some CharacterToByteCodecs where the Character form is comprised of ASCII characters only. These variants' output is the same as using the original plus encoding the characters with the ASCII charset.

There are three currently implemented codec families: charsets (UTF-8 for example), base encodings (like base64), and text ciphers (rot13 for example). See those packages for further documentation and examples of use.

By: Stéphane Épardaud, Alex Szczuczko
Packages
ceylon.buffer

See ceylon.buffer

ceylon.buffer.base

This package contains the “base” codecs defined by RFC 4648.

ceylon.buffer.charset

This package contains the Charset codec family.

ceylon.buffer.codec

This package contains the infrastructure of the Codec system.

ceylon.buffer.readers
ceylon.buffer.text

This package contains implementations of CharacterToCharacterCodecs

Dependencies
ceylon.collection1.3.2
ceylon.interop.java (jvm)1.3.2
java.base (jvm)7
See also ceylon.buffer
Classes
BufferSource Codeshared abstract Buffer<Element>

Represents a memory buffer that can be read and written to with no allocation. The easiest way to get an idea of what a buffer is, is that it consists in an array of a given Buffer.capacity, a Buffer.position index within the array, and a Buffer.limit index.

Typical operations on a buffer will be to fill it, which you do with Buffer.put() until you reach the Buffer.limit.

Then if you want to read the data you just put in the buffer, you Buffer.flip() the buffer, which will set its Buffer.limit to the current Buffer.position, and reset its Buffer.position to 0. This essentially means that you will be able to read from the beginning of the buffer until the last object you Buffer.put() in it when writing.

You can then start calling Buffer.get() to read objects from this buffer until you reach its Buffer.limit.

Once you are done reading from the buffer, you can Buffer.clear() the buffer to start writing to it again. That will reset the Buffer.position to 0 and the Buffer.limit to the Buffer.capacity, allowing you to write to the full underlying array.

Buffers can be resized (grown and expanded), which will cause an underlying array reallocation and copy.

ByteBufferSource Codeshared ByteBuffer

Represents a buffer of Bytes (from 0 to 255 inclusive, unsigned).

CharacterBufferSource Codeshared CharacterBuffer

Represents a buffer of Characters.

Exceptions
BufferExceptionSource Codeshared BufferException
BufferOverflowExceptionSource Codeshared BufferOverflowException
BufferUnderflowExceptionSource Codeshared BufferUnderflowException