Document new File functions (Copy, Rename, GetFileTime, Read/WriteRawFloat, Read/WriteBytes)

[ericoporto]

https://github.com/adventuregamestudio/ags-manual/wiki/File

• - File.Copy

  /// Creates a copy of an existing file; if there's already a file with the new name then it will be overwritten
  import static bool Copy(const string old_filename, const string new_filename);   // $AUTOCOMPLETESTATICONLY$

---

• - File.GetFileTime

  /// Retrieves specified file's last write time; returns null if file does not exist
  import static DateTime* GetFileTime(const string filename); // $AUTOCOMPLETESTATICONLY$

---

• - File.Rename

  /// Renames an existing file; if there's already a file with the new name then it will be overwritten
  import static bool Rename(const string old_filename, const string new_filename);   // $AUTOCOMPLETESTATICONLY$

---

• - File.ReadRawFloat

  /// Reads the next raw 32-bit float from the file.
  import float  ReadRawFloat();

---

• - File.WriteRawFloat

  /// Writes a raw 32-bit float to the file.
  import void   WriteRawFloat(float value);

---

• - File.ReadBytes

  /// Reads up to "count" number of bytes and stores them in a provided dynamic array, starting with certain index. Returns actual number of read bytes.
  import int    ReadBytes(char bytes[], int index, int count);

---

• - File.WriteBytes

  /// Writes up to "count" number of bytes from the provided dynamic array, starting with certain index. Returns actual number of written bytes.
  import int    WriteBytes(char bytes[], int index, int count);

---

Some of the new File API were added in PR adventuregamestudio/ags#2541

Additional documentation in the source code https://github.com/adventuregamestudio/ags/blob/e7fc02178d50e808134a651f4a9e07d3d7cc65e0/Engine/ac/file.cpp#L87

A few notes

• File.Copy returns false if it fails and true if it executes correctly.
• File.Rename creates any dir necessary and also returns false if it fails or true if it succeeds.
• File.GetFileTime returns null if it fails (like if the file doesn't exist)
• the time returned is also known as the modified time

[ivan-mogilko]

File.Copy returns false if it fails and true if it executes correctly.
File.Rename creates any dir necessary and also returns false if it fails or true if it succeeds.

IIRC File.Copy also should create directories.

But the engine only creates subdirs within the standard locations ($SAVEGAMEDIR$ and others), it is forbidden from creating directories outside of those.

[ericoporto]

@ivan-mogilko I am a bit unsure on returning true on success and false on error. If we ever want to return error codes as enum, this gives us many values for success but only one value for error.

[ivan-mogilko]

I thought about this, and my guess is that for the majority of users of AGS the specific error code would be meaningless. What would be interesting is whether operation succeeds or not. In which case their habit would be to test it as any other operation that returns a result, like:

if (File.Copy(
{
    // on success
}

if (!File.Rename(
{
    // on failure
}

If we make these enums where 0 is success, then this will become a source of endless mistakes.

I propose to find another way of getting specific error code.

[ericoporto]

uhm, ok.

I added File.Copy,GetFileTime and Rename in the simplest way as possible.

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/bd914fe80e41568d4d7cb91f17ba2efc6c27fb69...c3e703282566f96b81b28f060fb8a8c9c51edbde

[ericoporto]

and quickly added RawRawFloat and WriteRawFloat

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/c3e703282566f96b81b28f060fb8a8c9c51edbde...8e943432d2a8fb5794892f33590323ee26c22e38

Need to think of examples for these and include any error handle in the example.

[ericoporto]

Added examples for File.Rename and File.GetFileTime (nothing too inspired though....)

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/5ce7b9bfc052d004422ff3d1bdc4b5ef9334ee6c...be45672a62fbf5353a2da2ec515453fe69ccdd7c

[ericoporto]

@ivan-mogilko shouldn't ReadBytes and WriteBytes be ReadRawBytes and WriteRawBytes?

I had to look into the code to figure it out they weren't like WriteInt and instead more like WriteRawIntArray of sorts. It is also weird there is WriteRawFloat but not WriteFloat.

Also I feel like File should be reordered so it has static functions alphabetically, functions alphabetically and then properties alphabetically.

documented them here

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/be45672a62fbf5353a2da2ec515453fe69ccdd7c...4f76eec0b186702e272165a3e8a73ab09c0c5aed

[ivan-mogilko]

Personally, I do not like current separation between Read "normal" and Read "raw" values, I think that's confusing and prone to mistakes.

I wish there were a separate class for reading and writing "safeguarded" values, if anyone would like to have that.
Or at least they were called specifically to indicate that they are safeguarded; i.e. turn the naming to opposite.

If you think that's necessary, then we can add both "raw" and "not raw" variants for dealing with array of bytes.
It's also trivial to add safeguarded Float functions.

[ericoporto]

I wish there were a separate class for reading and writing "safeguarded" values, if anyone would like to have that.

I was thinking the same. In my head nowadays people would prefer some format like ini or json and have something that gives a friendly interface to them. The "safeguarded" version feels more "binary", which is usually hard to quickly inspect. But I don't have a good idea for a name for such class to hide these functions.

If you think that's necessary

It's more that their name should have Raw in it, since they aren't safeguarded.

[ivan-mogilko]

Opened a PR with these changes:
adventuregamestudio/ags#2631