repo_zf1/documentation/manual/de/module_specs/Zend_Locale-Parsing.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15156 -->
<!-- Reviewed: no -->
<sect1 id="zend.locale.parsing">

    <title>Normalisierung und Lokalisierung</title>

    <para>
        <classname>Zend_Locale_Format</classname> ist eine interne Komponente welche von <classname>Zend_Locale</classname> verwendet wird.
        Alle lokalisierbaren Klassen benutzen <classname>Zend_Locale_Format</classname> für Normalisierung und
        Lokalisierung von Nummern und Daten. Normalisierung beinhaltet das Analysieren von Eingaben von einer
        Vielfalt von Werten wie Datumswerte in eine standardisierten, strukturieren Art wie zum Beispiel
        ein PHP Array mit Jahr, Monat und Tages Elementen.
    </para>

    <para>
        Genau die gleiche Zeichenkette die eine Zahl oder ein Datum enthält meint etwas ganz anderes für Leute
        mit anderen Regeln und Konventionen. Die Erkennung von Nummern und Daten benötigt Regeln darüber wie diese
        Zeichenketten zu interpretieren sind um diese Werte in eine standardisierte Form zu bringen. Deswegen
        benötigen alle Methoden in <classname>Zend_Locale_Format</classname> ein Gebietsschema um Eingabedaten
        analysieren zu können.
        <note>
            <title>Standard "root" Gebietsschema</title>
            <para>
                Wenn kein Gebietsschema spezifiziert wurde, wird die Normalisierung und Lokalisierung das
                Standard "root" Gebietsschema verwenden, was zu unerwarteten Ergebnissen führen kann wenn die
                Eingabe in einem anderen Gebietsschema angegeben oder die Ausgabe für ein anderes
                Gebietsschema erwartet wurde.
            </para>
        </note>
    </para>

    <sect2 id="zend.locale.number.normalize">

        <title>Normalisierung von Nummern: getNumber($input, Array $options)</title>

        <para>
            Es gibt viele
            <ulink url="http://en.wikipedia.org/wiki/Numeral">Ziffernsysteme</ulink>
            welche siche vom üblichen
            <ulink url="http://en.wikipedia.org/wiki/Decimal">Dezimalsystem</ulink>
            unterscheiden (z.B. "3.14"). Nummern können mit der Funktion <code>getNumber()</code>
            normalisiert werden um ein gleichwertiges Ergebnis in einer Schreibweise des Standard
            Dezimalsystems zu erhalten. Für alle Ziffern-Relevanten Diskussionen in diesem Handbuch
            werden die
            <ulink url="http://en.wikipedia.org/wiki/Arabic_numerals">Arabisch/Europäischen Ziffern (0,1,2,3,4,5,6,7,8,9)</ulink>
            verwendet, ausser es ist anders definiert. Das Options Array kann ein 'locale' Gebietsschema enthalten, um
            eine Gruppierung und Kommazeichen zu definieren. Das Array kann auch eine Genauigkeit 'precision' enthalten
            um überschüssige Ziffern vom Ergebnis abzuschneiden.
        </para>

        <example id="zend.locale.number.normalize.example-1">
            <title>Normalisieren von Nummern</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::getNumber('13.524,678',
                                        array('locale' => $locale,
                                              'precision' => 3)
                                       );

