std::mdspan

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

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

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

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

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (C++20)

演算法函式庫

字串函式庫

文本處理函式庫

數值函式庫

日期與時間函式庫

輸入/輸出函式庫

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

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

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

技術規範

符號索引

外部函式庫

 

容器函式庫

序列

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

關聯

set

multiset

map

multimap

無序關聯

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

適配器 (Adaptors)

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

檢視

span (C++20)

mdspan (C++23)

表格

迭代器失效

成員函式表

非成員函式表

 

std::mdspan

成員函式 mdspan::mdspan mdspan::operator= 元素存取 mdspan::operator[] 觀察器 mdspan::rank mdspan::rank_dynamic mdspan::static_extent mdspan::extent mdspan::size mdspan::empty mdspan::stride mdspan::extents mdspan::data_handle mdspan::mapping mdspan::accessor mdspan::is_uniquemdspan::is_exhaustivemdspan::is_stridedmdspan::is_always_uniquemdspan::is_always_exhaustivemdspan::is_always_strided

非成員函式 swap(std::mdspan) 子視圖 (Subviews) submdspan (C++26) submdspan_extents (C++26) 輔助類型與模板 extentsdextents dims (C++26) default_accessor aligned_accessor (C++26) 佈局映射策略 layout_left layout_right layout_stride layout_left_padded (C++26) layout_right_padded (C++26) 子視圖輔助 full_extent (C++26) strided_slice (C++26) submdspan_mapping_result (C++26) 推導指引

 

定義於標頭檔 <mdspan>
template<     class T,     class Extents,     class LayoutPolicy = std::layout_right,     class AccessorPolicy = std::default_accessor<T> > class mdspan;		(自 C++23 起)

std::mdspan 是一個多維陣列視圖，將多維索引映射到陣列的元素。映射與元素存取策略皆可配置，且底層陣列不必是連續的，甚至不需要實際存在於記憶體中。

mdspan 的每個特化式 MDS 均符合 copyable 概念，並且滿足

• std::is_nothrow_move_constructible_v<MDS> 為 true，
• std::is_nothrow_move_assignable_v<MDS> 為 true，以及
• std::is_nothrow_swappable_v<MDS> 為 true。

若 mdspan 的 accessor_type、mapping_type 與 data_handle_type 皆為 TriviallyCopyable 類型，則該 mdspan 的特化式即為 TriviallyCopyable 類型。

範本參數

T	-	元素類型；必須為完整物件類型，且既非抽象類別類型也非陣列類型。
Extents	-	指定維度數量、各維度大小，以及哪些維度在編譯期已知。必須為 std::extents 的特化式。
LayoutPolicy	-	指定如何將多維索引轉換為底層的一維索引（例如：欄優先 3D 陣列、對稱三角 2D 矩陣等）。必須滿足 LayoutMappingPolicy 的要求。
存取器策略 (AccessorPolicy)	-	指定如何將底層的一維索引轉換為指向 T 的參考。必須滿足以下限制：std::is_same_v<T, typename AccessorPolicy​::​element_type> 必須為 true。必須滿足 AccessorPolicy 的要求。

成員類型

成員	定義
extents_type	Extents
layout_type	LayoutPolicy
accessor_type	存取器策略 (AccessorPolicy)
mapping_type	LayoutPolicy::mapping<Extents>
element_type	T
value_type	std::remove_cv_t<T>
index_type	Extents::index_type
size_type	Extents::size_type
rank_type	Extents::rank_type
data_handle_type	AccessorPolicy::data_handle_type
reference	AccessorPolicy::reference

資料成員

成員	描述
accessor_type acc_ (私有)	存取器 (accessor) (僅用於闡述的成員物件*)
mapping_type map_ (私有)	佈局映射 (layout mapping) (僅用於闡述的成員物件*)
data_handle_type ptr_ (私有)	底層資料控制代碼 (data handle) (僅用於闡述的成員物件*)

成員函式

