Writing Data to Files

In this lesson, we’ll introduce how to write data from our program to external sources. We’ll focus on writing to files for now, but the techniques we cover lay the foundations for working with other data streams, such as network traffic.

As we might expect, SDL’s mechanism for writing data shares much in common with their API for reading data. We’ll rely on SDL_RWops objects, and the functions we use will be familiar to what we learned in the previous lesson.

Like before, we’ll start with a basic main function that initializes SDL, and calls Write() and Read() functions within an included File namespace.

1// main.cpp
2#include <SDL.h>
3#include "File.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(0);
7  File::Write("output.txt");
8  File::Read("output.txt");
9  return 0;
10}

Our Read() function logs out the file’s contents, using techniques we covered in the previous lesson. In this lesson, we’ll work on the Write() function, which is currently empty:

1// File.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5
6namespace File {
7  void Read(const std::string& Path) {
8    char* Content{static_cast<char*>(
9      SDL_LoadFile(Path.c_str(), nullptr)
10    )};
11    
12    if (Content) {
13      std::cout << "Content: " << Content;
14    } else {
15      std::cout << "Error loading file: "
16        << SDL_GetError();
17    }
18    
19    SDL_free(Content);
20  }
21  
22  void Write(const std::string& Path) {
23    // ...
24  }
25
26}

Running our program, we should see an error output from our Read() function, as it’s trying to read a file that we haven’t created yet:

1Error loading file: Parameter 'src' is invalid

Creating a File Using SDL_RWFromFile()

We introduced the SDL_RWFromFile() function in the previous lesson. It returns an SDL_RWops object, which is SDL’s standard interface for interacting with data streams, such as files.

In the previous lesson, we passed the file path and the "rb" open mode to read the file. We’ll use the same technique here, except we’ll pass "wb" as the open mode, as we want to write to the file. We cover open modes in more detail later in this lesson.

Let’s update our File::Write() function to create an SDL_RWops handle for outputting content. Similar to the previous lesson, we’ll also add an error check, and we’ll close the file using SDL_RWclose() when we’re done:

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(const std::string& Path) {
7  SDL_RWops* Handle{
8    SDL_RWFromFile(Path.c_str(), "wb")};
9
10  if (!Handle) {
11    std::cout << "Error opening file: "
12      << SDL_GetError();
13  }
14
15  // Use file...
16
17  SDL_RWclose(Handle);
18}
19}

The "wb" open mode will additionally cause SDL to create a file if it doesn’t exist. Therefore, running our program, after these changes we should now see our Read() function can successfully open the file, although it has no content yet:

1Content:

SDL_RWwrite()

The SDL_RWwrite() function is one of the main ways we output a collection of objects or values to a file. Let’s update our File::Write() function to use it to output the C-style string "Hello World".

We introduced SDL_RWread() in the previous lesson, and the arguments to SDL_RWwrite() follow a similar pattern. It accepts 4 arguments:

1. The SDL_RWops handle to use
2. A pointer to the memory address where the content we want to write begins. Remember, a C-style string is simply a location in memory containing a contiguous sequence of char values, represented by a pointer to the first character - a char*.
3. The size of each object in bytes. In this example, we’re writing char values, and a char is 1 byte. We could simply pass 1 as the argument, but we’ll use sizeof(char) as it clarifies what the 1 represents.
4. The quantity of objects to write. We can use the strlen() function to determine how many characters are in a C-style string

Let’s update our File::Write() function to make use of this:

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(const std::string& Path) {
7  SDL_RWops* Handle{
8    SDL_RWFromFile(Path.c_str(), "wb")};
9
10  if (!Handle) {
11    std::cout << "Error opening file: "
12      << SDL_GetError();
13  }
14
15  const char* Content{"Hello World"};
16  SDL_RWwrite(Handle, Content,
17    sizeof(char), strlen(Content));
18
19  SDL_RWclose(Handle);
20}
21}

1Content: Hello World

SDL_RWFromFile() returns an integer, representing how many objects it wrote:

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(const std::string& Path) {
7  SDL_RWops* Handle{
8    SDL_RWFromFile(Path.c_str(), "wb")};
9
10  if (!Handle) {
11    std::cout << "Error opening file: "
12      << SDL_GetError();
13  }
14
15  const char* Content{"Hello World"};
16  
17  size_t ValuesWritten{SDL_RWwrite(
18    Handle, Content,
19    sizeof(char), strlen(Content)
20  )};
21  
22  std::cout << ValuesWritten
23    << " values written\n";
24
25  SDL_RWclose(Handle);
26}
27}