print $number; // wird 13524.678 zurückgeben
]]></programlisting>
        </example>

        <sect3 id="zend.locale.number.normalize.precision">

            <title>Genauigkeit und Berechnungen</title>

            <para>
                Da <code>getNumber($value, array $options = array())</code> extrem lange Nummern lokalisieren
                kann, sollte das Ergebnis sorgfältig geprüft werden bevor endlich genaue Berechnungen
                wie normale mathematische PHP Operationen gemacht werden. Zum Beispiel
                <code>if ((string)int_val($number) != $number) { benutze
                <ulink url="http://www.php.net/bc">BCMath</ulink>
                oder
                <ulink url="http://www.php.net/gmp">GMP</ulink>
                </code>. Die meisten PHP Installationen unterstützen die BCMath Erweiterung.
            </para>

            <para>
                Auch die Genauigkeit des dezimalen Ergebnisses kann zu einer gewünschten Länge abgerundet werden
                bei <code>getNumber()</code> mit der Option <code>'precision'</code>. Wenn keine Genauigkeit
                angegeben wurde, wird nicht abgerundet. Für die Angabe der Genauigkeit dürfen nur PHP Integer
                Zahlen verwendet werden.
                Das Ergebnis wird nicht gerundet. Deswegen wird "1.6" auch "1" und nicht "2" zurückgeben, wenn als
                Genauigkeit null angegeben wurde.
            </para>

            <para>
                Wenn das dezimale Ergebnis zu einer gewünschten Länge abgeschnitten statt gerundet werden soll kann
                stattdessen die Option <code>'number_format'</code> verwendet werden. Die Länge des gewünschten
                dezimalen Ergebnisses kann mit der gewünschten Länge von Nullen bestimmt werden. Das Ergebnis wird
                dann nicht gerundet. Wenn also die definierte Genauigkeit innerhalb von <code>number_format</code>
                Null ist wird "1.6" den Wert "1" und nicht "2" zurückgeben. Siehe das folgende Beispiel:
            </para>

            <example id="zend.locale.number.normalize.precision.example-1">
                <title>Normalisierung von Nummern mit Genauigkeit</title>
                <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::getNumber('13.524,678',
                                        array('precision' => 1,
                                              'locale' => $locale)
                                       );
print $number; // will 13524.7 zurückgeben

$number = Zend_Locale_Format::getNumber('13.524,678',
                                        array('number_format' => '#.00',
                                              'locale' => $locale)
                                       );
print $number; // will 13524.67 zurückgeben
]]></programlisting>
            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.locale.number.localize">

        <title>Lokalisieren von Nummern</title>

        <para>
            <code>toNumber($value, array $options = array())</code> kann, mit Hilfe der folgenden
            <link linkend="zend.locale.appendix">unterstützten Gebietsschemata</link>, Nummern lokalisieren.
            Diese Funktion gibt eine lokalisierte Zeichenkette der angegebenen Nummer in dem konventionellen
            Format für ein definiertes Gebietsschema aus. Die Option 'number_format' definiert ein explizit
            angegebenes nicht standardmäßiges Nummernformat für die Verwendung mit <code>toNumber()</code>.
        </para>

        <example id="zend.locale.number.localize.example-1">
            <title>Lokalisieren von Nummern</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::toNumber(13547.36,
                                       array('locale' => $locale));

// gibt 13.547,36 zurück
print $number;
]]></programlisting>
        </example>

        <para>
            <note>
                <title>Unlimitierte Länge</title>
                <para>
                    <code>toNumber()</code> kann Nummern mit unendlicher Länge lokalisieren. Hierbei gibt
                    es keine Abhängigkeiten mit Integer oder Float Limits.
                </para>
            </note>
        </para>

        <para>
            Auf dem selben Web wie unter <code>getNumber()</code> verwendet <code>toNumber()</code> die Genauigkeit.
            Wenn keine Genauigkeit angegeben wurde, wird die komplette lokalisierte Nummer zurückgegeben.
        </para>

        <example id="zend.locale.number.localize.example-2">
            <title>Nummern mit bestimmter Genauigkeit lokalisieren</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::toNumber(13547.3678,
                                       array('precision' => 2,
                                             'locale' => $locale));

