RandomAccessFile abstract interface

abstract interface class RandomAccessFile

Random access to the data in a file.

RandomAccessFile objects are obtained by calling the open method on a File object.

A RandomAccessFile has both asynchronous and synchronous methods. The asynchronous methods all return a Future whereas the synchronous methods will return the result directly, and block the current isolate until the result is ready.

At most one asynchronous method can be pending on a given RandomAccessFile instance at the time. If another asynchronous method is called when one is already in progress, a FileSystemException is thrown.

If an asynchronous method is pending, it is also not possible to call any synchronous methods. This will also throw a FileSystemException.

Properties

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

path no setter

String get path

The path of the file underlying this random access file.

Implementation

String get path;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

close()

Future<void> close()

Closes the file.

Returns a Future that completes when it has been closed.

Implementation

Future<void> close();

closeSync()

void closeSync()

Synchronously closes the file.

Throws a FileSystemException if the operation fails.

Implementation

void closeSync();

flush()

Future<RandomAccessFile> flush()

Flushes the contents of the file to disk.

Returns a Future<RandomAccessFile> that completes with this random access file when the flush operation completes.

Implementation

Future<RandomAccessFile> flush();

flushSync()

void flushSync()

Synchronously flushes the contents of the file to disk.

Throws a FileSystemException if the operation fails.

Implementation

void flushSync();

length()

Future<int> length()

Gets the length of the file.

Returns a Future<int> that completes with the length in bytes.

Implementation

Future<int> length();

lengthSync()

int lengthSync()

Synchronously gets the length of the file.

Throws a FileSystemException if the operation fails.

Implementation

int lengthSync();

lock()

Future<RandomAccessFile> lock([
  FileLock mode = FileLock.exclusive,
  int start = 0,
  int end = -1,
])

Locks the file or part of the file.

By default an exclusive lock will be obtained, but that can be overridden by the mode argument.

Locks the byte range from start to end of the file, with the byte at position end not included. If no arguments are specified, the full file is locked, If only start is specified the file is locked from byte position start to the end of the file, no matter how large it grows. It is possible to specify an explicit value of end which is past the current length of the file.

To obtain an exclusive lock on a file, it must be opened for writing.

If mode is FileLock.exclusive or FileLock.shared, an error is signaled if the lock cannot be obtained. If mode is FileLock.blockingExclusive or FileLock.blockingShared, the returned Future is resolved only when the lock has been obtained.

NOTE file locking does have slight differences in behavior across platforms:

On Linux and OS X this uses advisory locks, which have the surprising semantics that all locks associated with a given file are removed when any file descriptor for that file is closed by the process. Note that this does not actually lock the file for access. Also note that advisory locks are on a process level. This means that several isolates in the same process can obtain an exclusive lock on the same file.

On Windows the regions used for lock and unlock needs to match. If that is not the case unlocking will result in the OS error "The segment is already unlocked".

On Windows, locking a file associates the lock with the specific file handle used to acquire the lock. If the same file is opened again with a different handle (even within the same process), attempts to write to the locked region using the new handle will fail. To ensure successful writes after locking, use the same RandomAccessFile object that acquired the lock for subsequent write operations.

Implementation

Future<RandomAccessFile> lock([
  FileLock mode = FileLock.exclusive,
  int start = 0,
  int end = -1,
]);

lockSync()

void lockSync([FileLock mode = FileLock.exclusive, int start = 0, int end = -1])

Synchronously locks the file or part of the file.

By default an exclusive lock will be obtained, but that can be overridden by the mode argument.

Locks the byte range from start to end of the file ,with the byte at position end not included. If no arguments are specified, the full file is locked, If only start is specified the file is locked from byte position start to the end of the file, no matter how large it grows. It is possible to specify an explicit value of end which is past the current length of the file.

To obtain an exclusive lock on a file it must be opened for writing.

If mode is FileLock.exclusive or FileLock.shared, an exception is thrown if the lock cannot be obtained. If mode is FileLock.blockingExclusive or FileLock.blockingShared, the call returns only after the lock has been obtained.

NOTE file locking does have slight differences in behavior across platforms:

On Linux and OS X this uses advisory locks, which have the surprising semantics that all locks associated with a given file are removed when any file descriptor for that file is closed by the process. Note that this does not actually lock the file for access. Also note that advisory locks are on a process level. This means that several isolates in the same process can obtain an exclusive lock on the same file.

On Windows the regions used for lock and unlock needs to match. If that is not the case unlocking will result in the OS error "The segment is already unlocked".

On Windows, locking a file associates the lock with the specific file handle used to acquire the lock. If the same file is opened again with a different handle (even within the same process), attempts to write to the locked region using the new handle will fail. To ensure successful writes after locking, use the same RandomAccessFile object that acquired the lock for subsequent write operations.

Implementation

void lockSync([
  FileLock mode = FileLock.exclusive,
  int start = 0,
  int end = -1,
]);

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

position()

Future<int> position()

Gets the current byte position in the file.

Returns a Future<int> that completes with the position.

Implementation

Future<int> position();

positionSync()

int positionSync()

Synchronously gets the current byte position in the file.

Throws a FileSystemException if the operation fails.

Implementation

int positionSync();

read()

Future<Uint8List> read(int count)

Reads up to count bytes from a file.

May return fewer than count bytes. This can happen, for example, when reading past the end of a file or when reading from a pipe that does not currently contain additional data.

An empty Uint8List will only be returned when reading past the end of the file or when count is 0.

Implementation

Future<Uint8List> read(int count);

readByte()

Future<int> readByte()

Reads a byte from the file.

Returns a Future<int> that completes with the byte, or with -1 if end-of-file has been reached.

