fileSystem.md 4.0 KB
File system {#fileSystem}
Paths
Instead of using strings for representing paths, Banshee uses the @ref bs::Path "Path" class. Aside from containing the path it provides a variety of other useful information and allows for path manipulation. It is recommended to always store paths using Path instead of strings.
Path myPath = "C:/Path/To/File.txt";
Some of the things you can do with a Path:
- Retrieve the filename using @ref bs::Path::getFilename "Path::getFilename"
- Retrieve the filename extension using @ref bs::Path::getExtension "Path::getExtension"
- Get last element of path, either file or directory using @ref bs::Path::getTail "Path::getTail"
- Iterate over directories, get drive, combine paths, convert relative to absolute paths and vice versa, and more. See the API reference for a complete list.
For example:
Path myPath = "C:/Path/To/File.txt";
String filename = myPath.getFilename(); // Returns filename, if the path has any
myPath.setExtension(".jpg"); // Path is now "C:/Path/To/File.jpg"
myPath.makeRelative("C:/Path"); // Path is now "To/File.jpg"
Path a("C:/Path/To/");
Path b("File.txt");
Path combined = a + b; // // Path is now "C:/Path/To/File.txt"
All Path methods that return strings come in two variants, one that returns a narrow (8-bit) character string like Path::getFilename, and one that contains wide character string like Path::getWFilename.
When setting paths be careful with setting backslashes or slashes at the end of the path. Path with a no backslash/slash on the end will be interpreted as a file path, and path with a backslash/slash will be interpreted as a folder path. For example:
- "C:/MyFolder" - "MyFolder" interpreted as a file, Path::getFilename returns "MyFolder"
- "C:/MyFolder/" - "MyFolder" interpreted as a folder, Path::getFilename returns an empty string
File system
File system operations like opening, creating, deleting, moving, copying files/folders are provided by the @ref bs::FileSystem "FileSystem" class. Check the API reference for a complete list of operations.
An example creating a folder and a file:
FileSystem::createDir("C:/Path/To/");
SPtr<DataStream> fileStream = FileSystem::createAndOpenFile("C:/Path/To/File.txt");
// Write to data stream (see below)
Data streams
If you create or open a file you will receive a @ref bs::DataStream "DataStream" object. Data streams allow you to easily write to, or read from open files.
SPtr<DataStream> fileStream = FileSystem::createAndOpenFile("C:/Path/To/File.txt");
// Write some string data
fileStream->writeString("Writing to a file");
// Write some binary data
UINT8* myBuffer = bs_alloc(1024);
// ... fill up the buffer with some data ...
fileStream->write(myBuffer, 1024);
fileStream->close();
bs_free(myBuffer);
Once you are done with a stream make sure to close it by calling @ref bs::DataStream::close "DataStream::close". Stream will also be automatically closed when it goes out of scope.
Streams don't need to be read or written to sequentially, use @ref bs::DataStream::seek "DataStream::seek" to move within any position of the stream, and @ref bs::DataStream::tell "DataStream::tell" to find out the current position.
// Open the file we wrote in the previous example
SPtr<DataStream> fileStream = FileSystem::openFile("C:/Path/To/File.txt");
// Seek past the string we wrote
String str = "Writing to a file";
fileStream->seek(str.size());
// Read the byte data
UINT8* myBuffer = bs_alloc(1024);
fileStream->read(myBuffer, 1024);
fileStream->close();
bs_free(myBuffer);
Each time you read or write from the stream, the current read/write indices will advance. So subsequent calls to read/write will continue from the last position that was read/written.
Finally, use @ref bs::DataStream::size "DataStream::size" to find out the size of a stream in bytes.