NAME

Quiq::Array - Operationen auf Arrays

BASE CLASS

Quiq::Object

DESCRIPTION

Ein Objekt der Klasse repräsentiert ein Array. Jede der Methoden kann sowohl auf ein Objekt der Klasse als auch per Aufruf als Klassenmethode auf ein ungeblesstes Perl-Array angewendet werden.

Aufruf als Objektmethode:

  $arr->$meth(...);

Aufruf als Klassenmethode:

  $class->$meth(\@arr, ...);

METHODS

Konstruktor

new() - Konstruktor

Synopsis

  $arr = $class->new;
  $arr = $class->new(\@arr);

Description

Instantiiere ein Array-Objekt und liefere eine Referenz auf dieses Objekt zurück. Ohne Angabe einer Array-Referenz wird ein leeres Array-Objekt instantiiert.

Operationen

different() - Vergleiche Array gegen Array

Synopsis

  ($only1A,$only2A,$bothA) = $arr1->different(\@arr2);
  ($only1A,$only2A,$bothA) = $class->different(\@arr1,\@arr2);

Alias

compare()

Description

Vergleiche die Elemente der Arrays @$arr1 und @arr2 und liefere Referenzen auf drei Arrays (Mengen) zurück:

$only1A:

Referenz auf die Liste der Elemente, die nur in @arr1 enthalten sind.

$only2A:

Referenz auf die Liste der Elemente, die nur in @arr2 enthalten sind.

$bothA:

Referenz auf die Liste der Elemente, die sowohl in @arr1 als auch in @arr2 enthalten sind.

Die drei Ergebnislisten sind als Mengen zu sehen: Jedes Element taucht in einer der drei Listen höchstens einmal auf, auch wenn es in den Eingangslisten mehrfach vorkommt.

Die gelieferten Arrays sind auf die Klasse geblesst.

Example

  • Verwalte Objekte auf Datenbank

    Die Methode ist nützlich, wenn eine Menge von Objekten auf einer Datenbank identisch zu einer Menge von Elementen einer Benutzerauswahl gehalten werden soll. Die Objekte werden durch ihre Objekt-Id identifiziert. Die Liste der Datenbankobjekte sei @idsDb und die Liste der Objekte der Benutzerauswahl sei @idsUser. Dann liefert der Aufruf

      ($idsNew,$idsDel) = $idsUserA->different(\@idsDb);

    mit @$idsNew die Liste der zur Datenbank hinzuzufügenden Objekte und mit @$idsDel die Liste der von der Datenbank zu entfernenden Objekte. Die Liste der identischen Objekte wird hier nicht benötigt.

  • Prüfe zwei Arrays auf Identiät

    Prüfe, ob zwei Arrays die gleichen Elemente enthalten, aber nicht unbedingt in der gleichen Reihenfolge:

      ($only1,$only2) = $arr1->different(\@arr2);
      if (!@$only1 && !@$only2) {
          # @$arr1 und @$arr2 enthalten die gleichen Elemente
      }

decode() - Dekodiere Array

Synopsis

  $arr->decode($encoding);
  $class->decode(\@arr,$encoding);

Description

Dekodiere die Elemente des Arrays gemäß Encoding $encoding.

exists() - Teste, ob Element existiert

Synopsis

  $bool = $arr->exists($str);
  $bool = $class->exists(\@arr,$str);

Description

Durchsuche $arr nach Element $str. Kommt $str in $arr vor, liefere "wahr", sonst "falsch". Vergleichsoperator ist eq.

extractKeyVal() - Extrahiere Paar, liefere Wert

Synopsis

  $val = $arr->extractKeyVal($key);
  $val = $arr->extractKeyVal($key,$step);
  $val = $class->extractKeyVal(\@arr,$key);
  $val = $class->extractKeyVal(\@arr,$key,$step);

Alias

extractPair()

Description

