cv::FileStorage Class Reference

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

#include <opencv2/core/persistence.hpp>

Collaboration diagram for cv::FileStorage:

Public Types
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...
enum	State {   UNDEFINED = 0 ,   VALUE_EXPECTED = 1 ,   NAME_EXPECTED = 2 ,   INSIDE_MAP = 4 }

Public Member Functions
	FileStorage ()
	The constructors.
	FileStorage (const String &filename, int flags, const String &encoding=String())
virtual	~FileStorage ()
	the destructor. calls release()
void	endWriteStruct ()
	Finishes writing nested structure (should pair startWriteStruct())
FileNode	getFirstTopLevelNode () const
	Returns the first element of the top-level mapping.
int	getFormat () const
	Returns the current format.
virtual bool	isOpened () const
	Checks whether the file is opened.
virtual bool	open (const String &filename, int flags, const String &encoding=String())
	Opens a file.
FileNode	operator[] (const char *nodename) const
FileNode	operator[] (const String &nodename) const
	Returns the specified element of the top-level mapping.
virtual void	release ()
	Closes the file and releases all the memory buffers.
virtual String	releaseAndGetString ()
	Closes the file and releases all the memory buffers.
FileNode	root (int streamidx=0) const
	Returns the top-level mapping.
void	startWriteStruct (const String &name, int flags, const String &typeName=String())
	Starts to write a nested structure (sequence or a mapping).
void	write (const String &name, const Mat &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, const std::vector< 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, 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, double 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, int val)
	Simplified writing API to use with bindings.
void	write (const String &name, int64_t 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.
void	writeRaw (const String &fmt, const void *vec, size_t len)
	Writes multiple numbers.

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

Public Attributes
std::string	elname
Ptr< Impl >	p
int	state

Detailed Description

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

Examples

samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp, samples/cpp/tutorial_code/features/Homography/decompose_homography.cpp, samples/cpp/tutorial_code/features/Homography/homography_from_camera_displacement.cpp, samples/cpp/tutorial_code/features/Homography/pose_from_homography.cpp, and samples/dnn/classification.cpp.

Member Enumeration Documentation

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

State

enum cv::FileStorage::State

Enumerator
UNDEFINED	Initial or uninitialized state.
VALUE_EXPECTED	Expecting a value in the current position.
NAME_EXPECTED	Expecting a key/name in the current position.
INSIDE_MAP	Indicates being inside a map (a set of key-value pairs).

Constructor & Destructor Documentation

FileStorage() [1/2]

cv::FileStorage::FileStorage

(

)

Python:
	cv.FileStorage(		) ->	<FileStorage object>
	cv.FileStorage(	filename, flags[, encoding]	) ->	<FileStorage object>

The constructors.

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

FileStorage() [2/2]

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

Python:
	cv.FileStorage(		) ->	<FileStorage object>
	cv.FileStorage(	filename, flags[, encoding]	) ->	<FileStorage object>

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

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.

~FileStorage()

virtual cv::FileStorage::~FileStorage ( )

virtual

the destructor. calls release()

Member Function Documentation

endWriteStruct()

void cv::FileStorage::endWriteStruct

(

)

Python:
	cv.FileStorage.endWriteStruct(		) ->	None

Finishes writing nested structure (should pair startWriteStruct())

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

Python:
	cv.FileStorage.getFirstTopLevelNode(		) ->	retval

Returns the first element of the top-level mapping.

Returns

The first element of the top-level mapping.

getFormat()

int cv::FileStorage::getFormat

(

)

const

Python:
	cv.FileStorage.getFormat(		) ->	retval

Returns the current format.

Returns

The current format, see FileStorage::Mode

isOpened()

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

virtual

Python:
	cv.FileStorage.isOpened(		) ->	retval

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

samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

open()

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

virtual

Python:
	cv.FileStorage.open(	filename, flags[, encoding]	) ->	retval

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.

Examples

samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

operator[]() [1/2]

FileNode cv::FileStorage::operator[]

(

const char *

nodename

)

const

Python:
	cv.FileStorage.getNode(	nodename	) ->	retval

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

operator[]() [2/2]

FileNode cv::FileStorage::operator[]

(

const String &

nodename

)

const

Python:
	cv.FileStorage.getNode(	nodename	) ->	retval

Returns the specified element of the top-level mapping.

Parameters

nodename

Name of the file node.

Returns

Node with the given name.

release()

virtual void cv::FileStorage::release ( )

virtual

Python:
	cv.FileStorage.release(		) ->	None

Closes the file and releases all the memory buffers.

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

Examples

samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

releaseAndGetString()

virtual String cv::FileStorage::releaseAndGetString ( )

virtual

Python:
	cv.FileStorage.releaseAndGetString(		) ->	retval

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

root()

FileNode cv::FileStorage::root

(

int

streamidx = 0

)

const

Python:
	cv.FileStorage.root(	[, streamidx]	) ->	retval

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.

startWriteStruct()

void cv::FileStorage::startWriteStruct	(	const String &	name,
		int	flags,
		const String &	typeName = String()
	)

Python:
	cv.FileStorage.startWriteStruct(	name, flags[, typeName]	) ->	None

Starts to write a nested structure (sequence or a mapping).

Parameters

name	name of the structure. When writing to sequences (a.k.a. "arrays"), pass an empty string.
flags	type of the structure (FileNode::MAP or FileNode::SEQ (both with optional FileNode::FLOW)).
typeName	optional name of the type you store. The effect of setting this depends on the storage format. I.e. if the format has a specification for storing type information, this parameter is used.

write() [1/6]

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

Python:
	cv.FileStorage.write(	name, val	) ->	None

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

write() [2/6]

void cv::FileStorage::write	(	const String &	name,
		const std::vector< String > &	val
	)

Python:
	cv.FileStorage.write(	name, val	) ->	None

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

write() [3/6]

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

Python:
	cv.FileStorage.write(	name, val	) ->	None

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

write() [4/6]

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

Python:
	cv.FileStorage.write(	name, val	) ->	None

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

write() [5/6]

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

Python:
	cv.FileStorage.write(	name, val	) ->	None

Simplified writing API to use with bindings.

Parameters

name	Name of the written object. When writing to sequences (a.k.a. "arrays"), pass an empty string.
val	Value of the written object.

write() [6/6]

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

Python:
	cv.FileStorage.write(	name, val	) ->	None

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
	)

Python:
	cv.FileStorage.writeComment(	comment[, append]	) ->	None

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.

writeRaw()

void cv::FileStorage::writeRaw	(	const String &	fmt,
		const void *	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.

Member Data Documentation

elname

std::string cv::FileStorage::elname

p

Ptr<Impl> cv::FileStorage::p

state

int cv::FileStorage::state

---

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

• opencv2/core/persistence.hpp