Location: PHPKode > scripts > ASCII85 - binary to tex > ascii85-binary-to-text/doc.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" >
<meta name="title" content="ASCII85 Class Documentation" >
<meta name="keywords" content="ascii85,byte-to-ascii,encode,decode" >
<meta name="author" content="Rubens Takiguti Ribeiro" >
<title>ASCII85 Class Documentation</title>
<style type="text/css" rel="stylesheet"><!--
.method { background-color: #EEEEFF; border: 1px outset #EEEEFF; padding: 1em; margin: 1em; }
.method pre, .synopsis { background-color: #FFFFFF; border: 1px solid #000000; padding: .5em; }
.method h4 { border-bottom: 2px dotted #222244; }
--></style>
</head>
<body>

<div>
<h1>ASCII85 Class Documentation</h1>
<p><em>Version: 1.0 / 20081127<br />
   Author: <a href="http://www.tecnolivre.ufla.br/">Rubens <span title="Takiguti">&#28381;&#21475;</span> Ribeiro</a><br />
   License: <a href="LICENSE.TXT">LGPL 3</a></em></p>

<p>This class provide an algorithm to encode/decode binary data using
   printable characters. It is like base64_encode/base64_decode and
   convert_uuencode/convert_uudecode functions, but it is more economic.</p>
<p>While base64 and uuencode generates text result 33% greater than original data,
   ascii85 generates text result 25% greater (approximadly).</p>
<p>It is very useful to transfer binary data under text protocols.
   Some kinds of documents uses this algorithm to encode data (i.e: 
   <abbr title="Portable Document Format">PDF</abbr>).</p>
<p>Internal links:
  <a href="#class_definition">Definition</a>;
  <a href="#class_constants">Constants</a>;
  <a href="#class_methods">Methods</a>;
</p>

</div>

<hr />

<div>
<h2 id="class_definition" name="class_definition">Class Definition</h2>
<p>This class uses PHP5 class format. It has a private constructor, because
   there are only two main static methods: encode and decode.</p>
<p>Decoding an encoded data can failure. Internal errors are
   sent using PHP exceptions. Each kind of exception has a code 
   (see constants) and the message can be translated.</p>
<pre>

&lt;?php
final class ascii85 {
    private void __construct()
    public static string <a href="#encode">encode()</a>
    public static string <a href="#decode">decode()</a>
    private static void split() /* internal use */
    private static bool clean() /* internal use */
    public static void <a href="#btoa_get_checks">btoa_get_checks()</a>
    public static void <a href="#btoa_create_checks">btoa_create_checks()</a>
    public static bool <a href="#btoa_validate_checks">btoa_validate_checks()</a>
}
?&gt;
</pre>
</div>

<hr />

<div>
<h2 id="class_constants" name="class_constants">Class Constants</h2>
<p>Algorithm Variations:
<ul>
  <li><code><strong>ascii85::BASIC</strong></code></li>
  <li><code><strong>ascii85::ADOBE</strong></code></li>
  <li><code><strong>ascii85::BTOA</strong></code></li>
</ul>
</p>
<p>Exception Codes:
<ul>
  <li><code><strong>ascii85::THROW_ADOBE_DELIMITER</strong></code></li>
  <li><code><strong>ascii85::THROW_BTOA_CHEKS</strong></code></li>
  <li><code><strong>ascii85::THROW_BTOA_VALUE</strong></code></li>
  <li><code><strong>ascii85::THROW_TUPLE_CHAR</strong></code></li>
  <li><code><strong>ascii85::THROW_TUPLE_SIZE</strong></code></li>
</ul>
</p>
</div>

<hr />

<div>
<h2 id="class_methods" name="class_methods">Class Methods</h2>

<div class="method">
<h3 id="encode" name="encode">encode</h3>

<h4>Description</h4>
<p class="synopsis"><code>public static string <strong>encode</strong> ( string $value, [ int $variation [, int $split_pos ]] )</code></p>
<p>Encode a binary data ($value) using ASCII85 algorithm. You can also specify a variation of
   basic algorithm passing second parameter ($variation) that can asume the value of one
   internal constant:
<ul>
  <li><code><strong>ascii85::BASIC</strong></code> - basic algorithm;</li>
  <li><code><strong>ascii85::ADOBE</strong></code> - Adobe variation;</li>
  <li><code><strong>ascii85::ATOB</strong></code> - atob/btoa variation;</li>
</ul>
</p>

<h4>Parameters</h4>
<ul>
  <li><code><strong>$value</strong></code>: the string to be encoded.</li>
  <li><code><strong>$variation</strong></code>: code of algorithm variation. Default value is <code>ascii85::BASIC</code>.</li>
  <li><code><strong>$split_pos</strong></code>: splits encoded value in specified position using new-line (0x10). Default value is false (no split).</li>
</ul>

<h4>Return Values</h4>
<p>Returns the encoded data.</p>

<h4>Examples</h4>
<pre>
$text = 'Some text or binary data';

// Encode using Basic algorithm
$basic_encoded = ascii85::encode($text);

// Encode using Adobe variation and split on position 80
$adobe_encoded = ascii85::encode($text, ascii85::ADOBE, 80);

// Encode using BTOA variation and split on position 72
$btoa_encoded = ascii85::encode($text, ascii85::BTOA, 72);
</pre>
</div>


<hr />

<div class="method">
<h3 id="decode" name="decode">decode</h3>

<h4>Description</h4>
<p class="synopsis"><code>public static string <strong>decode</strong> ( string $value, [ int $variation ] )</code></p>
<p>Decode an encoded data ($value) using ASCII85 algorithm. You can also specify a variation of
   basic algorithm passing second parameter ($variation) like <code>encode</code> method.</p>

<h4>Parameters</h4>
<ul>
  <li><code><strong>$value</strong></code>: the string to be encoded.</li>
  <li><code><strong>$variation</strong></code>: code of algorithm variation. Default value is <code>ascii85::BASIC</code>.</li>
</ul>

<h4>Exceptions</h4>
<ul>
  <li><code><strong>ascii85::THROW_BTOA_VALUE</strong></code> - if encoded data has invalid format <em>(BTOA variation only)</em>.</li>
  <li><code><strong>ascii85::THROW_BTOA_CHECKS</strong></code> - if data verification fails <em>(BTOA variation only)</em>.</li>
  <li><code><strong>ascii85::THROW_ADOBE_DELIMITER</strong></code> - if value has no delimiter <em>(Adobe variation only)</em>.</li>
  <li><code><strong>ascii85::THROW_TUPLE_CHAR</strong></code> - if an invalid character was found.</li>
  <li><code><strong>ascii85::THROW_TUPLE_SIZE</strong></code> - if tuple binary value is greater then 2<sup>32</sup> (can not be represented by 4 bytes).</li>
</ul>

<h4>Return Values</h4>
<p>Returns the original data.</p>

<h4>Notes</h4>
<p>If some data was generated using a specific algorithm variation, the decode process 
<strong>shoud</strong> use the same algorithm variation. The value of split position is
not used in decode process because whitespaces are ignored.</p>

<h4>Examples</h4>
<pre>
$text = 'Some text or binary data';

// Encode using Basic algorithm
$basic_encoded = ascii85::encode($text);

// Decode using Basic algorithm
$basic_decoded = ascii85::decode($basic_encoded);

// Encode using Adobe variation and split on position 80
$adobe_encoded = ascii85::encode($text, ascii85::ADOBE, 80);

// Decode using Adobe variation
$adobe_decoded = ascii85::decode($adobe_encoded, ascii85::ADOBE);

</pre>
</div>


<hr />

<div class="method">
<h3 id="btoa_get_checks" name="btoa_get_checks">btoa_get_checks</h3>

<h4>Description</h4>
<p class="synopsis"><code>public static void <strong>btoa_get_checks</strong> ( string $value, string &$size_dec, string &$size_hex, string &$check_xor, string &$check_sum, string &$check_rot )</code></p>
<p>Get data verification from an encoded string (using BTOA variant) and update parameters.</p>

<h4>Parameters</h4>
<ul>
  <li><code><strong>$value</strong></code>: the string to be parsed.</li>
  <li><code><strong>&$size_dec</strong></code>: size in decimal format.</li>
  <li><code><strong>&$size_hex</strong></code>: size in hexadecimal format.</li>
  <li><code><strong>&$check_xor</strong></code>: check XOR in hexadecimal format.</li>
  <li><code><strong>&$check_sum</strong></code>: check SUM in hexadecimal format.</li>
  <li><code><strong>&$check_rot</strong></code>: check ROT in hexadecimal format.</li>
</ul>

<h4>Exceptions</h4>
<ul>
  <li><code><strong>ascii85::THROW_BTOA_VALUE</strong></code> - if encoded data has invalid format <em>(BTOA variation only)</em>.</li>
</ul>

<h4>Examples</h4>
<pre>
$btoa_encoded = &lt;&lt;&lt;BTOA
xbtoa Begin
;KZG[DK?q/A92?k+EM(*@&lt;5s%Amoak+D,&amp;'A7cq
xbtoa End N 31 1f E d S b44 R 89760043
BTOA;

// Parse btoa encoded value
try {
    ascii85::btoa_get_checks($btoa_encoded, $size_dec, $size_hex, $check_xor, $check_sum, $check_rot);
} catch (Exception $e) {
    echo 'Error '.$e->getCode().': '.$e->getMessage();
}

// Print parsed value
var_dump($size_dec, $size_hex, $check_xor, $check_sum, $check_rot);

/*
string(2) "31"
string(2) "1f"
string(1) "d"
string(3) "b44"
string(8) "89760043"
*/
</pre>
</div>


<hr />

<div class="method">
<h3 id="btoa_create_checks" name="btoa_create_checks">btoa_create_checks</h3>

<h4>Description</h4>
<p class="synopsis"><code>public static void <strong>btoa_create_checks</strong> ( string $value, string 
&$size_dec, string &$size_hex, string &$check_xor, string &$check_sum, string &$check_rot )</code></p>
<p>Calculate data verification from a string and update parameters.</p>

<h4>Parameters</h4>
<ul>
  <li><code><strong>$value</strong></code>: the input string.</li>
  <li><code><strong>&$size_dec</strong></code>: size in decimal format.</li>
  <li><code><strong>&$size_hex</strong></code>: size in hexadecimal format.</li>
  <li><code><strong>&$check_xor</strong></code>: check XOR in hexadecimal format.</li>
  <li><code><strong>&$check_sum</strong></code>: check SUM in hexadecimal format.</li>
  <li><code><strong>&$check_rot</strong></code>: check ROT in hexadecimal format.</li>
</ul>

<h4>Examples</h4>
<pre>
$text = 'Hello World';

ascii85::btoa_create_checks($btoa_encoded, $size_dec, $size_hex, $check_xor, $check_sum, $check_rot);

// Print calculated values
var_dump($size_dec, $size_hex, $check_xor, $check_sum, $check_rot);

/*
string(2) "11"
string(2) "b"
string(1) "20"
string(3) "427"
string(8) "2b7ac"
*/
</pre>
</div>


<hr />

<div class="method">
<h3 id="btoa_validate_checks" name="btoa_validate_checks">btoa_validate_checks</h3>

<h4>Description</h4>
<p class="synopsis"><code>public static bool <strong>btoa_validate_checks</strong> ( string $value, string 
$size_dec, string $size_hex, string $check_xor, string $check_sum, string $check_rot )</code></p>
<p>Calculate data verification from a string and compares with parameters.</p>

<h4>Parameters</h4>
<ul>
  <li><code><strong>$value</strong></code>: the input string.</li>
  <li><code><strong>$size_dec</strong></code>: size in decimal format.</li>
  <li><code><strong>$size_hex</strong></code>: size in hexadecimal format.</li>
  <li><code><strong>$check_xor</strong></code>: check XOR in hexadecimal format.</li>
  <li><code><strong>$check_sum</strong></code>: check SUM in hexadecimal format.</li>
  <li><code><strong>$check_rot</strong></code>: check ROT in hexadecimal format.</li>
</ul>

<h4>Examples</h4>
<pre>
$text = 'Hello World';

$r = ascii85::btoa_validate_checks($btoa_encoded, '11', 'b', '20', '427', '2b7ac');
var_dump($r);

/*
bool(true)
*/
</pre>
</div>

</div>

<p>Last update:
$Date2008/11/30 16:26:58 $
</p>
<p>Copyright &copy; 2008  Rubens Takiguti Ribeiro</p>

</body>
</html>
Return current item: ASCII85 - binary to tex