EAFile
Introduction
EAFile is the file manipulation interface in the UTF. The IO portion of it is built upon the EAStream interface. EAFile provides the following suite of components:
Each of the above components resides in independent sources files and is documented independently.
Conventions
There are some conventions and standards we use in the UTF in order to make user and developer expectations consistent and safe:
- Paths are represented in the form that is normal for the given target platform. There is no attempt to make some kind of universal path format that works for all platforms. However, both '\' and '/' are accepted under Microsoft platforms as directory separators.
- Path case sensitivity follows the conventions of the given platform. Thus Microsoft-based platforms are case-insensitive, and other platforms are usually case-sensitive.
- UTF functions that accept file paths always expect a supplied path buffer to be at least kMaxPathLength in capacity. This makes for simpler logic, though it creates an opportunity for inattentive users to generate buffer overruns.
- Directory paths always end with a directory separator. This makes for simpler logic and portable behaviour.
- Path representations are preferred to be char16_t strings. This makes for simpler logic and manipulation and for easier localization on platforms that require it, especially Windows. The debates on this topic are legendary and we admit that both sides of the debate have points.
- The term "file name" is used to describe just the name of the file and not its full path. The term "file path" is used to describe a full path to a file.
- The concept of "current directory" is not supported by the UTF file system, as it has been found to be a concept fraught with perils and portability problems. There is a GetCurrentDirectory and SetCurrentDirectory function, but that is entirely for the user's use and the EAFile* functions don't use it. Similarly, the concept of current drive or current volume is also not supported.
- All functionality is made possible on all platforms to the extent possible. This may include custom implementations of some functionality.