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.