Description: Documentation

## function array_to_bstring

### 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

bstring_to_array , init_char_array

## function bstring_to_array

### 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

array_to_bstring , init_char_array

## function bstrlen

### 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

strlen , length

## 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

unpack , sizeof_pack , pad_pack_format , sprintf

## function pad_pack_format

### 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

pack , unpack , sizeof_pack

## function sizeof_pack

### 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

pack , unpack , pad_pack_format

## function unpack

### 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

pack , sizeof_pack , pad_pack_format