binary Class Reference


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.


  • binary-<
  • binary-=
  • binary->
  • binary-base64
  • binary-binary
  • binary-concat
  • binary-constructor
  • binary-copy
  • binary-count
  • binary-delete
  • binary-deposit
  • binary-float
  • binary-format
  • binary-hexadecimal
  • binary-integer
  • binary-length
  • binary-ndeposit
  • binary-ord
  • binary-position
  • binary-remove
  • binary-reverse
  • binary-search
  • binary-string
  • binary-subseq
  • binary-substitute
  • binary-unsignedinteger

    • List of all Inherited Classes

  • class

    • binary-<

    (< arg1 arg2 )

    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

    binary-=

    (= arg1 arg2 )

    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

    binary->

    (> arg1 arg2 )

    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

    binary-base64

    (base64 arg )

    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"

    binary-binary

    (binary arg1 )

    Function Type subr
    Arguments a binary
    Return Value a binary
    Description does nothing; is just needed by some weird application
    Example -

    binary-concat

    (concat arg1 ... argn )

    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 -

    binary-constructor

    (make-instance binary arg1 arg2 arg3 )

    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

    binary-copy

    (copy arg )

    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

    binary-count

    (count arg1 arg2 )

    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

    binary-delete

    (delete arg1 arg2 )

    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

    binary-deposit

    (deposit arg1 arg2 arg3 arg4 )

    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)

    binary-float

    (float arg1 )

    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)

    binary-format

    (format arg1 ... argn )

    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"

    binary-hexadecimal

    (hexadecimal arg )

    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"

    binary-integer

    (integer arg )

    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)

    binary-length

    (length arg )

    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)

    binary-ndeposit

    (ndeposit arg1 arg2 arg3 arg4 )

    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)

    binary-ord

    (ord arg )

    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)

    binary-position

    (position arg1 arg2 )

    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)

    binary-remove

    (remove arg1 arg2 )

    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

    binary-reverse

    (reverse arg )

    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)

    binary-search

    (search arg1 arg2 )

    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)

    binary-string

    (string arg )

    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)

    binary-subseq

    (subseq arg1 arg2 arg3 )

    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)

    binary-substitute

    (substitute arg1 arg2 arg3 )

    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)

    binary-unsignedinteger

    (unsignedinteger arg )

    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)
    Updated 29/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo