Binary Class

Binary Creation

The following creates a binary item in Carapace script:

    0x"A10200B5"

Each pair of hex values (ie. A1, 02 etc) are converted into a single byte.

The create function can be used to create a zero-length binary item:

    (create Binary)

A Binary of a given length can be created as follows:

    (create Binary 24)

There are also methods on a String to convert a string to its binary equivalent.

Binary Properties

None

Binary Methods

method name	description
`length`	return the length of the binary data
`string`	convert the binary data to a string -- note that strings are terminated by a null (hex value `00`) character
`binary`	return a copy of this binary object
`copy`	return a copy of this binary object
`isBinary`	check for null bytes within the binary data
`fromFile`	fill the binary with data from the contents of the supplied file
`toFile`	write the binary data to the supplied file
`extract`	extract a range of bytes from the binary data and return them
`remove`	remove the supplied binary character from this binary
`==`	test equality of binary items
`!=`	test in-equality of binary items
`digest`	create the MD5 digest (see RFC 1321) for the string
`hex`	return a string of hex characters (in lower case)
`fromHex`	fill the binary with data from the contents of the supplied hex string
`set`	set a character within this binary data - treating the data as an array of characters
`get`	get a character from this binary data - treating the data as an array of characters
`search`	search this binary data for an occurrence of the supplied data
`translate`	surgically modify this binary data to translate the given characters
`+`	concatenatet this item with the supplied ones
`base64`	encode/decode this object using the Base 64 (MIME RFC 2045) encoding scheme
`quotedPrintable`	encode/decode this object using the `quoted-printable` (MIME RFC 2045) encoding scheme

`length`

Return the length of the binary data.

Arguments: none

Return type: Integer

`string`

Convert the binary data to a string -- note that strings are terminated by a null (hex value 00) character.

Arguments: none

Return type: String

`binary`

Return a copy of this binary item.

Arguments: none

Return type: Binary

`copy`

Return a copy of this binary item.

Arguments: none

Return type: Binary

`isBinary`

Check for null bytes within the binary data. If no null bytes are found, the Symbol true is returned, otherwise the empty List () is returned.

Arguments: none

Return type: Symbol true or the empty List ()

`fromFile`

Fill the binary with data from the contents of the supplied file. This surgically alters the binary item.

Arguments:

filename String

Return type: the empty List ()

`toFile`

Write the binary data to the supplied file. The mode for opening the file can be supplied -- the default mode is to write binary data (rather than append).

Arguments:

filename	`String`
mode optional	`String`

Return type: the empty List ()

`extract`

Extract a range of bytes from the binary data and return them. This is similar to the substring method for a String.

Arguments:

start	`Integer`
length (optional)	`Integer`

Return type: Binary

`remove`

Remove the supplied binary character from this binary. Currently, this only removes a binary string of unit-length.

Arguments:

bin Binary

Return type: the empty List () is returned.

`==`

Test equality of binary items. If the items are the same, the Symbol true is returned, otherwise the empty List () is returned.

Arguments:

item Binary

Return type: Symbol true or the empty List ()

`!=`

Test in-equality of binary items. If the items are the different, the Symbol true is returned, otherwise the empty List () is returned.

Arguments:

item Binary

Return type: Symbol true or the empty List ()

`digest`

Create the MD5 digest (see RFC 1321) for the string. This is returned as a Binary item of length 16.

Arguments: none

Return type: Binary

`hex`

Return a string of hex characters (in lower case).

Arguments: none

Return type: String

`fromHex`

Fill the binary with data from the contents of the supplied hex string.

Arguments:

hexChars String

Return type: String

`set`

Set a character within this binary data - treating the data as an array of characters. This surgically modifies this data. See the equivalent function String::get for further details.

This set method is reasonably tolerant of the type of its second argument - which can be a String, Integer or a Binary value.

Note that when indexing into binary data, the initial index is 0 rather than 1

Arguments:

index	`Integer`
newCharacter	`String` or Integer or Binary

Return type: the empty List () is returned

`get`

Get a character from within this binary data - treating the data as an array of characters. See the equivalent function String::get for further details.

Note that when indexing into binary data, the initial index is 0 rather than 1

Arguments:

index Integer

Return type: Integer

`search`

Search this binary data for an occurrence of the supplied data. If found, the integer offset is returned otherwise the empty list () is returned.

Arguments:

toFind	`String` or `Binary`
offset - optional	`Integer`

Return type: Integer or the empty List () is returned.

`translate`

Surgically modify this binary data to translate the given characters. All characters in the from argument are translated to corresponding entries in the to argument. The arguments must be the same length.

Arguments:

from	`Binary`
to	`Binary`

Return type: the empty List

`+`

Return a new binary which is the concatenation of this binary with all the supplied ones. The supplied binaries can be passed as a single List or as a sequence of Binaries.

Arguments: a List of Binary or one one or more Binary values.

Return type: Binary

`base64`

Encode/decode this data using the Base 64 (MIME RFC 2045) encoding scheme.

With no arguments, this binary data is assumed to be base64 encoded and the decoded result is returned.

If a lineLength is supplied, then the result of base64 encoding this data is returned. A lineLength of -1 ensures that no new-lines or carriage-returns are inserted into the encoded data. Otherwise, the lineLength must be a multiple of 4.

Arguments:

lineLength - optional Integer

Return type: Binary

`quotedPrintable`

Encode/decode this data using the quoted-printable (MIME RFC 2045) encoding scheme.

With no arguments, this string data is assumed to be quoted-printable encoded and the decoded result is returned.

If an argument is supplied, then the result of the lineLength decoding this data is returned.

Arguments:

flag - optional Object

Return type: Binary

Contents

Index

Current topic: objects