hold — Control plot replacement versus appending in MATLAB and RunMat.
hold controls whether new plotting commands append to the current axes or replace existing plot objects. Per-axes hold state and command forms follow MATLAB semantics.
Syntax
hold()
hold(mode)
hold(ax, mode)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
mode | Any | No | "toggle" | Hold mode ('on'|'off'|'all') or numeric/logical scalar. |
ax | AxesHandle | Yes | — | Target axes. |
mode | Any | Yes | — | Hold mode ('on'|'off'|'all') or numeric/logical scalar. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:hold:InvalidArgument | Hold mode argument is unsupported. | hold: invalid argument |
How hold works
hold()toggles the current hold state.hold('on')enables appending to the current axes.hold('off')disables appending so later plots replace the axes contents.hold('all')is currently treated the same ashold('on').- Logical and numeric scalar inputs are accepted: zero means off and one means on.
- An axes handle can be supplied before the mode to update that axes.
Does RunMat run hold on the GPU?
hold performs no provider dispatch; it updates per-axes plotting state in the host-side registry.
GPU memory and residency
hold only mutates plotting state and does not affect array residency.
Examples
Append a second line to the same axes
x = 0:0.1:1;
plot(x, x);
hold on;
plot(x, x.^2);Expected output:
% both lines remain visible on the current axesDisable appending again
hold off;
plot(1:5, [5 4 3 2 1]);Expected output:
% the new plot replaces the previous axes contentsToggle hold state
hold();
hold();Expected output:
% each call toggles the current axes hold stateUsing hold with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how hold changes the result.
Run a small hold example, explain the result, then change one input and compare the output.
FAQ
Is hold state per figure or per axes?⌄
It is tracked per axes, so one subplot can be in hold mode while another is not.
What does hold('all') do?⌄
RunMat currently treats 'all' the same as 'on'.
Does hold return the current state?⌄
No. hold mutates axes state and has no public output.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how hold is executed, line by line, in Rust.
- View the source for hold in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.