IO¶

Usage

use IO;

or

import IO;

Submodules

FormattedIO

Support for a variety of kinds of input and output.

Note

All Chapel programs automatically include write, writeln and writef.

Input/output (I/O) facilities in Chapel include the types file, fileReader and fileWriter; the constants stdin, stdout and stderr; the functions open, file.close, file.reader, file.writer, fileReader.read, fileWriter.write, and many others.

Warning

Please be aware, the IO Module documentation is under development and currently contains some minor inconsistencies.

I/O Overview¶

A file in Chapel identifies a file in the underlying operating system. Reads to a file are done via one or more fileReaders associated with the file and writes to a file are done via one or more fileWriters. Each fileReader or fileWriter uses a buffer to provide sequential read or write access to its file, optionally starting at an offset.

For example, the following program opens a file and writes an integer to it:

try {
  // open the file "test-file.txt" for writing, creating it if
  // it does not exist yet.
  var myFile = open("test-file.txt", ioMode.cw);

  // create a fileWriter starting at file offset 0
  // (start and end offsets can be specified when creating the
  // fileWriter)
  var myFileWriter = myFile.writer();

  var x: int = 17;

  // This function will write the human-readable text version of x;
  // binary I/O is also possible.
  myFileWriter.write(x);

  // Now test-file.txt contains:
  // 17

} catch e: Error {
  // Generally speaking, the I/O functions throw errors.  Handling these
  // errors is application-dependent and is left out of this example for
  // brevity.  Please see the documentation for individual functions for more
  // details about errors that they can throw.
}

Then, the following program can be used to read the integer:

try {
  // open the file "test-file.txt" for reading only
  var myFile = open("test-file.txt", ioMode.r);

  // create a fileReader starting at file offset 0
  // (start and end offsets can be specified when creating the
  // fileReader)
  var myFileReader = myFile.reader();

  var x: int;

  // Now read a textual integer. Note that the
  // fileReader.read function returns a bool to indicate
  // if it read something or if the end of the file
  // was reached before something could be read.
  var readSomething = myFileReader.read(x);

  writeln("Read integer ", x);
  // prints out:
  // Read integer 17

} catch e: Error {
  // Generally speaking, the I/O functions throw errors.  Handling these
  // errors is application-dependent and is left out of this example for
  // brevity.  Please see the documentation for individual functions for more
  // details about errors that they can throw.
}

The read functions allow one to read values into variables as the following example demonstrates. It shows three ways to read values into a pair of variables x and y.

var x: int;
var y: real;
/* reading into variable expressions, returning
   true if the values were read, false on EOF */
var ok:bool = read(x, y);

/* reading via a single type argument */
x = read(int);
y = read(real);

/* reading via multiple type arguments */
(x, y) = read(int, real);

Design Rationale¶

Since fileReaders and fileWriters operate independently, concurrent I/O to the same open file is possible without contending for locks. Furthermore, since the fileReader or fileWriter (and not the file) stores the current file offset, it is straightforward to create programs that access the same open file in parallel. Note that such parallel access is not possible in C when multiple threads are using the same FILE* to write to different regions of a file because of the race condition between fseek and fwrite. Because of these issues, Chapel programmers wishing to perform I/O will need to know how to open files as well as create fileReaders and fileWriters.

I/O Styles¶

Warning

iostyle is now unstable. We are working on creating a full-featured replacement for it but in the meantime the Formatted I/O facilities are still available to control formatting.

Reading and writing of Chapel’s basic types is regulated by an applicable iostyle. In particular, the I/O style controls whether binary or text I/O should be performed. For binary I/O it specifies, for example, byte order and string encoding. For text I/O it specifies string representation; the base, field width and precision for numeric types; and so on. Each fileReader or fileWriter has an associated I/O style. It applies to all read/write operations on that fileReader or fileWriter, except when the program specifies explicitly an I/O style for a particular read or write.

See the definition for the iostyle type. This type represents I/O styles and provides details on formatting and other representation choices.

The default value of the iostyle type is undefined. However, the compiler-generated constructor is available. It can be used to generate the default I/O style, with or without modifications. In addition, the function defaultIOStyle will return the default I/O style just as new iostyle() will.

The I/O style for an I/O operation can be provided through an optional style= argument in a variety of places:

when performing the I/O, e.g. in calls to fileWriter.write or fileReader.read

when creating the fileReader with file.reader

when creating the fileWriter file.writer

or when creating the file with e.g. open

Note that file.reader, or file.writer will copy the file’s I/O style if a style= argument is not provided. Also note that I/O functions on fileReaders and fileWriters will by default use the I/O style stored with that fileReader or fileWriter.

A fileReader’s I/O style may be retrieved using fileReader._style and set using fileReader._set_style. A fileWriter’s I/O style may be retrieved using fileWriter._style and set using fileWriter._set_style. These functions should only be called while the fileReader’s or fileWriter’s lock is held, however. See Synchronization of fileReader and fileWriter Data and Avoiding Data Races for more information on fileReader and fileWriter locks.

As an example for specifying an I/O style, the code below specifies the minimum width for writing numbers so array elements are aligned in the output:

stdout.writeln(MyArray, new iostyle(min_width=10));

I/O facilities in Chapel also include several other ways to control I/O formatting. There is support for formatted I/O with FormattedIO.fileReader.readf and FormattedIO.fileWriter.writef. Also note that record or class implementations can provide custom functions implementing read or write operations for that type (see The readThis() and writeThis() Methods).

Files¶

There are several functions that open a file and return a file including open, openTempFile, openMemFile, the file initializer that takes an int argument, and the file initializer that takes a c_FILE argument.

Once a file is open, it is necessary to create associated fileReader(s) and/or fileWriter(s) - see file.reader and file.writer - to read from and/or write to the file.

Use the file.fsync function to explicitly synchronize the file to ensure that file data is committed to the file’s underlying device for persistence.

Files, fileReaders, and fileWriters will be kept alive while there are variables referring to them and closed when all variables referring to them have gone out of scope. However, each can be closed explicitly with close methods. Note that file.close will not work if the file has open fileReaders and/or fileWriters.

Note

Escaped strings can be used for paths on systems where UTF-8 file names are not enforced.

Functions for fileReader and fileWriter Creation¶

file.writer creates a fileWriter for writing to a file, and file.reader creates a fileReader for reading from a file.

The helper functions openReader and openWriter can also be used to open a file and create a fileReader or fileWriter to it in a single step.

Synchronization of fileReader and fileWriter Data and Avoiding Data Races¶

FileReaders and fileWriters (and files) contain locks in order to keep their operation safe for multiple tasks. When creating a fileReader or fileWriter, it is possible to disable the lock (for performance reasons) by passing locking=false to e.g. file.writer(). Some fileReader and fileWriter methods - in particular those beginning with the underscore - should only be called on locked fileReaders or fileWriters. With these methods, it is possible to get or set the fileReader or fileWriter style, or perform I/O “transactions” (see fileWriter.mark, e.g.). To use these methods, e.g., first lock the fileWriter with fileWriter.lock, call the methods you need, then unlock the fileWriter with fileWriter.unlock. Note that in the future, we may move to alternative ways of calling these functions that guarantee that they are not called on a fileReader or fileWriter without the appropriate locking.

Besides data races that can occur if locking is not used in fileWriters when it should be, it is also possible for there to be data races on file data that is buffered simultaneously in multiple fileReader/fileWriter combinations. The main way to avoid such data races is the fileWriter.flush synchronization operation. fileWriter.flush will make all writes to the fileWriter, if any, available to concurrent viewers of its associated file, such as other fileWriters, fileReaders or other applications accessing this file concurrently. See the note below for more details on the situation in which this kind of data race can occur.

Note

Since fileWriters can buffer data until fileWriter.flush is called, it is possible to write programs that have undefined behavior because of race conditions on fileWriter buffers. In particular, the problem comes up for programs that make:

concurrent operations on multiple fileWriters and/or fileReaders that operate on overlapping regions of a file

where at least one fileWriter is used along with other fileWriters or fileReaders

and where data could be stored in more than one of the overlapping fileWriter’s buffers at the same time (i.e., write and read ordering are not enforced through fileWriter.flush and other means such as sync variables).

Note that it is possible in some cases to create a file that does not allow multiple fileWriters and/or fileReaders at different offsets. FileWriters created on such files will not change the file’s offset based on a start= offset arguments. Instead, each read or write operation will use the file descriptor’s current offset. Therefore, only one fileWriter or fileReader should be created for files created in the following situations:

with the file initializer that takes a c_FILE argument

with the file initializer that takes an int argument, where the int represents a non-seekable system file descriptor

Performing I/O with FileReaders and FileWriters¶

FileReaders have a variety of read methods and fileWriters have a variety of write methods. The most common variety of these are generic methods that can read or write values of any type. For non-primitive types, the relevant readThis or writeThis method is used to control the I/O formatting; see The readThis() and writeThis() Methods. These functions generally take any number of arguments and throw if there was an error:

fileWriter.write

fileWriter.writeln

FormattedIO.fileWriter.writef (see also Formatted I/O)

fileReader.read

fileReader.readln

FormattedIO.fileReader.readf (see also Formatted I/O)

The fileWriter type also has the following methods for executing write operations with more specific types. These methods can provide finer control over the fileWriter’s behavior as well as some performance advantages over the generic write methods:

fileWriter.writeBits

fileWriter.writeCodepoint

fileWriter.writeByte

fileWriter.writeString

fileWriter.writeBytes

fileWriter.writeBinary

The fileReader type has similar methods for executing read operations with more specific types, where the goal of these methods is also to provide finer control over the fileReader’s behavior and the potential for performance advantages:

fileReader.readBits

fileReader.readCodepoint

fileReader.readByte

fileReader.readString

fileReader.readBytes

fileReader.readBinary

Additionally, the fileReader has the following methods which read arbitrary amounts of data from the file until some stop condition is met. These methods generally have multiple overloads for reading into values of different types:

fileReader.readLine

fileReader.lines

fileReader.readThrough

fileReader.readTo

fileReader.readAll

Sometimes it’s important to flush the buffer in a fileWriter - to do that, use the fileWriter.flush() method. Flushing the buffer will make all writes available to other applications or other views of the file (e.g., it will call the OS call pwrite()). It is also possible to close a fileWriter, which will implicitly flush it and release any buffer memory used by the fileWriter. Note that if you need to ensure that data from a fileWriter is on disk, you’ll have to call fileWriter.flush or fileWriter.close and then file.fsync on the related file.

Functions for Closing FileReaders and FileWriters¶

A fileReader or fileWriter must be closed in order to free the resources allocated for it, to ensure that data written to it is visible to other fileReaders, or to allow the associated file to be closed.

See fileReader.close and fileWriter.close.

It is an error to perform any I/O operations on a fileReader or fileWriter that has been closed. It is an error to close a file when it has fileReaders and/or fileWriters that have not been closed.

Files, fileReaders and fileWriters are reference counted. Each file, fileReader and fileWriter is closed automatically when no references to it remain. For example, if a local variable is the only reference to a fileReader, the fileReader will be closed when that variable goes out of scope. Programs may also close a file, fileReader or fileWriter explicitly.

The `stdin` fileReader, and `stdout` and `stderr` fileWriters¶

Chapel provides the predefined fileReader stdin, and the predefined fileWriters stdout, and stderr to access the corresponding operating system streams standard input, standard output, and standard error.

stdin supports reading; stdout and stderr support writing.

All three are safe to use concurrently. Their types’ kind argument is dynamic.

Error Handling¶

Most I/O routines throw a SystemError, which can be handled appropriately with try and catch (see the documentation for more detail).

Additionally, some subclasses of Error are commonly used within the I/O implementation. These are:

OS.EofError - the end of file was reached

OS.UnexpectedEofError - a read or write only returned part of the requested data

OS.BadFormatError - data read did not adhere to the requested format

System Errors:

For other error cases, a general SystemError is typically thrown. These errors are often produced by less predictable circumstances that are more challenging to recover from. For example, a fileReader could run out of memory when attempting to allocate more buffer space.

As such, it is typically recommended that more specific errors are caught and recovered from separately from a SystemError. See the following example:

const r = openReader("test.txt");

try {
  var i = r.read(int);
  // ...
} catch e: EofError {
  writeln("r is at EOF");
  // we're done reading

} catch e: UnexpectedEofError {
  writeln("unable to read an 'int'");
  // try to read something else? ...

} catch e: SystemError {
  writeln("system error in IO implementation: ", e);
  // try to recover from the error? ...

} catch e: Error {
  writeln("something else went wrong...");
}

Ensuring Successful I/O¶

It is possible - in some situations - for I/O to fail without returning an error. In cases where a programmer wants to be sure that there was no error writing the data to disk, it is important to call file.fsync to make sure that data has arrived on disk without an error. Many errors can be reported with a typical operation, but some errors can only be reported by the system during file.close or even file.fsync.

When a file (or fileWriter) is closed, data written to that file will be written to disk eventually by the operating system. If an application needs to be sure that the data is immediately written to persistent storage, it should use file.fsync prior to closing the file.

Correspondence with C I/O¶

It is not possible to seek, read, or write to a file directly; fileReaders and/or fileWriters must be created and used.

fileWriter.flush in Chapel has the same conceptual meaning as fflush() in C. However, fflush() is not necessarily called in fileWriter.flush(), unlike fsync(), which is actually called by file.fsync() in Chapel.

IO Functions and Types¶

enum ioMode { r = 1, cw = 2, rw = 3, cwr = 4 }¶

The ioMode type is an enum. When used as arguments when opening files, its constants have the same meaning as the following strings passed to fopen() in C:

`ioMode`	`fopen()` argument	Description
`ioMode.r`	`"r"`	open an existing file for reading.
`ioMode.rw`	`"r+"`	open an existing file for reading and writing.
`ioMode.cw`	`"w"`	create a new file for writing. If the file already exists, its contents are truncated.
`ioMode.cwr`	`"w+"`	same as `ioMode.cw`, but reading from the file is also allowed.

However, open() in Chapel does not necessarily invoke fopen() in C.

enum iomode { r = 1, cw = 2, rw = 3, cwr = 4 }¶: Warning

enum iomode is deprecated - please use ioMode instead

enum iokind { dynamic = 0, native = 1, big = 2, little = 3 }¶

The iokind type is an enum. When used as arguments to the fileReader or fileWriter type, its constants have the following meaning:

iokind.dynamic means that the applicable I/O style has full effect and as a result the kind varies at runtime.
iokind.native means binary I/O in native byte order (similar to iokind.big but with the byte order that is native to the target platform).
iokind.big means binary I/O with big-endian byte order is performed when writing basic types to the fileWriter or reading basic types from the fileReader.
iokind.little means binary I/O with little-endian byte order (similar to iokind.big but with little-endian byte order).

In the case of iokind.big, iokind.little, and iokind.native the applicable iostyle is consulted when writing/reading strings, but not for other basic types.

There are synonyms available for these values:

iodynamic = iokind.dynamic
ionative = iokind.native
iobig = iokind.big
iolittle = iokind.little

param iodynamic = iokind.dynamic¶: A synonym for iokind.dynamic; see iokind

param ionative = iokind.native¶: A synonym for iokind.native; see iokind

param iobig = iokind.big¶: A synonym for iokind.big; see iokind

param iolittle = iokind.little¶: A synonym for iokind.little; see iokind

enum ioendian { native = 0, big = 1, little = 2 }¶

The ioendian type is an enum. When used as an argument to the fileReader or fileWriter methods, its constants have the following meanings:

ioendian.big means binary I/O is performed in big-endian byte order.
ioendian.little means binary I/O is performed in little-endian byte order.
ioendian.native means binary I/O is performed in the byte order that is native to the target platform.

enum iostringstyle { len1b_data = -1, len2b_data = -2, len4b_data = -4, len8b_data = -8, lenVb_data = -10, data_toeof = -0xff00, data_null = -0x0100 }¶

This enum contains values used to control binary I/O with strings via the str_style field in iostyle.

iostringstyle.len1b_data indicates a string format of 1 byte of length followed by length bytes of string data.
iostringstyle.len2b_data indicates a string format of 2 bytes of length followed by length bytes of string data.
iostringstyle.len4b_data indicates a string format of 4 bytes of length followed by length bytes of string data.
iostringstyle.len8b_data indicates a string format of 8 bytes of length followed by length bytes of string data.
iostringstyle.lenVb_data indicates a string format of a variable number of bytes of length, encoded with high-bit meaning more bytes of length follow, and where the 7-bits of length from each byte store the 7-bit portions of the length in order from least-significant to most-significant. This way of encoding a variable-byte length matches Google Protocol Buffers.
iostringstyle.data_toeof indicates a string format that contains only the string data without any length or terminator. When reading, this format will read a string until the end of the file is reached.
iostringstyle.data_null indicates a string that is terminated by a zero byte. It can be combined with other numeric values to indicate a string terminated by a particular byte. For example, to indicate a string terminated by $ (which in ASCII has byte value 0x24), one would use the value iostringstyle.data_null|0x24.
A positive and nonzero value indicates that a string of exactly that many bytes should be read or written.

Warning

iostringstyle is unstable and will eventually be replaced

enum iostringformat { word = 0, basic = 1, chpl = 2, json = 3, toend = 4, toeof = 5 }¶

This enum contains values used to control text I/O with strings via the string_format field in iostyle.

iostringformat.word means string is as-is; reading reads until whitespace. This is the default.

iostringformat.basic means only escape string_end and \ with \

iostringformat.chpl means escape string_end \ ' " \n with \ and nonprinting characters c = 0xXY with \xXY

iostringformat.json means escape string_end " and \ with \, and nonprinting characters c = \uABCD

iostringformat.toend means string is as-is; reading reads until string_end

iostringformat.toeof means string is as-is; reading reads until end of file

Warning

iostringformat is unstable and will eventually be replaced

proc stringStyleTerminated(terminator: uint(8))¶

This method returns the appropriate iostyle str_style value to indicate a string format where strings are terminated by a particular byte.

Arguments: terminator – a byte value that the strings will be terminated by
Returns: a value that indicates a string format where strings are terminated by the terminator byte. This value is appropriate to store in iostyle.str_style.

Warning

stringStyleTerminated is unstable because it supports the unstable type ‘iostyle’

proc stringStyleNullTerminated()¶: This method returns the appropriate iostyle str_style value to indicate a string format where strings are terminated by a zero byte.

Warning

stringStyleNullTerminated is unstable because it supports the unstable type ‘iostyle’

proc stringStyleWithLength(lengthBytes: int) throws¶

Return the appropriate iostyle str_style value to indicate a string format where string data is preceded by a lengthBytes of length. Only lengths of 1, 2, 4, or 8 are supported. When lengthBytes is 0, the returned value indicates variable-byte length.

Throws: SystemError – Thrown for an unsupported value of lengthBytes.

Warning

stringStyleWithLength is unstable because it supports the unstable type ‘iostyle’

type iostyle = iostyleInternal¶: Warning

iostyle is unstable, a new way of controlling fileReader and fileWriter output is planned

proc defaultIOStyle(): iostyle¶

Returns: the default I/O style. See iostyle and I/O Styles

Warning

defaultIOStyle is unstable due to returning an unstable type

record ioHintSet¶

A value of the ioHintSet type defines a set of hints to provide information about the operations that a file, fileReader or fileWriter will perform. These hints may be used by the implementation to select optimized versions of the I/O operations.

Most hints have POSIX equivalents associated with posix_fadvise() and posix_madvise().

This example depicts how an ioHintSet might be used.

use IO;

// define a set of hints using a union operation
var hints = ioHintSet.sequential | ioHintSet.prefetch;

// open a file using the hints
var f: file;
try! {
  f = open("path/to/my/file.txt", ioMode.r, hints=hints);
}

proc type empty¶: Defines an empty set, which provides no hints. Corresponds to ‘POSIX_*_NORMAL’.

proc type sequential¶: Suggests that the file will be accessed sequentially. Corresponds to ‘POSIX_*_SEQUENTIAL’

proc type random¶: Suggests that the file will be accessed randomly. Corresponds to ‘POSIX_*_RANDOM’.

proc type prefetch¶: Suggests that the runtime/OS should immediately begin prefetching the file contents. Corresponds to ‘POSIX_*_WILLNEED’.

proc type mmap(useMmap = true)¶

Suggests whether or not ‘mmap’ should be used to access the file contents.

when useMmap is true, suggests that ‘mmap’ should be used

when useMmap is false, suggests that ‘mmap’ should not be used and ‘pread’/’pwrite’ should be used instead

proc type noMmap¶: Suggests that ‘mmap’ should not be used to access the file contents. Instead, pread/pwrite are used.

Warning

ioHintSet.noMmap is deprecated; please use ioHintSet.mmap(false) instead

operator ioHintSet.|(lhs: ioHintSet, rhs: ioHintSet): Compute the union of two hint sets

operator ioHintSet.&(lhs: ioHintSet, rhs: ioHintSet): Compute the intersection of two hint sets

operator ioHintSet.==(lhs: ioHintSet, rhs: ioHintSet)¶: Compare two hint sets for equality

operator ioHintSet.!=(lhs: ioHintSet, rhs: ioHintSet)¶: Compare two hint sets for inequality

record file¶

The file type is implementation-defined. A value of the file type refers to the state that is used by the implementation to identify and interact with the OS file.

When a file formal argument has default intent, the actual is passed by const ref to the formal upon a function call, and the formal cannot be assigned within the function.

The default value of the file type does not represent any OS file. It is illegal to perform any I/O operations on the default value.

proc file.init(fp: ?t, hints = ioHintSet.empty, style: iostyle, own = false) throws¶: Warning

initializing a file with a style argument is unstable

proc file.init(fp: ?t, hints = ioHintSet.empty, own = false) throws

Create a Chapel file that wraps around an open C file. A pointer to a C FILE object can be obtained via Chapel’s C Interoperability functionality.

Note

This is an alternative way to create a file. The main way to do so is via the open function.

Once the Chapel file is created, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to perform I/O operations on the C file.

Note

The resulting file value should only be used with one fileReader or fileWriter at a time. The I/O system will ignore the offsets when reading or writing to a file opened using this initializer.

Arguments

fp – a pointer to a C FILE. See c_FILE.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.
own – set to indicate if the c_FILE provided should be cleaned up when the file is closed. Defaults to false

Throws

SystemError – Thrown if the C file could not be retrieved.

proc file.init(fileDescriptor: int, hints = ioHintSet.empty, style: iostyle, own = false) throws: Warning

initializing a file with a style argument is unstable

proc file.init(fileDescriptor: int, hints = ioHintSet.empty, own = false) throws

Create a Chapel file that works with a system file descriptor. Note that once the file is open, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to actually perform I/O operations

Note

This is an alternative way to create a file. The main way to do so is via the open function.

The system file descriptor will be closed when the Chapel file is closed.

Note

This function can be used to create Chapel files that refer to system file descriptors that do not support the seek functionality. For example, file descriptors that represent pipes or open socket connections have this property. In that case, the resulting file value should only be used with one fileReader or fileWriter at a time. The I/O system will ignore the fileReader offsets when reading (or the fileWriter offsets when writing) to files backed by non-seekable file descriptors.

Arguments

fileDescriptor – a system file descriptor.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.
own – set to indicate if the fileDescriptor provided should be cleaned up when the file is closed. Defaults to false

Throws

SystemError – Thrown if the file descriptor could not be retrieved.

proc file.check() throws¶

Throw an error if this is not a valid representation of an OS file.

Throws: SystemError – Indicates that this does not represent an OS file.

Warning

‘file.check()’ is deprecated, please use file.isOpen instead

proc file.isOpen(): bool¶: Indicates if the file is currently open. Will return false for both closed and invalid files

