---

         

---

Charset
[SHELL API]

Charset objects and API for them. More...

Variables: Symbols representing a charset.
Each of the following symbols represents a predefined charset.
MSymbol	Mcharset_ascii
	Symbol representing the charset ASCII.
MSymbol	Mcharset_iso_8859_1
	Symbol representing the charset ISO/IEC 8859/1.
MSymbol	Mcharset_unicode
	Symbol representing the charset Unicode.
MSymbol	Mcharset_m17n
	Symbol representing the largest charset.
MSymbol	Mcharset_binary
	Symbol representing the charset for ill-decoded characters.
Variables: Parameter keys for mchar_define_charset().
These are the predefined symbols to use as parameter keys for the function mchar_define_charset() (which see).
MSymbol	Mmethod
MSymbol	Mdimension
MSymbol	Mmin_range
MSymbol	Mmax_range
MSymbol	Mmin_code
MSymbol	Mmax_code
MSymbol	Mascii_compatible
MSymbol	Mfinal_byte
MSymbol	Mrevision
MSymbol	Mmin_char
MSymbol	Mmapfile
MSymbol	Mparents
MSymbol	Msubset_offset
MSymbol	Mdefine_coding
MSymbol	Maliases
Variables: Symbols representing charset methods.
These are the predefined symbols that can be a value of the Mmethod parameter of a charset used in an argument to the mchar_define_charset() function. A method specifies how code-points and character codes are converted. See the documentation of the mchar_define_charset() function for the details.
MSymbol	Moffset
	Symbol for the offset type method of charset.
MSymbol	Mmap
	Symbol for the map type method of charset.
MSymbol	Munify
	Symbol for the unify type method of charset.
MSymbol	Msubset
	Symbol for the subset type method of charset.
MSymbol	Msuperset
	Symbol for the superset type method of charset.
Defines
#define	MCHAR_INVALID_CODE
	Invalid code-point.
Functions
MSymbol	mchar_define_charset (const char *name, MPlist *plist)
	Define a charset.
MSymbol	mchar_resolve_charset (MSymbol symbol)
	Resolve charset name.
int	mchar_list_charset (MSymbol **symbols)
	List symbols representing charsets.
int	mchar_decode (MSymbol charset_name, unsigned code)
	Decode a code-point.
unsigned	mchar_encode (MSymbol charset_name, int c)
	Encode a character code.
int	mchar_map_charset (MSymbol charset_name, void(*func)(int from, int to, void *arg), void *func_arg)
	Call a function for all the characters in a specified charset.
Variables
MSymbol	Mcharset
	The symbol Mcharset.

---

Detailed Description

The m17n library uses charset objects to represent a coded character sets (CCS). The m17n library supports many predefined coded character sets. Moreover, application programs can add other charsets. A character can belong to multiple charsets.

The m17n library distinguishes the following three concepts:

• A code-point is a number assigned by the CCS to each character. Code-points may or may not be continuous. The type unsigned is used to represent a code-point. An invalid code-point is represented by the macro MCHAR_INVALID_CODE.

• A character index is the canonical index of a character in a CCS. The character that has the character index N occupies the Nth position when all the characters in the current CCS are sorted by their code-points. Character indices in a CCS are continuous and start with 0.

• A character code is the internal representation in the m17n library of a character. A character code is a signed integer of 21 bits or longer.

Each charset object defines how characters are converted between code-points and character codes. To encode means converting code-points to character codes and to decode means converting character codes to code-points.

---

Define Documentation

#define MCHAR_INVALID_CODE

The macro MCHAR_INVALID_CODE gives the invalid code-point.

---

Function Documentation

MSymbol mchar_define_charset	(	const char *	name,
		MPlist *	plist
	)

The mchar_define_charset() function defines a new charset and makes it accessible via a symbol whose name is name. plist specifies parameters of the charset as below:

• Key is Mmethod, value is a symbol.

  The value specifies the method for decoding/encoding code-points in the charset. It must be Moffset, Mmap (default), Munify, Msubset, or Msuperset.

• Key is Mdimension, value is an integer

  The value specifies the dimension of code-points of the charset. It must be 1 (default), 2, 3, or 4.

