class cv::FileStorage

Overview

XML/YAML/JSON file storage class that encapsulates all the information necessary for writing or reading data to/from a file. More…

#include <persistence.hpp>

class FileStorage
{
public:
    // enums

    enum
    {
        UNDEFINED      = 0,
        VALUE_EXPECTED = 1,
        NAME_EXPECTED  = 2,
        INSIDE_MAP     = 4,
    };

    enum Mode;

    // fields

    String elname;
    Ptr<CvFileStorage> fs;
    int state;
    std::vector<char> structs;

    // construction

    FileStorage();

    FileStorage(
        const String& source,
        int flags,
        const String& encoding = String()
        );

    FileStorage(
        CvFileStorage* fs,
        bool owning = true
        );

    // methods

    void
    write(
        FileStorage& fs,
        const String& name,
        int value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        float value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        double value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        const String& value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        const Mat& value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        const SparseMat& value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        const std::vector<KeyPoint>& value
        );

    void
    write(
        FileStorage& fs,
        const String& name,
        const std::vector<DMatch>& value
        );

    void
    writeScalar(
        FileStorage& fs,
        int value
        );

    void
    writeScalar(
        FileStorage& fs,
        float value
        );

    void
    writeScalar(
        FileStorage& fs,
        double value
        );

    void
    writeScalar(
        FileStorage& fs,
        const String& value
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const _Tp& value
        );

    void
    write(
        FileStorage& fs,
        const int& value
        );

    void
    write(
        FileStorage& fs,
        const float& value
        );

    void
    write(
        FileStorage& fs,
        const double& value
        );

    void
    write(
        FileStorage& fs,
        const String& value
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Point_<_Tp>& pt
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Point3_<_Tp>& pt
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Size_<_Tp>& sz
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Complex<_Tp>& c
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Rect_<_Tp>& r
        );

    template <
        typename _Tp,
        int cn
        >
    static
    void
    write(
        FileStorage& fs,
        const Vec<_Tp, cn>& v
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const Scalar_<_Tp>& s
        );

    static
    void
    write(
        FileStorage& fs,
        const KeyPoint& kpt
        );

    static
    void
    write(
        FileStorage& fs,
        const DMatch& m
        );

    static
    void
    write(
        FileStorage& fs,
        const Range& r
        );

    static
    void
    write(
        FileStorage& fs,
        const std::vector<KeyPoint>& vec
        );

    static
    void
    write(
        FileStorage& fs,
        const std::vector<DMatch>& vec
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const std::vector<_Tp>& vec
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Point_<_Tp>& pt
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Point3_<_Tp>& pt
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Size_<_Tp>& sz
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Complex<_Tp>& c
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Rect_<_Tp>& r
        );

    template <
        typename _Tp,
        int cn
        >
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Vec<_Tp, cn>& v
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Scalar_<_Tp>& s
        );

    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const Range& r
        );

    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const KeyPoint& r
        );

    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const DMatch& r
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const std::vector<_Tp>& vec
        );

    template <typename _Tp>
    static
    void
    write(
        FileStorage& fs,
        const String& name,
        const std::vector<std::vector<_Tp>>& vec
        );

    template <typename _Tp>
    static
    FileStorage&
    operator<<(
        FileStorage& fs,
        const _Tp& value
        );

    static
    FileStorage&
    operator<<(
        FileStorage& fs,
        const char* str
        );

    static
    FileStorage&
    operator<<(
        FileStorage& fs,
        char* value
        );

    FileNode
    getFirstTopLevelNode() const;

    virtual
    bool
    isOpened() const;

    virtual
    bool
    open(
        const String& filename,
        int flags,
        const String& encoding = String()
        );

    CvFileStorage*
    operator*();

    const CvFileStorage*
    operator*() const;

    FileNode
    operator[](const String& nodename) const;

    FileNode
    operator[](const char* nodename) const;

    virtual
    void
    release();

    virtual
    String
    releaseAndGetString();

    FileNode
    root(int streamidx = 0) const;

    void
    write(
        const String& name,
        double val
        );

    void
    write(
        const String& name,
        const String& val
        );

    void
    write(
        const String& name,
        InputArray val
        );

    void
    writeComment(
        const String& comment,
        bool append = false
        );

    void
    writeObj(
        const String& name,
        const void* obj
        );

    void
    writeRaw(
        const String& fmt,
        const uchar* vec,
        size_t len
        );

    static
    String
    getDefaultObjectName(const String& filename);

    FileStorage&
    operator<<(
        FileStorage& fs,
        const String& str
        );
};

Detailed Documentation

XML/YAML/JSON file storage class that encapsulates all the information necessary for writing or reading data to/from a file.

Fields

String elname

the currently written element

Ptr<CvFileStorage> fs

the underlying C FileStorage structure

