view release on metacpan or  search on metacpan

lib/AmberDB/Array.pm  view on Meta::CPAN

  my $merged = $adb->array_add([ 1, 2, 3 ], [ 3, 4, 5 ], [ 5, 6 ]);
  # => [ 1, 2, 3, 4, 5, 6 ]

=head2 array_punch($primary_arr, @other_arrs)

Subtracts all elements found in subsequent array references (C<@other_arrs>) from the primary array reference (C<$primary_arr>). Returns an array of remaining elements with duplicates removed.

  my $primary = [ "a", "b", "c", "d", "e" ];
  my $exclude = [ "b", "d" ];
  my @remaining = $adb->array_punch($primary, $exclude);
  # => ("a", "c", "e")

=head2 array_substr($primary_arr, @other_arrs)

Removes elements of subsequent array references from C<$primary_arr>, returning an array reference of the difference. Unlike C<array_punch>, preserves duplicates within the primary list if not present in the subtractors.

  my $diff = $adb->array_substr([ "a", "b", "c", "a" ], [ "b" ]);
  # => [ "a", "c", "a" ]

=head2 array_filter($predicate, @arrays)

Filters an array using a C<CODE> reference predicate. Executes fast and safe in-memory filtering without eval overhead.

  my @evens = $adb->array_filter(sub { $_[0] % 2 == 0 }, 1, 2, 3, 4, 5, 6);
  # => (2, 4, 6)

=head2 array_substrno($arraydata, @indices_to_remove)

Removes elements at specified 0-based indices from an array reference.

  my $data = [ "first", "second", "third", "fourth" ];
  my $sub  = $adb->array_substrno($data, 1, 3);
  # => [ "first", "third" ]

=head2 array_compare($arr1, $arr2)

Performs an element-by-element string comparison between two array references. Returns C<1> if both arrays are identical in length and values, C<0> otherwise.

  my $same = $adb->array_compare([ 1, "test" ], [ 1, "test" ]); # 1
  my $diff = $adb->array_compare([ 1, "test" ], [ 2, "test" ]); # 0

=head2 array_sublist($chunk_size, @records)

Splits a flat list into an array of sub-lists (chunks), each containing C<$chunk_size> items (valid chunk sizes: 2, 3, 4, 6, 12; default is 2).

  my @matrix = $adb->array_sublist(2, "a", "b", "c", "d");
  # => ( ["a", "b"], ["c", "d"] )

=head2 array_size(@lines)

Calculates the dimensions of a list of array references (matrix). Returns a 2-element list: C<($max_row_index, $max_column_index)>.

  my ($max_row, $max_col) = $adb->array_size( [1, 2, 3], [4, 5] );
  # => (1, 2)  # 2 rows (0..1), 3 columns (0..2)

=head2 array_pick(\@indexes, @record)

Extracts and returns only the fields at the given 0-based index positions from C<@record>.

  my @selected = $adb->array_pick([ 0, 2 ], "ID101", "SecretKey", "PublicTitle");
  # => ("ID101", "PublicTitle")

=head2 deep_copy($data)

Recursively clones nested Perl data structures (hash references, array references, and scalar values) to produce an independent copy.

  my $copy = $adb->deep_copy({ user => { roles => [ "admin", "editor" ] } });

=head2 hash_diff($hash1, $hash2)

Non-destructively compares two hash references and returns a hash reference containing the keys unique to each input hash. The original hash structures are preserved unmodified.

  my $h1 = { a => 1, b => 2, c => 3 };
  my $h2 = { b => 2, c => 3, d => 4 };
  my $diff = $adb->hash_diff($h1, $h2);
  # => { hash1 => { a => 1 }, hash2 => { d => 4 } }

=head2 array_shuffle(@array)

Shuffles the order of elements randomly using the Fisher-Yates algorithm and returns the new list.

  my @randomized = $adb->array_shuffle(1, 2, 3, 4, 5);

=head2 inverse_matrix(@lines)

Transposes a two-dimensional matrix (swaps rows and columns).

  my @transposed = $adb->inverse_matrix(
      [ "r1c1", "r1c2" ],
      [ "r2c1", "r2c2" ]
  );
  # => ( [ "r1c1", "r2c1" ], [ "r1c2", "r2c2" ] )

=head2 array_sort($type, $direct, $field, @records)

Versatile array and matrix sorting engine. Supports scalar lists as well as array-of-arrays (AoA) records.

=over 4

=item * C<$type>: C<'num'> (numeric C<E<lt>=E<gt>>) or C<'ascii'> (string C<cmp>). Set to C<undef> or C<'auto'> for automatic detection.

=item * C<$direct>: C<0>, C<'asc'>, or C<undef> for ascending; C<1>, C<'desc'>, C<'reverse'>, or C<'-'> for descending.

=item * C<$field>: Column/block index (0-based) when sorting array references. If sorting scalars, pass C<undef>.

=item * C<@records>: List of scalars or array references to sort (can also be passed as a single C<\@records> arrayref).

=back

Context-aware: Returns a list in list context or an array reference in scalar context.

  # 1. Simple numeric descending sort
  my @sorted_nums = $adb->array_sort('num', 'desc', undef, 10, 5, 20, 1);
  # => (20, 10, 5, 1)

  # 2. Sorting records by column index 1 ascending
  my @records = (
      [ 101, "Zebra", 50 ],
      [ 102, "Apple", 20 ],
      [ 103, "Mango", 80 ]