Structs

struct FileDescriptor

public struct FileDescriptor

Description: Obtains the file handle information.

NOTE

A file handle is a data structure allocated by an operating system to trace a file, and is used to identify an instance for opening the file. A file handle contains the metadata (such as the file name, path, size, and modification time) of a file and the physical location of the file data on the disk. The file handle format may vary according to the operating system. In Unix and Linux, the file handle is usually a non-negative integer, which is allocated by the operating system kernel and returned to the application when the file is opened. In Windows, the file handle is usually a pointer to a file object. It is allocated by the operating system kernel and returned to the application when the file is opened. A file handle, regardless of its format, can be used by applications to read, write, and modify files.

prop fileHandle

public prop fileHandle: IntNative

Description: Obtains file handle information.

Type: IntNative

struct FileInfo

public struct FileInfo <: Equatable<FileInfo> {
    public init(path: Path)
    public init(path: String)
}

Description: Obtains the file metadata in a file system.

NOTE

File metadata refers to file-related information in a file system, including the name, size, creation time, modification time, access time, and owner of as well as permissions on a file.

The underlying implementation of FileInfo does not support direct file attribute cache. Each API calling FileInfo obtains the latest file attribute.

Note that when the file attribute is obtained twice by using the same FileInfo instance, if the file entity is modified or replaced by another user or process, the file attribute obtained later may not be the expected one. For the same FileInfo instance, the corresponding file entity may be modified or replaced by another user or process during the interval between two adjacent operations of obtaining the file attribute of the instance, so that the file attribute obtained later may not be the expected one. To avoid this problem, you can set file permissions or lock key file operations.

Parent types:

prop creationTime

public prop creationTime: DateTime

Description: Obtains the creation time.

Type: DateTime

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

prop lastAccessTime

public prop lastAccessTime: DateTime

Description: Obtains the last access time.

Type: DateTime

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

prop lastModificationTime

public prop lastModificationTime: DateTime

Description: Obtains the last modification time.

Type: DateTime

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

prop name

public prop name: String

Description: Obtains the file name or directory name corresponding to the current instance.

This property is equivalent to this.path.fileName. For details about the path parsing rules, see the fileName property of the path structure.

Type: String

prop parentDirectory

public prop parentDirectory: Option<FileInfo>

Description: Obtains the metadata of the parent directory and returns the metadata in Option<FileInfo> format. If there is a parent directory, Option<FileInfo>.Some(v) is returned. Otherwise, Option<FileInfo>.None is returned.

Type: Option<FileInfo>

prop path

public prop path: Path

Description: Obtains the file path and returns it in path format.

Type: Path

prop size

public prop size: Int64

Description: Returns the current file size.

  • For a file, the value indicates the size of the disk space occupied by a single file.
  • For a directory, the value indicates the size of the disk space occupied by all files in the directory.

Type: Int64

Throws:

  • FSException: If an error occurs in the system API called at the bottom layer during the check, this exception is thrown.

init(Path)

public init(path: Path)

Description: Creates a FileInfo instance.

Parameters:

  • path: Path: directory path in the Path format

Throws:

init(String)

public init(path: String)

Description: Creates a FileInfo instance.

Parameters:

Throws:

func canExecute()

public func canExecute(): Bool

Description: Checks whether a user has the permission to execute the file corresponding to the instance.

  • For a file, checks whether a user has the permission to execute the file.
  • For a directory, checks whether a user has the permission to access the directory.
  • In Windows, the file name extension determines a user's permission to execute files. The user always has the permission to execute a directory. No operation is performed and true is returned.
  • In Linux and macOS, this function works normally.

Returns:

  • Bool: If the user has the permission. true is returned. If the user has no permission, false is returned.

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func canRead()

public func canRead(): Bool

Description: Checks whether a user has the permission to read the file corresponding to the instance.

  • For a file, checks whether a user has the permission to read the file.
  • For a directory, checks whether a user has the permission to browse the directory.
  • In Windows, a user always has the read permission on the file and directory. No operation is performed and true is returned.
  • In Linux and macOS, this function works normally.

Returns:

  • Bool: If the user has the permission. true is returned. If the user has no permission, false is returned.

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func canWrite()

