Array Generation Functions - Complete Implementation

Last Updated: 2025-12-29

Overview

Implemented all IDL/GDL array generation functions with full multi-dimensional support (D1-D8) and keyword arguments (START, INCREMENT).

Implemented Functions

1. FINDGEN - Floating Point Array Generation 

Result = FINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates floating-point arrays with sequential values starting from 0.0.

Examples:

arr = FINDGEN(5)       ; [0.0, 1.0, 2.0, 3.0, 4.0]
arr = FINDGEN(3, 4)    ; 3×4 array with values 0-11
arr = FINDGEN(2, 2, 2) ; 2×2×2 array with values 0-7

2. DINDGEN - Double Precision Array Generation 

Result = DINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Identical to FINDGEN (since XDL uses f64 by default).

3. BINDGEN - Byte Integer Array Generation 

Result = BINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates byte arrays with values 0-255.

Examples:

arr = BINDGEN(6)    ; [0, 1, 2, 3, 4, 5]
arr = BINDGEN(3, 4) ; 3×4 byte array

4. CINDGEN - Complex Integer Array Generation 

Result = CINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates complex arrays with real part incrementing from 0, imaginary part = 0. Values are interleaved: [real0, imag0, real1, imag1, …]

Examples:


arr = CINDGEN(3)  ; [0+0i, 1+0i, 2+0i]
                  ; Stored as: [0.0, 0.0, 1.0, 0.0, 2.0, 0.0]

5. DCINDGEN - Double Complex Array Generation 

Result = DCINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Double precision complex array generation. Same as CINDGEN in XDL.

6. INDGEN - Integer Array Generation 

Result = INDGEN(D1[, ..., D8] [, /BYTE | , /COMPLEX | , /DCOMPLEX | , /DOUBLE | , /FLOAT |
                INCREMENT=value | , /L64 | , /LONG | , /STRING | , /UINT | , /UL64 | , /ULONG]
               [, START=value] [, TYPE=value])

Generates integer arrays with sequential values.

Type flags (not yet implemented - pending evaluator support):

  • /BYTE, /COMPLEX, /DCOMPLEX, /DOUBLE, /FLOAT
  • /L64, /LONG, /STRING, /UINT, /UL64, /ULONG
  • TYPE=value - specify type code

Examples:

arr = INDGEN(5)     ; [0, 1, 2, 3, 4]
arr = INDGEN(2, 3)  ; 2×3 array with values 0-5

7. LINDGEN - Long Integer Array Generation 

Result = LINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates long integer arrays. Same as INDGEN in XDL implementation.

8. L64INDGEN - 64-bit Long Integer Array Generation 

Result = L64INDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates 64-bit long integer arrays.

9. SINDGEN - String Array Generation 

Result = SINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates string arrays with string representations of integers.

Note: Currently returns numeric array. Full string array support pending.

10. UINDGEN - Unsigned Integer Array Generation 

Result = UINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates unsigned integer arrays.

11. UL64INDGEN - Unsigned 64-bit Long Array Generation 

Result = UL64INDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates unsigned 64-bit long integer arrays.

12. ULINDGEN - Unsigned Long Integer Array Generation 

Result = ULINDGEN(D1 [, ..., D8] [, INCREMENT=value] [, START=value])

Generates unsigned long integer arrays.

Implementation Details

Architecture

Helper Function

Created extract_dimensions() helper function to reduce code duplication:

  • Validates 1-8 dimension arguments
  • Ensures all dimensions are non-negative
  • Supports all numeric types (Long, Int, Byte, Float, Double)

Return Types

  • 1D arrays: Returns XdlValue::Array (backward compatible)
  • Multi-dimensional: Returns XdlValue::MultiDimArray with shape metadata

Location

  • Implementation: xdl-stdlib/src/math.rs (lines 367-632)
  • Registration: xdl-stdlib/src/lib.rs (lines 227-238)

Algorithm

All functions follow this pattern:

  1. Extract dimensions using extract_dimensions()
  2. Calculate total size: product of all dimensions
  3. Generate sequential values: start + (index × increment)
  4. Return appropriate type based on number of dimensions

Testing

Test File

Created test_all_indgen.xdl with 16 comprehensive tests covering:

  • 1D array generation
  • Multi-dimensional arrays (2D, 3D)
  • All function variants
  • Math operations on generated arrays
  • Complex array generation

Results

✅ All 16 tests passed successfully ✅ Backward compatibility maintained ✅ Math operations work correctly

✅ Recently Implemented Features (2025-12-29)

1. Keyword Arguments: START and INCREMENT ✅

Status: COMPLETE

All array generation functions now support START and INCREMENT keyword arguments:

