class ara::core::Span

Die Elementfunktion crbegin der Klasse ara::core::Span liefert einen konstanten Reverse-Iterator, der auf das letzte Element der referenzierten Sequenz zeigt [SWS_CORE_01978]. Die Funktion erfordert die Header-Datei #include "ara/core/span.h" und folgt der Verwendung in [views.span] [SWS_CORE_01978]. Der Rückgabewert vom Typ const_reverse_iterator erlaubt eine schreibgeschützte Rückwärtsiteration über den durch das Span beschriebenen Speicherbereich [SWS_CORE_01978].

Da crbegin als constexpr deklariert ist, kann die Auswertung bereits zur Kompilierzeit erfolgen [SWS_CORE_01978]. Bezüglich der Fehlerbehandlung ist die Funktion als noexcept deklariert und als exception safe eingestuft; sie wirft folglich keine Ausnahmen, und es existieren weder Fehlercodes noch DET- oder DEM-Meldungen [SWS_CORE_01978].

Hinsichtlich Nebenläufigkeit und Einschränkungen ist die Methode const-qualifiziert; Interpretation: Parallele lesende Aufrufe auf derselben Instanz dürften ohne externe Synchronisation threadsicher sein, solange der zugrundeliegende Speicherbereich nicht zeitgleich modifiziert wird [SWS_CORE_01978]. Frage Q-d63c0354556f1d23 (offen)

Im Zusammenspiel mit anderen Elementen von ara::core folgt crbegin einem einheitlichen Muster für Container und Ansichten:

• ara::core::Array bietet ein entsprechendes constexpr- und exception safe-Interface [SWS_CORE_01260].
• ara::core::StringView stellt crbegin ebenfalls als constexpr und exception safe bereit [SWS_CORE_02126].
• ara::core::Vector [SWS_CORE_01342], ara::core::Map [SWS_CORE_01450] sowie ara::core::BasicString [SWS_CORE_03049] stellen crbegin synchron und ausnahmesicher (noexcept) zur Verfügung.

Verwendung

Die Elementfunktion crend der Template-Klasse ara::core::Span ([SWS_CORE_01979]) liefert synchron einen konstanten Rückwärts-Iterator vom Typ const_reverse_iterator zurück. Die Funktion erfordert die Einbindung der Header-Datei ara/core/span.h und nimmt keine Aufrufparameter entgegen. Gemäß der Spezifikation richtet sich das Verhalten nach der Standard-Verwendung in [views.span]. Interpretation: Der zurückgegebene Iterator dürfte die theoretische Position unmittelbar vor dem ersten Element des Bereichs darstellen und somit als Abbruchbedingung bei einer Rückwärtsiteration dienen. Frage Q-83d4ed4a6e68fb19 (offen)

Fehlerbehandlung und Nebenläufigkeit

Die Funktion ist als noexcept deklariert und explizit als exception safe klassifiziert ([SWS_CORE_01979]). Ein Aufruf löst keine Ausnahmen aus, und es existieren weder Fehlerrückgabewerte noch spezifische Fehlerprotokollierungen über DET oder DEM. Da crend als constexpr definiert ist, kann die Auswertung direkt zur Kompilierzeit erfolgen. Als reine const-Elementfunktion verändert sie den Zustand der Instanz nicht; nebenläufige lesende Zugriffe auf dieselbe Span-Instanz dürften daher ohne Synchronisation threadsicher sein. Frage Q-d90bd6b4f01c8af6 (offen)

Zusammenspiel

Das Verhalten von crend in ara::core::Span fügt sich nahtlos in die Sequenz- und Container-Schnittstellen von ara::core ein:

• ara::core::Array ([SWS_CORE_01261]) und ara::core::StringView ([SWS_CORE_02127]) bieten identische, ebenfalls als constexpr und noexcept deklarierte Signaturen.
• ara::core::Vector ([SWS_CORE_01343]), ara::core::Map ([SWS_CORE_01451]) und ara::core::BasicString ([SWS_CORE_03050]) stellen analoge const_reverse_iterator-Endpunkte für dynamische Container bereit.

