User Tools

Site Tools


DzFile

DAZ Script file I/O class.

More...

Inherits :

Enumerations

Constructors

DAZ Script
DzFile ( String file )

Methods

DAZ Script
voidclose ()
Booleancopy ( String newName )
Booleaneof ()
FileErrorerror ()
StringerrorString ()
BooleanisOpen ()
BooleanisTextModeEnabled ()
Booleanlink ( String linkName )
Booleanopen ( OpenMode mode )
OpenModeopenMode ()
ByteArraypeek ( Number maxSize )
Numberpos ()
ByteArrayread ( Number maxSize )
Stringread ()
ByteArrayreadAll ()
NumberreadByte ()
ByteArrayreadByteLine ( Number maxSize=0 )
StringreadLine ()
ArrayreadLines ()
Booleanrename ( String newName )
Booleanreset ()
Booleanseek ( Number pos )
voidsetFileName ( String name )
BooleansetPermissions ( Permissions permissions )
voidsetTextModeEnabled ( Boolean enabled )
Numberwrite ( String data, Number maxSize=-1 )
voidwriteByte ( Number byte )
NumberwriteBytes ( ByteArray byteArray )
voidwriteLine ( String data )
voidwriteLineUtf8 ( String data )
NumberwriteUtf8 ( String data, Number length=-1 )

Detailed Description

Provides access for reading and writing files.

Enumerations


: FileError

TODO: Add description.

  • NoError - No error occurred.
  • ReadError - An error occurred when reading from the file.
  • WriteError - An error occurred when writing to the file.
  • FatalError - A fatal error occurred.
  • ResourceError - TODO: Add description.
  • OpenError - The file could not be opened.
  • AbortError - The operation was aborted.
  • TimeOutError - A timeout occurred.
  • UnspecifiedError - An unspecified error occurred.
  • RemoveError - The file could not be removed.
  • RenameError - The file could not be renamed.
  • PositionError - The position in the file could not be changed.
  • ResizeError - The file could not be resized.
  • PermissionsError - The file could not be accessed.
  • CopyError - The file could not be copied.

—–

: OpenModeFlag

Enumerated values used with open() to describe the mode in which a file is opened.

  • NotOpen - The file is not open.
  • ReadOnly - The file is open the for reading.
  • WriteOnly - The file is open the for writing.
  • ReadWrite - The file is open the for reading and writing.
  • Append - The file is opened in append mode, so that all data is written to the end of the file.
  • Truncate - If possible, the file is truncated before it is opened. All earlier contents of the file are lost.
  • Text - When reading, the end-of-line terminators are translated to '

'. When writing, the end-of-line terminators are translated to the local encoding.

  • Translate - Alias for Text.

Constructors


DzFile( String file )

Creates a file object with the given file name.

Parameter(s):

  • file - The path of the file.

Methods


void : close()

Closes the file, sets its openMode() to NotOpen, and resets the error string.


Boolean : copy( String newName )

Parameter(s):

  • newName - The path to copy this file to.

Return Value:

  • true if copying the file is successful, otherwise false.

Attention:

  • If newName already exists it will not be overwritten.

Boolean : eof()

Return Value:

  • true if the current position is at the end of the file, otherwise false.

FileError : error()

Return Value:

  • The file error status.

Attention:

  • For example, if open() returns false, or a read/write operation returns -1, this function can be called to find out the reason why the operation failed.

Since:

  • 4.9.3.35

String : errorString()

Return Value:

  • A human-readable description of the last error that occurred.

Since:

  • 4.9.3.35

Boolean : isOpen()

Return Value:

  • true if the file is open, otherwise false.

Since:

  • 4.9.3.35

Boolean : isTextModeEnabled()

Return Value:

  • true if the Text OpenModeFlag is enabled, otherwise false.

Since:

  • 4.9.3.35

Boolean : link( String linkName )

Creates a link named linkName that points to the file currently specified by fileName(). What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Mac OS X).

Return Value:

  • true if successful, otherwise false.

Attention:

  • This will not overwrite an already existing entity in the file system; in this case, link() will return false and set error() to return RenameError.

Since:

  • 4.9.3.35

Renames the file currently specified by fileName() to newName.

Return Value:

  • true if successful, otherwise false (for example, if a file with the name newName already exists).

