std::tuple

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (C++20)

演算法函式庫

字串函式庫

文本處理函式庫

數值函式庫

日期與時間函式庫

輸入/輸出函式庫

檔案系統函式庫 (C++17)

並行支援函式庫 (C++11)

執行控制函式庫 (C++26)

技術規範

符號索引

外部函式庫

 

工具程式庫

語言支援 型別支援 (基本型別, RTTI) 函式庫特性測試巨集 (C++20) 程式公用程式 可變參數函式 initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) 協程支援 (C++20) 合約支援 (C++26) 三向比較 three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

通用公用程式 函式物件 位元操作 (C++20) bitset hash (C++11) 關係運算子 (C++20 中棄用) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= 整數比較函式 cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap 與 型別操作 swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) 通用詞彙型別 pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

std::tuple

成員函式

tuple::tuple

tuple::operator=

tuple::swap

非成員函式

make_tuple

tie

forward_as_tuple

tuple_cat

operator==operator!=operator<operator<=operator>operator>=operator<=> (直到 C++20)(直到 C++20)(直到 C++20)(直到 C++20)(直到 C++20)(自 C++20 起)

swap(std::tuple)

get(std::tuple)

輔助概念

tuple 類 (C++23)

輔助類別

tuple_size<std::tuple>

tuple_element<std::tuple>

uses_allocator<std::tuple>

basic_common_reference<std::tuple> (C++23)

common_type<std::tuple> (C++23)

formatter<std::tuple> (C++23)

ignore

推導指南(C++17)

 

定義於標頭檔 <tuple>
template< class... Types > class tuple;		（C++11 起）

類別樣板 std::tuple 是一個固定大小的異質值集合。它是 std::pair 的廣義化。

如果對於 Types 中的每個 Ti，std::is_trivially_destructible<Ti>::value 皆為 true，則 std::tuple 的解構子是平庸的 (trivial)。

如果程式宣告了 std::tuple 的顯式 (explicit) 或部分 (partial) 特化，則該程式是病態的 (ill-formed)，且無需診斷訊息。

樣板參數

Types...

-

tuple 所儲存元素的型別。支援空列表。

成員函式

(建構子)	建構一個新的 tuple (公開成員函式)
operator=	將一個 tuple 的內容賦值給另一個 (公開成員函式)
swap	交換兩個 tuple 的內容 (公開成員函式)

非成員函式

make_tuple (C++11)	建立一個由參數型別定義的 tuple 物件 (函式模板)
tie (C++11)	建立一個左值參考的 tuple，或將 tuple 解包至個別物件中 (函式模板)
forward_as_tuple (C++11)	建立一個轉發引用（forwarding references）tuple (函式模板)
tuple_cat (C++11)	藉由串接任意數量的 tuple 來建立一個 tuple (函式樣板)
get(std::tuple) (C++11)	tuple 存取指定的元素 (函式樣板)
operator==operator!=operator<operator<=operator>operator>=operator<=> (於 C++20 中移除)(於 C++20 中移除)(於 C++20 中移除)(於 C++20 中移除)(於 C++20 中移除)(自 C++20 起)	按字典序比較 tuple 中的值 (函式模板)
std::swap(std::tuple) (C++11)	特化 std::swap 演算法 (函式樣板)

輔助概念

tuple-likepair-like (C++23)

指定一個型別實現了 tuple 協定 (std::get, std::tuple_element, std::tuple_size) (僅供說明之概念*)

輔助類別

std::tuple_size<std::tuple> (C++11)	取得一個 tuple 的大小 (類別樣板特化)
std::tuple_element<std::tuple> (C++11)	取得指定元素的型別 (類別樣板特化)
std::uses_allocator<std::tuple> (C++11)	特化 std::uses_allocator 型別特徵 (類別樣板特化)
std::basic_common_reference<tuple-like> (C++23)	判定 tuple 與 tuple-like 型別的共同參考型別 (類別樣板特化)
std::common_type<tuple-like> (C++23)	判定 tuple 與 tuple-like 型別的共同型別 (類別樣板特化)
std::formatter<std::tuple> (C++23)	tuple 的格式化支援 (類別模板特化)
ignore (C++11)	當使用 tie 解包 tuple 時，用來跳過元素的預留位置 (常數)

輔助特化