int state

the writer state

std::vector<char> structs

the stack of written structures

Construction

FileStorage()

The constructors.

The full constructor opens the file. Alternatively you can use the default constructor and then call FileStorage::open.

FileStorage(
    const String& source,
    int flags,
    const String& encoding = String()
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

source	Name of the file to open or the text string to read the data from. Extension of the file (.xml, .yml/.yaml, or .json) determines its format (XML, YAML or JSON respectively). Also you can append .gz to work with compressed files, for example myHugeMatrix.xml.gz. If both FileStorage::WRITE and FileStorage::MEMORY flags are specified, source is used just to specify the output file format (e.g. mydata.xml, .yml etc.).
flags	Mode of operation. See FileStorage::Mode
encoding	Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.

FileStorage(
    CvFileStorage* fs,
    bool owning = true
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Methods

template <typename _Tp>
static
FileStorage&
operator<<(
    FileStorage& fs,
    const _Tp& value
    )

Writes data to a file storage.

static
FileStorage&
operator<<(
    FileStorage& fs,
    const char* str
    )

Writes data to a file storage.

static
FileStorage&
operator<<(
    FileStorage& fs,
    char* value
    )

Writes data to a file storage.

FileNode
getFirstTopLevelNode() const

Returns the first element of the top-level mapping.

Returns:

The first element of the top-level mapping.

virtual
bool
isOpened() const

Checks whether the file is opened.

Returns:

true if the object is associated with the current file and false otherwise. It is a good practice to call this method after you tried to open a file.

virtual
bool
open(
    const String& filename,
    int flags,
    const String& encoding = String()
    )

Opens a file.

See description of parameters in FileStorage::FileStorage. The method calls FileStorage::release before opening the file.

Parameters:

filename	Name of the file to open or the text string to read the data from. Extension of the file (.xml, .yml/.yaml or .json) determines its format (XML, YAML or JSON respectively). Also you can append .gz to work with compressed files, for example myHugeMatrix.xml.gz. If both FileStorage::WRITE and FileStorage::MEMORY flags are specified, source is used just to specify the output file format (e.g. mydata.xml, .yml etc.). A file name can also contain parameters. You can use this format, “*?base64” (e.g. “file.json?base64” (case sensitive)), as an alternative to FileStorage::BASE64 flag.
flags	Mode of operation. One of FileStorage::Mode
encoding	Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.

CvFileStorage*
operator*()

Returns the obsolete C FileStorage structure.

Returns:

Pointer to the underlying C FileStorage structure

const CvFileStorage*
operator*() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

FileNode
operator[](const String& nodename) const

Returns the specified element of the top-level mapping.

Parameters:

nodename

Name of the file node.

Returns:

Node with the given name.

FileNode
operator[](const char* nodename) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual
void
release()

Closes the file and releases all the memory buffers.

Call this method after all I/O operations with the storage are finished.

virtual
String
releaseAndGetString()

Closes the file and releases all the memory buffers.

Call this method after all I/O operations with the storage are finished. If the storage was opened for writing data and FileStorage::WRITE was specified

FileNode
root(int streamidx = 0) const

Returns the top-level mapping.

Parameters:

streamidx

Zero-based index of the stream. In most cases there is only one stream in the file. However, YAML supports multiple streams and so there can be several.

Returns:

The top-level mapping.

void
write(
    const String& name,
    double val
    )

Simplified writing API to use with bindings.

Parameters:

name	Name of the written object
val	Value of the written object

void
write(
    const String& name,
    const String& val
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
write(
    const String& name,
    InputArray val
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void
writeComment(
    const String& comment,
    bool append = false
    )

Writes a comment.

The function writes a comment into file storage. The comments are skipped when the storage is read.

Parameters:

comment	The written comment, single-line or multi-line
append	If true, the function tries to put the comment at the end of current line. Else if the comment is multi-line, or if it does not fit at the end of the current line, the comment starts a new line.

void
writeObj(
    const String& name,
    const void* obj
    )

Writes the registered C structure (CvMat, CvMatND, CvSeq).

Parameters:

name	Name of the written object.
obj	Pointer to the object.

See also:

ocvWrite for details.

void
writeRaw(
    const String& fmt,
    const uchar* vec,
    size_t len
    )

Writes multiple numbers.

Writes one or more numbers of the specified format to the currently written structure. Usually it is more convenient to use operator << instead of this method.

Parameters:

fmt	Specification of each array element, see format specification
vec	Pointer to the written array.
len	Number of the uchar elements to write.

static
String
getDefaultObjectName(const String& filename)

Returns the normalized object name for the specified name of a file.

Parameters:

filename

Name of a file

Returns:

The normalized object name.

FileStorage&
operator<<(
    FileStorage& fs,
    const String& str
    )

Writes string to a file storage.