WPILibC++ 2024.3.2
frc2::CommandPtr Class Referencefinal

A wrapper around std::unique_ptr<Command> so commands have move-only semantics. More...

#include <frc2/command/CommandPtr.h>

Public Member Functions

 CommandPtr (std::unique_ptr< Command > &&command)
 
template<std::derived_from< Command > T>
 CommandPtr (T &&command)
 
 CommandPtr (CommandPtr &&)
 
CommandPtroperator= (CommandPtr &&)=default
 
 CommandPtr (std::nullptr_t)=delete
 
CommandPtr Repeatedly () &&
 Decorates this command to run repeatedly, restarting it when it ends, until this command is interrupted. More...
 
CommandPtr AsProxy () &&
 Decorates this command to run "by proxy" by wrapping it in a ProxyCommand. More...
 
CommandPtr IgnoringDisable (bool doesRunWhenDisabled) &&
 Decorates this command to run or stop when disabled. More...
 
CommandPtr WithInterruptBehavior (Command::InterruptionBehavior interruptBehavior) &&
 Decorates this command to have a different interrupt behavior. More...
 
CommandPtr AndThen (std::function< void()> toRun, Requirements requirements={}) &&
 Decorates this command with a runnable to run after the command finishes. More...
 
CommandPtr AndThen (CommandPtr &&next) &&
 Decorates this command with a set of commands to run after it in sequence. More...
 
CommandPtr BeforeStarting (std::function< void()> toRun, Requirements requirements={}) &&
 Decorates this command with a runnable to run before this command starts. More...
 
CommandPtr BeforeStarting (CommandPtr &&before) &&
 Decorates this command with another command to run before this command starts. More...
 
CommandPtr WithTimeout (units::second_t duration) &&
 Decorates this command with a timeout. More...
 
CommandPtr Until (std::function< bool()> condition) &&
 Decorates this command with an interrupt condition. More...
 
CommandPtr OnlyWhile (std::function< bool()> condition) &&
 Decorates this command with a run condition. More...
 
CommandPtr Unless (std::function< bool()> condition) &&
 Decorates this command to only run if this condition is not met. More...
 
CommandPtr OnlyIf (std::function< bool()> condition) &&
 Decorates this command to only run if this condition is met. More...
 
CommandPtr DeadlineWith (CommandPtr &&parallel) &&
 Decorates this command with a set of commands to run parallel to it, ending when the calling command ends and interrupting all the others. More...
 
CommandPtr AlongWith (CommandPtr &&parallel) &&
 Decorates this command with a set of commands to run parallel to it, ending when the last command ends. More...
 
CommandPtr RaceWith (CommandPtr &&parallel) &&
 Decorates this command with a set of commands to run parallel to it, ending when the first command ends. More...
 
CommandPtr FinallyDo (std::function< void(bool)> end) &&
 Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method. More...
 
CommandPtr FinallyDo (std::function< void()> end) &&
 Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method. More...
 
CommandPtr HandleInterrupt (std::function< void()> handler) &&
 Decorates this command with a lambda to call on interrupt, following the command's inherent Command::End(bool) method. More...
 
CommandPtr WithName (std::string_view name) &&
 Decorates this Command with a name. More...
 
Commandget () const &
 Get a raw pointer to the held command. More...
 
Commandget () &&=delete
 
std::unique_ptr< CommandUnwrap () &&
 Convert to the underlying unique_ptr. More...
 
void Schedule () const &
 Schedules this command. More...
 
void Schedule () &&=delete
 
void Cancel () const &
 Cancels this command. More...
 
void Cancel () &&=delete
 
bool IsScheduled () const &
 Whether or not the command is currently scheduled. More...
 
void IsScheduled () &&=delete
 
bool HasRequirement (Subsystem *requirement) const &
 Whether the command requires a given subsystem. More...
 
void HasRequirement (Subsystem *requirement) &&=delete
 
 operator bool () const &
 Check if this CommandPtr object is valid and wasn't moved-from. More...
 
 operator bool () &&=delete
 

Static Public Member Functions

static std::vector< std::unique_ptr< Command > > UnwrapVector (std::vector< CommandPtr > &&vec)
 Convert a vector of CommandPtr objects to their underlying unique_ptrs. More...
 

Detailed Description

A wrapper around std::unique_ptr<Command> so commands have move-only semantics.

Commands should only be stored and passed around when held in a CommandPtr instance. For more info, see https://github.com/wpilibsuite/allwpilib/issues/4303.

Various classes in the command-based library accept a std::unique_ptr<Command>, use CommandPtr::Unwrap to convert. CommandPtr::UnwrapVector does the same for vectors.