public func canWrite(): Bool

Description: Checks whether a user has the permission to write the file corresponding to the instance.

  • For a file, checks whether a user has the permission to write the file.
  • For a directory, checks whether a user has the permission to delete, move, and create files in a directory.
  • In Windows, a user can write files normally and always has the write permission on the directory. No operation is performed and true is returned.
  • In Linux and macOS, this function works normally.

Returns:

  • Bool: If the user has the permission. true is returned. If the user has no permission, false is returned.

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func isDirectory()

public func isDirectory(): Bool

Description: Checks whether a file is a directory.

Returns:

  • Bool: true: yes, false: no

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func isRegular()

public func isRegular(): Bool

Description: Checks whether a file is a common file.

Returns:

  • Bool: true: yes, false: no

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func isHidden()

public func isHidden(): Bool

Description: Checks whether a file is hidden.

Returns:

  • Bool: true: yes, false: no

func isReadOnly()

public func isReadOnly(): Bool

Description: Checks whether a file is read-only.

  • In Windows, the read-only permission on a file is effective and a user always has the permission to delete or modify the directory. No operation is performed and false is returned.
  • In Linux and macOS, this function works normally.

Returns:

  • Bool: true: yes, false: no

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.
public func isSymbolicLink(): Bool

Description: Checks whether a file is a soft link.

Returns:

  • Bool: If the file is a soft link, true is returned; if the file is not a soft link, false is returned.

Throws:

  • FSException: If an error occurs in the system interface called at the underlying layer, this exception is thrown.

func setExecutable(Bool)

public func setExecutable(executable: Bool): Bool

Description: Sets whether the permission to execute a file corresponding to the current instance is granted for a user. If the user does not have the permission to modify the system permissions, an exception is thrown.

  • For a file, whether the permission to execute the file is granted for a user. For a directory, whether the permission to access the directory is granted for a user.
  • In Windows, the file name extension determines a user's permission to execute the file, and the user always has the permission to execute a directory. No operation is performed and false is returned.
  • In Linux and macOS, this function works normally. If the file entity corresponding to FileInfo is modified by other users or processes when this function is called, other modifications may not take effect due to the race condition.

Parameters:

  • executable: Bool: whether the user can execute the file

Returns:

  • Bool: If the operation is successful, true is returned. If the operation fails, false is returned.

func setReadable(Bool)

public func setReadable(readable: Bool): Bool

Description: Sets whether the read permission on a file corresponding to the current instance is granted for a user. If the user does not have the permission to modify the system permissions, an exception is thrown.

  • For a file, sets whether a user has the permission to read the file.
  • For a directory, sets whether a user has the permission to browse the directory.
  • In Windows, a user always has the read permission on files and directories and such read permission cannot be modified. No operation is performed. If readable is set to true, true is returned. If readable is set to false, false is returned.
  • In Linux and macOS, this function works normally. If the file entity corresponding to FileInfo is modified by other users or processes when this function is called, other modifications may not take effect due to the race condition.

Parameters:

  • readable: Bool: whether a user can read the file

Returns:

  • Bool: If the operation is successful, true is returned. If the operation fails, false is returned.

func setWritable(Bool)

public func setWritable(writable: Bool): Bool

Description: Sets whether the write permission on a file corresponding to the current instance is granted for a user. If the user does not have the permission to modify the system permissions, an exception is thrown.

  • For a file, sets whether a user has the permission to write the file.
  • For a directory, sets whether a user has the permission to delete, move, and create files in a directory.
  • In Windows, a user can write files normally and always has the write permission on directories and such write permission cannot be modified. No operation is performed and false is returned.
  • In Linux and macOS, this function works normally. If the file entity corresponding to FileInfo is modified by other users or processes when this function is called, other modifications may not take effect due to the race condition.

Parameters:

  • writable: Bool: whether a user can write the file

Returns:

  • Bool: If the operation is successful, true is returned. If the operation fails, false is returned.

operator func ==(FileInfo)

public operator func ==(that: FileInfo): Bool

Description: Checks whether the current FileInfo and the other FileInfo correspond to the same file.

Parameters:

Returns:

  • Bool: true: yes, false: no

