Implements interface to access to the AVDictionary entity. More...

#include <dictionary.h>

Inheritance diagram for av::Dictionary:

Collaboration diagram for av::Dictionary:

Classes
struct	AvStringDeleter
	Deleter for raw string. More...

struct	AvStringPtr
	RAII holder for strings allocated by FFmpeg internals. More...

class	DictionaryIterator
	Base dictionary iterator implementation. More...

class	Entry
	Dictionary key and value holder and accessor. More...

Public Types
enum	Flags { FlagMatchCase = AV_DICT_MATCH_CASE, FlagIgnoreSuffix = AV_DICT_IGNORE_SUFFIX, FlagDontStrdupKey = AV_DICT_DONT_STRDUP_KEY, FlagDontStrdupVal = AV_DICT_DONT_STRDUP_VAL, FlagDontOverwrite = AV_DICT_DONT_OVERWRITE, FlagAppend = AV_DICT_APPEND }
	AVDictionary flags mapping. More...

using	Iterator = DictionaryIterator< false >
	Non-const iterator. More...

using	ConstIterator = DictionaryIterator< true >
	Const iterator. More...

Public Member Functions

Dictionary ()

Default ctor do nothig, null dictionary creates. More...

Dictionary (AVDictionary *dict, bool takeOwning=true)

Assign ctor Wrap around raw dictionary. More...

~Dictionary ()

Dtor If Dictionary takes ownershipping on AVDictionary, it free allocated resources. More...

Dictionary (const Dictionary &other)

Copy ctor Make deep copy of dictionary. More...

Dictionary & operator= (const Dictionary &rhs)

Copy assign operator Make deep copy of dictionary. More...

Dictionary (Dictionary &&other)

Move ctor Takes resources. More...

Dictionary & operator= (Dictionary &&rhs)

Move assign operator Takes resources. More...

Dictionary (std::initializer_list< std::pair< const char *, const char * >> list, int flags=0)

Initializer ctor Allows create dictionaries in array manier: More...

Dictionary & operator= (std::initializer_list< std::pair< const char *, const char * >> list)

Initializer assign operator Allows assign dictionaries in array manier: More...

bool isOwning () const noexcept

isOwning - checks resources owning status More...

void assign (AVDictionary *dict, bool takeOwning=true) noexcept

assign - assign new resouces Old dictionary destroyes (if owning). More...

template<typename Key , typename Value = Key>

auto set (const Key &key, const Value &value, OptionalErrorCode ec=throws(), int flags=0) -> typename std::enable_if<(std::is_same< Key, std::string >::value||std::is_same< typename std::remove_cv< typename std::decay< Key >::type >::type, char * >::value) &&(std::is_same< Value, std::string >::value||std::is_same< typename std::remove_cv< typename std::decay< Value >::type >::type, char * >::value||std::is_integral< Value >::value), void >::type

set - set new value for key or add new dictionary item (or create dictionary) If dictionary empty (null), it takes ownershipping too. More...

template<typename Str , typename Sep1 , typename Sep2 >

void parseString (const Str &str, const Sep1 &keyValSep, const Sep2 &pairsSep, int flags=0, OptionalErrorCode ec=throws())

parseString - process string with options and fill dictionary String examples: More...

std::string toString (const char keyValSep, const char pairsSep, OptionalErrorCode ec=throws()) const

toString - converts dictionary to the string representation (serialize) More...

AvStringPtr toRawStringPtr (const char keyValSep, const char pairsSep, OptionalErrorCode ec=throws()) const

toRawStringPtr - converts dictionary to the raw string (char*) and protect it with smart pointer (std::unique_ptr). More...

void copyFrom (const Dictionary &other, int flags=0) noexcept

copyFrom - copy data from other dictionary. More...

void swap (Dictionary &other) noexcept

swap - swaps resouces between objects More...

AVDictionary * release ()

release - drops ownershipping More...

AVDictionary ** rawPtr () noexcept

Iterator interface

Iterator begin ()

Iterator end ()

ConstIterator begin () const

