OpenCV: cv::FileStorage Class Reference

| OpenCV 3.4.2 Open Source Computer Vision

Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Related Functions | List of all members
cv::FileStorage Class Reference
Core functionality » XML/YAML Persistence

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"`

## Public Types
enum | { UNDEFINED = 0, VALUE_EXPECTED = 1, NAME_EXPECTED = 2, INSIDE_MAP = 4 }
enum | Mode { READ = 0, WRITE = 1, APPEND = 2, MEMORY = 4, FORMAT_MASK = (7<<3), FORMAT_AUTO = 0, FORMAT_XML = (1<<3), FORMAT_YAML = (2<<3), FORMAT_JSON = (3<<3), BASE64 = 64, WRITE_BASE64 = BASE64 | WRITE }
| file storage mode More...

## Public Member Functions
| FileStorage ()
| The constructors. More...
| FileStorage (const String &filename, int flags, const String &encoding=String())
| Opens a file. More...
| FileStorage (CvFileStorage *fs, bool owning=true)
virtual | ~FileStorage ()
| the destructor. calls release() More...
FileNode | getFirstTopLevelNode () const
| Returns the first element of the top-level mapping. More...
int | getFormat () const
| Returns the current format. More...
virtual bool | isOpened () const
| Checks whether the file is opened. More...
virtual bool | open (const String &filename, int flags, const String &encoding=String())
| Opens a file. More...
CvFileStorage * | operator* ()
| Returns the obsolete C FileStorage structure. More...
const CvFileStorage * | operator* () const
FileNode | operator[] (const String &nodename) const
| Returns the specified element of the top-level mapping. More...
FileNode | operator[] (const char *nodename) const
virtual void | release ()
| Closes the file and releases all the memory buffers. More...
virtual String | releaseAndGetString ()
| Closes the file and releases all the memory buffers. More...
FileNode | root (int streamidx=0) const
| Returns the top-level mapping. More...
void | write (const String &name, int val)
| Simplified writing API to use with bindings. More...
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)
| Writes a comment. More...
void | writeObj (const String &name, const void *obj)
| Writes the registered C structure (CvMat, CvMatND, CvSeq). More...
void | writeRaw (const String &fmt, const uchar *vec, size_t len)
| Writes multiple numbers. More...

## Static Public Member Functions
static String | getDefaultObjectName (const String &filename)
| Returns the normalized object name for the specified name of a file. More...

## Public Attributes
String | elname
| the currently written element More...
Ptr< CvFileStorage > | fs
| the underlying C FileStorage structure More...
int | state
| the writer state More...
std::vector< char > | structs
| the stack of written structures More...

## Related Functions
(Note that these are not member functions.)
FileStorage & | operator<< (FileStorage &fs, const String &str)
| Writes string to a file storage. More...
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 | 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)
template<>
void | write (FileStorage &fs, const int &value)
template<>
void | write (FileStorage &fs, const float &value)
template<>
void | write (FileStorage &fs, const double &value)
template<>
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 Range &r)
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 &kpt)
static void | write (FileStorage &fs, const String &name, const DMatch &m)
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)
| Writes data to a file storage. More...
static FileStorage & | operator<< (FileStorage &fs, const char *str)
| Writes data to a file storage. More...
static FileStorage & | operator<< (FileStorage &fs, char *value)
| Writes data to a file storage. More...

## Detailed Description

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

Examples:
  decompose_homography.cpp, filestorage.cpp, homography_from_camera_displacement.cpp, and pose_from_homography.cpp.

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

Enumerator
UNDEFINED |
VALUE_EXPECTED |
NAME_EXPECTED |
INSIDE_MAP |

## ◆ Mode

enum cv::FileStorage::Mode

file storage mode

