FileManager is a line-based and crash-safe file manipulation tool for C++17. I began the project mainly for the reason of attempting to learn how to handle files. This repository was created to share the knowledge I've gathered in one simple to use class. The class aims to stay user-friendly while possessing impressive features. It is not a replacement for SQLite or designed for heavy workloads.
- Very beginner/user friendly
- Line-based (deleting a line shifts all later lines down)
- Crash resilient, able to recover most data after a crash
- Prevents file corruption by atomic rewrites
- Very memory efficient
- Extremely efficient line deletes
- File will stay humanly readable
- Standalone library
- You need simple, persistent storage
- Data loss must be avoided
- File are small (KBs - MBs, not GBs)
- Human readable files are desired
- You don't want gaps inside your file (empty lines)
- Files are very large
- You need complex queries
- You need concurrent access
- Download the latest package
- Make sure to use C++17 and a 64-bit system
- Extract the header file (include/filemanager.h) into your project folder
- Include it:
#include "filemanager.h"
Roughly 16 bytes per line plus 80-120 bytes per unsaved change. Memory usage is predictable and scales linearly with file size.
No. It was designed for single-threaded usage.
All flushed changes will be recovered automatically on the next startup. Unflushed changes are lost.
DO NOT TOUCH OR DELETE THE JOURNAL FILE! That file is responsible for recovering lost data in the case of a crash. Modifying its contents can lead to issues in restoring lost data.
The journal's purpose is to record method calls during runtime. In order to do that, it'll have to serialize method calls in a way that is able to be verified later when replaying. The journal's entries all follow the same structure, namely: (instruction)(arguments) The arguments are always saved in this way: (argument length)(argument) in order to be able to verify whether the extracted argument is invalid or not. Unless you know what you're doing, it's highly advised to keep your hands off of the journal!
| Method | Description | Note |
|---|---|---|
| FileManager(file path) | Creates a new FileManager instance that manages the specified file | |
| read(index) | Returns the text at the specified row | |
| front() | Returns a copy of the text at the first row | |
| back() | Returns a copy of the text at the last row | |
| all() | Returns a copy of the text at every row | |
| append(args) | Converts the given arguments into text and appends it to the file | |
| overwrite(index, args) | Converts the given arguments into text and overwrites the specified line | |
| erase(index) | Deletes the specified line | Deleting a line shifts all later lines down |
| clear() | Deletes entire text in the file | |
| flush() | Records all changes, making recovery possible | Does not apply changes to the file |
| commit() | Applies all changes to the file | Very expensive if file is big, use wisely |
| empty() | Returns true if there are no present lines | |
| size() | Returns the number of present lines |