proc file.close() throws¶

Close a file.

In order to free the resources allocated for a file, it must be closed using this method.

Closing a file does not guarantee immediate persistence of the performed updates, if any. In cases where immediate persistence is important, file.fsync should be used for that purpose prior to closing the file. In particular, even though closing the file might complete without errors, the data written might not persist in the event of a severe error like running out of storage space or power loss. See also Ensuring Successful I/O.

Files are automatically closed when the file variable goes out of scope and all fileReaders and fileWriters using that file are closed. Programs may also explicitly close a file using this method.

It is an error to perform any I/O operations on a file that has been closed. It is an error to close a file when it has fileReaders and/or fileWriters that have not been closed.

Throws: SystemError – Thrown if the file could not be closed.

proc file.fsync() throws¶

Sync a file to disk.

Commits file data to the device associated with this file. Data written to the file by a fileWriter will only be guaranteed committed if the fileWriter has been closed or flushed.

This function will typically call the fsync system call.

Throws: SystemError – Thrown if the file could not be synced.

config param filePathAbsolute = false¶

A compile-time parameter to control the behavior of file.path

When ‘false’, the deprecated behavior is used (i.e., return the shortest of the relative path and the absolute path)

When ‘true’, the new behavior is used (i.e., always return the absolute path)

proc file.path: string throws¶: Warning

The variant of file.path that can return a relative path is deprecated; please compile with -sfilePathAbsolute=true to use the strictly absolute variant

proc file.path: string throws

Get the absolute path to an open file.

Note that not all files have a path (e.g. files opened with openMemFile), and that this function may not work on all operating systems.

The function Path.realPath is an alternative way to get the path to a file.

Returns: the absolute path to the file
Return type: string
Throws: SystemError – Thrown if the path could not be retrieved.

proc file.size: int throws¶

Get the current size of an open file. Note that the size can always change if other fileWriters, tasks or programs are writing to the file.

Returns: the current file size
Throws: SystemError – Thrown if the size could not be retrieved.

proc open(path: string, mode: iomode, hints = ioHintSet.empty, style: iostyle): file throws¶: Warning

open with an iomode argument is deprecated - please use ioMode

proc open(path: string, mode: ioMode, hints = ioHintSet.empty, style: iostyle): file throws: Warning

open with a style argument is unstable

proc open(path: string, mode: ioMode, hints = ioHintSet.empty): file throws

Open a file on a filesystem. Note that once the file is open, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to actually perform I/O operations

Arguments

path – which file to open (for example, “some/file.txt”).
mode – specify whether to open the file for reading or writing and whether or not to create the file if it doesn’t exist. See ioMode.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file to the requested resource.

Throws

FileNotFoundError – Thrown if part of the provided path did not exist
PermissionError – Thrown if part of the provided path had inappropriate permissions
NotADirectoryError – Thrown if part of the provided path was expected to be a directory but was not
SystemError – Thrown if the file could not be opened.

proc open(path: string, mode: iomode, hints = ioHintSet.empty): file throws: Warning

open with an iomode argument is deprecated - please use ioMode

proc openfd(fd: c_int, hints = ioHintSet.empty, style: iostyle): file throws¶: Warning

openfd is deprecated, please use the file initializer with a ‘c_int’ argument instead

proc openfd(fd: c_int, hints = ioHintSet.empty): file throws

Create a Chapel file that works with a system file descriptor. Note that once the file is open, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to actually perform I/O operations

The system file descriptor will be closed when the Chapel file is closed.

Note

This function can be used to create Chapel files that refer to system file descriptors that do not support the seek functionality. For example, file descriptors that represent pipes or open socket connections have this property. In that case, the resulting file value should only be used with one fileReader or fileWriter at a time. The I/O system will ignore the fileReader or fileWriter offsets when reading or writing to files backed by non-seekable file descriptors.

Arguments

fd – a system file descriptor.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file using the specified file descriptor.

Throws

SystemError – Thrown if the file descriptor could not be retrieved.

Warning

openfd is deprecated, please use the file initializer with a ‘c_int’ argument instead

proc openfp(fp, hints = ioHintSet.empty, style: iostyle): file throws¶: Warning

openfp is deprecated, please use the file initializer with a ‘c_FILE’ argument instead

proc openfp(fp, hints = ioHintSet.empty): file throws

Create a Chapel file that wraps around an open C file. A pointer to a C FILE object can be obtained via Chapel’s C Interoperability functionality.

Once the Chapel file is created, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to perform I/O operations on the C file.

Note

The resulting file value should only be used with one fileReader or fileWriter at a time. The I/O system will ignore the fileReader or fileWriter offsets when reading or writing to a file opened with openfp.

Arguments

fp – a pointer to a C FILE. See c_FILE.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file corresponding to the C file.

Throws

SystemError – Thrown if the C file could not be retrieved.

Warning

openfp is deprecated, please use the file initializer with a ‘c_FILE’ argument instead

proc openfp(fp: _file, hints = ioHintSet.empty): file throws: Warning

‘_file’ is deprecated; use the file initializer that takes a ‘c_FILE’ instead

proc openTempFile(hints = ioHintSet.empty, style: iostyle): file throws¶: Warning

openTempFile with a style argument is unstable

proc opentmp(hints = ioHintSet.empty, style: iostyle): file throws¶: Warning

opentmp is deprecated, please use openTempFile instead

proc openTempFile(hints = ioHintSet.empty): file throws

Open a temporary file. Note that once the file is open, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to actually perform I/O operations.

The temporary file will be created in an OS-dependent temporary directory, for example “/tmp” is the typical location. The temporary file will be deleted upon closing.

Temporary files are opened with ioMode ioMode.cwr; that is, a new file is created that supports both writing and reading. When possible, it may be opened using OS support for temporary files in order to make sure that a new file is created only for use by the current application.

Arguments: hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.
Returns: an open temporary file.
Throws: SystemError – Thrown if the temporary file could not be opened.

proc opentmp(hints = ioHintSet.empty): file throws: Warning

opentmp is deprecated, please use openTempFile instead

proc openmem(style: iostyle): file throws¶: Warning

openmem is deprecated - please use openMemFile instead

proc openmem(): file throws: Warning

openmem is deprecated - please use openMemFile instead

proc openMemFile(style: iostyle): file throws¶: Warning

openMemFile with a style argument is unstable

proc openMemFile(): file throws

Open a file that is backed by a buffer in memory that will not persist when the file is closed. Note that once the file is open, you will need to use a file.reader to create a fileReader or file.writer to create a fileWriter to actually perform I/O operations.

The resulting file supports both reading and writing.

Returns: an open memory file.
Throws: SystemError – Thrown if the memory buffered file could not be opened.

config param useIOSerializers = false¶

record fileReader¶

A fileReader supports sequential reading from an underlying file object. It can buffer data. Read operations on it might return old data.

The fileReader type is implementation-defined. A value of the fileReader type refers to the state that is used to implement the reading operations.

When a fileReader formal argument has default intent, the actual is passed by const ref to the formal upon a function call, and the formal cannot be assigned within the function.

The default value of the fileReader type is not associated with any file, and so cannot be used to perform I/O.

The fileReader type is generic.

param kind: iokind¶: kind is an enum iokind that allows narrowing this fileReader’s I/O style for more efficient binary I/O.

param locking: bool¶: locking is a boolean indicating whether it is safe to use this fileReader concurrently (when true).

type deserializerType = defaultSerializeType(false)¶: deserializerType indicates the type of the deserializer that this fileReader will use to deserialize data.

proc fileReader.writing param: bool¶: Returns a bool indicating whether the fileReader is used for writing. It is always false

Warning

‘fileReader.writing’ is deprecated and will be removed in a future release

proc fileReader.deserializer ref: deserializerType¶: Return a mutable reference to this fileReader’s deserializer.

record fileWriter¶

A fileWriter supports sequential writing to an underlying file object. A fileWriter can buffer data. Write operations might not have an immediate effect. Use fileWriter.flush to control this buffering.

The fileWriter type is implementation-defined. A value of the fileWriter type refers to the state that is used to implement the writing operations.

When a fileWriter formal argument has default intent, the actual is passed by const ref to the formal upon a function call, and the formal cannot be assigned within the function.

The default value of the fileWriter type is not associated with any file, and so cannot be used to perform I/O.

The fileWriter type is generic.

param kind: iokind¶: kind is an enum iokind that allows narrowing this fileWriter’s I/O style for more efficient binary I/O.

param locking: bool¶: locking is a boolean indicating whether it is safe to use this fileWriter concurrently (when true).

type serializerType = defaultSerializeType(true)¶: serializerType indicates the type of the serializer that this fileWriter will use to serialize data.

proc fileWriter.writing param: bool¶: Returns a bool indicating whether the fileWriter is used for writing. It is always true

Warning

‘fileWriter.writing’ is deprecated and will be removed in a future release

proc fileWriter.serializer ref: serializerType¶: Return a mutable reference to this fileWriter’s serializer.

record DefaultSerializer¶

The default serializer used by fileWriter.

Implements the ‘serializeValue’ method which is called by a fileWriter to produce a serialized representation of a value.

Serializers can choose to invoke a user-defined method, ‘serialize’, on class and record types. The ‘serialize’ method should match the formal names, intents, and types of the following signature:

proc MyType.serialize(writer: fileWriter(?), ref serializer: writer.serializerType) throws

The compiler is expected to generate a default implementation of ‘serialize’ methods for records and classes.

proc serializeValue(writer: fileWriter, const val: ?t): void throws¶

record DefaultDeserializer¶

The default deserializer used by fileReader.

Implements the ‘deserializeType’ and ‘deserializeValue’ methods which are called by a fileReader to deserialize a serialized representation of a type or value.

Deserializers may choose to invoke certain user-defined methods or initializers on class and record types. When deserializing a type, deserializers should first attempt to invoke an initializer on the type:

proc MyType.init(reader: fileReader(?), ref deserializer: reader.deserializerType) throws

If this initializer is not available or cannot be resolved, the deserializer may then attempt to invoke a user-defined type method ‘deserializeFrom’ as a factory method that will produce the type:

proc type MyType.deserializeFrom(reader: fileReader(?)
ref deserializer: reader.deserializerType) : MyType throws

If neither of these methods are available, the deserializer may attempt to default-initialize the desired type and invoke the value-reading form of deserialization. If the value-reading form of deserialization cannot be resolved, then a compiler error may be issued.

The value-reading form of deserialization may attempt to invoke a user-defined ‘deserialize’ method on classes and records:

proc MyType.deserialize(reader: fileReader(?), ref deserializer: reader.deserializerType) throws

If this method is unavailable, the value-reading form of deserialization may attempt to invoke the type-reading form of deserialization, and assign the result into the original value.

The compiler is expected to generate a default implementation of ‘deserialize’ methods and deserializing initializers for records and classes.

proc deserializeType(reader: fileReader, type readType): readType throws¶

proc deserializeValue(reader: fileReader, ref val: ?readType): void throws¶

type ioChar = _internalIoChar¶: Represents a Unicode codepoint. I/O routines (such as fileReader.read and fileWriter.write) can use arguments of this type in order to read or write a single Unicode codepoint.

Warning

ioChar type is deprecated - please use fileReader.readCodepoint and fileWriter.writeCodepoint instead

record ioNewline¶

Represents a newline character or character sequence (ie \n). I/O routines (such as fileReader.read and fileWriter.write) can use arguments of this type in order to read or write a newline. This is different from \n because an ioNewline always produces an actual newline, but in some cases writing \n will produce an escaped string (such as "\n").

When reading an ioNewline, read routines will skip any character sequence (including, e.g., letters and numbers) to get to the newline character unless skipWhitespaceOnly is set to true.

var skipWhitespaceOnly: bool = false¶: Normally, we will skip anything at all to get to a \n, but if skipWhitespaceOnly is set, it will be an error if we run into non-space characters other than \n.

record ioLiteral¶

Used to represent a constant string we want to read or write.

When writing, the ioLiteral is output without any quoting or escaping.

