Helper class: implementation of character set/collation library. More...

#include <collations_internal.h>

Public Member Functions
	Collations (const Collations &)=delete

Collations &	operator= (const Collations &)=delete

	Collations (const char charset_dir, MY_CHARSET_LOADER loader=nullptr)
	Constructor. More...

	~Collations ()

CHARSET_INFO *	find_by_name (const mysql::collation::Name &name, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
	Finds collation by its name. More...

CHARSET_INFO *	find_by_id (unsigned id, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
	Finds collation by its number. More...

CHARSET_INFO *	find_primary (const mysql::collation::Name &cs_name, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
	Finds primary collation by its character set name. More...

CHARSET_INFO *	find_default_binary (const mysql::collation::Name &cs_name, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
	Finds binary collation by its character set name. More...

unsigned	get_collation_id (const mysql::collation::Name &name) const
	Finds collation by its name and returns its id. More...

unsigned	get_primary_collation_id (const mysql::collation::Name &name) const
	Finds character set by its name and returns an id of its primary collation. More...

unsigned	get_default_binary_collation_id (const mysql::collation::Name &name) const
	Finds character set by its name and returns an id of its default binary collation. More...

CHARSET_INFO *	safe_init_when_necessary (CHARSET_INFO cs, myf flags=0, MY_CHARSET_ERRMSG errmsg=nullptr)
	If not done yet, force collation parsing/initialization under m_mutex lock. More...

CHARSET_INFO *	find_by_name_unsafe (const mysql::collation::Name &name)
	Like find_by_name but without initialization of return value. More...

bool	add_internal_collation (CHARSET_INFO *cs)
	For registering compile-time collations. More...

void	iterate (const std::function< void(const CHARSET_INFO *)> &f)
	Iterate over all collation objects known to the library. More...

Protected Types
template<typename Key >
using	Hash = std::unordered_map< Key, CHARSET_INFO * >
	Common parametric type to map character set/collation names or their ids to CHARSET_INFO object pointers. More...

Protected Member Functions
CHARSET_INFO *	unsafe_init (CHARSET_INFO cs, myf flags, MY_CHARSET_ERRMSG errmsg)
	Internals of safe_init_when_necessary() More...

Protected Attributes
const std::string	m_charset_dir
	Optional '/'-terminated path to the directory containing Index.xml. More...

Hash< unsigned >	m_all_by_id
	Maps collation ids to CHARSET_INFO object pointers. More...

Hash< std::string >	m_all_by_collation_name
	Maps normalized strings of all known character set names, collation names, and their aliases to CHARSET_INFO object pointers. More...

Hash< std::string >	m_primary_by_cs_name
	Maps normalized strings of character set names to CHARSET_INFO object pointers. More...

Hash< std::string >	m_binary_by_cs_name
	Maps normalized strings of character set names to CHARSET_INFO objects of preferred binary collations. More...

const bool	m_owns_loader
	False if m_loader references external MY_CHARSET_LOADER, otherwise true. More...

MY_CHARSET_LOADER *	m_loader
	Shared MY_CHARSET_LOADER implementation for use in collation parser and initializer. More...

Private Attributes
std::mutex	m_mutex
	Collation parser/initializer mutex. More...

Detailed Description

Helper class: implementation of character set/collation library.

See also: mysql::collation_internals::entry.

Member Typedef Documentation

◆ Hash

template<typename Key >

using mysql::collation_internals::Collations::Hash = std::unordered_map<Key, CHARSET_INFO *>

protected

Common parametric type to map character set/collation names or their ids to CHARSET_INFO object pointers.

Template Parameters

Key	Name or id type (std::string or unsigned respectively)

TODO(gleb): it would be good to use mysql::collation::Name instead of std::string for Key.

Constructor & Destructor Documentation

◆ Collations() [1/2]

mysql::collation_internals::Collations::Collations ( const Collations & )

delete

◆ Collations() [2/2]

mysql::collation_internals::Collations::Collations	(	const char *	charset_dir,
		MY_CHARSET_LOADER *	loader = `nullptr`
	)

explicit

Constructor.

Parameters

charset_dir	Optional "/\0"-terminated path to the directory containing Index.xml
loader	Optional user-specified hooks to the character set/collation parser/initializer.

◆ ~Collations()

mysql::collation_internals::Collations::~Collations ( )

Member Function Documentation

◆ add_internal_collation()

bool mysql::collation_internals::Collations::add_internal_collation ( CHARSET_INFO * cs )

For registering compile-time collations.

Parameters

cs	Collation object

Returns: false on success, otherwise true.

◆ find_by_id()

CHARSET_INFO * mysql::collation_internals::Collations::find_by_id	(	unsigned	id,
		myf	flags = `0`,
		MY_CHARSET_ERRMSG *	errmsg = `nullptr`
	)

Finds collation by its number.

Note: Forces collation parsing/initialization if not done yet.

Parameters

	id	Collation id (hardcoded in library sources or specified in Index.xml)
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: pointer to a collation object on success, nullptr if not found

◆ find_by_name()

CHARSET_INFO * mysql::collation_internals::Collations::find_by_name	(	const mysql::collation::Name &	name,
		myf	flags = `0`,
		MY_CHARSET_ERRMSG *	errmsg = `nullptr`
	)

Finds collation by its name.

Note: Forces collation parsing/initialization if not done yet.

Parameters

	name	Collation name
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: pointer to a collation object on success, nullptr if not found

◆ find_by_name_unsafe()

CHARSET_INFO * mysql::collation_internals::Collations::find_by_name_unsafe ( const mysql::collation::Name & name )

Like find_by_name but without initialization of return value.

Parameters

name	Collation name

Returns: Pointer to CHARSET_INFO object on success, nullptr if not found. The resulting value can point to a half-initialized object. Moreover, further initialization of that object or parsing of its collation XML can fail.

◆ find_default_binary()

CHARSET_INFO * mysql::collation_internals::Collations::find_default_binary	(	const mysql::collation::Name &	cs_name,
		myf	flags = `0`,
		MY_CHARSET_ERRMSG *	errmsg = `nullptr`
	)

Finds binary collation by its character set name.

Note: Forces collation parsing/initialization if not done yet.

Parameters

	cs_name	Character set name
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: pointer to a collation object on success, nullptr if not found

◆ find_primary()

CHARSET_INFO * mysql::collation_internals::Collations::find_primary	(	const mysql::collation::Name &	cs_name,
		myf	flags = `0`,
		MY_CHARSET_ERRMSG *	errmsg = `nullptr`
	)

Finds primary collation by its character set name.

Note: Forces collation parsing/initialization if not done yet.

Parameters

	cs_name	Character set name
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: pointer to a collation object on success, nullptr if not found

◆ get_collation_id()

unsigned mysql::collation_internals::Collations::get_collation_id ( const mysql::collation::Name & name ) const

Finds collation by its name and returns its id.

Parameters

name	Collation name

Returns: collation id

◆ get_default_binary_collation_id()

unsigned mysql::collation_internals::Collations::get_default_binary_collation_id ( const mysql::collation::Name & name ) const

Finds character set by its name and returns an id of its default binary collation.

Parameters

name	Collation name

Returns: default binary collation id

◆ get_primary_collation_id()

unsigned mysql::collation_internals::Collations::get_primary_collation_id ( const mysql::collation::Name & name ) const

Finds character set by its name and returns an id of its primary collation.

Parameters

name	Collation name

Returns: primary collation id

◆ iterate()

void mysql::collation_internals::Collations::iterate ( const std::function< void(const CHARSET_INFO *)> & f )

inline

Iterate over all collation objects known to the library.

Parameters

f	Closure to execute on each collation object known to the library

◆ operator=()

Collations & mysql::collation_internals::Collations::operator= ( const Collations & )

delete

◆ safe_init_when_necessary()

CHARSET_INFO * mysql::collation_internals::Collations::safe_init_when_necessary	(	CHARSET_INFO *	cs,
		myf	flags = `0`,
		MY_CHARSET_ERRMSG *	errmsg = `nullptr`
	)

If not done yet, force collation parsing/initialization under m_mutex lock.

Parameters

	cs	Pointer to collation object
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: cs on success, otherwise nullptr

◆ unsafe_init()

CHARSET_INFO * mysql::collation_internals::Collations::unsafe_init	(	CHARSET_INFO *	cs,
		myf	flags,
		MY_CHARSET_ERRMSG *	errmsg
	)

protected

Internals of safe_init_when_necessary()

This function is similar to safe_init_when_necessary, but, unlike safe_init_when_necessary(), it doesn't acquire locks.

Parameters

	cs	Pointer to collation object
	flags	Optional mysys-specific flags
[out]	errmsg	Optional buffer to return error message from collation parser/initializer

Returns: cs on success, otherwise nullptr

Member Data Documentation

◆ m_all_by_collation_name

Hash<std::string> mysql::collation_internals::Collations::m_all_by_collation_name

protected

Maps normalized strings of all known character set names, collation names, and their aliases to CHARSET_INFO object pointers.

Note: see old_conv and get_old_charset_by_name() for exclusions

See also: old_conv(), get_old_charset_by_name()

◆ m_all_by_id

Hash<unsigned> mysql::collation_internals::Collations::m_all_by_id

protected

Maps collation ids to CHARSET_INFO object pointers.

◆ m_binary_by_cs_name

Hash<std::string> mysql::collation_internals::Collations::m_binary_by_cs_name

protected

Maps normalized strings of character set names to CHARSET_INFO objects of preferred binary collations.

Note: utf8mb4 has two separate binary collations, so m_binary_by_cs_name contains a reference to utf8mb4_bin only.

◆ m_charset_dir

const std::string mysql::collation_internals::Collations::m_charset_dir

protected

Optional '/'-terminated path to the directory containing Index.xml.

◆ m_loader

MY_CHARSET_LOADER* mysql::collation_internals::Collations::m_loader

protected

Shared MY_CHARSET_LOADER implementation for use in collation parser and initializer.

By default references an instance of mysql::collation_internals::Loader.

◆ m_mutex

std::mutex mysql::collation_internals::Collations::m_mutex

private

Collation parser/initializer mutex.

The library parses collations and initializes CHARSET_INFO objects in depth on demand, so m_mutex is necessary to guarantee a safety of concurrent find_... function calls.

◆ m_owns_loader

const bool mysql::collation_internals::Collations::m_owns_loader

protected

False if m_loader references external MY_CHARSET_LOADER, otherwise true.

◆ m_primary_by_cs_name

Hash<std::string> mysql::collation_internals::Collations::m_primary_by_cs_name

protected

Maps normalized strings of character set names to CHARSET_INFO object pointers.

Note: In MySQL, CHARSET_INFO object of character set is also an object of its primary collation.

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

strings/collations_internal.h
strings/collations_internal.cc

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Hash

Constructor & Destructor Documentation

◆ Collations() [1/2]

◆ Collations() [2/2]

◆ ~Collations()

Member Function Documentation

◆ add_internal_collation()

◆ find_by_id()

◆ find_by_name()

◆ find_by_name_unsafe()

◆ find_default_binary()

◆ find_primary()

◆ get_collation_id()

◆ get_default_binary_collation_id()

◆ get_primary_collation_id()

◆ iterate()

◆ operator=()

◆ safe_init_when_necessary()

◆ unsafe_init()

Member Data Documentation

◆ m_all_by_collation_name

◆ m_all_by_id

◆ m_binary_by_cs_name

◆ m_charset_dir

◆ m_loader

◆ m_mutex

◆ m_owns_loader

◆ m_primary_by_cs_name