simpleini.h

iContact v0.75 iContact is designed to be an all-inclusive finger-friendly contact manager for Wind

        FileWriter(FILE * a_file) : m_file(a_file) { }
        void Write(const char * a_pBuf) {
            fputs(a_pBuf, m_file);
        }
    private:
        FileWriter(const FileWriter &);             // disable
        FileWriter & operator=(const FileWriter &); // disable
    };

    /** OutputWriter class to write the INI data to a string */
    class StringWriter : public OutputWriter {
        std::string & m_string;
    public:
        StringWriter(std::string & a_string) : m_string(a_string) { }
        void Write(const char * a_pBuf) {
            m_string.append(a_pBuf);
        }
    private:
        StringWriter(const StringWriter &);             // disable
        StringWriter & operator=(const StringWriter &); // disable
    };

#ifdef SI_SUPPORT_IOSTREAMS
    /** OutputWriter class to write the INI data to an ostream */
    class StreamWriter : public OutputWriter {
        std::ostream & m_ostream;
    public:
        StreamWriter(std::ostream & a_ostream) : m_ostream(a_ostream) { }
        void Write(const char * a_pBuf) {
            m_ostream << a_pBuf;
        }
    private:
        StreamWriter(const StreamWriter &);             // disable
        StreamWriter & operator=(const StreamWriter &); // disable
    };
#endif // SI_SUPPORT_IOSTREAMS

    /** Characterset conversion utility class to convert strings to the
        same format as is used for the storage.
    */
    class Converter : private SI_CONVERTER {
    public:
        Converter(bool a_bStoreIsUtf8) : SI_CONVERTER(a_bStoreIsUtf8) {
            m_scratch.resize(1024);
        }
        Converter(const Converter & rhs) { operator=(rhs); }
        Converter & operator=(const Converter & rhs) {
            m_scratch = rhs.m_scratch;
            return *this;
        }
        bool ConvertToStore(const SI_CHAR * a_pszString) {
            size_t uLen = SizeToStore(a_pszString);
            if (uLen == (size_t)(-1)) {
                return false;
            }
            while (uLen > m_scratch.size()) {
                m_scratch.resize(m_scratch.size() * 2);
            }
            return SI_CONVERTER::ConvertToStore(
                a_pszString,
                const_cast<char*>(m_scratch.data()),
                m_scratch.size());
        }
        const char * Data() { return m_scratch.data(); }
    private:
        std::string m_scratch;
    };

public:
    /*-----------------------------------------------------------------------*/

    /** Default constructor.

        @param a_bIsUtf8     See the method SetUnicode() for details.
        @param a_bMultiKey   See the method SetMultiKey() for details.
        @param a_bMultiLine  See the method SetMultiLine() for details.
     */
    CSimpleIniTempl(
        bool a_bIsUtf8 = false,
        bool a_bMultiKey = false,
        bool a_bMultiLine = false
        );

    /** Destructor */
    ~CSimpleIniTempl();

    /** Deallocate all memory stored by this object */
    void Reset();

    /*-----------------------------------------------------------------------*/
    /** @{ @name Settings */

    /** Set the storage format of the INI data. This affects both the loading
        and saving of the INI data using all of the Load/Save API functions.
        This value cannot be changed after any INI data has been loaded.

        If the file is not set to Unicode (UTF-8), then the data encoding is
        assumed to be the OS native encoding. This encoding is the system
        locale on Linux/Unix and the legacy MBCS encoding on Windows NT/2K/XP.
        If the storage format is set to Unicode then the file will be loaded
        as UTF-8 encoded data regardless of the native file encoding. If
        SI_CHAR == char then all of the char* parameters take and return UTF-8
        encoded data regardless of the system locale.

        \param a_bIsUtf8     Assume UTF-8 encoding for the source?
     */
    void SetUnicode(bool a_bIsUtf8 = true) {
        if (!m_pData) m_bStoreIsUtf8 = a_bIsUtf8;
    }

    /** Get the storage format of the INI data. */
    bool IsUnicode() const { return m_bStoreIsUtf8; }

    /** Should multiple identical keys be permitted in the file. If set to false
        then the last value encountered will be used as the value of the key.
        If set to true, then all values will be available to be queried. For
        example, with the following input:

        <pre>
        [section]
        test=value1
        test=value2
        </pre>

        Then with SetMultiKey(true), both of the values "value1" and "value2"
        will be returned for the key test. If SetMultiKey(false) is used, then
        the value for "test" will only be "value2". This value may be changed
        at any time.

        \param a_bAllowMultiKey  Allow multi-keys in the source?
     */
    void SetMultiKey(bool a_bAllowMultiKey = true) {
        m_bAllowMultiKey = a_bAllowMultiKey;
    }

    /** Get the storage format of the INI data. */
    bool IsMultiKey() const { return m_bAllowMultiKey; }

    /** Should data values be permitted to span multiple lines in the file. If
        set to false then the multi-line construct <<<TAG as a value will be
        returned as is instead of loading the data. This value may be changed
        at any time.

        \param a_bAllowMultiLine     Allow multi-line values in the source?
     */
    void SetMultiLine(bool a_bAllowMultiLine = true) {
        m_bAllowMultiLine = a_bAllowMultiLine;
    }

    /** Query the status of multi-line data */
    bool IsMultiLine() const { return m_bAllowMultiLine; }

    /*-----------------------------------------------------------------------*/
    /** @}
        @{ @name Loading INI Data */

    /** Load an INI file from disk into memory

        @param a_pszFile    Path of the file to be loaded. This will be passed
                            to fopen() and so must be a valid path for the
                            current platform.

        @return SI_Error    See error definitions
     */
    SI_Error LoadFile(
        const char * a_pszFile
        );

