X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=bitmatch.mli;h=c4aacc56a61661bbd44d1dbbaa8c6a2e4e1aa53c;hb=00f782f26fa89fa07dabb7155707b1415f50572b;hp=979e591aac783b5bfe64f36e38eaccf4076e00e2;hpb=97cd7dd22059a1c5ca72852130ac430aa713e968;p=ocaml-bitstring.git diff --git a/bitmatch.mli b/bitmatch.mli index 979e591..c4aacc5 100644 --- a/bitmatch.mli +++ b/bitmatch.mli @@ -15,7 +15,7 @@ * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * - * $Id: bitmatch.mli,v 1.20 2008-05-08 21:28:28 rjones Exp $ + * $Id$ *) (** @@ -634,7 +634,35 @@ val string_of_bitstring : bitstring -> string This function is inefficient. In the best case when the bitstring is nicely byte-aligned we do a [String.sub] operation. If the bitstring isn't aligned then this involves a lot of bit twiddling - and is particularly inefficient. *) + and is particularly inefficient. + + If the bitstring is not a multiple of 8 bits wide then the + final byte of the string contains the high bits set to the + remaining bits and the low bits set to 0. *) + +val bitstring_to_file : bitstring -> string -> unit +(** [bitstring_to_file bits filename] writes the bitstring [bits] + to the file [filename]. It overwrites the output file. + + Some restrictions apply, see {!bitstring_to_chan}. *) + +val bitstring_to_chan : bitstring -> out_channel -> unit +(** [bitstring_to_file bits filename] writes the bitstring [bits] + to the channel [chan]. + + Channels are made up of bytes, bitstrings can be any bit length + including fractions of bytes. So this function only works + if the length of the bitstring is an exact multiple of 8 bits + (otherwise it raises [Invalid_argument "bitstring_to_chan"]). + + Furthermore the function is efficient only in the case where + the bitstring is stored fully aligned, otherwise it has to + do inefficient bit twiddling like {!string_of_bitstring}. + + In the common case where the bitstring was generated by the + [BITSTRING] operator and is an exact multiple of 8 bits wide, + then this function will always work efficiently. +*) (** {3 Printing bitstrings} *)