The m17n Library: Chartable

# Chartable
[CORE API]

Chartable objects and API for them. More...

## Typedefs
typedef struct MCharTable | MCharTable
| Type of chartables.
## Functions
MCharTable * | mchartable (MSymbol key, void *default_value)
| Create a new chartable.
int | mchartable_min_char (MCharTable *table)
| Return the minimum character whose value is set in a chartabe.
int | mchartable_max_char (MCharTable *table)
| Return the maximum character whose value is set in a chartabe.
void * | mchartable_lookup (MCharTable *table, int c)
| Return the assigned value of a character in a chartable.
int | mchartable_set (MCharTable *table, int c, void *val)
| Assign a value to a character in a chartable.
int | mchartable_set_range (MCharTable *table, int from, int to, void *val)
| Assign a value to the characters in the specified range.
void | mchartable_range (MCharTable *table, int *from, int *to)
| Search for characters that have non-default value.
int | mchartable_map (MCharTable *table, void *ignore, void(*func)(int, int, void *, void *), void *func_arg)
| Call a function for characters in a chartable.
## Variables
MSymbol | Mchar_table
| Symbol whose name is "char-table".

## Detailed Description

Chartable objects and API for them.

The m17n library supports enormous number of characters. Thus, if attributes of each character are to be stored in a simple array, such an array would be impractically big. The attributes usually used, however, are often assigned only to a range of characters. Even when all characters have attributes, characters of consecutive character code tend to have the same attribute values.

The m17n library utilizes this tendency to store characters and their attribute values efficiently in an object called Chartable. Although a chartable object is not a simple array, application programs can handle a chartable as if it is an array. Attribute values of a character can be obtained by accessing a Chartable for the attribute with the character code of the specified character.

A chartable is a managed object.

## Typedef Documentation

typedef struct MCharTable MCharTable

Type of chartables.

The type MCharTable is for a chartable objects. Its internal structure is concealed from application programs.

## Function Documentation

MCharTable* mchartable | ( | MSymbol | key,
|  | void * | default_value |
| ) |  |  |

Create a new chartable.

The mchartable() function creates a new chartable object with symbol key and the default value default_value. If key is a managing key, the elements of the table (including the default value) are managed objects or NULL.

Return value:
  If the operation was successful, mchartable() returns a pointer to the created chartable. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

int mchartable_min_char | ( | MCharTable * | table | ) |

Return the minimum character whose value is set in a chartabe.

The mchartable_min_char() function return the minimum character whose value is set in chartable table. No character is set its value, the function returns -1.

int mchartable_max_char | ( | MCharTable * | table | ) |

Return the maximum character whose value is set in a chartabe.

The mchartable_max_char() function return the maximum character whose value is set in chartable table. No character is set its value, the function returns -1.

void* mchartable_lookup | ( | MCharTable * | table,
|  | int | c |
| ) |  |  |

Return the assigned value of a character in a chartable.

The mchartable_lookup() function returns the value assigned to character c in chartable table. If no value has been set for c explicitly, the default value of table is returned. If c is not a valid character, mchartable_lookup() returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_CHAR`

See Also:
  mchartable_set()

int mchartable_set | ( | MCharTable * | table,
|  | int | c,
|  | void * | val |
| ) |  |  |

Assign a value to a character in a chartable.

The mchartable_set() function sets the value of character c in chartable table to val.

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

Errors:
  `MERROR_CHAR`

See Also:
  mchartable_lookup(), mchartable_set_range()

int mchartable_set_range | ( | MCharTable * | table,
|  | int | from,
|  | int | to,
|  | void * | val |
| ) |  |  |

Assign a value to the characters in the specified range.

The mchartable_set_range() function assigns value val to the characters from from to to (both inclusive) in chartable table.

Return value:
  If the operation was successful, mchartable_set_range() returns 0. Otherwise it returns -1 and assigns an error code to the external variable merror_code. If from is greater than to, mchartable_set_range() returns immediately without an error.

Errors:
  `MERROR_CHAR`

See Also:
  mchartable_set()

void mchartable_range | ( | MCharTable * | table,
|  | int * | from,
|  | int * | to |
| ) |  |  |

Search for characters that have non-default value.

The mchartable_range() function searches chartable table for the first and the last character codes that do not have the default value of table, and set from and to to them, respectively. If all characters have the default value, both from and to are set to -1.

int mchartable_map | ( | MCharTable * | table,
|  | void * | ignore,
|  | void(*)(int, int, void *, void *) | func,
|  | void * | func_arg |
| ) |  |  |

Call a function for characters in a chartable.

The mchartable_map() function calls function func for characters in chartable table. No function call occurs for characters that have value ignore in table. Comparison of ignore and character value is done with the operator `==`. Be careful when you use string literals or pointers.

Instead of calling func for each character, mchartable_map() tries to optimize the number of function calls, i.e. it makes a single function call for a chunk of characters when those consecutive characters have the same value.

No matter how long the character chunk is, func is called with four arguments; from, to, val, and arg. from and to (both inclusive) defines the range of characters that have value val. arg is the same as func_arg.

Return value:
  This function always returns 0.

## Variable Documentation

MSymbol Mchar_table

Symbol whose name is "char-table".

The symbol `Mchar_table` has the name `"char-table"`.