(建構子)	建構一個 mdspan (公開成員函式)
operator=	指派一個 mdspan (公開成員函式)
元素存取
operator[]	存取指定多維索引處的元素 (公開成員函式)
觀察器
rank [靜態]	回傳 mdspan 的秩 (rank) (公開靜態成員函式)
rank_dynamic [靜態]	回傳 mdspan 的動態秩 (公開靜態成員函式)
static_extent [靜態]	回傳 mdspan 在給定秩索引處的靜態維度大小 (公開靜態成員函式)
extent	回傳 mdspan 在給定秩索引處的維度大小 (公開成員函式)
size	回傳多維索引空間的大小 (公開成員函式)
empty	檢查索引空間的大小是否為零 (公開成員函式)
stride	取得指定維度上的跨度 (stride) (公開成員函式)
extents	取得維度物件 (公開成員函式)
data_handle	取得底層一維序列的指標 (公開成員函式)
mapping	取得映射物件 (公開成員函式)
accessor	取得存取器策略物件 (公開成員函式)
is_unique	判斷此 mdspan 的映射是否為唯一（即每種索引組合是否皆映射至不同的底層元素） (公開成員函式)
is_exhaustive	判斷此 mdspan 的映射是否為詳盡（即每個底層元素是否皆能透過某種索引組合被存取） (公開成員函式)
is_strided	判斷此 mdspan 的映射是否為跨距（即在每個維度中，遞增索引是否每次皆會跳過相同數量的底層元素） (公開成員函式)
is_always_unique [靜態]	判斷此 mdspan 的佈局映射是否總是唯一的 (公開靜態成員函式)
is_always_exhaustive [靜態]	判斷此 mdspan 的佈局映射是否總是詳盡的 (公開靜態成員函式)
is_always_strided [靜態]	判斷此 mdspan 的佈局映射是否總是跨距的 (公開靜態成員函式)

非成員函式

std::swap(std::mdspan) (C++23)	為 mdspan 特化 std::swap 演算法 (函式模板)
子視圖 (Subviews)
submdspan (C++26)	回傳現有 mdspan 子集的視圖 (函式模板)
submdspan_extents (C++26)	根據現有的維度與切片說明符建立新的維度 (函式模板)

輔助類型與模板

extents (C++23)	描述特定秩之多維索引空間的描述符 (類別模板)
dextentsdims (C++23)(C++26)	用於全動態 std::extents 的方便別名模板 (別名模板)
default_accessor (C++23)	用於存取 mdspan 元素的索引類型 (類別模板)
aligned_accessor (C++26)	用於對齊存取 mdspan 元素的類型 (類別模板)
佈局映射策略
layout_left (C++23)	欄優先多維陣列佈局映射策略；最左側維度具有跨度 1 (類別)
layout_right (C++23)	列優先多維陣列佈局映射策略；最右側維度具有跨度 1 (類別)
layout_stride (C++23)	具備使用者定義跨度的佈局映射策略 (類別)
layout_left_padded (C++26)	欄優先佈局映射策略，其填補跨度可大於或等於最左側維度 (類別模板)
layout_right_padded (C++26)	列優先佈局映射策略，其填補跨度可大於或等於最右側維度 (類別模板)
子視圖輔助
full_extentfull_extent_t (C++26)	描述指定維度中完整索引範圍的切片說明符標籤。 (標籤)
strided_slice (C++26)	表示一組規則間隔索引的切片說明符，由偏移量、範圍與跨度指示 (類別模板)
submdspan_mapping_result (C++26)	submdspan_mapping 多載的回傳類型 (類別模板)

附註

功能測試巨集	數值	標準	功能
__cpp_lib_mdspan	202207L	(C++23)	std::mdspan
__cpp_lib_submdspan	202306L	(C++26)	std::submdspan
	202403L	(C++26)	std::mdspan 填補佈局
__cpp_lib_aligned_accessor	202411L	(C++26)	std::aligned_accessor

範例

可在 Compiler Explorer 上預覽。

執行此程式碼

#include <cstddef>
#include <mdspan>
#include <print>
#include <vector>
 
int main()
{
    std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};
 
    // View data as contiguous memory representing 2 rows of 6 ints each
    auto ms2 = std::mdspan(v.data(), 2, 6);
    // View the same data as a 3D array 2 x 3 x 2
    auto ms3 = std::mdspan(v.data(), 2, 3, 2);
 
    // Write data using 2D view
    for (std::size_t i = 0; i != ms2.extent(0); i++)
        for (std::size_t j = 0; j != ms2.extent(1); j++)
            ms2[i, j] = i * 1000 + j;
 
    // Read back using 3D view
    for (std::size_t i = 0; i != ms3.extent(0); i++)
    {
        std::println("slice @ i = {}", i);
        for (std::size_t j = 0; j != ms3.extent(1); j++)
        {
            for (std::size_t k = 0; k != ms3.extent(2); k++)
                std::print("{} ", ms3[i, j, k]);
            std::println("");
        }
    }
}

輸出

slice @ i = 0
0 1
2 3
4 5
slice @ i = 1
1000 1001
1002 1003
1004 1005

參見

span (C++20)	連續物件序列上的非擁有型視圖 (類別樣板)
valarray	數值陣列、陣列遮罩與陣列切片 (類別樣板)