<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-2.xml                                                      = -->
<!-- = standard text processing module guide - chapter 2                  = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter module="txt" number="2">
  <title>Text sorting and transformation</title>
  
  <p>
  This chapter is dedicated to the <afnix/> text sorting and
  transformation, which is a subpart of the <em>standard text
  processing</em> module.
  </p>

  <!-- text sorting -->
  <section>
    <title>Text sorting</title>

    <p>
    Sorting is one the primary function implemented inside the
    <em>text processing</em> module. There are three sorting
    functions available in the module.
    </p>

    <!-- ascending and descending order sorting -->
    <subsect>
      <title>Ascending and descending order sorting</title>

      <p>
      The <code>sort-ascent</code> function operates with a vector
      object and sorts the elements in ascending order. Any kind of
      objects can be sorted as long as they support a comparison
      method. The elements are sorted in placed by using a <em>quick
      sort</em> algorithm.
      </p>

      <example>
      # create an unsorted vector
      const v-i (Vector 7 5 3 4 1 8 0 9 2 6)
      # sort the vector in place
      afnix:txt:sort-ascent v-i
      # print the vector
      for (e) (v) (println e)
      </example>

      <p>
      The <code>sort-descent</code> function is similar to the
      <code>sort-ascent</code> function except that the object are
      sorted in descending order.
      </p>
    </subsect>

    <!-- lexical sorting -->
    <subsect>
      <title>Lexical sorting</title>

      <p>
      The <code>sort-lexical</code> function operates with a vector
      object and sorts the elements in ascending order using a
      lexicographic ordering relation. Objects in the vector must be
      literal objects or an exception is raised.
      </p>
    </subsect>
  </section>

  <!-- transliteration -->
  <section>
    <title>Transliteration</title>

    <p>
    Transliteration is the process of changing characters my mapping
    one to another one. The transliteration process operates with a
    character source and produces a target character with the help of
    a mapping table. The transliteration process is not necessarily
    reversible as often indicated in the literature.
    </p>

    <!-- literate object -->
    <subsect>
      <title>Literate object</title>

      <p>
      The <code>Literate</code> object is a transliteration object
      that is bound by default with the identity function mapping. As
      usual, a predicate is associate with the object.
      </p>

      <example>
      # load the text module
      interp:library "afnix-txt"

      # create a transliterate object
      const tl (afnix:txt:Literate)

      # check the object
      afnix:txt:literate-p tl # true
      </example>

      <p>
      The transliteration process can also operate with an escape
      character in order to map double character sequence into a
      single one, as usually found inside programming language.
      </p>

      <example>
      # create a transliterate object with an escape character
      const tl (afnix:txt:Literate '\\')
      </example>
    </subsect>

    <!-- transliteration configuration -->
    <subsect>
      <title>Transliteration configuration</title>

      <p>
      The <code>set-map</code> configures the transliteration mapping
      table while the <code>set-escape-map</code> configure the escape
      mapping table. The mapping is done by setting the source
      character and the target character. For instance, if one want to
      map the tabulation character to a white space, the mapping table
      is set as follow:
      </p>

      <example>
      tl:set-map '\t' ' '
      </example>

      <p>
      The escape mapping table operates the same way. It should be
      noted that the mapping algorithm translate first the input
      character, eventually yielding to an escape character and then
      the escape mapping takes place. Note also that the
      <code>set-escape</code> method can be used to set the escape
      character.
      </p>

      <example>
      tl:set-map '\t' ' '
      </example>
    </subsect>

    <!-- transliteration process -->
    <subsect>
      <title>Transliteration process</title>

      <p>
      The transliteration process is done either with a string or an
      input stream. In the first case, the <code>translate</code>
      method operates with a string and returns a translated
      string. On the other hand, the <code>read</code> method returns
      a character when operating with a stream. 
      </p>

      <example>
      # set the mapping characters
      tl:set-map '\h' 'w'
      tl:set-map '\e' 'o'
      tl:set-map '\l' 'r'
      tl:set-map '\o' 'd'

      # translate a string
      tl:translate "helo" # word
      </example>
    </subsect>
  </section>
</chapter>