When reading, the ioLiteral must be matched exactly - or else the read call will return an error for incorrectly formatted input

var val: string¶: The value of the literal

var ignoreWhiteSpace: bool = true¶: Should read operations using this literal ignore and consume whitespace before the literal?

proc writeThis(f) throws¶

type ioBits = _internalIoBits¶: Warning

ioBits type is deprecated - please use fileReader.readBits and fileWriter.writeBits instead

proc fileReader.lock() throws¶

Acquire a fileReader’s lock.

Throws: SystemError – Thrown if the lock could not be acquired.

proc fileWriter.lock() throws¶

Acquire a fileWriter’s lock.

Throws: SystemError – Thrown if the lock could not be acquired.

proc fileReader.unlock()¶: Release a fileReader’s lock.

proc fileWriter.unlock()¶: Release a fileWriter’s lock.

config param fileOffsetWithoutLocking = false¶

A compile-time parameter to control the behavior of fileReader.offset and fileWriter.offset when fileReader.locking or fileWriter.locking is true.

When ‘false’, the deprecated behavior is used (i.e., the method acquires a lock internally before getting the offset)

When ‘true’, the new behavior is used (i.e., no lock is automatically acquired)

proc fileReader.offset(): int(64)¶

Return the current offset of a fileReader.

The fileReader will call fileReader.lock before getting the offset and call fileReader.unlock after.

Returns: the current offset of the fileReader

Warning

The variant of fileReader.offset that automatically acquires a lock before getting the offset is deprecated; please compile with -sfileOffsetWithoutLocking=true and wrap fileReader.offset with the appropriate locking calls where necessary to opt in to the new behavior

proc fileReader.offset(): int(64)

Return the current offset of a fileReader.

If the fileReader can be used by multiple tasks, take care when doing operations that rely on the fileReader’s current offset. To prevent race conditions, lock the fileReader with fileReader.lock before calling fileReader.offset, then unlock it afterwards with fileReader.unlock.

Returns: the current offset of the fileReader

proc fileWriter.offset(): int(64)¶

Return the current offset of a fileWriter.

The fileWriter will call fileWriter.lock before getting the offset and call fileWriter.unlock after.

Returns: the current offset of the fileWriter

Warning

The variant of fileWriter.offset that automatically acquires a lock before getting the offset is deprecated; please compile with -sfileOffsetWithoutLocking=true and wrap fileWriter.offset with the appropriate locking calls where necessary to opt in to the new behavior

proc fileWriter.offset(): int(64)

Return the current offset of a fileWriter.

If the fileWriter can be used by multiple tasks, take care when doing operations that rely on the fileWriter’s current offset. To prevent race conditions, lock the fileWriter with fileWriter.lock before calling fileWriter.offset, then unlock it afterwards with fileWriter.unlock.

Returns: the current offset of the fileWriter

proc fileReader.advance(amount: int(64)) throws¶

Move a fileReader offset forward.

This function will consume the next amount bytes. If EOF is reached, the fileReader offset may be left at the EOF.

Throws

EofError – If EOF is reached before the requested number of bytes can be consumed.
SystemError – For other failures, for which fileReader offset is not moved.

proc fileWriter.advance(amount: int(64)) throws¶

Move a fileWriter offset forward.

This function will write amount zeros - or some other data if it is stored in the fileWriter’s buffer, for example with fileWriter.mark and fileWriter.revert.

Throws

EofError – If EOF is reached before the offset can be advanced by the requested number of bytes.
SystemError – For other failures, for which fileWriter offset is not moved.

proc fileReader.advancePastByte(byte: uint(8)) throws¶

Reads until byte is found and then leaves the fileReader offset just after it.

Throws

UnexpectedEofError – Throws if the requested byte could not be found. The fileReader offset is left at EOF.
SystemError – Thrown if data could not be read from the file.

Warning

advancePastByte is deprecated; please use advanceThrough instead

proc fileReader.advanceThrough(separator: ?t) throws¶

Read until a separator is found, leaving the fileReader offset just after it.

If the separator cannot be found, the fileReader offset is left at EOF and an UnexpectedEofError is thrown.

Note

If a single-byte string or bytes is passed to the separator argument, a faster implementation is used.

Arguments

separator – The separator to match with. Must be a string or bytes.

Throws

EofError – Thrown if the fileReader offset was already at EOF.
UnexpectedEofError – Thrown if the requested separator could not be found.
SystemError – Thrown if data could not be read from the file.

proc fileReader.advanceTo(separator: ?t) throws¶

Read until a separator is found, leaving the fileReader offset just before it.

If the separator cannot be found, the fileReader offset is left at EOF and an UnexpectedEofError is thrown.

Note

If a single-byte string or bytes is passed to the separator argument, a faster implementation is used.

Arguments

separator – The separator to match with. Must be a string or bytes.

Throws

EofError – Thrown if the fileReader offset is already at EOF.
UnexpectedEofError – Thrown if the requested separator could not be found.
SystemError – Thrown if data could not be read from the fileReader.

proc fileReader.mark() throws¶

Mark a fileReader - that is, save the current offset of the fileReader on its mark stack.

The mark stack stores several fileReader offsets. For any fileReader offset that is between the minimum and maximum value in the mark stack, I/O operations on the fileReader will keep that region of the file buffered in memory so that those operations can be undone. As a result, it is possible to perform I/O transactions on a fileReader. The basic steps for an I/O transaction are:

mark the current offset with fileReader.mark

do something speculative (e.g. try to read 200 bytes of anything followed by a ‘B’)

if the speculative operation was successful, commit the changes by calling fileReader.commit

if the speculative operation was not successful, go back to the mark by calling fileReader.revert. Subsequent I/O operations will work as though nothing happened.

If a fileReader has locking==true, fileReader.mark should be called only once the fileReader has been locked with fileReader.lock. The fileReader should not be unlocked with fileReader.unlock until after the mark has been committed with fileReader.commit or reverted with fileReader.revert.

Note

Note that it is possible to request an entire file be buffered in memory using this feature, for example by marking at offset=0 and then advancing to the end of the file. It is important to be aware of these memory space requirements.

Returns: The offset that was marked
Throws: SystemError – if marking the fileReader failed

proc fileWriter.mark() throws¶

Mark a fileWriter - that is, save the current offset of the fileWriter on its mark stack.

The mark stack stores several fileWriter offsets. For any fileWriter offset that is between the minimum and maximum value in the mark stack, I/O operations on the fileWriter will keep that region of the file buffered in memory so that those operations can be undone. As a result, it is possible to perform I/O transactions on a fileWriter. The basic steps for an I/O transaction are:

mark the current offset with fileWriter.mark

do something speculative (e.g. try to write 200 bytes of anything followed by a ‘B’)

if the speculative operation was successful, commit the changes by calling fileWriter.commit

if the speculative operation was not successful, go back to the mark by calling fileWriter.revert. Subsequent I/O operations will work as though nothing happened.

If a fileWriter has locking==true, fileWriter.mark should be called only once the fileWriter has been locked with fileWriter.lock. The fileWriter should not be unlocked with fileWriter.unlock until after the mark has been committed with fileWriter.commit or reverted with fileWriter.revert.

Note

Note that it is possible to request an entire file be buffered in memory using this feature, for example by marking at offset=0 and then advancing to the end of the file. It is important to be aware of these memory space requirements.

Returns: The offset that was marked
Throws: SystemError – if marking the fileWriter failed

proc fileReader.revert()¶

Abort an I/O transaction. See fileReader.mark. This function will pop the last element from the mark stack and then leave the previous fileReader offset unchanged.

This function should only be called on a fileReader that has already been marked. If called on a fileReader with locking==true, the fileReader should have already been locked.

proc fileWriter.revert()¶

Abort an I/O transaction. See fileWriter.mark. This function will pop the last element from the mark stack and then leave the previous fileWriter offset unchanged.

This function should only be called on a fileWriter that has already been marked. If called on a fileWriter with locking==true, the fileWriter should have already been locked.

proc fileReader.commit()¶

Commit an I/O transaction. See fileReader.mark. This function will pop the last element from the mark stack and then set the fileReader offset to the popped offset.

This function should only be called on a fileReader that has already been marked. If called on a fileReader with locking==true, the fileReader should have already been locked.

proc fileWriter.commit()¶

Commit an I/O transaction. See fileWriter.mark. This function will pop the last element from the mark stack and then set the fileWriter offset to the popped offset.

This function should only be called on a fileWriter that has already been marked. If called on a fileWriter with locking==true, the fileWriter should have already been locked.

config param useNewSeekRegionBounds = false¶: Used to control the behavior of the region argument for fileReader.seek or fileWriter.seek. When set to true, the region argument will fully specify the bounds of the seek. When set to false, the region argument will exclude the high bound. Defaults to false, the original behavior.

proc fileReader.seek(region: range(?)) throws¶

Reset a fileReader to point to a new part of a file. This function allows one to jump to a different part of a file without creating a new fileReader. It can only be called on a fileReader with locking==false.

The region specified must have a lower bound, but does not need to have a high bound for correctness. Specifying the high bound might be an important performance optimization since the fileReader will not try to read data outside of the region.

This function will, in most cases, discard the fileReader’s buffer.

Arguments: region – the new region, measured in bytes and counting from 0

Warning

The region argument will ignore any specified stride other than 1.

Throws

SystemError – if seeking failed. Possible reasons include that the file is not seekable, or that the fileReader is marked.
IllegalArgumentError – if region argument did not have a lower bound

proc fileWriter.seek(region: range(?)) throws¶

Reset a fileWriter to point to a new part of a file. This function allows one to jump to a different part of a file without creating a new fileWriter. It can only be called on a fileWriter with locking==false.

The region specified must have a lower bound, but does not need to have a high bound for correctness. Specifying the high bound might be an important performance optimization since the fileWriter will not try to read data outside of the region.

This function will, in most cases, discard the fileWriter’s buffer. The data will be saved to the file before discarding.

Arguments: region – the new region, measured in bytes and counting from 0

Warning

The region argument will ignore any specified stride other than 1.

Throws

SystemError – if seeking failed. Possible reasons include that the file is not seekable, or that the fileWriter is marked.
IllegalArgumentError – if region argument did not have a lower bound

proc fileReader.seek(region: range(?)) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewSeekRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc fileWriter.seek(region: range(?)) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewSeekRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc fileReader._offset(): int(64)¶: For a fileReader locked with fileReader.lock, return the offset of that fileReader.

Warning

fileReader._offset is deprecated - please use fileReader.offset instead

proc fileWriter._offset(): int(64)¶: For a fileWriter locked with fileWriter.lock, return the offset of that fileWriter.

Warning

fileWriter._offset is deprecated - please use fileWriter.offset instead

proc fileReader._mark() throws¶

This routine is identical to fileReader.mark except that it can be called on fileReaders with locking==true and should be called only once the fileReader has been locked with fileReader.lock. The fileReader should not be unlocked with fileReader.unlock until after the mark has been committed with fileReader._commit or reverted with fileReader._revert.

See fileReader.mark for details other than the locking discipline.

Returns: The offset that was marked
Throws: SystemError – if marking the fileReader failed

Warning

fileReader._mark is deprecated - please use fileReader.mark instead

proc fileWriter._mark() throws¶

This routine is identical to fileWriter.mark except that it can be called on fileWriters with locking==true and should be called only once the fileWriter has been locked with fileWriter.lock. The fileWriter should not be unlocked with fileWriter.unlock until after the mark has been committed with fileWriter._commit or reverted with fileWriter._revert.

See fileWriter.mark for details other than the locking discipline.

Returns: The offset that was marked
Throws: SystemError – if marking the fileWriter failed

Warning

fileWriter._mark is deprecated - please use fileWriter.mark instead

proc fileReader._revert()¶: Abort an I/O transaction. See fileReader._mark. This function will pop the last element from the mark stack and then leave the previous fileReader offset unchanged. This function should only be called on a fileReader that has already been locked and marked.

Warning