Constructor & Destructor Documentation

◆ CommandPtr() [1/4]

frc2::CommandPtr::CommandPtr ( std::unique_ptr< Command > &&  command)
explicit

◆ CommandPtr() [2/4]

template<std::derived_from< Command > T>
frc2::CommandPtr::CommandPtr ( T &&  command)
inlineexplicit

◆ CommandPtr() [3/4]

frc2::CommandPtr::CommandPtr ( CommandPtr &&  )

◆ CommandPtr() [4/4]

frc2::CommandPtr::CommandPtr ( std::nullptr_t  )
explicitdelete

Member Function Documentation

◆ AlongWith()

CommandPtr frc2::CommandPtr::AlongWith ( CommandPtr &&  parallel) &&

Decorates this command with a set of commands to run parallel to it, ending when the last command ends.

Often more convenient/less-verbose than constructing a new ParallelCommandGroup explicitly.

Parameters
parallelthe commands to run in parallel
Returns
the decorated command

◆ AndThen() [1/2]

CommandPtr frc2::CommandPtr::AndThen ( CommandPtr &&  next) &&

Decorates this command with a set of commands to run after it in sequence.

Often more convenient/less-verbose than constructing a new SequentialCommandGroup explicitly.

Parameters
nextthe commands to run next
Returns
the decorated command

◆ AndThen() [2/2]

CommandPtr frc2::CommandPtr::AndThen ( std::function< void()>  toRun,
Requirements  requirements = {} 
) &&

Decorates this command with a runnable to run after the command finishes.

Parameters
toRunthe Runnable to run
requirementsthe required subsystems
Returns
the decorated command

◆ AsProxy()

CommandPtr frc2::CommandPtr::AsProxy ( ) &&

Decorates this command to run "by proxy" by wrapping it in a ProxyCommand.

This is useful for "forking off" from command groups when the user does not wish to extend the command's requirements to the entire command group.

Returns
the decorated command

◆ BeforeStarting() [1/2]

CommandPtr frc2::CommandPtr::BeforeStarting ( CommandPtr &&  before) &&

Decorates this command with another command to run before this command starts.

Parameters
beforethe command to run before this one
Returns
the decorated command

◆ BeforeStarting() [2/2]

CommandPtr frc2::CommandPtr::BeforeStarting ( std::function< void()>  toRun,
Requirements  requirements = {} 
) &&

Decorates this command with a runnable to run before this command starts.

Parameters
toRunthe Runnable to run
requirementsthe required subsystems
Returns
the decorated command

◆ Cancel() [1/2]

void frc2::CommandPtr::Cancel ( ) &&
delete

◆ Cancel() [2/2]

void frc2::CommandPtr::Cancel ( ) const &

Cancels this command.

Will call End(true). Commands will be canceled regardless of interruption behavior.

◆ DeadlineWith()

CommandPtr frc2::CommandPtr::DeadlineWith ( CommandPtr &&  parallel) &&

Decorates this command with a set of commands to run parallel to it, ending when the calling command ends and interrupting all the others.

Often more convenient/less-verbose than constructing a new ParallelDeadlineGroup explicitly.

Parameters
parallelthe commands to run in parallel
Returns
the decorated command

◆ FinallyDo() [1/2]

CommandPtr frc2::CommandPtr::FinallyDo ( std::function< void()>  end) &&

Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method.

The provided lambda will run identically in both interrupt and end cases.

Parameters
enda lambda to run when the command ends, whether or not it was interrupted.
Returns
the decorated command

◆ FinallyDo() [2/2]

CommandPtr frc2::CommandPtr::FinallyDo ( std::function< void(bool)>  end) &&

Decorates this command with a lambda to call on interrupt or end, following the command's inherent Command::End(bool) method.

Parameters
enda lambda accepting a boolean parameter specifying whether the command was interrupted
Returns
the decorated command

◆ get() [1/2]

Command * frc2::CommandPtr::get ( ) &&
delete

◆ get() [2/2]

Command * frc2::CommandPtr::get ( ) const &

Get a raw pointer to the held command.

◆ HandleInterrupt()

CommandPtr frc2::CommandPtr::HandleInterrupt ( std::function< void()>  handler) &&

Decorates this command with a lambda to call on interrupt, following the command's inherent Command::End(bool) method.

Parameters
handlera lambda to run when the command is interrupted
Returns
the decorated command

◆ HasRequirement() [1/2]

void frc2::CommandPtr::HasRequirement ( Subsystem requirement) &&
delete

◆ HasRequirement() [2/2]

bool frc2::CommandPtr::HasRequirement ( Subsystem requirement) const &