• Key is Mmin_range, value is an unsigned integer

  The value specifies the minimum range of a code-point, which means that the Nth byte of the value is the minimum Nth byte of code-points of the charset. The default value is 0.

• Key is Mmax_range, value is an unsigned integer

  The value specifies the maximum range of a code-point, which means that the Nth byte of the value is the maximum Nth byte of code-points of the charset. The default value is 0xFF, 0xFFFF, 0xFFFFFF, or 0xFFFFFFFF if the dimension is 1, 2, 3, or 4 respectively.

• Key is Mmin_code, value is an unsigned integer

  The value specifies the minimum code-point of the charset. The default value is the minimum range.

• Key is Mmax_code, value is an unsigned integer

  The value specifies the maximum code-point of the charset. The default value is the maximum range.

• Key is Mascii_compatible, value is a symbol

  The value specifies whether the charset is ASCII compatible or not. If the value is Mnil (default), it is not ASCII compatible, else compatible.

• Key is Mfinal_byte, value is an integer

  The value specifies the final byte of the charset registered in The International Registry. It must be 0 (default) or 32..127. The value 0 means that the charset is not in the registry.

• Key is Mrevision, value is an integer

  The value specifies the revision number of the charset registered in The International Registry. It must be 0..127. If the charset is not in The International Registry, the value is ignored. The value 0 means that the charset has no revision number.

• Key is Mmin_char, value is an integer

  The value specifies the minimum character code of the charset. The default value is 0.

• Key is Mmapfile, value is an M-text

  If the method is Mmap or Munify, a data that contains mapping information is added to the m17n database by calling the function mdatabase_define() with the value as an argument extra_info, i.e. the value is used as a file name of the data.

  Otherwise, this parameter is ignored.

• Key is Mparents, value is a plist

  If the method is Msubset, the value must is a plist of length 1, and the value of the plist must be a symbol representing a parent charset.

  If the method is Msuperset, the value must be a plist of length less than 9, and the values of the plist must be symbols representing subset charsets.

  Otherwise, this parameter is ignored.

• Key is Mdefine_coding, value is a symbol

  If the dimension of the charset is 1, the value specifies whether or not to define a coding system of the same name whose type is Mcharset. A coding system is defined if the value is not Mnil.

  Otherwise, this parameter is ignored.

Return value:

If the operation was successful, mchar_define_charset() returns a symbol whose name is name. Otherwise it returns Mnil and assigns an error code to the external variable merror_code.

Errors:

MERROR_CHARSET

MSymbol mchar_resolve_charset

(

MSymbol

symbol

)

The mchar_resolve_charset() function returns symbol if it represents a charset. Otherwise, canonicalize symbol as to a charset name, and if the canonicalized name represents a charset, return it. Otherwise, return Mnil.

int mchar_list_charset

(

MSymbol **

symbols

)

The mchar_list_charsets() function makes an array of symbols representing a charset, stores the pointer to the array in a place pointed to by symbols, and returns the length of the array.

int mchar_decode	(	MSymbol	charset_name,
		unsigned	code
	)

The mchar_decode() function decodes code-point code in the charset represented by the symbol charset_name to get a character code.

Return value:

If decoding was successful, mchar_decode() returns the decoded character code. Otherwise it returns -1.

See Also:

mchar_encode()

unsigned mchar_encode	(	MSymbol	charset_name,
		int	c
	)

The mchar_encode() function encodes character code c to get a code-point in the charset represented by the symbol charset_name.

Return value:

If encoding was successful, mchar_encode() returns the encoded code-point. Otherwise it returns MCHAR_INVALID_CODE.

See Also:

mchar_decode()

int mchar_map_charset	(	MSymbol	charset_name,
		void(*)(int from, int to, void *arg)	func,
		void *	func_arg
	)

The mcharset_map_chars() function calls func for all the characters in the charset named charset_name. A call is done for a chunk of consecutive characters rather than character by character.

func receives three arguments: from, to, and arg. from and to specify the range of character codes in charset. arg is the same as func_arg.

Return value:

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

Errors:

MERROR_CHARSET

---

Variable Documentation

MSymbol Mcharset

Any decoded M-text has a text property whose key is the predefined symbol Mcharset. The name of Mcharset is "charset".

