.. highlight:: c++
  :linenothreshold: 5

.. _array-passing:

********************************
Passing Arrays To/From Functions
********************************

.. _pass-by-array:

Array Parameters
================

.. note::

  Only discussing one dimensional array in this document. Read the
  :ref:`passing 2d array document<pass-2d-array>` as needed.

+ pass an array is the same as passing a pointer
+ only the first part (pointer part) is passed, data part stays
+ use [] syntax or * syntax

  ::

    // ==== Array parameter ====
    // ---- Correct ----

    // ignore the size
    double average(double arr[], int size);
    double average(double *arr, int size);

    // ---- Wrong ----
    double average(double arr[size], int size);  // not compile
    double average(double arr[3], int size);  // compile but 3 is ignored

    // ---- to call ----
    double arr1[3] = {1.0, 2.0, 3.0};
    cout << average(arr1, 3) << endl;
    // cout << average(arr1[], 3) << endl;  // wrong!

.. _return-array:

Return an Array
===============
+ Returning an array is the same as returning a pointer
+ Only the first part (pointer part) is passed to outside, data part stays
+ The return type should use pointer syntax
+ **Never return a local array from a function**

  ::

    // ==== Array as returned value ====

    // ---- Correct ----
    // return a dynamic array
    int *makeSequence(int size) {
      int *sequence;
      sequence = new int[size];
      for (int i = 0; i < size; ++i)
        sequence[i] = i + 1;
      return sequence;
    }

    // ---- Wrong ----
    int *makeSequence(int size) {
      int sequence[size];
      for (int i = 0; i < size; ++i)
        sequence[i] = i + 1;
      return sequence;
    }

    // ---- to call ----
    int *seq = makeSequence(10);
    delete [] seq;

+ Read the :ref:`returning multidimensional arrays document<return-md-array>`
  as needed