class ara::diag::DiagnosticSovdArrayContentElementDataView

Verwendung

Die Elementfunktion Clear der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView leert den gesamten Inhalt eines SOVD-Array-Elements ([SWS_DM_02233]). Der Aufruf wird über den Header #include "ara/diag/diagnostic_sovd_content_element_data.h" bereitgestellt. Die Methode besitzt die Signatur auto Clear () noexcept -> void;. Sie arbeitet synchron, nimmt keine Parameter entgegen und liefert keinen Rückgabewert ([SWS_DM_02233]).

Fehlerbehandlung und Randbedingungen

Gemäß Spezifikation ist die Funktion als ausnahmesicher (exception safe) definiert und mit dem Spezifizierer noexcept versehen ([SWS_DM_02233]). Sie gibt weder Fehlercodes noch ein ara::core::Result zurück. Als bindende Anforderung gilt, dass das referenzierte DiagnosticSovdContentElementData vom Typ ArrayContentElementData sein muss ([SWS_DM_02233]). Da keine Fehler signalisiert werden, dürfte die Einhaltung dieses Typs durch die View-Klasse bereits zur Konstruktionszeit sichergestellt sein. Frage Q-cdb2385e081c3456 (offen)

Nebenläufigkeit

Die Spezifikation stuft die Methode ausdrücklich als threadsicher (thread-safe) ein ([SWS_DM_02233]). Aufrufe von Clear können daher ohne externe Synchronisation nebenläufig aus mehreren Threads erfolgen.

Zusammenspiel im Diagnose-Subsystem

Innerhalb der SOVD-Datenstrukturen steht die Operation in engem Zusammenhang mit weiteren Löschmethoden:

• DiagnosticSovdContentElementData::Clear ([SWS_DM_02338]) bildet das generische Gegenstück auf Element-Ebene, gibt jedoch ein ara::core::Result<void> zurück und schlägt fehl, wenn das Objekt kein Array darstellt.
• DiagnosticSovdRecordContentElementDataView::Clear ([SWS_DM_02276]) übernimmt die analoge Bereinigung für Datenstrukturen vom Typ RecordContentElementData bzw. ContentData.
• Im klassischen Fehlerspeicher-Kontext dient demgegenüber ara::diag::DTCInformation::Clear ([SWS_DM_00671]) der asynchronen Bereinigung von UDS-DTCs über ara::core::Future.

Verwendung

Die Methode Erase der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView dient dem Entfernen eines Elements aus diagnostischen SOVD-Inhaltsdaten ([SWS_DM_02247], SWS Diagnostics §8.60.5.1.1.8 „Erase“). Als Parameter nimmt die Funktion einen Iterator vom Typ DiagnosticSovdArrayContentElementDataIterator entgegen, welcher auf das zu löschende Element verweist. Der Aufruf erfolgt als synchrone Operation; dies dürfte sich aus der direkten Rückgabe von ara::core::Result<void> ohne asynchrones Future-Muster ergeben. Frage Q-28de22574e525c78 (offen)

Fehlerbehandlung und Randbedingungen

Die Funktion ist mit noexcept deklariert und besitzt die Eigenschaften exception safe sowie thread-safe ([SWS_DM_02247]). Schlägt das Löschen fehl, liefert die Methode einen Fehler über das zurückgegebene ara::core::Result. Dies ist der Fall, wenn das übergeordnete DiagnosticSovdContentElementData nicht vom geforderten Typ ArrayContentElementData ist oder das Element aus anderen Gründen nicht entfernt werden konnte ([SWS_DM_02247]).

Zusammenspiel

Innerhalb der SOVD-Schnittstelle korrespondiert diese Operation mit der Löschmethode Erase des zugrundeliegenden Datencontainers DiagnosticSovdContentElementData für Array-Elemente ([SWS_DM_02352]). Für Record-Strukturen existieren mit DiagnosticSovdRecordContentElementDataView::Erase sowie der entsprechenden Container-Methode analoge Gegenstücke ([SWS_DM_02294], [SWS_DM_02374]).

Die synchrone Memberfunktion PushBack dient dazu, ein ganzzahliges Element mit Vorzeichen vom Typ std::int64_t an eine Array-Struktur von Diagnose-SOVD-Inhaltselementen anzuhängen ([SWS_DM_02241], AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.14 „PushBack“). Sie ist in der Header-Datei ara/diag/diagnostic_sovd_content_element_data.h deklariert und als noexcept definiert ([SWS_DM_02241]).

Für einen erfolgreichen Aufruf gelten folgende Voraussetzungen und Schnittstellenanforderungen:

