MySQL 9.1.0
Source Code Documentation
mysql::collation_internals::Collations Class Referencefinal

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

#include <collations_internal.h>

Public Member Functions

 Collations (const Collations &)=delete
 
Collationsoperator= (const Collations &)=delete
 
 Collations (const char *charset_dir, MY_CHARSET_LOADER *loader=nullptr)
 Constructor. More...
 
 ~Collations ()
 
CHARSET_INFOfind_by_name (const mysql::collation::Name &name, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
 Finds collation by its name. More...
 
CHARSET_INFOfind_by_id (unsigned id, myf flags=0, MY_CHARSET_ERRMSG *errmsg=nullptr)
 Finds collation by its number. More...
 
CHARSET_INFOfind_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_INFOfind_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_INFOsafe_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_INFOfind_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_INFOunsafe_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_LOADERm_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
KeyName 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_dirOptional "/\0"-terminated path to the directory containing Index.xml
loaderOptional 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
csCollation 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
idCollation id (hardcoded in library sources or specified in Index.xml)
flagsOptional mysys-specific flags
[out]errmsgOptional 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
nameCollation name
flagsOptional mysys-specific flags
[out]errmsgOptional 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
nameCollation 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_nameCharacter set name
flagsOptional mysys-specific flags
[out]errmsgOptional 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_nameCharacter set name
flagsOptional mysys-specific flags
[out]errmsgOptional 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
nameCollation 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
nameCollation 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
nameCollation 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
fClosure 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
csPointer to collation object
flagsOptional mysys-specific flags
[out]errmsgOptional 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
csPointer to collation object
flagsOptional mysys-specific flags
[out]errmsgOptional 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: