path: root/fpcdocs/ascii85.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<package name="fcl">

<!--
  ====================================================================
    ascii85
  ====================================================================
-->

<module name="ascii85">
<short>ASCII 85 or Base 85 encoding</short>
<descr>
<p>
The <file>ascii85</file> provides an ASCII 85 or base 85 decoding algorithm.
It is class and stream based: the <link id="TASCII85DecoderStream"/> stream
can be used to decode any stream with ASCII85 encoded data.
</p>
<p>
Currently, no ASCII85 encoder stream is available.
</p>
<p>
It's usage and purpose is similar to the <link id="#fcl.idea">IDEA</link> or
<link id="#fcl.base64">base64</link> units.
</p>
</descr>

<!-- enumeration type Visibility: default
     Declaration: TASCII85State = (ascInitial,ascOneEncodedChar,ascTwoEncodedChars,
                 ascThreeEncodedChars,ascFourEncodedChars,
                 ascNoEncodedChar,ascPrefix) -->
<element name="TASCII85State">
<short>Encoder state enumeration</short>
<descr>
<var>TASCII85State</var> is for internal use, it contains the current state of the
decoder.
</descr>
<seealso>
<link id="TASCII85DecoderStream"/>
</seealso>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascInitial -->
<element name="TASCII85State.ascInitial">
<short>Initial state</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascOneEncodedChar -->
<element name="TASCII85State.ascOneEncodedChar">
<short>One encoded character in buffer.</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascTwoEncodedChars -->
<element name="TASCII85State.ascTwoEncodedChars">
<short>Two encoded characters in buffer.</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascThreeEncodedChars -->
<element name="TASCII85State.ascThreeEncodedChars">
<short>Three encoded characters in buffer.</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascFourEncodedChars -->
<element name="TASCII85State.ascFourEncodedChars">
<short>Four encoded characters in buffer.</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascNoEncodedChar -->
<element name="TASCII85State.ascNoEncodedChar">
<short>No encoded characters in buffer.</short>
</element>

<!-- enumeration value Visibility: default
     Declaration: ascPrefix -->
<element name="TASCII85State.ascPrefix">
<short>Prefix processing</short>
</element>

<!--
  ********************************************************************
    #fcl.ascii85.TASCII85RingBuffer
  ********************************************************************
-->

<!-- class Visibility: default -->
<element name="TASCII85RingBuffer">
<short>Internal buffer class</short>
<descr>
<var>TASCII85RingBuffer</var> is an internal buffer class: it maintains a
memory buffer of 1Kb, for faster reading of the stream. It should not be
necessary to instantiate an instance of this class, the <link
id="TASCII85DecoderStream"/> decoder stream will create an instance of this
class automatically.
</descr>
<seealso>
<link id="TASCII85DecoderStream"/>
</seealso>
</element>

<!-- property Visibility: published
     Declaration: FillCount : Cardinal -->
<element name="TASCII85RingBuffer.FillCount">
<short>Number of bytes in buffer</short>
<descr>
<var>FillCount</var> is the available amount of bytes in the buffer.
</descr>
<seealso>
<link id="TASCII85RingBuffer.Write"/>
<link id="TASCII85RingBuffer.Read"/>
<link id="TASCII85RingBuffer.Size"/>
</seealso>
</element>

<!-- property Visibility: published
     Declaration: Size : Cardinal -->
<element name="TASCII85RingBuffer.Size">
<short>Size of buffer</short>
<descr>
<var>Size</var> is the total size of the memory buffer. This is currently
hardcoded to 1024Kb.
</descr>
<seealso>
<link id="TASCII85RingBuffer.FillCount"/>
</seealso>
</element>

<!-- procedure Visibility: published
     Declaration: procedure Write(const aBuffer;aSize: Cardinal) -->
<element name="TASCII85RingBuffer.Write">
<short>Write data to the internal buffer</short>
<descr>
<var>Write</var> writes <var>aSize</var> bytes from <var>aBuffer</var> to
the internal memory buffer. Only as much bytes are written as will fit in
the buffer.
</descr>
<seealso>
<link id="TASCII85RingBuffer.FillCount"/>
<link id="TASCII85RingBuffer.Read"/>
<link id="TASCII85RingBuffer.Size"/>
</seealso>
</element>