• Aufrufkontext und Vorbedingungen: Das Zielobjekt der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView muss ein ArrayContentElementData repräsentieren, und der hinzuzufügende primitive Typ muss dem im Konstruktor definierten Elementtyp entsprechen ([SWS_DM_02241]).
• Rückgabewert und Fehlerbehandlung: Die Funktion gibt ein ara::core::Result<void> zurück. Schlägt die Prüfung fehl, weil das zugrundeliegende Element nicht vom Typ ArrayContentElementData ist, enthält das Ergebnis einen Fehler ([SWS_DM_02241]). Interpretation: Eine Diskrepanz zum im Konstruktor vorgegebenen Datentyp dürfte analog als Fehler im Ergebnisobjekt gemeldet werden. Frage Q-d4715ecbd0f12d26 (offen)
• Nebenläufigkeit: Die Funktion ist als thread-safe sowie exception-safe spezifiziert ([SWS_DM_02241]).

Die Methode ist Bestandteil einer Familie typisierter Überladungen innerhalb von DiagnosticSovdArrayContentElementDataView für vorzeichenlose Ganzzahlen ([SWS_DM_02242]), Fließkommazahlen ([SWS_DM_02243]), Wahrheitswerte ([SWS_DM_02244]), Zeichenketten ([SWS_DM_02245]) und vollständige Datenelemente ([SWS_DM_02246]). Korrespondierende Methoden existieren zudem auf der Datenklasse DiagnosticSovdContentElementData selbst ([SWS_DM_02346]).

Verwendung

Die synchrone API-Funktion PushBack der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView fügt einen vorzeichenlosen 64-Bit-Ganzzahlwert (std::uint64_t) als primitives Datenelement an das Ende eines bestehenden SOVD-Array-Elements an [SWS_DM_02242]. Die Einbindung erfolgt über die Header-Datei ara/diag/diagnostic_sovd_content_element_data.h SWS Diagnostics §8.60.5.1.1.15 „PushBack“. Voraussetzung für den erfolgreichen Aufruf ist, dass das aktuelle Element ein ArrayContentElementData darstellt und der hinzuzufügende Wert dem im Konstruktor definierten Elementtyp entspricht [SWS_DM_02242].

Fehlerbehandlung und Nebenläufigkeit

Die Funktion signalisiert ihren Ausführungsstatus über ara::core::Result<void> [SWS_DM_02242]. Ist das Zielobjekt nicht vom Typ ArrayContentElementData, liefert die Funktion einen Fehler im Ergebnis zurück [SWS_DM_02242]. Da keine spezifischen Fehlercodes genannt werden (Interpretation: Fehlerzustände werden generisch durch das Result signalisiert), muss der Aufrufer das Result-Objekt auswerten. Frage Q-95f2dd96e2681368 (offen) Die Methode ist als noexcept deklariert, garantiert Exception-Sicherheit und ist explizit als threadsicher spezifiziert [SWS_DM_02242].

Zusammenspiel

Die Operation gehört zu einer Familie typspezifischer Überladungen innerhalb von DiagnosticSovdArrayContentElementDataView, die analog vorzeichenbehaftete Ganzzahlen über std::int64_t [SWS_DM_02241], Fließkommazahlen via double [SWS_DM_02243], Wahrheitswerte über bool [SWS_DM_02244], Zeichenketten via ara::core::StringView [SWS_DM_02245] oder strukturierte Elemente des Typs DiagnosticSovdContentElementData [SWS_DM_02246] verarbeiten. Eine gleichartige Implementierung für std::uint64_t wird zudem von DiagnosticSovdContentElementData bereitgestellt [SWS_DM_02347].

Verwendung

Die synchrone Methode PushBack wird über die Header-Datei #include "ara/diag/diagnostic_sovd_content_element_data.h" im Scope der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView bereitgestellt ([SWS_DM_02243], AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.13 „PushBack“). Sie hängt einen primitiven Gleitkommawert vom Typ double als Inhaltselement an ein bestehendes Array an ([SWS_DM_02243]). Der einzige Übergabeparameter ist das anzufügende Datum content_element.

Fehlerbehandlung und Randbedingungen

Die Funktion gibt ein ara::core::Result<void> zurück ([SWS_DM_02243]). Eine erfolgreiche Ausführung setzt voraus, dass das aktuelle Element vom Typ ArrayContentElementData ist und das hinzuzufügende Element dem im Konstruktor von ArrayContentElementData festgelegten Typ entspricht ([SWS_DM_02243]). Sofern das Ziel nicht vom Typ ArrayContentElementData ist, schlägt die Operation fehl und gibt einen Fehler im Result zurück ([SWS_DM_02243]).

