break_string()
==============

FUNKTION
--------
::

    string break_string(string str)
    string break_string(string str, int width)
    string break_string(string str, int width, string indent)
    string break_string(string str, int width, int space)
    string break_string(string str, int width, string indent, int flags)
    string break_string(string str, int width, int space, int flags)

ARGUMENTE
---------
::

    str    - umzubrechender String
    width  - optional: maximale Zeilenlaenge (default 78)
    indent - optional: String, der vor jeder umgebrochenen Zeile erscheint
    space  - optional: Anzahl der Leerzeichen vor jeder umgebrochenen Zeile
    flags  - optional: hiermit laesst sich das Verhalten von break_string()
             aendern; moegliche Flags siehe Punkt 'Beschreibung'

BESCHREIBUNG
------------
::

    In der ersten Form wird der String 'str' durch Einfuegen von "\n" so um-
    gebrochen, dass bei einer anschliessenden Ausgabe keine Zeile laenger
    als 'width' Zeichen ist. Eventuell schon in 'str' vorhandene "\n" werden
    dabei vorher entfernt.

    Gibt man zusaetzlich noch einen String 'indent' an, so wird dieser vor
    jede der umgebrochenen Zeilen gesetzt.

    Analog wird bei der Angabe der Zahl 'space' ein String mit 'space' Leer-
    zeichen vor jede umgebrochene Zeile gesetzt.

    Zusaetzlich gibt es folgende optionale Flags, die man beliebig kombinieren
    kann:

        BS_LEAVE_MY_LFS  -  schon im Text vorhandene "\n" werden beibehalten
        BS_SINGLE_SPACE  -  doppelte Leerzeichen sowie Leerzeichen nach Zeilen-
                            umbruechen werden entfernt
        BS_BLOCK         -  der Text wird im Blocksatz formatiert
        BS_NO_PARINDENT  -  bei Blocksatz mit vorgegebenen Zeilenumbruechen
                            (BS_BLOCK|BS_LEAVE_MY_LFS) werden Zeilen nach "\n"
                            normalerweise mit einem Leerzeichen begonnen.
                            Um das Einfuegen des fuehrenden Leerzeichens zu
                            unterdruecken, muss BS_NO_PARINDENT angegeben werden
        BS_INDENT_ONCE   -  die erste Zeile des Textes wird mit vorangestelltem
                            'indent' ausgegeben; alle folgenden Zeilen bekommen
                            einen Leerstring vorangestellt
        BS_PREPEND_INDENT - der Ident wird dem Text vorangestellt sofern der 
                            Indent + Text laenger als eine Zeile ist. Der Text
			    wird um ein Leerzeichen eingerueckt, was mittels
                            BS_NO_PARINDENT verhindert werden kann.

RUECKGABEWERT
-------------
::

    Der umgebrochene Text.

    Laufzeit-Fehler, wenn der Indent laenger ist als die vorgegebene Breite.

BEISPIELE
---------
::

    write(break_string("Dies ist ein laengerer Text. Nur so als Beispiel.",27));

        => Dies ist ein laengerer
           Text. Nur so als Beispiel.

    write(break_string("Mit indent sieht das so aus", 30, "Wargon sagt: "));

        => Wargon sagt: Mit indent sieht
           Wargon sagt: das so aus

    write(break_string("Mit indent sieht das so aus", 30, "Wargon sagt: ",
                        BS_INDENT_ONCE));

        => Wargon sagt: Mit indent sieht
                        das so aus

    write(break_string("Mit Leerzeichen sieht das so aus", 30, 2));

        =>   Mit Leerzeichen sieht das so
             aus...

    write(break_string("Ich will es\naber vorformatiert!",60,
                        "Wargon sagt: ", BS_LEAVE_MY_LFS));

        => Wargon sagt: Ich will es
           Wargon sagt: aber vorformatiert!

    write(break_string("Ich will es\naber vorformatiert!",30,
                        "Wargon sagt: ", BS_PREPEND_INDENT));

        => Wargon sagt:
            Ich will es aber 
            vorformatiert!

SIEHE AUCH
----------
::

    senderwiederholung