fileReader._revert is deprecated - please use fileReader.revert instead

proc fileWriter._revert()¶: Abort an I/O transaction. See fileWriter._mark. This function will pop the last element from the mark stack and then leave the previous fileWriter offset unchanged. This function should only be called on a fileWriter that has already been locked and marked.

Warning

fileWriter._revert is deprecated - please use fileWriter.revert instead

proc fileReader._commit()¶: Commit an I/O transaction. See fileReader._mark. This function will pop the last element from the mark stack and then set the fileReader offset to the popped offset. This function should only be called on a fileReader that has already been locked and marked.

Warning

fileReader._commit is deprecated - please use fileReader.commit instead

proc fileWriter._commit()¶: Commit an I/O transaction. See fileWriter._mark. This function will pop the last element from the mark stack and then set the fileWriter offset to the popped offset. This function should only be called on a fileWriter that has already been locked and marked.

Warning

fileWriter._commit is deprecated - please use fileWriter.commit instead

proc fileReader._style(): iostyle¶: Return the current style used by a fileReader. This function should only be called on a locked fileReader.

Warning

fileReader._style is unstable because it returns a type that is unstable

proc fileWriter._style(): iostyle¶: Return the current style used by a fileWriter. This function should only be called on a locked fileWriter.

Warning

fileWriter._style is unstable because it returns a type that is unstable

proc fileReader._set_style(style: iostyle)¶: Set the style associated with a fileReader. This function should only be called on a locked fileReader.

Warning

fileReader._set_style is unstable because its purpose involves an unstable type

proc fileWriter._set_style(style: iostyle)¶: Set the style associated with a fileWriter. This function should only be called on a locked fileWriter.

Warning

fileWriter._set_style is unstable because its purpose involves an unstable type

proc fileReader.readWriteThisFromLocale()¶: Return the locale on which an ongoing I/O was started with a fileReader. This method will return nilLocale unless it is called on a fileReader that is the formal argument to a readThis method.

Warning

‘readWriteThisFromLocale’ is unstable and may be removed or modified in a future release

proc fileWriter.readWriteThisFromLocale()¶: Return the locale on which an ongoing I/O was started with a fileWriter. This method will return nilLocale unless it is called on a fileWriter that is the formal argument to a writeThis method.

Warning

‘readWriteThisFromLocale’ is unstable and may be removed or modified in a future release

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileReader(kind, locking) throws¶: Warning

openreader is deprecated - please use openReader instead

proc openReader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileReader(kind, locking, defaultSerializeType(false)) throws¶: Warning

openReader with a style argument is unstable

config param useNewOpenReaderRegionBounds = false¶: Used to control the behavior of the region argument for openReader. When set to true, the region argument will fully specify the bounds of the fileReader. When set to false, the region argument will exclude the high bound. Defaults to false, the original behavior.

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): fileReader(kind, locking, defaultSerializeType(false)) throws

Open a file at a particular path and return a fileReader for it. This function is equivalent to calling open and then file.reader on the resulting file.

Arguments

path – which file to open (for example, “some/file.txt”).
kind – iokind compile-time argument to determine the corresponding parameter of the fileReader type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileReader should use locking; sets the corresponding parameter of the fileReader type. Defaults to true, but when safe, setting it to false can improve performance.
region – zero-based byte offset indicating where in the file the fileReader should start and stop reading. Defaults to 0.., meaning from the start of the file to no specified end point.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open fileReader to the requested resource.

Warning

The region argument will ignore any specified stride other than 1.

Throws

FileNotFoundError – Thrown if part of the provided path did not exist
PermissionError – Thrown if part of the provided path had inappropriate permissions
NotADirectoryError – Thrown if part of the provided path was expected to be a directory but was not
SystemError – Thrown if a fileReader could not be returned.
IllegalArgumentError – Thrown if trying to read explicitly prior to byte 0.

Warning

openreader is deprecated - please use openReader instead

proc openReader(path: string, param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty, in deserializer: ?dt = defaultSerializeVal(false)): fileReader(kind, locking, dt) throws

Open a file at a particular path and return a fileReader for it. This function is equivalent to calling open and then file.reader on the resulting file.

Arguments

path – which file to open (for example, “some/file.txt”).
kind – iokind compile-time argument to determine the corresponding parameter of the fileReader type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileReader should use locking; sets the corresponding parameter of the fileReader type. Defaults to true, but when safe, setting it to false can improve performance.
region – zero-based byte offset indicating where in the file the fileReader should start and stop reading. Defaults to 0.., meaning from the start of the file to no specified end point.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open fileReader to the requested resource.

Warning

The region argument will ignore any specified stride other than 1.

Throws

FileNotFoundError – Thrown if part of the provided path did not exist
PermissionError – Thrown if part of the provided path had inappropriate permissions
NotADirectoryError – Thrown if part of the provided path was expected to be a directory but was not
SystemError – Thrown if a fileReader could not be returned.
IllegalArgumentError – Thrown if trying to read explicitly prior to byte 0.

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): fileReader(kind, locking, defaultSerializeType(false)) throws: Warning

openreader is deprecated - please use openReader instead

proc openReader(path: string, param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): fileReader(kind, locking, defaultSerializeType(false)) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewOpenReaderRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileWriter(kind, locking, defaultSerializeType(true)) throws¶: Warning

openwriter is deprecated - please use openWriter instead

proc openWriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileWriter(kind, locking, defaultSerializeType(true)) throws¶: Warning

openWriter with a style argument is unstable

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, hints = ioHintSet.empty): fileWriter(kind, locking, defaultSerializeType(true)) throws

Open a file at a particular path and return a fileWriter for it. This function is equivalent to calling open with ioMode.cwr and then file.writer on the resulting file.

Arguments

path – which file to open (for example, “some/file.txt”).
kind – iokind compile-time argument to determine the corresponding parameter of the fileWriter type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileWriter should use locking; sets the corresponding parameter of the fileWriter type. Defaults to true, but when safe, setting it to false can improve performance.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open fileWriter to the requested resource.

Throws

FileNotFoundError – Thrown if part of the provided path did not exist
PermissionError – Thrown if part of the provided path had inappropriate permissions
NotADirectoryError – Thrown if part of the provided path was expected to be a directory but was not
SystemError – Thrown if a fileWriter could not be returned.
IllegalArgumentError – Thrown if trying to write explicitly prior to byte 0.

Warning

openwriter is deprecated - please use openWriter instead

proc openWriter(path: string, param kind = iokind.dynamic, param locking = true, hints = ioHintSet.empty, in serializer: ?st = defaultSerializeVal(true)): fileWriter(kind, locking, st) throws

Open a file at a particular path and return a fileWriter for it. This function is equivalent to calling open with ioMode.cwr and then file.writer on the resulting file.

Arguments

path – which file to open (for example, “some/file.txt”).
kind – iokind compile-time argument to determine the corresponding parameter of the fileWriter type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileWriter should use locking; sets the corresponding parameter of the fileWriter type. Defaults to true, but when safe, setting it to false can improve performance.
hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open fileWriter to the requested resource.

Throws

FileNotFoundError – Thrown if part of the provided path did not exist
PermissionError – Thrown if part of the provided path had inappropriate permissions
NotADirectoryError – Thrown if part of the provided path was expected to be a directory but was not
SystemError – Thrown if a fileWriter could not be returned.
IllegalArgumentError – Thrown if trying to write explicitly prior to byte 0.

