Jacobi.ArrayOperators 1.2.1

Array Operators

This library provides a set of operator extension for Array, IEnumerable<T> and ICollection<T> types.

This will allow you to do 'array arithmetic' in a more natural way.

Key Advantages

1. Readability: Mathematical operations look like actual math notation
2. Performance: Batch operations instead of loops
3. Maintainability: Less boilerplate code
4. Safety: Type-safe generic constraints ensure valid operations
5. Expressiveness: Natural syntax for array/vector mathematics

Usage

Add the Jacobi.ArrayOperators nuget package to your project.

using Jacobi.ArrayOperators;

Here are some examples of array (IEnumerable<T>) arithmetic:

int[] arr = [1, 2, 3];
// this works for any IEnumerable<T>
var result = arr * 5;
// result is [5, 10, 15]

int[] arr1 = [1, 2, 3];
int[] arr2 = [6, 8, 3];
var result = arr + arr2;
// result is [7, 10, 6]

Array specific operations:

int[] arr = [1, 2, 3];
arr += 5;
// arr is now [6, 7, 8]

When Arrays are of different lengths, only the calculated items are returned (shortest array length):

IEnumerable<int> arr1 = [1, 2, 3];
IEnumerable<int> arr2 = [4, 5, 6, 7];
var result = arr1 + arr2;
// result is [5, 7, 9]

Compare two arrays (IEnumerable<T>):

int[] arr1 = [1, 2, 3];
int[] arr2 = [1, 2, 3];
if (arr1 == arr2)
{
    // this block will be executed
}

int[] arr1 = [1, 2, 3]
int[] arr2 = [6, 8, 3]
if (arr1 > arr2)
{
    // this block will not be executed
}

Operator Extensions Reference

IEnumerbale<T> and Ilist<T> return types are implemented by List<T>.

Arithmetic Operators

Scalar Arithmetic Operators

Mutating Arithmetic Operators (In-place)

Logical Operators

Note that the && and || operators cannot be overloaded.

Bitwise Operators

Comparison Operators

Notes:

• Element-wise operations stop at the length of the shorter sequence
• In-place operators modify the original array/collection/list
• IList<T> operators use optimized indexed access
• ICollection<T> operators work with non-indexed collections (e.g., HashSet<T>)
• Requires types implementing appropriate System.Numerics interfaces
• BitArray operations maintain minimum length between operands
• BitVector32 works with 32-bit integer data

Method Extensions Reference

T is IFloatingPoint<T>

T is INumber<T>

Potential Use Cases

The Jacobi.ArrayOperators library enables powerful array-based computations across various domains. Here are practical use cases:

1. Scientific Computing & Data Analysis

Statistical Calculations

// Normalize data (z-score normalization)
double[] data = [10.5, 12.3, 9.8, 11.2, 13.1];
double mean = data.Average();
double stdDev = CalculateStdDev(data);
var normalized = (data - mean) / stdDev;

Vector Operations

// Calculate dot product using element-wise multiplication
double[] vector1 = [1.0, 2.0, 3.0];
double[] vector2 = [4.0, 5.0, 6.0];
var dotProduct = (vector1 * vector2).Sum(); // 32.0

2. Image Processing

Brightness Adjustment

// Increase brightness by 20 units across all pixels
byte[] pixels = GetImagePixels();
pixels += 20;

Image Blending

// Blend two images with 50% opacity each
byte[] image1 = GetImage1Pixels();
byte[] image2 = GetImage2Pixels();
var blended = (image1 + image2) / 2;

Apply Masks

// Apply binary mask to filter pixels
bool[] mask = GetMask();
byte[] pixels = GetPixels();
var filtered = mask ? pixels : default; // Using true operator

3. Signal Processing

Apply Gain/Attenuation

// Amplify audio signal by 2x
float[] audioSamples = LoadAudioData();
audioSamples *= 2.0f;

Signal Mixing

// Mix two audio channels
float[] leftChannel = GetLeftChannel();
float[] rightChannel = GetRightChannel();
var mixedMono = (leftChannel + rightChannel) / 2.0f;

4. Financial Calculations

Portfolio Analysis

// Calculate daily returns
decimal[] prices = [100m, 102m, 101m, 105m];
decimal[] previousPrices = [99m, 100m, 102m, 101m];
var returns = (prices - previousPrices) / previousPrices * 100;

Risk-Weighted Assets

// Apply risk weights to asset values
decimal[] assetValues = [1000m, 2000m, 1500m];
decimal[] riskWeights = [0.5m, 0.75m, 1.0m];
var riskWeightedAssets = assetValues * riskWeights;

5. Game Development

Bulk Transform Operations

// Scale all enemy positions
float[] enemyPositions = [10.0f, 20.0f, 30.0f];
enemyPositions *= scaleFactor;

Damage Calculations

// Apply armor reduction to damage values
int[] damageValues = [50, 75, 100];
float[] armorReduction = [0.8f, 0.8f, 0.8f];
var finalDamage = damageValues * armorReduction;

Batch Health Updates

// Apply healing to multiple entities
int[] healthValues = [50, 75, 30];
healthValues += healingAmount;

6. Machine Learning & AI

Feature Scaling

// Min-max normalization
double[] features = [100, 200, 150, 300];
double min = features.Min();
double max = features.Max();
var scaled = (features - min) / (max - min);

Activation Functions

// Apply ReLU activation (using comparison)
double[] values = [-1.0, 2.0, -3.0, 4.0];
var activated = values > 0 ? values : 0; // Simplified concept

Gradient Descent Updates

// Update weights
double[] weights = [0.5, 0.3, 0.8];
double learningRate = 0.01;
double[] gradients = [0.1, -0.2, 0.15];
weights -= gradients * learningRate;

7. Physics Simulations

Force Calculations

// F = m * a
double[] masses = [10.0, 15.0, 20.0];
double[] accelerations = [2.0, 1.5, 3.0];
var forces = masses * accelerations;

Velocity Updates

// Update velocities with acceleration
double[] velocities = [5.0, 10.0, 15.0];
double deltaTime = 0.016; // ~60 FPS
velocities += accelerations * deltaTime;

8. Bitwise Operations for Flags/Permissions

Combine Permission Sets

// Merge permission flags
int[] userPermissions = [0b0001, 0b0010, 0b0100];
int[] rolePermissions = [0b0010, 0b0100, 0b1000];
var combinedPermissions = userPermissions | rolePermissions;

Apply Masks

// Extract specific bits
int[] values = [0b11111111, 0b10101010, 0b11110000];
int mask = 0b00001111;
var masked = values & mask;

9. Data Validation & Filtering

Boolean Mask Operations

// Check if all values meet criteria
bool[] validations = CheckDataValidity();
if (validations) // Uses true operator
{
    Console.WriteLine("All data is valid!");
}

Logical Combinations

// Combine multiple validation results
bool[] check1 = [true, false, true];
bool[] check2 = [true, true, false];
var allPassed = check1 & check2; // [true, false, false]

10. Time Series Analysis

Moving Averages

// Simple moving average calculation
double[] window1 = GetWindow(data, 0, 5);
double[] window2 = GetWindow(data, 1, 5);
var difference = window2 - window1;

Percentage Changes

// Calculate period-over-period changes
decimal[] currentPeriod = [100m, 110m, 105m];
decimal[] previousPeriod = [95m, 105m, 100m];
var percentChange = ((currentPeriod - previousPeriod) / previousPeriod) * 100;

Future Enhancements

• Create the return type based on the (first) parameter type.
• Implement other Math functions.

Implement support for types:

• Span<T>
• ReadOnlySpan<T>
• IReadOnlyList<T>
• ArraySegment<T>
• ImmutableArray<T>
• ImmutableList<T>