Symbol
CORE API

Symbol objects and API for them. More...

Collaboration diagram for Symbol:

## Functions

MSymbol | msymbol (const char *name)
| Get a symbol. More...
MSymbol | msymbol_as_managing_key (const char *name)
| Create a managing key. More...
int | msymbol_is_managing_key (MSymbol symbol)
| Check if a symbol is a managing key. More...
MSymbol | msymbol_exist (const char *name)
char * | msymbol_name (MSymbol symbol)
int | msymbol_put (MSymbol symbol, MSymbol key, void *val)
| Set the value of a symbol property. More...
void * | msymbol_get (MSymbol symbol, MSymbol key)
| Get the value of a symbol property. More...
int | msymbol_put_func (MSymbol symbol, MSymbol key, M17NFunc func)
| Set the value (function pointer) of a symbol property. More...
M17NFunc | msymbol_get_func (MSymbol symbol, MSymbol key)
| Get the value (function pointer) of a symbol property. More...

## Variables

MSymbol | Mnil
| Symbol whose name is "nil". More...
MSymbol | Mt
| Symbol whose name is "t". More...
MSymbol | Mstring
| Symbol whose name is "string". More...
MSymbol | Msymbol
| Symbol whose name is "symbol". More...

## Detailed Description

Symbol objects and API for them.

The m17n library uses objects called symbols as unambiguous identifiers. Symbols are similar to atoms in the X library, but a symbol can have zero or more symbol properties. A symbol property consists of a key and a value, where key is also a symbol and value is anything that can be cast to `(void *)`.
"The symbol property that belongs to the symbol S and whose key is K" may be shortened to "K property of S".

Symbols are used mainly in the following three ways.

- As keys of symbol properties and other properties.

- To represent various objects, e.g. charsets, coding systems, fontsets.

- As arguments of the m17n library functions to control their behavior.

There is a special kind of symbol, a managing key. The value of a property whose key is a managing key must be a managed object. See Managed Object for the detail.

## Function Documentation

## msymbol()

MSymbol msymbol | ( | const char * | name | ) |

Get a symbol.

The msymbol() function returns the canonical symbol whose name is name. If there is none, one is created. The created one is not a managing key.

Symbols whose name starts by two spaces are reserved by the m17n library, and are used by the library only internally.

Return value:
  This function returns the found or created symbol.

Errors:
  This function never fails.

See Also:
  msymbol_as_managing_key(), msymbol_name(), msymbol_exist()

## msymbol_as_managing_key()

MSymbol msymbol_as_managing_key | ( | const char * | name | ) |

Create a managing key.

The msymbol_as_managing_key() function returns a newly created managing key whose name is name. It there already exists a symbol of name name, it returns Mnil.

Symbols whose name starts by two spaces are reserved by the m17n library, and are used by the library only internally.

Return value:
  If the operation was successful, this function returns the created symbol. Otherwise, it returns Mnil.

Errors:
  MERROR_SYMBOL

See Also:
  msymbol(), msymbol_exist()

## msymbol_is_managing_key()

int msymbol_is_managing_key | ( | MSymbol | symbol | ) |

Check if a symbol is a managing key.

The msymbol_is_managing_key() function checks if the symbol symbol is a managing key or not.

Return value:
  Return 1 if the symbol is a managing key. Otherwise, return 0.

## msymbol_exist()

MSymbol msymbol_exist | ( | const char * | name | ) |

    @brief Search for a symbol that has a specified name.

    The msymbol_exist() function searches for the symbol whose name
    is @b name.

    @par Return value:
    If such a symbol exists, msymbol_exist() returns that symbol.
    Otherwise it returns the predefined symbol #Mnil.

    @par Errors:
    This function never fails.

See Also:
  msymbol_name(), msymbol()

## msymbol_name()

char* msymbol_name | ( | MSymbol | symbol | ) |

    @brief Get symbol name.

    The msymbol_name() function returns a pointer to a string
    containing the name of @b symbol.

    @par Errors:
    This function never fails.

See Also:
  msymbol(), msymbol_exist()

## msymbol_put()

int msymbol_put | ( | MSymbol | symbol,
|  | MSymbol | key,
|  | void * | val
| ) |  |

Set the value of a symbol property.

The msymbol_put() function assigns val to the value of the symbol property that belongs to symbol and whose key is key. If the symbol property already has a value, val overwrites the old one. Both symbol and key must not be Mnil.

If key is a managing key, val must be a managed object. In this case, the reference count of the old value, if not `NULL`, is decremented by one, and that of val is incremented by one.

Return value:
  If the operation was successful, msymbol_put() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_SYMBOL`

See Also:
  msymbol_get()

## msymbol_get()

void* msymbol_get | ( | MSymbol | symbol,
|  | MSymbol | key
| ) |  |

Get the value of a symbol property.

The msymbol_get() function searches for the value of the symbol property that belongs to symbol and whose key is key. If symbol has such a symbol property, its value is returned. Otherwise `NULL` is returned.

Return value:
  If an error is detected, msymbol_get() returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_SYMBOL`

See Also:
  msymbol_put()

## msymbol_put_func()

int msymbol_put_func | ( | MSymbol | symbol,
|  | MSymbol | key,
|  | M17NFunc | func
| ) |  |

Set the value (function pointer) of a symbol property.

The msymbol_put_func() function is similar to msymbol_put() but for setting function pointer func as the property value of symbol for key key.

See Also:
  msymbol_put(), M17N_FUNC()

## msymbol_get_func()

M17NFunc msymbol_get_func | ( | MSymbol | symbol,
|  | MSymbol | key
| ) |  |

Get the value (function pointer) of a symbol property.

The msymbol_get_func() function is similar to msymbol_get() but for getting a function pointer form the property of symbol symbol.

See Also:
  msymbol_get()

## Variable Documentation

## Mnil

MSymbol Mnil

Symbol whose name is "nil".

The symbol Mnil has the name `"nil"` and, in general, represents false or no. When coerced to "int", its value is zero. Mnil can't have any symbol property.

## Mt

MSymbol Mt

Symbol whose name is "t".

The symbol Mt has the name `"t"` and, in general, represents true or yes.

## Mstring

MSymbol Mstring

Symbol whose name is "string".

The symbol Mstring has the name `"string"` and is used as an argument of the functions mchar_define_property(), etc.

## Msymbol

MSymbol Msymbol

Symbol whose name is "symbol".

The symbol Msymbol has the name `"symbol"` and is used as an argument of the functions mchar_define_property(), etc.