Whether the command requires a given subsystem.

Named "HasRequirement" rather than "requires" to avoid confusion with Command::Requires(Subsystem) – this may be able to be changed in a few years.

Parameters
requirementthe subsystem to inquire about
Returns
whether the subsystem is required

◆ IgnoringDisable()

CommandPtr frc2::CommandPtr::IgnoringDisable ( bool  doesRunWhenDisabled) &&

Decorates this command to run or stop when disabled.

Parameters
doesRunWhenDisabledtrue to run when disabled
Returns
the decorated command

◆ IsScheduled() [1/2]

void frc2::CommandPtr::IsScheduled ( ) &&
delete

◆ IsScheduled() [2/2]

bool frc2::CommandPtr::IsScheduled ( ) const &

Whether or not the command is currently scheduled.

Note that this does not detect whether the command is in a composition, only whether it is directly being run by the scheduler.

Returns
Whether the command is scheduled.

◆ OnlyIf()

CommandPtr frc2::CommandPtr::OnlyIf ( std::function< bool()>  condition) &&

Decorates this command to only run if this condition is met.

If the command is already running and the condition changes to false, the command will not stop running. The requirements of this command will be kept for the new conditional command.

Parameters
conditionthe condition that will allow the command to run
Returns
the decorated command

◆ OnlyWhile()

CommandPtr frc2::CommandPtr::OnlyWhile ( std::function< bool()>  condition) &&

Decorates this command with a run condition.

If the specified condition becomes false before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
conditionthe run condition
Returns
the command with the run condition added

◆ operator bool() [1/2]

frc2::CommandPtr::operator bool ( ) &&
explicitdelete

◆ operator bool() [2/2]

frc2::CommandPtr::operator bool ( ) const &
explicit

Check if this CommandPtr object is valid and wasn't moved-from.

◆ operator=()

CommandPtr & frc2::CommandPtr::operator= ( CommandPtr &&  )
default

◆ RaceWith()

CommandPtr frc2::CommandPtr::RaceWith ( CommandPtr &&  parallel) &&

Decorates this command with a set of commands to run parallel to it, ending when the first command ends.

Often more convenient/less-verbose than constructing a new ParallelRaceGroup explicitly.

Parameters
parallelthe commands to run in parallel
Returns
the decorated command

◆ Repeatedly()

CommandPtr frc2::CommandPtr::Repeatedly ( ) &&

Decorates this command to run repeatedly, restarting it when it ends, until this command is interrupted.

The decorated command can still be canceled.

Returns
the decorated command

◆ Schedule() [1/2]

void frc2::CommandPtr::Schedule ( ) &&
delete

◆ Schedule() [2/2]

void frc2::CommandPtr::Schedule ( ) const &

Schedules this command.

◆ Unless()

CommandPtr frc2::CommandPtr::Unless ( std::function< bool()>  condition) &&

Decorates this command to only run if this condition is not met.

If the command is already running and the condition changes to true, the command will not stop running. The requirements of this command will be kept for the new conditional command.

Parameters
conditionthe condition that will prevent the command from running
Returns
the decorated command

◆ Until()

CommandPtr frc2::CommandPtr::Until ( std::function< bool()>  condition) &&

Decorates this command with an interrupt condition.

If the specified condition becomes true before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
conditionthe interrupt condition
Returns
the command with the interrupt condition added

◆ Unwrap()

std::unique_ptr< Command > frc2::CommandPtr::Unwrap ( ) &&

Convert to the underlying unique_ptr.

◆ UnwrapVector()

static std::vector< std::unique_ptr< Command > > frc2::CommandPtr::UnwrapVector ( std::vector< CommandPtr > &&  vec)
static

Convert a vector of CommandPtr objects to their underlying unique_ptrs.

◆ WithInterruptBehavior()

CommandPtr frc2::CommandPtr::WithInterruptBehavior ( Command::InterruptionBehavior  interruptBehavior) &&

Decorates this command to have a different interrupt behavior.

Parameters
interruptBehaviorthe desired interrupt behavior
Returns
the decorated command

◆ WithName()

CommandPtr frc2::CommandPtr::WithName ( std::string_view  name) &&

Decorates this Command with a name.

Is an inline function for Command::SetName(std::string_view);

Parameters
namename
Returns
the decorated Command

◆ WithTimeout()

CommandPtr frc2::CommandPtr::WithTimeout ( units::second_t  duration) &&

Decorates this command with a timeout.

If the specified timeout is exceeded before the command finishes normally, the command will be interrupted and un-scheduled.

Parameters
durationthe timeout duration
Returns
the command with the timeout added

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