/ 
Quiq-1.220
River stage zero No dependents
/ Quiq::String

NAME

Quiq::String - Operationen auf Zeichenketten

BASE CLASS

Quiq::Object

METHODS

Eigenschaften

maxLineLength() - Länge der längsten Zeile

Synopsis

$len = $class->maxLineLength($text);

Arguments

$text

Ein String, typischerweise mehrzeilig.

Returns

Länge der längsten Zeile (Integer)

Description

Ermittele die Länge der längsten Zeile und liefere diese zurück. Newline wird nicht mitgezählt.

Encoding

autoDecode() - Auto-dekodiere Zeichenkette

Synopsis

$str = $class->autoDecode($str);
$str = $class->autoDecode($str,$otherEncoding);

Description

Analysiere Zeichenkette $str hinsichtlich ihres Character-Encodings und dekodiere sie entsprechend. Unterschieden werden:

  • ASCII

  • UTF-8

  • UTF-16/32 mit BOM

und $otherEncoding. Ist $otherEncoding nicht angegeben, wird ISO-8859-1 angenommen.

Einrückung

indent() - Rücke Text ein

Synopsis

$str2 = $class->indent($str,$indentStr,@opt);
$class->indent(\$str,$indentStr,@opt);

Options

-indentBlankLines => $bool (Default: 0)

Rücke auch Leerzeilen ein. Per Default werden nur Zeilen mit wenigstens einem Zeichen eingerückt.

Diese Option ist nützlich, wenn die Funktion zum Auskommentieren genutzt werden soll.

-strip => $bool (Default: 0)

Entferne Newlines am Anfang und Whitespace am Ende. Per Default geschieht dies nicht.

Description

Rücke den Text $str um Zeichenkette $indentStr ein und liefere das Resultat zurück.

Die Einrück-Zeichenkette $indentStr wird jeder Zeile von $str hinzugefügt, außer Leerzeilen.

Example

  • Texteinrückung um vier Leerzeichen

    $class->indent($txt,' ' x 4);

|Dies ist                   |    Dies ist
|ein Test-   - wird zu ->   |    ein Test-
|Text.                      |    Text.

determineIndentation() - Einrücktiefe eines Textes

Synopsis

$n = $class->determineIndentation($str);

Description

Ermittele die Einrücktiefe des Textes $str und liefere diese zurück. Die Einrücktiefe ist der größte gemeinsame Teiler aller Zeilen-Einrückungen. Beispiel:

|Dies
|    ist
|       ein
|           Test

Einrücktiefe ist 4.

WICHTIG: Für die Einrückung zählen nur Leerzeichen, keine Tabs!

reduceIndentation() - Reduziere Einrücktiefe eines Textes

Synopsis

$str = $class->reduceIndentation($n,$str);
$class->reduceIndentation($n,\$str);

Description

Reduziere die Einrücktiefe des Textes $str auf Tiefe $n.

Example

Text:

|Dies
|    ist
|        ein
|            Test

Reduktion auf Einrücktiefe 2:

Quiq::String->reduceIndentation(2,$str);

Resultat:

|Dies
|  ist
|    ein
|      Test

removeIndentation() - Entferne Text-Einrückung

Synopsis

$str = $class->removeIndentation($str,@opt); # [1]
$class->removeIndentation(\$str,@opt);       # [2]

Options

-addNL => $bool (Default: 0)

Nach dem Entfernen aller NEWLINEs am Ende füge ein NEWLINE hinzu.

Description

[1] Entferne Text-Einrückung aus Zeichenkette $str und liefere das Resultat zurück.

[2] Wird eine Referenz auf $str übergeben, wird die Zeichenkette "in place" manipuliert und nichts zurückgegeben.

  • NEWLINEs am Anfang werden entfernt.

  • Whitespace (SPACEs, TABs, NEWLINEs) am Ende wird entfernt. Das Resultat endet also grundsätzlich nicht mit einem NEWLINE.

  • Die Methode kehrt zurück, wenn $str anschließend nicht mit wenigstens einem Whitespace-Zeichen beginnt, denn dann existiert keine Einrückung, die zu entfernen wäre.

  • Die Einrückung von $str ist die längste Folge von SPACEs und TABs, die allen Zeilen von $str gemeinsam ist, ausgenommen Leerzeilen. Diese Einrückung wird am Anfang aller Zeilen von $str entfernt.

  • Eine Leerzeile ist eine Zeile, die nur aus Whitespace besteht.

Example

  • Einrückung entfernen, Leerzeile übergehen:

    |
|  Dies ist
|              <- Leerzeile ohne Einrückung
|  ein Test-
|  Text.
|

    wird zu

    |Dies ist
|
|ein Test-
|Text.

  • Tiefere Einrückung bleibt bestehen:

    |
|    Dies ist
|  ein Test-
|  Text.
|

    wird zu

    |  Dies ist
|ein Test-
|Text.

