ASCII85 Class Documentation

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;


Class Definition

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()
}
?>

Class Constants

Algorithm Variations:

Exception Codes:


Class Methods

encode

Description

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:

Parameters

Return Values

Returns the encoded data.

Examples

$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);

decode

Description

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.

Parameters

Exceptions

Return Values

Returns the original data.

Notes

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.

Examples

$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);


btoa_get_checks

Description

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.

Parameters

Exceptions

Examples

$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"
*/

btoa_create_checks

Description

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.

Parameters

Examples

$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"
*/

btoa_validate_checks

Description

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.

Parameters

Examples

$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