Synopsis
Convert an array to a binary string
Usage
BString_Type array_to_bstring (Array_Type a)
Description
The array_to_bstring function returns the elements of an
array a as a binary string.
See also
Synopsis
Convert a binary string to an array of characters
Usage
UChar_Type[] bstring_to_array (BString_Type b)
Description
The bstring_to_array function returns an array of unsigned
characters whose elements correspond to the characters in the
binary string.
See also
Synopsis
Get the length of a binary string
Usage
UInt_Type bstrlen (BString_Type s)
Description
The bstrlen function may be used to obtain the length of a
binary string. A binary string differs from an ordinary string (a C
string) in that a binary string may include null chracters.
Example
variable s = "hello\0";
len = bstrlen (s); % ==> len = 6
len = strlen (s); % ==> len = 5
See also
function pack
Synopsis
Pack objects into a binary string
Usage
BString_Type pack (String_Type fmt, ...)
Description
The
pack function combines zero or more the objects (represented
by the ellipses above) into a binary string acording to the format
string
fmt .
The format string consists of one or more data-type specification
characters, and each may be followed by an optional decimal length
specifier. Specifically, the data-types are specified according to
the following table:
c char
C unsigned char
h short
H unsigned short
i int
I unsigned int
l long
L unsigned long
j 16 bit int
J 16 unsigned int
k 32 bit int
K 32 bit unsigned int
f float
d double
F 32 bit float
D 64 bit float
s character string, null padded
S character string, space padded
x a null pad character
A decimal length specifier may follow the data-type specifier. With
the exception of the
s and
S specifiers, the length
specifier indicates how many objects of that data type are to be
packed or unpacked from the string. When used with the
s or
S specifiers, it indicates the field width to be used. If the
length specifier is not present, the length defaults to one.
With the exception of
c ,
C ,
s ,
S , and
x , each of these may be prefixed by a character that indicates
the byte-order of the object:
> big-endian order (network order)
< little-endian order
= native byte-order
The default is to use native byte order.
When unpacking via the
unpack function, if the length
specifier is greater than one, then an array of that length will be
returned. In addition, trailing whitespace and null character are
stripped when unpacking an object given by the
S specifier.
Example
a = pack ("cc", 'A', 'B'); % ==> a = "AB";
a = pack ("c2", 'A', 'B'); % ==> a = "AB";
a = pack ("xxcxxc", 'A', 'B'); % ==> a = "\0\0A\0\0B";
a = pack ("h2", 'A', 'B'); % ==> a = "\0A\0B" or "\0B\0A"
a = pack (">h2", 'A', 'B'); % ==> a = "\0\xA\0\xB"
a = pack ("<h2", 'A', 'B'); % ==> a = "\0B\0A"
a = pack ("s4", "AB", "CD"); % ==> a = "AB\0\0"
a = pack ("s4s2", "AB", "CD"); % ==> a = "AB\0\0CD"
a = pack ("S4", "AB", "CD"); % ==> a = "AB "
a = pack ("S4S2", "AB", "CD"); % ==> a = "AB CD"
See also
Synopsis
Add padding to a pack format
Usage
BString_Type pad_pack_format (String_Type fmt)
Description
The pad_pack_format function may be used to add the
appropriate padding to the format fmt such that the data types
specified by the format will be properly aligned for the system.
This is especially important when reading or writing files that
assume the native alignment.
See the S-Lang User's Guide for more information about the use of
this function.
See also
Synopsis
Compute the size implied by a pack format string
Usage
UInt_Type sizeof_pack (String_Type fmt)
Description
The sizeof_pack function returns the size of the binary string
represented by the format string fmt . This information may be
needed when reading a structure from a file.
Notes
See also
Synopsis
Unpack Objects from a Binary String
Usage
(...) = unpack (String_Type fmt, BString_Type s)
Description
The
unpack function unpacks objects from a binary string
s according to the format
fmt and returns the objects to
the stack in the order in which they were unpacked. See the
documentation of the
pack function for details about the
format string.
Example
(x,y) = unpack ("cc", "AB"); % ==> x = 'A', y = 'B'
x = unpack ("c2", "AB"); % ==> x = ['A', 'B']
x = unpack ("x<H", "\0\xAB\xCD"); % ==> x = 0xCDABuh
x = unpack ("xxs4", "a b c\0d e f"); % ==> x = "b c\0"
x = unpack ("xxS4", "a b c\0d e f"); % ==> x = "b c"
See also