removeIndentationNl() - Entferne Text-Einrückung

Synopsis

$str = $class->removeIndentationNl($str,@opt); # [1]
$class->removeIndentationNl(\$str,@opt);       # [2]

Kommentare

removeComments() - Entferne Kommentare aus Quelltext

Synopsis

$newCode = $this->removeComments($code,$start);
$newCode = $this->removeComments($code,$start,$stop);

Description

Entferne alle Kommentare aus Quelltext $code und liefere das Resultat zurück. Die Kommentarzeichen werden durch die Parameter $start und $stop definiert. Siehe Abschnitt Examples.

Die Methode entfernt nicht nur die Kommentare selbst, sondern auch nachfolgenden oder vorausgehenden Whitespace, so dass kein überflüssiger Leerraum entsteht.

Im Falle von einzeiligen Kommentaren (d.h. nur $start ist definiert), wird vorausgesetzt, dass dem Kommentarzeichen (der Kommentar-Zeichenkette) im Quelltext zusätzlich ein Leerzeichen oder Tab vorausgeht, sofern es nicht am Anfang der Zeile steht. D.h.

my $ind = ' ' x 4; # Einrückung
                  ^ ^
                  hier müssen Leerzeichen (oder Tabs) stehen

my $ind = ' ' x 4;# Einrückung
                  ^
                  Wird nicht erkannt!

my $ind = ' ' x 4; #Einrückung
                   ^
                   Wird nicht erkannt!

Im Falle von mehrzeiligen Kommentaren ($start und $stop sind definiert) ist dies das vorausgehende Leereichen nicht nötig.

Examples

HTML, XML:

$code = Quiq::String->removeComments($code,'<!--','-->');

C, Java, CSS:

$code = Quiq::String->removeComments($code,'/*','*/');

C++, JavaScript:

$code = Quiq::String->removeComments($code,'//');

Shell, Perl, Python, Ruby, ...:

$code = Quiq::String->removeComments($code,'#');

SQL:

$code = Quiq::String->removeComments($code,'--');

Quoting

quote() - Fasse Zeichenkette in Single Quotes ein

Synopsis

$quotedStr = $class->quote($str);

Description

Fasse Zeichenkette $str in einfache Anführungsstriche (') ein und liefere das Resultat zurück. Enthält die Zeichenkette bereits einfache Anführungsstriche, werden diese per Backslash geschützt.

Zeilenfortsetzungen

joinLines() - Füge Zeilen mit Zeilenfortsetzungszeichen zusammen

Synopsis

$newText = $class->joinLines($char,$text);

Arguments

$char

Zeilenfortsetzungszeichen

$text

Text mit Zeilenfortsetzungszeichen

Description

Vereinige alle Zeilen in $text, die auf das Zeilenfortsetzungszeichen $char enden, mit der Folgezeile zusammen und liefere das Resultat zurück. Whitespace am Anfang der Folgezeile wird entfernt.

Wird das Zeilenfortsetzungszeichen verdoppelt, bleibt es stehen und die Zeilen werden nicht zusammengefasst.

Anmerkung: Der Backslash (\) ist als Fortsetzungszeichen nicht so gut geeignet, da er von Perl interpretiert wird und in Zeichenketten mit doppelten Anführungsstrichen verdoppelt werden muss.

Example

Verwende die Tilde (~) als Fortsetzungszeichen:

Quiq::String->joinLines('~',"Dies ist ~\nein Text");
==>
"Dies ist ein Text"

Das Fortsetzungszeichen kann literal am Ende einer Zeile stehen, wenn es verdoppelt wird:

Quiq::String->joinLines('~',"Dies ist ~~\nein Text");
==>
"Dies ist ~\nein Text"

Umbruch

wrap() - Umbreche Fließtext

Synopsis

$text = $class->wrap($text,@opt);

Options

-width => $n (Default: 70)

Maximale Zeilenbreite des resultierenden Fließtextes (sofern kein einzelnes Wort länger als die Zeilenbreite ist).

Description

Umbreche Fließext $text, so dass die Zeilenlänge $width möglichst nicht überschritten wird. Sie kann überschritten werden, wenn ein Wort länger als $width ist, sonst ist die Zeilenlänge <= $width.

Whitespace:

  • Whitespace am Anfang und am Ende von $text wird entfernt

  • Folgen von Whitespace-Zeichen innerhalb von $text werden zu einem Whitespace-Zeichen reduziert

Paragraphen:

Ist der Text in Paragraphen organisiert und soll dies erhalten bleiben, muss jeder Paragraph einzeln umbrochen werden.

Example

Maximale Zeilenlänge auf 12 Zeichen begrenzen:

$txt = "Dies ist ein Test mit einem kurzen Text.";
$txt = Quiq::String->wrap($txt,-width=>12);
# =>
Dies ist ein
Test mit
einem kurzen
Text.

VERSION

1.220

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.