struct Path

public struct Path <: Equatable<Path> & Hashable & ToString {
    public static const Separator: String = PATH_SEPARATOR
    public static const ListSeparator: String = PATH_LISTSEPARATOR
    public init(rawPath: String)
}

Description: Provides path-related functions.

Path indicates the local path. (Windows supports the DOS device path and UNC path. The length limit is the same as that set in system settings.) The path string can contain a maximum of 4096 bytes (including the terminator\0).

NOTE

An invalid path is one of the following:

  • A path containing invalid characters, such as spaces, tabs, and newline characters
  • A path containing invalid characters, such as special characters and control characters
  • A path containing a directory or file that does not exist
  • A path containing a directory or file that cannot be accessed. For example, the permission is insufficient or the directory or file is locked.

Enter a valid path without invalid characters so that the target file or directory can be accessed correctly.

Parent types:

static const ListSeparator

public static const ListSeparator: String = PATH_LISTSEPARATOR

Description: Obtains a path list separator, which is used to separate different paths in a path list.

In Windows, the paths are separated by semicolons (;). In non-Windows, the paths are separated by colons (:).

Type: String

static const Separator

public static const Separator: String = PATH_SEPARATOR

Description: Obtains a path separator, which is used to separate multiple levels of directories.

In Windows, the directories are separated by "\". In non-Windows, the directories are separated by "/".

Type: String

prop extensionName

public prop extensionName: String

Description: Obtains the file name extension of Path.

fileName is divided into fileNameWithoutExtension (without the extension name) and extensionName (extension name) based on the last r'.'. If no extension name exists, an empty string is returned.

  • For the path "./NewFile.txt", "txt" is returned.
  • For the path "./.gitignore", "gitignore" is returned.
  • For the path "./noextension", "" is returned.
  • For the path "./a.b.c", "c" is returned.
  • For the path "./NewFile.txt/", "txt" is returned.

Type: String

Throws:

prop fileName

public prop fileName: Option<String>

Description: Obtains the file name (including the file name extension) of Path.

The entire path string is divided into parent and fileName. For details, see parent. If no file name exists, an empty string is returned.

The following examples apply to all systems:

  • For the path "./NewFile.txt", "NewFile.txt" is returned.
  • For the path "./.gitignore", ".gitignore" is returned.
  • For the path "./noextension", "noextension" is returned.
  • For the path "./a.b.c", "a.b.c" is returned.
  • For the path "./NewDir/", "NewDir" is returned.

In the Windows file system, fileName does not include the volume name.

The following examples apply only to Windows:

  • For the path "c:\a.txt", "a.txt" is returned.
  • For the path "c:", "" is returned.
  • For the path "\\Server\Share\a.txt", "a.txt" is returned.
  • For the path "\\Server\Share\", "" is returned.
  • For the path "\\?\C:a\b.txt", "b.txt" is returned.
  • For the path "\\?\C:", "" is returned.

Type: String

Throws:

prop fileNameWithoutExtension

public prop fileNameWithoutExtension: String

Description: Obtains the file name (excluding the file name extension) of Path.

fileName is divided into fileNameWithoutExtension (without the extension name) and extensionName (extension name) based on the last r'.'. If no file name (without the extension name) exists, an empty string is returned.

  • For the path "./NewFile.txt", "NewFile" is returned.
  • For the path "./.gitignore", "" is returned.
  • For the path "./noextension", "noextension" is returned.
  • For the path "./a.b.c", "a.b" is returned.
  • For the path "./NewFile/", "NewFile" is returned.

Type: String

Throws:

prop parent

public prop parent: Path

Description: Obtains the parent path of the path instance.

The entire path string is divided into parent and fileName, and the last valid file separator (excluding the separator at the end) is used as the boundary. If parent does not exist, the path instance constructed by an empty string is returned. parent and fileName do not contain the separator at the end. parent retains the separator indicating the root directory. If no parent directory exists, an empty path instance is returned.

This property does not access the file system or eliminate special names. It can be used together with normalization if necessary.

This property has different behaviors on different operating systems. In Windows, the file separator is "\" or "/" (which will be converted to "\" during normalization). In Linux, macOS, and OHOS, the file separator is "/".

