comparison src/charset.h @ 35478:340a9e4aeb29

comment fixes

35477:e6bffd5c5287

/*** GENERAL NOTE on CHARACTER SET (CHARSET) ***

  A character set ("charset" hereafter) is a meaningful collection
  (i.e. language, culture, functionality, etc) of characters.  Emacs
  handles multiple charsets at once.  Each charset corresponds to one
  of ISO charsets.  Emacs identifies a charset by a unique
  identification number, whereas ISO identifies a charset by a triplet
  of DIMENSION, CHARS and FINAL-CHAR.  So, hereafter, just saying
  "charset" means an identification number (integer value).

  The value range of charset is 0x00, 0x81..0xFE.  There are four
  kinds of charset depending on DIMENSION (1 or 2) and CHARS (94 or
  96).  For instance, a charset of DIMENSION2_CHARS94 contains 94x94
  characters.

  Within Emacs Lisp, a charset is treated as a symbol which has a
  property `charset'.  The property value is a vector containing
  various information about the charset.  For readability of C codes,
  we use the following convention for C variable names:
	charset_symbol: Emacs Lisp symbol of a charset
	charset_id: Emacs Lisp integer of an identification number of a charset
	charset: C integer of an identification number of a charset

  Each charset (except for ascii) is assigned a base leading-code
  (range 0x80..0x9E).  In addition, a charset of greater than 0xA0
  (whose base leading-code is 0x9A..0x9D) is assigned an extended
  leading-code (range 0xA0..0xFE).  In this case, each base
  leading-code specify the allowable range of extended leading-code as
  shown in the table below.  A leading-code is used to represent a
  character in Emacs' buffer and string.

  We call a charset which has extended leading-code as "private
  charset" because those are mainly for a charset which is not yet
  registered by ISO.  On the contrary, we call a charset which does
  not have extended leading-code as "official charset".

  ---------------------------------------------------------------------------
  charset	dimension	 base leading-code	extended leading-code
  ---------------------------------------------------------------------------
  0x00		official dim1    -- none --		-- none --

   multibyte buffer/string.  So this macro name is not appropriate.  */
#define CHAR_HEAD_P(ch) ((unsigned char) (ch) < 0xA0)

/*** GENERAL NOTE on CHARACTER REPRESENTATION ***

  At first, the term "character" or "char" is used for a multilingual
  character (of course, including ASCII character), not for a byte in
  computer memory.  We use the term "code" or "byte" for the latter
  case.

  A character is identified by charset and one or two POSITION-CODEs.
  POSITION-CODE is the position of the character in the charset.  A

  A character of DIMENSION2 charset has two POSITION-CODE:
  POSITION-CODE-1 and POSITION-CODE-2.  The code range of
  POSITION-CODE is 0x20..0x7F.

  Emacs has two kinds of representation of a character: multi-byte
  form (for buffer and string) and single-word form (for character
  object in Emacs Lisp).  The latter is called "character code" here
  after.  Both representations encode the information of charset and
  POSITION-CODE but in a different way (for instance, MSB of
  POSITION-CODE is set in multi-byte form).

  For details of multi-byte form, see the section "2. Emacs internal
  format handlers" of `coding.c'.

  Emacs uses 19 bits for a character code.  The bits are divided into
  3 fields: FIELD1(5bits):FIELD2(7bits):FIELD3(7bits).

  A character code of DIMENSION1 character uses FIELD2 to hold charset

#define SINGLE_BYTE_CHAR_P(c) ((unsigned) (c) < 0x100)

/* 1 if BYTE is an ASCII character in itself, in multibyte mode.  */
#define ASCII_BYTE_P(byte) ((byte) < 0x80)