// gibt 13.547,37 zurück
print $number;
]]></programlisting>
        </example>

        <para>
            Wird die Option 'number_format' benutzt, kann ein selbst definiertes Format für das erstellen
            der Nummer definiert werden. Das Format selbst muß im CLDR Format wie anbei beschrieben angegeben
            werden. Das Gebietsschema wird hierbei benutzt um das Trennzeichen, die Genauigkeit und andere
            Formatierungszeichen für Zahlen zu erhalten. Deutsch definiert zum Beispiel ',' als Kommazeichen
            und im Englischen wird das '.' Zeichen benutzt.
        </para>

        <table id="zend.locale.number.localize.table-1">
            <title>Definitionen für selbst erzeugte Zahlenformate
            </title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Definition</entry>
                        <entry>Beschreibung</entry>
                        <entry>Beispiel Format</entry>
                        <entry>Erzeugte Ausgabe</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>#0</entry>
                        <entry>Erzeugt eine Zahl ohne Genauigkeit und ohne Trennung</entry>
                        <entry>#0</entry>
                        <entry>1234567</entry>
                    </row>
                    <row>
                        <entry>,</entry>
                        <entry>Erzeugt eine Trennung mit der Länge von einem Trennzeichen zum nächsten oder zur 0</entry>
                        <entry>#,##0</entry>
                        <entry>1,234,567</entry>
                    </row>
                    <row>
                        <entry>#,##,##0</entry>
                        <entry>Erzeugt eine Standard Trennung von 3 und alle weiteren Trennungen mit 2</entry>
                        <entry>#,##,##0</entry>
                        <entry>12,34,567</entry>
                    </row>
                    <row>
                        <entry>.</entry>
                        <entry>Erzeugt eine Kommazahl</entry>
                        <entry>#0.#</entry>
                        <entry>1234567.1234</entry>
                    </row>
                    <row>
                        <entry>0</entry>
                        <entry>Erzeugt eine Kommazahl mit definierter Länge</entry>
                        <entry>#0.00</entry>
                        <entry>1234567.12</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <example id="zend.locale.number.localize.example-3">
            <title>Ein selbst definiertes Zahlenformat verwenden</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::toNumber(13547.3678,
                                       array('number_format' => '#,#0.00',
                                             'locale' => 'de')
                                      );

// gibt 1.35.47,36 zurück
print $number;

$number = Zend_Locale_Format::toNumber(13547.3,
                                       array('number_format' => '#,##0.00',
                                             'locale' => 'de')
                                      );

// gibt 13.547,30 zurück
print $number;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.number.test">

        <title>Testen von Zahlen</title>

        <para>
            <code>isNumber($value, array $options = array())</code> prüft ob eine gegebene Zeichenkette eine Zahl
            enthält und gibt wahr oder falsch zurück.
        </para>

        <example id="zend.locale.number.test.example-1">
            <title>Testen von Zahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale();
if (Zend_Locale_Format::isNumber('13.445,36', array('locale' => 'de_AT')) {
    print "Zahl";
} else {
    print "keine Zahl";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.float.normalize">

        <title>Gleitkommazahlen normalisieren</title>

        <para>
            Lokalisierte Gleitkommazahlen können mit <code>getFloat($value, array $options = array())</code>
            analysiert werden. Es wird eine Gleitkommazahl zurückgegeben.
        </para>

        <example id="zend.locale.float.normalize.example-1">
            <title>Gleitkommazahlen normalisieren</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::getFloat('13.524,678',
                                       array('precision' => 2,
                                             'locale' => $locale));

// gibt 13524.68 zurück
print $number;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.float.localize">

        <title>Lokalisieren von Gleitkommazahlen</title>

        <para>
            <code>toFloat()</code> kann Gleitkommazahlen lokalisieren. Diese Funktion gibt eine
            lokalisierte Zeichenkette mit der gegebenen Zahl zurück.
        </para>

        <example id="zend.locale.float.localize.example-1">
            <title>Lokalisieren von Gleitkommazahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::toFloat(13547.3655,
                                      array('precision' => 1,
                                            'locale' => $locale));

// gibt 13.547,4 zurück
print $number;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.float.test">

        <title>Testen von Gleitkommazahlen</title>

        <para>
            <code>isFloat($value, array $options = array())</code> prüft ob eine gegebene Zeichenkette eine
            Gleitkommazahl enthält und gibt wahr oder falsch zurück.
        </para>

        <example id="zend.locale.float.test.example-1">
            <title>Testen von Gleitkommazahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::isFloat('13.445,36', array('locale' => $locale)) {
    print "Gleitkommazahl";
} else {
    print "keine Gleitkommazahl";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.integer.normalize">

        <title>Integer Zahlen normalisieren</title>

        <para>
            Integer Zahlen können mit der Funktion <code>getInteger()</code> analysiert werden. Es wird ein
            Integer Wert zurückgegeben.
        </para>

        <example id="zend.locale.integer.normalize.example-1">
            <title>Normalisieren von Integer Zahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::getInteger('13.524,678',
                                         array('locale' => $locale));

// gibt 13524 zurück
print $number;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.integer.localize">

        <title>Lokalisieren von Integer Zahlen</title>

        <para>
            <code>toInteger($value, array $options = array())</code> kann Integer Zahlen lokalisieren.
            Diese Funktion gibt eine lokalisierte Zeichenkette anhand der gegebenen Nummer zurück.
        </para>

        <example id="zend.locale.integer.localize.example-1">
            <title>Lokalisieren von Integer Zahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$number = Zend_Locale_Format::toInteger(13547.3655,
                                        array('locale' => $locale));

// gibt 13.547 zurück
print $number;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.integer.test">

        <title>Testen von Integer Zahlen</title>

        <para>
            <code>isInteger($value, array $options = array())</code> prüft ob eine gegebene Zeichenkette eine
            Integer Zahl enthält und gibt wahr oder falsch zurück.
        </para>

        <example id="zend.locale.integer.test.example-1">
            <title>Testen von Integer Zahlen</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::isInteger('13.445', array('locale' => $locale)) {
    print "Integerzahl";
} else {
    print "keine Integerzahl";
}
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.numbersystems">

        <title>Konvertieren von Zahlensystemen</title>

        <para>
            <classname>Zend_Locale_Format::convertNumerals()</classname> kann die Ziffern zwischen den unterschiedlichen
            <ulink url="http://en.wikipedia.org/wiki/Arabic_numerals">Zahlensystemen</ulink> umwandeln.
            Das inkludiert auch das Standard Arabisch/Europäisch/Lateinische Zahlensystem (0,1,2,3,4,5,6,7,8,9).
            Nicht zu verwechseln mit dem
            <ulink url="http://en.wikipedia.org/wiki/Eastern_Arabic_numerals">Ost-arabischen Zahlensystem</ulink>
            welches in der Arabischen Sprache benutzt wird um Zahlen zu schreiben. Der Versuch ein nicht
            unterstütztes Zahlensystem zu benutzen führt zu einer Ausnahme um eine irrtümliche falsche Konvertierung
            wegen eines Schreibfehlers zu verhindern. Alle Zeichen der Eingabe, welche keine Ziffern des angegebenen
            Zahlenformates sind, werden in den Ausgabestring kopiert ohne das Sie verändert werden. Das beinhaltet
            auch die Trennzeichen der Zahlen. <classname>Zend_Locale</classname>* Komponenten sind abhängig von den Daten welche
            durch die CLDR liefert (hier ist eine
            <ulink url="http://unicode.org/cldr/data/diff/supplemental/languages_and_scripts.html?sortby=date">
            Liste von Schreibweisen gruppiert nach Sprachen</ulink>).
        </para>

        <para>
            Im CLDR und auch hier, werden die Europäisch/Lateinischen Zahlen als "Latin" bezeichnet und mit
            dem zugeordneten 4-Zeichen-Code "Latn" referriert. Im CLDR werden Zahlensysteme auch als
            "Schreibweisen" (Scripts) bezeichnet.
        </para>

        <para>
            Nehmen wir an eine Web Form erhält eine nummerische Eingabe welche Ost-Arabische
            Ziffern enthält "١‎٠٠". Die meisten Programme und PHP Funktionen erwarten Eingaben aber
            als Lateinische Ziffern. Glücklicherweise wird für die Konvertierung dieser Eingabe in
            gleichwertige Lateinische Ziffern "100" sehr wenig Aufwand. Es muß nur
            <code>convertNumerals($inputNumeralString, $sourceNumeralSystem, $destNumeralSystem)</code>
            benutzt werden werden welches <code>$input</code> zurückgibt und hierbei die Ziffern
            der Schreibweise <code>$sourceNumeralSystem</code> in die Schreibweise
            <code>$destNumeralSystem</code> konvertiert.
        </para>

        <example id="zend.locale.numbersystems.example-1">
            <title>Konvertieren von Ost-Arabischen Ziffern in Europäisch Lateinische Ziffern</title>
            <programlisting role="php"><![CDATA[
$arabicScript = "١‎٠٠";   // Arabisch für "100" (ein Hundert)
$latinScript = Zend_Locale_Format::convertNumerals($arabicScript,
                                                   'Arab',
                                                   'Latn');

print "\nOriginal:   " . $arabicScript;
print "\nNormalisiert: " . $latinScript;
]]></programlisting>
        </example>

        <para>
            Genauso kann jedes unterstützte Zahlensystem in jedes andere unterstützte Zahlensystem konvertiert werden.
        </para>

        <example id="zend.locale.numbersystems.example-2">
            <title>Konvertieren von Lateinischen Ziffern in Ost-Arabische Ziffern</title>
            <programlisting role="php"><![CDATA[
$latinScript = '123';
$arabicScript = Zend_Locale_Format::convertNumerals($latinScript,
                                                    'Latn',
                                                    'Arab');

print "\nOriginal:  " . $latinScript;
print "\nLokalisiert: " . $arabicScript;
]]></programlisting>
        </example>

        <example id="zend.locale.numbersystems.example-3">
            <title>Auslesen des 4 Zeichen CLDR Codes durch Benutzen des Namens in der Muttersprache</title>
            <programlisting role="php"><![CDATA[
function getScriptCode($scriptName, $locale)
{
    $scripts2names = Zend_Locale_Data::getList($locale, 'scriptlist');
    $names2scripts = array_flip($scripts2names);
    return $names2scripts[$scriptName];
}
echo getScriptCode('Latin', 'en'); // Ausgabe "Latn"
echo getScriptCode('Tamil', 'en'); // Ausgabe "Taml"
echo getScriptCode('tamoul', 'fr'); // Ausgabe "Taml"
]]></programlisting>
        </example>

        <sect3 id="zend.locale.appendix.numberscripts.supported">

            <title>Liste der unterstützten Zahlensysteme</title>

            <para>
                <table id="zend.locale.appendix.numberscripts.supported.table">
                    <title>Liste der unterstützten Zahlensysteme</title>
                    <tgroup cols="2">
                        <thead>
                            <row>
                                <entry>Geschriebener Name</entry>
                                <entry>Schreibweise</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>Arabisch</entry>
                                <entry>Arab</entry>
                            </row>
                            <row>
                                <entry>Balinesisch</entry>
                                <entry>Bali</entry>
                            </row>
                            <row>
                                <entry>Bengalisch</entry>
                                <entry>Beng</entry>
                            </row>
                            <row>
                                <entry>Devanagari</entry>
                                <entry>Deva</entry>
                            </row>
                            <row>
                                <entry>Gujarati</entry>
                                <entry>Gujr</entry>
                            </row>
                            <row>
                                <entry>Gurmukhi</entry>
                                <entry>Guru</entry>
                            </row>
                            <row>
                                <entry>Kannada</entry>
                                <entry>Knda</entry>
                            </row>
                            <row>
                                <entry>Khmer</entry>
                                <entry>Khmr</entry>
                            </row>
                            <row>
                                <entry>Laotisch</entry>
                                <entry>Laoo</entry>
                            </row>
                            <row>
                                <entry>Limbu</entry>
                                <entry>Limb</entry>
                            </row>
                            <row>
                                <entry>Malaysisch</entry>
                                <entry>Mlym</entry>
                            </row>
                            <row>
                                <entry>Mongolisch</entry>
                                <entry>Mong</entry>
                            </row>
                            <row>
                                <entry>Burmesisch</entry>
                                <entry>Mymr</entry>
                            </row>
                            <row>
                                <entry>Tai Lue</entry>
                                <entry>Talu</entry>
                            </row>
                            <row>
                                <entry>N’Ko</entry>
                                <entry>Nkoo</entry>
                            </row>
                            <row>
                                <entry>Oriya</entry>
                                <entry>Orya</entry>
                            </row>
                            <row>
                                <entry>Tamilisch</entry>
                                <entry>Taml</entry>
                            </row>
                            <row>
                                <entry>Telugu</entry>
                                <entry>Telu</entry>
                            </row>
                            <row>
                                <entry>Tai Le</entry>
                                <entry>Tale</entry>
                            </row>
                            <row>
                                <entry>Tibetisch</entry>
                                <entry>Tibt</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </para>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->