226 lines
10 KiB
HTML
226 lines
10 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Issue READ-AND-WRITE-BYTES Writeup</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="../Issues/iss284_w.htm">
|
|
<LINK REL=UP HREF="../Issues/iss285.htm">
|
|
<LINK REL=NEXT HREF="../Issues/iss286_w.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="../Issues/iss284_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="../Issues/iss285.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="../Issues/iss286_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<H2>Issue READ-AND-WRITE-BYTES Writeup</H2>
|
|
|
|
<PRE><B>Issue:</B> <A HREF="iss285.htm">READ-AND-WRITE-BYTES</A><P>
|
|
Reference: X3J13/92-102, dpANS 12.24<P>
|
|
X3J13/92-2601, Jeremy Wertheimer comment #1<P>
|
|
<B>Category:</B> ADDITION<P>
|
|
<B>Edit History:</B> Version 1, 1/5/92, Kim Barrett<P>
|
|
<B>Status:</B> Proposal NEW-FUNCTIONS passed (5+3)-3 on letter ballot 93-302.<P>
|
|
<P>
|
|
<B>Problem Description:<P>
|
|
</B><P>
|
|
Common Lisp should have a facility for reading and writing blocks of <P>
|
|
binary bytes. The lack of such a facility makes it impossible to write <P>
|
|
portable efficient programs to access binary files. This lack might make <P>
|
|
common lisp unsuitable for various applications such as database management <P>
|
|
and image processing. This lack is not simply a matter of convenience that<P>
|
|
could be remedied by user programming. If the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A> does not <A REL=DEFINITION HREF="../Body/f_provid.htm#provide"><B>provide</B></A> at <P>
|
|
least one <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> for efficiently reading and writing blocks of binary bytes, <P>
|
|
users cannot later construct one using available common lisp facilities.<P>
|
|
<P>
|
|
In addition, some users have complained about the lack of a non-consing<P>
|
|
variant of READ-STRING, to which an existing string could be passed to receive<P>
|
|
the data.<P>
|
|
<P>
|
|
<B>Proposal (READ-AND-WRITE-BYTES:NEW-FUNCTIONS):<P>
|
|
</B><P>
|
|
Add the following dictionary entries to Chapter 21, Streams.<P>
|
|
<P>
|
|
%%% ========== <A REL=DEFINITION HREF="../Body/f_rd_seq.htm#read-sequence"><B>READ-SEQUENCE</B></A><P>
|
|
\begincom{read-sequence}\ftype{Function}<P>
|
|
<P>
|
|
\label Syntax::<P>
|
|
<P>
|
|
\DefunWithValues {read-sequence} {sequence stream {\key} start end} {position}<P>
|
|
<P>
|
|
\param{sequence}---a \term{sequence}.<P>
|
|
<P>
|
|
\param{stream}---an \term{input} \term{stream}.<P>
|
|
<P>
|
|
\param{start}, \param{end}---\term{bounding index designators} of<P>
|
|
\param{sequence}. \Defaults{\param{start} and \param{end}}{\f{0} and \nil}<P>
|
|
<P>
|
|
\param{position}---an \term{integer} greater than or equal to zero, and<P>
|
|
less than or equal to the \term{length} of the \param{sequence}.<P>
|
|
<P>
|
|
\label Description::<P>
|
|
<P>
|
|
Destructively modifies \param{sequence} by replacing the \term{elements}<P>
|
|
of \param{sequence} \term{bounded} by \param{start} and \param{end} with<P>
|
|
\term{elements} read from \param{stream}.<P>
|
|
<P>
|
|
\param{Sequence} is destructively modified by copying successive<P>
|
|
\term{elements} into it from \param{stream}. If the \term{end of file} for<P>
|
|
\param{stream} is reached before copying all \term{elements} of the<P>
|
|
subsequence, then the extra \term{elements} near the end of \param{sequence}<P>
|
|
are not updated.<P>
|
|
<P>
|
|
\param{Position} is the index of the first \term{element} of \param{sequence}<P>
|
|
that was not updated, which might be less than \param{end} because the<P>
|
|
\term{end of file} was reached.<P>
|
|
<P>
|
|
\label Examples::<P>
|
|
<P>
|
|
\code<P>
|
|
(<A REL=DEFINITION HREF="../Body/m_defpar.htm#defvar"><B>defvar</B></A> *data* (<A REL=DEFINITION HREF="../Body/f_mk_ar.htm#make-array"><B>make-array</B></A> 15 :initial-element <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>nil</B></A>))<P>
|
|
(<A REL=DEFINITION HREF="../Body/a_values.htm#values"><B>values</B></A> (<A REL=DEFINITION HREF="../Body/f_rd_seq.htm#read-sequence"><B>read-sequence</B></A> *data* (<A REL=DEFINITION HREF="../Body/f_mk_s_1.htm#make-string-input-stream"><B>make-string-input-stream</B></A> "test string")) *data*)<P>
|
|
\EV 11, #(#\t #\e #\s #\t #\Space #\s #\t #\r #\i #\n #\g <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A> <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A> <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A> <A REL=DEFINITION HREF="../Body/a_nil.htm#nil"><B>NIL</B></A>)<P>
|
|
\endcode<P>
|
|
<P>
|
|
\label Side Effects::<P>
|
|
<P>
|
|
Modifies \param{stream} and \param{sequence}.<P>
|
|
<P>
|
|
\label Affected By:\None<P>
|
|
<P>
|
|
\label Exceptional Situations::<P>
|
|
<P>
|
|
\Lazychecktype{sequence}{a \term{proper sequence}}<P>
|
|
\Shouldchecktype{start}{a non-negative \term{integer}}<P>
|
|
\Shouldchecktype{end}{a non-negative \term{integer} or \nil}<P>
|
|
<P>
|
|
Might signal an error \oftype{type-error} if an \term{element} read from<P>
|
|
the \param{stream} is not a member of the \term{element type} of the<P>
|
|
\param{sequence}.<P>
|
|
<P>
|
|
\label See Also::<P>
|
|
<P>
|
|
{\secref\ConstantModification}, \funref{write-sequence}, \funref{read-line}<P>
|
|
<P>
|
|
\label Notes::<P>
|
|
<P>
|
|
\funref{read-sequence} is identical in effect to iterating over the indicated<P>
|
|
subsequence and reading one \term{element} at a time from \param{stream} and<P>
|
|
storing it into \param{sequence}, but may be more efficient than the<P>
|
|
equivalent loop. An efficient implementation is more likely to exist<P>
|
|
for the case where the \param{sequence} is a \term{vector} with the same<P>
|
|
\term{element type} as the \param{stream}.<P>
|
|
<P>
|
|
%%% ========== <A REL=DEFINITION HREF="../Body/f_wr_seq.htm#write-sequence"><B>WRITE-SEQUENCE</B></A><P>
|
|
\begincom{write-sequence}\ftype{Function}<P>
|
|
<P>
|
|
\label Syntax::<P>
|
|
<P>
|
|
\DefunWithValues {write-sequence} {sequence stream {\key} start end} {sequence}<P>
|
|
<P>
|
|
\param{sequence}---a \term{sequence}.<P>
|
|
<P>
|
|
\param{stream}---an \term{output} \term{stream}.<P>
|
|
<P>
|
|
\param{start}, \param{end}---\term{bounding index designators} of<P>
|
|
\param{sequence}. \Defaults{\param{start} and \param{end}}{\f{0} and \nil}<P>
|
|
<P>
|
|
\label Description::<P>
|
|
<P>
|
|
\funref{write-sequence} writes the \term{elements} of the subsequence<P>
|
|
of \param{sequence} \term{bounded} by \param{start} and \param{end} to<P>
|
|
\param{stream}.<P>
|
|
<P>
|
|
\label Examples::<P>
|
|
<P>
|
|
\code<P>
|
|
(<A REL=DEFINITION HREF="../Body/f_wr_seq.htm#write-sequence"><B>write-sequence</B></A> "bookworms" <A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*standard-output*</B></A> :end 4)<P>
|
|
\OUT book<P>
|
|
\EV "bookworms"<P>
|
|
\endcode<P>
|
|
<P>
|
|
\label Side Effects::<P>
|
|
<P>
|
|
Modifies \param{stream}.<P>
|
|
<P>
|
|
\label Affected By:\None<P>
|
|
<P>
|
|
\label Exceptional Situations::<P>
|
|
<P>
|
|
\Lazychecktype{sequence}{a \term{proper sequence}}<P>
|
|
\Shouldchecktype{start}{a non-negative \term{integer}}<P>
|
|
\Shouldchecktype{end}{a non-negative \term{integer} or \nil}<P>
|
|
<P>
|
|
Might signal an error \oftype{type-error} if an \term{element} of the<P>
|
|
\term{bounded} \term{sequence} is not a member of the<P>
|
|
\term{stream element type} of the \param{stream}.<P>
|
|
<P>
|
|
\label See Also::<P>
|
|
<P>
|
|
{\secref\ConstantModification}, \funref{read-sequence}, \funref{write-string},<P>
|
|
\funref{write-line}<P>
|
|
<P>
|
|
\label Notes::<P>
|
|
<P>
|
|
\funref{write-sequence} is identical in effect to iterating over the indicated<P>
|
|
subsequence and writing one \term{element} at a time to \param{stream}, but<P>
|
|
may be more efficient than the equivalent loop. An efficient implementation<P>
|
|
is more likely to exist for the case where the \param{sequence} is a<P>
|
|
\term{vector} with the same \term{element type} as the \param{stream}.<P>
|
|
<P>
|
|
<B>Editorial Impact:<P>
|
|
</B><P>
|
|
Just drop in a couple more dictionary entries. Might want to add a few more<P>
|
|
cross references.<P>
|
|
<P>
|
|
<B>Rationale:<P>
|
|
</B><P>
|
|
Addresses the problem description.<P>
|
|
<P>
|
|
<B>Current Practice:<P>
|
|
</B><P>
|
|
Symbolics Genera provides :string-in and :string-out operations on streams<P>
|
|
that could easily be used to implement these functions.<P>
|
|
<P>
|
|
IIM Common Lisp provides functions with similar capabilities but under<P>
|
|
slightly different names.<P>
|
|
<P>
|
|
<B>Cost to Implementors:<P>
|
|
</B><P>
|
|
Depends on the details of the implementation of the stream operators, but<P>
|
|
probably not very difficult in most cases. Getting maximum efficiency might<P>
|
|
<A REL=DEFINITION HREF="../Body/f_provid.htm#require"><B>require</B></A> some significant work, but some of that work has probably already<P>
|
|
been done to support existing operators or extensions.<P>
|
|
<P>
|
|
<B>Cost to Users:<P>
|
|
</B><P>
|
|
None. This is an upwardly compatible addition.<P>
|
|
<P>
|
|
<B>Performance Impact:<P>
|
|
</B><P>
|
|
Some existing code that uses iteration could be rewritten to use the new<P>
|
|
operators, with a potentially substantial improvement in performance.<P>
|
|
<P>
|
|
<B>Benefits:<P>
|
|
</B><P>
|
|
Improved performance, and clearer code.<P>
|
|
<P>
|
|
<B>Aesthetics:<P>
|
|
</B><P>
|
|
The use of these operators is probably clearer than the corresponding<P>
|
|
iteration code, and therefor more aesthetic.<P>
|
|
<P>
|
|
</PRE>
|
|
<HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|