v1.2.0.1-beta1
List of all members
File
File System

Description

The File class provides access to... files. Shocking.

It has many static functions which are accessed in JS with the File. qualifier. These are "atomic" operations, eg. read a whole file at once or check if a file name exists, etc.

Note
On Windows all file path arguments passed to functions in this class can use the / directory separator (recommended) as well as \ (which needs to be escaped as "\\"" per JS syntax rules).

Public Member Functions

ArrayBuffer read (String &file, ::FS::OpenMode mode=O_TEXT)
 
ArrayBuffer read (String &file, String &mode)
 
String readText (String &file)
 
String readLines (String &file, int maxLines, int fromLine=0, bool trimTrailingNewlines=true)
 
int write (String &file, ArrayBuffer &data, ::FS::OpenMode mode=O_TEXT)
 
int write (String &file, ArrayBuffer &data, String &mode)
 
bool remove (String &file)
 
bool rename (String &from, String &to)
 
bool copy (String &from, String &to)
 
bool link (String &fileName, String &linkName)
 
bool exists (String &file)
 
bool isFile (String &path)
 
bool isDir (String &path)
 
bool isReadable (String &file)
 
bool isWritable (String &file)
 
bool isAbs (String &file)
 
bool isExec (String &file)
 
String path (String &file)
 
String name (String &file)
 
String filePath (String &file)
 
String baseName (String &file)
 
String fullBaseName (String &file)
 
String suffix (String &file)
 
String fullSuffix (String &file)
 
String absPath (String &path)
 
String absFilePath (String &file)
 
String normPath (String &path)
 
String normFilePath (String &file)
 
uint size (String &file)
 
Date btime (String &file)
 
Date mtime (String &file)
 
Date atime (String &file)
 
Date ctime (String &file)
 
::FS::Permissions permissions (String &file)
 
bool setPermissions (String &file, ::FS::Permissions p)
 

Member Function Documentation

◆ read() [1/2]

ArrayBuffer read ( String &  file,
::FS::OpenMode  mode = O_TEXT 
)

Reads a file and returns the contents as a byte array. Set mode to FS.O_BIN to read in binary mode. Default is to read as text.

Exceptions
ReferenceErroris thrown if file loading fails (file not found/etc) and returns and empty string.

◆ read() [2/2]

ArrayBuffer read ( String &  file,
String &  mode 
)

Reads a file and returns the contents as a byte array. Set mode to 'b' to read in binary mode. Default is to read as text.

Exceptions
ReferenceErroris thrown if file loading fails (file not found/etc) and returns and empty string.

◆ readText()

String readText ( String &  file)

Reads a file in text mode and returns the contents as a string. This is a convenience method which is equivalent to calling String(File.read(file));

Exceptions
ReferenceErroris thrown if file loading fails (file not found/etc) and returns and empty string.

◆ readLines()

String readLines ( String &  file,
int  maxLines,
int  fromLine = 0,
bool  trimTrailingNewlines = true 
)

Reads up to maxLines lines from file starting at fromLine (default = 0, start of file) and returns the contents as a string. Can search from start or end of file.
maxLines can be 0 in which case all remaining lines in the file are returned. This is useful when fromLine != 0 to skip a number of lines and then return the rest.
fromLine can be negative, in which case the file will be read from the end, backwards. In this case -1 means starting at the end of the file, -2 means to skip one line ("start at second-to-last line"), and so on.
Set trimTrailingNewlines to true (default) to trim/skip over any empty lines from the end of the file. When searching backwards, setting trimTrailingNewlines to false will count every newline from the end, including any potential newline at end of the last line of the file.

Exceptions
ReferenceErroris thrown if file loading fails (file not found/etc) and returns and empty string.
Note
Note that if no newlines are found in the file then the full contents will be returned (a potentially expensive operation). This operation works on all text files regardless of line endings.

◆ write() [1/2]

int write ( String &  file,
ArrayBuffer &  data,
::FS::OpenMode  mode = O_TEXT 
)

Writes data to file and returns the number of bytes written. Returns -1 on error. mode flags can be a combination of FileLib::OpenModeFlag enums:

  • FS.O_BIN write in binary mode (default is to write as text).
  • FS.O_APPEND to append to file (default is to truncate/replace it).
  • FS.O_EXCL to fail if the file exists, or FS.O_NOCREAT to to fail if the file doesn't already exist (both will return an error if the condition isn't met).
Exceptions
Erroris thrown if the file writing fails for any reason.

◆ write() [2/2]