The following examples apply to all systems:

  • For the path "/a/b/c", Path("/a/b") is returned.
  • For the path "/a/b/", Path("/a") is returned.
  • For the path "/a", Path("/") is returned.
  • For the path "/", Path("/") is returned.
  • For the path "./a/b", Path("./a") is returned.
  • For the path "./", Path("") is returned.
  • For the path ".gitignore", Path("") is returned.
  • For the path "/a/./../b", Path("/a/./..") is returned.

In addition, in Windows, the path contains the volume name, directory name, and file name. For details, see the Microsoft documentation. The property parent contains the volume name and directory name.

The following examples apply only to Windows:

  • For the path "C:", Path("C:") is returned.
  • For the path "C:\a\b", Path("C:\a") is returned.
  • For the path "\\Server\Share\xx\yy", Path("\\Server\Share\xx") is returned.
  • For the path "\\?\UNC\Server\Share\xx\yy", Path("\\?\UNC\Server\Share\xx") is returned.
  • For the path "\\?\c:\xx\yy", Path("\\?\c:\xx") is returned.

Type: Path

Throws:

init(String)

public init(rawPath: String)

Description: When a path instance is created, the validity of the path (including the absolute and relative path) string is not checked.

Parameters:

  • rawPath: String: string of the path

func hashCode()

public func hashCode(): Int64

Description: Obtains the hash value of Path.

Returns:

func isAbsolute()

public func isAbsolute(): Bool

Description: Checks whether Path is an absolute path. In Unix, the path starting with / is an absolute path.

Returns:

  • Bool: true: yes, false: no

Throws:

func isEmpty()

public func isEmpty(): Bool

Description: Checks whether the current instance is an empty path.

Returns:

  • Bool: If the current instance is an empty path, true is returned. Otherwise, false is returned.

func isRelative()

public func isRelative(): Bool

Description: Checks whether Path is a relative path. The result is opposite to that of the isAbsolute function.

Returns:

  • Bool: true: yes, false: no

Throws:

func join(Path)

public func join(path: Path): Path

Description: Concatenates another path string after the current path to form a new path.

  • If "c" is concatenated after "a/b", "a/b/c" is returned.
  • If "b/c" is concatenated after "a", "a/b/c" is returned.

Returns:

Throws:

  • FSException: If path is an absolute path, this exception is thrown.
  • IllegalArgumentException: If the current path is empty or the current path or input parameter path is invalid, this exception is thrown.

func join(String)

public func join(path: String): Path

Description: Concatenates another path string after the current path to form a new path.

  • If "c" is concatenated after "a/b", "a/b/c" is returned.
  • If "b/c" is concatenated after "a", "a/b/c" is returned.

Returns:

Throws:

  • FSException: If path is an absolute path, this exception is thrown.
  • IllegalArgumentException: If the current path is empty or the current path or input parameter path is invalid, this exception is thrown.

func normalize()

public func normalize(): Path

Description: Normalizes a path string and constructs a new path instance using the normalized string. This function is used only for string parsing and does not perform I/O operations.

Normalization rules:

  • Replace multiple consecutive path separators with a single path separator.
  • Delete the path separator at the end (excluding the characters in the path separator or volume name that is used as the root directory).
  • Delete each path name element "." (indicating the current directory).
  • Delete the path name element ".." (indicating the parent directory) in each path and the path name element which is not ".." before it.
  • Delete the path name element ".." that starts from the root path, that is, replace "/.." at the beginning of the path with "/". (In Windows, replace "\.." with "\".)
  • Retain "../" at the beginning of the relative path. (In Windows, retain "..\".)
  • If an empty path is obtained, Path(".") is returned.

In the Windows file system, only the separator in the volume name is converted, that is, "/" is converted to "\".

Returns:

func toString()

public func toString(): String

Description: Obtains the path string of Path.

Returns:

operator func ==(Path)

public operator func ==(that: Path): Bool

Description: Checks whether two path instances are the same.

During the check, the path instances are normalized. If the normalized strings are the same, the two path instances are considered equal. For details about the normalization rules, see the function normalize.

Parameters:

Returns:

  • Bool: true: yes, false: no