marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/HyperSpec-7-0/HyperSpec/Issues/iss285_w.htm

227 lines
10 KiB
HTML
Raw Normal View History

Add hyperspec
2024-04-01 10:24:07 +02:00
<!-- 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> &quot;test string&quot;)) *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> &quot;bookworms&quot; <A REL=DEFINITION HREF="../Body/v_debug_.htm#STstandard-outputST"><B>*standard-output*</B></A> :end 4)<P>
\OUT book<P>
\EV &quot;bookworms&quot;<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>
Copy permalink