Durchsuche @arr nach Element $key und liefere das folgende Element $val. Beide Elemente werden aus @arr entfernt. Kommt $key in @arr nicht vor, liefere undef und lasse @arr unverändert. Vergleichsoperator ist eq. Per Default wird das Array paarweise durchsucht, d.h. der Defaultwert für $step ist 2. Wird $step auf 1 gesetzt, kann jedes Element den gesuchten $key enthalten.

eq() - Vergleiche Arrays per eq

Synopsis

  $bool = $arr->eq(\@arr);
  $bool = $class->eq(\@arr1,\@arr2);

Description

Vergleiche @arr1 und @arr2 elementweise per eq. Liefere "wahr", wenn alle Elemente identisch sind, andernfalls "falsch".

Sind zwei Elemente undef, gelten sie als identisch.

findPairValue() - Liefere Wert zu Schlüssel

Synopsis

  $val = $arr->findPairValue($key);
  $val = $class->findPairValue(\@arr,$key);

Returns

Wert oder undef

Description

Durchsuche $arr paarweise nach Element $key. Kommt es vor, liefere dessen Wert. Kommt es nicht vor, liefere undef. Vergleichsoperator ist eq.

index() - Suche Element

Synopsis

  $i = $arr->index($val);
  $i = $class->index(\@arr,$val);

Description

Durchsuche @arr vom Anfang her nach Element $val und liefere dessen Index zurück. Kommt $str in @arr nicht vor, liefere -1. Vergleichsoperator ist eq.

last() - Liefere letztes Element

Synopsis

  $e = $arr->last;
  $e = $class->last(\@arr);

maxLength() - Länge des längsten Elements

Synopsis

  $l = $arr->maxLength;
  $l = $class>maxLength(\@arr);

Description

Ermittele die Länge des längsten Arrayelements und liefere diese zurück.

pick() - Liefere Elemente nach Position heraus

Synopsis

  $arr2 | @arr = $class->pick(\@arr,$n,$m);
  $arr2 | @arr = $class->pick(\@arr,$n);
  $arr2 | @arr = $arr->pick($n,$m);
  $arr2 | @arr = $arr->pick($n);

Description

Picke jedes $n-te Array-Element ab Positon $m heraus, bilde aus diesen Elementen ein neues Array und liefere dieses zurück.

push() - Füge Element am Ende hinzu

Synopsis

  $arr->push($e);
  $class->push(\@arr,$e);

select() - Selektiere Array-Elemente

Synopsis

  $arr2|@arr2 = $arr->select($test);
  $arr2|@arr2 = $class->select(\@arr,$test);

Description

Wende Test $test auf alle Arrayelemente an und liefere ein Array mit den Elementen zurück, die den Test erfüllen.

Folgende Arten von Tests sind möglich:

Regex qr/REGEX/

Wende Regex-Test auf jedes Element an.

Code-Referenz sub { CODE }

Wende Subroutine-Test auf jedes Element an. Als erster Parameter wird das zu testende Element übergeben. Die Subroutine muss einen boolschen Wert liefern.

shuffle() - Verwürfele Array-Elemente

Synopsis

  $arr->shuffle;
  $arr->shuffle($factor);
  $class->shuffle(\@arr);
  $class->shuffle(\@arr,$factor);

Arguments

@arr

Das zu mischende Array.

$factor (Default: 100)

Faktor für die Anzahl der Vertauschungsoperationen. Es werden Arraygröße * $factor Vertauschungsoperationen ausgeführt.

Description

Mische die Elemente des Array @arr, d.h. bringe sie in eine zufällige Reihenfolge. Die Operation wird in-place ausgeführt.

Die Methode liefert keinen Wert zurück.

sort() - Sortiere Elemente alphanumerisch

Synopsis

  $arr | @arr = $arr->sort;
  $arr | @arr = $class->sort(\@arr);

Description

Sortiere die Elemente des Array alphanumerisch.

Im Skalar-Kontext sortiere die Elemente "in place" und liefere die Array-Referenz zurück (Method-Chaining).

Im List-Kontext liefere die Elemente sortiert zurück, ohne den Inhalt des Array zu verändern.

toHash() - Erzeuge Hash aus Array

