When we're loading text files into our program, we need the ability to programmatically understand that text data. This process is commonly called parsing the data.

In this lesson, we'll imagine the configuration of our program is provided in a serialized form - perhaps a file or network response - that looks like this:

1WINDOW_TITLE: Example Window
2WINDOW_WIDTH: 800
3WINDOW_HEIGHT: 600
4LEVELS: 1, 2, 3, 4

We want to deserialize this payload into C++ content, defined by a struct that looks like this:

1struct Config {
2  std::string WindowTitle;
3  int WindowWidth;
4  int WindowHeight;
5  std::vector<int> Levels;
6};

We'll cover the most important techniques to achieve results like this, using the standard library's std::string type.

Loading Content into a `std::string`

Behind the scenes, a std::string object manages a contiguous block of memory. This memory holds the collection of char values that make up the string.

The data() method of std::string returns the memory address where this block of memory starts:

1std::string Content{"Hello"};
2void* DataAddress{Content.data()};
3std::cout << DataAddress;

1000000C4E77BF760

In most use cases, we don't need to worry about this block of memory. In fact, the main benefit of the std::string class over something like a char* is that std::string mostly absolves us of the need to manage memory. The std::string class takes care of it for us.

For example, if we use a std::string method or operation that would cause the string to no longer fit within the allocated memory, the std::string class will automatically allocate a new, larger memory block, and automatically copy our string content to the new location.

The following program shows an example of this behavior:

1#include <iostream>
2
3int main() {
4  std::string Content{"Hello"};
5  std::cout << "Memory Location is       "
6    << static_cast<void*>(Content.data());
7
8  Content += "World";
9  std::cout << "\nMemory Location is still "
10    << static_cast<void*>(Content.data());
11
12  Content += "This is too much content for the "
13    "current memory location";
14  std::cout << "\nString has moved to      "
15    << static_cast<void*>(Content.data());
16}

1Memory Location is       0000007F5EFEFCA0
2Memory Location is still 0000007F5EFEFCA0
3String has moved to      000001D3BCF98150

However, when we're working with a string's underlying memory address (by accessing it through the data() method, for example), we're bypassing the string's automatic memory management. As such, responsibility falls back on us to ensure that whatever we're doing with that pointer isn't going to introduce memory-related bugs.

The most common use case for retrieving the data() pointer is that we want to write content directly to the location that the std::string is managing. Therefore, we need to ensure that the std::string has allocated enough capacity to accommodate the amount of data we're going to write into its memory.

We can find the current capacity of a std::string using the capacity() method.
We can increase the capacity by passing an integer to the reserve() method, which ensures our std::string can hold at least that number of characters, and usually slightly more.

Here's an example:

1std::string Content{"Hello"};
2std::cout << "Capacity: " << Content.capacity();
3Content.reserve(100);
4std::cout << "\nCapacity: " << Content.capacity();

1Capacity: 15
2Capacity: 111

String Capacity vs Size vs Length

Note that the capacity of a std::string is not necessarily the same as its length.

The capacity() method returns how many characters the std::string can manage in its current memory location
The length() method returns how much of that capacity is currently used - that is, how many characters are currently in the string
The size() method is the same as length() - it returns the exact same value. This alias exists primarily for compatibility with algorithms that require the container to have a size() method
The empty() method returns a bool, and provides a short-hand way to determine if the size/length of the string is 0

Here's an example:

1std::string Content{"Hello"};
2std::cout << "Capacity: " << Content.capacity();
3std::cout << "\nLength: " << Content.length();
4std::cout << "\nSize: " << Content.size();
5std::cout << "\nEmpty: "
6  << std::boolalpha << Content.empty();

1Capacity: 15
2Length: 5
3Size: 5
4Empty: false

Let's use these techniques alongside SDL_RWops to write the content of our config.txt file directly into a std::string:

1SDL_RWops* File{SDL_RWFromFile(
2  "Config.txt", "rb")};
3
4// How many characters are in the file?
5Sint64 Size{SDL_RWsize(File)};
6
7// The string that we'll use to store
8// our file's content
9std::string Content;
10
11// Update the string's capacity to ensure it
12// can contain everything in the file
13Content.reserve(Size);
14
15// Populate the string with everything from
16// the file
17SDL_RWread(File, Content.data(), 1, Size);
18
19// Cleanup
20SDL_RWclose(File);
21
22std::cout << "Content:\n" << Content;

1Content:
2WINDOW_TITLE: Example Window
3WINDOW_WIDTH: 800
4WINDOW_HEIGHT: 600
5LEVELS: 1, 2, 3, 4

Finding Substrings

One of the main techniques we will need to understand the content of a string is to determine if the string contains some sequence of characters - that is, some other string. A specific string that is part of a larger string is sometimes called a substring.

We can find if our string contains a specific substring, and the position of that substring, using the find() method. Below, we search our "Hello World!" string for the "World" substring:

1std::string Content{"Hello World!"};
2size_t SubstringLocation{Content.find("World")};
3std::cout << "Location: " << SubstringLocation;

We find that Content does contain the "World" substring, and the substring starts at position 6:

1Location: 6

Like arrays, string indices start at 0, so this 6 value indicates that "World" begins at the 7th character.

In this example, we find where the first line break in our string is:

1std::string Content{
2  "WINDOW_TITLE: Example Window\n"
3  "WINDOW_WIDTH : 800\n"
4  "WINDOW_HEIGHT : 600\n"
5  "LEVELS: 1, 2, 3, 4"};
6
7std::cout << "First Line Break: "
8  << Content.find('\n');

1First Line Break: 28

If our string does not contain the substring we're searching for, the find() method will return a value equal to std::string::npos:

1std::string Content{
2  "WINDOW_TITLE: Example Window\n"
3  "WINDOW_WIDTH : 800\n"
4  "WINDOW_HEIGHT : 600\n"
5  "LEVELS: 1, 2, 3, 4"};
6
7if (Content.find("Hi") == std::string::npos) {
8  std::cout << "Cannot find \"Hi\"";
9}

1Cannot find "Hi"

Finding Multiple Substrings

The find() method accepts a second optional argument, indicating where we want our search to begin. In the following example, we skip the first 5 characters in our search, allowing us to find the second "Hello" in the string:

1std::string Content{"Hello World Hello"};
2
3std::cout << "First Hello: "
4  << Content.find("Hello");
5
6std::cout << "\nNext Hello: "
7  << Content.find("Hello", 5);

1First Hello: 0
2Next Hello: 12

This is primarily useful when we want to find every instance of a substring within our larger string. Below, we continuously call the find() method in a loop, until find() returns std::string::npos.

On every successful find(), we update our Start value with the index of the previous find, allowing us to advance through the string:

1std::string Content{
2  "WINDOW_TITLE: Example Window\n"
3  "WINDOW_WIDTH : 800\n"
4  "WINDOW_HEIGHT : 600\n"
5  "LEVELS: 1, 2, 3, 4"
6};
7
8size_t Start;
9size_t LineBreak{Content.find("\n")};
10
11while (LineBreak != std::string::npos) {
12  std::cout << "Line Break at "
13    << LineBreak << '\n';
14  Start = LineBreak + 1;
15  LineBreak = Content.find("\n", Start);
16}

1Line Break at 28
2Line Break at 47
3Line Break at 67

Creating Substrings

Beyond finding substrings, it can be helpful to create a new std::string based on the contents of some other std::string. We can do this using the substr() method, passing two arguments:

The position within the original string that we want our substring to begin
How many characters we want the substring to contain

Below, we create a substring by starting at position 6 of our Content, and copying 5 characters to our new string:

1std::string Content{"Hello World!"};
2std::string Substring{Content.substr(6, 5)};
3std::cout << Substring;

1World

The second argument is optional. If we omit it, our substring will continue until the end of the original string:

1std::string Content{"Hello World!"};
2std::string Substring{Content.substr(6)};
3std::cout << Substring;

1World!

Example: Combining `find()` and `substr()`

It's common for the arguments we pass to substr() to be determined based on the value returned by a find() call.

Below, we have a string comprising two lines. We find where the line break \n is, and use this index to create substrings containing the first and second lines of our original content:

1std::string Content{
2  "WINDOW_TITLE: Example Window\n"
3  "WINDOW_WIDTH : 800"};
4
5size_t LineBreak{Content.find('\n')};
6if (LineBreak != std::string::npos) {
7  std::string Line1{Content.substr(0, LineBreak)};
8  std::cout << "Line 1: " << Line1;
9  std::string Line2{Content.substr(LineBreak + 1)};
10  std::cout << "\nLine 2: " << Line2;
11}

1Line 1: WINDOW_TITLE: Example Window
2Line 2: WINDOW_WIDTH : 800

Example: Splitting Strings into Lines

Below, we expand our previous example to split a string into a dynamic number of substrings, based on how many line breaks our content has:

1std::string Content{
2  "WINDOW_TITLE: Example Window\n"
3  "WINDOW_WIDTH : 800\n"
4  "WINDOW_HEIGHT : 600\n"
5  "LEVELS: 1, 2, 3, 4"
6};
7
8size_t Start{0};
9size_t End{Content.find("\n", Start)};
10while (End != std::string::npos) {
11  std::cout << "Line: "
12    << Content.substr(Start, End - Start)
13    << '\n';
14
15  Start = End + 1;
16  End = Content.find("\n", Start);
17}
18
19// There are no more line breaks, but we haven't
20// printed the final line yet - let's do it
21std::cout << "Final Line: "
22  << Content.substr(Start);

1Line: WINDOW_TITLE: Example Window
2Line: WINDOW_WIDTH : 800
3Line: WINDOW_HEIGHT : 600
4Final Line: LEVELS: 1, 2, 3, 4

Example: Splitting Strings into Keys and Values

Each line of our sample content contains a key and value pair formatted as KEY: VALUE. We can split these lines into the key and value substrings by finding the ": " delimiter:

1std::string Content{
2  "WINDOW_TITLE: Example Window"
3};
4
5size_t Delim{Content.find(": ")};
6if (Delim == std::string::npos) {
7  std::cout << "Invalid Input";
8  return 0;
9};
10
11std::string Key{Content.substr(0, Delim)};
12std::string Value{Content.substr(Delim + 2)};
13
14std::cout << "Key: " << Key
15  << "\nValue: " << Value;

1Key: WINDOW_TITLE
2Value: Example Window

Example: Splitting Comma-Separated Strings

Finally, one of the keys in our sample content contains a comma-separated list of integers: 1,2,3,4. Here's one way we can parse such a string into its individual parts:

1std::string Content{"1,2,3,4"};
2size_t Start{0};
3size_t End {Content.find(",")};
4
5while (End != std::string::npos) {
6  std::cout << "Value: "
7    << Content.substr(Start, End - Start)
8    << '\n';
9  Start = End + 1;
10  End = Content.find(",", Start);
11}
12std::cout << "Final Value: "
13  << Content.substr(Start, End - Start);

1Value: 1
2Value: 2
3Value: 3
4Final Value: 4

This is just a basic overview of string handling that solves some of the more common problems. In our advanced course, we have a dedicated chapter on text processing.

This includes a deeper overview of the std::string class, as well as more advanced techniques such as regular expressions, which provide unlimited flexibility for processing and understanding text content.

The first lesson in that chapter is available here:

Characters, Unicode and Encoding

An introduction to C++ character types, the Unicode standard, character encoding, and C-style strings

View Related Lesson

Example: Loading a Configuration File

Let's combine these techniques to load our configuration file config.txt into a C++ Config struct. Our configuration file looks like this:

1// config.txt
2WINDOW_TITLE: Example Window
3WINDOW_WIDTH: 800
4WINDOW_HEIGHT: 600
5LEVELS: 1, 2, 3, 4

We'll add a public Load() method to our struct, which accepts the path to the file to load as an argument:

1// Config.h
2#pragma once
3#include <SDL.h>
4#include <iostream>
5#include <string>
6#include <vector>
7
8struct Config {
9  std::string WindowTitle;
10  int WindowWidth;
11  int WindowHeight;
12  std::vector<int> Levels;
13
14  void Load(const std::string& Path) {
15    // ...
16  }
17};

We'll add two private helper methods to break up our load process into multiple steps. The ReadFile() will load the file into a std::string and return it. The ParseConfig() function will then receive this string, and use it to update our data members:

1// Config.h
2// ...
3
4struct Config {
5  std::string WindowTitle;
6  int WindowWidth;
7  int WindowHeight;
8  std::vector<int> Levels;
9
10  void Load(const std::string& Path) {
11    std::string Content{ReadFile(Path)};
12    if (Content.empty()) return;
13    ParseConfig(Content);
14  }
15
16 private:
17  std::string ReadFile(const std::string& Path) {
18    // TODO
19    return "";
20  }
21
22  void ParseConfig(const std::string& Content) {
23    // TODO
24  }
25};

Our ReadFile() function will use the techniques we covered earlier, loading our content into a std::string and returning it:

1// Config.h
2// ...
3
4struct Config {
5  // ...
6 private:
7  std::string ReadFile(const std::string& Path) {
8    SDL_RWops* File{SDL_RWFromFile(
9      Path.c_str(), "rb")};
10    if (!File) {
11      std::cout << "Failed to open config file: "
12        << SDL_GetError() << "\n";
13      return "";
14    }
15
16    Sint64 Size{SDL_RWsize(File)};
17    std::string Content;
18    Content.reserve(Size);
19    SDL_RWread(File, Content.data(), 1, Size);
20    SDL_RWclose(File);
21    return Content;
22  }
23};

