
list_to_stream(?Codes, +Stream, +Mode)

   Map a list to an output stream

Arguments
   Codes               A (possibly partial) list of character codes
   Stream              A stream handle
   Mode                One of the atoms 'incremental' or 'delayed'

Type
   library(lazy_io)

Description

	This predicates maps a list of character codes to an output
	stream.  When list_to_stream/3 is called, the list Codes may
	be uninstantiated, or it may be a partial list.  Once the list
	is terminated, and the Stream is closed, the file will reflect
	the last state of the list.  As long as the stream is not
	closed, the list may be arbitrarily extended, shortened on
	backtracking, terminated, un-terminated on backtracking, etc. 
	Only once the stream is closed using close/1, is the stream
	contents committed to reflect the list (provided the list has
	been terminated).  This behaviour is independent of the Mode
	argument.

	Mode 'incremental' should be used if the list may become very long.
	In this mode the list is copied into the stream incrementally, such
	that the front of the list can be garbage collected.

	Mode 'delayed' may be slightly more efficient, since it copies the
	list contents to the stream only once the list is terminated.  This
	will however use more memory, since the whole list needs to be held
	in memory until it is terminated.

	The Stream must be open in write-mode.  In addition it is advisable
	to set the delete_file(when_lost) option when opening - this will
	have the effect of eventually deleting the associated file in case
	the stream is never explicitly closed.

	If the stream is closed without the list being terminated, the stream
	content is essentially undefined.  In practice, with 'incremental'
	mode the stream will reflect the partial list as it was when the
	stream was closed.  With 'delayed' mode, the stream will be empty
	or reflect an earlier terminated state that was backtracked over.

    

Modes and Determinism
   list_to_stream(?, +, +) is det

Examples
   
    write_list(File, N, Code) :-
	open(File, write, Out, [delete_file(when_lost)]),
	list_to_stream(Codes, Out, incremental),
	( for(_,1,N), foreach(Code,Codes), param(Code) do true ),
	close(Out).
    

See Also
   stream_to_lazy_list / 2, open / 4, char_code / 2, string_list / 2
