Класс file

Материал из docs.kb-agava.ru
Перейти к навигации Перейти к поиску

Класс предоставляет интерфейс для работы с файлами: открытие, закрытие, чтение и запись данных различных типов, позиционирование внутри файла. Поддерживает как текстовый, так и бинарный режимы работы.

1 Свойства

bool mostSignificantByteFirst

Назначение: Определяет порядок байтов (endianness) при чтении и записи числовых значений.

Аргументы: Отсутствуют.

Возвращаемое значение: Отсутствует (свойство).

Примечания:

  • true – используется порядок Big-endian (старший байт первый).
  • false (по умолчанию) – используется порядок Little-endian (младший байт первый).
  • Влияет на методы readInt, readUInt, readFloat, readDouble и соответствующие методы записи.
  • Может изменяться в любой момент до выполнения операций чтения/записи.

2 Методы

int open(const string &in filename, const string &in mode)

Назначение: Открывает файл для чтения и/или записи.

Аргументы:

  • filename – путь к файлу (относительный или абсолютный).
  • mode – режим открытия файла:
    • "r" – открыть для чтения (только чтение).
    • "w" – открыть для записи (создаёт новый или перезаписывает существующий).
    • "a" – открыть для добавления (запись в конец файла).

Возвращаемое значение:

  • 0 – файл успешно открыт.
  • -1 – ошибка открытия (файл не существует, недостаточно прав, неверный режим).

Примечания:

  • Перед открытием нового файла автоматически закрывает ранее открытый.
  • На Windows автоматически добавляет флаг "b" (бинарный режим) для предотвращения преобразования \r\n в \n.
  • На Windows CE пути преобразуются в абсолютные относительно директории приложения.
  • Если режим не поддерживается (например, запись при AS_WRITE_OPS == 0), возвращает -1.
int close()

Назначение: Закрывает открытый файл.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • 0 – файл успешно закрыт.
  • -1 – файл уже был закрыт или не открыт.

Примечания:

  • Автоматически вызывается в деструкторе объекта.
  • После закрытия файла дальнейшие операции чтения/записи будут возвращать ошибки.
int getSize() const

Назначение: Возвращает размер файла в байтах.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • Размер файла в байтах (тип int).
  • -1 – файл не открыт или произошла ошибка.

Примечания:

  • Для определения размера сохраняет текущую позицию, перемещается в конец файла и возвращается обратно.
bool isEndOfFile() const

Назначение: Проверяет, достигнут ли конец файла.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • true – достигнут конец файла или файл не открыт.
  • false – не достигнут конец файла.

Примечания:

  • Использует стандартную функцию feof().
  • Возвращает true, если файл не открыт.
int getPos() const

Назначение: Возвращает текущую позицию в файле.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • Текущая позиция в байтах от начала файла.
  • -1 – файл не открыт или произошла ошибка.

Примечания:

  • Использует функцию ftell().
int setPos(int pos)

Назначение: Устанавливает текущую позицию в файле от начала.

Аргументы:

  • pos – абсолютная позиция в байтах от начала файла.

Возвращаемое значение:

  • 0 – позиция успешно установлена.
  • -1 – файл не открыт или позиция вне допустимого диапазона.

Примечания:

  • Использует функцию fseek(SEEK_SET).
int movePos(int delta)

Назначение: Смещает текущую позицию в файле относительно текущего положения.

Аргументы:

  • delta – смещение в байтах (положительное – вперёд, отрицательное – назад).

Возвращаемое значение:

  • 0 – позиция успешно изменена.
  • -1 – файл не открыт или смещение выходит за границы.

Примечания:

  • Использует функцию fseek(SEEK_CUR).
string readString(uint length)

Назначение: Читает указанное количество символов из файла.

Аргументы:

  • length – количество символов (байт) для чтения.

Возвращаемое значение:

  • Строка с прочитанными данными (реальная длина может быть меньше length, если достигнут конец файла).
  • Пустая строка – если файл не открыт.

Примечания:

  • Возвращает все прочитанные байты как есть (включая нулевые символы).
  • Размер результирующей строки соответствует количеству реально прочитанных байт.
string readLine()

Назначение: Читает одну строку из файла.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • Строка, содержащая прочитанную строку (без символа \n).
  • Пустая строка – если достигнут конец файла или файл не открыт.

Примечания:

  • Читает до символа перевода строки (\n) или до заполнения внутреннего буфера (255 символов).
  • Поддерживает чтение длинных строк – операция повторяется до обнаружения \n или конца файла.
  • Символ \n не включается в результат.
int64 readInt(uint bytes)

Назначение: Читает знаковое целое число из файла.

