Skip to main content

/

Docs

Log in

Mojo struct

FileHandle

File handle to an opened file.

Fields​

  • ​handle (UnsafePointer[NoneType, 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]): The underlying pointer to the file handle.

Implemented traits​

AnyType

Methods​

__init__​

__init__(inout self: Self)

Default constructor.

__init__(inout self: Self, path: String, mode: String)

Construct the FileHandle using the file path and mode.

Args:

  • ​path (String): The file path.
  • ​mode (String): The mode to open the file in (the mode can be "r" or "w" or "rw").

__init__(inout self: Self, path: StringRef, mode: StringRef)

Construct the FileHandle using the file path and string.

Args:

  • ​path (StringRef): The file path.
  • ​mode (StringRef): The mode to open the file in (the mode can be "r" or "w" or "rw").

__moveinit__​

__moveinit__(inout self: Self, owned existing: Self)

Moves constructor for the file handle.

Args:

  • ​existing (Self): The existing file handle.

__del__​

__del__(owned self: Self)

Closes the file handle.

close​

close(inout self: Self)

Closes the file handle.

read​

read(self: Self, size: SIMD[int64, 1] = -1) -> String

Reads data from a file and sets the file handle seek position. If size is left as the default of -1, it will read to the end of the file. Setting size to a number larger than what's in the file will set String.size to the total number of bytes, and read all the data.

Examples:

Read the entire file into a String:

var file = open("/tmp/example.txt", "r")
var string = file.read()
print(string)
var file = open("/tmp/example.txt", "r")
var string = file.read()
print(string)

Read the first 8 bytes, skip 2 bytes, and then read the next 8 bytes:

import os
var file = open("/tmp/example.txt", "r")
var word1 = file.read(8)
print(word1)
_ = file.seek(2, os.SEEK_CUR)
var word2 = file.read(8)
print(word2)
import os
var file = open("/tmp/example.txt", "r")
var word1 = file.read(8)
print(word1)
_ = file.seek(2, os.SEEK_CUR)
var word2 = file.read(8)
print(word2)

Read the last 8 bytes in the file, then the first 8 bytes

_ = file.seek(-8, os.SEEK_END)
var last_word = file.read(8)
print(last_word)
_ = file.seek(8, os.SEEK_SET) # os.SEEK_SET is the default start of file
var first_word = file.read(8)
print(first_word)
_ = file.seek(-8, os.SEEK_END)
var last_word = file.read(8)
print(last_word)
_ = file.seek(8, os.SEEK_SET) # os.SEEK_SET is the default start of file
var first_word = file.read(8)
print(first_word)

.

Args:

  • ​size (SIMD[int64, 1]): Requested number of bytes to read (Default: -1 = EOF).

Returns:

The contents of the file.

Raises:

An error if this file handle is invalid, or if the file read returned a failure.

read[type: DType](self: Self, ptr: UnsafePointer[SIMD[type, 1], 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1], size: SIMD[int64, 1] = -1) -> SIMD[int64, 1]

Read data from the file into the pointer. Setting size will read up to sizeof(type) * size. The default value of size is -1 which will read to the end of the file. Starts reading from the file handle seek pointer, and after reading adds sizeof(type) * size bytes to the seek pointer.

Examples:

import os

alias file_name = "/tmp/example.txt"
var file = open(file_name, "r")

# Allocate and load 8 elements
var ptr = UnsafePointer[Float32].alloc(8)
var bytes = file.read(ptr, 8)
print("bytes read", bytes)

var first_element = ptr[0]
print(first_element)

# Skip 2 elements
_ = file.seek(2 * sizeof[DType.float32](), os.SEEK_CUR)

# Allocate and load 8 more elements from file handle seek position
var ptr2 = UnsafePointer[Float32].alloc(8)
var bytes2 = file.read(ptr2, 8)

var eleventh_element = ptr2[0]
var twelvth_element = ptr2[1]
print(eleventh_element, twelvth_element)

# Free the memory
ptr.free()
ptr2.free()
import os

alias file_name = "/tmp/example.txt"
var file = open(file_name, "r")

# Allocate and load 8 elements
var ptr = UnsafePointer[Float32].alloc(8)
var bytes = file.read(ptr, 8)
print("bytes read", bytes)

var first_element = ptr[0]
print(first_element)

# Skip 2 elements
_ = file.seek(2 * sizeof[DType.float32](), os.SEEK_CUR)