<!-- argument Visibility: default
     Declaration: aBuffer -->
<element name="TASCII85RingBuffer.Write.aBuffer">
<short>Buffer to get data from</short>
</element>

<!-- argument Visibility: default
     Declaration: aSize: Cardinal -->
<element name="TASCII85RingBuffer.Write.aSize">
<short>Total amount of bytes to read from <var>aBuffer</var></short>
</element>

<!-- function Visibility: published
     Declaration: function Read(var aBuffer;aSize: Cardinal) : Cardinal -->
<element name="TASCII85RingBuffer.Read">
<short>Read data from the internal buffer</short>
<descr>
<var>Read</var> will read <var>aSize</var> bytes from the internal buffer
and writes them to <var>aBuffer</var>. If not enough bytes are available,
only as much bytes as available will be written. The function returns the
number of bytes transferred.
</descr>
<seealso>
<link id="TASCII85RingBuffer.FillCount"/>
<link id="TASCII85RingBuffer.Write"/>
<link id="TASCII85RingBuffer.Size"/>
</seealso>
</element>

<!-- function result Visibility: default
     Declaration: Result -->
<element name="TASCII85RingBuffer.Read.Result">
<short>Number of actually transferred bytes</short>
</element>

<!-- argument Visibility: default
     Declaration: aBuffer -->
<element name="TASCII85RingBuffer.Read.aBuffer">
<short>Buffer to write data to</short>
</element>

<!-- argument Visibility: default
     Declaration: aSize: Cardinal -->
<element name="TASCII85RingBuffer.Read.aSize">
<short>Number of bytes to transfer</short>
</element>

<!--
  ********************************************************************
    #fcl.ascii85.TASCII85DecoderStream
  ********************************************************************
-->

<!-- class Visibility: default -->
<element name="TASCII85DecoderStream">
<short>ASCII 85 decoder stream.</short>
<descr>
<p>
<var>TASCII85DecoderStream</var> is a read-only stream: it takes an input
stream with ASCII 85 encoded data, and decodes the data as it is read. To
this end, it overrides the <link id="#rtl.classes.tstream.read">TSTream.Read</link> method.
</p>
<p>
The stream cannot be written to, trying to write to the stream will result
in an exception.
</p>
</descr>
</element>

<!-- constructor Visibility: published
     Declaration: constructor Create(aStream: TStream) -->
<element name="TASCII85DecoderStream.Create">
<short>Create new ASCII 85 decoder stream</short>
<descr>
<var>Create</var> instantiates a new <var>TASCII85DecoderStream</var>
instance, and sets <var>aStream</var> as the source stream.
</descr>
<seealso>
<link id="TASCII85DecoderStream.Destroy"/>
</seealso>
</element>

<!-- argument Visibility: default
     Declaration: aStream: TStream -->
<element name="TASCII85DecoderStream.Create.aStream">
<short>Source data</short>
</element>

<!-- procedure Visibility: published
     Declaration: procedure Decode(aInput: Byte) -->
<element name="TASCII85DecoderStream.Decode">
<short>Decode source byte</short>
<descr>
<var>Decode</var> decodes a source byte, and transfers it to the buffer. It
is an internal routine and should not be used directly.
</descr>
<seealso>
<link id="TASCII85DecoderStream.Close"/>
</seealso>
</element>

<!-- argument Visibility: default
     Declaration: aInput: Byte -->
<element name="TASCII85DecoderStream.Decode.aInput">
<short>Byte to decode</short>
</element>

<!-- procedure Visibility: published
     Declaration: procedure Close -->