ConstIterator end () const

ConstIterator cbegin () const

ConstIterator cend () const

Index based access operator

operator [] - access to the entry via index O(1) complexity.

Parameters

index

Returns

const char * operator[] (size_t index) const

Entry operator[] (size_t index)

Key based access operator

operator [] - access to the entry via key O(n) complexity.

Parameters

key

Returns

const char * operator[] (const char *key) const

Entry operator[] (const char *key) noexcept

Entries counting

count/size - returns count of dictionary entries.

O(1) complexity.

Returns

size_t count () const noexcept

size_t size () const noexcept

Key based getter interface

get - gets value by key O(n) complexity.

Parameters

key	key for entry access
flags	see Flags

Returns: nullptr if key does not present

const char * get (const char *key, int flags=0) const noexcept

const char * get (const std::string &key, int flags=0) const noexcept

Public Member Functions inherited from FFWrapperPtr< AVDictionary >

FFWrapperPtr ()=default

FFWrapperPtr (AVDictionary *raw)

const AVDictionary * raw () const

AVDictionary * raw ()

void reset (AVDictionary *raw=nullptr)

bool isNull () const

void _log (int level, const char *fmt) const

void _log (int level, const char *fmt, const Args &... args) const

Additional Inherited Members
Protected Attributes inherited from FFWrapperPtr< AVDictionary >
AVDictionary *	m_raw

Detailed Description

Implements interface to access to the AVDictionary entity.

It also add useful extensions, like:

Iterator interface: you can walk via dictionary entries via foreach cycles
Initialization list construction: you can initialize dictionary simple as structure or array

This class also provide way to controll owning: you can create entity that does not owning data but provide access to them. You can drop owning by release() call.

Member Typedef Documentation

◆ ConstIterator

using av::Dictionary::ConstIterator = DictionaryIterator<true>

Const iterator.

◆ Iterator

using av::Dictionary::Iterator = DictionaryIterator<false>

Non-const iterator.

Member Enumeration Documentation

◆ Flags

enum av::Dictionary::Flags

AVDictionary flags mapping.

Enumerator
FlagMatchCase	Do not ignore case.
FlagIgnoreSuffix	Special case: Iterate via dictionary.
FlagDontStrdupKey	Do not duplicate string key. String must be duplicate before with av_strdup() or allocates with av_malloc(). Do not use new[] for it! This flag ignores for std::string keys.
FlagDontStrdupVal	Do not duplicate string value. String must be duplicate before with av_strdup() or allocates with av_malloc(). Do not use new[] for it! This flag ignores for std::string values and for integer values
FlagDontOverwrite	Keep existing value if key already exists.
FlagAppend	Append value to the existing one (string concat)

Constructor & Destructor Documentation

◆ Dictionary() [1/5]

av::Dictionary::Dictionary ( )

Default ctor do nothig, null dictionary creates.

◆ Dictionary() [2/5]

av::Dictionary::Dictionary	(	AVDictionary *	dict,
		bool	takeOwning = `true`
	)

explicit

Assign ctor Wrap around raw dictionary.

Useful to iterate with low-level FFmpeg API

Parameters

dict	dictionary to hold
takeOwning	ownershipping flag. If false, Dictionary only wraps access to the AVDictionary and do not free resources on destroy.

◆ ~Dictionary()

av::Dictionary::~Dictionary ( )

Dtor If Dictionary takes ownershipping on AVDictionary, it free allocated resources.

◆ Dictionary() [3/5]

av::Dictionary::Dictionary ( const Dictionary & other )

Copy ctor Make deep copy of dictionary.

Takes ownershipping on newly created dict.

Parameters

other

◆ Dictionary() [4/5]

av::Dictionary::Dictionary ( Dictionary && other )

Move ctor Takes resources.

Other dictionary moves to uninited state. Ownershpping same to other.

Parameters

other

◆ Dictionary() [5/5]

av::Dictionary::Dictionary	(	std::initializer_list< std::pair< const char , const char >>	list,
		int	flags = `0`
	)