proc file.reader(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileReader(kind, locking) throws¶: Warning

reader with a style argument is unstable

config param useNewFileReaderRegionBounds = false¶: Used to control the behavior of the region argument for file.reader. When set to true, the region argument will fully specify the bounds of the fileReader. When set to false, the region argument will exclude the high bound. Defaults to false, the original behavior.

proc file.reader(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty, in deserializer: ?dt = defaultSerializeVal(false)): fileReader(kind, locking, dt) throws

Create a fileReader that supports reading from a file. See I/O Overview.

The region= argument defines the portion of the file that the fileReader will read from. This is a byte offset; the beginning of the file is at the offset 0. The default for this argument enables the fileReader to access the entire file.

A fileReader will never read beyond its maximum end offset. In addition, reading from a fileReader beyond the end of the underlying file will not extend that file. Reading beyond the end of the file or beyond the end offset of the fileReader will produce the error OS.EofError (or just return false in many cases such as fileReader.read) to indicate that the end was reached.

Arguments

kind – iokind compile-time argument to determine the corresponding parameter of the fileReader type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileReader should use locking; sets the corresponding parameter of the fileReader type. Defaults to true, but when safe, setting it to false can improve performance.
region – zero-based byte offset indicating where in the file the fileReader should start and stop reading. Defaults to 0.. - meaning from the start of the file to no end point.
hints – provide hints about the I/O that this fileReader will perform. See ioHintSet. The default value of ioHintSet.empty will cause the fileReader to use the hints provided when the file was opened.

Warning

The region argument will ignore any specified stride other than 1.

Throws

SystemError – Thrown if a fileReader could not be returned.
IllegalArgumentError – Thrown if trying to read explicitly prior to byte 0.

proc file.reader(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): fileReader(kind, locking) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewFileReaderRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc file.lines(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, in local_style: iostyle) throws¶: Warning

lines with a local_style argument is unstable

config param useNewLinesRegionBounds = false¶: Used to control the behavior of the region argument for file.lines. When set to true, the region argument will fully specify the bounds that this function would cover. When set to false, the region argument will exclude the high bound. Defaults to false, the original behavior.

proc file.lines(param locking: bool = true, region: range(?) = 0.., hints = ioHintSet.empty) throws

Iterate over all of the lines in a file.

Returns: an object which yields strings read from the file
Throws: SystemError – Thrown if an object could not be returned.

Warning

file.lines is deprecated; please use file.reader().lines instead

proc file.lines(param locking: bool = true, region: range(?) = 0.., hints = ioHintSet.empty) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewLinesRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc file.writer(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): fileWriter(kind, locking) throws¶: Warning

writer with a style argument is unstable

config param useNewFileWriterRegionBounds = false¶: Used to control the behavior of the region argument for file.writer. When set to true, the region argument will fully specify the bounds of the fileWriter. When set to false, the region argument will exclude the high bound. Defaults to false, the original behavior.

proc file.writer(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty, in serializer: ?st = defaultSerializeVal(true)): fileWriter(kind, locking, st) throws

Create a fileWriter that supports writing to a file. See I/O Overview.

The region= argument defines the portion of the file that the fileWriter will write to. This is a byte offset; the beginning of the file is at the offset 0. The default for this argument enables the fileWriter to access the entire file.

When a fileWriter writes to a file, it will replace file data that was previously stored at the relevant offset. If the offset is beyond the end of the file, the file will be extended.

A fileWriter will never write beyond its maximum end offset. It will extend the file only as necessary to store data written to the fileWriter. In other words, specifying the high bound of the region argument here does not impact the file size directly; it impacts only the section of the file that this fileWriter can write to. After all fileWriters to a file are closed, that file will have a size equal to the last offset written to by any fileWriter.

Arguments

kind – iokind compile-time argument to determine the corresponding parameter of the fileWriter type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.
locking – compile-time argument to determine whether or not the fileWriter should use locking; sets the corresponding parameter of the fileWriter type. Defaults to true, but when safe, setting it to false can improve performance.
region – zero-based byte offset indicating where in the file the fileWriter should start and stop writing. Defaults to 0.. - meaning from the start of the file to no specified end point.
hints – provide hints about the I/O that this fileWriter will perform. See ioHintSet. The default value of ioHintSet.empty will cause the fileWriter to use the hints provided when the file was opened.

Warning

The region argument will ignore any specified stride other than 1.

Throws

SystemError – Thrown if a fileWriter could not be returned.
IllegalArgumentError – Thrown if trying to write explicitly prior to byte 0.

proc file.writer(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): fileWriter(kind, locking) throws: Warning

Currently the region argument’s high bound specifies the first location in the file that is not included. This behavior is deprecated, please compile your program with -suseNewFileWriterRegionBounds=true to have the region argument specify the entire segment of the file covered, inclusive.

proc fileReader.readWriteLiteral(lit: string, ignoreWhiteSpace = true) throws¶: Explicit call for reading or writing a literal as an alternative to using IO.ioLiteral.

proc fileWriter.readWriteLiteral(lit: string, ignoreWhiteSpace = true) throws¶: Explicit call for reading or writing a literal as an alternative to using IO.ioLiteral.

proc fileReader.readLiteral(literal: string, ignoreWhitespace = true): void throws¶

Advances the offset of a fileReader within the file by reading the exact text of the given string literal from the fileReader.

If the string is not matched exactly, then the fileReader’s offset is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the fileReader is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

literal – the string to be matched.
ignoreWhitespace – determines whether leading whitespace is ignored.

Throws

BadFormatError – Thrown if literal could not be matched.
EofError – Thrown if end of fileReader is encountered.

Warning

fileReader.readLiteral is unstable and subject to change.

proc fileReader.readLiteral(literal: bytes, ignoreWhitespace = true): void throws

Advances the offset of a fileReader by reading the exact bytes of the given literal from the fileReader.

If the bytes are not matched exactly, then the fileReader’s offset is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the fileReader is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

literal – the bytes to be matched.
ignoreWhitespace – determines whether leading whitespace is ignored.

Throws

BadFormatError – Thrown if literal could not be matched.
EofError – Thrown if end of the fileReader is encountered.

Warning

fileReader.readLiteral is unstable and subject to change.

proc fileReader.readNewline(): void throws¶

Advances the offset of the fileReader by reading a newline.

If a newline is not matched exactly, then the fileReader’s offset is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the fileReader is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a newline.

Throws

BadFormatError – Thrown if a newline could not be matched.
EofError – Thrown if end of the fileReader is encountered.

Warning

fileReader.readNewline is unstable and subject to change.

proc fileReader.matchLiteral(literal: string, ignoreWhitespace = true): bool throws¶

Advances the offset of a fileReader by reading the exact text of the given string literal from the fileReader.

If the string is not matched exactly, then the fileReader’s offset is unchanged and this method will return false. In other words, this fileReader will return false in the cases where fileReader.readLiteral would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

literal – the string to be matched.
ignoreWhitespace – determines whether leading whitespace is ignored.

Returns

true if the read succeeded, and false on end of file or if the literal could not be matched.

Warning

fileReader.matchLiteral is unstable and subject to change.

proc fileReader.matchLiteral(literal: bytes, ignoreWhitespace = true): bool throws

Advances the offset of a fileReader by reading the exact bytes of the given literal from the fileReader.

If the bytes are not matched exactly, then the fileReader’s offset is unchanged and this method will return false. In other words, this fileReader will return false in the cases where fileReader.readLiteral would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

literal – the bytes to be matched.
ignoreWhitespace – determines whether leading whitespace is ignored.

Returns

true if the read succeeded, and false on end of file or if the literal could not be matched.

Warning

fileReader.matchLiteral is unstable and subject to change.

proc fileReader.matchNewline(): bool throws¶

Advances the offset of the fileReader by reading a newline.

If a newline is not matched exactly, then the fileReader’s offset is unchanged and this method will return false. In other words, this fileReader will return false in the cases where fileReader.readNewline would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a newline.

Returns: true if the read succeeded, and false on end of file or if the newline could not be matched.

Warning

fileReader.matchNewline is unstable and subject to change.

proc fileWriter.writeLiteral(literal: string): void throws¶: Writes a string to the fileWriter, ignoring any formatting configured for this fileWriter.

Warning

fileWriter.writeLiteral is unstable and subject to change.

proc fileWriter.writeLiteral(literal: bytes): void throws: Writes bytes to the fileWriter, ignoring any formatting configured for this fileWriter.

Warning

fileWriter.writeLiteral is unstable and subject to change.

proc fileWriter.writeNewline(): void throws¶: Writes a newline to the fileWriter, ignoring any formatting configured for this fileWriter.

Warning

fileWriter.writeNewline is unstable and subject to change.

proc fileReader.readWriteNewline() throws¶: Explicit call for reading or writing a newline as an alternative to using IO.ioNewline.

proc fileWriter.readWriteNewline() throws¶: Explicit call for reading or writing a newline as an alternative to using IO.ioNewline.

proc fileReader.binary(): bool¶: Returns true if this fileReader is configured for binary I/O.

proc fileWriter.binary(): bool¶: Returns true if this fileWriter is configured for binary I/O.

proc fileWriter.writeBytes(x, len: c_ssize_t) throws¶

Write a sequence of bytes.

Throws

UnexpectedEofError – Thrown if EOF encountered before all bytes could be written.
SystemError – Thrown if the byte sequence could not be written for another reason.

Warning

‘writeBytes’ with a generic pointer argument is deprecated; please use the variant that takes a ‘bytes’ object

iter fileReader.lines(stripNewline = false)¶

Iterate over all of the lines ending in \n in a fileReader - the fileReader lock will be held while iterating over the lines.

Only serial iteration is supported. This iterator will halt on internal system errors.

Warning

This iterator executes on the current locale. This may impact multilocale performance if the current locale is not the same locale on which the fileReader was created.

Arguments: stripNewline – Whether to strip the trailing \n from the line. Defaults to false
Yields: lines from the fileReader, by default with a trailing \n

proc stringify(const args ...?k): string¶

Creates a string representing the result of writing the arguments.

Writes each argument, possibly using a writeThis method, to a string and returns the result.

proc fileReader.read(ref args ...?k): bool throws¶

Read one or more values from a fileReader. The fileReader’s lock will be held while reading the values — this protects against interleaved reads.

Arguments

args – a series of variables to read into. Basic types are handled internally, but for other types this function will call value.readThis() with a Reader argument as described in The readThis() and writeThis() Methods.

Returns

true if the read succeeded, and false on end of file.

Throws

UnexpectedEofError – Thrown if an EOF occurred while reading an item.
SystemError – Thrown if data could not be read from the fileReader for another reason.

proc fileReader.read(ref args ...?k, style: iostyle): bool throws: Warning

read with a style argument is unstable

proc fileReader.readline(arg: [] uint(8), out numRead: int, start = arg.domain.lowBound, amount = arg.domain.highBound - start + 1): bool throws¶

Read a line into a Chapel array of bytes. Reads until a \n is reached. The \n is returned in the array.

Note that this routine currently requires a 1D rectangular non-strided array.

Throws a SystemError if a line could not be read from the fileReader.

Arguments

arg – A 1D DefaultRectangular array which must have at least 1 element.
numRead – The number of bytes read.
start – Index to begin reading into.
amount – The maximum amount of bytes to read.

Returns

true if the bytes were read without error.

Warning

fileReader.readline is deprecated. Use fileReader.readLine instead

proc fileReader.readLine(ref a: [] ?t, maxSize = a.size, stripNewline = false): int throws¶

Read a line into an array of bytes.

Reads bytes from the fileReader until a \n is reached. Values are read in binary format (i.e., this method is not aware of UTF-8 encoding).

The array’s size is not changed to accommodate bytes. If a newline is not found before the array is filled, or maxSize bytes are read, a BadFormatError is thrown and the fileReader offset is returned to its original position.

Arguments

a – A 1D DefaultRectangular non-strided array storing int(8) or uint(8). Values are overwritten.
maxSize – The maximum number of bytes to store into the a array. Defaults to the size of the array.
stripNewline – Whether to strip the trailing \n from the line. If true, the newline isn’t counted in the number of bytes read.

Returns

The number of array elements set by this call, or 0 otherwise (i.e., the fileReader was already at EOF).

Throws

IllegalArgumentError – Thrown if maxSize > a.size
BadFormatError – Thrown if the line is longer than maxSize. File offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readline(ref arg: ?t): bool throws

Read a line into a Chapel string or bytes. Reads until a \n is reached. The \n is included in the resulting value.

Arguments

arg – a string or bytes to receive the line

Returns

true if a line was read without error, false upon EOF

Throws

UnexpectedEofError – Thrown if unexpected EOF encountered while reading.
SystemError – Thrown if data could not be read from the fileReader.

Warning

fileReader.readline is deprecated. Use fileReader.readLine instead

proc fileReader.readLine(ref s: string, maxSize = -1, stripNewline = false): bool throws

Read a line into a string. Reads until a \n is reached.

Arguments

s – the string to read into. Contents are overwritten.
maxSize – The maximum number of codepoints to store into s. The default of -1 means to read an unlimited number of codepoints.
stripNewline – Whether to strip the trailing \n from the line.

Returns

true if a line was read without error, false upon EOF

Throws

BadFormatError – Thrown if the line is longer than maxSize. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readLine(ref b: bytes, maxSize = -1, stripNewline = false): bool throws

Read a line into a bytes. Reads until a \n is reached.

Arguments

b – the bytes to receive the line. Contents are overwritten.
maxSize – The maximum number of bytes to store into b. The default of -1 means to read an unlimited number of bytes.
stripNewline – Whether to strip the trailing \n from the line.

Returns

true if a line was read without error, false upon EOF

Throws

BadFormatError – Thrown if the line is longer than maxSize. The file offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readLine(type t = string, maxSize = -1, stripNewline = false): t throws

Read a line. Reads until a \n is reached.

Arguments

t – the type of data to read, which must be string or bytes. Defaults to string if not specified.
maxSize – The maximum number of codepoints to read. The default of -1 means to read an unlimited number of codepoints.
stripNewline – Whether to strip the trailing \n from the line.

Returns

A string or bytes with the contents of the fileReader up to (and possibly including) the newline.

Throws

EofError – Thrown if nothing could be read because the fileReader was already at EOF.
BadFormatError – Thrown if the line is longer than maxSize. The file offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readThrough(separator: ?t, maxSize = -1, stripSeparator = false): t throws¶

Read until the given separator is found, returning the contents of the fileReader through that point.

If the separator is found, the fileReader offset is left immediately after it. If the separator could not be found in the next maxSize bytes, a BadFormatError is thrown and the fileReader’s offset is not changed. Otherwise, if EOF is reached before finding the separator, the remainder of the fileReader’s contents are returned and the offset is left at EOF.

To match with multiple separators, or a more complex separator, use the overload of readThrough that accepts a regex separator.

Arguments

separator – The separator to match with. Must be a string or bytes.
maxSize – The maximum number of bytes to read. For the default value of -1, this method can read until EOF.
stripSeparator – Whether to strip the separator from the returned string or bytes. If true, the returned value will not include the separator.

Returns

A string or bytes with the contents of the fileReader up to (and possibly including) the separator.

Throws

EofError – Thrown if nothing could be read because the fileReader was already at EOF.
BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readThrough(separator: string, ref s: string, maxSize = -1, stripSeparator = false): bool throws

Read until the given separator is found, returning the contents of the fileReader through that point.

See the above overload of this method for more details.

Arguments

separator – The separator to match with.
s – The string to read into. Contents will be overwritten.
maxSize – The maximum number of bytes to read. For the default value of -1, this method can read until EOF.
stripSeparator – Whether to strip the separator from the returned string. If true, the separator will not be included in s.

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readThrough(separator: bytes, ref b: bytes, maxSize = -1, stripSeparator = false): bool throws

Read until the given separator is found, returning the contents of the fileReader through that point.

See the above overload of this method for more details.

Arguments

separator – The separator to match with.
s – The bytes to read into. Contents will be overwritten.
maxSize – The maximum number of codepoints to read. For the default value of -1, this method can read until EOF.
stripSeparator – Whether to strip the separator from the returned bytes. If true, the separator will not be included in b.

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readTo(separator: ?t, maxSize = -1): t throws¶

Read until the given separator is found, returning the contents of the fileReader up to that point.

If the separator is found, the fileReader offset is left immediately before it. If the separator could not be found in the next maxSize bytes, a BadFormatError is thrown and the fileReader’s offset is not changed. Otherwise, if EOF is reached before finding the separator, the remainder of the fileReader’s contents are returned and the offset is left at EOF.

To match with multiple separators, or a more complex separator, use the overload of readTo that accepts a regex separator.

Arguments

separator – The separator to match with. Must be a string or bytes.
maxSize – The maximum number of bytes to read. For the default value of -1, this method can read until EOF.

Returns

A string or bytes with the contents of the fileReader up to the separator.

Throws

EofError – Thrown if nothing could be read because the fileReader was already at EOF.
BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readTo(separator: string, ref s: string, maxSize = -1): bool throws

Read until the given separator is found, returning the contents of the fileReader up to that point.

See the above overload of this method for more details.

Arguments

separator – The separator to match with.
s – The string to read into. Contents will be overwritten.
maxSize – The maximum number of bytes to read. For the default value of -1, this method will read until EOF.

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readTo(separator: bytes, ref b: bytes, maxSize = -1): bool throws

Read until the given separator is found, returning the contents of the fileReader up to that point.

See the above overload of this method for more details.

Arguments

separator – The separator to match with.
b – The bytes to read into. Contents will be overwritten.
maxSize – The maximum number of bytes to read. For the default value of -1, this method will read until EOF.

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

BadFormatError – Thrown if the separator was not found in the next maxSize bytes. The fileReader offset is not moved.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readAll(type t = bytes): t throws¶

Read the remaining contents of the fileReader into an instance of the specified type

Arguments

t – the type to read into; must be string or bytes. Defaults to bytes if not specified.

Returns

the contents of the fileReader as a t

Throws

EofError – Thrown if nothing could be read because the fileReader was already at EOF.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readAll(ref s: string): int throws

Read the remaining contents of the fileReader into a string.

Note that any existing contents of the string are overwritten.

Arguments: s – the string to read into
Returns: the number of codepoints that were stored in s, or 0 if the fileReader is at EOF.
Return type: int
Throws: SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readAll(ref b: bytes): int throws

Read the remaining contents of the fileReader into a bytes.

Note that any existing contents of the bytes are overwritten.

Arguments: b – the bytes to read into
Returns: the number of bytes that were stored in b, or 0 if the fileReader is at EOF.
Return type: int
Throws: SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readAll(ref a: [?d] ?t): int throws

Read the remaining contents of the fileReader into an array of bytes.

Note that this routine currently requires a 1D rectangular non-strided array.

If the remaining contents of the fileReader exceed the size of a, the first a.size bytes will be read into a, and then an InsufficientCapacityError will be thrown. In such a case, the fileReader offset is advanced a.size bytes from its original position.

Arguments

a – the array of bytes to read into

Returns

the number of bytes that were stored in a

Return type

int

Throws

InsufficientCapacityError – Thrown if the fileReader’s contents do not fit into a.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readstring(ref str_out: string, len: int(64) = -1): bool throws¶

read a given number of bytes from a fileReader

Arguments

str_out – The string to be read into
len – Read up to len bytes from the fileReader, up until EOF (or some kind of I/O error). If the default value of -1 is provided, read until EOF starting from the fileReader’s current offset.

Returns

true if we read something, false upon EOF

Throws

UnexpectedEofError – Thrown if unexpected EOF encountered while reading.
SystemError – Thrown if the bytes could not be read from the fileReader.

Warning

‘readstring’ is deprecated; please use ‘readString’ instead

proc fileReader.readString(maxSize: int): string throws¶

Read a given number of codepoints from a fileReader, returning a new string.

The string’s length may be less than maxSize if EOF is reached while reading. If nothing is read, the empty string ("") will be returned.

Arguments

maxSize – the maximum number of codepoints to read from the fileReader

Returns

a new string containing up to the next maxSize codepoints from the fileReader

Throws

EofError – Thrown if the fileReader offset was already at EOF.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readString(ref s: string, maxSize: int): bool throws

Read a given number of codepoints from a fileReader into a string.

The updated string’s length may be less than maxSize if EOF is reached while reading. If nothing is read, it will be set to the empty string ("").

Arguments

s – the string to read into — contents will be overwritten
maxSize – the maximum number of codepoints to read from the fileReader

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readbytes(ref bytes_out: bytes, len: int(64) = -1): bool throws¶

read a given number of bytes from a fileReader

arg bytes_out

The bytes to be read into

arg len

Read up to len bytes from the fileReader, up until EOF (or some kind of I/O error). If the default value of -1 is provided, read until EOF starting from the fileReader’s current offset.

returns

true if we read something, false upon EOF

Throws: SystemError – Thrown if data could not be read from the fileReader.

Warning

‘readbytes’ is deprecated; please use ‘readBytes’ instead

proc fileReader.readBytes(maxSize: int): bytes throws¶

Read a given number of bytes from a fileReader, returning a new bytes.

The bytes’s length may be less than maxSize if EOF is reached while reading. If nothing is read, the empty bytes (b"") will be returned.

Arguments

maxSize – the maximum number of bytes to read from the fileReader

Returns

a new bytes containing up to the next maxSize bytes from the fileReader

Throws

EofError – Thrown if the fileReader offset was already at EOF.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBytes(ref b: bytes, maxSize: int): bool throws

Read a given number of bytes from a fileReader into a bytes.

The updated bytes’s length may be less than maxSize if EOF is reached while reading. If nothing is read, it will be set to the empty bytes (b"").

Arguments

b – the bytes to read into — contents will be overwritten
maxSize – the maximum number of bytes to read from the fileReader

Returns

true if something was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readbits(ref v: integral, nbits: integral): bool throws¶: Warning

fileReader.readbits is deprecated - please use fileReader.readBits instead

proc fileReader.readBits(ref x: integral, numBits: int): bool throws¶

Read bits with binary I/O

Arguments

x – where to store the read bits. This value will have its numBits least-significant bits set.
numBits – how many bits to read

Returns

true if the bits were read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

UnexpectedEofError – Thrown if EOF was encountered before numBits could be read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBits(type resultType, numBits: int): resultType throws

Read bits with binary I/O

Arguments

resultType – type of the value returned
numBits – how many bits to read

Returns

bits read. This value will have its numBits least-significant bits set

Throws

EofError – Thrown if the fileReader offset was already at EOF.
UnexpectedEofError – Thrown if EOF was encountered before numBits could be read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileWriter.writebits(v: integral, nbits: integral) throws¶: Warning

fileWriter.writebits is deprecated - please use fileWriter.writeBits instead

proc fileWriter.writeBits(x: integral, numBits: int): void throws¶

Write bits with binary I/O

Arguments

x – a value containing numBits bits to write the least-significant bits
numBits – how many bits to write

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified range.
IllegalArgumentError – Thrown if writing more bits than fit into x.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeCodepoint(codepoint: int) throws¶

Write a single Unicode codepoint to a fileWriter

Arguments

codepoint – Unicode codepoint to write

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified range.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileReader.readCodepoint(): int throws¶

Read a single Unicode codepoint from a fileReader

Returns

Unicode codepoint read

Throws

EofError – Thrown if the fileReader offset was already at EOF.
UnexpectedEofError – Thrown if EOF was encountered while reading a codepoint.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readCodepoint(ref codepoint: int): bool throws

Read a single Unicode codepoint from a fileReader

Arguments

c – where to store the read codepoint

Returns

true if the codepoint was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

UnexpectedEofError – Thrown if EOF was encountered while reading a codepoint.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileWriter.writeByte(byte: uint(8)) throws¶

Write a single byte to a fileWriter

Arguments

byte – the byte to write

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified range.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileReader.readByte(): uint(8) throws¶

Read a single byte from a fileReader

Returns

the byte read

Throws

EofError – Thrown if the fileReader offset was already at EOF.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readByte(ref byte: uint(8)): bool throws

Read a single byte from a fileReader

Arguments: byte – where to store the read byte
Returns: true if the byte was read, and false otherwise (i.e., the fileReader was already at EOF).
Throws: SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileWriter.writeString(s: string, size = s.size) throws¶

Write size codepoints from a string to a fileWriter

Arguments

s – the string to write
size – the number of codepoints to write from the string

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified range.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.
IllegalArgumentError – Thrown if size is larger than s.size

proc fileWriter.writeBytes(b: bytes, size = b.size) throws

Write size bytes from a bytes to a fileWriter

Arguments

b – the bytes to write
size – the number of bytes to write from the bytes

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified range.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.
IllegalArgumentError – Thrown if size is larger than b.size

proc fileWriter.writeBinary(ptr: c_ptr(?t), numBytes: int) throws¶

Write numBytes of data from a c_ptr to a fileWriter

Note that native endianness is always used.

If numBytes is not evenly divisible by the size of t, the remaining bytes will be ignored. For example, if the c_ptr’s internal type is 4 bytes in length, and numBytes=17, only 16 bytes will be written.

Warning

This method provides no protection against attempting to access invalid memory

Arguments

ptr – a c_ptr to some valid memory
numBytes – the number of bytes to write

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeBinary(ptr: c_void_ptr, numBytes: int) throws

Write numBytes of data from a c_void_ptr to a fileWriter

The data are written to the file one byte at a time.

Warning

This method provides no protection against attempting to access invalid memory

Arguments

ptr – a typeless c_void_ptr to some valid memory
numBytes – the number of bytes to write

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeBinary(arg: numeric, param endian: ioendian = ioendian.native) throws

Write a binary number to the fileWriter

Arguments

arg – number to be written
endian – ioendian compile-time argument that specifies the byte order in which to write the number. Defaults to ioendian.native.

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeBinary(arg: numeric, endian: ioendian) throws

Write a binary number to the fileWriter

Arguments

arg – number to be written
endian – ioendian specifies the byte order in which to write the number.

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeBinary(s: string, size: int = s.size) throws

Write a string to a fileWriter in binary format

Arguments

s – the string to write
size – the number of codepoints to write from the string

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.
IllegalArgumentError – Thrown if size is larger than s.size.

proc fileWriter.writeBinary(b: bytes, size: int = b.size) throws

Write a bytes to a fileWriter in binary format

Arguments

b – the bytes to write
size – the number of bytes to write from the bytes

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.
IllegalArgumentError – Thrown if size is larger than b.size.

proc fileWriter.writeBinary(const ref data: [?d] ?t, param endian: ioendian = ioendian.native) throws

Write an array of binary numbers to a fileWriter

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array of numbers to write to the fileWriter
endian – ioendian compile-time argument that specifies the byte order in which to read the numbers. Defaults to ioendian.native.

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeBinary(const ref data: [?d] ?t, endian: ioendian) throws

Write an array of binary numbers to a fileWriter

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array of numbers to write to the fileWriter
endian – ioendian specifies the byte order in which to write the number.

Throws

EofError – Thrown if the fileWriter offset was already at EOF.
UnexpectedEofError – Thrown if the write operation exceeds the fileWriter’s specified region.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileReader.readBinary(ref arg: numeric, param endian: ioendian = ioendian.native): bool throws¶

Read a binary number from the fileReader

Arguments

arg – number to be read
endian – ioendian compile-time argument that specifies the byte order in which to read the number. Defaults to ioendian.native.

Returns

true if the number was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

UnexpectedEofError – Thrown if EOF was encountered while reading the number.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ref arg: numeric, endian: ioendian): bool throws