Synopsis

  %hash | $hashH = $arr->toHash;
  %hash | $hashH = $arr->toHash($val);
  %hash | $hashH = $class->toHash(\@arr);
  %hash | $hashH = $class->toHash(\@arr,$val);

Arguments

@$arr, @arr

Array.

$val (Default: 1)

Wert.

Returns

Hash. Im Skalarkontext wird eine Referenz auf den Hash geliefert.

Description

  Erzeuge aus Array @$arr bzw. @arr einen Hash mit den Werten des Array
  als Schlüssel und dem Wert $val als deren Werte und liefere diesen zurück.
  Ist $val nicht angegeben, werden alle Werte des Hash auf 1 gesetzt.

Numerische Operationen

gcd() - Größter gemeinsamer Teiler

Synopsis

  $gcd = $arr->%METHOD;
  $gcd = $class->gcd(\@arr);

Description

Berechne den größten gemeinsamen Teiler (greatest common divisor) der natürlichen Zahlen in Array @$arr bzw. @arr und liefere diesen zurück. Ist das Array leer, wird undef geliefert. Enthält das Array nur ein Element, wird dessen Wert geliefert.

min() - Ermittele numerisches Minimum

Synopsis

  $min = $arr->min;
  $min = $class->min(\@arr);

Description

Ermittele die kleinste Zahl und liefere diese zurück. Enthält $arr keine Elemente, liefere undef.

max() - Ermittele numerisches Maximum

Synopsis

  $max = $arr->max;
  $max = $class->max(\@arr);

Description

Ermittele die größte Zahl und liefere diese zurück. Enthält $arr keine Elemente, liefere undef.

minMax() - Ermittele numerisches Minimum und Maximum

Synopsis

  ($min,$max) = $arr->minMax;
  ($min,$max) = $class->minMax(\@arr);

Description

Ermittele die kleinste und die größte Zahl und liefere die beiden Werte zurück. Enthält $arr keine Elemente, wird jeweils undef geliefert.

meanValue() - Berechne Mittelwert

Synopsis

  $x = $arr->meanValue;
  $x = $class->meanValue(\@arr);

Description

Berechne das Arithmetische Mittel und liefere dieses zurück. Enthält $arr keine Elemente, liefere undef.

standardDeviation() - Berechne Standardabweichung

Synopsis

  $x = $arr->standardDeviation;
  $x = $class->standardDeviation(\@arr);

Description

Berechne die Standardabweichung und liefere diese zurück. Enthält $arr keine Elemente, liefere undef.

variance() - Berechne Varianz

Synopsis

  $x = $arr->variance;
  $x = $class->variance(\@arr);

Description

Berechne die Varianz und liefere diese zurück. Enthält das Array keine Elemente, liefere undef.

median() - Ermittele den Median

Synopsis

  $x = $arr->median;
  $x = $class->median(\@arr);

Description

Ermittele den Median und liefere diesen zurück. Enthält das Array keine Elemente, liefere undef.

Dump/Restore

dump() - Erzeuge einzeilige, externe Repräsentation

Synopsis

  $str = $arr->dump;
  $str = $arr->dump($colSep);
  $str = $class->dump(\@arr);
  $str = $class->dump(\@arr,$colSep);

Description

Liefere eine einzeilige, externe Repräsentation für Array $arr bzw. @arr im Format

  elem0|elem1|...|elemN

Die Array-Elemente werden durch "|" (bzw. $colSep) getrennt. In den Elementen werden folgende Wandlungen vorgenommen:

  undef    -> '' (undef wird zu Leerstring)
  \        -> \\ (Backslash wird verdoppelt)
  $colSep  -> \!
  LF       -> \n
  CR       -> \r

restore() - Wandele einzeilige, externe Repräsentation in Array

Synopsis

  $arr = $class->restore($str);
  $arr = $class->restore($str,$colSep);

Description

Wandele einzeilige, externe Array-Repräsentation (siehe Methode dump()) in ein Array-Objekt und liefere dieses zurück.

VERSION

1.164

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2019 Frank Seitz

LICENSE

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