int write ( String &  file,
ArrayBuffer &  data,
String &  mode 
)

Writes data to file and returns the number of bytes written. Returns -1 on error. mode flags can be a combination of the following (in any order):

  • b write in binary mode (default is to write as text).
  • a to append to file (default is to truncate/replace it).
  • x to fail if the file exists, or n to to fail if the file doesn't already exist (both will return an error if the condition isn't met).
Exceptions
Erroris thrown if the file writing fails for any reason.

◆ remove()

bool remove ( String &  file)

Removes the file specified by file. Returns true if successful; otherwise returns false.

◆ rename()

bool rename ( String &  from,
String &  to 
)

Renames the from file to a file specified in to. Returns true if successful; otherwise returns false. If a file with the name to already exists, rename() returns false.

◆ copy()

bool copy ( String &  from,
String &  to 
)

Copies the from file to a file specified in to. Returns true if successful; otherwise returns false. If a file with the name to already exists, copy() returns false.

◆ link()

bool link ( String &  fileName,
String &  linkName 
)

Creates a link named linkName that points to the file fileName. What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Unix). Returns true if successful; otherwise returns false.

◆ exists()

bool exists ( String &  file)

Returns true if the file exists; otherwise returns false.

◆ isFile()

bool isFile ( String &  path)

Returns true if this object points to a file or to a symbolic link to a file. Returns false if the object points to something which isn't a file, such as a directory.

◆ isDir()

bool isDir ( String &  path)

Returns true if this object points to a directory or to a symbolic link to a directory; otherwise returns false.

◆ isReadable()

bool isReadable ( String &  file)

Returns true if the user can read the file; otherwise returns false.

◆ isWritable()

bool isWritable ( String &  file)

Returns true if the user can write to the file; otherwise returns false.

◆ isAbs()

bool isAbs ( String &  file)

Returns true if the file path name is absolute, otherwise returns false if the path is relative.

◆ isExec()

bool isExec ( String &  file)

Returns true if the file is executable; otherwise returns false.

◆ path()

String path ( String &  file)

Returns the file's path, excluding the file name.

◆ name()

String name ( String &  file)

Returns the name of a file (with suffix), excluding the path.

◆ filePath()

String filePath ( String &  file)

Returns the file name, including the path (which may be absolute or relative).

◆ baseName()

String baseName ( String &  file)

Returns the base name of the file without the path. The base name consists of all characters in the file up to (but not including) the first '.' character.

◆ fullBaseName()

String fullBaseName ( String &  file)

Returns the complete base name of the file without the path. The full base name consists of all characters in the file up to (but not including) the last '.' character.

◆ suffix()

String suffix ( String &  file)

Returns the suffix (extension) of the file. The suffix consists of all characters in the file after (but not including) the last '.'.

◆ fullSuffix()

String fullSuffix ( String &  file)

Returns the "full" suffix (extension) of the file. The full suffix consists of all characters in the file after (but not including) the first '.'.

◆ absPath()

String absPath ( String &  path)

Returns the file's absolute path, excluding the file name.

◆ absFilePath()

String absFilePath ( String &  file)

Returns the file's absolute path, including the file name (with extension).

◆ normPath()

String normPath ( String &  path)

Returns the file's path canonical path (excluding the file name), i.e. an absolute path without symbolic links or redundant "." or ".." elements.

◆ normFilePath()

String normFilePath ( String &  file)

Returns the canonical path including the file name, i.e. an absolute path without symbolic links or redundant "." or ".." elements.

◆ size()

uint size ( String &  file)

Returns the file size in bytes. If the file does not exist or cannot be fetched, 0 is returned.

◆ btime()

Date btime ( String &  file)

Returns the date and time when the file was created / born. If the file birth time is not available, this function returns an invalid Date object.

◆ mtime()

Date mtime ( String &  file)

Returns the date and local time when the file was last modified. If the file is not available, this function returns an invalid Date object.

◆ atime()

Date atime ( String &  file)

Returns the date and local time when the file was last accessed (read). If the file is not available, this function returns an invalid Date object.

◆ ctime()

Date ctime ( String &  file)

Returns the date and time when the file metadata (status, eg. permissions) was changed. If the file is not available, this function returns an invalid Date object.

◆ permissions()

::FS::Permissions permissions ( String &  file)

Returns the complete OR-ed together combination of FS.Permissions for the file.

◆ setPermissions()

bool setPermissions ( String &  file,
::FS::Permissions  p 
)

Sets the permissions for file to the FS.Permissions flags specified in p. Returns true if successful, or false if the permissions cannot be modified.