Enumerator
READ | value, open the file for reading
WRITE | value, open the file for writing
APPEND | value, open the file for appending
MEMORY | flag, read data from source or write data to the internal buffer (which is returned by FileStorage::release)
FORMAT_MASK | mask for format flags
FORMAT_AUTO | flag, auto format
FORMAT_XML | flag, XML format
FORMAT_YAML | flag, YAML format
FORMAT_JSON | flag, JSON format
BASE64 | flag, write rawdata in Base64 by default. (consider using WRITE_BASE64)
WRITE_BASE64 | flag, enable both WRITE and BASE64

## Constructor & Destructor Documentation

## ◆ FileStorage() [1/3]

cv::FileStorage::FileStorage | ( |  | ) |

The constructors.

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

## ◆ FileStorage() [2/3]

cv::FileStorage::FileStorage | ( | const String & | filename,
|  | int | flags,
|  | const String & | encoding = `String()`
| ) |  |

Opens a file.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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.

## ◆ FileStorage() [3/3]

cv::FileStorage::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.

## ◆ ~FileStorage()

virtual cv::FileStorage::~FileStorage | ( |  | ) |
| virtual

the destructor. calls release()

## Member Function Documentation

## ◆ getDefaultObjectName()

static String cv::FileStorage::getDefaultObjectName | ( | const String & | filename | ) |
| static

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

Parameters

  filename | Name of a file

Returns
  The normalized object name.

## ◆ getFirstTopLevelNode()

FileNode cv::FileStorage::getFirstTopLevelNode | ( |  | ) | const

Returns the first element of the top-level mapping.

Returns
  The first element of the top-level mapping.

## ◆ getFormat()

int cv::FileStorage::getFormat | ( |  | ) | const

Returns the current format.

Returns
  The current format, see FileStorage::Mode

## ◆ isOpened()

virtual bool cv::FileStorage::isOpened | ( |  | ) | const
| virtual

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.

Examples:
  filestorage.cpp.

## ◆ open()

virtual bool cv::FileStorage::open | ( | const String & | filename,
|  | int | flags,
|  | const String & | encoding = `String()`
| ) |  |
| virtual

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.

## ◆ operator*() [1/2]

CvFileStorage* cv::FileStorage::operator* | ( |  | ) |
| inline

Returns the obsolete C FileStorage structure.

Returns
  Pointer to the underlying C FileStorage structure

## ◆ operator*() [2/2]

const CvFileStorage* cv::FileStorage::operator* | ( |  | ) | const
| inline

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

## ◆ operator[]() [1/2]

FileNode cv::FileStorage::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.

## ◆ operator[]() [2/2]

FileNode cv::FileStorage::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.

## ◆ release()

virtual void cv::FileStorage::release | ( |  | ) |
| virtual

Closes the file and releases all the memory buffers.

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

## ◆ releaseAndGetString()

virtual String cv::FileStorage::releaseAndGetString | ( |  | ) |
| virtual

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

Examples:
  filestorage.cpp.

## ◆ root()

FileNode cv::FileStorage::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.

## ◆ write() [1/4]

void cv::FileStorage::write | ( | const String & | name,
|  | int | val
| ) |  |

Simplified writing API to use with bindings.

Parameters

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

## ◆ write() [2/4]

void cv::FileStorage::write | ( | const String & | name,
|  | double | val
| ) |  |

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

## ◆ write() [3/4]

void cv::FileStorage::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.

## ◆ write() [4/4]

void cv::FileStorage::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.

## ◆ writeComment()

void cv::FileStorage::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.

## ◆ writeObj()

void cv::FileStorage::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.

## ◆ writeRaw()

void cv::FileStorage::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.

## Friends And Related Function Documentation

## ◆ operator<<() [1/4]

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

Writes string to a file storage.

## ◆ operator<<() [2/4]

template<typename _Tp >

static FileStorage & operator<< | ( | FileStorage & | fs,
|  | const _Tp & | value
| ) |  |
| related

Writes data to a file storage.

## ◆ operator<<() [3/4]

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

Writes data to a file storage.

