Next Previous Contents

6. Functions that Operate on Binary Strings

6.1 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

6.2 bstring_to_array

Synopsis

Convert a binary string to an array of bytes

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 bytes in the binary string.

See Also

array_to_bstring, init_char_array

6.3 bstrcat

Synopsis

Concatenate binary strings

Usage

String_Type bstrcat (BString_Type a_1, ..., BString_Type a_N)

Description

The bstrcat function concatenates its N binary string arguments a_1, ... a_N together and returns the result.

Notes

This function will produce a result that is identical to that of strcat if the input strings do not contain null characters.

See Also

strcat, bstrjoin

6.4 bstrjoin

Synopsis

Concatenate elements of an array of BString_Type objects

Usage

String_Type bstrjoin (Array_Type a [, BString_Type delim])

Description

The bstrjoin function operates on an array of binary strings by joining successive elements together separated with the optional delimiter delim. If delim is not specified, then empty string "" will be used resulting in a concatenation of the elements.

See Also

bstrcat, strjoin

6.5 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 characters.

Example

    s = "hello\0";
    len = bstrlen (s);      % ==> len = 6
    len = strlen (s);       % ==> len = 5

See Also

strlen, length

6.6 count_byte_occurrences

Synopsis

Count the number of occurrences of a byte in a binary string

Usage

UInt_Type count_byte_occurrences (bstring, byte)

Description

This function returns the number of times the specified byte occurs in the binary string bstr.

Notes

This function uses byte-semantics. If character semantics are desired, use the count_char_occurrences function.

See Also

count_char_occurrences

6.7 is_substrbytes

Synopsis

test if a binary string contains a series of bytes

Usage

Int_Type is_substrbytes (a, b [,ofs])

Description

This function may be used to see if the binary string a contains the byte-sequence given by the binary string b. If b is contained in a, then a ones-based offset of the first occurance of b in a is returned. Otherwise, the function will return 0 to indicate that a does not contain b.

An optional 1-based parameter ofs may be passed to the function to indicate where in a the search is to start. The returned value is still a 1-based offset from the beginning of a where b is located.

Notes

Support for the optional argument was added in version 2.3.0.

See Also

is_substr, count_byte_occurrences

6.8 pack

Synopsis

Pack objects into a binary string

Usage

BString_Type pack (String_Type fmt, ...)

Description

The pack function combines zero or more objects (represented by the ellipses above) into a binary string according to the format string fmt.

The format string consists of one or more data-type specification characters defined by the following table:

     c     signed byte
     C     unsigned byte
     h     short
     H     unsigned short
     i     int
     I     unsigned int
     l     long
     L     unsigned long
     m     long long
     M     unsigned long long
     j     16 bit int
     J     16 bit unsigned int
     k     32 bit int
     K     32 bit unsigned int
     q     64 bit int
     Q     64 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
     z     character string, null 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, S, or z specifiers, it indicates the field width to be used. If the length specifier is not present, the length defaults to one.

When packing, unlike the s specifier, the z specifier guarantees that at least one null byte will be written even if the field has to be truncated to do so.

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 characters are stripped when unpacking an object given by the S specifier. Trailing null characters will be stripped from an object represented by the z specifier. No such stripping is performed 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"
     a = pack ("z4", "AB");             % ==> a = "AB\0\0"
     a = pack ("s4", "ABCDEFG");        % ==> a = "ABCD"
     a = pack ("z4", "ABCDEFG");        % ==> a = "ABC\0"

See Also

unpack, sizeof_pack, pad_pack_format, sprintf

6.9 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 characters to the format fmt such that the data types specified by the format will be properly aligned on word boundaries. This is especially important when reading or writing files that assume the native alignment.

See Also

pack, unpack, sizeof_pack

6.10 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.

See Also

pack, unpack, pad_pack_format

6.11 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


Next Previous Contents