S-Lang Run-Time Library Reference: Version 2.0.4: Functions that Operate on Binary Strings

Next Previous Contents

## 5. Functions that Operate on Binary Strings

## 5.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`

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

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

  > `

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

  > `

See Also

  `strlen, length`

## 5.4 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     char
  >          C     unsigned char
  >          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`

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

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

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