annotate scripts/miscellaneous/swapbytes.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children 597f3ee61a48
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 2007-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26600
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
7 ##
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
8 ## This file is part of Octave.
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
14 ##
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
19 ##
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
7016
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe]
jwe
parents: 6869
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
25
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{y} =} swapbytes (@var{x})
20164
df437a52bcaf doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
28 ## Swap the byte order on values, converting from little endian to big endian
df437a52bcaf doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
29 ## and vice versa.
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
30 ##
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
31 ## For example:
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
32 ##
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
33 ## @example
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
34 ## @group
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
35 ## swapbytes (uint16 (1:4))
26600
f6730533820e doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents: 26376
diff changeset
36 ## @result{} 256 512 768 1024
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
37 ## @end group
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
38 ## @end example
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
39 ##
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
40 ## @seealso{typecast, cast}
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
41 ## @end deftypefn
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
42
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
43 function y = swapbytes (x)
12847
619c1895e3e0 codesprint: Add tests for swapbytes.m
Rik <octave@nomad.inbox5.com>
parents: 12575
diff changeset
44
28891
de5f2f9a64ff maint: Use same coding style when checking for a minimum of 1 input.
Rik <rik@octave.org>
parents: 28886
diff changeset
45 if (nargin < 1)
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
46 print_usage ();
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
47 endif
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
48
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
49 cls = class (x);
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
50 if (strcmp (cls, "int8") || strcmp (cls, "uint8") || isempty (x))
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
51 y = x;
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
52 else
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
53 if (strcmp (cls, "int16") || strcmp (cls, "uint16"))
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
54 nb = 2;
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
55 elseif (strcmp (cls, "single")
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
56 || strcmp (cls, "int32") || strcmp (cls, "uint32"))
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
57 nb = 4;
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
58 elseif (strcmp (cls, "double")
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
59 || strcmp (cls, "int64") || strcmp (cls, "uint64"))
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
60 nb = 8;
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
61 else
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
62 error ("swapbytes: invalid object of class '%s'", cls);
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
63 endif
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
64 y = reshape (typecast (reshape (typecast (x(:), "uint8"), nb, numel (x))
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
65 ([nb : -1 : 1], :) (:), cls), size (x));
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
66 endif
12847
619c1895e3e0 codesprint: Add tests for swapbytes.m
Rik <octave@nomad.inbox5.com>
parents: 12575
diff changeset
67
6869
f9c893831e68 [project @ 2007-09-06 16:38:44 by dbateman]
dbateman
parents:
diff changeset
68 endfunction
12847
619c1895e3e0 codesprint: Add tests for swapbytes.m
Rik <octave@nomad.inbox5.com>
parents: 12575
diff changeset
69
619c1895e3e0 codesprint: Add tests for swapbytes.m
Rik <octave@nomad.inbox5.com>
parents: 12575
diff changeset
70
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
71 %!assert (swapbytes (uint16 (1:4)), uint16 ([256 512 768 1024]))
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
72 %!test
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
73 %! assert (swapbytes (swapbytes (pi)), pi);
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
74 %! assert (swapbytes (swapbytes (single (pi))), single (pi));
12847
619c1895e3e0 codesprint: Add tests for swapbytes.m
Rik <octave@nomad.inbox5.com>
parents: 12575
diff changeset
75
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
76 ## Test input validation
28886
d8318c12d903 test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents: 27923
diff changeset
77 %!error <Invalid call> swapbytes ()
19209
827ac8b5ae07 swapbytes.m: Add support for 'single' type.
Rik <rik@octave.org>
parents: 17744
diff changeset
78 %!error <invalid object of class 'cell'> swapbytes ({1})