diff options
Diffstat (limited to 'libslang/doc/tm/rtl/bstr.tm')
| -rw-r--r-- | libslang/doc/tm/rtl/bstr.tm | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/libslang/doc/tm/rtl/bstr.tm b/libslang/doc/tm/rtl/bstr.tm new file mode 100644 index 0000000..ffe2825 --- /dev/null +++ b/libslang/doc/tm/rtl/bstr.tm @@ -0,0 +1,151 @@ +\function{array_to_bstring} +\synopsis{Convert an array to a binary string} +\usage{BString_Type array_to_bstring (Array_Type a)} +\description + The \var{array_to_bstring} function returns the elements of an + array \var{a} as a binary string. +\seealso{bstring_to_array, init_char_array} +\done + +\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 \var{bstring_to_array} function returns an array of unsigned + characters whose elements correspond to the characters in the + binary string. +\seealso{array_to_bstring, init_char_array} +\done + +\function{bstrlen} +\synopsis{Get the length of a binary string} +\usage{UInt_Type bstrlen (BString_Type s)} +\description + The \var{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 +#v+ + variable s = "hello\0"; + len = bstrlen (s); % ==> len = 6 + len = strlen (s); % ==> len = 5 +#v- +\seealso{strlen, length} +\done + +\function{pack} +\synopsis{Pack objects into a binary string} +\usage{BString_Type pack (String_Type fmt, ...)} +\description + The \var{pack} function combines zero or more the objects (represented + by the ellipses above) into a binary string acording to the format + string \var{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: +#v+ + 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 +#v- + A decimal length specifier may follow the data-type specifier. With + the exception of the \var{s} and \var{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 \var{s} or + \var{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 \var{c}, \var{C}, \var{s}, \var{S}, and + \var{x}, each of these may be prefixed by a character that indicates + the byte-order of the object: +#v+ + > big-endian order (network order) + < little-endian order + = native byte-order +#v- + The default is to use native byte order. + + When unpacking via the \var{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 \var{S} specifier. +\example +#v+ + 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" +#v- +\seealso{unpack, sizeof_pack, pad_pack_format, sprintf} +\done + +\function{pad_pack_format} +\synopsis{Add padding to a pack format} +\usage{BString_Type pad_pack_format (String_Type fmt)} +\description + The \var{pad_pack_format} function may be used to add the + appropriate padding to the format \var{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. +\seealso{pack, unpack, sizeof_pack} +\done + +\function{sizeof_pack} +\synopsis{Compute the size implied by a pack format string} +\usage{UInt_Type sizeof_pack (String_Type fmt)} +\description + The \var{sizeof_pack} function returns the size of the binary string + represented by the format string \var{fmt}. This information may be + needed when reading a structure from a file. +\notes +\seealso{pack, unpack, pad_pack_format} +\done + +\function{unpack} +\synopsis{Unpack Objects from a Binary String} +\usage{(...) = unpack (String_Type fmt, BString_Type s)} +\description + The \var{unpack} function unpacks objects from a binary string + \var{s} according to the format \var{fmt} and returns the objects to + the stack in the order in which they were unpacked. See the + documentation of the \var{pack} function for details about the + format string. +\example +#v+ + (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" +#v- +\seealso{pack, sizeof_pack, pad_pack_format} +\done + |