From 1f0f950baa009ce5b11c3b38b26e25d0301a88e8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ludovic=20Court=C3=A8s?= Date: Thu, 9 Apr 2009 23:20:34 +0200 Subject: [PATCH] doc: Document binary I/O. * doc/api-r6rs.texi (R6RS Port Manipulation): Add xref to `seek'. (R6RS Binary I/O): Renamed to... (R6RS Binary Input): this. Add binary input procedures. (R6RS Binary Output): New. --- doc/api-r6rs.texi | 125 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 27 deletions(-) diff --git a/doc/api-r6rs.texi b/doc/api-r6rs.texi index 2b506dd..68d942d 100644 --- a/doc/api-r6rs.texi +++ b/doc/api-r6rs.texi @@ -406,7 +406,8 @@ in Guile 1.8. @menu * R6RS End-of-File:: The end-of-file object. * R6RS Port Manipulation:: Manipulating R6RS ports. -* R6RS Binary I/O:: Binary input/output. +* R6RS Binary Input:: Binary input. +* R6RS Binary Output:: Binary output. @end menu @node R6RS End-of-File @@ -446,6 +447,10 @@ If @var{port} supports it (see below), return the offset (an integer) indicating where the next octet will be read from/written to in @var{port}. If @var{port} does not support this operation, an error condition is raised. + +This is similar to Guile's @code{seek} procedure with the +@code{SEEK_CUR} argument (@pxref{Random Access,,, guile, The GNU Guile +Reference Manual}). @end deffn @deffn {Scheme Procedure} port-has-port-position? port @@ -457,6 +462,10 @@ If @var{port} supports it (see below), set the position where the next octet will be read from/written to @var{port} to @var{offset} (an integer). If @var{port} does not support this operation, an error condition is raised. + +This is similar to Guile's @code{seek} procedure with the +@code{SEEK_SET} argument (@pxref{Random Access,,, guile, The GNU Guile +Reference Manual}). @end deffn @deffn {Scheme Procedure} port-has-set-port-position!? port @@ -469,13 +478,13 @@ of @var{proc}. Return the return values of @var{proc}. @end deffn -@node R6RS Binary I/O -@subsection Binary Input/Output +@node R6RS Binary Input +@subsection Binary Input @cindex binary input -R6RS binary input and output ports can be created with the procedures -described below. +R6RS binary input ports can be created with the procedures described +below. @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder] @deffnx {C Function} scm_r6rs_open_bytevector_input_port (bv, transcoder) @@ -486,27 +495,6 @@ Return an input port whose contents are drawn from bytevector @var{bv} The @var{transcoder} argument is currently not supported. @end deffn -@deffn {Scheme Procedure} open-bytevector-output-port [transcoder] -@deffnx {C Function} scm_r6rs_open_bytevector_output_port (transcoder) -Return two values: a binary output port and a procedure. The latter -should be called with zero arguments to obtain a bytevector containing -the data accumulated by the port, as illustrated below. - -@lisp -(call-with-values - (lambda () - (open-bytevector-output-port)) - (lambda (port get-bytevector) - (display "hello" port) - (get-bytevector))) - -@result{} #vu8(104 101 108 108 111) -@end lisp - -@c FIXME: Update description when implemented. -The @var{transcoder} argument is currently not supported. -@end deffn - @cindex custom binary input ports @deffn {Scheme Procedure} make-custom-binary-input-port id read! [get-position [set-position! [close]]] @@ -562,8 +550,91 @@ could be implemented as follows: @end lisp @end deffn +@cindex binary input +Binary input is achieved using the procedures below: + +@deffn {Scheme Procedure} get-u8 port +@deffnx {C Function} scm_r6rs_get_u8 (port) +Return an octet read from @var{port}, a binary input port, blocking as +necessary, or the end-of-file object. +@end deffn + +@deffn {Scheme Procedure} lookahead-u8 port +@deffnx {C Function} scm_r6rs_lookahead_u8 (port) +Like @code{get-u8} but does not update @var{port}'s position to point +past the octet. +@end deffn + +@deffn {Scheme Procedure} get-bytevector-n port count +@deffnx {C Function} scm_r6rs_get_bytevector_n (port, count) +Read @var{count} octets from @var{port}, blocking as necessary and +return a bytevector containing the octets read. If fewer bytes are +available, a bytevector smaller than @var{count} is returned. +@end deffn + +@deffn {Scheme Procedure} get-bytevector-n! port bv start count +@deffnx {C Function} scm_r6rs_get_bytevector_n_x (port, bv, start, count) +Read @var{count} bytes from @var{port} and store them in @var{bv} +starting at index @var{start}. Return either the number of bytes +actually read or the end-of-file object. +@end deffn + +@deffn {Scheme Procedure} get-bytevector-some port +@deffnx {C Function} scm_r6rs_get_bytevector_some (port) +Read from @var{port}, blocking as necessary, until data are available or +and end-of-file is reached. Return either a new bytevector containing +the data read or the end-of-file object. +@end deffn + +@deffn {Scheme Procedure} get-bytevector-all port +@deffnx {C Function} scm_r6rs_get_bytevector_all (port) +Read from @var{port}, blocking as necessary, until the end-of-file is +reached. Return either a new bytevector containing the data read or the +end-of-file object (if no data were available). +@end deffn + +@node R6RS Binary Output +@subsection Binary Output + +Binary output ports can be created with the procedures below. + +@deffn {Scheme Procedure} open-bytevector-output-port [transcoder] +@deffnx {C Function} scm_r6rs_open_bytevector_output_port (transcoder) +Return two values: a binary output port and a procedure. The latter +should be called with zero arguments to obtain a bytevector containing +the data accumulated by the port, as illustrated below. + +@lisp +(call-with-values + (lambda () + (open-bytevector-output-port)) + (lambda (port get-bytevector) + (display "hello" port) + (get-bytevector))) + +@result{} #vu8(104 101 108 108 111) +@end lisp + +@c FIXME: Update description when implemented. +The @var{transcoder} argument is currently not supported. +@end deffn + +@cindex binary output +Writing to a binary output port can be done using the following +procedures: + +@deffn {Scheme Procedure} put-u8 port octet +@deffnx {C Function} scm_r6rs_put_u8 (port, octet) +Write @var{octet}, an integer in the 0--255 range, to @var{port}, a +binary output port. +@end deffn + +@deffn {Scheme Procedure} put-bytevector port bv [start [count]] +@deffnx {C Function} scm_r6rs_put_bytevector (port, bv, start, count) +Write the contents of @var{bv} to @var{port}, optionally starting at +index @var{start} and limiting to @var{count} octets. +@end deffn -FIXME: Finish. @c LocalWords: Bytevectors bytevector bytevectors endianness endian accessors @c LocalWords: endiannesses -- 2.11.4.GIT