Nebenläufigkeit

Die Funktion ist als noexcept deklariert, gewährleistet Exception-Sicherheit (exception safe) und ist laut Spezifikation thread-safe ([SWS_DM_02243]). Mehrere Threads können die Funktion daher nebenläufig ohne externe Synchronisation aufrufen.

Zusammenspiel

Innerhalb von DiagnosticSovdArrayContentElementDataView existieren typgleiche Überladungen für weitere primitive Datentypen, darunter std::int64_t ([SWS_DM_02241]), std::uint64_t ([SWS_DM_02242]), bool ([SWS_DM_02244]), ara::core::StringView ([SWS_DM_02245]) sowie für vollständige DiagnosticSovdContentElementData-Objekte ([SWS_DM_02246]). Analoge Methoden stehen auch auf DiagnosticSovdContentElementData zur Verfügung (z. B. [SWS_DM_02348]).

Die Elementfunktion PushBack dient dazu, ein DiagnosticSovdContentElementData mit dem primitiven Datentyp bool an ein bestehendes Array-Element anzuhängen ([SWS_DM_02244]). Die Schnittstelle ist im Header ara/diag/diagnostic_sovd_content_element_data.h innerhalb der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView definiert (AUTOSAR_AP_SWS_Diagnostics §8.60.5.1.1.12 „PushBack“). Als Eingabeparameter nimmt die synchrone Funktion den Wahrheitswert content_element entgegen ([SWS_DM_02244]).

Voraussetzung für den Aufruf ist, dass das aktuelle Element vom Typ ArrayContentElementData ist und der anzufügende Wert mit dem Typ übereinstimmt, der im Konstruktor der Datenstruktur deklariert wurde ([SWS_DM_02244]). Ist das Zielelement nicht vom Typ ArrayContentElementData, schlägt die Operation fehl und liefert ein ara::core::Result<void> mit einem entsprechenden Fehler zurück; im Erfolgsfall enthält das Ergebnis ein leeres void ([SWS_DM_02244]).

Hinsichtlich der Ausführungssicherheit ist die Methode als noexcept deklariert sowie als threadsicher (thread-safe) und ausnahmesicher (exception safe) spezifiziert ([SWS_DM_02244]).

Die Methode ist Bestandteil einer Familie typisierter PushBack-Überladungen innerhalb von DiagnosticSovdArrayContentElementDataView. Neben booleschen Werten decken Geschwisterfunktionen das Einfügen von ganzzahligen Typen wie std::int64_t ([SWS_DM_02241]) und std::uint64_t ([SWS_DM_02242]), Fließkommawerten double ([SWS_DM_02243]), Zeichenketten ara::core::StringView ([SWS_DM_02245]) sowie komplexen Datenelementen ([SWS_DM_02246]) ab. Korrespondierende Operationen stehen zudem auf der Ebene von DiagnosticSovdContentElementData zur Verfügung, darunter die boolesche Variante [SWS_DM_02349].

Verwendung

Die synchrone Elementfunktion PushBack der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView ([SWS_DM_02245], definiert in SWS Diagnostics §8.60.5.1.1.11 „PushBack“) fügt ein neues Element mit dem primitiven Typ Zeichenkette an ein diagnostisches SOVD-Array an. Hierfür muss der Header ara/diag/diagnostic_sovd_content_element_data.h eingebunden werden. Die Funktion übernimmt das hinzuzufügende Element über den Parameter content_element vom Typ ara::core::StringView.

Fehlerbehandlung

Als Rückgabetyp dient ara::core::Result<void>. Ein Fehler wird im Ergebnisobjekt zurückgegeben, falls das aktuelle Objekt nicht vom Typ ArrayContentElementData ist oder der Typ des übergebenen Elements nicht mit dem im Konstruktor von ArrayContentElementData festgelegten Elementtyp übereinstimmt ([SWS_DM_02245]).

Nebenläufigkeit und Einschränkungen

Die Funktion ist mit dem Spezifizierer noexcept deklariert. Sie bietet garantierte Exception-Sicherheit (exception safe) und ist uneingeschränkt threadsicher (thread-safe) spezifiziert ([SWS_DM_02245]).

Zusammenspiel

Die Operation ist Teil einer Familie überladener Methoden. Innerhalb von DiagnosticSovdArrayContentElementDataView existieren weitere Überladungen für skalare Typen wie std::int64_t ([SWS_DM_02241]), std::uint64_t ([SWS_DM_02242]), double ([SWS_DM_02243]) und bool ([SWS_DM_02244]) sowie für vollständige Elemente vom Typ DiagnosticSovdContentElementData ([SWS_DM_02246]). Zudem stellt auch die Klasse ara::diag::DiagnosticSovdContentElementData eine entsprechende PushBack-Schnittstelle für Zeichenketten bereit ([SWS_DM_02350]).