Initializer ctor Allows create dictionaries in array manier:

Dictionary dict = {
  {"key1", "value1"},
  {"key2", "value2"},
};

New dictionary owning resources.

Parameters

list	init list
flags	see Flags

Member Function Documentation

◆ assign()

void av::Dictionary::assign	(	AVDictionary *	dict,
		bool	takeOwning = `true`
	)

noexcept

assign - assign new resouces Old dictionary destroyes (if owning).

If dict same to the olready holding one, but takeOwning is true and isOwning() false - takes owning. Otherwise do nothing.

Parameters

dict	dictionary to hold
takeOwning	owning flag

◆ begin() [1/2]

Dictionary::ConstIterator av::Dictionary::begin ( )

◆ begin() [2/2]

ConstIterator av::Dictionary::begin ( ) const

◆ cbegin()

Dictionary::ConstIterator av::Dictionary::cbegin ( ) const

◆ cend()

Dictionary::ConstIterator av::Dictionary::cend ( ) const

◆ copyFrom()

void av::Dictionary::copyFrom	(	const Dictionary &	other,
		int	flags = `0`
	)

noexcept

copyFrom - copy data from other dictionary.

If dictionary already exists, new fields will be addred. Entries with same keys will be overrided according to flags.

Parameters

other	dict to copy from
flags	see Flags

◆ count()

size_t av::Dictionary::count ( ) const

noexcept

◆ end() [1/2]

Dictionary::ConstIterator av::Dictionary::end ( )

◆ end() [2/2]

ConstIterator av::Dictionary::end ( ) const

◆ get() [1/2]

const char * av::Dictionary::get	(	const char *	key,
		int	flags = `0`
	)		const

noexcept

◆ get() [2/2]

const char * av::Dictionary::get	(	const std::string &	key,
		int	flags = `0`
	)		const

noexcept

◆ isOwning()

bool av::Dictionary::isOwning ( ) const

noexcept

isOwning - checks resources owning status

Returns: true if object owning resources

◆ operator=() [1/3]

Dictionary & av::Dictionary::operator= ( const Dictionary & rhs )

Copy assign operator Make deep copy of dictionary.

Takes ownershipping on newly created dict. Old dict destroyed (resouces freed if there is ownershipping)

Parameters

rhs

Returns

◆ operator=() [2/3]

Dictionary & av::Dictionary::operator= ( Dictionary && rhs )

Move assign operator Takes resources.

Rhs dictionary moves to uninited state. Ownershpping same to rhs. Old dict destroyed (resouces freed if there is ownershipping)

Parameters

rhs

Returns

◆ operator=() [3/3]

Dictionary & av::Dictionary::operator= ( std::initializer_list< std::pair< const char *, const char * >> list )

Initializer assign operator Allows assign dictionaries in array manier:

Dictionary dict;
...
dict = {
  {"key1", "value1"},
  {"key2", "value2"},
};

New dictionary owning resources. Old dictionary destroes (resource freed if owning)

Parameters

list	init list
flags	see Flags

◆ operator[]() [1/4]

const char * av::Dictionary::operator[] ( const char * key ) const

◆ operator[]() [2/4]

Dictionary::Entry av::Dictionary::operator[] ( const char * key )

noexcept

◆ operator[]() [3/4]

Dictionary::Entry av::Dictionary::operator[] ( size_t index )

◆ operator[]() [4/4]

const char * av::Dictionary::operator[] ( size_t index ) const

◆ parseString()

template<typename Str , typename Sep1 , typename Sep2 >

void av::Dictionary::parseString	(	const Str &	str,
		const Sep1 &	keyValSep,
		const Sep2 &	pairsSep,
		int	flags = `0`,
		OptionalErrorCode	ec = `throws()`
	)

inline

parseString - process string with options and fill dictionary String examples:

foo=bar;foo2=bar2

foo:bar&foo2:bar2

Parameters

	str	string to process
	keyValSep	null-terminated string with chars that interprets as key and value separators '=' and ':' in most cases.
	pairsSep	null-terminates string with chars that interprets as pairs (key and value) separators. ';' and ',' in most cases.
	flags	See Flags. All flags that omit strdups ignores.
