Working with data arrays is fundamental in MQL4, whether processing historical price data, managing indicator buffers, or handling collections of trading objects. Often, you need a function to perform some computation or data retrieval and return a result that is inherently an array. However, unlike some modern languages or even MQL5, MQL4 has specific limitations regarding directly returning arrays from functions.
Understanding the Limitations of Direct Array Returns in MQL4
MQL4 functions primarily operate by passing fundamental data types (like int, double, bool, string) by value. When you pass an array to a function, MQL4 also passes it by value, meaning a copy of the array is created within the function’s scope. Any modifications made to the array inside the function do not affect the original array outside of it.
The critical limitation is that MQL4 functions cannot directly return an array as a return type like double[] MyFunction(...). This design requires developers to use alternative methods to achieve the effect of returning array data from a function.
Why Returning Arrays is Important in MQL4 Programming
Despite the limitations, the need to have a function supply an array of data is frequent and necessary for structured programming. Encapsulating logic that produces an array within a function promotes code reusability, modularity, and readability.
Examples include functions that:
- Calculate a series of indicator values over a specific range.
- Filter a list of open orders or positions based on criteria.
- Parse a string into an array of substrings.
- Generate a sequence of numbers or price levels.
- Retrieve historical data for a custom analysis period.
Without methods to effectively ‘return’ arrays, complex logic would have to reside within a single function or rely on less clean methods like directly manipulating global variables without proper control.
Methods for Returning Arrays in MQL4
Given MQL4’s constraints, developers have devised several patterns to work around the inability to return arrays directly. The most common and practical methods involve modifying data structures that are accessible outside the function’s local scope.
Using Global Arrays as Return Values
This is perhaps the simplest approach conceptually but comes with significant drawbacks, especially in multi-threaded environments or when functions need to be re-entrant.
The idea is to declare an array with global scope. Functions that ‘return’ an array instead populate or modify this global array. The calling code then accesses the data from this predefined global variable.
Mechanism: A globally declared array acts as a shared buffer. Functions write to it, and callers read from it.
Pros: Straightforward to implement for simple cases.
Cons: Poor encapsulation, not thread-safe, difficult to manage in complex EAs or when multiple functions might use the same global array, cannot return arrays of different sizes dynamically without complex logic.
Employing Pointers to Return Arrays
This method involves dynamic memory allocation. A function creates a dynamic array on the heap using the new operator and returns a pointer (the address) to this allocated memory. The caller receives the pointer and can then access the array data.
Mechanism: The function allocates memory, populates the array, and returns the pointer. The caller is responsible for deallocating the memory using ArrayFree() when done to prevent memory leaks.
Pros: Allows returning arrays of dynamic size, better encapsulation than global variables, data is not tied to the function’s stack.
Cons: Requires careful memory management (new and ArrayFree), risk of memory leaks if not managed correctly, pointer usage can be less intuitive for beginners.
Utilizing Structures to Encapsulate and Return Arrays
Structures (struct) in MQL4 can contain arrays as members. While structures are typically passed by value, you can pass a structure by reference to a function. The function then modifies the array member within the referenced structure instance. Alternatively, the function could return a structure instance by value, although this copies the entire structure, including the array, which can be inefficient for large arrays.
Mechanism: Define a structure containing the array. Pass an instance of this structure by reference (struct_name& variable_name) to the function. The function modifies the array inside the referenced structure.
Pros: Good encapsulation, combines related data, clear intent when passing data by reference, generally cleaner than pointers for data management.
Cons: Requires defining a structure, passing by value (if not using reference) can be inefficient, arrays within structures often need to be fixed-size unless combined with pointers/dynamic allocation within the structure itself.
Practical Examples and Code Snippets
Let’s illustrate these methods with simple MQL4 code examples.
Example 1: Returning an Array Using a Global Variable
double GlobalDataArray[10]; // Global array
// Function to populate the global array
void PopulateGlobalArray()
{
for(int i = 0; i < ArraySize(GlobalDataArray); i++)
{
GlobalDataArray[i] = MathRand(); // Fill with random values
}
}
// Example usage
int OnInit()
{
PopulateGlobalArray(); // Populate the global array
// Access the 'returned' data from the global array
Print("Data from global array:");
for(int i = 0; i < ArraySize(GlobalDataArray); i++)
{
Print("GlobalDataArray[", i, "] = ", GlobalDataArray[i]);
}
return(INIT_SUCCEEDED);
}
Explanation: The function PopulateGlobalArray doesn’t return anything (void), but it modifies the globally accessible GlobalDataArray. The calling code then reads from this global array.
Example 2: Returning an Array Using Pointers
// Function that returns a pointer to a dynamically allocated array
double* CreateDynamicArray(int size)
{
if (size <= 0)
{
Print("Error: Invalid size for dynamic array.");
return(NULL); // Return NULL on error
}
double tempArray[];
ArrayResize(tempArray, size);
if (ArraySize(tempArray) != size) // Check if resize was successful
{
Print("Error: Failed to allocate memory for dynamic array.");
return(NULL);
}
// Populate the dynamic array
for(int i = 0; i < size; i++)
{
tempArray[i] = MathRand(); // Fill with random values
}
// NOTE: MQL4 ArrayResize internally handles memory allocation similar to 'new'
// and returning the base pointer is implicitly handled when returning dynamic arrays
// declared locally and sized with ArrayResize.
// However, explicit pointer arithmetic and management with new/delete is not
// standard practice for simple dynamic arrays in MQL4 like it might be in C++.
// The cleaner MQL4 way is often to return the sized dynamic array itself,
// but this often results in a copy. The 'pointer' concept is more conceptual
// for how MQL4 manages dynamic arrays internally to allow size changes.
// A more explicit C++ pointer approach in MQL4 is less common for simple cases.
// Let's revise to the more MQL4 idiomatic way which *behaves* like returning data,
// though still subject to copy implications depending on context.
// A more direct pointer return usually involves Low Level Functions or complex structures.
// For typical array data, modifying an array passed by reference is often preferred.
// However, demonstrating the concept of returning an 'address' or reference to data:
// Reverting to the 'pass by reference' pattern which is the practical MQL4 pointer/reference equivalent
// for modifying arrays in a function without relying on globals.
// The 'returning a pointer' idea is more aligned with C++ 'new' and returning the result.
// In MQL4, returning a dynamic array often implies returning a copy.
// The closest to 'returning a pointer' that modifies the original outside scope
// is passing the array *by reference*.
// Let's demonstrate the pass-by-reference method as the practical equivalent
// of letting a function populate memory accessible to the caller without globals.
// (The direct pointer return as in C++ `double* func() { return new double[10]; }`
// is not the standard dynamic array handling paradigm in MQL4).
Print("\n--- Pointer Example (Using Pass by Reference as MQL4 Equivalent) ---");
Print("Note: MQL4 dynamic array behavior often involves copies. Pass-by-reference is a common workaround.");
return(NULL); // Placeholder - see pass-by-reference example below.
}
// Let's provide the practical MQL4 equivalent using pass-by-reference
void PopulateArrayByReference(double& targetArray[], int size)
{
if (size <= 0)
{
Print("Error: Invalid size for reference array.");
ArrayFree(targetArray); // Clear the array
return;
}
ArrayResize(targetArray, size);
if (ArraySize(targetArray) != size)
{
Print("Error: Failed to resize reference array.");
return;
}
// Populate the array passed by reference
for(int i = 0; i < size; i++)
{
targetArray[i] = MathRand(); // Fill with random values
}
}
// Example usage (using pass-by-reference)
int OnStart() // Using OnStart for a simple script
{
Print("\n--- Pointer/Reference Method Example ---");
double myDataArray[]; // Declare dynamic array
// Pass the array by reference to the function
PopulateArrayByReference(myDataArray, 15); // Request size 15
// Check if successful and access the modified array
if (ArraySize(myDataArray) > 0)
{
Print("Data from reference array (size ", ArraySize(myDataArray), "):");
for(int i = 0; i < ArraySize(myDataArray); i++)
{
Print("myDataArray[", i, "] = ", myDataArray[i]);
}
ArrayFree(myDataArray); // IMPORTANT: Free memory when done
}
else
{
Print("Failed to populate or array is empty.");
}
return(0);
}
Explanation: The PopulateArrayByReference function takes a dynamic array by reference (double& targetArray[]). Inside the function, ArrayResize allocates/resizes the memory for this specific array instance, and the loop populates it. Because it’s passed by reference, the modifications happen directly on myDataArray declared in OnStart. ArrayFree is used to release the memory.
Self-correction during thought: The initial idea of a C++ style double* func() { return new double[size]; } returning a raw pointer is not the standard MQL4 dynamic array handling. MQL4’s ArrayResize manages the memory. The closest practical equivalent for modifying caller-owned memory (like returning a pointer allows) without globals is passing the array by reference. The corrected example reflects this common MQL4 pattern.
Example 3: Returning an Array within a Structure
// Define a structure to hold array data
struct ArrayContainer
{
double data[20]; // Fixed size array
int size;
};
// Function that populates an ArrayContainer structure passed by reference
void PopulateStructureArray(ArrayContainer& container)
{
// We can only fill up to the fixed size of the array member
container.size = ArraySize(container.data);
for(int i = 0; i < container.size; i++)
{
container.data[i] = MathRand(); // Fill with random values
}
}
// Function that creates and returns an ArrayContainer structure (passed by value - less common for large arrays)
// Note: Returning by value copies the whole struct
ArrayContainer CreateStructureArray()
{
ArrayContainer container;
// For fixed-size arrays within a struct, size is known
container.size = ArraySize(container.data);
for(int i = 0; i < container.size; i++)
{
container.data[i] = MathRand(); // Fill with random values
}
return(container);
}
// Example usage (using pass-by-reference)
int OnInit()
{
Print("\n--- Structure Method Example (Pass by Reference) ---");
ArrayContainer myContainer;
// Pass the structure by reference to the function
PopulateStructureArray(myContainer);
// Access the data from the structure
Print("Data from structure array (size ", myContainer.size, "):");
for(int i = 0; i < myContainer.size; i++)
{
Print("myContainer.data[", i, "] = ", myContainer.data[i]);
}
return(INIT_SUCCEEDED);
}
// Example usage (using return by value - requires OnStart/OnDeinit context for variables)
/*
int OnStart()
{
Print("\n--- Structure Method Example (Return by Value) ---");
ArrayContainer myContainer = CreateStructureArray(); // Call function and get copy
// Access the data from the structure
Print("Data from structure array (size ", myContainer.size, "):");
for(int i = 0; i < myContainer.size; i++)
{
Print("myContainer.data[", i, "] = ", myContainer.data[i]);
}
return(0);
}
*/
Explanation: The ArrayContainer struct holds the array. PopulateStructureArray takes an instance of this struct by reference and populates its internal data array. This modifies the original myContainer variable in OnInit. The CreateStructureArray function demonstrates returning a struct by value, which works but copies the potentially large array inside.
Best Practices and Considerations
When using these methods to work around MQL4’s array return limitation, consider the following best practices.
Memory Management and Array Size Considerations
- Global Arrays: Size is fixed at compile time. No dynamic memory management needed for the array itself, but managing the data within it across different function calls requires careful synchronization or understanding of execution flow.
- Pointer/Reference Method: With dynamic arrays (
ArrayResize), MQL4 manages the memory allocation. When passing by reference, ensure the caller declares a dynamic array. If explicitly usingnew(less common for simple arrays), the caller must useArrayFree()on the returned pointer to avoid leaks. Always checkArraySizeafterArrayResizeto ensure allocation/resizing was successful. - Structure Method: If the array within the struct is fixed-size, memory is managed automatically with the struct instance. If the array is dynamic,
ArrayResizerules apply within the function operating on the struct. Be mindful of copy costs when passing structures by value, especially if they contain large arrays.
Error Handling when Returning Arrays
- Global Arrays: Error handling is complex. You might need a separate global status variable to indicate if the population was successful or if the data is valid.
- Pointer/Reference Method: The function populating the array (e.g.,
PopulateArrayByReference) should indicate success or failure. For pass-by-reference, this could be aboolreturn value. If hypothetically returning a pointer (like in C++), returningNULLis the standard way to signal allocation failure. Always check the returned pointer or the reference array’s size/validity after the function call. - Structure Method: Similar to the reference method, the function operating on the structure should ideally return a
boolto indicate success. Check the structure’s contents (e.g., a size member) after the call.
Code Readability and Maintainability
- Global Arrays: Least readable and maintainable for complex logic. Hard to track dependencies and potential side effects.
- Pointer/Reference Method: More structured than globals. Pass-by-reference is the most idiomatic MQL4 way for functions to modify caller arrays. Requires clear documentation if memory management is manual (
new/ArrayFree). - Structure Method: Generally the most readable for returning structured data. Encapsulates data logically. Using pass-by-reference for modification is clear. Returning by value should be used judiciously for performance.
For most scenarios in MQL4 where a function needs to provide an array of data to a caller without using global variables, passing a dynamic array by reference or passing a structure containing an array by reference are the preferred and most maintainable methods.
Conclusion
While MQL4 does not support the direct return of arrays from functions, developers have effective workarounds. Understanding these techniques is crucial for writing modular, clean, and efficient MQL4 code.
Summary of Array Returning Techniques in MQL4
- Global Variables: Simple but generally discouraged due to poor encapsulation and thread safety issues.
- Passing by Reference (Arrays/Structures): The most common and recommended MQL4 approach. A dynamic array or a structure containing an array is passed to the function by reference (
&), allowing the function to directly modify the original data structure owned by the caller. RequiresArrayResizefor dynamic arrays. - Structures Returned by Value: A function can return a structure containing an array. This works but copies the entire structure and array, potentially impacting performance for large data sets.
Further Exploration and Advanced Techniques
For advanced use cases, particularly in MQL5, the landscape changes significantly. MQL5 fully supports returning dynamic arrays (double[] func(...) { ... return array; }) and offers more robust object-oriented features, allowing classes to encapsulate arrays and their management. Exploring MQL5’s features will reveal a more streamlined approach to handling and returning data structures, including arrays. For MQL4, mastering the pass-by-reference pattern for dynamic arrays and structures remains the key to handling functional array returns effectively.