Verwendung

Die synchrone Memberfunktion PushBack der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView (SWS Diagnostics §8.60.5.1.1.10 „PushBack“) fügt ein Element vom Typ DiagnosticSovdContentElementData an eine bestehende Array-Datenansicht an ([SWS_DM_02246]). Als Übergabeparameter übernimmt sie das hinzuzufügende Objekt content_element per Wert und besitzt keinen Rückgabewert (void). Die Deklaration wird über die Header-Datei ara/diag/diagnostic_sovd_content_element_data.h bereitgestellt.

Nebenläufigkeit und Vorbedingungen

Die Spezifikation definiert die Funktion als ausnahmesicher (exception safe), threadsicher (thread-safe) und mit noexcept annotiert ([SWS_DM_02246]). Als verbindliche Vorbedingung verlangt die Operation, dass das aktuelle Element vom Typ ArrayContentElementData ist und das anzuhängende Element genau dem Typ entspricht, der im Konstruktor von ArrayContentElementData festgelegt wurde ([SWS_DM_02246]).

Fehlerbehandlung und Zusammenspiel

Im Unterschied zu den Überladungen für Primitivtypen wie std::int64_t ([SWS_DM_02241]), std::uint64_t ([SWS_DM_02242]), double ([SWS_DM_02243]), bool ([SWS_DM_02244]) oder ara::core::StringView ([SWS_DM_02245]), welche ein ara::core::Result<void> zur Fehlerübermittlung zurückgeben, liefert diese Methode void. Es dürfte daher in der Verantwortung des Aufrufers liegen, die Typkompatibilität vorab zu prüfen, da Laufzeitfehler an dieser Schnittstelle nicht über einen Result-Typ signalisiert werden. Frage Q-00739dff7d34e242 (offen) Eine äquivalente Methode zum Anhängen von Datenelementen ist auch auf DiagnosticSovdContentElementData definiert ([SWS_DM_02351]).

Die synchrone Methode Reserve der Klasse ara::diag::DiagnosticSovdArrayContentElementDataView dient der Vorab-Allokation von Speicherkapazität für Array-Datenelemente ([SWS_DM_02240], SWS Diagnostics §8.60.5.1.1.16 „Reserve“). Sie wird über den Header #include "ara/diag/diagnostic_sovd_content_element_data.h" bereitgestellt und nimmt den Parameter capacity vom Typ std::size_t entgegen, der die bereitzustellende Kapazität der zugrunde liegenden DiagnosticSovdArrayContentElementData festlegt ([SWS_DM_02240]). Ein Rückgabewert wird nicht zurückgegeben ([SWS_DM_02240]).

Hinsichtlich der Fehlerbehandlung ist die Funktion als ausnahmesicher (exception safe) sowie noexcept deklariert ([SWS_DM_02240]). Sie verwendet weder Fehlercodes über ara::core::Result noch C++-Exceptions. Interpretation: Bei einem Speicherengpass dürfte die Allokation intern fehlschlagen oder zum Programmabbruch führen, da dem Aufrufer kein Fehlerkanal zur Verfügung steht. Frage Q-348805197c004eea (offen)

Für die Nebenläufigkeit ist die Operation explizit als threadsicher (thread-safe) spezifiziert ([SWS_DM_02240]). Aufrufe können somit ohne externe Verriegelung aus parallelen Threads erfolgen.

Im Gesamtsystem ergänzt die Schnittstelle verwandte Reservierungsfunktionen: Während DiagnosticSovdRecordContentElementDataView::Reserve analog für Record-Datenstrukturen zuständig ist ([SWS_DM_02283], SWS Diagnostics §8.60.11.1.1.20 „Reserve“), liefert die allgemeine Basisklassenfunktion DiagnosticSovdContentElementData::Reserve ein ara::core::Result<void>, um bei falschem Elementtyp einen Fehler zu melden ([SWS_DM_02345], SWS Diagnostics §8.60.6.1.2.55 „Reserve“). Im Unterschied zur nicht threadsicheren Speicherreservierung DiagnosticServiceDynamicAccessList::Reserve ([SWS_DM_01163], SWS Diagnostics §8.13.1.1.3.3 „Reserve“) arbeitet diese View-Methode direkt und nebenläufig auf SOVD-Array-Elementen.