MSymbol Mcharset_ascii

The symbol Mcharset_ascii has name "ascii" and represents the charset ISO 646, USA Version X3.4-1968 (ISO-IR-6).

MSymbol Mcharset_iso_8859_1

The symbol Mcharset_iso_8859_1 has name "iso-8859-1" and represents the charset ISO/IEC 8859-1:1998.

MSymbol Mcharset_unicode

The symbol Mcharset_unicode has name "unicode" and represents the charset Unicode.

MSymbol Mcharset_m17n

The symbol Mcharset_m17n has name "m17n" and represents the charset that contains all characters supported by the m17n library.

MSymbol Mcharset_binary

The symbol Mcharset_binary has name "binary" and represents the fake charset which the decoding functions put to an M-text as a text property when they encounter an invalid byte (sequence).

See Code Conversion for more details.

MSymbol Mmethod

Parameter key for mchar_define_charset() (which see).

MSymbol Mdimension

Parameter key for mchar_define_charset() (which see).

MSymbol Mmin_range

Parameter key for mchar_define_charset() (which see).

MSymbol Mmax_range

Parameter key for mchar_define_charset() (which see).

MSymbol Mmin_code

Parameter key for mchar_define_charset() (which see).

MSymbol Mmax_code

Parameter key for mchar_define_charset() (which see).

MSymbol Mascii_compatible

Parameter key for mchar_define_charset() (which see).

MSymbol Mfinal_byte

Parameter key for mchar_define_charset() (which see).

MSymbol Mrevision

Parameter key for mchar_define_charset() (which see).

MSymbol Mmin_char

Parameter key for mchar_define_charset() (which see).

MSymbol Mmapfile

Parameter key for mchar_define_charset() (which see).

MSymbol Mparents

Parameter key for mchar_define_charset() (which see).

MSymbol Msubset_offset

Parameter key for mchar_define_charset() (which see).

MSymbol Mdefine_coding

Parameter key for mchar_define_charset() (which see).

MSymbol Maliases

Parameter key for mchar_define_charset() (which see).

MSymbol Moffset

The symbol Moffset has the name "offset" and, when used as a value of Mmethod parameter of a charset, it means that the conversion of code-points and character codes of the charset is done by this calculation:

CHARACTER-CODE = CODE-POINT - MIN-CODE + MIN-CHAR

where, MIN-CODE is a value of Mmin_code parameter of the charset, and MIN-CHAR is a value of Mmin_char parameter.

MSymbol Mmap

The symbol Mmap has the name "map" and, when used as a value of Mmethod parameter of a charset, it means that the conversion of code-points and character codes of the charset is done by map looking up. The map must be given by Mmapfile parameter.

MSymbol Munify

The symbol Munify has the name "unify" and, when used as a value of Mmethod parameter of a charset, it means that the conversion of code-points and character codes of the charset is done by map looking up and offsetting. The map must be given by Mmapfile parameter. For this kind of charset, a unique continuous character code space for all characters is assigned.

If the map has an entry for a code-point, the conversion is done by looking up the map. Otherwise, the conversion is done by this calculation:

CHARACTER-CODE = CODE-POINT - MIN-CODE + LOWEST-CHAR-CODE

where, MIN-CODE is a value of Mmin_code parameter of the charset, and LOWEST-CHAR-CODE is the lowest character code of the assigned code space.

MSymbol Msubset

The symbol Msubset has the name "subset" and, when used as a value of Mmethod parameter of a charset, it means that the charset is a subset of a parent charset. The parent charset must be given by Mparents parameter. The conversion of code-points and character codes of the charset is done conceptually by this calculation:

CHARACTER-CODE = PARENT-CODE (CODE-POINT) + SUBSET-OFFSET

where, PARENT-CODE is a pseudo function that returns a character code of CODE-POINT in the parent charset, and SUBSET-OFFSET is a value given by Msubset_offset parameter.

MSymbol Msuperset

The symbol Msuperset has the name "superset" and, when used as a value of Mmethod parameter of a charset, it means that the charset is a superset of parent charsets. The parent charsets must be given by Mparents parameter.

---

Top of this page

         

---