Implementation

Future<int> readByte();

readByteSync()

int readByteSync()

Synchronously reads a single byte from the file.

If end-of-file has been reached -1 is returned.

Throws a FileSystemException if the operation fails.

Implementation

int readByteSync();

readInto()

Future<int> readInto(List<int> buffer, [int start = 0, int? end])

Reads bytes into an existing buffer.

Reads bytes and writes them into the range of buffer from start to end. The start must be non-negative and no greater than buffer.length. If end is omitted, it defaults to buffer.length. Otherwise end must be no less than start and no greater than buffer.length.

Returns the number of bytes read. This maybe be less than end - start if the file doesn't have that many bytes to read.

Implementation

Future<int> readInto(List<int> buffer, [int start = 0, int? end]);

readIntoSync()

int readIntoSync(List<int> buffer, [int start = 0, int? end])

Synchronously reads into an existing buffer.

Reads bytes and writes them into the range of buffer from start to end. The start must be non-negative and no greater than buffer.length. If end is omitted, it defaults to buffer.length. Otherwise end must be no less than start and no greater than buffer.length.

Returns the number of bytes read. This maybe be less than end - start if the file doesn't have that many bytes to read.

Throws a FileSystemException if the operation fails.

Implementation

int readIntoSync(List<int> buffer, [int start = 0, int? end]);

readSync()

Uint8List readSync(int count)

Synchronously reads up to count bytes from a file

May return fewer than count bytes. This can happen, for example, when reading past the end of a file or when reading from a pipe that does not currently contain additional data.

An empty Uint8List will only be returned when reading past the end of the file or when count is 0.

Throws a FileSystemException if the operation fails.

Implementation

Uint8List readSync(int count);

setPosition()

Future<RandomAccessFile> setPosition(int position)

Sets the byte position in the file.

Returns a Future<RandomAccessFile> that completes with this random access file when the position has been set.

Implementation

Future<RandomAccessFile> setPosition(int position);

setPositionSync()

void setPositionSync(int position)

Synchronously sets the byte position in the file.

Throws a FileSystemException if the operation fails.

Implementation

void setPositionSync(int position);

toString() override

String toString()

Returns a human-readable string for this random access file.

Implementation

String toString();

truncate()

Future<RandomAccessFile> truncate(int length)

Truncates (or extends) the file to length bytes.

Returns a Future<RandomAccessFile> that completes with this random access file when the truncation has been performed.

Implementation

Future<RandomAccessFile> truncate(int length);

truncateSync()

void truncateSync(int length)

Synchronously truncates (or extends) the file to length bytes.

Throws a FileSystemException if the operation fails.

Implementation

void truncateSync(int length);

unlock()

Future<RandomAccessFile> unlock([int start = 0, int end = -1])

Unlocks the file or part of the file.

Unlocks the byte range from start to end of the file, with the byte at position end not included. If no arguments are specified, the full file is unlocked, If only start is specified the file is unlocked from byte position start to the end of the file.

NOTE file locking does have slight differences in behavior across platforms:

See lock for more details.

Implementation

Future<RandomAccessFile> unlock([int start = 0, int end = -1]);

unlockSync()

void unlockSync([int start = 0, int end = -1])

Synchronously unlocks the file or part of the file.

Unlocks the byte range from start to end of the file, with the byte at position end not included. If no arguments are specified, the full file is unlocked, If only start is specified the file is unlocked from byte position start to the end of the file.

NOTE file locking does have slight differences in behavior across platforms:

See lockSync for more details.

Implementation

void unlockSync([int start = 0, int end = -1]);

writeByte()

Future<RandomAccessFile> writeByte(int value)

Writes a single byte to the file.

Returns a Future<RandomAccessFile> that completes with this random access file when the write completes.

Implementation

Future<RandomAccessFile> writeByte(int value);

writeByteSync()

int writeByteSync(int value)

Synchronously writes a single byte to the file.

Returns 1 on success.

Throws a FileSystemException if the operation fails.

Implementation

int writeByteSync(int value);

writeFrom()

Future<RandomAccessFile> writeFrom(List<int> buffer, [int start = 0, int? end])

Writes from a buffer to the file.

Will read the buffer from index start to index end. The start must be non-negative and no greater than buffer.length. If end is omitted, it defaults to buffer.length. Otherwise end must be no less than start and no greater than buffer.length.

Returns a Future<RandomAccessFile> that completes with this RandomAccessFile when the write completes.

Implementation

Future<RandomAccessFile> writeFrom(
  List<int> buffer, [
  int start = 0,
  int? end,
]);

writeFromSync()

void writeFromSync(List<int> buffer, [int start = 0, int? end])

Synchronously writes from a buffer to the file.

Will read the buffer from index start to index end. The start must be non-negative and no greater than buffer.length. If end is omitted, it defaults to buffer.length. Otherwise end must be no less than start and no greater than buffer.length.

Throws a FileSystemException if the operation fails.

Implementation

void writeFromSync(List<int> buffer, [int start = 0, int? end]);

writeString()

Future<RandomAccessFile> writeString(String string, {Encoding encoding = utf8})

Writes a string to the file using the given Encoding.

Returns a Future<RandomAccessFile> that completes with this random access file when the write completes.

Implementation

Future<RandomAccessFile> writeString(
  String string, {
  Encoding encoding = utf8,
});

writeStringSync()

void writeStringSync(String string, {Encoding encoding = utf8})

Synchronously writes a single string to the file using the given Encoding.

Throws a FileSystemException if the operation fails.

Implementation

void writeStringSync(String string, {Encoding encoding = utf8});

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);