/* A char-table containing information of each character set.

   Unlike ordinary char-tables, this doesn't contain any nested table.
   Only the top level elements are used.  Each element is a vector of
   the following information:
	CHARSET-ID, BYTES, DIMENSION, CHARS, WIDTH, DIRECTION,
	LEADING-CODE-BASE, LEADING-CODE-EXT,
	ISO-FINAL-CHAR, ISO-GRAPHIC-PLANE,
	REVERSE-CHARSET, SHORT-NAME, LONG-NAME,	DESCRIPTION,
	PLIST.

   CHARSET-ID (integer) is the identification number of the charset.

   BYTES (integer) is the length of multi-byte form of a character in
   the charset: one of 1, 2, 3, and 4.

   DIMENSION (integer) is the number of bytes to represent a character: 1 or 2.

   CHARS (integer) is the number of characters in a dimension: 94 or 96.

   LEADING-CODE-BASE (integer) is the base leading-code for the
   charset.

   LEADING-CODE-EXT (integer) is the extended leading-code for the
   charset.  All charsets of less than 0xA0 has the value 0.

   ISO-FINAL-CHAR (character) is the final character of the
   corresponding ISO 2022 charset.  It is -1 for such a character
   that is used only internally (e.g. `eight-bit-control').

   (e.g. `eight-bit-control').

   REVERSE-CHARSET (integer) is the charset which differs only in
   LEFT-TO-RIGHT value from the charset.  If there's no such a
   charset, the value is -1.
   
   SHORT-NAME (string) is the short name to refer to the charset.

   LONG-NAME (string) is the long name to refer to the charset.

   DESCRIPTION (string) is the description string of the charset.

   PLIST (property list) may contain any type of information a user
   want to put and get by functions `put-charset-property' and
   `get-charset-property' respectively.  */
extern Lisp_Object Vcharset_table;

/* Macros to access various information of CHARSET in Vcharset_table.
   We provide these macros for efficiency.  No range check of CHARSET.  */

  (SINGLE_BYTE_CHAR_P (c)				\
   ? ((ASCII_BYTE_P (c) || (c) >= 0xA0) ? 1 : 2)	\
   : char_bytes (c))

/* The following two macros CHAR_STRING and STRING_CHAR are the main
   entry points to convert between Emacs two types of character
   representations: multi-byte form and single-word form (character
   code).  */

/* Store multi-byte form of the character C in STR.  The caller should
   allocate at least MAX_MULTIBYTE_LENGTH bytes area at STR in

35478:340a9e4aeb29

/*** GENERAL NOTE on CHARACTER SET (CHARSET) ***

  A character set ("charset" hereafter) is a meaningful collection
  (i.e. language, culture, functionality, etc) of characters.  Emacs
  handles multiple charsets at once.  Each charset corresponds to one
  of the ISO charsets.  Emacs identifies a charset by a unique
  identification number, whereas ISO identifies a charset by a triplet
  of DIMENSION, CHARS and FINAL-CHAR.  So, hereafter, just saying
  "charset" means an identification number (integer value).

  The value range of charsets is 0x00, 0x81..0xFE.  There are four
  kinds of charset depending on DIMENSION (1 or 2) and CHARS (94 or
  96).  For instance, a charset of DIMENSION2_CHARS94 contains 94x94
  characters.

  Within Emacs Lisp, a charset is treated as a symbol which has a
  property `charset'.  The property value is a vector containing
  various information about the charset.  For readability of C code,
  we use the following convention for C variable names:
	charset_symbol: Emacs Lisp symbol of a charset
	charset_id: Emacs Lisp integer of an identification number of a charset
	charset: C integer of an identification number of a charset

  Each charset (except for ascii) is assigned a base leading-code
  (range 0x80..0x9E).  In addition, a charset of greater than 0xA0
  (whose base leading-code is 0x9A..0x9D) is assigned an extended
  leading-code (range 0xA0..0xFE).  In this case, each base
  leading-code specifies the allowable range of extended leading-code
  as shown in the table below.  A leading-code is used to represent a
  character in Emacs' buffer and string.

  We call a charset which has extended leading-code a "private
  charset" because those are mainly for a charset which is not yet
  registered by ISO.  On the contrary, we call a charset which does
  not have extended leading-code an "official charset".

  ---------------------------------------------------------------------------
  charset	dimension	 base leading-code	extended leading-code
  ---------------------------------------------------------------------------
  0x00		official dim1    -- none --		-- none --

   multibyte buffer/string.  So this macro name is not appropriate.  */
