The m17n Library: Symbol

# Symbol
[CORE API]

Symbol objects and API for them. More...

## Typedefs
typedef struct MSymbolStruct * | MSymbol
| Type of symbols.
## Functions
MSymbol | msymbol (const char *name)
| Get a symbol.
MSymbol | msymbol_as_managing_key (const char *name)
| Create a managing key.
int | msymbol_is_managing_key (MSymbol symbol)
| Check if a symbol is a managing key.
MSymbol | msymbol_exist (const char *name)
| Search for a symbol that has a specified name.
char * | msymbol_name (MSymbol symbol)
| Get symbol name.
int | msymbol_put (MSymbol symbol, MSymbol key, void *val)
| Set the value of a symbol property.
void * | msymbol_get (MSymbol symbol, MSymbol key)
| Get the value of a symbol property.
int | msymbol_put_func (MSymbol symbol, MSymbol key, M17NFunc func)
| Set the value (function pointer) of a symbol property.
M17NFunc | msymbol_get_func (MSymbol symbol, MSymbol key)
| Get the value (function pointer) of a symbol property.
## Variables
MSymbol | Mnil
| Symbol whose name is "nil".
MSymbol | Mt
| Symbol whose name is "t".
MSymbol | Mstring
| Symbol whose name is "string".
MSymbol | Msymbol
| Symbol whose name is "symbol".

## 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.

## Typedef Documentation

typedef struct MSymbolStruct* MSymbol

Type of symbols.

The type MSymbol is for a symbol object. Its internal structure is concealed from application programs.

## Function Documentation

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 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()

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 msymbol_exist | ( | const char * | name | ) |

Search for a symbol that has a specified name.

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

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

Errors:
  This function never fails.

See Also:
  msymbol_name(), msymbol()

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

Get symbol name.

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

Errors:
  This function never fails.

See Also:
  msymbol(), msymbol_exist()

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()

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()

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()

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

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.

MSymbol Mt

Symbol whose name is "t".

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

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

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.