arr = FINDGEN(5, START=10)           ; [10.0, 11.0, 12.0, 13.0, 14.0]
arr = FINDGEN(5, INCREMENT=2)        ; [0.0, 2.0, 4.0, 6.0, 8.0]
arr = FINDGEN(5, START=5, INCREMENT=3) ; [5.0, 8.0, 11.0, 14.0, 17.0]
arr = INDGEN(5, START=100)           ; [100, 101, 102, 103, 104]

2. MAKE_ARRAY Function ✅

Status: COMPLETE

The flexible array creation function is now fully implemented:

; Create array with dimensions
arr = MAKE_ARRAY(5)                   ; [0.0, 0.0, 0.0, 0.0, 0.0]
arr = MAKE_ARRAY(3, 4)                ; 3x4 array of zeros

; Use VALUE keyword to fill with specific value
arr = MAKE_ARRAY(5, VALUE=42)         ; [42.0, 42.0, 42.0, 42.0, 42.0]

; Use /INDEX flag to fill with index values (like INDGEN)
arr = MAKE_ARRAY(5, /INDEX)           ; [0.0, 1.0, 2.0, 3.0, 4.0]

; Use DIMENSION keyword for dimension vector
arr = MAKE_ARRAY(DIMENSION=[2,3], /INDEX)  ; 2x3 array with index values

3. SINDGEN String Arrays ✅

Status: COMPLETE

SINDGEN now returns proper string arrays:

arr = SINDGEN(5)                      ; ["0", "1", "2", "3", "4"]
arr = SINDGEN(3, START=10)            ; ["10", "11", "12"]

Remaining Enhancements

INDGEN Type Flags

Type selection flags like /BYTE, /FLOAT, etc. are documented but not yet fully implemented. These would allow specifying the output data type explicitly.

Compatibility Matrix

Function Multi-Dim START INCREMENT Type Flags Status
FINDGEN ✅ ✅ ✅ N/A Complete
DINDGEN ✅ ✅ ✅ N/A Complete
BINDGEN ✅ ✅ ✅ N/A Complete
CINDGEN ✅ ✅ ✅ N/A Complete
DCINDGEN ✅ ✅ ✅ N/A Complete
INDGEN ✅ ✅ ✅ ⏳ Complete
LINDGEN ✅ ✅ ✅ N/A Complete
L64INDGEN ✅ ✅ ✅ N/A Complete
SINDGEN ✅ ✅ ✅ N/A Complete
UINDGEN ✅ ✅ ✅ N/A Complete
UL64INDGEN ✅ ✅ ✅ N/A Complete
ULINDGEN ✅ ✅ ✅ N/A Complete
MAKE_ARRAY ✅ ✅ ✅ ⏳ Complete

Legend:

  • ✅ Implemented
  • ⏳ Pending (type flags not yet implemented)
  • N/A: Not applicable for this function

Code Quality

Build Status

✅ Clean build with no warnings ✅ All tests passing ✅ No breaking changes

Code Structure

  • Modular design with helper functions
  • Consistent error handling
  • Comprehensive documentation
  • Type-safe implementation

Files Modified

  1. xdl-stdlib/src/math.rs
    • Added extract_dimensions() helper (lines 367-423)
    • Updated findgen() to use helper (lines 425-465)
    • Added 11 new array generation functions (lines 481-632)
    • Removed duplicate old indgen() implementation
  2. xdl-stdlib/src/lib.rs
    • Registered 10 new functions (lines 229-238)
  3. docs/FINDGEN_UPDATE.md
    • Initial FINDGEN update documentation
  4. docs/ARRAY_GENERATION_FUNCTIONS.md
    • This comprehensive documentation

Migration Guide

For Existing Code

No changes required! All existing code continues to work:

; All of these still work exactly as before
arr1 = FINDGEN(10)
arr2 = DINDGEN(5)
arr3 = INDGEN(8)

For New Code

Take advantage of multi-dimensional support:

; Create multi-dimensional arrays directly
matrix = FINDGEN(4, 5)      ; 4×5 matrix
cube = INDGEN(3, 3, 3)      ; 3×3×3 cube
hypercube = LINDGEN(2,2,2,2); 4D array

Performance

All functions:

  • O(n) time complexity where n = product of dimensions
  • Memory allocation proportional to array size
  • Efficient sequential value generation
  • No unnecessary copies

Summary

✅ 12 functions fully implemented with multi-dimensional support ✅ Helper function reduces code duplication ✅ Comprehensive testing with 16 test cases ✅ Full documentation with examples ✅ Backward compatible - no breaking changes ✅ Clean build - no warnings or errors

This implementation provides a solid foundation for IDL/GDL compatibility in XDL’s array generation capabilities.