Why does Matlab care how many output arguments I specify?

I've never known any native Matlab function to place a requirement on the number of ouput arguments that I request. For some reason getpoints() is an exception. Why does it care?

h = animatedline;
axis([0,4*pi,-1,1])

x = linspace(0,4*pi,1000);
y = sin(x);
for k = 1:length(x)
    addpoints(h,x(k),y(k));
    drawnow
end

[X,~] = getpoints(h)

X = 1×1000

0 0.0126 0.0252 0.0377 0.0503 0.0629 0.0755 0.0881 0.1006 0.1132 0.1258 0.1384 0.1509 0.1635 0.1761 0.1887 0.2013 0.2138 0.2264 0.2390 0.2516 0.2642 0.2767 0.2893 0.3019 0.3145 0.3271 0.3396 0.3522 0.3648

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

X=getpoints(h)

Error using matlab.graphics.animation.AnimatedLine/getpoints
Specify either two or three output arguments.

[Chuguang Pan]

@Matt J. MATLAB use nargout to check the number of function output arguments. The getpoints function maybe use the nargout to guarantee that the number of function output arguments is greater than 1.

Answer 1

[dpb]

help getpoints

 getpoints - Return points that define animated line

    Syntax
      [x,y] = getpoints(an)
      [x,y,z] = getpoints(an)

    Input Arguments
      an - AnimatedLine object
        AnimatedLine object

    Output Arguments
      x - First coordinate values
        vector
      y - Second coordinate values
        vector
      z - Third coordinate values
        vector

    Examples
      openExample('graphics/ReturnPointsFromAnimatedLineExample')

    See also animatedline, addpoints, clearpoints, AnimatedLine Properties

    Introduced in MATLAB in R2014b
    Documentation for getpoints
       doc getpoints

Apparently MathWorks chose to make it a requirement to match its stated purpose to retrieve the points that make up an animated line object and that while the user may have reasons for only retrieving one dimension, the values obtained wouldn't be sufficient to recreate the object. Simply an internal design decision since there would be no fundamental reason that the function itself couldn't behave in a fashion consistent with overall MATLAB practice.

It is at least highly unusual (if not totally unique?) behavior, granted. Only somebody inside and on the design and implementation team would be able to say more definitively, of course. :>)

ADDENDUM:

Wonder if it knows enough depending upon the animated line itself?

h = animatedline;
N=10;
for k = 1:N
  addpoints(h,rand,rand,rand);
  drawnow
end

Warning: Graphics acceleration hardware is unavailable. Graphics quality and performance might be diminished. See MATLAB System Requirements.

view(-37.5,30)
grid on

[X,Y]=getpoints(h)

X = 1×10

0.5396 0.2867 0.8253 0.2297 0.1373 0.7132 0.7034 0.0280 0.8111 0.1784

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

Y = 1×10

0.4115 0.4045 0.9757 0.4389 0.6266 0.7855 0.0756 0.3378 0.9604 0.8120

<mw-icon class=""></mw-icon>

<mw-icon class=""></mw-icon>

No, it apparently only enforces >1, not as many as are actually required for the animatedline object itself which doesn't expose whether it was created with two or three coordinates; internally one would guess probably always three, just default for the third if not given.

get(h)

    AlignVertexCenters: off
            Annotation: [1×1 matlab.graphics.eventdata.Annotation]
          BeingDeleted: off
            BusyAction: 'queue'
         ButtonDownFcn: ''
              Children: [0×0 GraphicsPlaceholder]
              Clipping: on
                 Color: [0.1294 0.1294 0.1294]
             ColorMode: 'auto'
           ContextMenu: [0×0 GraphicsPlaceholder]
             CreateFcn: ''
             DeleteFcn: ''
           DisplayName: ''
      HandleVisibility: 'on'
               HitTest: on
         Interruptible: on
             LineStyle: '-'
         LineStyleMode: 'auto'
             LineWidth: 0.5000
                Marker: 'none'
       MarkerEdgeColor: 'auto'
       MarkerFaceColor: 'none'
            MarkerMode: 'auto'
            MarkerSize: 6
      MaximumNumPoints: 1000000
                Parent: [1×1 Axes]
         PickableParts: 'visible'
              Selected: off
    SelectionHighlight: on
           SeriesIndex: 'none'
                   Tag: ''
                  Type: 'animatedline'
              UserData: []
               Visible: on

ADDENDUM SECOND

I notice the documentation doesn't note anywhere that at least the two outputs are required. I don't know that the behavior is sufficient to justify an enhancement request to modify its behavior, but it does look as though a documentation update would be in order.

[Torsten]

Quite inconsistent that there is an error message with one output argument and 2d-data as input and no error message with two output arguments and 3d-data as input ...

[dpb]

Indeed, why I tried the test...using struct(h) on the handle and poking around didn't immediately find a way to determine about the dimensionality. Although somewhere in the bowels there has to be the associated data, it isn't readily visible outside using the associated getpoints function. It does seem on the surface to be a totally superfluous requirement.