<element name="TASCII85DecoderStream.Close">
<short>Close decoder</short>
<descr>
<var>Close</var> closes the decoder mechanism: it checks if all data was
read and performs a check to see whether all input data was consumed. 
</descr>
<errors>
If the input stream was invalid, an <var>EConvertError</var> exception is raised.
</errors>
<seealso>
<link id="TASCII85DecoderStream.ClosedP"/>
<link id="TASCII85DecoderStream.Read"/>
<link id="TASCII85DecoderStream.Destroy"/>
</seealso>
</element>

<!-- function Visibility: published
     Declaration: function ClosedP : Boolean -->
<element name="TASCII85DecoderStream.ClosedP">
<short>Check if the state is correct</short>
<descr>
<var>ClosedP</var> checks if the decoder state is one of
<var>ascInitial</var>, <var>ascNoEncodedChar</var>, <var>ascPrefix</var>,
and returns <var>True</var> if it is.
</descr>
<seealso>
<link id="TASCII85DecoderStream.Close"/>
<link id="TASCII85DecoderStream.BExpectBoundary"/>
</seealso>
</element>

<!-- function result Visibility: default
     Declaration: Result -->
<element name="TASCII85DecoderStream.ClosedP.Result">
<short>State is one of <var>ascInitial</var>, <var>ascNoEncodedChar</var> or <var>ascPrefix</var>.</short>
</element>

<!-- property Visibility: published
     Declaration: BExpectBoundary : Boolean -->
<element name="TASCII85DecoderStream.BExpectBoundary">
<short>Expect ~ character</short>
<descr>
<var>BExpectBoundary</var> is <var>True</var> if a encoded data boundary is
to be expected ("~&gt;").
</descr>
<seealso>
<link id="TASCII85DecoderStream.ClosedP">ClosedP</link>
</seealso>
</element>

<!-- destructor Visibility: public
     Declaration: destructor Destroy;  Override -->
<element name="TASCII85DecoderStream.Destroy">
<short>Clean up instance</short>
<descr>
<var>Destroy</var> closes the input stream using <link
id="TASCII85DecoderStream.Close">Close</link> and cleans 
up the <var>TASCII85DecoderStream</var> instance from memory.
</descr>
<errors>
In case the input stream was invalid, an exception may occur.
</errors>
<seealso>
<link id="TASCII85DecoderStream.Close"/>
</seealso>
</element>

<!-- function Visibility: public
     Declaration: function Read(var aBuffer;aCount: LongInt) : LongInt;  Override -->
<element name="TASCII85DecoderStream.Read">
<short>Read data from stream</short>
<descr>
<p>
<var>Read</var> attempts to read <var>aCount</var> bytes from the stream
and places them in <var>aBuffer</var>. It reads only as much data as is
available. The actual number of read bytes is returned.
</p>
<p>
The read method reads as much data from the input stream as needed to get to
<var>aCount</var> bytes, in general this will be <var>aCount*5/4</var>
bytes.
</p>
</descr>
</element>

<!-- function result Visibility: default
     Declaration: Result -->
<element name="TASCII85DecoderStream.Read.Result">
<short>Actual number of bytes transferred to buffer.</short>
</element>

<!-- argument Visibility: default
     Declaration: aBuffer -->
<element name="TASCII85DecoderStream.Read.aBuffer">
<short>Buffer to transfer data to</short>
</element>

<!-- argument Visibility: default
     Declaration: aCount: LongInt -->
<element name="TASCII85DecoderStream.Read.aCount">
<short>Number of bytes to transfer to buffer</short>
</element>

<!-- function Visibility: public
     Declaration: function Seek(aOffset: LongInt;aOrigin: Word) : LongInt;  Override -->
<element name="TASCII85DecoderStream.Seek">
<short>Set stream position</short>
<descr>
<var>Seek</var> sets the stream position. It only allows to set the position
to the current position of this file, and returns then the current position. 
All other arguments will result in an <var>EReadError</var> exception.
</descr>
<errors>
In case the arguments are different from <var>soCurrent</var> and 0, an
<var>EReadError</var> exception will be raised.
</errors>
<seealso>
<link id="TASCII85DecoderStream.Read"/>
</seealso>
</element>

<!-- function result Visibility: default
     Declaration: Result -->