# Allocate and load 8 more elements from file handle seek position
var ptr2 = UnsafePointer[Float32].alloc(8)
var bytes2 = file.read(ptr2, 8)

var eleventh_element = ptr2[0]
var twelvth_element = ptr2[1]
print(eleventh_element, twelvth_element)

# Free the memory
ptr.free()
ptr2.free()

.

Parameters:

  • ​type (DType): The type that will the data will be represented as.

Args:

  • ​ptr (UnsafePointer[SIMD[type, 1], 0, 0, alignof[::AnyType,__mlir_type.!kgen.target]() if triple_is_nvidia_cuda() else 1]): The pointer where the data will be read to.
  • ​size (SIMD[int64, 1]): Requested number of elements to read.

Returns:

The total amount of data that was read in bytes.

Raises:

An error if this file handle is invalid, or if the file read returned a failure.

read_bytes​

read_bytes(self: Self, size: SIMD[int64, 1] = -1) -> List[SIMD[uint8, 1], 0]

Reads data from a file and sets the file handle seek position. If size is left as default of -1, it will read to the end of the file. Setting size to a number larger than what's in the file will be handled and set the List.size to the total number of bytes in the file.

Examples:

Reading the entire file into a List[Int8]:

var file = open("/tmp/example.txt", "r")
var string = file.read_bytes()
var file = open("/tmp/example.txt", "r")
var string = file.read_bytes()

Reading the first 8 bytes, skipping 2 bytes, and then reading the next 8 bytes:

import os
var file = open("/tmp/example.txt", "r")
var list1 = file.read(8)
_ = file.seek(2, os.SEEK_CUR)
var list2 = file.read(8)
import os
var file = open("/tmp/example.txt", "r")
var list1 = file.read(8)
_ = file.seek(2, os.SEEK_CUR)
var list2 = file.read(8)

Reading the last 8 bytes in the file, then the first 8 bytes:

import os
var file = open("/tmp/example.txt", "r")
_ = file.seek(-8, os.SEEK_END)
var last_data = file.read(8)
_ = file.seek(8, os.SEEK_SET) # os.SEEK_SET is the default start of file
var first_data = file.read(8)
import os
var file = open("/tmp/example.txt", "r")
_ = file.seek(-8, os.SEEK_END)
var last_data = file.read(8)
_ = file.seek(8, os.SEEK_SET) # os.SEEK_SET is the default start of file
var first_data = file.read(8)

.

Args:

  • ​size (SIMD[int64, 1]): Requested number of bytes to read (Default: -1 = EOF).

Returns:

The contents of the file.

Raises:

An error if this file handle is invalid, or if the file read returned a failure.

seek​

seek(self: Self, offset: SIMD[uint64, 1], whence: SIMD[uint8, 1] = 0) -> SIMD[uint64, 1]

Seeks to the given offset in the file.

Examples:

Skip 32 bytes from the current read position:

import os
var f = open("/tmp/example.txt", "r")
_ = f.seek(32, os.SEEK_CUR)
import os
var f = open("/tmp/example.txt", "r")
_ = f.seek(32, os.SEEK_CUR)

Start from 32 bytes from the end of the file:

import os
var f = open("/tmp/example.txt", "r")
_ = f.seek(-32, os.SEEK_END)
import os
var f = open("/tmp/example.txt", "r")
_ = f.seek(-32, os.SEEK_END)

.

Args:

  • ​offset (SIMD[uint64, 1]): The byte offset to seek to.
  • ​whence (SIMD[uint8, 1]): The reference point for the offset: os.SEEK_SET = 0: start of file (Default). os.SEEK_CUR = 1: current position. os.SEEK_END = 2: end of file.

Returns:

The resulting byte offset from the start of the file.

Raises:

An error if this file handle is invalid, or if file seek returned a failure.

write​

write(self: Self, data: String)

Write the data to the file.

Args:

  • ​data (String): The data to write to the file.

write(self: Self, data: Span[is_mutable, SIMD[uint8, 1], lifetime])

Write a borrowed sequence of data to the file.

Args:

  • ​data (Span[is_mutable, SIMD[uint8, 1], lifetime]): The data to write to the file.

write(self: Self, data: StringRef)

Write the data to the file.

Args:

  • ​data (StringRef): The data to write to the file.

__enter__​

__enter__(owned self: Self) -> Self

The function to call when entering the context.

Returns:

The file handle.

Was this page helpful?