1########################################################################
2##
3## Copyright (C) 2000-2021 The Octave Project Developers
4##
5## See the file COPYRIGHT.md in the top-level directory of this
6## distribution or <https://octave.org/copyright/>.
7##
8## This file is part of Octave.
9##
10## Octave is free software: you can redistribute it and/or modify it
11## under the terms of the GNU General Public License as published by
12## the Free Software Foundation, either version 3 of the License, or
13## (at your option) any later version.
14##
15## Octave is distributed in the hope that it will be useful, but
16## WITHOUT ANY WARRANTY; without even the implied warranty of
17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18## GNU General Public License for more details.
19##
20## You should have received a copy of the GNU General Public License
21## along with Octave; see the file COPYING.  If not, see
22## <https://www.gnu.org/licenses/>.
23##
24########################################################################
25
26## -*- texinfo -*-
27## @deftypefn {} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp})
28##
29## Extract the components of a piecewise polynomial structure @var{pp}.
30##
31## This function is the inverse of @code{mkpp}: it extracts the inputs to
32## @code{mkpp} needed to create the piecewise polynomial structure @var{PP}.
33## The code below makes this relation explicit:
34##
35## @example
36## @group
37## [breaks, coefs, numinter, order, dim] = unmkpp (pp);
38## pp2  = mkpp (breaks, coefs, dim);
39## @end group
40## @end example
41##
42## The piecewise polynomial structure @code{pp2} obtained in this way, is
43## identical to the original @code{pp}.  The same can be obtained by directly
44## accessing the fields of the structure @code{pp}.
45##
46## The components are:
47##
48## @table @asis
49## @item @var{x}
50## Sample points or breaks.
51##
52## @item @var{p}
53## Polynomial coefficients for points in sample interval.
54## @code{@var{p}(@var{i}, :)} contains the coefficients for the polynomial
55## over interval @var{i} ordered from highest to lowest degree.
56## If @code{@var{d} > 1}, then @var{p} is a matrix of size
57## @code{[@var{n}*prod(@var{d}) @var{m}]}, where the
58## @code{@var{i} + (1:@var{d})} rows are the coefficients of all the @var{d}
59## polynomials in the interval @var{i}.
60##
61## @item @var{n}
62## Number of polynomial pieces or intervals,
63## @code{@var{n} = length (@var{x}) - 1}.
64##
65## @item @var{k}
66## Order of the polynomial plus 1.
67##
68## @item @var{d}
69## Number of polynomials defined for each interval.
70## @end table
71##
72## @seealso{mkpp, ppval, spline, pchip}
73## @end deftypefn
74
75function [x, P, n, k, d] = unmkpp (pp)
76
77  if (nargin != 1)
78    print_usage ();
79  endif
80  if (! (isstruct (pp) && isfield (pp, "form") && strcmp (pp.form, "pp")))
81    error ("unmkpp: PP must be a piecewise polynomial structure");
82  endif
83  x = pp.breaks;
84  P = pp.coefs;
85  n = pp.pieces;
86  k = pp.order;
87  d = pp.dim;
88
89endfunction
90
91
92%!test
93%! b = 1:3;
94%! c = 1:24;
95%! pp = mkpp (b,c);
96%! [x, P, n, k, d] = unmkpp (pp);
97%! assert (x, b);
98%! assert (P, reshape (c, [2 12]));
99%! assert (n, 2);
100%! assert (k, 12);
101%! assert (d, 1);
102
103## Test input validation
104%!error unmkpp ()
105%!error unmkpp (1,2)
106%!error <piecewise polynomial structure> unmkpp (1)
107%!error <piecewise polynomial structure> unmkpp (struct ("field1", "pp"))
108%!error <piecewise polynomial structure> unmkpp (struct ("form", "not_a_pp"))
109