#define CHAR_HEAD_P(ch) ((unsigned char) (ch) < 0xA0)

/*** GENERAL NOTE on CHARACTER REPRESENTATION ***

  Firstly, the term "character" or "char" is used for a multilingual
  character (of course, including ASCII characters), not for a byte in
  computer memory.  We use the term "code" or "byte" for the latter
  case.

  A character is identified by charset and one or two POSITION-CODEs.
  POSITION-CODE is the position of the character in the charset.  A

  A character of DIMENSION2 charset has two POSITION-CODE:
  POSITION-CODE-1 and POSITION-CODE-2.  The code range of
  POSITION-CODE is 0x20..0x7F.

  Emacs has two kinds of representation of a character: multi-byte
  form (for buffers and strings) and single-word form (for character
  objects in Emacs Lisp).  The latter is called "character code"
  hereafter.  Both representations encode the information of charset
  and POSITION-CODE but in a different way (for instance, the MSB of
  POSITION-CODE is set in multi-byte form).

  For details of the multi-byte form, see the section "2. Emacs
  internal format handlers" of `coding.c'.

  Emacs uses 19 bits for a character code.  The bits are divided into
  3 fields: FIELD1(5bits):FIELD2(7bits):FIELD3(7bits).

  A character code of DIMENSION1 character uses FIELD2 to hold charset

#define SINGLE_BYTE_CHAR_P(c) ((unsigned) (c) < 0x100)

/* 1 if BYTE is an ASCII character in itself, in multibyte mode.  */
#define ASCII_BYTE_P(byte) ((byte) < 0x80)

/* A char-table containing information on each character set.

   Unlike ordinary char-tables, this doesn't contain any nested tables.
   Only the top level elements are used.  Each element is a vector of
   the following information:
	CHARSET-ID, BYTES, DIMENSION, CHARS, WIDTH, DIRECTION,
	LEADING-CODE-BASE, LEADING-CODE-EXT,
	ISO-FINAL-CHAR, ISO-GRAPHIC-PLANE,
	REVERSE-CHARSET, SHORT-NAME, LONG-NAME,	DESCRIPTION,
	PLIST.

   CHARSET-ID (integer) is the identification number of the charset.

   BYTES (integer) is the length of the multi-byte form of a character
   in the charset: one of 1, 2, 3, and 4.

   DIMENSION (integer) is the number of bytes to represent a character: 1 or 2.

   CHARS (integer) is the number of characters in a dimension: 94 or 96.

   LEADING-CODE-BASE (integer) is the base leading-code for the
   charset.

   LEADING-CODE-EXT (integer) is the extended leading-code for the
   charset.  All charsets of less than 0xA0 have the value 0.

   ISO-FINAL-CHAR (character) is the final character of the
   corresponding ISO 2022 charset.  It is -1 for such a character
   that is used only internally (e.g. `eight-bit-control').

   (e.g. `eight-bit-control').

   REVERSE-CHARSET (integer) is the charset which differs only in
   LEFT-TO-RIGHT value from the charset.  If there's no such a
   charset, the value is -1.

   SHORT-NAME (string) is the short name to refer to the charset.

   LONG-NAME (string) is the long name to refer to the charset.

   DESCRIPTION (string) is the description string of the charset.

   PLIST (property list) may contain any type of information a user
   wants to put and get by functions `put-charset-property' and
   `get-charset-property' respectively.  */
extern Lisp_Object Vcharset_table;

/* Macros to access various information of CHARSET in Vcharset_table.
   We provide these macros for efficiency.  No range check of CHARSET.  */

  (SINGLE_BYTE_CHAR_P (c)				\
   ? ((ASCII_BYTE_P (c) || (c) >= 0xA0) ? 1 : 2)	\
   : char_bytes (c))

/* The following two macros CHAR_STRING and STRING_CHAR are the main
   entry points to convert between Emacs's two types of character
   representations: multi-byte form and single-word form (character
   code).  */

/* Store multi-byte form of the character C in STR.  The caller should
   allocate at least MAX_MULTIBYTE_LENGTH bytes area at STR in