Die Template-Elementfunktion first<Count>() der Klasse ara::core::Span erzeugt synchron einen neuen Teilbereich über die ersten Count Elemente des aktuellen Spans und liefert diesen als ara::core::Span<element_type, Count> zurück [SWS_CORE_01961]. Die Funktion ist in der Header-Datei ara/core/span.h deklariert und als constexpr sowie const noexcept spezifiziert [SWS_CORE_01961].

In Bezug auf die Fehlerbehandlung ist die Funktion als ausnahmesicher (exception safe) eingestuft und wirft keine Exceptions [SWS_CORE_01961]. Spezifische Fehlercodes, Fehler-Rückgabewerte oder Meldungen an DET oder DEM sind nicht definiert. Es besteht jedoch eine bindende Vorbedingung: Das Verhalten ist undefiniert, wenn der Template-Parameter Count größer als die Laufzeitgröße des Spans ist (Count > size()) [SWS_CORE_01961]. Aufrufer müssen daher sicherstellen, dass ausreichend Elemente vorliegen.

Da die Methode als const deklariert ist und das zugrunde liegende Span-Objekt nicht modifiziert, dürfte ein nebenläufiger lesender Zugriff über mehrere Threads hinweg ohne zusätzliche Sperren thread-sicher sein (Interpretation). Frage Q-215ae1cc00b7a590 (offen) Werden die adressierten Elemente des Spans währenddessen durch andere Threads verändert, muss der Zugriff extern synchronisiert werden.

Verwendung

Die Elementfunktion first wird auf einer Instanz von ara::core::Span aufgerufen (bereitgestellt über den Header ara/core/span.h), um eine Teilansicht auf die ersten Elemente einer Sequenz zu erzeugen [SWS_CORE_01962]. Als Parameter wird die gewünschte Anzahl an Elementen count vom Typ size_type übergeben [SWS_CORE_01962]. Der Rückgabewert ist ein Span<element_type, dynamic_extent>, welcher das entsprechende Präfix abbildet [SWS_CORE_01962]. Das Verhalten richtet sich dabei nach der Semantik von [views.span] aus dem C++-Standard [SWS_CORE_01962]. Durch die Deklaration als constexpr und noexcept arbeitet die Methode synchron, ausnahmefrei und kann bereits zur Übersetzungszeit evaluiert werden [SWS_CORE_01962].

Fehlerbehandlung und Randbedingungen

Die Funktion ist als ausnahmesicher (exception safe) spezifiziert; Fehlercodes oder spezifische Fehlermeldungen (wie DET oder DEM) sind nicht vorgesehen [SWS_CORE_01962]. Für den Aufrufer gilt folgende bindende Randbedingung:

• Das Verhalten der Funktion ist undefiniert (undefined behavior), wenn count > size() ist [SWS_CORE_01962].

Der anwendende Programmcode muss daher vor dem Aufruf eigenständig verifizieren, dass die angeforderte Elementanzahl die tatsächliche Größe des Spans nicht übersteigt.

Nebenläufigkeit und Einschränkungen

Als konstante Elementfunktion (const) modifiziert first den aufgerufenen Span nicht [SWS_CORE_01962]. Zur Thread-Sicherheit schweigt die Spezifikation; nebenläufige Lesezugriffe auf denselben Span sowie die darunterliegenden Sequenzdaten dürften jedoch unkritisch sein (Interpretation). Frage Q-8c3b51e54157dc12 (offen) Werden die referenzierten Elemente zeitgleich durch andere Threads modifiziert, ist eine externe Synchronisation erforderlich.

