HOWTO · Arduino

Arduino 從函式返回陣列

C++ 無法以值的方式返回內建陣列;本文介紹透過函式填入現有陣列、返回有效儲存空間的指標,或使用全域陣列等共用儲存空間的方法。

本頁內容

C++ 函式無法以值的方式返回內建陣列。在 Arduino sketch 中,可以改為將現有陣列傳入函式並填入資料、返回指向仍然有效之儲存空間的指標,或使用全域陣列等共用儲存空間。該選擇取決於儲存空間由誰管理,以及這些值需要保留多久。

以下範例是完整的標準 C++ 程式,方便理解資料如何流動。在 sketch 中,將相關操作放進 setup() 或其他函式,並以 Serial.print() 取代 std::cout。這些範例未經實體 Arduino 開發板驗證。

在函式中修改現有陣列

若要取得固定大小的結果,最簡單的方法是由呼叫端建立陣列,再將它傳給函式。陣列作為函式參數時會調整為指標,因此函式修改的是呼叫端原有的元素。也要一併傳入元素數量;函式無法從指標推知陣列的容量。

執行以下範例:

本節中的程式碼以及顯示的標籤或輸出仍為英文。

#include <iostream>

void fillValues(int values[], int count) {
  for (int i = 0; i < count; ++i) {
    values[i] = i + 1;
  }
}

int main() {
  int readings[5];
  fillValues(readings, 5);
  for (int value : readings) {
    std::cout << value << '\n';
  }
}

這種做法會修改現有的儲存空間,並不會返回陣列。此處的 readings 是區域自動陣列,在 fillValues 寫入前,其元素沒有初始值。相較之下,具有靜態儲存期的陣列(包括全域陣列)會在程式啟動時以零初始化。整數零是一個值,不是空指標。

對區域陣列而言,像 int readings[5] 這樣的固定界限受到 Arduino C++ 工具鏈廣泛支援。有些 C++ 實作以擴充功能支援可變長度陣列,但這不是標準 C++。在目標工具鏈與記憶體預算允許的情況下,請優先使用固定界限或動態配置的儲存空間。

返回指向靜態區域陣列的指標

函式可以返回指向 static 區域陣列的指標,因為函式返回後,該陣列仍然存在。陣列大小固定,而且每次呼叫都會返回指向同一個儲存空間的指標。後續呼叫可能會覆寫先前呼叫者原本想保留的值。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

#include <iostream>

int* makeValues() {
  static int values[3];
  for (int i = 0; i < 3; ++i) {
    values[i] = (i + 1) * 10;
  }
  return values;
}

int main() {
  int* result = makeValues();
  for (int i = 0; i < 3; ++i) {
    std::cout << result[i] << '\n';
  }
}

此指標在程式執行期間都有效,但它不會移轉所有權,也不會在每次呼叫時提供新的陣列。若呼叫端需要彼此獨立的結果,或函式可能在先前結果尚未使用前再次呼叫,請避免採用這種方式。

動態配置並返回陣列

如果結果大小要到執行時才決定,動態配置可能很有用,但也會增加所有權與記憶體管理工作。呼叫端必須先檢查配置是否成功,才能使用指標;配置成功後,還必須以 free() 釋放記憶體。在記憶體有限的 Arduino 開發板上,反覆配置與釋放可能造成堆積碎片;若所需容量已知,請優先使用固定儲存空間。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

#include <cstdlib>
#include <cstddef>
#include <cstdint>
#include <iostream>
#include <limits>

int* makeValues(int count) {
  if (count <= 0) return nullptr;
  const std::size_t maxCount = std::numeric_limits<std::size_t>::max() / sizeof(int);
  if (static_cast<std::uintmax_t>(count) > static_cast<std::uintmax_t>(maxCount)) return nullptr;
  const std::size_t bytes = static_cast<std::size_t>(count) * sizeof(int);
  int* values = static_cast<int*>(std::malloc(bytes));
  if (values == nullptr) return nullptr;
  for (int i = 0; i < count; ++i) {
    values[i] = i + 1;
  }
  return values;
}

int main() {
  const int count = 3;
  int* result = makeValues(count);
  if (result == nullptr) {
    std::cout << "allocation failed\n";
    return 0;
  }
  for (int i = 0; i < count; ++i) {
    std::cout << result[i] << '\n';
  }
  std::free(result);
}

呼叫端擁有返回的記憶體區塊,使用完畢後必須呼叫 free() 恰好一次。釋放後不要再存取該指標,也不要混用 malloc() 與 delete,或混用 new 與 free()。在相乘之前,makeValues 會將正數元素數量與 size_t 所能容納的最大 int 元素數量比較;若位元組數會溢位(包括 size_t 比 int 窄的情況),便返回 nullptr。

在函式中修改全域陣列

全域陣列提供固定的儲存空間,sketch 中的函式都能存取。小型程式若只有一份共用結果,這種方式可能很方便;但它會讓函式依賴全域狀態,也使彼此獨立或重複使用時較難推理。全域陣列會在 setup() 執行前以零初始化。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

#include <iostream>

int readings[3];

void fillReadings() {
  for (int i = 0; i < 3; ++i) {
    readings[i] = 10 + i;
  }
}

int main() {
  fillReadings();
  for (int value : readings) {
    std::cout << value << '\n';
  }
}

此陣列會在整個程式執行期間持續存在。請明確指定容量,並確保每個寫入它的函式都遵守容量限制。

透過參考參數修改陣列

C++ 參考參數可以在參數型別中保留陣列大小。這會讓所需容量成為函式簽章的一部分,也讓編譯器能拒絕傳入大小不同的陣列。使用樣板可讓輔助函式適用於多種固定大小。

本節中的程式碼以及顯示的標籤或輸出仍為英文。

#include <cstddef>
#include <iostream>

template <std::size_t N>
void fillValues(int (&values)[N]) {
  for (std::size_t i = 0; i < N; ++i) {
    values[i] = static_cast<int>(i + 1);
  }
}

int main() {
  int readings[4];
  fillValues(readings);
  for (int value : readings) {
    std::cout << value << '\n';
  }
}

這樣便不必另外傳入容量,同時仍可修改呼叫端的陣列。此輔助函式接受編譯期大小已知的內建陣列;它不會把指標或動態配置的記憶體區塊當成自帶長度的陣列來接受。

為 Arduino sketch 選擇合適的方法

對一般的 Arduino sketch,請在使用陣列的地方建立固定大小的陣列,再連同長度一起傳給函式。若輔助函式只應接受特定大小的陣列,或希望樣板自動保留大小資訊,參考參數就很實用。若確實需要整個程式共用狀態,則可使用全域陣列。

只有在一份共用的固定大小結果已足夠,而且後續呼叫可以安全地覆寫它時,才適合返回指向靜態區域陣列的指標。只有在執行時決定大小確有必要,且 sketch 能妥善處理配置失敗、所有權、釋放與堆積限制時,才適合動態配置。無論採用哪種方式,函式都可以返回指標或修改呼叫端可見的儲存空間,但無法以值的方式返回內建陣列。