Drake
Classes | Public Types | Public Member Functions | List of all members
SystemScalarConverter Class Reference

Detailed Description

Helper class to convert a System into a System<T>, intended for internal use by the System framework, not directly by users.

For user-facing documentation see System Scalar Conversion.

Because it is not templated on a System subclass, this class can be used by LeafSystem without any direct knowledge of the subtypes being converted. In other words, it enables a runtime flavor of the CRTP.

Throughout this class, the template type S must be the most-derived concrete System subclass. This object may only be used to convert System objects of runtime type S, not subclasses of S.

#include <drake/systems/framework/system_scalar_converter.h>

Public Types

enum  GuaranteedSubtypePreservation { kEnabled, kDisabled }
 A configuration option for our constructor, controlling whether or not the Convert implementation requires that the System subclass type is preserved. More...
 
template<typename T , typename U >
using ConverterFunction = std::function< std::unique_ptr< System< T > >(const System< U > &)>
 A std::function used to convert a System into a System<T>. More...
 

Public Member Functions

 SystemScalarConverter ()
 Creates an object that returns nullptr for all Convert() requests. More...
 
template<template< typename > class S>
 SystemScalarConverter (SystemTypeTag< S > tag)
 Creates an object that uses S's scalar-type converting copy constructor. More...
 
template<template< typename > class S>
 SystemScalarConverter (SystemTypeTag< S >, GuaranteedSubtypePreservation subtype_preservation)
 (Advanced) Creates using S's scalar-type converting copy constructor. More...
 
bool empty () const
 Returns true iff no conversions are supported. More...
 
template<typename T , typename U >
void Add (const ConverterFunction< T, U > &)
 Registers the std::function to be used to convert a System into a System<T>. More...
 
template<template< typename > class S, typename T , typename U >
void AddIfSupported ()
 Adds converter for an S into an S<T>, iff scalar_conversion::Traits says its supported. More...
 
void RemoveUnlessAlsoSupportedBy (const SystemScalarConverter &other)
 Removes from this converter all pairs where other.IsConvertible<T, U> is false. More...
 
template<typename T >
void Remove ()
 Removes from this converter the ability to convert to or from System<T>. More...
 
template<typename T , typename U >
bool IsConvertible () const
 Returns true iff this object can convert a System into a System<T>, i.e., whether Convert() will return non-null. More...
 
template<typename T , typename U >
std::unique_ptr< System< T > > Convert (const System< U > &other) const
 Converts a System into a System<T>. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 SystemScalarConverter (const SystemScalarConverter &)=default
 
SystemScalarConverter & operator= (const SystemScalarConverter &)=default
 
 SystemScalarConverter (SystemScalarConverter &&)=default
 
SystemScalarConverter & operator= (SystemScalarConverter &&)=default
 

Member Typedef Documentation

◆ ConverterFunction

using ConverterFunction = std::function<std::unique_ptr<System<T> >(const System<U>&)>

A std::function used to convert a System into a System<T>.

Member Enumeration Documentation

◆ GuaranteedSubtypePreservation

enum GuaranteedSubtypePreservation
strong

A configuration option for our constructor, controlling whether or not the Convert implementation requires that the System subclass type is preserved.

Enumerator
kEnabled 

The argument to Convert must be of the exact type S that was used to populate the SystemScalarConverter.

kDisabled 

The argument to Convert need not be the exact type S that was used to populate the SystemScalarConverter – it can be either exactly that S, or a subtype of that S.

This permits subtype information to be lost across conversion.

Constructor & Destructor Documentation

◆ SystemScalarConverter() [1/5]

SystemScalarConverter ( const SystemScalarConverter &  )
default

◆ SystemScalarConverter() [2/5]

SystemScalarConverter ( SystemScalarConverter &&  )
default

◆ SystemScalarConverter() [3/5]

SystemScalarConverter ( )

Creates an object that returns nullptr for all Convert() requests.

The single-argument constructor below is the typical way to create a useful instance of this type.

◆ SystemScalarConverter() [4/5]

SystemScalarConverter ( SystemTypeTag< S >  tag)

Creates an object that uses S's scalar-type converting copy constructor.

That constructor takes the form of, e.g.:

template <typename T>
class Foo {
template <typename U>
explicit Foo(const Foo<U>& other);
};

This constructor only creates a converter between a limited set of types, specifically the default scalars.

By default, all non-identity pairs (pairs where T and U differ) drawn from the above list can be used for T and U. Systems may specialize scalar_conversion::Traits to disable support for some or all of these conversions, or after construction may call Add<T, U>() on the returned object to enable support for additional custom types.

Template Parameters
Sis the System type to convert

This an implicit conversion constructor (not marked explicit), in order to make calling code substantially more readable, with relatively little risk of an unwanted accidental conversion happening.

See System Scalar Conversion for additional overview documentation.

◆ SystemScalarConverter() [5/5]

SystemScalarConverter ( SystemTypeTag< S >  ,
GuaranteedSubtypePreservation  subtype_preservation 
)

(Advanced) Creates using S's scalar-type converting copy constructor.

Behaves exactly like SystemScalarConverter(SystemTypeTag<S>), but with the additional option to turn off guaranteed subtype preservation of the System being converted. In general, subtype preservation is an important invariant during scalar conversion, so be cautious about disabling it.

Member Function Documentation

◆ Add()

void Add ( const ConverterFunction< T, U > &  )

Registers the std::function to be used to convert a System into a System<T>.

A pair of types can be registered (added) at most once.

◆ AddIfSupported()

void AddIfSupported ( )

Adds converter for an S into an S<T>, iff scalar_conversion::Traits says its supported.

The converter uses S's scalar-type converting copy constructor.

◆ Convert()

std::unique_ptr<System<T> > Convert ( const System< U > &  other) const

Converts a System into a System<T>.

This is the API that LeafSystem uses to provide a default implementation of DoToAutoDiffXd, etc.

Template Parameters
Uthe donor scalar type (to convert from)
Tthe resulting scalar type (to convert into)

◆ empty()

bool empty ( ) const

Returns true iff no conversions are supported.

(In other words, whether this is a default-constructed object.)

◆ IsConvertible()

bool IsConvertible ( ) const

Returns true iff this object can convert a System into a System<T>, i.e., whether Convert() will return non-null.

Template Parameters
Uthe donor scalar type (to convert from)
Tthe resulting scalar type (to convert into)

◆ operator=() [1/2]

SystemScalarConverter& operator= ( SystemScalarConverter &&  )
default

◆ operator=() [2/2]

SystemScalarConverter& operator= ( const SystemScalarConverter &  )
default

◆ Remove()

void Remove ( )

Removes from this converter the ability to convert to or from System<T>.

◆ RemoveUnlessAlsoSupportedBy()

void RemoveUnlessAlsoSupportedBy ( const SystemScalarConverter &  other)

Removes from this converter all pairs where other.IsConvertible<T, U> is false.

The subtype S need not be the same between this and other.

The documentation for this class was generated from the following file: