Skip to content

Latest commit

 

History

History
267 lines (205 loc) · 6.52 KB

README.md

File metadata and controls

267 lines (205 loc) · 6.52 KB

ini.h

Logo

Release Version MIT License

Windows Build macOS Build Ubuntu Build

ini.h is a header-only library for reading and writing INI files in C++ through a simple, intuitive API.

Table of Contents

Preface

To start using ini.h, copy the single header file and drop it into your project. Now you can use the library by adding the following directive:

#include "ini.h"

Prerequisites

  • C++17 or higher

Usage

Reading and Writing INI Files

There are two ways to read and parse INI files with ini.h:

  1. Through a file path
  2. Through a file stream

File Path

#include "ini.h"

int main(int argc, char* argv[])
{
    ini::File file = ini::open("path/to/ini/example.ini");
}

File Stream

#include <fstream>
#include "ini.h"

int main(int argc, char* argv[])
{
    std::ifstream stream("path/to/ini/example.ini");
    ini::File file = ini::load(stream);

    // You are responsible for closing the file stream.
    stream.close();
}

As for writing, simply pass the destination path to the write function.

Writing to an INI File

#include "ini.h"

int main(int argc, char* argv[])
{
    ini::File file = ini::open("path/to/ini/example.ini");

    file.add_section("New Section");
    file["New Section"]["is_generic_key"] = "true";

    file.write("path/to/ini/example.ini");
}

Getting and Setting Values

You can retrieve values by using the operator[] but this will only return a string value. If you need a value in the form of a bool, for example, you can do so by using the get function.

Getting Values

#include "ini.h"

int main(int argc, char* argv[])
{
    ini::File file = ini::open("path/to/ini/example.ini");

    std::string title = file["FileInfo"]["title"];
    bool auto_save_enabled = file["FileInfo"].get<bool>("autoSaveEnabled"):
    size_t word_count = file["FileInfo"].get<size_t>("wordCount");
    double line_spacing = file["FileInfo"].get<double>("lineSpacing");
}

example.ini

[FileInfo]
title = On the topic of C++
author = John Appleseed
lastDateOpened = 2022-07-24
autoSaveEnabled = true
wordCount = 0
lineSpacing = 1.5

Setting values with can also be done with the subscript operator but this requires a string representation of the value you're trying to set.

If you already have a bool, a double, etc., you can simply use the set function. Those values will automatically be converted into a string representation for you.

Setting Values

#include "ini.h"

int main(int argc, char* argv[])
{
    ini::File file = ini::open("path/to/ini/example.ini");

    file["FileInfo"]["title"] = "On the topic of C#";
    file["FileInfo"].set<bool>("autoSaveEnabled", false);
    file["FileInfo"].set<size_t>("wordCount", 1);
    file["FileInfo"].set<double>("lineSpacing", 2.0);
}

example.ini

[FileInfo]
title = On the topic of C++
author = John Appleseed
lastDateOpened = 2022-07-24
autoSaveEnabled = true
wordCount = 0
lineSpacing = 1.5

Features

Comments

  • ; comment text
  • # comment text

ℹ️ Comments must start at the beginning of a line.

Case Sensitivity

Section names and keys are case-sensitive.

example.ini

[SECTION]
key = value
KEY = value

[section]
key = value
KEY = value

Delimiters

  • =
  • :

example.ini

[Section]
key1 = value
key2 : value

Supported Value Types

Documentation

Documentation

You can view more in-depth, MSDN-style documentation on the ini.h library here.