.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2011
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, no Front-Cover Texts,
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "mchar_define_charset" 3m17n "12 Jan 2011" "Version 1.6.2" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
mchar_define_charset \- Define a charset. 


.SH SYNOPSIS
\fBMSymbol\fP
\fBmchar_define_charset\fP (const char *
\fIname\fP, \fBMPlist\fP *
\fIplist\fP)


.SH DESCRIPTION
Define a charset. The
.ft B
mchar_define_charset()
.ft R
function defines a new charset and makes it accessible via a symbol whose name is
.ft B
name\fP.
.ft R
.ft B
plist
.ft R
specifies parameters of the charset as below:
.PP
.PD 0
.IP "\(bu" 2
Key is
.ft B
Mmethod\fP,
.ft R
value is a symbol.
.PP
The value specifies the method for decoding/encoding code\-points in the charset. It must be
.ft B
Moffset\fP,
.ft R
.ft B
Mmap
.ft R
(default),
.ft B
Munify\fP,
.ft R
.ft B
Msubset\fP,
.ft R
or
.ft B
Msuperset\fP.
.ft R
.PP

.IP "\(bu" 2
Key is
.ft B
Mdimension\fP,
.ft R
value is an integer
.PP
The value specifies the dimension of code\-points of the charset. It must be 1 (default), 2, 3, or 4.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmin_range\fP,
.ft R
value is an unsigned integer
.PP
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.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmax_range\fP,
.ft R
value is an unsigned integer
.PP
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.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmin_code\fP,
.ft R
value is an unsigned integer
.PP
The value specifies the minimum code\-point of the charset. The default value is the minimum range.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmax_code\fP,
.ft R
value is an unsigned integer
.PP
The value specifies the maximum code\-point of the charset. The default value is the maximum range.
.PP

.IP "\(bu" 2
Key is
.ft B
Mascii_compatible\fP,
.ft R
value is a symbol
.PP
The value specifies whether the charset is ASCII compatible or not. If the value is
.ft B
Mnil
.ft R
(default), it is not ASCII compatible, else compatible.
.PP

.IP "\(bu" 2
Key is
.ft B
Mfinal_byte\fP,
.ft R
value is an integer
.PP
The value specifies the
.ft I
final
.ft R
.ft I
byte
.ft R
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.
.PP

.IP "\(bu" 2
Key is
.ft B
Mrevision\fP,
.ft R
value is an integer
.PP
The value specifies the
.ft I
revision
.ft R
.ft I
number
.ft R
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.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmin_char\fP,
.ft R
value is an integer
.PP
The value specifies the minimum character code of the charset. The default value is 0.
.PP

.IP "\(bu" 2
Key is
.ft B
Mmapfile\fP,
.ft R
value is an M\-text
.PP
If the method is
.ft B
Mmap
.ft R
or
.ft B
Munify\fP,
.ft R
a data that contains mapping information is added to the m17n database by calling the function
.ft B
mdatabase_define()
.ft R
with the value as an argument
.ft B
extra_info\fP,
.ft R
i.e. the value is used as a file name of the data.
.PP
Otherwise, this parameter is ignored.
.PP

.IP "\(bu" 2
Key is
.ft B
Mparents\fP,
.ft R
value is a plist
.PP
If the method is
.ft B
Msubset\fP,
.ft R
the value must is a plist of length 1, and the value of the plist must be a symbol representing a parent charset.
.PP
If the method is
.ft B
Msuperset\fP,
.ft R
the value must be a plist of length less than 9, and the values of the plist must be symbols representing subset charsets.
.PP
Otherwise, this parameter is ignored.
.PP

.IP "\(bu" 2
Key is
.ft B
Mdefine_coding\fP,
.ft R
value is a symbol
.PP
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
.ft B
Mcharset\fP.
.ft R
A coding system is defined if the value is not
.ft B
Mnil\fP.
.ft R
.PP
Otherwise, this parameter is ignored.
.PP

.PP
.PP
.SH RETURN VALUE
.PP
.RS 4
If the operation was successful,
.ft B
mchar_define_charset()
.ft R
returns a symbol whose name is
.ft B
name\fP.
.ft R
Otherwise it returns
.ft B
Mnil
.ft R
and assigns an error code to the external variable
.ft B
merror_code\fP.
.ft R
.RE
.PP
.SH ERRORS
.PP
.RS 4
\fCMERROR_CHARSET
.ft R
.RE
.PP

.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2011 National Institute of Advanced Industrial Science and Technology (AIST)
.br
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License 
<http://www.gnu.org/licenses/fdl.html>.