<element name="TASCII85DecoderStream.Seek.Result">
<short>new position in stream.</short>
</element>

<!-- argument Visibility: default
     Declaration: aOffset: LongInt -->
<element name="TASCII85DecoderStream.Seek.aOffset">
<short>Offset from current position (should be zero).</short>
</element>

<!-- argument Visibility: default
     Declaration: aOrigin: Word -->
<element name="TASCII85DecoderStream.Seek.aOrigin">
<short>Origin for seek operation (should be <var>soCurrent</var>).</short>
</element>

<element name="TASCII85EncoderStream">
<short>ASCII 85 encoding stream</short>
<descr>
<p>
<var>TASCII85EncoderStream</var> is the counterpart to the <link
id="TASCII85DecoderStream"/> decoder stream: what
<var>TASCII85EncoderStream</var> encodes, can be decoded by <link
id="TASCII85DecoderStream"/>.
</p>
<p>
The encoder stream works using a destination stream: whatever data is
written to the encoder stream is encoded and written to the destination
stream. The stream must be passed on in the constructor.
</p>
<p>
Note that all encoded data is only written to the destination stream 
when the encoder stream is destroyed.
</p>
</descr>
<seealso>
<link id="TASCII85EncoderStream.create"/>
<link id="TASCII85DecoderStream"/>
</seealso>
</element>

<element name="TASCII85EncoderStream.Create">
<short>Create a new instance of <var>TASCII85EncoderStream</var></short>
<descr>
<var>Create</var> creates a new instance of<var>TASCII85EncoderStream</var>.
It stores <var>ADest</var> as the destination stream for the encoded data.
The <var>Width</var> parameter indicates the width of the lines that are
written by the encoder: after this amount of characters, a linefeed is put in
the data stream. If <var>ABoundary</var> is <var>True</var> then a boundary
delineator is written to the stream before and after the data.
</descr>
<seealso>
<link id="TASCII85EncoderStream"/>
<link id="TASCII85EncoderStream.Width">Width</link>
<link id="TASCII85EncoderStream.Boundary">Boundary</link>
</seealso>
</element>

<element name="TASCII85EncoderStream.Boundary">
<short>Is a boundary delineator written before and after the data</short>
<descr>
<var>Boundary</var> indicates whether the stream will write a boundary
delineator before and after the encoded data. It is passed to the
constructor and cannot be changed.
</descr>
<seealso>
<link id="TASCII85EncoderStream.Width">Width</link>
<link id="TASCII85EncoderStream.Create">Create</link>
</seealso>
</element>

<element name="TASCII85EncoderStream.Width">
<short>Width of the lines written to the data stream</short>
<descr>
<var>Width</var> is the width of the lines of encoded data written to the
stream. After <var>Width</var> lines, a line ending will be written to the
stream. The value is passed to the constructor and cannot be changed
afterwards.
</descr>
<seealso>
<link id="TASCII85EncoderStream.Boundary">Boundary</link>
<link id="TASCII85EncoderStream.Create">Create</link>        
</seealso>
</element>

<element name="TASCII85EncoderStream.Write">
<short>Write data encoded to the destination stream</short>
<descr>
<p>
<var>Write</var> encodes the <var>aCount</var> bytes of data in
<var>aBuffer</var> and writes the encoded data to the destination stream.
</p>
<p>
Not all data is written immediatly to the destination stream. Only after the
encoding stream is destroyed will the destination stream contain the full
data.
</p>
</descr>
<seealso>
<link id="TASCII85EncoderStream.Destroy"/>
</seealso>
</element>

<element name="TASCII85EncoderStream.Destroy">
<short>Flushed the data to the output stream and cleans up the encoder
instance.</short>
<descr>
<var>Destroy</var> writes the data remaining in the internal buffer to the
destination stream (possibly followed by a boundary delineator) and then
destroys the encoder instance.
</descr>
<seealso>
<link id="TASCII85EncoderStream.Write"/>
<link id="TASCII85EncoderStream.Boundary"/>
</seealso>
</element>

</module> <!-- ascii85 -->

</package>
</fpdoc-descriptions>