Die Template-Elementfunktion [SWS_CORE_01963] der Klasse ara::core::Span (Header #include "ara/core/span.h") liefert synchron eine Teilansicht auf die letzten Count Elemente der zugrundeliegenden Sequenz. Sie folgt der Semantik von [views.span] [SWS_CORE_01963]. Da der Parameter Count als Template-Argument übergeben wird, besitzt das resultierende Span-Objekt ein bereits zur Übersetzungszeit feststehendes statisches Ausmaß.

Die Operation ist als constexpr, const sowie noexcept deklariert und als ausnahmesicher (exception safe) spezifiziert [SWS_CORE_01963]. Fehlerrückgaben über Fehlercodes oder Benachrichtigungen an DET oder DEM sind für diese Funktion nicht vorgesehen. Es liegt jedoch ein undefiniertes Verhalten vor, falls Count > size() ist [SWS_CORE_01963]. Aufrufende müssen daher vor der Instanziierung beziehungsweise Ausführung sicherstellen, dass die aktuelle Spanne mindestens die geforderte Anzahl an Elementen umfasst.

Hinsichtlich der Nebenläufigkeit trifft die Spezifikation keine explizite Aussage zur Thread-Sicherheit; als seiteneffektfreie const-Methode dürfte der gleichzeitige Lesezugriff mehrerer Threads auf dieselbe Span-Instanz jedoch unkritisch sein, sofern die referenzierten Elemente im Speicher nicht parallel verändert werden. Frage Q-120ccf3995c86b47 (offen)

Im Zusammenspiel innerhalb des Moduls ergänzt die Funktion die Überladung [SWS_CORE_01964]: Während die vorliegende Variante [SWS_CORE_01963] ein festes Extent zur Kompilierzeit erfordert, gestattet [SWS_CORE_01964] die Angabe einer variablen Elementanzahl zur Laufzeit und liefert ein Span mit dynamischem Ausmaß (dynamic_extent).

Verwendung

Die Elementfunktion last der Klasse ara::core::Span erzeugt eine Teilansicht (Subspan), welche die letzten count Elemente der aktuellen Sequenz umfasst [SWS_CORE_01964]. Der Aufruf erfolgt synchron und liefert einen Span<element_type, dynamic_extent> zurück [SWS_CORE_01964]. Da die Funktion als constexpr und noexcept deklariert ist, kann sie auch zur Übersetzungszeit evaluiert werden und garantiert vollständige Ausnahmesicherheit (exception safe) [SWS_CORE_01964].

Fehlerbehandlung und Randbedingungen

Die Funktion löst keine Ausnahmen aus. Ein fehlerhafter Aufruf liegt vor, wenn das Argument count die tatsächliche Anzahl der vorhandenen Elemente übersteigt (count > size()); in diesem Fall ist das Verhalten undefiniert [SWS_CORE_01964]. Aufrufer müssen daher vor der Übergabe dynamischer Werte sicherstellen, dass die geforderte Elementanzahl im gültigen Bereich liegt.

Nebenläufigkeit und Zusammenspiel

Da last eine zustandslose Leseoperation auf der Span-Instanz darstellt, dürften gleichzeitige Aufrufe über denselben Span unkritisch sein, solange die zugrunde liegenden Sequenzelemente nicht modifiziert werden. Frage Q-ec2beaa99d9627c0 (offen) Im Unterschied zur Template-Variante last<Count>() [SWS_CORE_01963], welche die Größe statisch festlegt, bestimmt diese Überladung die Länge zur Laufzeit. Neu erzeugte Sequenzen, etwa über MakeSpan [SWS_CORE_01991], können so flexibel auf ihr Suffix reduziert werden.

Die Elementfunktion size_bytes der Klasse ara::core::Span liefert die Gesamtgröße des referenzierten Speicherbereichs in Bytes zurück [SWS_CORE_01968]. Die Semantik entspricht dabei der Definition in Standard-C++ gemäß [views.span] [SWS_CORE_01968].

Verwendung

Die Funktion wird synchron auf einer bestehenden Instanz von ara::core::Span aufgerufen und erfordert die Einbindung des Headers ara/core/span.h [SWS_CORE_01968]:

• Aufrufkontext und Parameter: Die Methode ist parameterlos und als const deklariert, verändert den Zustand des Spans also nicht [SWS_CORE_01968]. Durch die Kennzeichnung als constexpr kann der Wert bereits zur Compile-Zeit ausgewertet werden, sofern der zugrunde liegende Kontext dies gestattet [SWS_CORE_01968].
• Rückgabewert: Gibt einen Wert vom Typ size_type zurück, der die Bytegröße des dargestellten Speichers repräsentiert [SWS_CORE_01968].

Fehlerbehandlung und Ausnahme-Sicherheit

Die Funktion ist als noexcept deklariert und spezifiziert das Garantieniveau exception safe [SWS_CORE_01968]. Es treten keine C++-Exceptions auf und es werden keine Fehlercodes zurückgegeben [SWS_CORE_01968].

Nebenläufigkeit und Einschränkungen

Da size_bytes eine reine lesende Operation (const) ohne Seiteneffekte ist, ist der nebenläufige Aufruf über dieselbe Instanz von mehreren Threads aus unkritisch, sofern das referenzierte Span-Objekt nicht zeitgleich modifiziert wird (Interpretation: Standard-Thread-Safety für Const-Methoden) [SWS_CORE_01968]. Frage Q-ea768d4f6fa1d12f (offen)

Die Elementfunktion subspan der Klasse ara::core::Span erzeugt eine Teilansicht auf eine bestehende Spanne ([SWS_CORE_01965]). Über die Template-Parameter Offset und Count werden die Startposition sowie die Anzahl der Elemente statisch zur Übersetzungszeit festgelegt; für Count ist standardmäßig dynamic_extent hinterlegt. Der Aufruf erfolgt synchron, ist als constexpr sowie noexcept deklariert und gilt als ausnahmesicher ([SWS_CORE_01965]).

Hinsichtlich des Verhaltens verweist die Spezifikation auf das C++-Standardkonstrukt [views.span] ([SWS_CORE_01965]). Anders als bei der überladenen Laufzeitfunktion [SWS_CORE_01966], bei der fehlerhafte Grenzen explizit zu undefiniertem Verhalten führen, erfolgt die Überprüfung hier vorrangig beim Kompilieren. Interpretation: Bei statisch bekannter Elementanzahl dürfte eine Überschreitung der Grenzen von Offset oder Count vermutlich zu einem Fehler bei der Kompilierung führen. Frage Q-c1b2dd93177fb266 (offen)

Die Funktion ist über den Header #include "ara/core/span.h" verfügbar ([SWS_CORE_01965]). Sie ergänzt die komplementäre Überladung [SWS_CORE_01966] für Fälle, in denen Teilbereiche bereits zur Übersetzungszeit feststehen. Da subspan eine konstante Elementfunktion ist, sind nebenläufige Lesezugriffe auf dasselbe Quellobjekt unkritisch, sofern das referenzierte Speicherelement nicht parallel verändert wird.

Verwendung

Die Elementfunktion subspan von ara::core::Span ([SWS_CORE_01966]) erstellt eine Teilansicht (Subspan) auf die zugrundeliegenden Daten. Sie wird über den Header ara/core/span.h eingebunden. Als Parameter akzeptiert sie einen Versatz (offset) sowie optional die Anzahl der Elemente (count), welche standardmäßig mit dynamic_extent belegt ist. Wenn count == dynamic_extent übergeben wird, umfasst die erzeugte Teilansicht vermutlich alle verbleibenden Elemente ab dem angegebenen Versatz. Frage Q-f300852e8a1a87c8 (offen) Die Funktion ist als constexpr sowie noexcept deklariert und gilt laut Spezifikation als ausnahmesicher (exception safe).

Fehlerbehandlung und Randbedingungen

Die Funktion signalisiert Fehler weder über Fehlercodes noch über C++-Exceptions. Stattdessen führt die Verletzung der definierten Vorbedingungen direkt zu undefiniertem Verhalten ([SWS_CORE_01966]). Ein Aufruf ist nur dann definiert, wenn folgende Bedingung erfüllt ist:

• offset <= size() && (count == dynamic_extent || count <= size() - offset)

Aufrufer müssen diese Bereichsgrenzen vor dem Aufruf eigenständig verifizieren, um undefiniertes Verhalten zur Laufzeit auszuschließen.

Zusammenspiel

Im Gegensatz zur Template-Variante [SWS_CORE_01965], welche Versatz und Elementanzahl bereits zur Übersetzungszeit über Template-Parameter bindet, erlaubt [SWS_CORE_01966] die dynamische Übergabe von Laufzeitwerten. Als Rückgabetyp liefert sie stets eine Instanz von Span<element_type, dynamic_extent>.