NAME
AmberDB::Array - Array, matrix manipulation, and set operations utility
SYNOPSIS
# 1. Direct usage via AmberDB instance ($adb inherits AmberDB::Array):
my @unique = $adb->array_nodup(@raw_list);
my $common_ids = $adb->array_crop($list1, $list2, $list3);
my @sorted = $adb->array_sort('num', 'desc', 0, @records);
my $cloned = $adb->deep_copy($nested_data);
# 2. Standalone usage:
use AmberDB::Array;
my $array_util = AmberDB::Array->new();
my @unique = $array_util->array_nodup(@raw_list);DESCRIPTION
AmberDB::Array provides a rich set of utility methods for array manipulation, set operations (union, intersection, difference), matrix transformations, filtering, multi-dimensional array sorting, and deep copying.
Inheritance Note: AmberDB inherits from AmberDB::Array via use parent. All methods documented below can be invoked directly on any $adb instance (e.g. $adb->array_nodup(...)), as well as on standalone AmberDB::Array objects.
METHODS
array_nodup(@list)
Removes duplicate elements from @list while strictly preserving original insertion order.
my @tags = $adb->array_nodup("perl", "db", "perl", "nosql", "db");
# => ("perl", "db", "nosql")array_crop($arr1, $arr2, ...)
Computes the mathematical intersection of two or more array references. Returns an array reference containing only elements present in all provided lists.
my $list1 = [ "apple", "banana", "cherry" ];
my $list2 = [ "banana", "cherry", "date" ];
my $common = $adb->array_crop($list1, $list2);
# => [ "banana", "cherry" ]array_add($arr1, $arr2, ...)
Merges multiple array references into a single unified array reference without duplicates (union), preserving appearance order.
my $merged = $adb->array_add([ 1, 2, 3 ], [ 3, 4, 5 ], [ 5, 6 ]);
# => [ 1, 2, 3, 4, 5, 6 ]array_punch($primary_arr, @other_arrs)
Subtracts all elements found in subsequent array references (@other_arrs) from the primary array reference ($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")array_substr($primary_arr, @other_arrs)
Removes elements of subsequent array references from $primary_arr, returning an array reference of the difference. Unlike 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" ]array_filter($predicate, @arrays)
Filters an array using a 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)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" ]array_compare($arr1, $arr2)
Performs an element-by-element string comparison between two array references. Returns 1 if both arrays are identical in length and values, 0 otherwise.
my $same = $adb->array_compare([ 1, "test" ], [ 1, "test" ]); # 1
my $diff = $adb->array_compare([ 1, "test" ], [ 2, "test" ]); # 0array_sublist($chunk_size, @records)
Splits a flat list into an array of sub-lists (chunks), each containing $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"] )array_size(@lines)
Calculates the dimensions of a list of array references (matrix). Returns a 2-element list: ($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)array_pick(\@indexes, @record)
Extracts and returns only the fields at the given 0-based index positions from @record.
my @selected = $adb->array_pick([ 0, 2 ], "ID101", "SecretKey", "PublicTitle");
# => ("ID101", "PublicTitle")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" ] } });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 } }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);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" ] )array_sort($type, $direct, $field, @records)
Versatile array and matrix sorting engine. Supports scalar lists as well as array-of-arrays (AoA) records.
$type:'num'(numeric<=>) or'ascii'(stringcmp). Set toundefor'auto'for automatic detection.$direct:0,'asc', orundeffor ascending;1,'desc','reverse', or'-'for descending.$field: Column/block index (0-based) when sorting array references. If sorting scalars, passundef.@records: List of scalars or array references to sort (can also be passed as a single\@recordsarrayref).
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 ]
);
my @by_name = $adb->array_sort('ascii', 'asc', 1, @records);
# => ([102, "Apple", 20], [103, "Mango", 80], [101, "Zebra", 50])
# 3. Sorting records by column index 2 numeric descending
my @by_price = $adb->array_sort('num', 'desc', 2, @records);AUTHOR
Maruf Cetin <marufcetin@gmail.com>
LICENSE AND COPYRIGHT
Copyright (C) 2018-2026 Maruf Cetin.
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.