[in,out]	ec	this represents the error status on exit, if this is pre-initialized to av::throws the function will throw on error instead

Returns: 0 on success, <0 on fail

◆ rawPtr()

AVDictionary ** av::Dictionary::rawPtr ( )

noexcept

◆ release()

AVDictionary * av::Dictionary::release ( )

release - drops ownershipping

Returns

◆ set()

template<typename Key , typename Value = Key>

auto av::Dictionary::set	(	const Key &	key,
		const Value &	value,
		OptionalErrorCode	ec = `throws()`,
		int	flags = `0`
	)		-> typename std::enable_if < (std::is_same<Key, std::string>::value \|\| std::is_same<typename std::remove_cv<typename std::decay<Key>::type>::type, char>::value) && (std::is_same<Value, std::string>::value \|\| std::is_same<typename std::remove_cv<typename std::decay<Value>::type>::type, char>::value \|\| std::is_integral<Value>::value) ,void >::type

inline

set - set new value for key or add new dictionary item (or create dictionary) If dictionary empty (null), it takes ownershipping too.

Parameters

[in]	key	key to change (can be std::string or char*)
[in]	value	key value (can be std::string, char* or integer)
[in,out]	ec	this represents the error status on exit, if this is pre-initialized to av::throws the function will throw on error instead
[in]	flags	see Flags

◆ size()

size_t av::Dictionary::size ( ) const

noexcept

◆ swap()

void av::Dictionary::swap ( Dictionary & other )

noexcept

swap - swaps resouces between objects

Parameters

other

◆ toRawStringPtr()

Dictionary::AvStringPtr av::Dictionary::toRawStringPtr	(	const char	keyValSep,
		const char	pairsSep,
		OptionalErrorCode	ec = `throws()`
	)		const

toRawStringPtr - converts dictionary to the raw string (char*) and protect it with smart pointer (std::unique_ptr).

This method omit data copy and returns raw pointer that allocated by av_dict_get_string(). For more safety this block wrapped with no-overhead smart pointer (std::unique_ptr).

See also: toString()

Parameters

[in]	keyValSep	char to separate key and value
[in]	pairsSep	chat to separate key-value pairs.
[in,out]	ec	this represents the error status on exit, if this is pre-initialized to av::throws the function will throw on error instead

Returns: valid string, null on error (check ec)

◆ toString()

string av::Dictionary::toString	(	const char	keyValSep,
		const char	pairsSep,
		OptionalErrorCode	ec = `throws()`
	)		const

toString - converts dictionary to the string representation (serialize)

This line can be processed via parseString() later.

FFmpeg internaly allocated buffer copies to the string and freed.

Parameters

[in]	keyValSep	char to separate key and value
[in]	pairsSep	chat to separate key-value pairs.
[in,out]	ec	this represents the error status on exit, if this is pre-initialized to av::throws the function will throw on error instead

Returns: valid string, null-string (std::string()) on error

Note: \0 and same separator chars unapplicable.

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

src/dictionary.h
src/dictionary.cpp

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ConstIterator

◆ Iterator

Member Enumeration Documentation

◆ Flags

Constructor & Destructor Documentation

◆ Dictionary() [1/5]

◆ Dictionary() [2/5]

◆ ~Dictionary()

◆ Dictionary() [3/5]

◆ Dictionary() [4/5]

◆ Dictionary() [5/5]

Member Function Documentation

◆ assign()

◆ begin() [1/2]

◆ begin() [2/2]

◆ cbegin()

◆ cend()

◆ copyFrom()

◆ count()

◆ end() [1/2]

◆ end() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ isOwning()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator[]() [1/4]

◆ operator[]() [2/4]

◆ operator[]() [3/4]

◆ operator[]() [4/4]

◆ parseString()

◆ rawPtr()

◆ release()

◆ set()

◆ size()

◆ swap()

◆ toRawStringPtr()

◆ toString()