111 values written
2Content: Hello World

We can add some simple error checking by comparing this return value to what we expected. As usual, we can call SDL_GetError() for information on errors detected by SDL:

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(const std::string& Path) {
7  SDL_RWops* Handle{
8    SDL_RWFromFile(Path.c_str(), "wb")};
9
10  if (!Handle) {
11    std::cout << "Error opening file: "
12      << SDL_GetError();
13  }
14
15  const char* Content{"Hello World"};
16  size_t ContentLength{strlen(Content)};
17  size_t ValuesWritten{SDL_RWwrite(
18    Handle, Content, sizeof(char),
19    ContentLength
20  )};
21
22  std::cout << ValuesWritten
23    << " values written\n";
24
25  if (ValuesWritten < ContentLength) {
26    std::cout << "Expected " << ContentLength
27      << " - Error: " << SDL_GetError() << '\n';
28  }
29
30  SDL_RWclose(Handle);
31}
32}

File Open Modes

In the previous lesson, we passed the rb string, telling SDL (and ultimately the underlying platform) that we wanted to read from the file in binary mode. In this case, we’re using wb , indicating we want to create a new file for writing in binary mode.

If a file with the same name already exists, it will be entirely replaced when using wb. We’ll cover more open modes, including the ability to edit or add to an existing file later in this chapter.

Binary Mode vs Text Mode

Platforms typically offer two ways to read or write files. These are commonly called binary mode and text mode. Binary mode reads and writes data in the exact format provided. This is intended when the data is used to communicate between programs (or within the same program), where a consistent and predictable format is useful.

On the other hand, text mode performs some platform-specific transformations to format the file in a way that conforms to that platform’s conventions.

For example, we use \n to represent new lines in this course, but some platforms use a two-byte sequence: \r\n. Text mode aims to handle those transformations. However, even if our program is writing data that is intended to be read by humans, that data is usually going to be read in some program that handles formatting, so binary mode is typically preferred even in that scenario.

As such, text mode is rarely useful, but can be used by removing the b character from open modes if needed:

1// Open a file for reading in text mode
2SDL_RWFromFile("input.txt", "r")}
3
4// Open a file for writing in text mode
5SDL_RWFromFile("output.txt", "w")}

Adding to Existing Files

As we’ve seen, opening a file in "write" mode (such as "wb") ensures we get a new file every time we create our handle. If a file with that name already exists, it will be replaced.

In contrast, we can open a file in an "append" mode, such as "ab":

1SDL_RWFromFile("some-file.txt", "ab")

This will also create the file if it doesn’t exist yet. However, if it does exist, write operations will be done at the end of the existing file, preventing us from losing any of the existing data.

This is primarily useful for logging scenarios, where we want to keep track of the actions our program performed:

1// main.cpp
2#include <SDL.h>
3#include "File.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(0);
7  File::Write("logs.txt", "One");
8  File::Write("logs.txt", "Two");
9  File::Write("logs.txt", "Three");
10  File::Read("logs.txt");
11  return 0;
12}

1// File.h
2// ...
3
4namespace File {
5// ...
6void Write(
7  const std::string& Path,
8  const char* Content
9) {
10  SDL_RWops* Handle{
11    SDL_RWFromFile(Path.c_str(), "ab")};
12
13  if (!Handle) {
14    std::cout << "Error opening file: "
15      << SDL_GetError();
16  }
17
18  SDL_RWwrite(
19    Handle, Content,
20    sizeof(char), strlen(Content)
21  );
22
23  SDL_RWclose(Handle);
24}
25}

Three file handles were opened and closed during the execution of the program, and each write operation was appended to the previous output:

1Content: OneTwoThree

If we run our program again, the logging from the second execution will add more content to the file, without replacing the output of the previous execution:

1Content: OneTwoThreeOneTwoThree

Summary

In this lesson, we explored writing data to files using SDL2 in C++. We learned how to:

• Create and open files using SDL_RWFromFile()
• Write data to files with SDL_RWwrite()
• Understand different file open modes, including binary and text modes
• Append data to existing files
• Handle potential errors during file operations

These skills form the foundation for more advanced file I/O operations in SDL2-based applications, which we’ll build on through the rest of this chapter.

Next Lesson

Maths and Geometry Primer

Learn the basics of maths and geometry, so we can represent concepts like positions and distances between objects in our worlds.

ContinueView Course