root/trunk/spec/int.dbk

<?xml version="1.0"?>
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article>
  <articleinfo>
    <title>
      Integer Language-Independent Type for
      <trademark>YAML</trademark>&nbsp;Version&nbsp;1.1
    </title>

    <subtitle>
      Working Draft 2005-02-11
    </subtitle>

    <authorgroup>
      <author>
        <firstname>Oren</firstname>
        <surname>Ben-Kiki</surname>
        <email>oren@ben-kiki.org</email>
      </author>

      <author>
        <firstname>Clark</firstname>
        <surname>Evans</surname>
        <email>cce+yaml@clarkevans.com</email>
      </author>

      <author>
        <firstname>Brian</firstname>
        <surname>Ingerson</surname>
        <email>ingy@ttul.org</email>
      </author>
    </authorgroup>

    <copyright>
      <year>2001-2005</year>
      <holder>Oren Ben-Kiki<fo>,&nbsp;</fo></holder>
      <holder>Clark Evans<fo>,&nbsp;</fo></holder>
      <holder>Brian Ingerson</holder>
    </copyright>

    <legalnotice>
      This document may be freely copied provided it is not modified.
    </legalnotice>

    <abstract>
      <title>Status</title>

      <para>
       This specification is a draft reflecting consensus reached by members of
       the <ulink
       url="http://lists.sourceforge.net/lists/listinfo/yaml-core">yaml-core
       mailing list</ulink>. Any questions regarding this draft should be
       raised on this list.
      </para>
    </abstract>
  </articleinfo>

  <section>
    <variablelist>
      <varlistentry>
        <term>
          <para>
            URI:
          </para>
        </term>

        <listitem>
          <para>
            <userinput>tag:yaml.org,2002:int</userinput>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Shorthand:
          </para>
        </term>

        <listitem>
          <para>
            <userinput>!!int</userinput>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Kind:
          </para>
        </term>

        <listitem>
          <para>
            Scalar.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Definition:
          </para>
        </term>

        <listitem>
          <para>
            Mathematical integers.
          </para>

          <para>
            Integers represent arbitrarily sized finite mathematical integers.
            Integers can be formatted using the familiar decimal notation, may
            have a leading <quote><userinput>0x</userinput></quote> to signal
            hexadecimal, a leading <quote><userinput>0b</userinput></quote> to
            indicate binary bits (base 2), or have leading
            <quote><userinput>0</userinput></quote> to signal an octal base.
            Using <quote><userinput>:</userinput></quote> allows expressing
            integers in base 60, which is convenient for time and angle values.
            Any <quote><userinput>_</userinput></quote> characters in the
            number are ignored, allowing a readable representation of large
            values.
          </para>

          <para>
            Scalars of this type should be represented by a native integer data
            type, if possible. However, there are cases where an integer
            provided may overflow the native type&#8217;s storage capability.
            In this case, the processor should find some manner to round-trip
            the integer, perhaps using a string based representation. In
            general, integers representable using 32 binary digits should
            safely round-trip through most systems.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Canonical Format:
          </para>
        </term>

        <listitem>
          <para>
            <userinput>0|-?[1-9]&amp;[0-9]* <lineannotation># (base
            10)</lineannotation></userinput>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <para>
            Resolution and Validation:
          </para>
        </term>

        <listitem>
          <para>
            Valid values must match the following regular expression,
            which may also be used for implicit tag resolution:
          </para>

<screen>
 [-+]?0b[0-1_]+ <lineannotation># (base 2)</lineannotation>
|[-+]?0[0-7_]+ <lineannotation># (base 8)</lineannotation>
|[-+]?(0|[1-9][0-9_]*) <lineannotation># (base 10)</lineannotation>
|[-+]?0x[0-9a-fA-F_]+ <lineannotation># (base 16)</lineannotation>
|[-+]?[1-9][0-9_]*(:[0-5]?[0-9])+ <lineannotation># (base 60)</lineannotation>
</screen>
        </listitem>
      </varlistentry>
    </variablelist>

    <example>
      <title><userinput>!!int</userinput> Examples</title>
<programlisting>
canonical: 685230
decimal: +685_230
octal: 02472256
hexadecimal: 0x_0A_74_AE
binary: 0b1010_0111_0100_1010_1110
sexagesimal: 190:20:30
</programlisting>
    </example>
  </section>
</article>