---

         

---

Chartable
[CORE API]

Chartable objects and API for them. More...

Typedefs
typedef MCharTable	MCharTable
	Type of chartables.
Functions
MCharTable *	mchartable (MSymbol key, void *default_value)
	Create a new chartable.
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

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

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
	)

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.

void* mchartable_lookup	(	MCharTable *	table,
		int	c
	)

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
	)

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
	)

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
	)

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
	)

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

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

---

Top of this page

         

---