<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter>
<title>Characters</title>
<section xml:id="ansi.characters.c-dict">
<title>C Reference</title>
  <refentry xml:id="ansi.characters.c-types">
    <refnamediv>
      <refname>C types</refname>
      <refpurpose>C character types</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Type names</title>
      <simplelist columns="2" type="horiz">
	<member><type>ecl_character</type></member>
	<member><type>character</type></member>

	<member><type>ecl_base_char</type></member>
	<member><type>base-char</type></member>
      </simplelist>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para>&ECL; defines two C types to hold its characters: <type>ecl_base_char</type> and <type>ecl_character</type>.</para>
      <itemizedlist>
	<listitem><para>When &ECL; is built without Unicode, they both coincide and typically match <type>unsigned char</type>, to cover the 256 codes that are needed.</para></listitem>
	<listitem><para>When &ECL; is built with Unicode, the two types are no longer equivalent, with <type>ecl_character</type> being larger.</para></listitem>
      </itemizedlist>

      <para>For your code to be portable and future proof, use both types to really express what you intend to do.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Constructors</refname>
      <refpurpose>Creating and extracting characters from Lisp objects</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions and macros</title>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ECL_CODE_CHAR</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>code</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>ecl_character <function>ECL_CHAR_CODE</function></funcdef>
	  <paramdef><type>cl_object</type> <parameter>o</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>cl_object <function>ecl_char_code</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>code</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>ecl_base_char <function>ecl_base_char_code</function></funcdef>
	  <paramdef><type>cl_object</type> <parameter>o</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>These functions and macros convert back and forth from C character types to Lisp. The macros <function>ECL_CHAR_CODE</function> and <function>ECL_CODE_CHAR</function> perform this coercion without checking the arguments. The functions <function>ecl_char_code</function> and <function>ecl_base_char_code</function>, on the other hand, verify that the argument has the right type and signal an error otherwise.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Predicates</refname>
      <refpurpose>C predicates for Lisp characters</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions and macros</title>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_base_char_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_alpha_char_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_alphanumeric_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_graphic_char_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_digit_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_standard_char_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>These functions are equivalent to their Lisp equivalents but return C booleans.</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Character case</refname>
      <refpurpose>C functions related to the character case</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <title>Functions and macros</title>
      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_upper_case_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_lower_case_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>bool <function>ecl_both_case_p</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>ecl_character <function>ecl_char_downcase</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>

      <funcsynopsis>
	<funcprototype>
	  <?dbhtml funcsynopsis-style='ansi'?>
	  <funcdef>ecl_character <function>ecl_char_upcase</function></funcdef>
	  <paramdef><type>ecl_character</type> <parameter>c</parameter></paramdef>
	</funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>These functions check or change the case of a character. Note that in an Unicode context, the output of these functions might not be accurate (for instance when the uppercase character has two or more codepoints).</para>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>ANSI Dictionary</refname>
      <refpurpose>&ANSI-C-Dict;</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<simplelist columns="2" type="horiz">
<member>Lisp symbol</member>
<member>C function</member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char=</symbol></ulink></member>
<member><code>cl_object cl_charE(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char/=</symbol></ulink></member>
<member><code>cl_object cl_charNE(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char&lt;</symbol></ulink></member>
<member><code>cl_object cl_charL(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char&gt;</symbol></ulink></member>
<member><code>cl_object cl_charG(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char&lt;=</symbol></ulink></member>
<member><code>cl_object cl_charLE(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char&gt;=</symbol></ulink></member>
<member><code>cl_object cl_charGE(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-equal</symbol></ulink></member>
<member><code>cl_object cl_char_equal(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-not-equal</symbol></ulink></member>
<member><code>cl_object cl_char_not_equal(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-lessp</symbol></ulink></member>
<member><code>cl_object cl_char_lessp(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-greaterp</symbol></ulink></member>
<member><code>cl_object cl_char_greaterp(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-not-greaterp</symbol></ulink></member>
<member><code>cl_object cl_char_not_greaterp(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_chareq.htm"><symbol>char-not-lessp</symbol></ulink></member>
<member><code>cl_object cl_char_not_lessp(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_ch.htm"><symbol>character</symbol></ulink></member>
<member><code>cl_object cl_character(cl_object char_designator)</code></member>

<member><ulink url="&clhs;f_chp.htm"><symbol>characterp</symbol></ulink></member>
<member><code>cl_object cl_characterp(cl_object object)</code></member>

<member><ulink url="&clhs;f_alpha_.htm"><symbol>alpha-char-p</symbol></ulink></member>
<member><code>cl_object cl_alpha_char_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_alphan.htm"><symbol>alphanumericp</symbol></ulink></member>
<member><code>cl_object cl_alphanumericp(cl_object character)</code></member>

<member><ulink url="&clhs;f_digit_.htm"><symbol>digit-char</symbol></ulink></member>
<member><code>cl_object cl_digit_char(cl_narg narg, cl_object character, ...)</code></member>

<member><ulink url="&clhs;f_digi_1.htm"><symbol>digit-char-p</symbol></ulink></member>
<member><code>cl_object cl_digit_char_p(cl_narg narg, cl_object character, ...)</code></member>

<member><ulink url="&clhs;f_graphi.htm"><symbol>graphic-char-p</symbol></ulink></member>
<member><code>cl_object cl_graphic_char_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_std_ch.htm"><symbol>standard-char-p</symbol></ulink></member>
<member><code>cl_object cl_standard_char_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_char_u.htm"><symbol>char_upcase</symbol></ulink></member>
<member><code>cl_object cl_char_upcase(cl_object character)</code></member>

<member><ulink url="&clhs;f_char_u.htm"><symbol>char-downcase</symbol></ulink></member>
<member><code>cl_object cl_char_downcase(cl_object character)</code></member>

<member><ulink url="&clhs;f_upper_.htm"><symbol>upper-case-p</symbol></ulink></member>
<member><code>cl_object cl_upper_case_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_upper_.htm"><symbol>lower-case-p</symbol></ulink></member>
<member><code>cl_object cl_lower_case_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_upper_.htm"><symbol>both-case-p</symbol></ulink></member>
<member><code>cl_object cl_both_case_p(cl_object character)</code></member>

<member><ulink url="&clhs;f_char_c.htm"><symbol>char-code</symbol></ulink></member>
<member><code>cl_object cl_char_code(cl_object character)</code></member>

<member><ulink url="&clhs;f_char_i.htm"><symbol>char-int</symbol></ulink></member>
<member><code>cl_object cl_char_int(cl_object character)</code></member>

<member><ulink url="&clhs;f_code_c.htm"><symbol>code-char</symbol></ulink></member>
<member><code>cl_object cl_code_char(cl_object code)</code></member>

<member><ulink url="&clhs;f_char_n.htm"><symbol>char-name</symbol></ulink></member>
<member><code>cl_object cl_char_name(cl_object character)</code></member>

<member><ulink url="&clhs;f_name_c.htm"><symbol>name-char</symbol></ulink></member>
<member><code>cl_object cl_name_char(cl_object name)</code></member>
</simplelist>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para></para>
    </refsect1>
  </refentry>
</section>
</chapter>
</book>