template< class... Ts > constexpr bool enable_nonlocking_formatter_optimization<std::tuple<Ts...>>  = (enable_nonlocking_formatter_optimization<Ts> && ...);		(自 C++23 起)

這個 std::enable_nonlocking_formatter_optimization 的特化，允許在每個元素型別皆支援的情況下，高效地實作 std::print 與 std::println 來列印 tuple 物件。

附註

由於 tuple 的「形狀」——即其大小、元素型別及其型別的順序——是其型別簽章的一部分，因此它們必須在編譯時期就已確定，且只能依賴於其他編譯時期的資訊。這意味著針對 tuple 的許多條件操作——特別是條件性的前置/後置插入與過濾——只有在條件能在編譯時期評估的情況下才可行。例如，給定一個 std::tuple<int, double, int>，我們可以進行型別過濾——例如回傳一個 std::tuple<int, int>——但無法過濾每個元素是否為正數（這會導致根據執行時期的 tuple 值而產生不同的型別簽章），除非所有元素本身皆為 constexpr。

作為變通方法，可以操作 std::optional 的 tuple，但仍無法根據執行時期資訊調整大小。

在 N4387（作為 C++11 的缺陷報告應用）之前，函式無法使用拷貝列表初始化 (copy-list-initialization) 來回傳 tuple。

std::tuple<int, int> foo_tuple()
{
    return {1, -1};  // Error until N4387
    return std::tuple<int, int>{1, -1}; // Always works
    return std::make_tuple(1, -1); // Always works
}

範例

執行此程式碼

#include <iostream>
#include <stdexcept>
#include <string>
#include <tuple>
 
std::tuple<double, char, std::string> get_student(int id)
{
    switch (id)
    {
        case 0: return {3.8, 'A', "Lisa Simpson"};
        case 1: return {2.9, 'C', "Milhouse Van Houten"};
        case 2: return {1.7, 'D', "Ralph Wiggum"};
        case 3: return {0.6, 'F', "Bart Simpson"};
    }
 
    throw std::invalid_argument("id");
}
 
int main()
{
    const auto student0 = get_student(0);
    std::cout << "ID: 0, "
              << "GPA: " << std::get<0>(student0) << ", "
              << "grade: " << std::get<1>(student0) << ", "
              << "name: " << std::get<2>(student0) << '\n';
 
    const auto student1 = get_student(1);
    std::cout << "ID: 1, "
              << "GPA: " << std::get<double>(student1) << ", "
              << "grade: " << std::get<char>(student1) << ", "
              << "name: " << std::get<std::string>(student1) << '\n';
 
    double gpa2;
    char grade2;
    std::string name2;
    std::tie(gpa2, grade2, name2) = get_student(2);
    std::cout << "ID: 2, "
              << "GPA: " << gpa2 << ", "
              << "grade: " << grade2 << ", "
              << "name: " << name2 << '\n';
 
    // C++17 structured binding:
    const auto [gpa3, grade3, name3] = get_student(3);
    std::cout << "ID: 3, "
              << "GPA: " << gpa3 << ", "
              << "grade: " << grade3 << ", "
              << "name: " << name3 << '\n';
}

輸出

ID: 0, GPA: 3.8, grade: A, name: Lisa Simpson
ID: 1, GPA: 2.9, grade: C, name: Milhouse Van Houten
ID: 2, GPA: 1.7, grade: D, name: Ralph Wiggum
ID: 3, GPA: 0.6, grade: F, name: Bart Simpson

缺陷報告

下列更改行為的缺陷報告追溯應用於之前的 C++ 標準。

DR	應用於	出版時的行為	正確的行為
LWG 2796	C++11	std::tuple 解構子的平庸性 (triviality) 未經明確規範	已指定
LWG 3990	C++11	程式可能宣告一個 std::tuple 的顯式或 部分特化	在這種情況下，該程式為病態的 (無需診斷訊息)

參考文獻

• C++23 標準 (ISO/IEC 14882:2024)

• 22.4 Tuples [tuple]

• C++20 標準 (ISO/IEC 14882:2020)

• 20.5 Tuples [tuple]

• C++17 標準 (ISO/IEC 14882:2017)

• 23.5 Tuples [tuple]

• C++14 標準 (ISO/IEC 14882:2014)

• 20.4 Tuples [tuple]

• C++11 標準 (ISO/IEC 14882:2011)

• 20.4 Tuples [tuple]

參見

pair	實作二元元組，即一對值 (類別模板)