The class binary defines blocks allocated in the binary space segment and the methods needed to manipulate them. Each binary block is represented by a wwlisp cell, which contains in its "car" part a pointer to the byte array of the block on a special segment (the binary space), the length of the block being attached as a property. A binary block can contain any bit pattern and can be used to define or map C structures in order to communicate with the system or APIs. Any new block is always allocated on 32 bits aligned address. Object can also be made using a pre-allocated block, in order to access a structure maintained by the system or an API. The objects of the class binary are readable and printable as the string [binary] followed immediately by the MIME-base64 encoded content of the binary block, without enclosing double-quotes. The binary space is submitted to a copying garbage collection when exhausted. |
Function Type | subr |
Arguments | a binary block, a binary block |
Return Value | t or nil |
Description | returns t if the second binary is lexically greater than the first |
Example | (setq bin1(make-instance binary 8 0)) (setq bin2(make-instance binary 8 1)) (< bin1 bin2) => t |
Function Type | subr |
Arguments | a binary block, a binary block |
Return Value | t or nil |
Description | returns t if the two blocks are bytewise equal |
Example | (setq bin1(make-instance binary 8 0)) (setq bin2(make-instance binary 8 0)) (= bin1 bin2) => t |
Function Type | subr |
Arguments | a binary block, a binary block |
Return Value | t or nil |
Description | returns t if the second binary is lexically before the first |
Example | (setq bin1(make-instance binary 8 0)) (setq bin2(make-instance binary 8 1)) (> bin2 bin1) => t |
Function Type | subr |
Arguments | a binary block |
Return Value | a string |
Description | returns a string where the content of the binary block has been translated to base64 without trailing '=' |
Example | (base64 (make-instance binary 10)) => "AAAAAAAAAAAAAA" |
Function Type | subr |
Arguments | a binary |
Return Value | a binary |
Description | does nothing; is just needed by some weird application |
Example | - |
Function Type | subr |
Arguments | one or more binary objects |
Return Value | a binary |
Description | makes a new binary object allocated on the binary space, made of the concatenation of the binary objects given as arguments |
Example | - |
Function Type | subr |
Arguments | the symbol binary, mandatory integer, optional integer, optional unsigned integer |
Return Value | a binary |
Description | never call binary-constructor directly but always through (make-instance) ; the first argument gives the length of the block allocated in binary space, the second argument gives the integer value 0..255 used for initializing the block, and the third argument gives the address where the block can already exist in case of a heap or system segment; if arg2 is omitted or nil, the block is initialized with zeroes; if an address is supplied, the block is not initialized |
Example | (make-instance binary 256 0) => gives a block with length 256 bytes initialized with zeroes |
Function Type | subr |
Arguments | a binary |
Return Value | a binary |
Description | makes a new binary allocated in binary space, containing the same data as the argument |
Example | (copy arg) => new binary |
Function Type | subr |
Arguments | a binary, a binary |
Return Value | integer |
Description | counts how many times the second argument appears in the sequence given as first argument |
Example | (count(concat block1 block1) block1) => 2 |
Function Type | subr |
Arguments | a binary, a binary |
Return Value | a binary |
Description | returns a binary bloc where all instances of the second argument in the first have been deleted; modifies the original block, reducing eventually its length |
Example | (delete block1 block2) => modified block1 |
Function Type | subr |
Arguments | mandatory binary, mandatory binary, mandatory integer, optional integer |
Return Value | a binary |
Description | makes a new binary where the second argument has been deposited in the first argument at the position stated in the third argument up to the position before that stated in the fourth argument, or the length of the block to deposit if the fourth argument is not given, or the length of the block to deposit |
Example | (deposit block1 block2 pos-start pos-end+1) |
Function Type | subr |
Arguments | a binary of which the length is enough to store a double precision float, ie 64 bits |
Return Value | a float |
Description | extracts a float from the binary |
Example | (float block1) |
Function Type | subr |
Arguments | a binary block, an optional keyword |
Return Value | a string |
Description | returns a character string containing the printable encoding of the binary block passed as argument; the text begins by the string "[binary]" immediately followed by the value of the binary block MIME-base64 encoded (ie: base64 without "=" padding); the function is the default formatter of the class binary ; such a formatted string can be read by readerprinter-ratom and give back an identical binary object; the optional keyword 'hexadecimal causes the method to return a string beginning by "[binary/hex]" and containing the binary block translated to hexadecimal in lowercase; the keyword 'HEXADECIMAL causes the same in uppercase; the keyword 'base64 does the same as the default option; |
Example | (format(make-instance binary 10)) => "[binary]AAAAAAAAAAAAAAAAAAAAAA" |
Function Type | subr |
Arguments | a binary block, an optional t or nil |
Return Value | a string |
Description | returns a string where the content is the binary block translated to hexadecimal, without the '0x' prefix; if the second argument is non nil, then the alphabetic characters are in uppercase |
Example | (hexadecimal (make-instance binary 10)) => "00000000000000000000" |
Function Type | subr |
Arguments | a binary of which length is enough to store a long integer (32 or 64 bits depending on CPU) |
Return Value | an integer |
Description | extracts an integer from the binary block |
Example | (integer block1) |
Function Type | subr |
Arguments | a binary |
Return Value | an integer |
Description | returns an integer giving the length in bytes of the binary block |
Example | (length block1) |
Function Type | subr |
Arguments | mandatory binary, mandatory binary, mandatory integer, optional integer |
Return Value | a binary |
Description | returns the binary given as first argument, where the second argument has been deposited at the position stated in the third argument up to the position before that stated in the fourth argument, or the length of the block to deposit if the fourth argument is not given, or the length of the block to deposit |
Example | (ndeposit block1 block2 pos-start pos-end+1) |
Function Type | subr |
Arguments | a binary |
Return Value | a list of integers or nil |
Description | returns a list of integers containing each a byte of the binary block; each integer has a value from 0 to 255 |
Example | (ord (make-instance binary 4)) => (0 0 0 0) |
Function Type | subr |
Arguments | a binary block, a binary block |
Return Value | an integer or nil |
Description | returns an integer with the position of the second argument in the first; returns 0 as lowest position; returnq nil if the second argument is not found in the first |
Example | (position block1 block2) |
Function Type | subr |
Arguments | a binary, a binary |
Return Value | a binary |
Description | returns a binary bloc where all instances of the second argument in the first have been deleted; does not modify the original block, works on a copy |
Example | (remove block1 block2) => new version of modified block1 |
Function Type | subr |
Arguments | a binary block |
Return Value | a binary block |
Description | returns a binary block where the sequence of the bytes have been reversed, the first becoming the last |
Example | (reverse block1) |
Function Type | subr |
Arguments | a binary block, a binary block |
Return Value | an integer or nil |
Description | returns an integer with the position of the second argument in the first; returns 0 as lowest position; returns nil if the second argument is not found in the first |
Example | (search block1 block2) |
Function Type | subr |
Arguments | a binary block |
Return Value | a string |
Description | returns a string made of bytes extracted from a binary block; the string has the same length as the binary; all occurences of zeroes are replaced by spaces (ie 0x20) |
Example | (string block) |
Function Type | subr |
Arguments | a binary block, an integer, an optional integer |
Return Value | a binary block or nil |
Description | returns a binary block extracted from the first argument starting at the position given as second argument, and ranging up to the position just before the one given as third argument; if no third argument is provided, the extraction goes up to the end of the first argument; returns nil if there is nothing to extract at the required positions ; first position is at 0 |
Example | (subseq block1 0 4) |
Function Type | subr |
Arguments | a binary block, a binary block, a binary block |
Return Value | a binary block |
Description | returns a copy of the binary block given as first argument where all occurences of the third argument have been replaced by the second argument; the total length of the resulting block can be modified, as the target and substitution can be of different lengths |
Example | (substitute block1 new target) |
Function Type | subr |
Arguments | a binary of which length is enough to store an unsigned long integer (32 or 64 bits depending on CPU) |
Return Value | an unsigned integer |
Description | extracts an unsigned integer from the binary block |
Example | (unsignedinteger block1) |