Attention:

  • The file is closed before it is renamed.

Since:

  • 4.9.3.35

Boolean : open( OpenMode mode )

Opens the file and sets its openMode() to mode.

Parameter(s):

  • mode - The access mode to open with.

Return Value:

  • true if the file was opened successfully, otherwise false.

OpenMode : openMode()

Return Value:

  • The mode in which the device has been opened.

Since:

  • 4.9.3.35

ByteArray : peek( Number maxSize )

Peeks at most maxSize bytes from the file, without side effects (i.e., if you read after you peek, you will get the same data).

Return Value:

  • The data peeked.

Since:

  • 4.9.3.35

Number : pos()

Return Value:

  • The position that data is written to or read from.

Since:

  • 4.9.3.35

ByteArray : read( Number maxSize )

Reads at most maxSize bytes from the file.

Return Value:

  • The data read.

Since:

  • 4.9.3.35

String : read()

Read the entire file.

Return Value:

  • The file contents as a string.

ByteArray : readAll()

Read the entire file.

Return Value:

  • All bytes of the file.

Attention:

  • This function has no way of reporting errors; returning an empty ByteArray can mean either that no data was currently available for reading, or that an error occurred.

Number : readByte()

Read one character from the file.

Return Value:

  • The character read from the file.

ByteArray : readByteLine( Number maxSize=0 )

Reads a line from the file, but no more than maxSize characters.

Parameter(s):

  • maxSize - The maximum number of characters to read. Since 4.9.3.35.

Return Value:

  • The bytes read.

Attention:

  • This function has no way of reporting errors; returning an empty ByteArray can mean either that no data was currently available for reading, or that an error occurred.

String : readLine()

Read a line of text from the file.

Return Value:

  • The file line as a string.

Array : readLines()

Read the entire file and split it into lines of text.

Return Value:

  • All lines from the file.

Boolean : rename( String newName )

TODO: Add description.


Boolean : reset()

Seeks to the start of input.

Return Value:

  • true on success, otherwise false (for example, if the file is not open).

Since:

  • 4.9.3.35

Boolean : seek( Number pos )

Sets the current position to pos.

Return Value:

  • true on success, otherwise false.

Since:

  • 4.9.3.35

void : setFileName( String name )

Sets the name of the file to name. The name can have no path, a relative path, or an absolute path.

Attention:

  • Do not call this function if the file has already been opened. If the file name has no path or a relative path, the path used will be the application's current directory path at the time of the open() call.

Since:

  • 4.9.3.35

Boolean : setPermissions( Permissions permissions )

Sets the permissions for the file to permissions.

Return Value:

  • true if successful, otherwise false (for example, if the permissions cannot be modified).

Since:

  • 4.9.3.35

void : setTextModeEnabled( Boolean enabled )

If enabled is true, sets the Text flag on the file, otherwise the Text flag is removed.

Since:

  • 4.9.3.35

Number : write( String data, Number maxSize=-1 )

Write a string to the file.

Parameter(s):

  • data - The string to write to the file.
  • maxSize - The maximum number of characters to write to the file. If this is less than 1 (default), the whole string is written.

Return Value:

  • The number of bytes that were actually written, or -1 if an error occurred. (since 4.9.3.35)

void : writeByte( Number byte )

Write a single byte (character) to the file.

Parameter(s):

  • byte - The character to write to the file.

Number : writeBytes( ByteArray byteArray )

Writes the content of byteArray to the file.

Return Value:

  • The number of bytes that were actually written, or -1 if an error occurred.

Since:

  • 4.14.0.7

void : writeLine( String data )

Write a line to the file.

Parameter(s):

  • data - The string to write to the file - a new line character will be written immediately following the string contents.

void : writeLineUtf8( String data )

Write a UTF-8 line to file.

Parameter(s):

  • data - The string to write to the file - a new line character will be written immediately following the string contents.

Since:

  • 4.16.1.25

Number : writeUtf8( String data, Number length=-1 )

Write a UTF-8 string to file.

Parameter(s):

  • data - The string to write to the file.
  • length - The number of characters to write to the file. If this is less than 1 (default), the whole string is written.

Return Value:

  • The number of bytes that were actually written, or -1 if an error occurred.

Since:

  • 4.16.1.25