#ifdef SI_HAS_WIDE_FILE
    /** Load an INI file from disk into memory

        @param a_pwszFile   Path of the file to be loaded in UTF-16.

        @return SI_Error    See error definitions
     */
    SI_Error LoadFile(
        const SI_WCHAR_T * a_pwszFile
        );
#endif // SI_HAS_WIDE_FILE

    /** Load the file from a file pointer.

        @param a_fpFile     Valid file pointer to read the file data from. The
                            file will be read until end of file.

        @return SI_Error    See error definitions
    */
    SI_Error LoadFile(
        FILE * a_fpFile
        );

#ifdef SI_SUPPORT_IOSTREAMS
    /** Load INI file data from an istream.

        @param a_istream    Stream to read from

        @return SI_Error    See error definitions
     */
    SI_Error Load(
        std::istream & a_istream
        );
#endif // SI_SUPPORT_IOSTREAMS

    /** Load INI file data direct from a std::string

        @param a_strData    Data to be loaded

        @return SI_Error    See error definitions
     */
    SI_Error Load(const std::string & a_strData) {
        return Load(a_strData.c_str(), a_strData.size());
    }

    /** Load INI file data direct from memory

        @param a_pData      Data to be loaded
        @param a_uDataLen   Length of the data in bytes

        @return SI_Error    See error definitions
     */
    SI_Error Load(
        const char *    a_pData,
        size_t          a_uDataLen
        );

    /*-----------------------------------------------------------------------*/
    /** @}
        @{ @name Saving INI Data */

    /** Save an INI file from memory to disk

        @param a_pszFile    Path of the file to be saved. This will be passed
                            to fopen() and so must be a valid path for the
                            current platform.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is
                            in UTF-8 format. If it is not UTF-8 then
                            this parameter is ignored.

        @return SI_Error    See error definitions
     */
    SI_Error SaveFile(
        const char *    a_pszFile,
        bool            a_bAddSignature = true
        ) const;

#ifdef SI_HAS_WIDE_FILE
    /** Save an INI file from memory to disk

        @param a_pwszFile   Path of the file to be saved in UTF-16.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is
                            in UTF-8 format. If it is not UTF-8 then
                            this parameter is ignored.

        @return SI_Error    See error definitions
     */
    SI_Error SaveFile(
        const SI_WCHAR_T *  a_pwszFile,
        bool                a_bAddSignature = true
        ) const;
#endif // _WIN32

    /** Save the INI data to a file. See Save() for details.

        @param a_pFile      Handle to a file. File should be opened for
                            binary output.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is in
                            UTF-8 format. If it is not UTF-8 then this value is
                            ignored. Do not set this to true if anything has
                            already been written to the file.

        @return SI_Error    See error definitions
     */
    SI_Error SaveFile(
        FILE *  a_pFile,
        bool    a_bAddSignature = false
        ) const;

    /** Save the INI data. The data will be written to the output device
        in a format appropriate to the current data, selected by:

        <table>
            <tr><th>SI_CHAR     <th>FORMAT
            <tr><td>char        <td>same format as when loaded (MBCS or UTF-8)
            <tr><td>wchar_t     <td>UTF-8
            <tr><td>other       <td>UTF-8
        </table>

        Note that comments from the original data is preserved as per the
        documentation on comments. The order of the sections and values
        from the original file will be preserved.

        Any data prepended or appended to the output device must use the the
        same format (MBCS or UTF-8). You may use the GetConverter() method to
        convert text to the correct format regardless of the output format
        being used by SimpleIni.

        To add a BOM to UTF-8 data, write it out manually at the very beginning
        like is done in SaveFile when a_bUseBOM is true.

        @param a_oOutput    Output writer to write the data to.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is in
                            UTF-8 format. If it is not UTF-8 then this value is
                            ignored. Do not set this to true if anything has
                            already been written to the OutputWriter.

        @return SI_Error    See error definitions
     */
    SI_Error Save(
        OutputWriter &  a_oOutput,
        bool            a_bAddSignature = false
        ) const;

#ifdef SI_SUPPORT_IOSTREAMS
    /** Save the INI data to an ostream. See Save() for details.

        @param a_ostream    String to have the INI data appended to.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is in
                            UTF-8 format. If it is not UTF-8 then this value is
                            ignored. Do not set this to true if anything has
                            already been written to the stream.

        @return SI_Error    See error definitions
     */
    SI_Error Save(
        std::ostream &  a_ostream,
        bool            a_bAddSignature = false
        ) const
    {
        StreamWriter writer(a_ostream);
        return Save(writer, a_bAddSignature);
    }
#endif // SI_SUPPORT_IOSTREAMS

    /** Append the INI data to a string. See Save() for details.

        @param a_sBuffer    String to have the INI data appended to.

        @param a_bAddSignature  Prepend the UTF-8 BOM if the output data is in
                            UTF-8 format. If it is not UTF-8 then this value is
                            ignored. Do not set this to true if anything has
                            already been written to the string.

        @return SI_Error    See error definitions
     */
    SI_Error Save(
        std::string &   a_sBuffer,
        bool            a_bAddSignature = false
        ) const
    {
        StringWriter writer(a_sBuffer);
        return Save(writer, a_bAddSignature);
    }

    /*-----------------------------------------------------------------------*/
    /** @}
        @{ @name Accessing INI Data */

    /** Retrieve all section names. The list is returned as an STL vector of
        names and can be iterated or searched as necessary. Note that the
        collation order of the returned strings is NOT DEFINED.