Аргументы:

  • bytes – количество байт для чтения (1–8). Если bytes > 8, используется 8.

Возвращаемое значение:

  • Прочитанное целое число (тип int64).
  • 0 – если файл не открыт или достигнут конец файла.

Примечания:

  • Поддерживает автоматическое расширение знака (sign extension) для отрицательных чисел.
  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Младшие байты заполняются нулями, если bytes < 8.
  • Для отрицательных чисел старшие байты заполняются 0xFF.
uint64 readUInt(uint bytes)

Назначение: Читает беззнаковое целое число из файла.

Аргументы:

  • bytes – количество байт для чтения (1–8). Если bytes > 8, используется 8.

Возвращаемое значение:

  • Прочитанное беззнаковое целое число (тип uint64).
  • 0 – если файл не открыт или достигнут конец файла.

Примечания:

  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Не выполняет расширение знака.
  • Младшие байты заполняются нулями, если bytes < 8.
float readFloat()

Назначение: Читает число с плавающей точкой (32 бита) из файла.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • Прочитанное число типа float.
  • 0.0f – если файл не открыт или достигнут конец файла.

Примечания:

  • Читает ровно 4 байта.
  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Использует объединение (union) для битового преобразования.
double readDouble()

Назначение: Читает число с плавающей точкой двойной точности (64 бита) из файла.

Аргументы: Отсутствуют.

Возвращаемое значение:

  • Прочитанное число типа double.
  • 0.0 – если файл не открыт или достигнут конец файла.

Примечания:

  • Читает ровно 8 байт.
  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Использует объединение (union) для битового преобразования.

3 Методы записи

int writeString(const string &in str)

Назначение: Записывает строку в файл.

Аргументы:

  • str – строка для записи.

Возвращаемое значение:

  • Количество записанных байт.
  • -1 – если файл не открыт.

Примечания:

  • Записывает строку целиком, включая все символы (без завершающего нуля).
int writeInt(int64 val, uint bytes)

Назначение: Записывает знаковое целое число в файл.

Аргументы:

  • val – значение для записи.
  • bytes – количество байт для записи (1–8). Если bytes > 8, используется 8.

Возвращаемое значение:

  • Количество записанных байт (0 или 1 в терминах fwrite).
  • 0 – если файл не открыт.

Примечания:

  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Записываются только младшие bytes байт числа.
int writeUInt(uint64 val, uint bytes)

Назначение: Записывает беззнаковое целое число в файл.

Аргументы:

  • val – значение для записи.
  • bytes – количество байт для записи (1–8). Если bytes > 8, используется 8.

Возвращаемое значение:

  • Количество записанных байт (0 или 1 в терминах fwrite).
  • 0 – если файл не открыт.

Примечания:

  • Порядок байт определяется свойством mostSignificantByteFirst.
  • Записываются только младшие bytes байт числа.
int writeFloat(float val)

Назначение: Записывает число с плавающей точкой (32 бита) в файл.

Аргументы:

  • val – значение для записи.

Возвращаемое значение:

  • Количество записанных байт (0 или 1 в терминах fwrite).
  • 0 – если файл не открыт.

Примечания:

  • Записывает ровно 4 байта.
  • Порядок байт определяется свойством mostSignificantByteFirst.
int writeDouble(double val)

Назначение: Записывает число с плавающей точкой двойной точности (64 бита) в файл.

Аргументы:

  • val – значение для записи.

Возвращаемое значение:

  • Количество записанных байт (0 или 1 в терминах fwrite).
  • 0 – если файл не открыт.

Примечания:

  • Записывает ровно 8 байт.
  • Порядок байт определяется свойством mostSignificantByteFirst.

4 Пример использования

// Создание и открытие файла для записи
file f;
f.mostSignificantByteFirst = false; // Little-endian

int result = f.open("data.bin", "w");

if (result == 0) 
{
    f.writeString("Hello, World!");
    f.writeInt(12345, 4);
    f.writeFloat(3.14159f);
    f.close();
}

// Открытие файла для чтения
file f2;
f2.mostSignificantByteFirst = false;
f2.open("data.bin", "r");

if (!f2.isEndOfFile()) 
{
    string str = f2.readLine();
    int64 num = f2.readInt(4);
    float pi = f2.readFloat();
}

f2.close();

// Чтение бинарных данных с Big-endian порядком
file f3;
f3.mostSignificantByteFirst = true; // Network byte order
f3.open("network_data.bin", "r");
uint64 value = f3.readUInt(4); // Читает 4 байта как Big-endian
Источник — https://docs.kb-agava.ru/index.php?title=Класс_file&oldid=3498