[ library(lazy_io) | Reference Manual | Alphabetic Index ]

list_to_stream(?Codes, +Stream, +Mode)

Map a list to an output stream
Codes
A (possibly partial) list of character codes
Stream
A stream handle
Mode
One of the atoms 'incremental' or 'delayed'

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

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