Read a binary number from the fileReader

arg arg

number to be read

arg endian

ioendian specifies the byte order in which to read the number.

returns

true if the number was read, and false otherwise (i.e., the fileReader was already at EOF).

Throws

UnexpectedEofError – Thrown if EOF was encountered while reading the number.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ref s: string, maxSize: int): bool throws

Read a specified number of codepoints into a string

The resulting string s may be smaller than maxSize if EOF is reached before reading the specified number of codepoints. Additionally, if nothing is read from the fileReader, s will be set to "" (the empty string) and the method will return false.

Note

This method always uses UTF-8 encoding regardless of the fileReader’s configuration

Arguments

s – the string to read into — this value is overwritten
maxSize – the number of codepoints to read from the fileReader

Returns

true if some codepoints were read, or false on EOF

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ref b: bytes, maxSize: int): bool throws

Read a specified number of bytes into a bytes

The bytes b may be smaller than maxSize if EOF is reached before reading the specified number of bytes. Additionally, if nothing is read from the fileReader, b will be set to b"" (the empty bytes) and the method will return false.

Arguments

b – the bytes to read into — this value is overwritten
maxSize – the number of bytes to read from the fileReader

Returns

true if some bytes were read, or false on EOF

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

config param ReadBinaryArrayReturnInt = false¶

