diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 212 |
1 files changed, 128 insertions, 84 deletions
@@ -8,7 +8,7 @@ A cross-platform library that provides a simple API to read and write INI-style # Feature Summary - MIT Licence allows free use in all software (including GPL and commercial) -- multi-platform (Windows 95/98/ME/NT/2K/XP/2003, Windows CE, Linux, Unix) +- multi-platform (Windows 95 to Windows 10, Windows CE, Linux, Unix) - loading and saving of INI-style configuration files - configuration files can have any newline format on all platforms - liberal acceptance of file format @@ -18,19 +18,14 @@ A cross-platform library that provides a simple API to read and write INI-style - optional support for multiple keys with the same name - optional case-insensitive sections and keys (for ASCII characters only) - saves files with sections and keys in the same order as they were loaded -- preserves comments on the file, section and keys where possible. +- preserves comments on the file, section and keys where possible - supports both char or wchar_t programming interfaces - supports both MBCS (system locale) and UTF-8 file encodings - system locale does not need to be UTF-8 on Linux/Unix to load UTF-8 file - support for non-ASCII characters in section, keys, values and comments - support for non-standard character types or file encodings via user-written converter classes - support for adding/modifying values programmatically -- compiles cleanly in the following compilers: - * Windows/VC6 (warning level 3) - * Windows/VC.NET 2003 (warning level 4) - * Windows/VC 2005 (warning level 4) - * Linux/gcc (-Wall) - * Windows/MinGW GCC +- should compile with no warnings in most compilers # Documentation @@ -38,115 +33,164 @@ Full documentation of the interface is available in doxygen format. # Examples -These snippets are included with the distribution in the file snippets.cpp. +These snippets are included with the distribution in the automatic tests as ts-snippets.cpp. ### SIMPLE USAGE ```c++ -CSimpleIniA ini; -ini.SetUnicode(); -ini.LoadFile("myfile.ini"); -const char * pVal = ini.GetValue("section", "key", "default"); -ini.SetValue("section", "key", "newvalue"); + // simple demonstration + + CSimpleIniA ini; + ini.SetUnicode(); + + SI_Error rc = ini.LoadFile("example.ini"); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_OK); + + const char* pv; + pv = ini.GetValue("section", "key", "default"); + ASSERT_STREQ(pv, "value"); + + ini.SetValue("section", "key", "newvalue"); + + pv = ini.GetValue("section", "key", "default"); + ASSERT_STREQ(pv, "newvalue"); ``` ### LOADING DATA ```c++ -// load from a data file -CSimpleIniA ini(a_bIsUtf8, a_bUseMultiKey, a_bUseMultiLine); -SI_Error rc = ini.LoadFile(a_pszFile); -if (rc < 0) return false; - -// load from a string -std::string strData; -rc = ini.LoadData(strData.c_str(), strData.size()); -if (rc < 0) return false; + // load from a data file + CSimpleIniA ini; + SI_Error rc = ini.LoadFile("example.ini"); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_OK); + + // load from a string + const std::string example = "[section]\nkey = value\n"; + CSimpleIniA ini; + SI_Error rc = ini.LoadData(example); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_OK); ``` ### GETTING SECTIONS AND KEYS ```c++ -// get all sections -CSimpleIniA::TNamesDepend sections; -ini.GetAllSections(sections); + // get all sections + CSimpleIniA::TNamesDepend sections; + ini.GetAllSections(sections); -// get all keys in a section -CSimpleIniA::TNamesDepend keys; -ini.GetAllKeys("section-name", keys); + // get all keys in a section + CSimpleIniA::TNamesDepend keys; + ini.GetAllKeys("section1", keys); ``` ### GETTING VALUES ```c++ -// get the value of a key -const char * pszValue = ini.GetValue("section-name", - "key-name", NULL /*default*/); - -// get the value of a key which may have multiple -// values. If bHasMultipleValues is true, then just -// one value has been returned -bool bHasMultipleValues; -pszValue = ini.GetValue("section-name", "key-name", - NULL /*default*/, &bHasMultipleValues); - -// get all values of a key with multiple values -CSimpleIniA::TNamesDepend values; -ini.GetAllValues("section-name", "key-name", values); - -// sort the values into the original load order -values.sort(CSimpleIniA::Entry::LoadOrder()); - -// output all of the items -CSimpleIniA::TNamesDepend::const_iterator i; -for (i = values.begin(); i != values.end(); ++i) { - printf("key-name = '%s'\n", i->pItem); -} + // get the value of a key that doesn't exist + const char* pv; + pv = ini.GetValue("section1", "key99"); + ASSERT_EQ(pv, nullptr); + + // get the value of a key that does exist + pv = ini.GetValue("section1", "key1"); + ASSERT_STREQ(pv, "value1"); + + // get the value of a key which may have multiple + // values. If hasMultiple is true, then there are + // multiple values and just one value has been returned + bool hasMulti; + pv = ini.GetValue("section1", "key1", nullptr, &hasMulti); + ASSERT_STREQ(pv, "value1"); + ASSERT_EQ(hasMulti, false); + + pv = ini.GetValue("section1", "key2", nullptr, &hasMulti); + ASSERT_STREQ(pv, "value2.1"); + ASSERT_EQ(hasMulti, true); + + // get all values of a key with multiple values + CSimpleIniA::TNamesDepend values; + ini.GetAllValues("section1", "key2", values); + + // sort the values into a known order, in this case we want + // the original load order + values.sort(CSimpleIniA::Entry::LoadOrder()); + + // output all of the items + CSimpleIniA::TNamesDepend::const_iterator it; + for (it = values.begin(); it != values.end(); ++it) { + printf("value = '%s'\n", it->pItem); + } ``` ### MODIFYING DATA ```c++ -// adding a new section -rc = ini.SetValue("new-section", NULL, NULL); -if (rc < 0) return false; -printf("section: %s\n", rc == SI_INSERTED ? - "inserted" : "updated"); - -// adding a new key ("new-section" will be added -// automatically if it doesn't already exist) -rc = ini.SetValue("new-section", "new-key", "value"); -if (rc < 0) return false; -printf("key: %s\n", rc == SI_INSERTED ? - "inserted" : "updated"); - -// changing the value of a key -rc = ini.SetValue("section", "key", "updated-value"); -if (rc < 0) return false; -printf("key: %s\n", rc == SI_INSERTED ? - "inserted" : "updated"); + // add a new section + rc = ini.SetValue("section1", nullptr, nullptr); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_INSERTED); + + // not an error to add one that already exists + rc = ini.SetValue("section1", nullptr, nullptr); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_UPDATED); + + // get the value of a key that doesn't exist + const char* pv; + pv = ini.GetValue("section2", "key1", "default-value"); + ASSERT_STREQ(pv, "default-value"); + + // adding a key (the section will be added if needed) + rc = ini.SetValue("section2", "key1", "value1"); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_INSERTED); + + // ensure it is set to expected value + pv = ini.GetValue("section2", "key1", nullptr); + ASSERT_STREQ(pv, "value1"); + + // change the value of a key + rc = ini.SetValue("section2", "key1", "value2"); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_UPDATED); + + // ensure it is set to expected value + pv = ini.GetValue("section2", "key1", nullptr); + ASSERT_STREQ(pv, "value2"); ``` ### DELETING DATA ```c++ -// deleting a key from a section. Optionally the entire -// section may be deleted if it is now empty. -ini.Delete("section-name", "key-name", - true /*delete the section if empty*/); - -// deleting an entire section and all keys in it -ini.Delete("section-name", NULL); + // deleting a key from a section. Optionally the entire + // section may be deleted if it is now empty. + bool done, deleteSectionIfEmpty = true; + done = ini.Delete("section1", "key1", deleteSectionIfEmpty); + ASSERT_EQ(done, true); + done = ini.Delete("section1", "key1"); + ASSERT_EQ(done, false); + + // deleting an entire section and all keys in it + done = ini.Delete("section2", nullptr); + ASSERT_EQ(done, true); + done = ini.Delete("section2", nullptr); + ASSERT_EQ(done, false); ``` ### SAVING DATA ```c++ -// save the data to a string -rc = ini.Save(strData); -if (rc < 0) return false; - -// save the data back to the file -rc = ini.SaveFile(a_pszFile); -if (rc < 0) return false; + // save the data to a string + std::string data; + rc = ini.Save(data); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_OK); + + // save the data back to the file + rc = ini.SaveFile("example2.ini"); + if (rc < 0) { /* handle error */ }; + ASSERT_EQ(rc, SI_OK); ``` |