Our ParseConfig() function will find each line of text within the string, by finding \n characters in a loop. We'll create a new std::string for each line in our original std::string using the substr() method. We'll then hand it off to the ProcessLine() function:

1// Config.h
2// ...
3
4struct Config {
5  // ...
6 private:
7  void ParseConfig(const std::string& Content) {
8    size_t Start{0};
9    size_t End{Content.find("\n", Start)};
10    while (End != std::string::npos) {
11      ProcessLine(Content.substr(
12        Start, End - Start));
13      Start = End + 1;
14      End = Content.find("\n", Start);
15    }
16    
17    // There are no more line breaks, but we
18    // still need to process the last line
19    ProcessLine(Content.substr(Start));
20  }
21
22  void ProcessLine(const std::string& Line) {
23    // ...
24  }
25};

Our ProcessLine() function will split each line into a Key and Value substring, based on the position of the ": " substring within the line.

Then, based on the Key, we'll update the appropriate variable using the Value substring. For numeric types, we'll use std::stoi() to convert the string to an integer. For the Levels array, we'll offload the work to our final helper function, ParseLevels().

1// Config.h
2// ...
3
4struct Config {
5  // ...
6 private:
7  void ProcessLine(const std::string& Line) {
8    size_t Delim{Line.find(": ")};
9    if (Delim == std::string::npos) return;
10
11    std::string Key{Line.substr(0, Delim)};
12    std::string Value{Line.substr(Delim + 2)};
13
14    if (Key == "WINDOW_TITLE") {
15      WindowTitle = Value;
16    } else if (Key == "WINDOW_WIDTH") {
17      WindowWidth = std::stoi(Value);
18    } else if (Key == "WINDOW_HEIGHT") {
19      WindowHeight = std::stoi(Value);
20    } else if (Key == "LEVELS") {
21      ParseLevels(Value);
22    }
23  }
24
25  void ParseLevels(const std::string& Value) {
26    // TODO
27  }
28};

Our ParseLevels() function will start by clearing out existing values from our Levels array using the clear() method.

Then, we'll iterate through our levels string to find all of the , characters, and create substrings based on these positions.

We'll convert these numeric substrings to integers using the std::stoi() function, and push them onto our Levels array using the push_back() method:

1// Config.h
2// ...
3
4struct Config {
5  // ...
6 private:
7  void ParseLevels(const std::string& Value) {
8    Levels.clear();
9    size_t Start{0};
10    size_t End{Value.find(",", Start)};
11    
12    while (End != std::string::npos) {
13      Levels.push_back(std::stoi(Value.substr(
14        Start, End - Start)));
15      Start = End + 1;
16      End = Value.find(",", Start);
17    }
18    
19    // There are no more commas, but we still need
20    // to push the final number to our array
21    Levels.push_back(std::stoi(
22      Value.substr(Start)));
23  }
24};

Our final class is given below, and we've also included an example of using it within a basic SDL application.

Summary

In this lesson, we learned how to load a configuration file into a C++ struct. We used SDL_RWops to read the file contents into a std::string, and then applied various string methods to parse the data. Here are the key takeaways:

We used SDL_RWFromFile() to open the config file.
We determined the file size with SDL_RWsize().
We used std::string::find() and std::string::substr() to locate and extract keys and values.
We used std::stoi to convert string values to integers.
We created a Config struct to encapsulate these capabilities and hold our parsed settings.

Parsing Data using `std::string`

Loading Content into a `std::string`

Finding Substrings

Finding Multiple Substrings

Creating Substrings

Example: Combining `find()` and `substr()`

Example: Splitting Strings into Lines

Example: Splitting Strings into Keys and Values

Example: Splitting Comma-Separated Strings

Characters, Unicode and Encoding

Example: Loading a Configuration File

Summary

Writing Data to Files

Game Development with SDL2

Questions & Answers

Parsing Data using std::string

Loading Content into a std::string

Finding Substrings

Finding Multiple Substrings

Creating Substrings

Example: Combining find() and substr()

Example: Splitting Strings into Lines

Example: Splitting Strings into Keys and Values

Example: Splitting Comma-Separated Strings

Characters, Unicode and Encoding

Example: Loading a Configuration File

Summary

Writing Data to Files

Questions & Answers

Parsing Data using `std::string`

Loading Content into a `std::string`

Example: Combining `find()` and `substr()`