## ◆ operator<<() [4/4]

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

Writes data to a file storage.

## ◆ write() [1/32]

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

## ◆ write() [2/32]

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

## ◆ write() [3/32]

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

## ◆ write() [4/32]

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

## ◆ write() [5/32]

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

## ◆ write() [6/32]

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

## ◆ write() [7/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const _Tp & | value
| ) |  |
| related

## ◆ write() [8/32]

void write | ( | FileStorage & | fs,
|  | const int & | value
| ) |  |
| related

## ◆ write() [9/32]

void write | ( | FileStorage & | fs,
|  | const float & | value
| ) |  |
| related

## ◆ write() [10/32]

void write | ( | FileStorage & | fs,
|  | const double & | value
| ) |  |
| related

## ◆ write() [11/32]

void write | ( | FileStorage & | fs,
|  | const String & | value
| ) |  |
| related

## ◆ write() [12/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Point_< _Tp > & | pt
| ) |  |
| related

## ◆ write() [13/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Point3_< _Tp > & | pt
| ) |  |
| related

## ◆ write() [14/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Size_< _Tp > & | sz
| ) |  |
| related

## ◆ write() [15/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Complex< _Tp > & | c
| ) |  |
| related

## ◆ write() [16/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Rect_< _Tp > & | r
| ) |  |
| related

## ◆ write() [17/32]

template<typename _Tp , int cn>

static void write | ( | FileStorage & | fs,
|  | const Vec< _Tp, cn > & | v
| ) |  |
| related

## ◆ write() [18/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const Scalar_< _Tp > & | s
| ) |  |
| related

## ◆ write() [19/32]

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

## ◆ write() [20/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const std::vector< _Tp > & | vec
| ) |  |
| related

## ◆ write() [21/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Point_< _Tp > & | pt
| ) |  |
| related

## ◆ write() [22/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Point3_< _Tp > & | pt
| ) |  |
| related

## ◆ write() [23/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Size_< _Tp > & | sz
| ) |  |
| related

## ◆ write() [24/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Complex< _Tp > & | c
| ) |  |
| related

## ◆ write() [25/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Rect_< _Tp > & | r
| ) |  |
| related

## ◆ write() [26/32]

template<typename _Tp , int cn>

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Vec< _Tp, cn > & | v
| ) |  |
| related

## ◆ write() [27/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const Scalar_< _Tp > & | s
| ) |  |
| related

## ◆ write() [28/32]

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

## ◆ write() [29/32]

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const KeyPoint & | kpt
| ) |  |
| related

## ◆ write() [30/32]

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const DMatch & | m
| ) |  |
| related

## ◆ write() [31/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const std::vector< _Tp > & | vec
| ) |  |
| related

## ◆ write() [32/32]

template<typename _Tp >

static void write | ( | FileStorage & | fs,
|  | const String & | name,
|  | const std::vector< std::vector< _Tp > > & | vec
| ) |  |
| related

## ◆ writeScalar() [1/4]

void writeScalar | ( | FileStorage & | fs,
|  | int | value
| ) |  |
| related

## ◆ writeScalar() [2/4]

void writeScalar | ( | FileStorage & | fs,
|  | float | value
| ) |  |
| related

## ◆ writeScalar() [3/4]

void writeScalar | ( | FileStorage & | fs,
|  | double | value
| ) |  |
| related

## ◆ writeScalar() [4/4]

void writeScalar | ( | FileStorage & | fs,
|  | const String & | value
| ) |  |
| related

## Member Data Documentation

## ◆ elname

String cv::FileStorage::elname

the currently written element

## ◆ fs

Ptr<CvFileStorage> cv::FileStorage::fs

the underlying C FileStorage structure

## ◆ state

int cv::FileStorage::state

the writer state

## ◆ structs

std::vector<char> cv::FileStorage::structs

the stack of written structures

The documentation for this class was generated from the following file:

- core/include/opencv2/core/persistence.hpp