Version: 1.0 / 20081127
Author: Rubens 滝口 Ribeiro
License: LGPL 3
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.
While base64 and uuencode generates text result 33% greater than original data, ascii85 generates text result 25% greater (approximadly).
It is very useful to transfer binary data under text protocols. Some kinds of documents uses this algorithm to encode data (i.e: PDF).
Internal links: Definition; Constants; Methods;
This class uses PHP5 class format. It has a private constructor, because there are only two main static methods: encode and decode.
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.
<?php final class ascii85 { private void __construct() public static string encode() public static string decode() private static void split() /* internal use */ private static bool clean() /* internal use */ public static void btoa_get_checks() public static void btoa_create_checks() public static bool btoa_validate_checks() } ?>
Algorithm Variations:
ascii85::BASIC
ascii85::ADOBE
ascii85::BTOA
Exception Codes:
ascii85::THROW_ADOBE_DELIMITER
ascii85::THROW_BTOA_CHEKS
ascii85::THROW_BTOA_VALUE
ascii85::THROW_TUPLE_CHAR
ascii85::THROW_TUPLE_SIZE
public static string encode ( string $value, [ int $variation [, int $split_pos ]] )
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:
ascii85::BASIC
- basic algorithm;ascii85::ADOBE
- Adobe variation;ascii85::ATOB
- atob/btoa variation;$value
: the string to be encoded.$variation
: code of algorithm variation. Default value is ascii85::BASIC
.$split_pos
: splits encoded value in specified position using new-line (0x10). Default value is false (no split).Returns the encoded data.
$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);
public static string decode ( string $value, [ int $variation ] )
Decode an encoded data ($value) using ASCII85 algorithm. You can also specify a variation of
basic algorithm passing second parameter ($variation) like encode
method.
$value
: the string to be encoded.$variation
: code of algorithm variation. Default value is ascii85::BASIC
.ascii85::THROW_BTOA_VALUE
- if encoded data has invalid format (BTOA variation only).ascii85::THROW_BTOA_CHECKS
- if data verification fails (BTOA variation only).ascii85::THROW_ADOBE_DELIMITER
- if value has no delimiter (Adobe variation only).ascii85::THROW_TUPLE_CHAR
- if an invalid character was found.ascii85::THROW_TUPLE_SIZE
- if tuple binary value is greater then 232 (can not be represented by 4 bytes).Returns the original data.
If some data was generated using a specific algorithm variation, the decode process shoud use the same algorithm variation. The value of split position is not used in decode process because whitespaces are ignored.
$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);
public static void btoa_get_checks ( string $value, string &$size_dec, string &$size_hex, string &$check_xor, string &$check_sum, string &$check_rot )
Get data verification from an encoded string (using BTOA variant) and update parameters.
$value
: the string to be parsed.&$size_dec
: size in decimal format.&$size_hex
: size in hexadecimal format.&$check_xor
: check XOR in hexadecimal format.&$check_sum
: check SUM in hexadecimal format.&$check_rot
: check ROT in hexadecimal format.ascii85::THROW_BTOA_VALUE
- if encoded data has invalid format (BTOA variation only).$btoa_encoded = <<<BTOA xbtoa Begin ;KZG[DK?q/A92?k+EM(*@<5s%Amoak+D,&'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" */
public static void btoa_create_checks ( string $value, string
&$size_dec, string &$size_hex, string &$check_xor, string &$check_sum, string &$check_rot )
Calculate data verification from a string and update parameters.
$value
: the input string.&$size_dec
: size in decimal format.&$size_hex
: size in hexadecimal format.&$check_xor
: check XOR in hexadecimal format.&$check_sum
: check SUM in hexadecimal format.&$check_rot
: check ROT in hexadecimal format.$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" */
public static bool btoa_validate_checks ( string $value, string
$size_dec, string $size_hex, string $check_xor, string $check_sum, string $check_rot )
Calculate data verification from a string and compares with parameters.
$value
: the input string.$size_dec
: size in decimal format.$size_hex
: size in hexadecimal format.$check_xor
: check XOR in hexadecimal format.$check_sum
: check SUM in hexadecimal format.$check_rot
: check ROT in hexadecimal format.$text = 'Hello World'; $r = ascii85::btoa_validate_checks($btoa_encoded, '11', 'b', '20', '427', '2b7ac'); var_dump($r); /* bool(true) */
Last update: $Date2008/11/30 16:26:58 $
Copyright © 2008 Rubens Takiguti Ribeiro