Controls the return type of the readBinary overloads that take an array argument. Those are:

fileReader.readBinary(ref data: [], param endian = ioendian.native) fileReader.readBinary(ref data: [], endian: ioendian)

when false: the deprecated methods are called. These return a bool indicating whether any values were read. These variants will also throw if EOF is reached before filling the array.
when true: the new methods are called. These return an int with the number of values that were read.

This param can be set to true by compiling your program with -sReadBinaryArrayReturnInt=true

proc fileReader.readBinary(ref data: [?d] ?t, param endian = ioendian.native): bool throws

Read an array of binary numbers from a fileReader

Binary values of the type data.eltType are consumed from the fileReader until data is full or EOF is reached. An UnexpectedEofError is thrown if EOF is reached before the array is filled.

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array to read into – existing values are overwritten.
endian – ioendian compile-time argument that specifies the byte order in which to read the numbers. Defaults to ioendian.native.

Returns

false if EOF is encountered before reading anything, true otherwise

Throws

SystemError – Thrown if an error occurred while reading from the fileReader.
UnexpectedEofError – Thrown if EOF is encountered before data.size values are read.

Warning

The variant of readBinary(data: []) that returns a bool is deprecated; please recompile with -sReadBinaryArrayReturnInt=true to use the new variant

proc fileReader.readBinary(ref data: [?d] ?t, param endian = ioendian.native): int throws

Read an array of binary numbers from a fileReader

Binary values of the type data.eltType are consumed from the fileReader until data is full or EOF is reached.

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array to read into – existing values are overwritten.
endian – ioendian compile-time argument that specifies the byte order in which to read the numbers in. Defaults to ioendian.native.

Returns

the number of values that were read into the array. This can be less than data.size if EOF was reached, or an error occurred, before filling the array.

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ref data: [?d] ?t, endian: ioendian): bool throws

Read an array of binary numbers from a fileReader

Binary values of the type data.eltType are consumed from the fileReader until data is full or EOF is reached. An UnexpectedEofError is thrown if EOF is reached before the array is filled.

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array to read into – existing values are overwritten.
endian – ioendian specifies the byte order in which to read the number.

Returns

false if EOF is encountered before reading anything, true otherwise

Throws

SystemError – Thrown if an error occurred while reading the from fileReader.
UnexpectedEofError – Thrown if EOF is encountered before data.size values are read.

Warning

The variant of readBinary(data: []) that returns a bool is deprecated; please recompile with -sReadBinaryArrayReturnInt=true to use the new variant

proc fileReader.readBinary(ref data: [?d] ?t, endian: ioendian): int throws

Read an array of binary numbers from a fileReader

Binary values of the type data.eltType are consumed from the fileReader until data is full or EOF is reached.

Note that this routine currently requires a 1D rectangular non-strided array.

Arguments

data – an array to read into – existing values are overwritten.
endian – ioendian specifies the byte order in which to read the number.

Returns

the number of values that were read into the array. This can be less than data.size if EOF was reached, or an error occurred, before filling the array.

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ptr: c_ptr(?t), maxBytes: int): int throws

Read up to maxBytes bytes from a fileReader into a c_ptr

Note that native endianness is always used.

If maxBytes is not evenly divisible by the size of t, then the remaining bytes are ignored.

Arguments

ptr – a c_ptr to some memory — existing values will be overwritten
maxBytes – the maximum number of bytes to read from the fileReader

Returns

the number of bytes that were read. this can be less than maxBytes if EOF was reached before reading the specified number of bytes, or if maxBytes is not evenly divisible by the size of t

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readBinary(ptr: c_void_ptr, maxBytes: int): int throws

Read up to maxBytes bytes from a fileReader into a c_void_ptr

Note that data are read from the file one byte at a time.

Arguments

ptr – a typeless c_void_ptr to some memory — existing values will be overwritten
maxBytes – the maximum number of bytes to read from the fileReader

Returns

the number of bytes that were read. this can be less than maxBytes if EOF was reached before reading the specified number of bytes

Throws

SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readln(ref args ...?k): bool throws¶

Read values from a fileReader and then consume any bytes until newline is reached. The input will be consumed atomically - the fileReader lock will be held while reading all of the passed values.

Arguments

args – a list of arguments to read. This routine can be called with zero or more such arguments. Basic types are handled internally, but for other types this function will call value.readThis() with a Reader argument as described in The readThis() and writeThis() Methods.

Returns

true if the read succeeded, and false upon end of file.

Throws

UnexpectedEofError – Thrown if EOF was encountered before data could be read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

Warning

‘readln’ is unstable and may be removed or modified in a future release

proc fileReader.readln(ref args ...?k, style: iostyle): bool throws: Warning

readln with a style argument is unstable

proc fileReader.read(type t) throws

Read a value of passed type.

For example, the following line of code reads a value of type int from stdin and uses it to initialize a variable x:

var x = stdin.read(int);

Arguments

t – the type to read

Returns

the value read

Throws

EofError – Thrown if the fileReader is already at EOF.
UnexpectedEofError – Thrown if EOF was encountered before data could be fully read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileReader.readln(type t) throws

Read a value of passed type followed by a newline.

Arguments

t – the type to read

Returns

the value read

Throws

EofError – Thrown if the fileReader is at already EOF.
UnexpectedEofError – Thrown if EOF was encountered before data could be fully read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

Warning

‘readln’ is unstable and may be removed or modified in a future release

proc fileReader.readln(type t ...?numTypes) throws

Read values of passed types followed by a newline and return a tuple containing the read values.

Arguments

t – more than one type to read

Returns

a tuple of the read values

Throws

EofError – Thrown if the fileReader is already at EOF.
UnexpectedEofError – Thrown if EOF was encountered before data could be fully read.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

Warning

‘readln’ is unstable and may be removed or modified in a future release

proc fileReader.read(type t ...?numTypes) throws

Read values of passed types and return a tuple containing the read values. The fileReader’s lock will be held while reading — this protects against interleaved reads.

Arguments

t – more than one type to read

Returns

a tuple of the read values

Throws

EofError – Thrown if the fileReader is already at EOF.
UnexpectedEofError – Thrown if EOF was encountered while more data was expected.
SystemError – Thrown if data could not be read from the fileReader due to a system error.

proc fileWriter.write(const args ...?k) throws¶

Write values to a fileWriter. The output will be produced atomically - the fileWriter lock will be held while writing all of the passed values.

Arguments

args – a list of arguments to write. Basic types are handled internally, but for other types this function will call value.writeThis() with the fileWriter as an argument.

Throws

EofError – Thrown if EOF is reached before all the arguments could be written.
UnexpectedEofError – Thrown if EOF is encountered while writing one of the arguments.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.write(const args ...?k, style: iostyle) throws: Warning

write with a style argument is unstable

proc fileWriter.writeln(const args ...?k) throws¶

Write values to a fileWriter followed by a newline. The output will be produced atomically - the fileWriter lock will be held while writing all of the passed values.

Arguments

args – a variable number of arguments to write. This method can be called with zero or more arguments. Basic types are handled internally, but for other types this function will call value.writeThis() with the fileWriter as an argument.

Throws

EofError – Thrown if EOF is reached before all the arguments could be written.
UnexpectedEofError – Thrown if EOF is encountered while writing one of the arguments.
SystemError – Thrown if data could not be written to the fileWriter due to a system error.

proc fileWriter.writeln(const args ...?k, style: iostyle) throws: Warning

writeln with a style argument is unstable

proc fileReader.flush() throws¶: Warning

fileReader.flush is deprecated; it has no replacement because ‘flush’ has no effect on ‘fileReader’

proc fileWriter.flush() throws¶

Makes all writes to the fileWriter, if any, available to concurrent viewers of its associated file, such as other fileWriters/fileReader or other applications accessing this file concurrently.

Unlike file.fsync, this does not commit the written data to the file’s device.

Throws: SystemError – Thrown if the flush fails.

proc fileReader.assertEOF(errStr: string = "- Not at EOF")¶: Assert that a fileReader has reached end-of-file and that there was no error doing the read.

proc fileReader.close() throws¶

Close a fileReader

Throws: SystemError – Thrown if the fileReader is not successfully closed.

proc fileWriter.close() throws¶

Close a fileWriter. Implicitly performs the fileWriter.flush operation (see Synchronization of fileReader and fileWriter Data and Avoiding Data Races).

Throws: SystemError – Thrown if the fileWriter is not successfully closed.

proc fileReader.isClosed(): bool¶: Return true if a fileReader is currently closed.

proc fileWriter.isClosed(): bool¶: Return true if a fileWriter is currently closed.

const stdin: fileReader(iokind.dynamic, true)¶: standard input, otherwise known as file descriptor 0

const stdout: fileWriter(iokind.dynamic, true)¶: standard output, otherwise known as file descriptor 1

const stderr: fileWriter(iokind.dynamic, true)¶: standard error, otherwise known as file descriptor 2

proc read(ref args ...?n): bool throws¶: Equivalent to stdin.read. See fileReader.read

proc read(type t ...?numTypes) throws: Equivalent to stdin.read. See fileReader.read for types

proc readLine(ref a: [] ?t, maxSize = a.size, stripNewline = false): int throws¶: Equivalent to stdin.readLine. See fileReader.readLine

proc readline(arg: [] uint(8), out numRead: int, start = arg.domain.lowBound, amount = arg.domain.highBound - start + 1): bool throws¶: Equivalent to stdin.readline. See fileReader.readline

Warning

readline is deprecated. Use readLine instead

proc readline(ref arg: ?t): bool throws: Equivalent to stdin.readline. See fileReader.readline

Warning

readline is deprecated. Use readLine instead

proc readLine(ref s: string, maxSize = -1, stripNewline = false): bool throws: Equivalent to stdin.readLine. See fileReader.readLine

proc readLine(ref b: bytes, maxSize = -1, stripNewline = false): bool throws: Equivalent to stdin.readLine. See fileReader.readLine

proc readLine(type t = string, maxSize = -1, stripNewline = false): t throws: Equivalent to stdin.readLine. See fileReader.readLine

proc readln(ref args ...?n): bool throws¶: Equivalent to stdin.readln. See fileReader.readln

Warning

‘readln’ is unstable and may be removed or modified in a future release

proc readln(type t ...?numTypes) throws: Equivalent to stdin.readln. See fileReader.readln for types

Warning

‘readln’ is unstable and may be removed or modified in a future release

proc file.localesForRegion(start: int(64), end: int(64))¶

Returns the ‘best’ locale to run something working with the region of the file in start..end-1.

This must return the same result when called from different locales. Returns a domain of locales that are “best” for the given region. If no locales are “best” we return a domain containing all locales.

Arguments

start – the file offset (starting from 0) where the region begins
end – the file offset just after the region

Returns

a set of locales that are best for working with this region

Return type

domain(locale)

Warning

file.localesForRegion is deprecated

IO¶

I/O Overview¶

Design Rationale¶

I/O Styles¶

Files¶

Functions for fileReader and fileWriter Creation¶

Synchronization of fileReader and fileWriter Data and Avoiding Data Races¶

Performing I/O with FileReaders and FileWriters¶

Functions for Closing FileReaders and FileWriters¶

The stdin fileReader, and stdout and stderr fileWriters¶

Error Handling¶

Ensuring Successful I/O¶

Correspondence with C I/O¶

IO Functions and Types¶

The `stdin` fileReader, and `stdout` and `stderr` fileWriters¶