15 Memory files

The library(memfile) provides an alternative to temporary files, intended for temporary buffering of data. Memory files in general are faster than temporary files and do not suffer from security risks or naming conflicts associated with temporary-file management.

There is no limit to the number of memory streams, nor the size of them. However, a single memory file cannot have multiple streams at the same time, i.e., a memory file cannot be opened multiple times, not even for reading. Memory files are thread-safe and subject to (atom) garbage collection.

These predicates are first of all intended for building higher-level primitives such as open_codes_stream/3. See also format/3, atom_to_term/3, term_to_atom/2, term_string/2, etc.

new_memory_file(-Handle)

Create a new memory file and return a unique opaque handle to it.

free_memory_file(+Handle)

Discard the memory file and its contents. If the file is open it is first closed.

open_memory_file(+Handle, +Mode, -Stream)

Open the memory-file. Mode is one of read, write, append, update or insert. The resulting Stream must be closed using close/1. When opened for update or insert, the current location is initialized at the start of the data and can be modified using seek/4 or set_stream_position/2. In update mode, existing content is replaced, while the size is enlarged after hitting the end of the data. In insert mode, the new data is inserted at the current point.

open_memory_file(+Handle, +Mode, -Stream, +Options)

Open a memory-file as open_memory_file/3. Options:

encoding(+Encoding)

Set the encoding for a memory file and the created stream. Encoding names are the same as used with open/4. By default, memoryfiles represent UTF-8 streams, making them capable of storing arbitrary Unicode text. In practice the only alternative is octet, turning the memoryfile into binary mode. Please study SWI-Prolog Unicode and encoding issues before using this option.

free_on_close(+Bool)

If true (default false) and the memory file is opened for reading, discard the file (see free_memory_file/1) if the input is closed. This is used to realise open_chars_stream/2 in library(charsio).

size_memory_file(+Handle, -Size)

Return the content-length of the memory-file in characters in the current encoding of the memory file. The file should be closed and contain data.

size_memory_file(+Handle, -Size, +Encoding)

Return the content-length of the memory-file in characters in the given Encoding. The file should be closed and contain data.

atom_to_memory_file(+Atom, -Handle)

Turn an atom into a read-only memory-file containing the (shared) characters of the atom. Opening this memory-file in mode write yields a permission error.

insert_memory_file(+Handle, +Offset, +Data)

Insert Data into the memory file at location Offset. The offset is specified in characters. Data can be an atom, string, code or character list. Other terms are first serialized using writeq/1. This predicate raises a domain_error exception if Offset is out of range and a permission_error if the memory file is read-only or opened.

delete_memory_file(+Handle, +Offset, +Length)

Delete a Length characters from the memory file, starting at Offset. This predicate raises a domain_error exception if Offset or Offset+Length is out of range and a permission_error if the memory file is read-only or opened.

memory_file_to_atom(+Handle, -Atom)

Return the content of the memory-file in Atom.

memory_file_to_atom(+Handle, -Atom, +Encoding)

Return the content of the memory-file in Atom, pretending the data is in the given Encoding. This can be used to convert from one encoding into another, typically from/to bytes. For example, if we must convert a set of bytes that contain text in UTF-8, open the memory file as octet stream, fill it, and get the result using Encoding is utf8. Currently only supported if Encoding is one of iso_latin_1, octed (the same as iso_latin_1), wchar or utf8. Use with another encoding raises a domain error.

memory_file_to_codes(+Handle, -Codes)

Return the content of the memory-file as a list of character-codes in Codes.

memory_file_to_codes(+Handle, -Codes, +Encoding)

Return the content of the memory-file as a list of character-codes in Codes, pretending the data is in the given Encoding.

memory_file_to_string(+Handle, -String)

Return the content of the memory-file as a string in -String.

memory_file_to_string(+Handle, -String, +Encoding)

Return the content of the memory-file as a string in String, pretending the data is in the given Encoding.

memory_file_substring(+Handle, ?Before, ?Length, ?After, -SubString)

SubString is a substring of the memory file. There are Before characters in the memory file before SubString, SubString contains Length character and is followed by After characters in the memory file. The signature is the same as sub_string/5 and sub_atom/5, but currently at least two of the 3 position arguments must be specified. Future versions might implement the full functionality of sub_string/5.

memory_file_line_position(+MF, ?Line, ?LinePos, ?Offset)

True if the character offset Offset corresponds with the LinePos character on line Line. Lines are counted from one (1). Note that LinePos is not the column as each character counts for one, including backspace and tab.