pax_global_header 0000666 0000000 0000000 00000000064 15227665741 0014531 g ustar 00root root 0000000 0000000 52 comment=9c9a8d34413ca2beb0b192b476f2ee288b99959f
pr0m1th3as-datatypes-9c9a8d3/ 0000775 0000000 0000000 00000000000 15227665741 0016055 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/.gitattributes 0000664 0000000 0000000 00000000077 15227665741 0020754 0 ustar 00root root 0000000 0000000 docs export-ignore
logos export-ignore
README.md export-ignore
pr0m1th3as-datatypes-9c9a8d3/COPYING 0000664 0000000 0000000 00000104513 15227665741 0017114 0 ustar 00root root 0000000 0000000 GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
Copyright (C)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
Copyright (C)
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
.
pr0m1th3as-datatypes-9c9a8d3/DESCRIPTION 0000664 0000000 0000000 00000000632 15227665741 0017564 0 ustar 00root root 0000000 0000000 Name: datatypes
Version: 1.2.7
Date: 2026-07-21
Author: Andreas Bertsatos
Maintainer: Andreas Bertsatos
Title: Data Types for GNU Octave
Description: A package for providing extra data types
and related functionality for GNU Octave.
Categories: Datatypes
Depends: octave (>= 11.1.0)
Url: https://github.com/pr0m1th3as/datatypes
Tracker: https://github.com/pr0m1th3as/datatypes/issues
pr0m1th3as-datatypes-9c9a8d3/INDEX 0000664 0000000 0000000 00000001525 15227665741 0016652 0 ustar 00root root 0000000 0000000 datatypes >> datatypes
categorical arrays
categorical
iscategorical
calendarDuration arrays
calendarDuration
caldays
calweeks
calmonths
calquarters
calyears
iscalendarduration
datetime arrays
datetime
isdatetime
isnat
NaT
duration arrays
duration
days
years
hours
minutes
seconds
milliseconds
isduration
string arrays
string
convertCharsToStrings
convertStringsToChars
table arrays
table
array2table
cell2table
csv2table
ods2table
ods2struct
readtable
struct2ods
struct2xlsx
struct2table
xlsx2struct
istable
supplementary classes
missing
vartype
@cell/disp
@cell/display
supplementary functions
findgroups
splitapply
keyHash
keyMatch
parsePairedArguments
compiled functions
__ckeyHash__
__nkeyHash__
__datetime__
__csv2table__
__table2csv__
__ods2table__
__table2ods__
__xlsx2table__
__table2xlsx__
pr0m1th3as-datatypes-9c9a8d3/LICENSE.txt 0000664 0000000 0000000 00000000375 15227665741 0017705 0 ustar 00root root 0000000 0000000 All software in the 'datatypes' package is published under the
GNU General Public License verion 3 (GPLv3). The package's
logo ('doc/datatypes.png') is licensed under a Creative Commons
Attribution-ShareAlike 4.0 International license (CC BY-SA 4.0).
pr0m1th3as-datatypes-9c9a8d3/NEWS 0000664 0000000 0000000 00000002541 15227665741 0016556 0 ustar 00root root 0000000 0000000 Summary of important user-visible changes for datatypes 1.2.7:
--------------------------------------------------------------
** The `datetime` class gains a large set of operations, as its
implementation continues incrementally. Newly available: arithmetic
`plus`/`minus` and the `:` range operator; the relational operators
`lt`/`le`/`gt`/`ge`/`eq`/`ne` together with `isequal`/`isequaln`;
ordering with `sort`/`issorted`, `sortrows`/`issortedrows`, `min`/`max`,
and `unique`; the set operations `intersect`/`union`/`setdiff`/`setxor`/
`ismember`; `diff` (returning a `duration`) and `caldiff`/`between`
(returning a `calendarDuration`); the interval test `isbetween`; the
reductions `mean`/`median`/`mode` (returning `datetime`) and `std`
(returning a `duration`); and `dateshift`. All are timezone- and
DST-aware.
** Updated the bundled IANA timezone database to version 2026c (issue #36).
** Added `%!demo` example blocks for the `table`, `categorical`,
`duration`, `calendarDuration`, and `string` classes, and for the
`table` file-I/O helper functions. Table demos now also show the input
table, not just the result.
** Modernized docstrings across the package: removed empty `@multitable`
spacer columns, added missing Name/Value headers, and use `*` for
multiplication inside `@math` expressions.
pr0m1th3as-datatypes-9c9a8d3/doc/ 0000775 0000000 0000000 00000000000 15227665741 0016622 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/doc/datatypes.png 0000664 0000000 0000000 00000110305 15227665741 0021326 0 ustar 00root root 0000000 0000000 PNG
IHDR WV zTXtRaw profile type exif xmP
g D 桞}`s~>ܫ;
K9Fh$[m6ctwxx̖?'0\ lhO!+ ƫ R*Zg)fbNm:gHY[R낭ր:w!"it&)
KH ^9dA 2"˝p_e{0X" iCCPICC profile x}=H@ _ӊ"U;8dNDEIP
Vh/hҐ8
?.κ:
"%/) =B4+4hmq1];_B/cFf1'II{zY =jb@@$eioOm}+*9I$~όA/K!W @wV~bK
ǁ:wFq q+ԁOk--zm-M.w'C6eW
y) k^o}> i*y #^ywW{oiYrh iTXtXML:com.adobe.xmp
2.0
Linux
1744600475516750
2.10.38
image/png
Andreas Bertsatos
1
GIMP 2.10
2025:04:14T06:14:33+03:00
2025:04:14T06:14:33+03:00
gimp:docid:gimp:c36f85fe-7e32-4501-97e3-7d47d2499f44
saved
/
xmp.iid:3f8dfdc4-0e75-4b69-9016-0456f95b7341
Gimp 2.10 (Linux)
2025-04-14T06:14:35+03:00
xmp.iid:a80de4dc-0b88-42bf-96d3-794dccb8d9ca
xmp.did:fef46d76-114e-4380-bbc6-ea93d6100512
1 bKGD C pHYs od tIME#bӼ tEXtAuthor Andreas Bertsatos"P tEXtCopyright CC BY-SA 4.0ωޔ IDATxw\Ցӓr"HB$!6ak{?Xg{m.ػu$ E"(#PΚh4s|i$֞z~}sOz=BJ)闓Υyl
UA5tTË
"4?B&HXIrf>@g{#V;+Y0Z
%PQC
NńYNBQuLߣ"-ȉ$۴CaK?NؑB !P! dڶӚu@D%Z v r .s
G,
`X&GMK~}s@ռMЋ 8
GU54]G4#1\\/Uk^ɶb4p9sSxG!Bpaڳ=)WN'
)賌r.u&" ض8 (Hq lv\T=[ٹ} k ұaX(E_b[7=k3pY?XH&@Dwz;zP FJuH*
qp )%0sVxBϧ_Aά6,e/"J+?fysѼ~H)q;Ic{l.GO'k*#$&Ց !? T ˔^BM㎭l[5 )H͢ ;E_UF o_E& X>1 l_>6xu;o.Wz] -!(89"gXi蚊
lƱ-¾89,c!MPU ۶( ;9 o <34Yۯ ɳrl_y76oF){Oށ(*GiJGb6c-ڲIҝ$
9$`7W5=ضeq*H S f8(݂R.EL9 . wbW~9l'E
~𱮏U.hI(8.T*>C#ϓΛX p\LJ9 #dȘy:2I,xHnx~^;/ۯ NBC oXE 4 ږUs+z^Z撨Jm B?B2P;'&y!oIړyb!GWP$dxHy er7w,t^s?|g)aKRWSh=lկ]+iW~ p]+)Mִ $4j*t$LL!h-±mpע tt? t+ȩ= v.l6W>扎b!+p$#ESGñ ,!Q,&,!UP1(¯Hi4hA<[+]; $hH!gS4wsMj5_{fO+g)~̑xI$n -iyCUB&gӑAE)[ qXx
Lq-n-Vi-EH*uIG2G*2mKU! рjk9gDg^~ w_ZҞߪQ?!k HaLj#~V060AC#ΑA(h S Uz<>^](R
kd۶ KF*kә`
yQ ! #$ y
3ݸX`_AP|["[L,HpG#S_1dM!]%$Bqno83y A?*#TGTBU\ţiIB*NlKޯ }(f*NӁ 1M4Ifr}AfJJXwTM&gb{<uT CJPUuŶmbiE P MV
C2Ƕ 2E*/_ws>@~C Mc'86cL CG
eaZ&cjbm6iD/viy]˥eaY;UP&5]GT7)L<"R"B<'
Gu z >l$jq:r _)%9,Z ,~TtsٺWܰuVB^xZ% ro
v܁
G;v|&X}` 4 [tM5Hf$2y"^O1p!ضN
E'IJe%)/d!}^̼$ϓ5- MGV 5W,±\qЙb&ccHZ9ϰ/#
'ۺEc'@MIP,ѯ S Mdnt' -;v/ΆկkV&NE/ __G>/~gy[qe1~xn(UUU,X۶?L.g?uuuL:˲x衇7*v/~D>v;q$^p!&LF`[Y48u2X;Ӵ
Mh?:0{b 9Y 蚡hgo/KѓW_}я}#ѺA ș<𣌘4nÆOJs!~Xx1=W_}5Ǐg ^իW` aŊL6
q>WBlmmEJO<ʵ! Xr~o GE*XXE[_{Wĩw,t wR_G*B q'af
#0
94Å^"0 NJy~?sEAmmmBPUUU]D
# GU52IOHaabԣz\IC0/7_L)@ܲhv93[~8^խ-)J n 6 XGb8 س-M^9.w)u;`^Pt>}]̑8D
(4
ѣM;*7|3/K(@)v\[L}wތ}E UTi 2!)$9CK"UC G++ݯw8nU7p¨\ _+ #o-H_Q7d L*? A+dɚZ.h|EA/v8J*YRl`6|U(xuM(}gʗ[yzN$wD}LH"aꁗrUd~ TWy+VQ ~Lvz+骎۸|U_ANVT C]2."Hi{t%M►TF7(*JQyJYs)A+QGJ()B`Bt!G6xU.{P c*ƢzCm )ymZ:ӥ;}br'n֢ V!͒J B ov֩$i|h s@ly[)bO7.IY@#@{SMؿ "**|B BX.K,%H"E,`(GU
] [J
C֔dMYZ3q E%dP=U<8iLZoϑ}˲$KL:J9 R4dD"9qy{xwsG_CD
טߜѱ{L4ig<҄-, 6D yin朗54Rd,EH`Yv TM@iZ:R48Ic{TED" VWiRI|?)i Nص$YgDF7'DiYEv(.}W9KVW1|hgHª{J]w' P w$~s|eW,Ҋr, UmKD:HU&qM) E2W5!TKHAjÕxu
QSJ%v=oq їO%isؾṟ{-?ykr v#_($XggXs)rJJ(|>4MU9e 3TVˑSWw
܋Wa ]dLeX"̢)U^õ>Cđtdr3yjޞ&X;eےdd:KUGeć8M*53E0jJAc۬|;9OĻe,,Zڔ9b!pC,I"Lr~߲mbD1$ RYYAE 2¨l^>}h~݈
/~owROKAޒd& diŲt $9LqWbeXI2'S
hiTWETX*C`8vl۶Yae[GT:q-JP S"' }eN4>/~@*g.2*J=o%IbұZgu8BpMznyoAGOfƔsXzJqZW2 ]\M.nS$tsc8xux6i]hmHYv$/ C+4ªB2[ ɒ/$L;]31"|l1\pP -ާI2!P͖ JYx h4
B9T v}+
d2t:q
eJ |x.#)td: oA 3l={Cm$[ xI: ґ] F:
4QMUp =)|_c=nθS*dϔ7bӍ/ )1t
{ds9>~`[6Njnxt(W<^z-]b=A CGJ Z5Li̊ X'#q/ 7|eqlMEΙ8H--1k٤sUОMД e拍U*% Hre^TErllD\LUbeK^qpi/dU L6v4eZ"hn"%pn$C(G7#ޔvsD.4 ժ% #
wi,( w+Ҹw[y>˦g(*ANg*ahT<]5Ek"eDCȑq<>-&hO*aE(
>-b,tH@Qeܰ?tR#NSh:kV>?(z٪z!RJnʲe˘8q"Ç' ps9n ʉT*SO=eY\x1@_{/UY)%˗/g] jjp]vr/SYU3` R4< #%N|h0!0^ ӇаY#[w+A\cXGoJ gK'
)b)Zd29jj~}AA M&E2%/p=A["G<[3[H"Ñ U"AWU{xk7X]/=W~촍͛M6{݂G7hmm>7tC P(wp
_o|B@K[;MMM466__TUU1~x~ qA y&O̯ {m۶e za^p 3lH>2sL~@&W_ez'z,zdNJzbD^ ϼ[Nj?G wx8+Ēi"* * #%fZW4bj6
Бr E:?^]öLtUULrɌ+hi`KSdW!q疭ÉF dXd `ӦMtbUmb8p
~$B1cƠPl.G[[Ç
0 Ǝ eعe˖҂
n ree%C &iigFF7Ķߏ.7CN0#{=Fw
ѳ/cm{n!Udo?CM$HA** vz@ct׃k ,e**>A0tld?d+q}&ewmC[ъ};? \.G"mvI6"_K&TFTWV7| 5&avlm.$=~ ۳4K&gvBfc>$qX~ IDATUɓ )t? <zpQ#/``Eo
@6,Ȧ;)\Ά]
R-[M0v2~,ӯCjN5 ,fƋÝۊ#6v 3\_L!V
zǮ/Xq3[yTdhz]e%{YOtҿD7tn?^+GUȟ)$=/m&^BP5`8sE;ʧ
f2¶سr 泥IQ;2JtkNj.ʳr?u
XLО\J"*'T Rzyo
rv͊m 3'to'b PpK-*!az4Xp? K|B
"SGز Yxo?Ku@וz?3fbFe[[
-ʰy#F_qڕz71kwkuKY *[x/J}9WzD?^,[T*E>#bq0 B `N]:_cNں)LjɳgN' GΆac]yNuy{ovMW7/`9G+sB(J8CtRVXA:. \E9KqB477z.+8YnFxce
>A8'
y=(P(N[[e-y{9%
t6O?`mCWW\{9ue3{G{ ߝfŋ/'Q)} `ˡּ7,/n}B wy'Bl\^3LId22[˞={x'HR8M>c0zH~ 0` O$h4J8DW &Jڊe
I0iUٽl<(KxCU{=>Z[u` 6n `P&/-aD [FA~Ĺ]{! W-3ihV&0aMMMyɯ͗Un6n 9?qLk&gl۶Ç~zLL<`Ν|﮻ټe/*~q1g ^}m9{ W/\.O{k4wO̲rWeP
/g_y3)&bez.-0F*wgjyqZwщ$m
l֭#f+kt ;k ݅A!\r .d 4 l #OaѼ4 #/Ew"5gd"ٖڛqdœ gTA,U@;٥U=,
qvτrVܲ,~_aH|'j&t%z]2b^(u\>O*&H^L\Fܴ|U7hc&PY[cפ~u< /S<~N]nk#6<:3
y lӶ3 mж[WO"` 75p $\me{PH >BeeeqQF (_m t)r !uITMex^~,3Hld!Dv#Q J*S4'H3El \3zrio-I.
[w /cfc+(vہ7B :Gr)ڟ`M. Nx;kܴ#VfN _lm+V1pK 6Y~kkуRNP HXJcRnUR n>e\G*#
C (˞J6Chf]CW wDוeгO
0:J
P %"R o6@ !gcʿ`w$<\PS ЋOҒrޡu(.IK9*#"T@=Kw_zo剕 Iҹ B|X3 Tc7iOgâ'-Ҷ
Le@T5*f ʞP6[A"L8RqL(\;sDulbcr$.qӲgBONu aY&
u^0J-%vu ˊy$O=Gr&x
UAcF;x2AF{&[|\!w=X_d᧿n[F~uxGR1Hu@˛T Fq, = ð ^jq9y!%l`0}AhKBmmM$ ^pEE8Iy,vI?g=-
/CG w%(mvD/GlCee%=|>OGGUUUT
$# sl@
Z4NsuH;ac䉓 nz 31rG`v [;/ 3I9vkA! Z4Ã
~ S]Vʣtō7p
bL vzA@E[b. luح=qƍ DFAulh2@oݢ=Kd2$ TU-o\ʏ/py|~ꇟŞ4pJD:M/v 3E1}; 39|>OضM{{;HJ$T
0=|+ޅ,Ʃa|) w$`삏38Zr:Mӷ?JYs7Г+{Pg+'0-T:MDIsݜ@z
Y>G''X2 ϼ]V_۶<%Tu[6sUcxp,Wu6@mϧDjF1e2>?x.S|^ M( I9YHaaYy7 % nD#Ag8dbݣ&4<l
o+8$2);5kְvZŎ{Te\D"<MXl2}bLzC]VtvR H]ב]7/]| ~o4a zNhI$tvvQ,EQhnnf߾}G?bΜ9|>)
477f|>hnnfҤI̘1l ZZZh5@uu5a`6---,"QUUqԸ_d%#TY{Q 9=d ?GitZ~Wh_}s֧q)6% x?-'Dy~Yc а:Ȏ!z(9 06ev@}h)*[ι>jB;]*++{yɓ?"hfy[U,`9{P}
RQ.'q! kaxϳjhFҨ@AKA]HFԏAW
fm^gW8G+,8귚 iT{מu) ?M*I-U"׳dB 8@ @Qbi :VZE0d˖-wy'Ey e)Ɖb3`8=ס$Bp%7Ҵ}cM$_¹ &M?C}$,
PLl=]_`n0<-
s?iWO9 Ol-*^Ob1r 477k.TUeĈB͛ikk3gJXf
g1M^xT*!N3zh< `̙ :tT*ť^J.cjw xEq sHN+1FW4 u,p:pA
lUHnh r?o &Cor W#Ȟ1揟]lg /^o2r_acaa$\F!+1b&LȪ!u4Aڶ~TaÆ1lذ^WRQgKuEBee%HJ ;vl9ihh`РAe'Џf'J^ߎG'!:˂@q pKf z5 D(
('aIlSa%7\bX9:>!b5`nՖ?f]?
qǮ>fRJYX|\j Wq'ÂTUU(M׃[,!*' 4QUUՃ!|>O(]JʀSUm( |]LS 8]vMPGiloB+ݥXRҮz80`Q5CNTςtu<~LZ), \.J[Wc,1Wb,BEw-v(:*uEcxt0ãHw7ߣ!XUe,έ1 vw0*dSڎ>>c`PQ0i\Mx ;w=7ҥKݾ}1o߾n>ϣ:fo{Mi;$Τ=jKBƇICo<c&UUP(t;S'
R~M}6[ /{ό 9T*q ]vtRjkkַŕW^kƲ,6mDm볯] c͛Wn;. 2X$ co|G $4c!͏%U̝y1P
Ȫ1Y{ 3+1%ҎGn?H>?{`Iv4^30[.\ȃ>X6o̷mpYg1zcfYjilڴ\.c3f ˖-ry<Լu)͛뮻ky7?ۻUl\yr' 5Iy
ۣ͘A~!sE<_}GɈ7~Ȉ8(BEEs_*6m MMM}:sgٺu #O[cY3MR;hXTeн3RJ֭[)
L0||yu]l߾ٳgڶ̓>Ȍ31***3f +W[n9a@%8m O+~ƺ'EWgA dܼ`bMGk! gݒǰ)cxx@ ĉyGq҂ >`VR(M&߲ DG1/blosataJ}}=uu]͛ٹs';w䷿mw|\ՙefFҨr-.L 5Jp I`I/$# d!,M8bMU-#i4r~f$7,' >/ޙ{gΜyNuua=7SXlٰy??:(9Zx
@z ~s(6lD1]wj'na >ew`[ )da |[R~tk4Yj~_y~[oIm۶q7f͚ak\V[r%'pB +V`۶m2qăA94<|z)X1 P)@C{ ^\әиx
L:8+ v ![ 7͍DLk7崱{-?gl ,kʕ+ 9Å^{] `՜vi\{CJÍ7C=\p%řsN֬Yo~ Xl;w&Q
@ $g3E+ػj/@#б70miTjGR q IDAT<"/Z=dώ
D>|x)`f(kp,'q;f1=̛B{Ρ&ʊz_W杻+()PGhiiŰMUU^{-ommmye;VZg=b4&LM83擧Z ǡ$S/(} ;45?,g7a V@Dè.H kCEq?BDͲ<&pUHsA$|4/yw4>f͚ UVV2uTN>dfΜʓ2---̛7I.iii n3f H$Bcc#˗/}}Guu5'|2. 4@2YvFO4@$qwzl!Z4Ds$,'-Y
@2knj ECԜ?W[HK/ˊ%8xTYAaqbJ**f _ 2Y )X'pn v ٸZ BRF$!P%$ I1+L=
k͙HbPQyqK8*>
n:!"0@$Թx]c 98(`sԜD
XlhROO_YZ*1jL|8*8|N]?`gw?(d,bɏ$ }b+b(I0)W˴
IF>B;`WG jo Ca˪-1 >S뮐LcHŒȖFGv9L 0F:6om|ز]?VeKaٺ{}r?L kZ"6˻{3IX:FQܸ:sdQlTJ; 3},s
Da
gUB)}0 $Hp5`D"]c=6NJ,\0W!r/yζmۆa,/knnO]t6N;o}[{w8ypv[yݻݛ;w/c{H:J@ur~Ԩ~K
NG1jcmO;fO. RIu̹s֢wmCaSGw1l,qW΅az)ϟϬY:Ea|kSO`dkƽO<1BvM$ _G }?/}$[/r+)*++ԉ-[Foo/fbAWWr 'tR^ؾ5JL;86tfʢ(ol v4TJgX%IB=~)E%C% fK&(&f^齆c Rg^Iq OkQ?0a9 ]--- ?[oo#N_*]w].ߩ˗SUUmݖ[BdYfر#< ˗/;rKڕW^<@< ?`qixoolذ`0wCJ14551f̘j́ݯ*K,駟泟, tɭ)L><[5d:@JS"[Q2%O8H$رctEQ2eJNB$=\l.k:V# =ų[ Y8d'̗e~ ֚,Akk+wqvmy(d&FK.夓N2*W\q+VଳsΡ9sp)P[[xsHR5!2bΚª\뇬ys.o]D"#d:fU,w NWZY+xvd4fr)̟??;w vWW:b{ÞW>}:/2/26l'o_v[ Z +P0룷 &W
d$7t]RU5d7sR.j\ r̙3;wn H32-!f̘gŋG$z Vl2.~_w}R_5T;B#n$ YIRBرc SYFiFAjjjYsMv8c ɟa
#ڑqbɼ⋇,Ȉ,cٰl,X 7ꫯ ؞Q+UQ4_\uBTWQ bt0u'g&XX,FWWVMUUUζzlƟ@`O\ͺ?ym.{ÁM6qڟ|_[,)=Eku>']$t^WY|Y$UUQUAqq1x OOOaޗJF\6u
5 @To`rO(@Z,ͤ7f^?{9Nn喼nm$qm gA}}3vnfZ#JQRRә2e(_6GTt[d 5 G DصkW7ng9c` $aZ(/:CfcR@PTɐR| bDF(iݧyɻگQAoo/p&VU՜Z%rN:lرcseUU7n\.m'H͊VL7]{?dDm&)
5YKp? u-uog8T'0 4b ?~Wl٘0aB8]]]VdIUE QdzAgW#;oi MHaSqZ%wo3ʳTgg'aQM➞ ~{zzPU5u>GW ' &
t XNAJK?kH08WK _;3!ԐSk3weeeNڵkװ짖6Xꔕiq, eee9- k3 ZT:I<طʥ۱>~{D:l8l oo[lcK{+ oaI
3m6n!F6K7!FKMxill̫x0avb .^I_Z."PSSx^.V\I{{4aDCaE$]EKDnIgLf6BncJ)=Y A :ź&6kP/wB% 4M^RVxjf[]\;li}±TM^(OEf 28!Ȣ) տ 8;eRK%iyU¼ Y;B RWW wsuYn{{;mmmCxDz# zjnF lٲEQ4h4Jmm-N3h&T
̙3Yr%'OOv nUP;a> G8[XRHs?),Í kdݸZ,TVVKUUA7[xugUI%D,: I=?iZbe۰Or؝zd.;Y|s*VY٦ ٝ>$,aN`;NE`h2wE7Q,NS^QUr6jAI OLb6I6S4M~i{]`7[}(6es$ Q*DUG "` L$dI 8N D6dvȋ=r
|D3+ 4٤شv03RrK=(&jCjQ<6:ZĀoazsp8W(Wf{e+%Iٕ5rdё ;'hZs$0!_:}zCΫb>}ڷ9X=٤
q5Thm~RSmqBF>IC?=(RH4X;7FqHLmdՎW0UUBׇ9'r><X,RAoooNU+((&xCL} l#+n< Er*UZ9U; ӌ05"m4vCcwPnjpEkBHΣ6ϓ摌 h{vV+9'iMMMr$}F===455JùfnIҳH3j1)]Lz__LJȸU͘b=H.`q3x"G }? ft}Ӫ`Ȗ}"BFB`WXh;)\dAϏE:zc`[Uabʉr0.**"ʨa~ ۍ jX"V^TT439ɻ(U # UGɤMA}=*` `$ @Sy*:֠ 7Χf/Woi bYAͭ8ߌ#d8h4 ׂӐp2= UChQu ,=-ye E2$ )// ֫/w(L4)փ
xCOO`0'eBM@ RY<=v3@TԠ )8-"H
IH5":
SH' F8 ߏoZ^r5lz~ZF$icF0NBGNM} /Vv˨ҡ_ɷNo,+RSSCcc#Bq8 -ڬ}bX~oy%/
k< - }P9m_A( $pXhtla `ˬdiݓ;yGOw6`Z&}@JT*M*8)bz|Yوq{\IRQƢQY6{ Z[6Mg6!nxUr|除 C.pf[9xr ,4inn& mmmR<0dhFkkk.>FR;8Ix:ξ `\I~HZ;vK斡,˔&&!-lI 1MC7@UT
0ucـE %d7Xw ]nI˅kmԸ8P
3b[˔b߿;D_-o^݈HbvcIcQ*Fl$6w($YfM[ Ä)#b$I?~< `0$I;林4ncZ |>bMMM9~,xd"I@3g\O"&kS Q\Z[uZ K2 {ƹj"KK8<>ٰܼq:BYc-U!OO߇[ q,Y&Y0M4s7EcLka 3?c,t^֗QHIa &H2$J@MM
*< IDAT^=]F|CjЫr9RЭv;HI Ξr ޡ\<@R{[W *0bt Պa?:[Tv[AT"k `kUU
F8τO/+ó N 3>.)ہo8 ;Tegڄ tSfWz%I0G!55}BO1NI&D,4MZZZp\S\\!İ iٻw/H$vjkksxmof2i{~HNJk: g9&Rn
CA,aN&8 vR6@x7݆sQ )o|SD[o Y\zi~#,TPdG#-\4>@V;Z- j}Sp92\MiӃiyen;ߟz8q"#Omʫ-/b9s¢ qdyAۇ?{OC?q]aNk.n^"%`옪! 좪2y$ Y \\< >-2n)oʑ_&R( >1uԿ&ﵼsVp ̽SvpZթL;#B!Z[[s =+5M]Y컄- 555CO4ŝiZK}hdRe7 $>{S2Y I`(B+2=ѯ ))X'Q8!a{?S7^D?S)<QΒ$3g)YfgdqOjSXXɵ1b躞Gh)館!`<?ET }g8 hp,$iZ
XP c5Fi]'Jv|3?<=t*W|O<8 w^.2FJ0a
{ $ +9; UVrFk1i!:ţT=DU$GvP15cyo&ooyi >)!F
3IS ؞ns@9g
ئ({`W)φ&IÝl@I)uv?hF5C>MN31r Țp' q=koZ8
qœp
[Y
+ޙoJldBL +g*vb#:iΗ15\
<#tM7<!Epsҳq8 ]7si!K;o硇 fl
}h~@dD^k ３ډyn*~y\veDi{P2AiG ) _U C(@\wej+}tYu$ەI*[]Al'w|Л&.ZhχWqy\4|Tgxhk@"m'z"9_aRU}Dp榐rlX KNdɦmy\s;EeyWTĒqM7sV+`QTL$ W3ov~sH$¿0Fc <*͗ O/G) 0X&.H) ]4i3`ذ٭8 \.H?KG1>(RoMwal酣:$qM vMCfڂHIB}:}Ξ
)--} 4o|p#7K
C6h4.,,bX 4 }iz3*b:dsgH(@(VtF8 x"Aχv"O/$
.z ֊V$$TEp #j"8Oj 03MAMƌʕ+ٰagy&UUz464}v8L6+ӧOgڴi|s?3;79sjeܹlظ7^D"q GQQK.UV gR[[~-r[=TMnhOyN
O щ'$ %fjN b\àX셙XDR ւ4H
Ɣ8Z:fQk@3t ϛtbגZW0\Gop.QU{qyS4h LjɊR?><^O^Dx =2n*+ˆjKWx5SXZ6j PͅU[{/i3
J#).0S&v syO8ŋdqi`& I""ї&:fLC-=RPQ^n݇؛O@%ېn{ łӕ76LA"$Jr0I2" aH vLa&F *p@6E܄R ȿO!e#q_ "&-ҠJ=Sv,!!t8)bZ bI H!ًdK9s$ T^$ņxEجAJKK(7m A.~F rH)_GMC],z#@djZ,|#[bH*xsDir_
P0d#'a]MѪ 8 <"HBHM22^"v;d>t
Bee#7{N04L#d$3jXR__ ӁA<{b&(P@)ɯRQx' G4HxԵ;gzzǐM
NF#i+ L# qS'[,I
Je "2<j稬@kqnsgAF>;ujV繒>Z 3 nq}ȂxfOWI<ɣ6)#DCrPK qE(
Th4J,EK'14.,G"nJ@XRXPESȠkJ
`d:/Y{Yˏ䐇⦲x
S!= z!+ItyCHfa
Oe̼fmG[vKJ|flثGm.DlFE*9-8o/a )*R LS"C<!NaC ,~=x>aB5@ObXԼ9t|7n,>(?4EJ⬢;hV653x*Oojѿ8AAJӈ9KɴF,4k +UZ&Ɋ"e mԴ %[Kh
8}T@x4fuKB&6Mt WU$J
i]'IKL6vv)`gz3zai HN'u18ƶ26D
fgjwV`fUp
HSSZ6
[?ݏ L&H@n^>`xJS:@xl q3?J(, E q!p ]2]L"mح&" 71e Bx43_bCBH#ҿdE٧* > ! "^D1 .xnܩxh1 ϰUEUUEȰm`¹co<Σ
yN U?] G& xWe k
En0MtҺjad"pP-[4>
od&2I;!$z1)v EStBz
/dHTWP7ϐP?Qk4!xd1p:3^P
F
`[kkpi6]ɂ Uis &LD),ȐKti$26F*'?1_fgۑd+#{]
[8R?]f+_6~̿0! d l6>,q j!qu)=1GΝ[S'bAQ n=]d̊J.^ݾ#c$ǍO"wu]90+oGe+$6mmʌ9 UN$2xˬr_dO{ =kW>nUOhRGV, w̙=];QRR²e|XU;B |׃̦nB y*2
Ѕ劺C{ $"+y*T4/ x h7`g~jN(şh ~!sKcʄ#5|[ //}}AjJH's+ Wg\H2e" W_}5[]`
;hOr
\t[b;/>;３uq
I 㼋9eRM $إ9r˱#[nAnPXE݇U(*Ǔ"Lx߽ϻ;NsM]|\
s(!XL0 0ƫFǞ5kVȪc2ijj?ߍDu(%EA7 7)pXc)is^jp`v~z~ JF4,3|*CH#,O6Ҵg=
q+0q'e(FQweQQ^J^ۻ^s b 12rLQ O@+V0mjm&JvvZnoXb{$a`N'rU_J|%9'$RSJVbE{AđT'Çdu"Y]HLOnjg l6DhO.2Du=> ,>QSbV>24rKlS,Κ.?vS&Т!B$H4wbÑ(Px&7oΓl& 5'5W*N0
wV~|(T9 Xq ˆ
ؾC'Mc⤩ذ~t
Xγ>KwO3f`μy۔PQ)9p:\M6xl6l}?D"c;%+56djB},]J ~alԩSzwc1c#K^}C륻y;x(2[d0mC"y6ax`6J'yZ["-7ʆ&NsrBy>6=oxK
[ !{В=] b]La4-,%+ZyL$s d :
lC={ W& Af"G
wإX]]Xk(Yw1vUU ǽ̝ G(С6H4hDbc41bh0$ !ACRh<,` t3s_s{o?;ә>ҹ =w?kXQ+W7 '#7jRF#oq&y xjj5@4SOuGCeWPYW%\c[6ޗ &B(dDMח_J) Dʌ4s]jYM+ M d$psBR C} @89}8Mx{yE+o+C's5U"β]d2v,Xu <
gm/̠\7E,3Ε ޕ >8Dx : ,]@0{ }X={avrK?` {G0(LRPB`vcw8= %q200eY9KӐRjh6H%
ju M#/r^)LR@A)۠zaѯ4M#U]4)JaO1Y S Ae4.I
nq% +N L
o lIDATeXJdY("R6F_O)47\tóh'
0V8E
!rw^YF&8VNzLK|/\MV{ ~(CX[ @z@#=w~8KnQ1icH)I҄$1 (bi9݁,j155E&b 7☙?>H\N^Vk kJ1 =J
aشIӰ #
°e1tiDH ,P* btlڹ6o"1ǗZ rZچi=C_K 6HRVtl[f,J<&%RfꁩC#]bH^glləIbtI".A* JN:6AGbp3XHNEtVĽ "
}RJs.|(8
ItI di~uðNLaBn+FA{Q
B 4U<#N#^y짬I.(y_ ȹe5 OT|7qKUs$U|j4"CQE!a!
ig TsQb` ,>te CIJTdzJ Vi<[xFe07|{Ҍ!;+\- FO ۃl?hwY?D>i$xe(Xr ?XLL=`.)k l,QQ} 0H=ĺ A^fՖ{(;/_O9 1>8奿"J&0 bݗ>Sĉ taSK2Nʷd!P(t:\Ha費W.p H&Z{~$UTA~qנbNC ,A,O9uE50ض8KP ЮٴC 7F`뗩؛{b fKj 6D߹KQSvu UH 0("|MۈG=oV-ˠ(o<? ݰhڻ 3}cW]OexV-B 79:ͧP1f<'F*+c.f RAB >Šg)GvWޅ[p rYNs d:+&(yE 8L:ɒeo
EN;'Jۤ ћU{BsF ˭;Ѕכ @> %a >O7;:H8W qI M ѱ~f?S뻁eٞo r%%LI6au4:[Ml;8.=9q!|on ~1ELAikS IENDB` pr0m1th3as-datatypes-9c9a8d3/inst/ 0000775 0000000 0000000 00000000000 15227665741 0017032 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/inst/@cell/ 0000775 0000000 0000000 00000000000 15227665741 0020051 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/inst/@cell/disp.m 0000664 0000000 0000000 00000002103 15227665741 0021162 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2025 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {} disp (@var{C})
##
## Customized display of cell arrays.
##
## This function overloads Octave core @code{disp} with respect to cell arrays
## and displays their contents in MATLAB like manner.
##
## @end deftypefn
function disp (C)
__disp__ (C);
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/@cell/display.m 0000664 0000000 0000000 00000002273 15227665741 0021700 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2025 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {} display (@var{C})
##
## Customized display of cell arrays.
##
## This function overloads Octave core @code{display} with respect to cell
## arrays and displays their contents in MATLAB like manner.
##
## @end deftypefn
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, in_name);
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/@cell/private/ 0000775 0000000 0000000 00000000000 15227665741 0021523 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/inst/@cell/private/__disp__.m 0000664 0000000 0000000 00000025064 15227665741 0023443 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2025 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
function __disp__ (C, name = 'ans')
if (isempty (C))
str = strjoin (repmat ({'%d'}, 1, ndims (C)), 'x');
str = sprintf ('\n %s empty cell array\n\n', str);
fprintf (str, size (C));
elseif (ismatrix (C))
fprintf (' %dx%d cell array\n\n', size (C));
dispcellmatrix (C);
else
str = strjoin (repmat ({'%d'}, 1, ndims (C)), 'x');
str = sprintf ('\n %s cell array\n\n', str);
fprintf (str, size (C));
## Handle each page separately
sz = size (C);
high_sz = sz(3:end);
high_ixs = {};
for i = 1:numel (high_sz)
high_ixs{i} = [1:high_sz(i)]';
endfor
page_ixs = combvec (high_ixs);
for ix = 1:size (page_ixs, 1)
p_ix = page_ixs(ix,:);
pagestr = sprintf (strjoin (repmat ({'%d'}, 1, numel (p_ix)), ':'), p_ix);
fprintf ('%s(:,:,%s) = \n\n', name, pagestr);
page_C = C(:,:,p_ix);
dispcellmatrix (page_C);
endfor
endif
endfunction
function dispcellmatrix (C)
sz = terminal_size ();
cols = sz(2) - 4;
colgap = " ";
dispstr = {};
optLens = [];
for iCol = 1:size (C, 2)
[outstr, optLen] = mixedcell2str (C(:, iCol), cols);
dispstr = [dispstr, outstr];
optLens = [optLens, optLen];
endfor
if (sum (optLens + 6) <= cols) # all columns fit in terminal size
rowSpat = "";
for iCol = 1:size (C, 2)
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,:});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
else # we need to split rows
optLen_cs = cumsum (optLens + 6);
startCol = 1;
while (! isempty (find (optLen_cs > cols)))
stopCol = find (optLen_cs > cols, 1) - 1;
## Just in case a single column exceeds terminal size
if (stopCol == 0)
stopCol = 1;
endif
rowSpat = "";
for iCol = 1:stopCol
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
optLens(1:iCol) = [];
optLen_cs = cumsum (optLens + 6);
stopCol = stopCol + startCol - 1;
fprintf ("Columns %d through %d:\n\n", startCol, stopCol);
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,[startCol:stopCol]});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
startCol = stopCol + 1;
endwhile
if (! isempty (optLens))
for iCol = 1:length (optLens)
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
stopCol = startCol + iCol - 1;
if (startCol == stopCol)
fprintf ("Column %d:\n\n", startCol);
else
fprintf ("Columns %d through %d:\n\n", startCol, stopCol);
endif
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,[startCol:stopCol]});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
endif
endif
endfunction
## Special function to convert a mixed cell array to cellstr array
## that keeps MATLAB like formatting for each type of element
function [dispstr, optLen] = mixedcell2str (data, cols)
dispstr = cell (size (data));
## Preallocate indexes to avoid truncation when last elements are 0
is_char = logical (zeros (size (data)));
is_bool = is_char;
is_numeric = is_char;
is_object = is_char;
is_struct = is_char;
has_method = is_char;
no_method = is_char;
## Nested cells are printed by size
is_cell = cellfun ('iscell', data);
sf = @(x) sprintf (strcat ([strjoin(repmat ({'%d'}, 1, ndims (x)), 'x'), ...
' cell']), size (x));
dispstr(is_cell) = cellfun (sf, data(is_cell), "UniformOutput", false);
## Empty cells are printed as doubles
is_empty = cellfun (@isempty, data);
sf = @(x) sprintf (strcat (repmat ("%dx", 1, ndims (x))(1:end-1), " %s"), ...
size (x), class (x));
dispstr(is_empty) = cellfun (sf, data(is_empty), "UniformOutput", false);
## Index remaining scalar and row vector elements
ve = cell2mat (cellfun (@(x) isrow (x), data, "UniformOutput", false)) == 1;
ve = ve & ! (is_cell | is_empty);
## Index everything else
me = cell2mat (cellfun (@(x) isrow (x), data, "UniformOutput", false)) != 1;
me = me & ! (is_cell | is_empty);
## Catch 'char' scalars or row vectors
is_char(ve) = cellfun ('ischar', data(ve));
sf = @(x) sprintf ("'%s'", x);
dispstr(is_char) = cellfun (sf, data(is_char), "UniformOutput", false);
## Catch 'logical' scalars or row vectors
is_bool(ve) = cellfun ('islogical', data(ve));
sf = @(x) sprintf ("%s", strtrim (sprintf ("%d ", x)));
dispstr(is_bool) = cellfun (sf, data(is_bool), "UniformOutput", false);
## Catch 'numeric' scalars or row vectors
is_numeric(ve) = cellfun ('isnumeric', data(ve));
sf = @(x) sprintf ("%s", strtrim (sprintf ("%g ", x)));
dispstr(is_numeric) = cellfun (sf, data(is_numeric), "UniformOutput", false);
## Catch 'object' scalars or row vectors
is_object(ve) = cellfun ('isobject', data(ve));
## Handle objects with dispstring method available
f = @(x) ismethod (x, 'dispstrings');
has_method(is_object) = cellfun (f, data(is_object));
sf = @(x) sprintf ("%s", strjoin (dispstrings (x), ' '));
dispstr(has_method) = cellfun (sf, data(has_method), "UniformOutput", false);
## Handle objects without
no_method(is_object) = ! cellfun (f, data(is_object));
sf = @(x) sprintf (strcat ([strjoin(repmat ({'%d'}, 1, ndims (x)), 'x'), ...
' %s']), size (x), class (x));
dispstr(no_method) = cellfun (sf, data(no_method), "UniformOutput", false);
## Catch scalar elements or row vectors of 'struct' type
is_struct(ve) = cellfun ('isstruct', data(ve));
sf = @(x) sprintf (strcat ([strjoin(repmat ({'%d'}, 1, ndims (x)), 'x'), ...
' struct']), size (x));
dispstr(is_struct) = cellfun (sf, data(is_struct), "UniformOutput", false);
## Catch remaining elements containing matrices or arrays of any type
sf = @(x) sprintf (strcat ([strjoin(repmat ({'%d'}, 1, ndims (x)), 'x'), ...
' %s']), size (x), class (x));
dispstr(me) = cellfun (sf, data(me), "UniformOutput", false);
## Index numerical and logical values to right alignment
pad_B = is_numeric | is_bool; # pad before: sprintf("{%%+%ds}"
## Index array types for bracketing
brackets = pad_B | has_method;
## Get optimal length
if (all (brackets))
optLen = max (cellfun (@length, dispstr(brackets))) + 2;
elseif (any (brackets))
optLen1 = max (cellfun (@length, dispstr(brackets))) + 2;
optLen2 = max (cellfun (@length, dispstr(! brackets)));
optLen = max (optLen1, optLen2);
else
optLen = max (cellfun (@length, dispstr(! brackets)));
endif
## Make sure a single column does not exceed terminal size
if (optLen > cols)
for i = 1:sum (is_char)
hm_idx = find (is_char, i);
sf = @(x) sprintf ("'%s ... '", x(1:cols-10));
dispstr(hm_idx) = cellfun (sf, data(hm_idx), "UniformOutput", false);
endfor
for i = 1:sum (is_bool)
hm_idx = find (is_bool)(i);
do_idx = find (cumsum (cellfun ('length', strsplit (dispstr{hm_idx})) ...
+ 1) > cols - 10, 1) - 1;
if (! isempty (do_idx))
sf = @(x) sprintf ("%s ... ", strtrim (sprintf ("%d ", x(1:do_idx))));
dispstr(hm_idx) = cellfun (sf, data(hm_idx), "UniformOutput", false);
endif
endfor
for i = 1:sum (is_numeric)
hm_idx = find (is_numeric)(i);
do_idx = find (cumsum (cellfun ('length', strsplit (dispstr{hm_idx})) ...
+ 1) > cols - 8, 1) - 1;
if (! isempty (do_idx))
sf = @(x) sprintf ("%s ... ", strtrim (sprintf ("%g ", x(1:do_idx))));
dispstr(hm_idx) = cellfun (sf, data(hm_idx), "UniformOutput", false);
endif
endfor
for i = 1:sum (has_method)
hm_idx = find (has_method)(i);
do_idx = find (cumsum (cellfun ('length', strsplit (dispstr{hm_idx})) ...
+ 4) > cols - 6, 1) - 1;
if (! isempty (do_idx))
sf = @(x) sprintf ("%s ... ", ...
strjoin (dispstrings (x(1:do_idx)), ' '));
dispstr(hm_idx) = cellfun (sf, data(hm_idx), "UniformOutput", false);
endif
endfor
## Recalculate optimal length
if (all (brackets))
optLen = max (cellfun (@length, dispstr(brackets))) + 2;
elseif (any (brackets))
optLen1 = max (cellfun (@length, dispstr(brackets))) + 2;
optLen2 = max (cellfun (@length, dispstr(! brackets)));
optLen = max (optLen1, optLen2);
else
optLen = max (cellfun (@length, dispstr(! brackets)));
endif
endif
## Pad data according to optimal length
## numeric and logical is right aligned, everything else is left aligned
Ra_wB = sprintf ("{[%%+%ds]}", optLen - 2);
fcn = @(x) sprintf (Ra_wB, x);
idx = pad_B & brackets;
dispstr(idx) = cellfun (fcn, dispstr(idx), "UniformOutput", false);
La_wB = sprintf ("{[%%-%ds]}", optLen - 2);
fcn = @(x) sprintf (La_wB, x);
idx = ! pad_B & brackets;
dispstr(idx) = cellfun (fcn, dispstr(idx), "UniformOutput", false);
La_nB = sprintf ("{%%-%ds}", optLen);
fcn = @(x) sprintf (La_nB, x);
idx = (! pad_B & ! brackets) | me;
dispstr(idx) = cellfun (fcn, dispstr(idx), "UniformOutput", false);
endfunction
function out = combvec (vecs)
switch (numel (vecs))
case 1
out = vecs{1}(:);
case 2
a = vecs{1}(:);
b = vecs{2}(:);
out = repmat (a, numel (b), 2);
i_comb = 1;
for i_a = 1:numel (a)
for i_b = 1:numel (b)
out(i_comb,:) = [a(i_a), b(i_b)];
i_comb = i_comb + 1;
endfor
endfor
otherwise
out = [];
a = vecs{1}(:);
rest = vecs(2:end);
rest_combs = combvec (rest);
for i = 1:numel (a)
out = [out; [repmat(a(i), [size(rest_combs,1), 1]), rest_combs]];
endfor
endswitch
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/NaT.m 0000664 0000000 0000000 00000010633 15227665741 0017675 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{T} =} NaT (@var{n})
## @deftypefnx {datatypes} {@var{T} =} NaT (@var{sz1}, @dots{}, @var{szN})
## @deftypefnx {datatypes} {@var{T} =} NaT (@var{sz})
## @deftypefnx {datatypes} {@var{T} =} NaT (@dots{}, @qcode{'Format'}, @var{fmt})
## @deftypefnx {datatypes} {@var{T} =} NaT (@dots{}, @qcode{'TimeZone'}, @var{tz})
##
## “Not-a-Time”. Creates missing-valued datetime arrays.
##
## @code{@var{T} = NaT (@var{n})} creates an @math{N*N} datetime matrix with all
## values being Not-a-Time (@qcode{NaT}). When called with no size input
## values, it returns a @qcode{NaT} datetime scalar.
##
## @code{@var{T} = NaT (@var{sz1}, @dots{}, @var{szN})} returns a datetime array
## with @qcode{NaT} values sized according to the input arguments @var{sz1},
## @dots{}, @var{szN}. Alternatively, individual input size arguments can be
## merged into a single size vector @var{sz}, as in the following syntax
## @code{@var{T} = NaT (@var{sz})}.
##
## @code{@var{T} = NaT (@dots{}, @qcode{'Format'}, @var{fmt})} returns a
## datetime array of @qcode{NaT} values with the specified display format.
##
## @code{@var{T} = NaT (@dots{}, @qcode{'TimeZone'}, @var{tz})} returns a
## datetime array of @qcode{NaT} values in the time zone specified by @var{tz}.
##
## @qcode{NaT} is the @qcode{datetime} equivalent of @qcode{NaN}. It represents
## a missing or invalid value. @qcode{NaT} values never compare equal to,
## greater than, or less than any value, including other @qcode{NaT}s. Doing
## arithmetic with a @qcode{NaT} and any other value results in a @qcode{NaT}.
##
## @seealso{datetime}
## @end deftypefn
function T = NaT (varargin)
## Parse optional Name-Value paired arguments
optNames = {'Format', 'TimeZone'};
dfValues = {'default', ''};
[Format, TimeZone, args] = parsePairedArguments (optNames, dfValues, ...
varargin(:));
## Check optional Name-Value paired arguments
if (! ((ischar (Format) && isvector (Format)) ||
(isa (Format, "string") && isscalar (Format))))
error (["NaT: 'Format' must be either a character vector or", ...
" a string scalar."]);
endif
if (! ((ischar (TimeZone) && (isvector (TimeZone) || isempty (TimeZone))) ||
(isa (TimeZone, "string") && isscalar (TimeZone))))
error (["NaT: 'TimeZone' must be either a character vector or", ...
" a string scalar."]);
endif
## Parse and check SIZE arguments
if (nargin == 0)
sz = 1;
elseif (nargin == 1)
if (isscalar (args{1}) && args{1} >= 0 && args{1} == fix (args{1}))
sz = [args{1}, args{1}];
elseif (isrow (args{1}) && all (args{1} >= 0) ...
&& all (args{1} == fix (args{1})))
sz = args{1};
else
error (strcat (["NaT: N must be a scalar or a row vector"], ...
[" of non-negative integers."]));
endif
elseif (nargin > 1)
posint = cellfun (@(x) (! isscalar (x) || x < 0 || x != fix (x)), args);
if (any (posint))
error ("NaT: dimensions must be non-negative integers.");
endif
sz = [args{:}];
endif
## Construct datetime object with static method
T = datetime (nan (sz), 'ConvertFrom', 'datenum', 'Format', Format, ...
'TimeZone', TimeZone);
endfunction
%!assert_equal (isscalar (NaT), true);
%!assert_equal (isnat (NaT), true);
%!assert_equal (size (NaT (3)), [3, 3]);
%!assert_equal (size (NaT (2, 3, 4)), [2, 3, 4]);
%!error ...
%! NaT (1, 'Format', 2);
%!error ...
%! NaT (1, 'TimeZone', 2);
pr0m1th3as-datatypes-9c9a8d3/inst/PKG_ADD 0000664 0000000 0000000 00000000507 15227665741 0020050 0 ustar 00root root 0000000 0000000 addpath (fullfile (fileparts (canonicalize_file_name (mfilename ("fullpath"))), "demos"));
addpath (fullfile (fileparts (canonicalize_file_name (mfilename ("fullpath"))), "tests"));
setenv ("TZDATA", fullfile (fileparts (canonicalize_file_name (mfilename ("fullpath"))), "tzdata"));
warning ("off", "Octave:data-file-in-path")
pr0m1th3as-datatypes-9c9a8d3/inst/PKG_DEL 0000664 0000000 0000000 00000000275 15227665741 0020066 0 ustar 00root root 0000000 0000000 rmpath (fullfile (fileparts (canonicalize_file_name (mfilename ("fullpath"))), "demos"));
rmpath (fullfile (fileparts (canonicalize_file_name (mfilename ("fullpath"))), "tests"));
clear -c
pr0m1th3as-datatypes-9c9a8d3/inst/array2table.m 0000664 0000000 0000000 00000014601 15227665741 0021422 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{tbl} =} array2table (@var{A})
## @deftypefnx {datatypes} {@var{tbl} =} array2table (@var{A}, @var{Name}, @var{Value})
##
## Convert an array to a table.
##
## @code{@var{tbl} = array2table (@var{A})} converts the 2-D matrix @var{A} to
## the table @var{tbl}, where each column of @var{A} becomes a variable in
## @var{tbl}.
##
## @var{A} can be any type of array supported by @code{table}, including a cell
## array, as long they are constraint to 2 dimensions. However, in the case of
## a cell array @code{array2table} does not extract the contents of its cells,
## resulting to a table with each variable being a column of cells. Use
## @code{cell2table} if you want to create a table from the contents of the
## cells in @var{A}.
##
## @code{@var{tbl} = array2table (@var{A}, @var{Name}, @var{Value})} specifies
## optional parameters for creating the table @var{tbl} with the following
## Name-Value paired arguments.
##
## @multitable @columnfractions 0.23 0.75
## @headitem @var{Name} @tab @var{Value}
##
## @item @qcode{'VariableNames'} @tab A cell array of character vectors or
## a string array defining the variable names of @var{tbl}. The names must be
## valid variable names and unique.
##
## @item @qcode{'RowNames'} @tab A cell array of character vectors or
## a string array defining the row names of @var{tbl}. The names must be unique
## but not necessarily valid variable names.
##
## @item @qcode{'DimensionNames'} @tab A cell array of character vectors or
## a string array defining the dimension names of @var{tbl}. The names must be
## unique and not in conflict with variable names. By default, dimension names
## are @qcode{'Row', 'Variables'}.
## @end multitable
##
## @seealso{cell2table, struct2table, table}
## @end deftypefn
function tbl = array2table (A, varargin)
## Check input is a matrix
if (ndims (A) > 2)
error ("array2table: input array must be a 2-D array.");
endif
## Parse optional Name-Value paired arguments
optNames = {'VariableNames', 'RowNames', 'DimensionNames'};
dfValues = {{}, {}, {}};
[varNames, rowNames, dimNames, args] = parsePairedArguments ...
(optNames, dfValues, varargin);
## Split columns into separate input data arguments for table
varN = size (A, 2);
varValues = cell (1, varN);
for ix = 1:varN
varValues{ix} = A(:,ix);
endfor
## Handle variable names
if (! isempty (varNames))
if (numel (varNames) != varN)
error (strcat ("array2table: 'VariableNames' must match the", ...
" columns in input array."));
endif
else
varName = inputname (1);
if (isempty (varName))
varName = 'Var';
endif
varNames = cell (1, varN);
for ix = 1:varN
varNames{ix} = sprintf ('%s%d', varName, ix);
endfor
endif
optArgs = {'VariableNames', varNames};
## Handle remaining paired arguments
if (! isempty (rowNames))
if (numel (rowNames) != size (A, 1))
error ("array2table: 'RowNames' must match the rows in input array.");
endif
optArgs = [optArgs {'RowNames', rowNames}];
endif
if (! isempty (dimNames))
if (numel (dimNames) != 2)
error ("array2table: 'DimensionNames' must be a two-element vector.");
endif
optArgs = [optArgs {'DimensionNames', dimNames}];
endif
## Construct table
tbl = table (varValues{:}, optArgs{:});
endfunction
%!demo
%! ## `array2table` wraps the columns of a matrix as table variables. Without
%! ## names the variables are auto-labelled `Var1`, `Var2`, ...
%!
%! A = [38, 71, 176; 43, 69, 163; 40, 67, 133];
%! array2table (A)
%!demo
%! ## Supply `'VariableNames'` (and optionally `'RowNames'`) to label the result
%! ## as you convert — the columns of the matrix keep their order.
%!
%! A = [38, 71; 43, 69; 40, 67];
%! array2table (A, 'VariableNames', {'Age', 'Height'}, ...
%! 'RowNames', {'Li', 'Diaz', 'Brown'})
%!test
%! A = [1, 2; 3, 4];
%! tbl = array2table (A);
%! assert_equal (tbl.A1, [1; 3]);
%! assert_equal (tbl.A2, [2; 4]);
%! assert_equal (size (A), size (tbl));
%!test
%! tbl = array2table ([1, 2; 3, 4]);
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, [2; 4]);
%! assert_equal (size (tbl), [2, 2]);
%!test
%! tbl = array2table ([1, 2; 3, 4], 'VariableNames', {'A', 'B'});
%! assert_equal (tbl.A, [1; 3]);
%! assert_equal (tbl.B, [2; 4]);
%! assert_equal (isa (tbl.A, "double"), true);
%!test
%! tbl = array2table ([1, 2; 3, 4], "RowNames", {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, [2; 4]);
%! assert_equal (tbl.Properties.RowNames, {'A'; 'B'});
%! assert_equal (class (tbl('A', :)), 'table');
%! assert_equal (tbl{'A', :}, [1, 2]);
%!test
%! tbl = array2table ([1, 2; 3, 4], string ('DimensionNames'), {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, [2; 4]);
%! assert_equal (tbl.A, {});
%! assert_equal (tbl.B, [1, 2; 3, 4]);
%!test
%! tbl = array2table ([1, 2; 3, 4], "RowNames", {'A', 'B'}, ...
%! "DimensionNames", {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, [2; 4]);
%! assert_equal (tbl.A, {'A'; 'B'});
%! assert_equal (tbl.B, [1, 2; 3, 4]);
%!error ...
%! array2table (ones (3, 3, 3));
%!error ...
%! array2table ([1; 2; 3], 'VariableNames', {'A', 'B'});
%!error ...
%! array2table ([1; 2; 3], 'RowNames', {'A', 'B'});
%!error ...
%! array2table ([1; 2; 3], 'DimensionNames', {'A', 'B', 'C'});
pr0m1th3as-datatypes-9c9a8d3/inst/caldays.m 0000664 0000000 0000000 00000005243 15227665741 0020634 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{calD} =} caldays (@var{X})
##
## Calendar duration in days.
##
## @code{@var{calD} = caldays (@var{X})} returns a @qcode{calendarDuration}
## array representing calendar days equivalent to the values in @var{X}, which
## must be a numeric array of integer values.
##
## @code{caldays} is also available as a method for @qcode{calendarDuration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{calendarDuration, calyears, calquarters, calmonths, calweeks,
## calendarDuration.caldays}
## @end deftypefn
function out = caldays (x)
## Check input
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("caldays: input array must be numeric.");
elseif (! isreal (x))
error ("caldays: input array must be real.");
endif
xx = x;
xx(isnan (x)) = 0;
if (any (fix (xx(:)) != xx(:)))
error ("caldays: input array must contain only integer values.");
endif
out = calendarDuration (0, 0, double (x));
endfunction
%!demo
%! ## `caldays` builds a calendar duration of whole days. It is one of the
%! ## component builders (`calyears`, `calquarters`, `calmonths`, `calweeks`,
%! ## `caldays`) that you combine by addition to assemble a full span.
%!
%! caldays (10)
%!
%! ## A numeric array builds one duration per element.
%! caldays ([7, 14, 21])
%!test
%! X = magic (3);
%! D = caldays (X);
%! assert_equal (size (D), size (X));
%!test
%! D = caldays ([1, 2, 3]);
%! assert_equal (caldays (D), [1, 2, 3]);
%!test
%! D = caldays ([1, 2, NaN, 4]);
%! assert_equal (caldays (D), [1, 2, NaN, 4]);
%!test
%! D = caldays (int16 (1));
%! assert_equal (caldays (D), 1);
%!test
%! D = caldays ();
%! assert_equal (caldays (D), 1);
%!error caldays ("asd");
%!error caldays (1+i);
%!error ...
%! caldays (1.2);
pr0m1th3as-datatypes-9c9a8d3/inst/calendarDuration.m 0000664 0000000 0000000 00000244640 15227665741 0022501 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
classdef calendarDuration
## -*- texinfo -*-
## @deftp {datatypes} calendarDuration
##
## Array representing durations of time using flexible-length calendar
## date/time units.
##
## Each @code{calendarDuration} element stores internally the number of whole
## months, the number of whole days, and a @code{duration} object representing
## hours, minutes, and seconds. It can be used to simplify calculations on
## @code{datetime} arrays involving calendar units.
##
## @code{calendarDuration} arrays can be created through their constructor by
## combining numeric arrays representing individual calendar duration units or
## through the functions @code{caldays}, @code{calweeks}, @code{calmonths},
## @code{calquarters}, and @code{calyears}, which create calendar durations in
## terms of a single calendar duration unit. These functions are also
## available as methods of @code{calendarDuration} arrays to extract
## individual calendar duration units as numeric arrays.
##
## @seealso{datetime, duration}
## @end deftp
properties
## -*- texinfo -*-
## @deftp {duration} {property} Format
##
## Display format
##
## Display format, specified as a character vector or string scalar. If
## specified as a string scalar, it is converted and stored internally as
## a character vector.
##
## @end deftp
Format = 'ymdt'
endproperties
properties (SetAccess = private, Hidden)
## Whole calendar months
Months = 0
## Whole calendar days
Days = 0
## Time as duration
Time = duration
endproperties
methods (Hidden)
## Custom display
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, 'calendarDuration', in_name);
endfunction
## Custom display
function disp (this)
__disp__ (this, 'calendarDuration');
endfunction
endmethods
################################################################################
## ** Create and convert 'calendarDuration' type ** ##
################################################################################
## Available Methods ##
## ##
## 'duration' 'dispstrings' 'cellstr' 'char' ##
## 'datevec' 'time' 'split' 'caldays' ##
## 'calweeks' 'calmonths' 'calquarters' 'calyears' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{calD} =} calendarDuration (@var{X})
## @deftypefnx {calendarDuration} {@var{calD} =} calendarDuration (@var{Y}, @var{MO}, @var{D})
## @deftypefnx {calendarDuration} {@var{calD} =} calendarDuration (@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}, @var{S})
## @deftypefnx {calendarDuration} {@var{calD} =} calendarDuration (@var{Y}, @var{MO}, @var{D}, @var{T})
## @deftypefnx {calendarDuration} {@var{calD} =} calendarDuration (@dots{}, @qcode{'Format'}, @var{FMT})
##
## Create a new array of calendar durations.
##
## @code{@var{calD} = calendarDuration (@var{X})} returns an array of
## calendar durations from numeric matrix @var{X}, which must have either
## three or six columns, representing years, months, days, hours, minutes,
## and seconds, accordingly. All but seconds must be represented as whole
## duration units by integer values.
##
## @code{@var{calD} = calendarDuration (@var{Y}, @var{MO}, @var{D})} returns
## an array of calendar durations from numeric arrays @var{Y}, @var{MO}, and
## @var{D}, which correspond to years, months, and days, respectively. The
## size of @var{calD} is the common size of the numeric input arguments,
## which must be of the same size or scalars. A scalar input functions as a
## constant array of the same size as the other inputs.
##
## @code{@var{calD} = calendarDuration (@var{Y}, @var{MO}, @var{D}, @var{H},
## @var{MI}, @var{S})} returns an array of calendar durations from numeric
## arrays @var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}, and @var{S}, which
## correspond to years, months, days, hours, minutes, and seconds,
## respectively. The size of @var{calD} is the common size of the numeric
## input arguments, which must be of the same size or scalars. A scalar
## input functions as a constant array of the same size as the other inputs.
##
## @code{@var{calD} = calendarDuration (@var{Y}, @var{MO}, @var{D},
## @var{T})} returns an array of calendar durations from numeric arrays
## @var{Y}, @var{MO}, and @var{D}, which correspond to years, months, and
## days, as well as a time duration array @var{T}. The size of @var{calD}
## is the common size of the data input arguments, which must be of the same
## size or scalars. A scalar input functions as a constant array of the
## same size as the other inputs.
##
## Numeric input arrays @var{Y}, @var{MO}, @var{D}, @var{H}, and @var{MI}
## must contain integer values corresponding to whole calendar units.
## @var{S} can also be contain fractions of seconds.
##
## @code{@var{calD} = calendarDuration (@dots{}, @qcode{'Format'},
## @var{FMT})} specifies the format in which @var{calD} is displayed.
## @var{FMT} must be a character vector containing the following letters.
##
## @itemize
## @item @qcode{'y'} years
## @item @qcode{'q'} quarters of a year
## @item @qcode{'m'} months
## @item @qcode{'w'} weeks
## @item @qcode{'d'} days
## @item @qcode{'t'} time duration
## @end itemize
##
## Each character must be specified only once in the same order as they
## appear in the above list. @qcode{'m'}, @qcode{'d'}, and @qcode{'t'}
## characters must always be included in the format specification. Any
## characters besides these listed above are ignored.
##
## @code{@var{calD} = calendarDuration ()} returns a scalar array of
## calendar durations with a value of zero days. To create an empty
## calendarDuration array, use @code{calendarDuration ([], [], [])}.
##
## @seealso{calyears, calquarters, calmonths, calweeks, caldays,
## calendarDuration, iscalendarduration, datetime, duration}
## @end deftypefn
function this = calendarDuration (varargin)
## Return a scalar calendarDuration object
if (nargin == 0)
return
endif
## Parse optional Name-Value paired arguments
optNames = {'Format'};
dfValues = {[]};
[Format, args] = parsePairedArguments (optNames, dfValues, varargin(:));
## Check optional 'Format' argument
if (! isempty (Format))
errmsg = checkFormatString (Format);
if (! isempty (errmsg))
error ("calendarDuration: 'Format' %s", errmsg);
endif
this.Format = Format;
endif
## Parse inputs
switch (numel (args))
## this = calendarDuration ()
case 0
return
## this = calendarDuration (X)
case 1
X = args{1};
if (! (isnumeric (X) && ismatrix (X)))
error ("calendarDuration: X must be a numeric matrix.");
endif
if (! isreal (X))
error ("calendarDuration: X must be real.");
endif
if (size (X, 2) == 3)
tmp = X(:);
tmp(isnan (tmp)) = 0;
if (any (fix (tmp) != tmp))
error (strcat ("calendarDuration: years, months,", ...
" and days must be integer values."));
endif
Y = X(:,1);
M = X(:,2);
D = X(:,3);
T = duration (zeros (size (X)));
elseif (size (X, 2) == 6)
tmp = X(:,[1:5]);
tmp(isnan (tmp)) = 0;
if (any (fix (tmp) != tmp, 'all'))
error (strcat ("calendarDuration: years, months, days,", ...
" hours, and minutes must be integer values."));
endif
Y = X(:,1);
M = X(:,2);
D = X(:,3);
T = duration (X(:,[4:6]));
else
error ("calendarDuration: X must have either 3 or 6 columns.");
endif
## this = calendarDuration (Y, M, D)
case 3
[Y, M, D] = args{:};
if (! (isnumeric (Y) && isnumeric (M) && isnumeric (D)))
error ("calendarDuration: Y, MO, and D must be a numeric arrays.");
endif
if (! (isreal (Y) && isreal (M) && isreal (D)))
error ("calendarDuration: Y, MO, and D must be real.");
endif
## Expand as necessary
if (! isscalar (Y) || ! isscalar (M) || ! isscalar (D))
[err, Y, M, D] = common_size (Y, M, D);
if (err > 0)
error (strcat ("calendarDuration: Y, MO, and D must", ...
" be of common size or scalars."));
endif
endif
tmp = [Y(:), M(:), D(:)];
tmp(isnan (tmp)) = 0;
if (any (fix (tmp) != tmp, 'all'))
error (strcat ("calendarDuration: years, months,", ...
" and days must be integer values."));
endif
T = repmat (duration (0, 0, 0), size (Y));
## this = calendarDuration (Y, M, D, T)
case 4
[Y, M, D, T] = args{:};
if (! (isnumeric (Y) && isnumeric (M) && isnumeric (D)))
error ("calendarDuration: Y, MO, and D must be a numeric arrays.");
endif
if (! (isreal (Y) && isreal (M) && isreal (D)))
error ("calendarDuration: Y, MO, and D must be real.");
endif
if (! isa (T, "duration"))
error ("calendarDuration: T must be a duration array.");
endif
## Expand as necessary
t = ones (size (T));
if (! isscalar (Y) || ! isscalar (M) || ! isscalar (D) || ...
! isscalar (t))
[err, Y, M, D, t] = common_size (Y, M, D, t);
if (err > 0)
error (strcat ("calendarDuration: Y, MO, D, and T", ...
" must be of common size or scalars."));
endif
if (! isequal (size (T), size (t)))
T = repmat (T, size (t));
endif
endif
tmp = [Y(:), M(:), D(:)];
tmp(isnan (tmp)) = 0;
if (any (fix (tmp) != tmp, 'all'))
error (strcat ("calendarDuration: years, months,", ...
" and days must be integer values."));
endif
## this = calendarDuration (Y, M, D, H, MI, S)
case 6
[Y, M, D, H, MI, S] = args{:};
if (! (isnumeric (Y) && isnumeric (M) && isnumeric (D) &&
isnumeric (H) && isnumeric (MI) && isnumeric (S)))
error (strcat ("calendarDuration: Y, MO, D, H, MI,", ...
" and S must be numeric arrays."));
endif
if (! (isreal (Y) && isreal (M) && isreal (D) &&
isreal (H) && isreal (MI) && isreal (S)))
error ("calendarDuration: numeric input data must be real.");
endif
## Expand as necessary
if (! isscalar (Y) || ! isscalar (M) || ! isscalar (D) ||
! isscalar (H) || ! isscalar (MI) || ! isscalar (S))
[err, Y, M, D, H, MI, S] = common_size (Y, M, D, H, MI, S);
if (err > 0)
error (strcat ("calendarDuration: Y, MO, D, H, MI, and", ...
" S must be of common size or scalars."));
endif
endif
tmp = [Y(:), M(:), D(:), H(:), MI(:)];
tmp(isnan (tmp)) = 0;
if (any (fix (tmp) != tmp, 'all'))
error (strcat ("calendarDuration: years, months, days,", ...
" hours, and minutes must be integer values."));
endif
T = duration (H, MI, S);
otherwise
error ("calendarDuration: invalid number of input arguments.");
endswitch
## Construction
this.Months = double (Y) * 12 + double (M);
this.Days = double (D);
this.Time = T;
## Broadcast NaNs
this = broadcastProperties (this);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{cstr} =} dispstrings (@var{calD})
##
## Get display formatted strings for each element of a calendarDuration
## array.
##
## @code{@var{cstr} = dispstrings (@var{calD})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## calendarDuration array, @var{calD}. The returned text representations
## in @var{cstr} are formatted according to the @qcode{'Format'} property
## of the input array @var{calD}.
##
## @end deftypefn
function cstr = dispstrings (this)
## Process all elements
sz = size (this);
cstr = cell (sz);
for i = 1:prod (sz)
calDur = subset (this, i);
if (isnan (calDur.Months))
cstr{i} = 'NaN';
elseif (isinf (calDur.Months))
cstr{i} = num2str (calDur.Months);
else
els = {};
## Check Format contains 'y' to split between years and months
if (! isempty (strfind (calDur.Format, 'y')))
years = fix (calDur.Months / 12);
months = rem (calDur.Months, 12);
if (years != 0)
els{end+1} = sprintf ('%dy', years);
endif
if (months != 0)
## Check Format contains 'q' to split between quarters and months
if (! isempty (strfind (calDur.Format, 'q')))
quarters = fix (months / 3);
months = rem (months, 3);
if (quarters != 0)
els{end+1} = sprintf ('%dq', quarters);
endif
if (months != 0)
els{end+1} = sprintf ('%dmo', months);
endif
else
els{end+1} = sprintf ('%dmo', months);
endif
endif
else
if (calDur.Months != 0)
## Check Format contains 'q' to split between quarters and months
if (! isempty (strfind (calDur.Format, 'q')))
quarters = fix (calDur.Months / 3);
months = rem (calDur.Months, 3);
if (quarters != 0)
els{end+1} = sprintf ('%dq', quarters);
endif
if (months != 0)
els{end+1} = sprintf ('%dmo', months);
endif
else
els{end+1} = sprintf ('%dmo', calDur.Months);
endif
endif
endif
if (calDur.Days != 0)
## Check Format contains 'w' to print whole weeks and subtract
## them from days
if (! isempty (strfind (calDur.Format, 'w')))
weeks = fix (calDur.Days / 7);
if (weeks != 0)
els{end+1} = sprintf ('%dw', weeks);
calDur.Days -= weeks * 7;
endif
endif
if (calDur.Days != 0)
els{end+1} = sprintf ('%dd', calDur.Days);
endif
endif
millis = milliseconds (calDur.Time);
if (abs (millis) > 4e-12)
sec = millis / 1000;
fracSec = rem (sec,1);
x = fix (sec);
hours = fix (x / (60 * 60));
x = rem (x, (60 * 60));
minutes = fix (x / 60);
x = rem (x, 60);
seconds = x;
msec = round (fracSec * 1000);
if (abs (msec) == 1000)
seconds = seconds + (msec / 1000);
msec = 0;
endif
if (msec >= 1)
str = sprintf ('%ds', msec / 1000);
str(1) = [];
els{end+1} = sprintf ('%dh %dm %d%s', hours, minutes, ...
seconds, str);
elseif (fracSec > 0 && fracSec < 0.001 && seconds == 0)
els{end+1} = sprintf ('%dh %dm %0.0es', hours, minutes, fracSec);
else
els{end+1} = sprintf ('%dh %dm %ds', hours, minutes, seconds);
endif
endif
if (isempty (els))
els = {'0d'};
endif
cstr{i} = strjoin (els, ' ');
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{cstr} =} cellstr (@var{calD})
## @deftypefnx {calendarDuration} {@var{cstr} =} cellstr (@var{calD}, @var{FMT})
##
## Convert calendarDuration array to a cell array of character vectors.
##
## @code{@var{cstr} = cellstr (@var{calD})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## @var{calD}. @var{cstr} contains the string representations of the
## calendar durations in @var{calD}.
##
## @code{@var{cstr} = cellstr (@var{calD}, @var{FMT})} further specifies
## the format of the returned string representations. @var{FMT} must be a
## character vector conforming to the same specifications required by the
## constructor's @qcode{'Format'} property paired argument. Note that
## @code{cellstr} only accepts @var{FMT} as a single argument and not as a
## property paired argument.
##
## @end deftypefn
function cstr = cellstr (this, FMT = '')
if (! isempty (FMT))
errmsg = checkFormatString (FMT);
if (! isempty (errmsg))
error ("calendarDuration.cellstr: FMT %s", errmsg);
endif
this.Format = FMT;
endif
cstr = dispstrings (this);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{cmat} =} char (@var{calD})
## @deftypefnx {calendarDuration} {@var{cmat} =} char (@var{calD}, @var{FMT})
##
## Convert calendarDuration array to a character matrix.
##
## @code{@var{cmat} = char (@var{calD})} returns a character matrix with
## one row per element in @var{calD}. The second optional argument,
## @var{FMT}, can be used to specify the format of the returned string
## representations of the calendarDuration input array @var{calD}.
##
## @end deftypefn
function cmat = char (this, FMT = '')
if (! isempty (FMT))
errmsg = checkFormatString (FMT);
if (! isempty (errmsg))
error ("calendarDuration.char: FMT %s", errmsg);
endif
this.Format = FMT;
endif
cmat = char (dispstrings (this));
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{DV} =} datevec (@var{calD})
## @deftypefnx {calendarDuration} {[@var{Y}, @var{MO}] =} datevec (@var{calD})
## @deftypefnx {calendarDuration} {[@var{Y}, @var{MO}, @var{D}] =} datevec (@var{calD})
## @deftypefnx {calendarDuration} {[@var{Y}, @var{MO}, @var{D}, @var{H}] =} datevec (@var{calD})
## @deftypefnx {calendarDuration} {[@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}] =} datevec (@var{calD})
## @deftypefnx {calendarDuration} {[@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}, @var{S}] =} datevec (@var{calD})
##
## Convert calendarDuration array to date vectors.
##
## @code{@var{DV} = datevec (@var{calD})} returns an @math{N*6} numeric
## matrix, where @math{N} is the number of elements in @var{calD} and the
## columns corresponds to years, months, days, hours, minutes, and seconds,
## respectively.
##
## When @code{datevec} is called with more than one output arguments, then
## it returns the components of the date vectors as individual variables
## @var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI},and @var{S} corresponding
## to years, months, days, hours, minutes, and seconds, respectively. In
## this case, the individual variables have the same size as the input array
## @var{calD}.
##
## @end deftypefn
function varargout = datevec (this)
[h, m, s] = hms (this.Time);
years = fix (this.Months / 12);
months = rem (this.Months, 12);
DV = [years(:), months(:), this.Days(:), h(:), m(:), s(:)];
if (nargout == 0 || nargout == 1)
varargout{1} = DV;
elseif (nargout <= 6)
varargout{1} = years;
varargout{2} = months;
if (nargout > 2)
varargout{3} = this.Days;
endif
if (nargout > 3)
varargout{4} = h;
endif
if (nargout > 4)
varargout{5} = m;
endif
if (nargout > 5)
varargout{6} = s;
endif
else
error ("calendarDuration.datevec: too many output arguments.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{T} =} time (@var{calD})
##
## Return time portion of calendarDuration array.
##
## @code{@var{T} = time (@var{calD})} returns a duration array @var{T} with
## the time portions of the calendarDuration array @var{calD}.
##
## @end deftypefn
function T = time (this)
T = this.Time;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {[@dots{}] =} split (@var{calD}, @var{units})
##
## Split calendarDuration array into numeric and duration units.
##
## @code{[@dots{}] = split (@var{calD}, @var{units})} splits the calendar
## duration units in @var{calD} into separate numeric arrays according to
## date/time units specified in @var{units}, which must be either a cell
## array of character vectors or a string array containing any of the
## following date/time units in descending order.
##
## @enumerate
## @item @qcode{'years'}
## @item @qcode{'quarters'}
## @item @qcode{'months'}
## @item @qcode{'weeks'}
## @item @qcode{'days'}
## @item @qcode{'time'}
## @end enumerate
##
## When a single date/time unit is specified, @var{units} may also be a
## character vector. When @qcode{'time'} is specified in @var{units}, the
## corresponding returned argument is a @code{duration} array. The values
## of years, quarters, and months are computed independently from the values
## of weeks and days in @var{calD}, with larger units taking precedence when
## specified The same applies for duration arrays, when requested.
##
## @end deftypefn
function varargout = split (this, units)
## Check input
if (nargin < 2)
error ("calendarDuration.split: too few input arguments.");
endif
if (isstring (units) || ischar (units))
units = cellstr (units);
elseif (! iscellstr (units))
error ("calendarDuration.split: invalid input type for UNITS.");
endif
valid_units = {'years', 'quarters', 'months', 'weeks', 'days', 'time'};
idx_units = ismember (tolower (units), valid_units);
if (! all (idx_units))
error ("calendarDuration.split: '%s' is not a valid time unit.", ...
units{find (! idx_units)});
endif
idx_order = cellfun (@(x) find (strcmpi (x, valid_units)), units);
if (any (diff (idx_order) < 0))
error (strcat ("calendarDuration.split: UNITS must", ...
" be specified in descending order."));
endif
## Check output
n_args = numel (units);
if (nargout != n_args)
error ("calendarDuration.split: wrong number of output arguments.");
endif
months = this.Months;
days = this.Days;
for i = 1:n_args
unit = units{i};
if (strcmpi (unit, 'years'))
years = fix (months / 12);
months = months - years * 12;
varargout{i} = years;
elseif (strcmpi (unit, 'quarters'))
quarters = fix (months / 3);
months = months - quarters * 3;
varargout{i} = quarters;
elseif (strcmpi (unit, 'months'))
varargout{i} = months;
elseif (strcmpi (unit, 'weeks'))
weeks = fix (days / 7);
days = days - weeks * 7;
varargout{i} = weeks;
elseif (strcmpi (unit, 'days'))
varargout{i} = days;
elseif (strcmpi (unit, 'time'))
varargout{i} = this.Time;
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{X} =} caldays (@var{calD})
##
## Calendar duration in days.
##
## @code{@var{X} = caldays (@var{calD})} returns a numeric array with the
## number of days as represented in @var{calD}.
##
## @code{caldays} is also available as a function, in which case it performs
## the opposite conversion.
##
## @seealso{calendarDuration.calyears, calendarDuration.calquarters,
## calendarDuration.calmonths, calendarDuration.calweeks, caldays}
## @end deftypefn
function out = caldays (this)
out = this.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{X} =} calweeks (@var{calD})
##
## Calendar duration in weeks.
##
## @code{@var{X} = calweeks (@var{calD})} returns a numeric array with the
## number of weeks as represented in @var{calD}.
##
## @code{calweeks} is also available as a function, in which case it
## performs the opposite conversion.
##
## @seealso{calendarDuration.calyears, calendarDuration.calquarters,
## calendarDuration.calmonths, calendarDuration.caldays, calweeks}
## @end deftypefn
function out = calweeks (this)
out = fix (this.Days / 7);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{X} =} calmonths (@var{calD})
##
## Calendar duration in months.
##
## @code{@var{X} = calmonths (@var{calD})} returns a numeric array with the
## number of months as represented in @var{calD}.
##
## @code{calmonths} is also available as a function, in which case it
## performs the opposite conversion.
##
## @seealso{calendarDuration.calyears, calendarDuration.calquarters,
## calendarDuration.calweeks, calendarDuration.caldays, calmonths}
## @end deftypefn
function out = calmonths (this)
out = this.Months;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{X} =} calquarters (@var{calD})
##
## Calendar duration in quarters.
##
## @code{@var{X} = calquarters (@var{calD})} returns a numeric array with
## the number of quarters as represented in @var{calD}.
##
## @code{calquarters} is also available as a function, in which case it
## performs the opposite conversion.
##
## @seealso{calendarDuration.calyears, calendarDuration.calmonths,
## calendarDuration.calweeks, calendarDuration.caldays, calquarters}
## @end deftypefn
function out = calquarters (this)
out = fix (this.Months / 3);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{X} =} calyears (@var{calD})
##
## Calendar duration in years.
##
## @code{@var{X} = calyears (@var{calD})} returns a numeric array with the
## number of years as represented in @var{calD}.
##
## @code{calyears} is also available as a function, in which case it
## performs the opposite conversion.
##
## @seealso{calendarDuration.calquarters, calendarDuration.calmonths,
## calendarDuration.calweeks, calendarDuration.caldays, calyears}
## @end deftypefn
function out = calyears (this)
out = fix (this.Months / 12);
endfunction
endmethods
################################################################################
## ** Summary Information ** ##
################################################################################
## Available Methods ##
## ##
## 'size' 'ndims' 'numel' 'nnz' ##
## 'length' 'keyHash' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{sz} =} size (@var{calD})
## @deftypefnx {calendarDuration} {@var{dim_sz} =} size (@var{calD}, @var{dim})
## @deftypefnx {calendarDuration} {@var{dim_sz} =} size (@var{calD}, @var{d1}, @var{d2}, @dots{})
## @deftypefnx {calendarDuration} {[@var{rows}, @var{columns}, @dots{}, @var{dim_n_sz}] =} size (@dots{})
##
## Size of a calendarDuration array.
##
## @code{@var{sz} = size (@var{calD})} returns a row vector with the size
## (number of elements) of each dimension for the calendar duration array
## @var{calD}.
##
## @code{@var{dim_sz} = size (@var{calD}, @var{dim})} returns the size of
## the corresponding dimension specified in @var{dim}. If @var{dim} is a
## vector, then @var{dim_sz} is a vector of the same length and with each
## element corresponding to a specified dimension. Multiple dimensions may
## also be specified as separate arguments.
##
## With a single output argument, @code{size} returns a row vector. When
## called with multiple output arguments, @code{size} returns the size of
## dimension N in the Nth argument.
##
## @end deftypefn
function varargout = size (this, varargin)
if (! isempty (varargin))
sz = size (this.Months, varargin{:});
else
sz = size (this.Months);
endif
if (nargout == 0 || nargout == 1)
varargout{1} = sz;
elseif (numel (sz) != nargout)
error (strcat ("calendarDuration.size: number of output arguments", ...
" does not match number of requested dimensions."));
else
for i = 1:nargout
varargout{i} = sz(i);
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{out} =} ndims (@var{calD})
##
## Number of dimensions in a calendarDuration array.
##
## @code{@var{out} = ndims (@var{calD})} returns the number of dimensions
## of the calendar duration array @var{calD}.
##
## @end deftypefn
function out = ndims (this)
out = ndims (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{out} =} numel (@var{calD})
##
## Total number of elements in a calendarDuration array.
##
## @code{@var{out} = numel (@var{calD})} returns the number of elements in
## the calendarDuration array @var{calD}.
##
## @end deftypefn
function out = numel (this, varargin)
out = numel (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{out} =} nnz (@var{calD})
##
## Number of nonzero elements in calendarDuration array.
##
## @code{@var{out} = nnz (@var{calD})} returns the number of nonzero
## elements in the calendar duration array @var{calD}.
##
## @end deftypefn
function out = nnz (this)
m = this.Months(:);
d = this.Days(:);
h = hours (this.Time(:));
out = numel (m) - sum (m == 0 & d == 0 & h == 0);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{N} =} length (@var{calD})
##
## Length of a calendarDuration vector.
##
## @code{@var{N} = length (@var{calD})} returns the size of the longest
## dimension of the calendarDuration array @var{calD}, unless any of its
## dimensions has zero length, in which case @code{length (@var{calD})}
## returns 0.
##
## @end deftypefn
function N = length (this)
if (isempty (this.Months))
N = 0;
else
N = max (size (this.Months));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{hey} =} keyHash (@var{calD})
## @deftypefnx {calendarDuration} {@var{hey} =} keyHash (@var{calD}, @var{base})
##
## Generate a hash code for a calendarDuration array.
##
## @code{@var{h} = keyHash (@var{calD})} generates a @qcode{uint64} scalar
## that represents the input array @var{calD}. @code{keyHash} utilizes the
## 64-bit FNV-1a variant of the Fowler-Noll-Vo non-cryptographic hash
## function.
##
## @code{@var{h} = keyHash (@var{calD}), @var{base}} also generates a 64-bit
## hash code using @var{base} as the offset basis for the FNV-1a hash
## algorithm. @var{base} must be a @qcode{uint64} integer type scalar. Use
## this syntax to cascade @code{keyHash} on multiple objects for which a
## single hash code is required.
##
## Note that unlike MATLAB, this implementation does not use any random
## seed. As a result, @code{keyHash} will always generate the exact same
## hash key for any particular input across different workers and Octave
## sessions.
##
## @end deftypefn
function key = keyHash (this, base = [])
## Initialize string with size and class name
size_str = sprintf ('%dx', size (this.Months))(1:end-1);
init_str = [size_str 'calendarDuration'];
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("calendarDuration.keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__(init_str, base);
else
key = __ckeyHash__(init_str);
endif
## Compute hash with underlying calendarDuration array values
if (! isempty (this.Months))
key = __nkeyHash__(this.Months(:), key);
key = __nkeyHash__(this.Days(:), key);
key = keyHash (this.Time, key);
endif
endfunction
endmethods
################################################################################
## ** Query Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'iscolumn' 'isempty' 'isequal' 'isequaln' ##
## 'isfinite' 'isinf' 'ismatrix' 'ismissing' ##
## 'isnan' 'isreal' 'isrow' 'isscalar' ##
## 'isvector' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} iscolumn (@var{calD})
##
## Return true if calendarDuration array is a column vector.
##
## @code{@var{TF} = iscolumn (@var{calD})} returns a logical scalar
## @var{TF}, which is @qcode{true} if the calendar duration array @var{calD}
## is a column vector and @qcode{false} otherwise. A column vector is a 2-D
## array for which @code{size (@var{X})} returns @code{[@var{N}, 1]} with
## non-negative @var{N}.
##
## @end deftypefn
function TF = iscolumn (this)
TF = iscolumn (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isempty (@var{calD})
##
## Return true if calendarDuration array is empty.
##
## @code{@var{TF} = isempty (@var{calD})} returns a logical scalar @var{TF},
## which is @qcode{true} if the calendar duration array @var{calD} is empty
## and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isempty (this)
TF = isempty (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isequal (@var{calD1}, @var{calD2})
## @deftypefnx {calendarDuration} {@var{TF} =} isequal (@var{calD1}, @var{calD2}, @dots{})
##
## Return true if calendarDuration arrays are equal.
##
## @code{@var{TF} = isequal (@var{calD1}, @var{calD2})} returns a logical
## scalar @var{TF}, which is @qcode{true} if the calendar duration arrays
## @var{calD1} and @var{calD2} contain the same values and @qcode{false}
## otherwise.
##
## @code{@var{TF} = isequal (@var{calD1}, @var{calD2}, @dots{})} returns a
## logical scalar @var{TF}, which is @qcode{true} if all input arguments are
## calendar duration arrays with equal values in each corresponding elements
## and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequal (this, varargin)
if (numel (varargin) < 1)
error ("calendarDuration.isequal: too few input arguments.");
endif
n_dim = size (this);
for i = 1:numel (varargin)
tmp = varargin{i};
if (! isa (tmp, 'calendarDuration'))
error (strcat ("calendarDuration.isequal: all input arguments", ...
" must be calendarDuration arrays."));
endif
if (! isequal (n_dim, size (tmp)))
TF = false;
return;
endif
if (this == tmp)
TF = true;
else
TF = false;
return;
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isequaln (@var{calD1}, @var{calD2})
## @deftypefnx {calendarDuration} {@var{TF} =} isequaln (@var{calD1}, @var{calD2}, @dots{})
##
## Return true if calendarDuration arrays are equal under the assumption
## that missing elements are equal.
##
## @code{@var{TF} = isequaln (@var{calD1}, @var{calD2})} returns a logical
## scalar @var{TF}, which is @qcode{true} if the calendar duration arrays
## @var{calD1} and @var{calD2} contain the same values or corresponding
## missing elements and @qcode{false} otherwise.
##
## @code{@var{TF} = isequaln (@var{calD1}, @var{calD2}, @dots{})} returns a
## logical scalar @var{TF}, which is @qcode{true} if all input arguments
## are calendar duration arrays with equal values or corresponding missing
## elements and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequaln (this, varargin)
if (numel (varargin) < 1)
error ("calendarDuration.isequaln: too few input arguments.");
endif
n_dim = size (this);
## Force NaNs to zeros
i_nan = isnan (this);
if (any (i_nan, 'all'))
this.Months(i_nan) = 0;
this.Days(i_nan) = 0;
this.Time(i_nan) = duration (0, 0, 0);
endif
for i = 1:numel (varargin)
tmp = varargin{i};
if (! isa (tmp, 'calendarDuration'))
error (strcat ("calendarDuration.isequaln: all input arguments", ...
" must be calendarDuration arrays."));
endif
if (! isequal (n_dim, size (tmp)))
TF = false;
return;
endif
## Force NaNs to zeros
i_nan = isnan (tmp);
if (any (i_nan, 'all'))
tmp.Months(i_nan) = 0;
tmp.Days(i_nan) = 0;
tmp.Time(i_nan) = duration (0, 0, 0);
endif
if (this == tmp)
TF = true;
else
TF = false;
return;
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isfinite (@var{calD})
##
## Return true for calendar durations that are finite.
##
## @code{@var{TF} = isfinite (@var{calD})} returns a logical array @var{TF}
## of the same size as @var{calD} containing @qcode{true} for each
## corresponding element of @var{calD} that is finite and @qcode{false}
## otherwise. Finite elements are those which are neither infinite nor
## Not-A-Number.
##
## @end deftypefn
function TF = isfinite (this)
TF = isfinite (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isinf (@var{calD})
##
## Return true for calendar durations that are infinite.
##
## @code{@var{TF} = isinf (@var{calD})} returns a logical array @var{TF}
## of the same size as @var{calD} containing @qcode{true} for each
## corresponding element of @var{calD} that is either @qcode{Inf} or
## @qcode{-Inf} and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isinf (this)
TF = isinf (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} ismatrix (@var{calD})
##
## Return true if calendarDuration array is a 2-D array.
##
## @code{@var{TF} = ismatrix (@var{calD})} returns a logical scalar
## @var{TF}, which is @qcode{true} if the calendarDuration array @var{calD}
## is a matrix and @qcode{false} otherwise. A matrix is an array of any
## type where @code{ndims (@var{X}) == 2} and for which
## @code{size (@var{X})} returns @code{[@var{H}, @var{W}]} with non-negative
## @var{H} and @var{W}.
##
## @end deftypefn
function TF = ismatrix (this)
TF = ismatrix (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} ismissing (@var{calD})
##
## Find missing data in a calendarDuration array.
##
## Missing values in calendarDuration arrays are represented by @qcode{NaN},
## thus @code{@var{TF} = ismissing (@var{calD})} is equivalent to
## @code{@var{TF} = isnan (@var{calD})}.
##
## Note: @code{ismissing} for calendarDuration arrays does not support a
## second @var{Indicator} argument.
##
## @end deftypefn
function TF = ismissing (this, varargin)
if (nargin > 1)
error ("calendarDuration.ismissing: Indicators are not supported.");
endif
TF = isnan (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isnan (@var{calD})
##
## Return true for calendar durations that are Not-A-Number.
##
## @code{@var{TF} = isnan (@var{calD})} returns a logical array @var{TF}
## of the same size as @var{calD} containing @qcode{true} for each
## corresponding element of @var{calD} that is @qcode{NaN} and @qcode{false}
## otherwise.
##
## @end deftypefn
function TF = isnan (this)
TF = isnan (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isreal (@var{calD})
##
## Always return true for calendarDuration arrays.
##
## @code{@var{TF} = isreal (@var{calD})} always returns a logical scalar
## @qcode{true} value, if the input argument is a calendarDuration array.
##
## @end deftypefn
function TF = isreal (this)
TF = true;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isrow (@var{calD})
##
## Return true if calendarDuration array is a row vector.
##
## @code{@var{TF} = isrow (@var{calD})} returns a logical scalar @var{TF},
## which is @qcode{true} if the calendarDuration array @var{calD} is a row
## vector and @qcode{false} otherwise. A row vector is a 2-D array for
## which @code{size (@var{X})} returns @code{[1, @var{N}]} with non-negative
## @var{N}.
##
## @end deftypefn
function TF = isrow (this)
TF = isrow (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isscalar (@var{calD})
##
## Return true if calendarDuration array is a scalar.
##
## @code{@var{TF} = isscalar (@var{calD})} returns a logical scalar
## @var{TF}, which is @qcode{true} if the calendarDuration array @var{calD}
## is also a scalar and @qcode{false} otherwise. A scalar is a single
## element object for which @code{size (@var{X})} returns @code{[1, 1]}.
##
## @end deftypefn
function TF = isscalar (this)
TF = isscalar (this.Months);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} isvector (@var{calD})
##
## Return true if calendarDuration array is a vector.
##
## @code{@var{TF} = isvector (@var{calD})} returns a logical scalar
## @var{TF}, which is @qcode{true} if the calendarDuration array @var{calD}
## is a vector and @qcode{false} otherwise. A vector is a 2-D array for
## which one of the dimensions is equal to 1 (either @math{1*N} or
## @math{N*1}). By definition, a scalar is also a vector.
##
## @end deftypefn
function TF = isvector (this)
TF = isvector (this.Months);
endfunction
endmethods
################################################################################
## ** Mathematical Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'minus' 'uminus' 'plus' 'uplus' ##
## 'times' 'mtimes' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} minus (@var{A}, @var{B})
##
## Subtraction for calendarDuration arrays.
##
## @code{@var{C} = minus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} - @var{B}} and returns the result of subtracting
## the corresponding elements of @var{B} from those of @var{A}. @var{C} is
## a calendarDuration array of the same size as the input arguments after
## the necessary (if required) expansion. @var{A} and @var{B} must be size
## compatible, which translates to they can be the same size, one can be
## scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## Either @var{A} or @var{B} may also be a duration or a numeric array with
## the latter representing duration days and being internally converted to a
## duration array with the @code{days ()} function.
##
## @end deftypefn
function out = minus (A, B)
if (isa (A, 'calendarDuration') && isa (B, 'calendarDuration'))
out = A;
out.Months = A.Months - B.Months;
out.Days = A.Days - B.Days;
out.Time = A.Time - B.Time;
elseif (isa (A, 'calendarDuration') && isa (B, 'duration'))
out = A;
tmp = zeros (size (B));
out.Months = A.Months - tmp;
out.Days = A.Days - tmp;
out.Time = A.Time - B;
elseif (isa (A, 'calendarDuration') && isnumeric (B))
out = A;
tmp = zeros (size (B));
out.Months = out.Months - tmp;
out.Days = out.Days - tmp;
out.Time = out.Time - days (B);
elseif (isnumeric (A) && isa (B, 'calendarDuration'))
out = B;
tmp = zeros (size (A));
out.Months = -out.Months + tmp;
out.Days = -out.Days + tmp;
out.Time = -out.Time + days (A);
else
error (strcat ("calendarDuration: subtraction is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
out = broadcastProperties (out);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} minus (@var{A})
##
## Unary minus for calendarDuration arrays.
##
## @code{@var{C} = uminus (@var{A})} is the equivalent of the syntax
## @code{@var{C} = -@var{A}} and returns @var{A} after negating its
## elements. @var{C} is a calendarDuration array of the same size as
## @var{A}.
##
## @end deftypefn
function out = uminus (A)
out = A;
out.Months = -A.Months;
out.Days = -A.Days;
out.Time = -A.Time;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} plus (@var{A}, @var{B})
##
## Addition for calendarDuration arrays.
##
## @code{@var{C} = plus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} + @var{B}} and returns the result of adding the
## corresponding elements of @var{A} and @var{B}. @var{C} is a
## calendarDuration array of the same size as the input arguments after the
## necessary (if required) expansion. @var{A} and @var{B} must be size
## compatible, which translates to they can be the same size, one can be
## scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## Either @var{A} or @var{B} may also be a duration or a numeric array with
## the latter representing duration days and being internally converted to a
## duration array with the @code{days ()} function.
##
## @end deftypefn
function out = plus (A, B)
if (isa (B, 'datetime'))
out = B + A;
return;
endif
if (isa (A, 'calendarDuration') && isa (B, 'calendarDuration'))
out = A;
out.Months = A.Months + B.Months;
out.Days = A.Days + B.Days;
out.Time = A.Time + B.Time;
out = broadcastProperties (out);
elseif (isa (A, 'calendarDuration') && isa (B, 'duration'))
out = A;
tmp = zeros (size (B));
out.Months = A.Months + tmp;
out.Days = A.Days + tmp;
out.Time = A.Time + B;
elseif (isa (A, 'calendarDuration') && isnumeric (B))
out = A;
tmp = zeros (size (B));
out.Months = A.Months + tmp;
out.Days = A.Days + tmp;
out.Time = A.Time + days (B);
elseif (isnumeric (A) && isa (B, 'calendarDuration'))
out = B;
tmp = zeros (size (A));
out.Months = B.Months + tmp;
out.Days = B.Days + tmp;
out.Time = B.Time + days (A);
else
error (strcat ("calendarDuration: addition is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} uplus (@var{A})
##
## Unary plus for calendarDuration arrays.
##
## @code{@var{C} = uplus (@var{A})} is the equivalent of the syntax
## @code{@var{C} = +@var{A}} and returns a copy of @var{A}. @var{C} is a
## calendarDuration array of the same size as @var{A}.
##
## @end deftypefn
function out = uplus (A)
out = A;
out.Months = A.Months;
out.Days = A.Days;
out.Time = A.Time;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} times (@var{A}, @var{B})
##
## Element-by-element multiplication for calendarDuration arrays.
##
## @code{@var{C} = times (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} .* @var{B}} and returns the element-by-element
## multiplication product of inputs @var{A} and @var{B}. Either @var{A} or
## @var{B} must be a calendarDuration array and its complement must be a
## double array.
##
## @var{C} is a calendarDuration array of the same size as the input
## arguments after the necessary (if required) expansion. @var{A} and
## @var{B} must be size compatible, which translates to they can be the same
## size, one can be scalar, or for every dimension, their dimension sizes
## must be equal or one of them must be 1.
##
## @end deftypefn
function out = times (A, B)
if (isa (A, 'calendarDuration') && isnumeric (B))
out = A;
tmp = double (B);
elseif (isnumeric (A) && isa (B, 'calendarDuration'))
out = B;
tmp = double (A);
else
error (strcat ("calendarDuration: multiplication is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
out.Months = out.Months .* tmp;
out.Days = out.Days .* tmp;
out.Time = out.Time .* tmp;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} mtimes (@var{A}, @var{B})
##
## Matrix multiplication for calendarDuration arrays.
##
## @code{@var{C} = mtimes (@var{A}, @var{B})} is the equivalent of the
## syntax @code{@var{C} = @var{A} * @var{B}} and returns the matrix
## multiplication product of inputs @var{A} and @var{B}. Either @var{A} or
## @var{B} must be a calendarDuration array and its complement must be a
## double array.
##
## @var{C} is a calendarDuration array of the same size as the input
## arguments after the necessary (if required) expansion. @var{A} and
## @var{B} must be size compatible, which translates to they can be the same
## size, one can be scalar, or for every dimension, their dimension sizes
## must be equal or one of them must be 1.
##
## @end deftypefn
function out = mtimes (A, B)
if (isa (A, 'calendarDuration') && isnumeric (B))
out = A;
tmp = double (B);
out.Months = A.Months * tmp;
out.Days = A.Days * tmp;
out.Time = A.Time * tmp;
elseif (isnumeric (A) && isa (B, 'calendarDuration'))
out = B;
tmp = double (A);
out.Months = tmp * B.Months;
out.Days = tmp * B.Days;
out.Time = tmp * B.Time;
else
error (strcat ("calendarDuration: matrix multiplication is", ...
" not defined between '%s' and '%s' arrays."), ...
class (A), class (B));
endif
endfunction
endmethods
################################################################################
## ** Equality and Filter Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'eq' 'ne' 'unique' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} eq (@var{A}, @var{B})
##
## Test for equality between calendarDuration arrays.
##
## @code{@var{TF} = eq (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} == @var{B}} and returns a logical array with
## elements set to @qcode{true} where calendarDuration arrays @var{A} and
## @var{B} are equal, otherwise set to @qcode{false}. Missing values are
## not equal to each other. Hence, any @code{NaN} values in @var{A} or
## @var{B} result to @qcode{false} elements in @var{TF}.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of the
## output @var{TF} is the same as the size of input arrays after their
## expansion according to the broadcasting rules.
##
## @end deftypefn
function TF = eq (A, B)
if (! (iscalendarduration (A) && iscalendarduration (B)))
error (strcat ("calendarDuration.eq: equality is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
TF = A.Months == B.Months & A.Days == B.Days & A.Time == B.Time;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{TF} =} ne (@var{A}, @var{B})
##
## Test for inequality between calendarDuration arrays.
##
## @code{@var{TF} = ne (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} != @var{B}} and returns a logical array with
## elements set to @qcode{true} where calendarDuration arrays @var{A} and
## @var{B} are not equal, otherwise set to @qcode{false}. Missing values
## are not equal to each other. Hence, any @code{NaN} values in @var{A} or
## @var{B} result to @qcode{true} elements in @var{TF}.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of the
## output @var{TF} is the same as the size of input arrays after their
## expansion according to the broadcasting rules.
##
## @end deftypefn
function TF = ne (A, B)
if (! (iscalendarduration (A) && iscalendarduration (B)))
error (strcat ("calendarDuration.ne: inequality is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
TF = A.Months != B.Months | A.Days != B.Days | A.Time != B.Time;
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} unique (@var{A})
## @deftypefnx {calendarDuration} {@var{B} =} unique (@var{A}, @var{setOrder})
## @deftypefnx {calendarDuration} {@var{B} =} unique (@var{A}, @var{occurrence})
## @deftypefnx {calendarDuration} {@var{B} =} unique (@var{A}, @var{setOrder}, @var{occurrence})
## @deftypefnx {calendarDuration} {@var{B} =} unique (@var{A}, @var{occurrence}, @var{setOrder})
## @deftypefnx {calendarDuration} {@var{B} =} unique (@var{A}, @dots{}, @qcode{'rows'})
## @deftypefnx {calendarDuration} {[@var{B}, @var{ixA}, @var{ixB}] =} unique (@dots{})
##
## Unique values in a calendarDuration array.
##
## @code{@var{B} = unique (@var{A})} returns the unique values of the
## calendarDuration array @var{A} in sorted order.
##
## @code{@var{B} = unique (@var{A}, @var{setOrder})} returns the unique
## values of the calendarDuration array @var{A} in an order as specified by
## @var{setOrder}, which can be either of the following values:
##
## @itemize
## @item @qcode{'sorted'} (default) returns the unique values sorted in
## ascending order.
## @item @qcode{'stable'} returns the unique values according to their order
## of occurrence.
## @end itemize
##
## @code{@var{B} = unique (@var{A}, @var{occurrence})} returns the unique
## values of the calendarDuration array @var{tblA} according to their order
## of occurrence. @var{occurrence} can be either of the following values:
##
## @itemize
## @item @qcode{'first'} (default) returns the first occurrence of each
## unique value, i.e. the lowest possible indices are returned.
## @item @qcode{'last'} returns the last occurrence of each unique value,
## i.e. the highest possible indices are returned.
## @end itemize
##
## You can specify @var{setOrder} and @var{occurrence} arguments together.
##
## @code{@var{B} = unique (@var{A}, @dots{}, @qcode{'rows'})} returns the
## unique rows of @var{A} by treating each row as a single entity. The
## @qcode{'rows'} option can be used alone or in any combination with the
## @var{setOrder} and @var{occurrence} arguments. @qcode{'rows'} can be
## placed at any position in the function's argument list after the input
## array @var{A}. However, this syntax is only valid for 2-dimensional
## calendarDuration arrays.
##
## @code{[@var{tblB}, @var{ixA}, @var{ixB}] = unique (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} using any of the previous syntaxes.
## @var{ixA} and @var{ixB} map the arrays @var{A} and @var{B} to one another
## such that @qcode{@var{B} = @var{A}(@var{ixA})} and
## @qcode{@var{A} = @var{B}(@var{ixB})}. When the @qcode{'rows'} optional
## argument is specified, then @qcode{@var{B} = @var{A}(@var{ixA},:)} and
## @qcode{@var{tblA} = @var{tblB}(@var{ixB},:)}.
##
## @end deftypefn
function [B, ixA, ixB] = unique (A, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("calendarDuration.unique: 'legacy' option is not supported.");
endif
## Handle each property array separately
[~, ~, Midx] = __unique__ (A.Months, varargin{:});
[~, ~, Didx] = __unique__ (A.Days, varargin{:});
[~, ~, Tidx] = unique (A.Time, varargin{:});
## Use indices to find unique calendarDuration values
if (any (strcmp ('rows', varargin)))
[~, ixA, ixB] = __unique__ ([Midx, Didx, Tidx], varargin{:});
if (any (strcmp ('last', varargin)))
[~, ixA, ~] = __unique__ (ixB, 'last');
endif
B = subset (A, ixA, ':');
else
[~, ixA, ixB] = __unique__ ([Midx, Didx, Tidx], 'rows', varargin{:});
if (any (strcmp ('last', varargin)))
[~, ixA, ~] = __unique__ (ixB, 'last');
endif
B = subset (A, ixA);
endif
endfunction
endmethods
################################################################################
## ** Array Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'cat' 'horzcat' 'vertcat' 'repmat' ##
## 'repelem' 'repelems' 'reshape' 'circshift' ##
## 'permute' 'ipermute' 'transpose' 'ctranspose' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} cat (@var{dim}, @var{A}, @var{B}, @dots{})
##
## Concatenate calendarDuration arrays.
##
## @code{@var{C} = cat (@var{dim}, @var{A}, @var{B}, @dots{})} concatenates
## calendarDuration arrays @var{A}, @var{B}, @dots{} along dimension
## @var{dim}. All input arrays must have the same size except along the
## operating dimension @var{dim}. Any of the input arrays may also be
## string arrays or cell arrays of character vectors of compatible size.
## Additionally, an input can be a numeric matrix, which when parsed to the
## constructor will return a calendarDuration array of compatible size.
##
## @end deftypefn
function out = cat (dim, varargin)
args = varargin;
[args{:}] = promote (varargin{:});
out = args{1};
fieldArgs = cellfun (@(obj) obj.Months, args, 'UniformOutput', false);
out.Months = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Days, args, 'UniformOutput', false);
out.Days = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Time, args, 'UniformOutput', false);
out.Time = cat (dim, fieldArgs{:});
out = broadcastProperties (out);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} horzcat (@var{A}, @var{B}, @dots{})
##
## Horizontal concatenation of calendarDuration arrays.
##
## @code{@var{C} = horzcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}, @var{B}, @dots{}]} and horizontally
## concatenates the calendarDuration arrays @var{A}, @var{B}, @dots{}. All
## input arrays must have the same size except along the second dimension.
## Any of the input arrays may also be string arrays or cell arrays of
## character vectors of compatible size. Additionally, an input can be a
## numeric matrix, which when parsed to the constructor will return a
## calendarDuration array of compatible size.
##
## @end deftypefn
function out = horzcat (varargin)
out = cat (2, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{C} =} vertcat (@var{A}, @var{B}, @dots{})
##
## Vertical concatenation of calendarDuration arrays.
##
## @code{@var{C} = vertcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}; @var{B}; @dots{}]} and vertically
## concatenates the calendarDuration arrays @var{A}, @var{B}, @dots{}. All
## input arrays must have the same size except along the first dimension.
## Any of the input arrays may also be string arrays or cell arrays of
## character vectors of compatible size. Additionally, an input can be a
## numeric matrix, which when parsed to the constructor will return a
## calendarDuration array of compatible size.
##
## @end deftypefn
function out = vertcat (varargin)
out = cat (1, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} repmat (@var{A}, @var{n})
## @deftypefnx {calendarDuration} {@var{B} =} repmat (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {calendarDuration} {@var{B} =} repmat (@var{A}, @var{dimvec})
##
## Repeat copies of a calendarDuration array.
##
## @code{@var{B} = repmat (@var{A}, @var{n})} returns a calendarDuration
## array @var{B} containing @var{n} copies of the input calendarDuration
## array @var{A} along every dimension of @var{A}.
##
## @code{@var{B} = repmat (@var{A}, @var{d1}, @dots{}, @var{dN})} returns an
## array @var{B} containing copies of @var{A} along the dimensions specified
## by the list of scalar integer values @var{d1}, @dots{}, @var{dN}, which
## specify how many copies of @var{A} are made in each dimension.
##
## @code{@var{B} = repmat (@var{A}, @var{dimvec})} is equivalent to the
## previous syntax with @code{@var{dimvec} = [@var{d1}, @dots{}, @var{dN}]}.
##
## @end deftypefn
function this = repmat (this, varargin)
this.Months = repmat (this.Months, varargin{:});
this.Days = repmat (this.Days, varargin{:});
this.Time = repmat (this.Time, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} repelem (@var{A}, @var{n})
## @deftypefnx {calendarDuration} {@var{B} =} repelem (@var{A}, @var{d1}, @dots{}, @var{dN})
##
## Repeat copies of calendarDuration array elements.
##
## @code{@var{B} = repelem (@var{A}, @var{n})} returns a calendarDuration
## vector @var{B} containing repeated elements of the input @var{A}, which
## must be a calendarDuration vector. If @var{n} is a scalar, each element
## of @var{A} is repeated @var{n} times along the non-singleton dimension of
## @var{A}. If @var{n} is a vector, it must have the same elements as
## @var{A}, in which case it specifies the number of times to repeat each
## corresponding element of @var{A}.
##
## @code{@var{B} = repelem (@var{A}, @var{d1}, @dots{}, @var{dN})} returns
## an array @var{B} with each element of @var{A} repeated according to the
## the list of input arguments @code{@var{d1}, @dots{}, @var{dN}} each
## corresponding to a different dimension @code{1:ndims (@var{A})} of the
## input array @var{A}. @var{d1}, @dots{}, @var{dN} must be either scalars
## or vectors with the same length as the corresponding dimension of
## @var{A} containing non-negative integer values specifying the number of
## repetitions of each element along the corresponding dimension.
##
## @end deftypefn
function this = repelem (this, varargin)
this.Months = repelem (this.Months, varargin{:});
this.Days = repelem (this.Days, varargin{:});
this.Time = repelem (this.Time, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} repelems (@var{A}, @var{R})
##
## Construct a vector of repeated elements from a calendarDuration array.
##
## @code{@var{B} = repelems (@var{A}, @var{R})} returns a calendarDuration
## vector @var{B} containing repeated elements of the input @var{A}, which
## must be a calendarDuration vector. @var{R} must be a @math{2*N} matrix
## of integers. Entries in the first row of @var{R} correspond to the
## linear indexing of the elements in @var{A} to be repeated. The
## corresponding entries in the second row of @var{R} specify the repeat
## count of each element.
##
## @end deftypefn
function this = repelems (this, R)
this.Months = repelems (this.Months, R);
this.Days = repelems (this.Days, R);
this.Time = repelems (this.Time, R);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} reshape (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {calendarDuration} {@var{B} =} reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})
## @deftypefnx {calendarDuration} {@var{B} =} reshape (@var{A}, @var{dimvec})
##
## Reshape calendarDuration array.
##
## @code{@var{B} = reshape (@var{A}, @var{d1}, @dots{}, @var{dN})} returns a
## calendarDuration array @var{B} with specified dimensions @var{d1},
## @dots{}, @var{dN}, whose elements are taken columnwise from the
## calendarDuration array @var{A}. The product of @var{d1}, @dots{},
## @var{dN} must equal the total number of elements in @var{A}.
##
## @code{@var{B} = reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})} returns
## a calendarDuration array @var{B} with one dimension unspecified which is
## calculated automatically so that the product of dimensions in @var{B}
## matches the total elements in @var{A}, which must be divisible the
## product of specified dimensions. An empty matrix @qcode{([])} is used to
## flag the unspecified dimension.
##
## @end deftypefn
function this = reshape (this, varargin)
this.Months = reshape (this.Months, varargin{:});
this.Days = reshape (this.Days, varargin{:});
this.Time = reshape (this.Time, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} circshift (@var{A}, @var{n})
## @deftypefnx {calendarDuration} {@var{B} =} circshift (@var{A}, @var{n}, @var{dim})
##
## Circularly shift the elements in a calendarDuration array.
##
## @code{@var{B} = circshift (@var{A}, @var{n})} circularly shifts the
## elements of the calendarDuration array @var{A} according to @var{n}. If
## @var{n} is a nonzero integer scalar, then the elements of @var{A} are
## shifted by @var{n} elements along the first non-singleton dimension of
## @var{A}. If @var{n} is a vector, it must not be longer that the number
## of dimensions of @var{A} with each value of @var{n} corresponding to a
## dimension in @var{A}. The sign of the value(s) in @var{n} specify the
## direction in the elements of @var{A} are shifted.
##
## @code{@var{B} = circshift (@var{A}, @var{n}, @var{dim})} circularly
## shifts the elements of the calendarDuration array @var{A} along the
## dimension specified by @var{dim}. In this case, @var{n} must be a scalar
## integer value.
##
## @end deftypefn
function this = circshift (this, varargin)
this.Months = circshift (this.Months, varargin{:});
this.Days = circshift (this.Days, varargin{:});
this.Time = circshift (this.Time, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} permute (@var{A}, @var{dims})
##
## Generalized transpose for a calendarDuration N-D array.
##
## @code{@var{B} = permute (@var{A}, @var{dims})} returns the generalized
## transpose of the calendarDuration array @var{A} by rearranging its
## dimensions according to the permutation vector specified in @var{dims}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{A})} of the
## input array @var{A}, in any order, but only once. The @var{N}th
## dimension of @var{A} gets remapped to the dimension in @var{B} specified
## by @code{@var{dims}(@var{N})}.
##
## @end deftypefn
function this = permute (this, order)
this.Months = permute (this.Months, order);
this.Days = permute (this.Days, order);
this.Time = permute (this.Time, order);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{A} =} ipermute (@var{B}, @var{dims})
##
## Inverse of the generalized transpose for a calendarDuration N-D array.
##
## @code{@var{A} = ipermute (@var{B}, @var{dims})} returns the inverse of
## the generalized transpose performed by the @code{permute} function. The
## expression @code{ipermute (permute (@var{A}, @var{dims}), @var{dims})}
## returns the original array @var{A}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{B})} of the
## input array @var{B}, in any order, but only once. The dimension of
## @var{B} specified in @code{@var{dims}(@var{N})} gets remapped to the
## @var{N}th dimension of @var{A}.
##
## @end deftypefn
function this = ipermute (this, order)
this.Months = ipermute (this.Months, order);
this.Days = ipermute (this.Days, order);
this.Time = ipermute (this.Time, order);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} transpose (@var{A})
##
## Transpose a calendarDuration matrix.
##
## @code{@var{B} = transpose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}.'} and returns the transpose of the
## calendarDuration matrix @var{A}.
##
## @end deftypefn
function this = transpose (this)
this.Months = transpose (this.Months);
this.Days = transpose (this.Days);
this.Time = transpose (this.Time);
endfunction
## -*- texinfo -*-
## @deftypefn {calendarDuration} {@var{B} =} ctranspose (@var{A})
##
## Transpose a calendarDuration matrix.
##
## @code{@var{B} = ctranspose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}'} and returns the transpose of the
## calendarDuration matrix @var{A}. For calendarDuration arrays,
## @code{ctranspose} is identical to @code{transpose}.
##
## @end deftypefn
function this = ctranspose (this)
this.Months = ctranspose (this.Months);
this.Days = ctranspose (this.Days);
this.Time = ctranspose (this.Time);
endfunction
endmethods
################################################################################
## ** Reference and Assignment Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'end' 'subsref' 'subsasgn' ##
## ##
################################################################################
methods (Hidden)
## Overloaded end keyword
function last_index = end (this, end_dim, ndim_obj)
lastdim = ndims (this);
if (end_dim == ndim_obj && ndim_obj == 1)
last_index = prod (size (this));
elseif (end_dim == ndim_obj && end_dim < lastdim)
last_index = prod (size (this)(end_dim:lastdim));
else
last_index = size (this, end_dim);
endif
endfunction
## Class specific subscripted reference
function varargout = subsref (this, s)
chain_s = s(2:end);
s = s(1);
switch (s.type)
case '()'
out = this;
out.Months = this.Months(s.subs{:});
out.Days = this.Days(s.subs{:});
out.Time = this.Time(s.subs{:});
case '{}'
error (strcat ("calendarDuration.subsref: '{}' invalid indexing", ...
" for referencing values. Use '()' instead."));
case '.'
if (! ischar (s.subs))
error (strcat ("calendarDuration.subsref: '.' index", ...
" argument must be a character vector."));
endif
switch (s.subs)
case 'proxyArray' # used by 'table' class
out = proxyArray (this);
case 'Format'
out = this.Format;
otherwise
error (strcat ("calendarDuration.subsref: unrecognized", ...
" property: '%s'"), s.subs);
endswitch
endswitch
## Chained references
if (! isempty (chain_s))
out = subsref (out, chain_s);
endif
varargout{1} = out;
endfunction
## Class specific subscripted assignment
function this = subsasgn (this, s, val)
if (numel (s) > 1)
error ("calendarDuration.subsasgn: chained subscripts not allowed.");
endif
switch s.type
case '()'
if (isempty (val))
this.Months(s.subs{:}) = [];
this.Days(s.subs{:}) = [];
this.Time(s.subs{:}) = [];
return;
elseif (isnumeric (val))
tmp = zeros (size (val));
this.Months(s.subs{:}) = tmp;
this.Days(s.subs{:}) = tmp;
this.Time(s.subs{:}) = duration (24 * double (val), 0, 0);
this = broadcastProperties (this);
elseif (isa (val, "calendarDuration"))
this.Months(s.subs{:}) = val.Months;
this.Days(s.subs{:}) = val.Days;
this.Time(s.subs{:}) = val.Time;
this = broadcastProperties (this);
elseif (isa (val, "duration"))
this.Months(s.subs{:}) = 0;
this.Days(s.subs{:}) = 0;
this.Time(s.subs{:}) = val;
this = broadcastProperties (this);
else
error (strcat ("calendarDuration.subsasgn: assignment value", ...
" must be calendarDuration or duration array", ...
" or a numeric array representing 24-hour days."));
endif
case '{}'
error (strcat ("calendarDuration.subsasgn: '{}' invalid indexing", ...
" for assigning values. Use '()' instead."));
case '.'
if (! ischar (s.subs))
error (strcat ("calendarDuration.subsasgn: '.' index", ...
" argument must be a character vector."));
endif
switch (s.subs)
case 'Format'
errmsg = checkFormatString (val);
if (! isempty (errmsg))
error ("calendarDuration.subsasgn: 'Format' %s", errmsg);
endif
this.Format = val;
otherwise
error (strcat ("calendarDuration.subsasgn: unrecognized", ...
" property: '%s'"), s.subs);
endswitch
endswitch
endfunction
endmethods
methods (Access = private)
## Return a subset of the array
function this = subset (this, varargin)
this = this;
this.Months = this.Months(varargin{:});
this.Days = this.Days(varargin{:});
this.Time = this.Time(varargin{:});
endfunction
## Broadcast properties
function this = broadcastProperties (this)
## Handle NaNs and Infs first
is_nan = isnan (this.Months) | isnan (this.Days) | isnan (this.Time);
isPinf = Inf == this.Months | Inf == this.Days | Inf == this.Time;
isNinf = -Inf == this.Months | -Inf == this.Days | -Inf == this.Time;
if (any (is_nan, 'all') || any (isPinf & isNinf, 'all'))
is_nan = is_nan | (isPinf & isNinf);
isPinf = isPinf & ! is_nan;
isNinf = isNinf & ! is_nan;
endif
## Broadcast NaNs
this.Months(is_nan) = NaN;
this.Days(is_nan) = NaN;
this.Time(is_nan) = duration ([NaN, NaN, NaN]);
## Broadcast Infs
if (any (isPinf, 'all'))
this.Months(isPinf) = Inf;
this.Days(isPinf) = Inf;
this.Time(isPinf) = duration ([Inf, Inf, Inf]);
endif
if (any (isNinf, 'all'))
this.Months(isNinf) = -Inf;
this.Days(isNinf) = -Inf;
this.Time(isNinf) = duration ([-Inf, -Inf, -Inf]);
endif
endfunction
## Promote numeric arrays to calendarDuration objects
function varargout = promote (varargin)
for i = 1:numel (varargin)
if (isa (varargin{i}, "calendarDuration"))
varargout{i} = varargin{i};
elseif (isa (varargin{i}, "duration"))
varargout{i} = calendarDuration (0, 0, 0, varargin{i});
elseif (isnumeric (varargin{i}))
if (isempty (varargin{i}))
varargout{i} = calendarDuration ([], [], []);
else
varargout{i} = calendarDuration (0, 0, 0, 24 * varargin{i}, 0, 0);
endif
else
error ("calendarDuration: invalid input to constructor.");
endif
endfor
endfunction
## Create a proxy array for sorting and set operations in tables
function out = proxyArray (this)
## Handle shape (for multicolumn calendarDuration matrix)
[rows, cols] = size (this);
if (cols > 1)
out = [];
for i = 1:cols
dt = hours (this.Time(:,i));
SC = [this.Months(:,i), this.Days(:,i), dt];
out = [out, SC];
endfor
else
dt = hours (this.Time);
out = [this.Months, this.Days, dt];
endif
endfunction
endmethods
endclassdef
## Check 'Format' string
function errmsg = checkFormatString (Format)
## Check for character vector
if (! (ischar (Format) && isvector (Format)))
errmsg = "must be a character vector.";
return;
endif
errmsg = '';
sf = @(x) strfind (Format, x);
sp = cellfun (sf, {'y','q','m','w','d','t'}, 'UniformOutput', false);
## Check for duplicate characters
if (any (cellfun (@(x) numel (x) > 1, sp)))
errmsg = "contains duplicate characters.";
## Check for 'm', 'd', and 't' being present
elseif (any (cellfun (@isempty, sp([3,5,6]))))
errmsg = "must contain 'm', 'd', and 't'.";
## Check order
elseif (any (diff (cell2mat (sp)) < 1))
errmsg = "has invalid order of characters.";
endif
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/calmonths.m 0000664 0000000 0000000 00000005056 15227665741 0021206 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{calD} =} calmonths (@var{X})
##
## Calendar duration in months.
##
## @code{@var{calD} = calmonths (@var{X})} returns a @qcode{calendarDuration}
## array representing calendar months equivalent to the values in @var{X}, which
## must be a numeric array of integer values.
##
## @code{calmonths} is also available as a method for @qcode{calendarDuration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{calendarDuration, calyears, calquarters, calweeks, caldays,
## calendarDuration.calmonths}
## @end deftypefn
function out = calmonths (x)
## Check input
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("calmonths: input array must be numeric.");
elseif (! isreal (x))
error ("calmonths: input array must be real.");
endif
xx = x;
xx(isnan (x)) = 0;
if (any (fix (xx(:)) != xx(:)))
error ("calmonths: input array must contain only integer values.");
endif
out = calendarDuration (0, double (x), 0);
endfunction
%!demo
%! ## `calmonths` builds a calendar duration of whole months. Twelve or more
%! ## months normalise into years on display.
%!
%! calmonths (5)
%! calmonths (14)
%!test
%! X = magic (3);
%! D = calmonths (X);
%! assert_equal (size (D), size (X));
%!test
%! D = calmonths ([1, 2, 3]);
%! assert_equal (calmonths (D), [1, 2, 3]);
%!test
%! D = calmonths ([1, 2, NaN, 4]);
%! assert_equal (calmonths (D), [1, 2, NaN, 4]);
%!test
%! D = calmonths (int16 (1));
%! assert_equal (calmonths (D), 1);
%!test
%! D = calmonths ();
%! assert_equal (calmonths (D), 1);
%!error calmonths ("asd");
%!error calmonths (1+i);
%!error ...
%! calmonths (1.2);
pr0m1th3as-datatypes-9c9a8d3/inst/calquarters.m 0000664 0000000 0000000 00000005260 15227665741 0021541 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{calD} =} calquarters (@var{X})
##
## Calendar duration in quarters.
##
## @code{@var{calD} = calquarters (@var{X})} returns a @qcode{calendarDuration}
## array representing calendar quarters equivalent to the values in @var{X},
## which must be a numeric array of integer values.
##
## @code{calquarters} is also available as a method for @qcode{calendarDuration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{calendarDuration, calyears, calmonths, calweeks, caldays,
## calendarDuration.calquarters}
## @end deftypefn
function out = calquarters (x)
## Check input
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("calquarters: input array must be numeric.");
elseif (! isreal (x))
error ("calquarters: input array must be real.");
endif
xx = x;
xx(isnan (x)) = 0;
if (any (fix (xx(:)) != xx(:)))
error ("calquarters: input array must contain only integer values.");
endif
out = calendarDuration (0, double (x) * 3, 0, 'Format', 'qmwdt');
endfunction
%!demo
%! ## `calquarters` builds a calendar duration of whole quarters (each quarter is
%! ## three months).
%!
%! calquarters (3)
%!
%! ## Quarters combine with the other component builders.
%! calquarters (2) + calmonths (1)
%!test
%! X = magic (3);
%! D = calquarters (X);
%! assert_equal (size (D), size (X));
%!test
%! D = calquarters ([1, 2, 3]);
%! assert_equal (calquarters (D), [1, 2, 3]);
%!test
%! D = calquarters ([1, 2, NaN, 4]);
%! assert_equal (calquarters (D), [1, 2, NaN, 4]);
%!test
%! D = calquarters (int16 (1));
%! assert_equal (calquarters (D), 1);
%!test
%! D = calquarters ();
%! assert_equal (calquarters (D), 1);
%!error calquarters ("asd");
%!error calquarters (1+i);
%!error ...
%! calquarters (1.2);
pr0m1th3as-datatypes-9c9a8d3/inst/calweeks.m 0000664 0000000 0000000 00000005106 15227665741 0021010 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{calD} =} calweeks (@var{X})
##
## Calendar duration in weeks.
##
## @code{@var{calD} = calweeks (@var{X})} returns a @qcode{calendarDuration}
## array representing calendar weeks equivalent to the values in @var{X}, which
## must be a numeric array of integer values.
##
## @code{calweeks} is also available as a method for @qcode{calendarDuration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{calendarDuration, calyears, calquarters, calmonths, caldays,
## calendarDuration.calweeks}
## @end deftypefn
function out = calweeks (x)
## Check input
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("calweeks: input array must be numeric.");
elseif (! isreal (x))
error ("calweeks: input array must be real.");
endif
xx = x;
xx(isnan (x)) = 0;
if (any (fix (xx(:)) != xx(:)))
error ("calweeks: input array must contain only integer values.");
endif
out = calendarDuration (0, 0, double (x) * 7, 'Format', 'ymwdt');
endfunction
%!demo
%! ## `calweeks` builds a calendar duration of whole weeks (each week is 7 days).
%!
%! calweeks (3)
%!
%! ## Combine the component builders by adding them.
%! calweeks (2) + caldays (3)
%!test
%! X = magic (3);
%! D = calweeks (X);
%! assert_equal (size (D), size (X));
%!test
%! D = calweeks ([1, 2, 3]);
%! assert_equal (calweeks (D), [1, 2, 3]);
%!test
%! D = calweeks ([1, 2, NaN, 4]);
%! assert_equal (calweeks (D), [1, 2, NaN, 4]);
%!test
%! D = calweeks (int16 (1));
%! assert_equal (calweeks (D), 1);
%!test
%! D = calweeks ();
%! assert_equal (calweeks (D), 1);
%!error calweeks ("asd");
%!error calweeks (1+i);
%!error ...
%! calweeks (1.2);
pr0m1th3as-datatypes-9c9a8d3/inst/calyears.m 0000664 0000000 0000000 00000005066 15227665741 0021022 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{calD} =} calyears (@var{X})
##
## Calendar duration in years.
##
## @code{@var{calD} = calyears (@var{X})} returns a @qcode{calendarDuration}
## array representing calendar years equivalent to the values in @var{X}, which
## must be a numeric array of integer values.
##
## @code{calyears} is also available as a method for @qcode{calendarDuration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{calendarDuration, calquarters, calmonths, calweeks, caldays,
## calendarDuration.calyears}
## @end deftypefn
function out = calyears (x)
## Check input
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("calyears: input array must be numeric.");
elseif (! isreal (x))
error ("calyears: input array must be real.");
endif
xx = x;
xx(isnan (x)) = 0;
if (any (fix (xx(:)) != xx(:)))
error ("calyears: input array must contain only integer values.");
endif
out = calendarDuration (double (x), 0, 0);
endfunction
%!demo
%! ## `calyears` builds a calendar duration of whole years. Add the component
%! ## builders together to assemble a full span.
%!
%! calyears (2)
%! calyears (1) + calmonths (6) + caldays (15)
%!test
%! X = magic (3);
%! D = calyears (X);
%! assert_equal (size (D), size (X));
%!test
%! D = calyears ([1, 2, 3]);
%! assert_equal (calyears (D), [1, 2, 3]);
%!test
%! D = calyears ([1, 2, NaN, 4]);
%! assert_equal (calyears (D), [1, 2, NaN, 4]);
%!test
%! D = calyears (int16 (1));
%! assert_equal (calyears (D), 1);
%!test
%! D = calyears ();
%! assert_equal (calyears (D), 1);
%!error calyears ("asd");
%!error calyears (1+i);
%!error ...
%! calyears (1.2);
pr0m1th3as-datatypes-9c9a8d3/inst/categorical.m 0000664 0000000 0000000 00000623001 15227665741 0021467 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
classdef categorical
## -*- texinfo -*-
## @deftp {datatypes} categorical
##
## Array representing categorical data.
##
## A @code{categorical} array represents an array of values that correspond
## to a finite set of discrete categories, which can be either ordinal (having
## a mathematical ordering) or nominal. It is an efficient way to define
## groups of rows in a table or to other types of variables.
##
## Each @code{categorical} array stores the list of categories as a cell array
## of character vectors and a numeric array of @qcode{uint16} type as indices
## to the categories. The categorical array may also store elements of
## undefined categorical values, which represent the absence of a given
## category and correspond to the @qcode{NaN} value for numeric arrays or in
## general to the missing value for other data types.
##
## @code{categorical} arrays do not have any public properties, which can be
## indexed by using dot notation similarly to structures. However, there are
## several methods which can be used to modify their categories once they are
## constructed.
##
## @end deftp
properties (SetAccess = private, Hidden)
## Category Names
cats = {}
## Indices to categories
code = uint16 ([])
## elements
isMissing = logical ([])
## Flag for ordinal categories
isOrdinal = false
## Flag for protecting category list
isProtected = false
endproperties
methods (Hidden)
## Custom display
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, 'categorical', in_name);
endfunction
## Custom display
function disp (this)
__disp__ (this, 'categorical');
endfunction
endmethods
################################################################################
## ** Create and convert 'categorical' type ** ##
################################################################################
## Available Methods ##
## ##
## 'categorical' 'dispstrings' 'cellstr' 'char' ##
## 'double' 'single' 'int64' 'int32' ##
## 'int16' 'int8' 'uint64' 'uint32' ##
## 'uint16' 'uint8' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} categorical (@var{A})
## @deftypefnx {categorical} {@var{C} =} categorical (@var{A}, @var{valueset})
## @deftypefnx {categorical} {@var{C} =} categorical (@var{A}, @var{valueset}, @var{catnames})
## @deftypefnx {categorical} {@var{C} =} categorical (@dots{}, @var{Name}, @var{Value})
##
## Create a new array of categorical values.
##
## @code{@var{C} = categorical (@var{A})} creates a categorical array
## @var{C} from the input array @var{A}, which can be numeric, logical,
## datetime, duration, string, or cell array of character vectors. Input
## @var{A} can also be another categorical array. The categories in @var{C}
## the sorted unique values from the input array @var{A}. When the input
## array is string or cell array of character vectors, any leading or
## trailing white spaces are removed. Missing values in the input array
## correspond to @qcode{} elements in the created categorical
## array. By default, there is no category for undefined values in the
## output array.
##
## @code{@var{C} = categorical (@var{A}, @var{valueset})} creates a
## categorical array from input @var{A} with the categories specified in
## @var{valueset}, which must be a vector of unique values. The data type
## of input array @var{A} and @var{valueset} must be the same, unless they
## are string or cell arrays of character vectors, in which case they can be
## used interchangeably. Similarly to input array @var{A} any leading or
## trailing white spaces are removed, if @var{valueset} is a string or cell
## array of character vectors.
##
## @code{@var{C} = categorical (@var{A}, @var{valueset}, @var{catnames})}
## creates a categorical array from input @var{A} with the categories
## specified in @var{valueset} and named after the corresponding values in
## @var{catnames}, which must be specified either as a string array or a
## cell array of character vectors. If omitted, @code{categorical} uses
## the cellstring representation of @var{valueset} to name the specified
## category names. @var{catnames} must not contain any missing values, it
## may have duplicate names, and it must have the same number of elements as
## @var{valueset}.
##
## @code{@var{C} = categorical (@dots{}, @var{Name}, @var{Value})} further
## specifies additional parameters for creating categorical array @var{C}.
##
## @itemize
## @item @qcode{"Ordinal"} must be a logical scalar specifying that the
## categories in @var{C} have a numeric ordering relationship. By default,
## it is @qcode{false} and @code{categorical} creates a non-ordinal array.
## The elements of unordered categorical arrays can only be compared for
## equality. Any other relational operator cannot be used. Setting
## @qcode{"Ordinal"} to @qcode{true} results in a categorical array with
## mathematically ordered categories. The ordering goes from smallest to
## largest according to the order in @var{valueset} or the order of
## appearance in input array @var{A}, when @var{valueset} is not specified,
## in which case the unique values in @var{A} are not sorted in order to set
## the categories. Ordinal categorical arrays allow for relational
## operators such as @qcode{>=, >, <=, <}, as well as statistical operations
## such as @code{min}, @code{max}, and @code{median}.
##
## @item @qcode{"Protected"} must be a logical scalar specifying that the
## categories in @var{C} are protected. By default, it is @qcode{false} for
## unordered categorical arrays and it is always @qcode{true} for ordinal
## categorical arrays. Setting @qcode{"Protected"} to @qcode{true} prevents
## from assigning new values that do not correspond to existing categories.
## When @qcode{false}, assigning new values to the array automatically
## updates the categories. Hence, categorical arrays with different sets of
## categories can be combined/merged into a new array with set operations.
## @end itemize
##
## @seealso{categories, discretize, iscategorical}
## @end deftypefn
function this = categorical (x, varargin)
## Return an empty categorical object
if (nargin == 0)
return;
endif
## Parse optional Name-Value paired arguments
optNames = {'Ordinal', 'Protected'};
dfValues = {false, false};
[Ordinal, Protected, args] = parsePairedArguments (optNames, dfValues, ...
varargin(:));
## Check optional Name-Value paired arguments
if (! ismember (Ordinal, [0, 1]))
error (strcat ("categorical: 'Ordinal' variable indicator", ...
" must be either false (0) or true (1)."));
endif
if (! ismember (Protected, [0, 1]))
error (strcat ("categorical: 'Protected' categories indicator", ...
" must be either false (0) or true (1)."));
endif
if (Ordinal)
this.isOrdinal = true;
this.isProtected = true;
elseif (Protected)
this.isProtected = true;
endif
## Function handle for identifying missing text
fmt = @(x) isempty (strtrim (x));
## Handle categorical input first
if (isa (x, 'categorical'))
this.cats = x.cats;
this.code = x.code;
this.isMissing = x.isMissing;
## Set new categories if valueset argument is provided
if (numel (args) > 0)
## valueset must be a same type as data input (categorical)
catvset = args{1};
if (isa (catvset, 'categorical'))
isnanvset = catvset.isMissing;
codevset = catvset.code;
if (sum (isnanvset) > 1)
error ("categorical: VALUESET contains multiple missing values.");
elseif (numel (unique (codevset)) != numel (codevset))
error ("categorical: VALUESET contains non-unique values.");
endif
if (any (isnanvset))
if (numel (args) == 1)
error (strcat ("categorical: VALUESET with missing value", ...
" requires CATNAMES."));
endif
## Keep index of missing values in x
isnanx = this.isMissing;
## Get CATNAMES
catnames = args{2};
if (! (iscellstr (catnames) || isa (catnames, 'string')))
error ("categorical: invalid type of CATNAMES.");
endif
catnames = cellstr (catnames);
## codevset must include 0 since there is an undefined element
if (numel (codevset) != numel (catnames))
error (strcat ("categorical: CATNAMES and VALUESET", ...
" lengths do not match."));
endif
if (any (cellfun (fmt, catnames)))
error (strcat ("categorical: CATNAMES contain empty or", ...
" missing strings."));
endif
## Separate missing from nonmissing catnames
valueset = catvset.cats(codevset(! isnanvset));
## Set nonmissing values
this = setcats (this, valueset);
## Find code value for missing catname, add 1 to all code values
## equal to or greater than the missing code value, and convert
## all initial 0 code values to the new missing catname value.
nanvalue = find (isnanvset);
this.code(this.code >= nanvalue) += 1;
this.code(isnanx) = uint16 (nanvalue);
this.isMissing(isnanx) = false;
this.cats = catnames(:);
else
valueset = catvset.cats(codevset);
this = setcats (this, valueset);
## Set new category names if catname argument is provided
if (numel (args) > 1)
catnames = args{2};
if (! (iscellstr (catnames) || isa (catnames, 'string')))
error ("categorical: invalid type of CATNAMES.");
endif
catnames = cellstr (catnames);
if (numel (valueset) != numel (catnames))
error (strcat ("categorical: CATNAMES and VALUESET", ...
" lengths do not match."));
endif
if (any (cellfun (fmt, catnames)))
error (strcat ("categorical: CATNAMES contain empty or", ...
" missing strings."));
endif
this.cats = catnames(:);
endif
endif
## In case of duplicate catnames, regrouping is required
if (numel (args) > 1 && ...
numel (unique (catnames)) != numel (catnames))
## Generate regrouping index to unique categories
index2cat = __grp2idx__ (catnames);
idx = ! this.isMissing;
this.code(idx) = arrayfun (@(x) index2cat(x), this.code(idx));
this.cats = unique (this.cats, 'stable');
endif
else
error ("categorical: incompatible types of VALUESET and X.");
endif
endif
return;
endif
## Handle input arguments
index2cat = [];
isnanvset = false;
## Input Array (x)
if (iscellstr (x))
classx = 'cellstr';
isnanx = cellfun (fmt, x);
elseif (isnumeric (x))
classx = 'numeric';
isnanx = isnan (x);
elseif (isa (x, 'datetime'))
classx = 'datetime';
isnanx = isnat (x);
elseif (isa (x, 'duration'))
classx = 'duration';
isnanx = isnan (x);
elseif (islogical (x))
classx = 'logical';
isnanx = isnan (x);
elseif (isa (x, 'string'))
classx = 'string';
isnanx = cellfun (fmt, cellstr (x));
else
error ("categorical: invalid input type for X.");
endif
## Force isnanx to logical array in case of empty text input
isnanx = logical (isnanx);
## Categories (valueset)
if (numel (args) > 0)
valueset = args{1};
if (iscellstr (valueset))
classv = 'cellstr';
elseif (isnumeric (valueset))
classv = 'numeric';
else
classv = class (valueset);
endif
if (any (strcmp (classx, {'cellstr', 'string'})))
if (! (iscellstr (valueset) || isa (valueset, 'string')))
error ("categorical: incompatible types of VALUESET and X.");
endif
if (iscellstr (valueset))
isnanvset = cellfun (fmt, valueset);
else # string
isnanvset = cellfun (fmt, cellstr (valueset));
endif
elseif (isequal (classx, classv))
if (strcmp (classv, 'datetime'))
isnanvset = isnat (valueset);
else # numeric, duration,
isnanvset = isnan (valueset);
endif
else
error ("categorical: incompatible types of VALUESET and X.");
endif
if (any (isnanvset) && numel (args) == 1)
error ("categorical: VALUESET with missing value requires CATNAMES.");
endif
if (sum (isnanvset) > 1)
error ("categorical: VALUESET contains multiple missing values.");
endif
if (prod (size (unique (valueset))) < prod (size (valueset)))
error ("categorical: VALUESET contains non-unique values.");
endif
## Category names (catnames)
if (numel (args) > 1)
catnames = args{2};
if (! (iscellstr (catnames) || isa (catnames, 'string')))
error ("categorical: invalid type of CATNAMES.");
endif
catnames = cellstr (catnames);
if (prod (size (valueset)) != numel (catnames))
error ("categorical: CATNAMES and VALUESET lengths do not match.");
endif
if (any (cellfun (@(x) isempty (strtrim (x)), catnames)))
error ("categorical: CATNAMES contain empty or missing strings.");
endif
## Create index vector to categories
index2cat = __grp2idx__ (catnames);
else
## Check valueset for missing or empty elements
if (any (strcmp (classv, {'cellstr', 'string'})))
valueset = cellstr (valueset);
catnames = valueset;
elseif (isnumeric (valueset))
catnames = arrayfun (@num2str, valueset, "UniformOutput", false);
elseif (strcmp (classv, 'logical'))
if (all (valueset))
catnames = {'true'};
elseif (! any (valueset))
catnames = {'false'};
else
catnames = {'false'; 'true'};
endif
else # datetime, duration
catnames = dispstrings (valueset);
endif
endif
else
## Resolve valueset and catnames from input array
if (strcmp (classx, 'numeric'))
valueset = unique (x);
valueset = valueset(! isnan (valueset));
catnames = arrayfun (@num2str, valueset, "UniformOutput", false);
elseif (strcmp (classx, 'logical'))
valueset = unique (x);
if (all (valueset))
catnames = {'true'};
elseif (! any (valueset))
catnames = {'false'};
else
catnames = {'false'; 'true'};
endif
elseif (strcmp (classx, 'cellstr'))
valueset = unique (x); # does not remove empty
valueset = valueset(! cellfun (fmt, valueset));
catnames = valueset;
elseif (strcmp (classx, 'string'))
valueset = unique (x); # removes missing, but not empty
valueset = valueset(! cellfun (fmt, cellstr (valueset)));
catnames = cellstr (valueset);
elseif (strcmp (classx, 'datetime'))
valueset = unique (x); # does not remove NaT
valueset = valueset(! isnat (valueset));
catnames = dispstrings (valueset);
elseif (strcmp (classx, 'duration'))
valueset = unique (x); # does not remove NaN
valueset = valueset(! ismissing (valueset));
catnames = dispstrings (valueset);
endif
endif
## Associate input array with valueset
[tf, loc] = ismember (x, valueset);
maxc = intmax ('uint16');
maxl = max (loc(:)) + sum (isnanvset);
if (maxl > maxc)
error (strcat ("categorical: too many categories; categorical", ...
" supports up to %d categories; this input has", ...
" %d."), maxc, maxl);
endif
## If missing value in valueset is associated with a category name
## remove missing values in X from 'tf' and assign the index of the
## valueset that corresponds to the missing value to 'loc'
if (any (isnanvset))
tf = tf | isnanx;
loc(find (isnanx)) = find (isnanvset);
endif
## Reassociate to user defined categories (only when regrouping required)
if (! isempty (index2cat))
if (numel (index2cat) != unique (index2cat) || any (isnanvset))
valueset = 1:prod (size (valueset));
fcn = @ (x) index2cat(find (valueset == x));
loc(tf) = arrayfun (fcn, loc(tf));
endif
endif
## Add constructor properties
this.code = uint16 (loc);
this.isMissing = ! tf;
if (isempty (catnames))
this.cats = {};
else
this.cats = unique (catnames(:), 'stable');
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{cstr} =} dispstrings (@var{C})
##
## Get display formatted strings for each element of a categorical array.
##
## @code{@var{cstr} = dispstrings (@var{C})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## categorical @var{C}.
##
## @end deftypefn
function cstr = dispstrings (this)
cstr = cell (size (this));
ix = this.code(! this.isMissing);
cstr(! this.isMissing) = this.cats(ix);
cstr(this.isMissing) = {''};
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{cstr} =} cellstr (@var{C})
##
## Convert categorical array to a cell array of character vectors.
##
## @code{@var{cstr} = cellstr (@var{C})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## categorical @var{C}.
##
## @end deftypefn
function cstr = cellstr (this)
cstr = dispstrings (this);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{CM} =} char (@var{C})
##
## Convert categorical array to a 2-D character matrix.
##
## @code{@var{CM} = char (@var{C})} returns a character matrix @var{CM},
## which contains @code{numel (@var{C})} rows and each row contains the
## category name for the corresponding element of @code{@var{C}(:)}.
##
## @end deftypefn
function CM = char (this)
cstr = dispstrings (this);
CM = char (cstr(:));
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} double (@var{C})
##
## Convert categorical array to a double array.
##
## @code{@var{out} = double (@var{C})} returns a double array indexing the
## categories in @var{C}. Categorical elements of undefined category are
## returned as @code{NaN}.
##
## @end deftypefn
function out = double (this)
out = double (this.code);
out(out == 0) = NaN;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} single (@var{C})
##
## Convert categorical array to a single array.
##
## @code{@var{out} = single (@var{C})} returns a single array indexing the
## categories in @var{C}. Categorical elements of undefined category are
## returned as @code{NaN}.
##
## @end deftypefn
function out = single (this)
out = single (this.code);
out(out == 0) = NaN;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} int64 (@var{C})
##
## Convert categorical array to a int64 array.
##
## @code{@var{out} = int64 (@var{C})} returns a @qcode{int64} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}.
##
## @end deftypefn
function out = int64 (this)
out = int64 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} int32 (@var{C})
##
## Convert categorical array to a int32 array.
##
## @code{@var{out} = int32 (@var{C})} returns a @qcode{int32} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}.
##
## @end deftypefn
function out = int32 (this)
out = int32 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} int16 (@var{C})
##
## Convert categorical array to a int16 array.
##
## @code{@var{out} = int16 (@var{C})} returns a @qcode{int16} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}. Note that the returned category
## indices saturate to @qcode{intmax ('int16')}, which is 32767.
##
## @end deftypefn
function out = int16 (this)
out = int16 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} int8 (@var{C})
##
## Convert categorical array to a int8 array.
##
## @code{@var{out} = int8 (@var{C})} returns a @qcode{int8} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}. Note that the returned category
## indices saturate to @qcode{intmax ('int8')}, which is 127.
##
## @end deftypefn
function out = int8 (this)
out = int8 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} uint64 (@var{C})
##
## Convert categorical array to a uint64 array.
##
## @code{@var{out} = uint64 (@var{C})} returns a @qcode{uint64} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}.
##
## @end deftypefn
function out = uint64 (this)
out = uint64 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} uint32 (@var{C})
##
## Convert categorical array to a uint32 array.
##
## @code{@var{out} = uint32 (@var{C})} returns a @qcode{uint32} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}.
##
## @end deftypefn
function out = uint32 (this)
out = uint32 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} uint16 (@var{C})
##
## Convert categorical array to a uint16 array.
##
## @code{@var{out} = uint16 (@var{C})} returns a @qcode{uint16} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}.
##
## @end deftypefn
function out = uint16 (this)
out = uint16 (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} uint8 (@var{C})
##
## Convert categorical array to a int8 array.
##
## @code{@var{out} = uint8 (@var{C})} returns a @qcode{uint8} array
## indexing the categories in @var{C}. Categorical elements of undefined
## category are returned as @qcode{0}. Note that the returned category
## indices saturate to @qcode{intmax ('uint8')}, which is 255.
##
## @end deftypefn
function out = uint8 (this)
out = uint8 (this.code);
endfunction
endmethods
################################################################################
## ** Summary Information ** ##
################################################################################
## Available Methods ##
## ##
## 'summary' 'categories' 'countcats' 'length' ##
## 'size' 'ndims' 'numel' 'keyHash' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {} summary (@var{C})
## @deftypefnx {categorical} {} summary (@var{C}, @var{dim})
## @deftypefnx {categorical} {} summary (@dots{}, @var{Name}, @var{Value})
## @deftypefnx {categorical} {@var{s} =} summary (@dots{})
##
## Display summary of categorical array.
##
## @code{summary (@var{C})} displays the number of elements in the
## categorical array @var{C} that are equal to each category of @var{C}.
## Any undefined elements in @var{C} are summed together and displayed as
## @qcode{}.
##
## @end deftypefn
function varargout = summary (this, varargin)
## Parse optional Name-Value paired arguments
optName = {'Statistics'};
dfValue = {'default'};
[stats, args] = parsePairedArguments (optName, dfValue, varargin(:));
## Force stats to cellstr
stats = cellstr (stats);
## Handle default statistcs
didx = strcmpi (stats, 'default');
if (this.isOrdinal)
if (any (didx))
default = {'counts', 'nummissing', 'min', 'median', 'max'};
stats(didx) = [];
ridx = cellfun (@(x) any (strcmpi (x, default)), stats);
stats(ridx) = [];
stats = [default, stats];
endif
else
if (any (didx))
default = {'counts', 'nummissing'};
stats(didx) = [];
ridx = cellfun (@(x) any (strcmpi (x, default)), stats);
stats(ridx) = [];
stats = [default, stats];
endif
endif
## Get operating dimension
sz = size (this);
if (isempty (args))
(dim = find (sz > 1, 1)) || (dim = 1);
else
if (numel (args) > 1)
error ("categorical.summary: unrecognized input argument.");
endif
dim = args{1};
if (! (isnumeric (dim) && isscalar (dim) && fix (dim) == dim && ...
dim > 0))
error ("categorical.summary: DIM must be a positive integer.");
endif
endif
## Store input size and category names in output struct
s.Size = sz;
s.Type = 'categorical';
s.Name = inputname (1);
s.Categories = this.cats;
## Store 'counts' first (if requested)
cidx = strcmpi (stats, 'counts');
NAMES = {};
if (any (cidx))
NAMES = [NAMES; this.cats];
s.Counts = countcats (this, dim);
stats(cidx) = [];
nidx = strcmpi (stats, 'nummissing');
if (any (nidx))
s.NumMissing = sum (this.isMissing, dim);
stats(nidx) = [];
NAMES = [NAMES; ''];
endif
endif
## Store remaining statistics according to their order in 'stats'
STATS = {};
while (! isempty (stats))
switch (lower (stats{1}))
case 'nummissing'
s.NumMissing = sum (this.isMissing, dim);
STATS = [STATS; 'NumMissing'];
case 'min'
if (this.isOrdinal)
s.Min = min (this, [], dim);
STATS = [STATS; 'Min'];
endif
case 'median'
if (this.isOrdinal)
s.Median = median (this, dim);
STATS = [STATS; 'Median'];
endif
case 'max'
if (this.isOrdinal)
s.Max = max (this, [], dim);
STATS = [STATS; 'Max'];
endif
case 'mode'
s.Mode = mode (this, dim);
STATS = [STATS; 'Mode'];
endswitch
stats(1) = [];
endwhile
## Return structure or display summary
if (nargout > 0)
s = rmfield (s, 'Name');
varargout{1} = s;
else
__summary__ (s, dim, NAMES, STATS);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{cstr} =} categories (@var{C})
##
## List of categories in categorical array.
##
## @code{@var{cstr} = categories (@var{C})} returns a cell array of
## character vectors with the names of the categories in @var{C}.
##
## @end deftypefn
function cstr = categories (this)
cstr = this.cats;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{N} =} countcats (@var{C})
## @deftypefnx {categorical} {@var{N} =} countcats (@var{C}, @var{dim})
##
## Count occurrences of categories in a categorical array.
##
## @code{@var{N} = countcats (@var{C})} returns the number of elements for
## each category in @var{C}. If @var{C} is a vector, @var{N} is also a
## vector with one element for each category in @var{C}. If @var{C} is a
## matrix, @var{N} is a matrix with each column containing the category
## counts from each column of @var{C}. For multidimensional arrays,
## @code{countcats} operates along the first non-singleton dimension.
##
## @code{@var{N} = countcats (@var{C}, @var{dim})} operates along the
## dimension @var{dim}.
##
## @end deftypefn
function N = countcats (this, dim = [])
codes = this.code;
sz = size (codes);
nc = numel (this.cats);
if (isempty (dim))
(dim = find (sz > 1, 1)) || (dim = 1);
elseif (! (isnumeric (dim) && isscalar (dim) && fix (dim) == dim && ...
dim > 0))
error ("categorical.countcats: DIM must be a positive integer.");
endif
if (nc == 0)
sz(dim) = 0;
N = zeros (sz);
return;
endif
if (dim <= ndims (this))
nsz = sz;
nsz(dim) = nc;
## Look-up indices.
grp = [1:nc];
idx = lookup (grp, codes);
## Zero invalid ones (including NaNs). x < edges(1) are already zero.
idx(! (codes <= grp(end))) = 0;
iidx = idx;
## In case of matrix input, we adjust the indices.
no_vector = (isrow (codes) && dim == 1) || ...
(iscolumn (codes) && dim == 2);
if (! isvector (codes) || no_vector)
nl = prod (sz(1:dim-1));
nn = sz(dim);
nu = prod (sz(dim+1:end));
if (nl != 1)
iidx = (iidx-1) * nl;
iidx += reshape (kron (ones (1, nn*nu), 1:nl), sz);
endif
if (nu != 1)
ne = length (grp);
iidx += reshape (kron (nl*ne*(0:nu-1), ones (1, nl*nn)), sz);
endif
endif
## Select valid elements.
iidx = iidx(idx != 0);
## Call accumarray to sum the indexed elements.
N = accumarray (iidx(:), 1, nsz);
else
N = repmat (zeros (size (this)), [ones(1, dim - 1), nc]);
totnum = prod (size (this));
linvec = 1:totnum;
for i = 1:nc
offset = (i - 1) * totnum;
N(linvec + offset) = codes == i;
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{N} =} length (@var{C})
##
## Length of a categorical vector.
##
## @code{@var{N} = length (@var{C})} returns the size of the longest
## dimension of the categorical array @var{C}, unless any of its dimensions
## has zero length, in which case @code{length (@var{C})} returns 0.
##
## @end deftypefn
function N = length (this)
if (isempty (this.code))
N = 0;
else
N = max (size (this.code));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{sz} =} size (@var{C})
## @deftypefnx {categorical} {@var{dim_sz} =} size (@var{C}, @var{dim})
## @deftypefnx {categorical} {@var{dim_sz} =} size (@var{C}, @var{d1}, @var{d2}, @dots{})
## @deftypefnx {categorical} {[@var{rows}, @var{columns}, @dots{}, @var{dim_n_sz}] =} size (@dots{})
##
## Size of a categorical array.
##
## @code{@var{sz} = size (@var{C})} returns a row vector with the size
## (number of elements) of each dimension for the categorical array @var{C}.
##
## @code{@var{dim_sz} = size (@var{C}, @var{dim})} returns the size of
## the corresponding dimension specified in @var{dim}. If @var{dim} is a
## vector, then @var{dim_sz} is a vector of the same length and with each
## element corresponding to a specified dimension. Multiple dimensions may
## also be specified as separate arguments.
##
## With a single output argument, @code{size} returns a row vector. When
## called with multiple output arguments, @code{size} returns the size of
## dimension N in the Nth argument.
##
## @end deftypefn
function varargout = size (this, varargin)
if (! isempty (varargin))
sz = size (this.code, varargin{:});
else
sz = size (this.code);
endif
if (nargout == 0 || nargout == 1)
varargout{1} = sz;
elseif (numel (sz) != nargout)
error (strcat ("categorical.size: nargout > 1 but does", ...
" not match number of requested dimensions."));
else
for i = 1:nargout
varargout{i} = sz(i);
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} ndims (@var{C})
##
## Number of dimensions in a categorical array.
##
## @code{@var{out} = ndims (@var{C})} returns the number of dimensions of
## the categorical array @var{C}.
##
## @end deftypefn
function out = ndims (this)
out = ndims (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} numel (@var{C})
##
## Total number of elements in a categorical array.
##
## @code{@var{out} = numel (@var{C})} returns the number of elements in the
## categorical array @var{C}.
##
## @end deftypefn
function out = numel (this, varargin)
out = numel (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{hey} =} keyHash (@var{C})
## @deftypefnx {categorical} {@var{hey} =} keyHash (@var{C}, @var{base})
##
## Generate a hash code for a categorical array.
##
## @code{@var{h} = keyHash (@var{C})} generates a @qcode{uint64} scalar that
## represents the input array @var{C}. @code{keyHash} utilizes the 64-bit
## FNV-1a variant of the Fowler-Noll-Vo non-cryptographic hash function.
##
## @code{@var{h} = keyHash (@var{C}), @var{base}} also generates a 64-bit
## hash code using @var{base} as the offset basis for the FNV-1a hash
## algorithm. @var{base} must be a @qcode{uint64} integer type scalar. Use
## this syntax to cascade @code{keyHash} on multiple objects for which a
## single hash code is required.
##
## Note that unlike MATLAB, this implementation does not use any random
## seed. As a result, @code{keyHash} will always generate the exact same
## hash key for any particular input across different workers and Octave
## sessions.
##
## @end deftypefn
function key = keyHash (this, base = [])
## Initialize string with size, class name, flags, and categories
size_str = sprintf ('%dx', size (this.code))(1:end-1);
flag_str = sprintf ('-o%d-p%d:', this.isOrdinal, this.isProtected);
cats_str = sprintf ('%s', this.cats{:});
init_str = [size_str 'categorical' flag_str cats_str];
if (isempty (this.code))
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("categorical.keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__(init_str, base);
else
key = __ckeyHash__(init_str);
endif
else
cats = [this.cats(:); ''];
code = this.code(:);
code(code == 0) = max (code) + 1;
cstr = [cats{code}];
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("categorical.keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__([init_str cstr], base);
else
key = __ckeyHash__([init_str cstr]);
endif
key = __nkeyHash__(this.isMissing(:), key);
endif
endfunction
endmethods
################################################################################
## ** Query Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'iscategory' 'iscolumn' 'isempty' 'isequal' ##
## 'isequaln' 'ismatrix' 'ismember' 'ismissing' ##
## 'isordinal' 'isprotected' 'isrow' 'isscalar' ##
## 'issorted' 'issortedrows' 'isundefined' 'isvector' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} iscategory (@var{C}, @var{catnames})
##
## Test for categories in a categorical array.
##
## @code{@var{TF} = iscategory (@var{C}, @var{catnames})} returns a logical
## array @var{TF} of the same size as @var{catnames} containing @qcode{true}
## for each corresponding element of @var{catnames} that is a category in
## categorical array @var{C} and @qcode{false} otherwise.
##
## @end deftypefn
function TF = iscategory (this, catnames)
if (nargin < 2)
error ("categorical.iscategory: CATNAMES input argument is required.");
endif
catnames = cellstr (catnames);
TF = ismember (catnames, this.cats);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} iscolumn (@var{C})
##
## Return true if categorical array is a column vector.
##
## @code{@var{TF} = iscolumn (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is a column
## vector, and @qcode{false} otherwise. A column vector is a 2-D array for
## which @code{size (@var{X})} returns @code{[@var{N}, 1]} with non-negative
## @var{N}.
##
## @end deftypefn
function TF = iscolumn (this)
TF = iscolumn (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isempty (@var{C})
##
## Return true if categorical array is empty.
##
## @code{@var{TF} = isempty (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is empty, and
## @qcode{false} otherwise.
##
## @end deftypefn
function TF = isempty (this)
TF = isempty (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isequal (@var{C1}, @var{C2})
## @deftypefnx {categorical} {@var{TF} =} isequal (@var{C1}, @var{C2}, @dots{})
##
## Return true if categorical arrays are equal.
##
## @code{@var{TF} = isequal (@var{C1}, @var{C2})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the categorical arrays @var{C1} and
## @var{C2} contain the same values, and @qcode{false} otherwise. Either
## @var{C1} or @var{C2} may also be a string array, a missing object array,
## a character vector, or a cell array of character vectors, which will be
## promoted to a categorical array prior to comparison.
##
## If categorical arrays @var{C1} and @var{C2} are ordinal, they must have
## the same set and ordering of categories. If neither are ordinal, the
## category names of each pair of elements are compared. Hence, they do not
## need to have the same set of categories.
##
## @code{@var{TF} = isequal (@var{C1}, @var{C2}, @dots{})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if all input arguments are equal,
## and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequal (varargin)
args = varargin;
[args{:}] = promote (varargin{:});
## Check for undefined elements (result to false)
if (any (cellfun (@(x) any (x.code == 0, 'all'), args)))
TF = false;
return;
endif
## If any categorical value is ordinal, all must be
is_ordinal = cellfun (@isordinal, args);
if (all (is_ordinal))
## Check that all categorical arrays have the same categories
## and they are in the same order
cats = cellfun (@(x) categories (x), args, 'UniformOutput', false);
if (! isequal (cats{:}))
TF = false;
return;
endif
fieldArgs = cellfun (@(x) x.code, args, 'UniformOutput', false);
TF = isequal (fieldArgs{:});
elseif (any (is_ordinal))
TF = false;
else
## Compare the category names of each element
fcn = @(x) reshape (x.cats(x.code), size (x.code));
fieldArgs = cellfun (fcn, args, 'UniformOutput', false);
TF = isequal (fieldArgs{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isequaln (@var{C1}, @var{C2})
## @deftypefnx {categorical} {@var{TF} =} isequaln (@var{C1}, @var{C2}, @dots{})
##
## Return true if categorical arrays are equal under the assumption that
## undefined elements are equal.
##
## @code{@var{TF} = isequaln (@var{C1}, @var{C2})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the categorical arrays @var{C1} and
## @var{C2} contain the same values or corresponding undefined elements, and
## @qcode{false} otherwise. Either @var{C1} or @var{C2} may also be a
## string array, a missing object array, a character vector, or a cell array
## of character vectors, which will be promoted to a categorical array prior
## to comparison.
##
## If categorical arrays @var{C1} and @var{C2} are ordinal, they must have
## the same set and ordering of categories. If neither are ordinal, the
## category names of each pair of elements are compared. Hence, they do not
## need to have the same set of categories.
##
## @code{@var{TF} = isequaln (@var{C1}, @var{C2}, @dots{})} returns a
## logical scalar @var{TF}, which is @qcode{true}, if all input arguments
## are equal, and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequaln (varargin)
args = varargin;
[args{:}] = promote (varargin{:});
## If any categorical value is ordinal, all must be
is_ordinal = cellfun (@isordinal, args);
if (all (is_ordinal))
## Check that all categorical arrays have the same categories
## and they are in the same order
cats = cellfun (@(x) categories (x), args, 'UniformOutput', false);
if (! isequal (cats{:}))
TF = false;
return;
endif
fieldArgs = cellfun (@(x) x.code, args, 'UniformOutput', false);
TF = isequal (fieldArgs{:});
elseif (any (is_ordinal))
TF = false;
else
## Compare the category names of each element
fcn = @(x) reshape (([''; x.cats])(x.code + 1), ...
size (x.code));
fieldArgs = cellfun (fcn, args, 'UniformOutput', false);
TF = isequal (fieldArgs{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} ismatrix (@var{C})
##
## Return true if categorical array is a 2-D array.
##
## @code{@var{TF} = ismatrix (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is a matrix, and
## @qcode{false} otherwise. A matrix is an array of any type where
## @code{ndims (@var{X}) == 2} and for which @code{size (@var{X})} returns
## @code{[@var{H}, @var{W}]} with non-negative @var{H} and @var{W}.
##
## @end deftypefn
function TF = ismatrix (this)
TF = ismatrix (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} ismember (@var{A}, @var{B})
## @deftypefnx {categorical} {@var{TF} =} ismember (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{TF}, @var{index}] =} ismember (@dots{})
## @deftypefnx {categorical} {[@var{TF}, @var{index}] =} ismember (@dots{}, @qcode{'legacy'})
##
## Find categorical elements in a set.
##
## @code{@var{TF} = ismember (@var{A}, @var{B})} returns a logical array
## @var{TF} of the same size as @var{A} containing @qcode{true} for each
## corresponding element of @var{A} that is in @var{B} and @qcode{false}
## otherwise. @qcode{} elements are not equal with each other
## and always return @qcode{false}. If @var{A} and @var{B} are ordinal,
## they must have the same ordered set of categories. If neither @var{A}
## nor @var{B} are ordinal, then this restriction is relaxed and comparison
## is performed using the category names. Comparison between an ordinal and
## an unordered categorical array is not allowed. Either @var{A} or @var{B}
## may also be a string array, a character vector, or a cell array of
## character vectors containing one or multiple category names to compare
## against an unordered categorical array.
##
## @code{@var{TF} = ismember (@var{A}, @var{B}, @qcode{'rows'})} only
## applies to categorical matrices with the same number of columns, in which
## case the logical vector @var{TF} contains @qcode{true} for each row of
## @var{A} that is also a row in @var{B}. @var{TF} has the same number of
## rows as @var{A}.
##
## @code{[@var{TF}, @var{index}] = ismember (@var{A}, @var{B})} also returns
## an index array of the same size as @var{A} containing the lowest index in
## @var{B} for each element of @var{A} that is a member of @var{B} and 0
## otherwise. If the @qcode{'rows'} optional argument is used, then the
## returning index is a column vector with the same rows as @var{A} and it
## contains the lowest index in @var{B} for each row of @var{A} that is a
## member of @var{B} and 0 otherwise. If the @qcode{'legacy'} optional
## argument is specified, then the highest index of matched elements is
## returned. Unless multiple matches exist, the @qcode{'legacy'} option has
## no effect on the returned @var{index}.
##
## @end deftypefn
function varargout = ismember (A, B, varargin)
## Either A or B contain categorical text representation
if ((ischar (A) && isrow (A)) || isstring (A) || iscellstr (A))
if (ischar (A))
A = cellstr (A);
endif
A = categorical (A);
elseif ((ischar (B) && isrow (B)) || isstring (B) || iscellstr (B))
if (ischar (B))
B = cellstr (B);
endif
B = categorical (B);
elseif (! (iscategorical (A) && iscategorical (B)))
error (strcat ("categorical.ismember: A and B must be categorical", ...
" arrays, or one of them (A or B) can be a string", ...
" array, a character vector, or a cell array of", ...
" character vectors specifying category names."));
endif
## Check for 'rows' and 'legacy' optional arguments
if (! isempty (varargin))
if (! cellfun ('ischar', varargin));
error (strcat ("categorical.ismember: all options must be", ...
" character vectors."));
elseif (! all (strcmpi (varargin, 'rows') | ...
strcmpi (varargin, 'legacy')))
error (strcat ("categorical.ismember: only 'rows' and", ...
" 'legacy' are valid options."));
endif
if (any (strcmpi ('rows', varargin)))
if (ndims (A) != 2 || ndims (A) != ndims (B))
error (strcat ("categorical.ismember: 'rows' applies only", ...
" to 2-D matrices."));
endif
if (size (A, 2) != size (B, 2))
error (strcat ("categorical.ismember: 'rows' requires same", ...
" number of columns."));
endif
endif
endif
## Handle empty input array
if (isempty (A) || isempty (B))
sz = size (A);
varargout{1} = false (sz);
if (nargout > 1)
varargout{2} = zeros (sz);
endif
return;
endif
## Both ordinal
if (isordinal (A) && isordinal (B))
if (! isequal (categories (A), categories (B)))
error (strcat ("categorical.ismember: ordinal categorical arrays", ...
" must have the same ordered set of categories."));
endif
if (nargout > 1)
[varargout{1}, varargout{2}] = __ismember__ (double (A), ...
double (B), varargin{:});
else
varargout{1} = __ismember__ (double (A), double (B), varargin{:});
endif
elseif (isordinal (A) || isordinal (B))
error (strcat ("categorical.ismember: both categorical arrays", ...
" must be ordinal."));
else
## Compare the category names of each element (except undefined)
A_idx = A.code != 0;
B_idx = B.code != 0;
cats_A = string (cell (size (A.code)));
cats_B = string (cell (size (B.code)));
cats_A(A_idx) = A.cats(A.code(A_idx));
cats_B(B_idx) = B.cats(B.code(B_idx));
if (nargout > 1)
[varargout{1}, varargout{2}] = ismember (cats_A, cats_B, varargin{:});
else
varargout{1} = ismember (cats_A, cats_B, varargin{:});
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} ismissing (@var{C})
## @deftypefnx {categorical} {@var{out} =} ismissing (@var{C}, @var{indicator})
##
## Find missing elements in categorical array.
##
## @code{@var{TF} = ismissing (@var{C})} returns a logical array @var{TF}
## of the same size as @var{C} containing @qcode{true} for each
## corresponding element of @var{C} that does not have a value from one of
## the categories in @var{C} and @qcode{false} otherwise.
##
## @code{@var{TF} = ismissing (@var{C}, @var{indicator})} also returns a
## logical array @var{TF} containing @qcode{true} for each corresponding
## element of @var{C} that does not have a value from one of the categories
## specified in @var{indicator} and @qcode{false} otherwise.
##
## @var{indicator} must be either a categorical array or a character vector
## or a string vector or a cell vector of character vectors. When the
## @var{indicator} contains text representation, the comparison is based on
## lexicographical equality to the category names of @var{C}.
##
## @end deftypefn
function TF = ismissing (this, varargin)
if (nargin > 2)
error ("categorical.ismissing: too many input arguments.");
endif
if (! isempty (varargin))
indicator = varargin{1};
TF = false (size (this));
if (isvector (indicator))
if (ischar (indicator))
if (! isrow (indicator))
error (strcat ("categorical.ismissing: INDICATOR specified", ...
" as a character vector must be a row vector."));
endif
TF(this == indicator) = true;
elseif (isstring (indicator) || iscellstr (indicator))
for i = 1:numel (indicator)
TF(this == indicator(i)) = true;
endfor
elseif (isa (indicator, 'categorical'))
for i = 1:length (indicator)
idx = indicator.code(i);
if (idx)
cat = indicator.cats{idx};
TF(this == cat) = true;
else # code = 0 corresponds to undefined categories
TF(this.isMissing) = true;
endif
endfor
else
error (strcat ("categorical.ismissing: INDICATOR must be", ...
" a text representation of categories or", ...
" categorical."));
endif
else
error ("categorical.ismissing: INDICATOR must be a vector.");
endif
else
TF = this.isMissing;
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isordinal (@var{C})
##
## Test if categorical array is ordinal.
##
## @code{@var{TF} = isordinal (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is ordinal, and
## @qcode{false} otherwise.
##
## @end deftypefn
function TF = isordinal (this)
TF = this.isOrdinal;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isprotected (@var{C})
##
## Test if categorical array is protected.
##
## @code{@var{TF} = isprotected (@var{C})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the categorical array @var{C} is
## protected, and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isprotected (this)
TF = this.isProtected;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isrow (@var{C})
##
## Return true if categorical array is a row vector.
##
## @code{@var{TF} = isrow (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is a row vector,
## and @qcode{false} otherwise. A row vector is a 2-D array for which
## @code{size (@var{X})} returns @code{[1, @var{N}]} with non-negative
## @var{N}.
##
## @end deftypefn
function TF = isrow (this)
TF = isrow (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isscalar (@var{C})
##
## Return true if categorical array is a scalar.
##
## @code{@var{TF} = isscalar (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is also a scalar,
## and @qcode{false} otherwise. A scalar is a single element object for
## which @code{size (@var{X})} returns @code{[1, 1]}.
##
## @end deftypefn
function TF = isscalar (this)
TF = isscalar (this.code);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} issorted (@var{C})
## @deftypefnx {categorical} {@var{TF} =} issorted (@var{C}, @var{dim})
## @deftypefnx {categorical} {@var{TF} =} issorted (@var{C}, @var{direction})
## @deftypefnx {categorical} {@var{TF} =} issorted (@var{C}, @var{dim}, @var{direction})
## @deftypefnx {categorical} {@var{TF} =} issorted (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
##
## Return true if categorical array is sorted.
##
## @code{@var{TF} = issorted (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the categorical array @var{C} is sorted in
## ascending order, and @qcode{false} otherwise.
##
## @code{@var{TF} = issorted (@var{C}, @var{dim})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the categorical array @var{C} is
## sorted in ascending order along the dimension @var{dim}, and
## @qcode{false} otherwise.
##
## @code{@var{TF} = issorted (@var{A}, @var{direction})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if the categorical array @var{C}
## is sorted in the direction specified by @var{direction}, and
## @qcode{false} otherwise. @var{direction} can be one of the following
## options:
##
## @itemize
## @item @qcode{'ascend'}, which is the default, checks is elements are in
## ascending order.
## @item @qcode{'descend'} checks if elements are in descending order.
## @item @qcode{'monotonic'} checks if elements are either in ascending or
## descending order.
## @item @qcode{'strictascend'} checks if elements are in ascending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictdescend'} checks if elements are in descending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictmonotonic'} checks if elements are either in
## ascending or descending order and there are no duplicate or undefined
## elements.
## @end itemize
##
## @code{@var{TF} = issorted (@dots{}, @qcode{'MissingPlacement'},
## @var{MP})} specifies where missing elements (@qcode{}) are
## placed with
## one of the following options specified in @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @end deftypefn
function TF = issorted (this, varargin)
## Single input argument
if (nargin == 1)
TF = isequaln (this, sort (this));
return;
endif
## Get operating dimension
cid = cellfun (@isnumeric, varargin);
if (any (cid))
dim = varargin{cid};
else
sz = size (this);
dim = find (sz != 1, 1);
if (isempty (dim)) # scalar
dim = 1;
endif
endif
## Parse and validate optional 'MissingPlacement' paired argument
optNames = {'MissingPlacement'};
dfValues = {'auto'};
[MP, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! ismember (MP, {'auto', 'first', 'last'}))
error ("categorical.issorted: invalid value for 'MissingPlacement'.");
endif
## Force strings to character vectors
[args{:}] = convertStringsToChars (args{:});
## Get direction
cid = cellfun (@(x) ischar (x), args);
if (any (cid))
direction = args{cid};
## Check for type of direction
valid_direction = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
if (! ismember (direction, valid_direction))
error ("categorical.issorted: invalid DIRECTION value.");
endif
switch (direction)
case {'ascend', 'descend'}
TF = isequaln (this, sort (this, args{:}, 'MissingPlacement', MP));
case {'strictascend', 'strictdescend'}
## Check for missing values first (fast)
if (any (this.isMissing, 'all'))
TF = false;
return;
endif
args{cid} = strrep (direction, 'strict', '');
if (! strcmp (MP, 'auto'))
args = [args, 'MissingPlacement', MP];
endif
sorted = sort (this, args{:});
if (any (diff (double (sorted), 1, dim) == 0, 'all'))
TF = false;
return;
endif
TF = isequal (this, sorted);
case 'monotonic'
## Check for either ascending or descending
args{cid} = 'ascend';
TF = isequaln (this, sort (this, args{:}, 'MissingPlacement', MP));
if (TF)
return;
endif
args{cid} = 'descend';
TF = isequaln (this, sort (this, args{:}, 'MissingPlacement', MP));
case 'strictmonotonic'
## Check missing values first (fast)
if (any (this.isMissing, 'all'))
TF = false;
return;
endif
## Check for either ascending or descending
args{cid} = 'ascend';
sorted = sort (this, args{:}, 'MissingPlacement', MP);
if (any (diff (double (sorted), 1, dim) == 0, 'all'))
TF = false;
return;
endif
TF = isequal (this, sorted);
if (TF)
return;
endif
args{cid} = 'descend';
sorted = sort (this, args{:}, 'MissingPlacement', MP);
if (any (diff (double (sorted), 1, dim) == 0, 'all'))
TF = false;
return;
endif
TF = isequal (this, sorted);
endswitch
else
## No DIRECTION input argument
TF = isequaln (this, sort (this, args{:}, 'MissingPlacement', MP));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} issortedrows (@var{C})
## @deftypefnx {categorical} {@var{TF} =} issortedrows (@var{C}, @var{col})
## @deftypefnx {categorical} {@var{TF} =} issortedrows (@var{C}, @var{direction})
## @deftypefnx {categorical} {@var{TF} =} issortedrows (@var{C}, @var{col}, @var{direction})
## @deftypefnx {categorical} {@var{TF} =} issortedrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
##
## Return true if categorical matrix rows are sorted.
##
## @code{@var{TF} = issortedrows (@var{C})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the rows in the 2-D categorical array
## @var{C} are sorted in ascending order, and @qcode{false} otherwise.
##
## @code{@var{TF} = issortedrows (@var{C}, @var{col})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if the categorical array @var{C}
## is sorted according to the columns specified by the vector @var{col}, and
## @qcode{false} otherwise. @var{col} must explicitly contain non-zero
## integers whose absolute values index existing columns in @var{C}.
## Positive elements sort the corresponding columns in ascending order,
## while negative elements sort the corresponding columns in descending
## order.
##
## @code{@var{TF} = issortedrows (@var{C}, @var{direction})} checks if the
## rows in @var{C} are sorted according to the specified direction, which
## can be one of the following options:
##
## @itemize
## @item @qcode{'ascend'}, which is the default, checks is elements are in
## ascending order.
## @item @qcode{'descend'} checks if elements are in descending order.
## @item @qcode{'monotonic'} checks if elements are either in ascending or
## descending order.
## @item @qcode{'strictascend'} checks if elements are in ascending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictdescend'} checks if elements are in descending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictmonotonic'} checks if elements are either in
## ascending or descending order and there are no duplicate or undefined
## elements.
## @end itemize
##
## Alternatively, @var{direction} can be a cell array of character
## vectors specifying the sorting direction for each individual column of
## @var{C}, in which case the number of elements in @var{direction} must
## equal the number of columns in @var{C}.
##
## @code{@var{TF} = issortedrows (@var{C}, @var{col}, @var{direction})}
## checks if the rows in the categorical array @var{C} are sorted according
## to the columns specified in @var{col} using the corresponding sorting
## direction specified in @var{direction}. In this case, the sign of the
## values in @var{col} is ignored. @var{col} and @var{direction} must have
## the same length, but not necessarily the same number of elements as the
## columns in @var{C}.
##
## @code{@var{TF} = issortedrows (@dots{}, @qcode{'MissingPlacement'},
## @var{MP})} specifies where missing elements (@qcode{}) are
## placed with one of the following options specified in @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @end deftypefn
function TF = issortedrows (this, varargin)
## Single input argument
if (nargin == 1)
TF = isequaln (this, sortrows (this));
return;
endif
## Force strings to character vectors or cell arrays of character vectors
[varargin{:}] = convertStringsToChars (varargin{:});
## Get valid direction(s) from input argument list
valid = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
fcn = @(x) (ischar (x) && ismember (x, valid)) || iscellstr (x);
cid = cellfun (fcn, varargin);
if (any (cid))
direction = cellstr (varargin{cid});
## Check for valid type of directions in cellstring
if (! all (cellfun (@(x) ismember (x, valid), direction)))
error ("duration.issortedrows: invalid DIRECTION value.");
endif
## Handle non-strict modes first
if (all (cellfun (@(x) ismember (x, {'ascend', 'descend'}), direction)))
TF = isequaln (this, sortrows (this, varargin{:}));
return;
endif
simple_types = {'ascend', 'descend', 'monotonic'};
if (all (cellfun (@(x) ismember (x, simple_types), direction)))
idx = strcmp (direction, 'monotonic');
direction{idx} = 'ascend';
varargin{cid} = direction;
TF = isequaln (this, sortrows (this, varargin{:}));
if (TF)
return;
endif
direction{idx} = 'descend';
varargin{cid} = direction;
TF = isequaln (this, sortrows (this, varargin{:}));
return;
endif
## Handle strict modes. Determine the sort-key column order and the
## sort position holding the first strict direction, then derive the
## prefix (the columns sorted up to and including that position, on
## which the duplicate test operates) and the binding strict column
## (the single column on which the missing test operates). A missing
## value in the binding column, or two consecutive sorted rows equal
## across the prefix columns, rules out a strict ordering; strict
## positions after the first are subsumed by it.
strict_types = {'strictascend', 'strictdescend', 'strictmonotonic'};
sflag = cellfun (@(x) ismember (x, strict_types), direction);
nc = size (this, 2);
nummask = cellfun (@isnumeric, varargin);
if (any (nummask))
col = varargin{nummask};
ocols = abs (col(:)');
if (isscalar (direction))
sflag = repmat (sflag, 1, numel (col));
elseif (numel (direction) != numel (col))
error ("categorical.issortedrows: COL and DIRECTION mismatch.");
endif
else
ocols = 1:nc;
if (isscalar (direction))
sflag = repmat (sflag, 1, nc);
endif
endif
K = find (sflag, 1);
prefix = ocols(1:K);
bindcol = ocols(K);
## A missing value in the binding strict column rules out strictness.
if (any (this.isMissing(:,bindcol), 'all'))
TF = false;
return;
endif
## Replace strict modes with their plain counterparts for the sort.
direction = strrep (direction, 'strict', '');
varargin{cid} = direction;
if (all (cellfun (@(x) ismember (x, {'ascend', 'descend'}), direction)))
sorted = sortrows (this, varargin{:});
## No two consecutive rows may tie across the prefix columns.
tmpcol = sorted.code(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
else # a 'monotonic' position also exists
idx = strcmp (direction, 'monotonic');
direction(idx) = {'ascend'};
varargin{cid} = direction;
sorted = sortrows (this, varargin{:});
tmpcol = sorted.code(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
if (TF)
return;
endif
direction(idx) = {'descend'};
varargin{cid} = direction;
sorted = sortrows (this, varargin{:});
tmpcol = sorted.code(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
endif
else
## No DIRECTION input argument
TF = isequaln (this, sortrows (this, varargin{:}));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{out} =} isundefined (@var{C})
##
## Test for undefined elements in categorical array.
##
## @code{@var{TF} = isundefined (@var{C})} returns a logical array @var{TF}
## of the same size as @var{C} containing @qcode{true} for each
## corresponding element of @var{C} that does not have a value from one of
## the categories in @var{C} and @qcode{false} otherwise.
## @qcode{} is the equivalent of @qcode{NaN} in numeric arrays.
##
## @end deftypefn
function TF = isundefined (this)
TF = this.isMissing;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} isvector (@var{C})
##
## Return true if categorical array is a vector.
##
## @code{@var{TF} = isvector (@var{C})} returns a logical scalar @var{TF},
## which is @qcode{true} if the categorical array @var{C} is a vector and
## @qcode{false} otherwise. A vector is a 2-D array for which one of the
## dimensions is equal to 1 (either @math{1*N} or @math{N*1}). By
## definition, a scalar is also a vector.
##
## @end deftypefn
function TF = isvector (this)
TF = isvector (this.code);
endfunction
endmethods
################################################################################
## ** Category Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'addcats' 'mergecats' 'removecats' 'renamecats' ##
## 'reordercats' 'setcats' 'times' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} addcats (@var{A}, @var{newcats})
## @deftypefnx {categorical} {@var{B} =} addcats (@dots{}, @qcode{'After'}, @var{catname})
## @deftypefnx {categorical} {@var{B} =} addcats (@dots{}, @qcode{'Before'}, @var{catname})
##
## Add categories to categorical array.
##
## @code{@var{B} = addcats (@var{A}, @var{newcats})} appends new categories
## specified in @var{newcats} to the categorical array @var{A} at the end of
## any existing categories. The output categorical array @var{B} does not
## contain elements that belong to the newly added categories.
##
## @code{@var{B} = addcats (@dots{}, @qcode{'After'}, @var{catname})} adds
## the categories after the existing category specified by @var{catname}.
##
## @code{@var{B} = addcats (@dots{}, @qcode{'Before'}, @var{catname})} adds
## the categories before the existing category specified by @var{catname}.
##
## @var{catname} must be either a character vector, a cellstr scalar or a
## string scalar. @var{newcats} can be a string array, a cell array of
## character vectors, or any type of array that can be converted to a cell
## array of character vectors with the @code{cellstr} function, as long as
## it does not contain any duplicate names or references existing category
## in @var{A}.
##
## When adding a single category, @var{newcats} can also be specified as a
## character vector.
##
## @end deftypefn
function B = addcats (A, newcats, varargin)
## Check input arguments
if (nargin < 2)
error ("categorical.addcats: too few input arguments.");
elseif (isempty (newcats))
error ("categorical.addcats: NEWCATS cannot be empty.");
elseif (isnumeric (newcats) || islogical (newcats))
error ("categorical.addcats: NEWCATS cannot be numeric or logical.");
endif
## Convert to cellstring
if (! iscellstr (newcats))
try
newcats = cellstr (newcats);
catch
error (strcat ("categorical.addcats: NEWCATS cannot be", ...
" converted to cellstr."));
end_try_catch
endif
## Force to column vector
newcats = newcats(:);
## New catnames must be unique and non-existing
if (numel (newcats) != numel (unique (newcats)))
error ("categorical.addcats: duplicate category names in NEWCATS.");
endif
TF = ismember (newcats, A.cats);
if (any (TF, 'all'))
error ("categorical.addcats: new category names already present.");
endif
## Parse optional Name-Value paired arguments
optNames = {'After', 'Before'};
dfValues = {[], []};
[After, Before] = parsePairedArguments (optNames, dfValues, varargin(:));
## Check optional Name-Value paired arguments
if (! isempty (After) && ! isempty (Before))
error (strcat ("categorical.addcats: cannot specify both", ...
" 'After' and 'Before'."));
endif
## Add categories
if (! isempty (After))
maxcode = numel (A.cats);
idxcode = find (strcmp (After, A.cats));
if (isempty (idxcode))
error (strcat ("categorical.addcats: 'After' indexes a", ...
" non-existing category."));
elseif (idxcode == maxcode)
B = A;
B.cats = [B.cats; newcats];
else
B = A;
B.cats = [B.cats(1:idxcode); newcats; B.cats(idxcode+1:end)];
idx_add = idxcode+1:maxcode;
n_cats = numel (newcats);
for i = numel (idx_add):-1:1
B.code(B.code == idx_add(i)) += n_cats;
endfor
endif
elseif (! isempty (Before))
maxcode = numel (A.cats);
idxcode = find (strcmp (Before, A.cats));
if (isempty (idxcode))
error (strcat ("categorical.addcats: 'Before' indexes a", ...
" non-existing category."));
elseif (idxcode == 1)
B = A;
B.cats = [newcats; B.cats];
B.code(! B.isMissing) += numel (newcats);
else
B = A;
B.cats = [B.cats(1:idxcode-1); newcats; B.cats(idxcode:end)];
idx_add = idxcode:maxcode;
n_cats = numel (newcats);
for i = numel (idx_add):-1:1
B.code(B.code == idx_add(i)) += n_cats;
endfor
endif
else
B = A;
B.cats = [B.cats; newcats];
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} mergecats (@var{A}, @var{oldcats})
## @deftypefnx {categorical} {@var{B} =} mergecats (@var{A}, @var{oldcats}, @var{newcat})
##
## Merge categories in categorical array.
##
## @code{@var{B} = mergecats (@var{A}, @var{oldcats})} merges two or more
## categories specified by @var{oldcats} into a single category with the
## same name as @qcode{@var{oldcats}(1)}. In case of ordinal categorical
## arrays, the categories listed in @var{oldcats} must be in consecutive
## order. All elements of @var{A} corresponding to the categories listed in
## @var{oldcats} are re-indexed to correspond to @qcode{@var{oldcats}(1)} in
## @var{B}.
##
## @code{@var{B} = mergecats (@var{A}, @var{oldcats}, @var{newcat})} merges
## the categories listed in @var{oldcats} into a single new category named
## as specified by @var{newcat}.
##
## @var{newcat} must be either a character vector, a cellstr scalar or a
## string scalar. @var{oldcats} can be string array, a cell array of
## character vectors, or any type of array that can be converted to a cell
## array of character vectors with the @code{cellstr} function. Any names
## in @var{oldcats} that do not reference an existing category are ignored.
##
## @end deftypefn
function B = mergecats (A, oldcats, varargin)
## Check input arguments
if (nargin < 2)
error ("categorical.mergecats: too few input arguments.");
elseif (isempty (oldcats))
error ("categorical.mergecats: OLDCATS cannot be empty.");
elseif (isnumeric (oldcats) || islogical (oldcats))
error ("categorical.mergecats: OLDCATS cannot be numeric or logical.");
elseif (ischar (oldcats))
error ("categorical.mergecats: OLDCATS cannot be a character vector.");
endif
## Convert to cellstring
if (! iscellstr (oldcats))
try
oldcats = cellstr (oldcats);
catch
error (strcat ("categorical.mergecats: OLDCATS cannot be", ...
" converted to cellstr."));
end_try_catch
endif
## Force to column vector
oldcats = oldcats(:);
## Check for optional third argument
if (nargin < 3)
newcat = oldcats{1};
else
newcat = varargin{1};
if (isstring (newcat) && isscalar (newcat))
newcat = cellstr (newcat);
elseif (ischar (newcat) && (isrow (newcat) || isempty (newcat)))
newcat = cellstr (newcat);
elseif (! (iscellstr (newcat) && isscalar (newcat)))
error (strcat ("categorical.mergecats: NEWCAT must be either", ...
" a character vector, a cellstring scalar, or", ...
" a string scalar."));
endif
newcat = cellstr (varargin{1});
if (cellfun ('isempty', newcat))
error ("categorical.mergecats: NEWCAT cannot be empty.");
endif
endif
## Keep old cat names that reference existing categories, ignore the rest
[TF, index] = ismember (oldcats, A.cats);
if (! any (TF, 'all'))
B = A;
return;
endif
index(! TF) = [];
## Only consecutive categories can be merged in ordinal arrays
if (A.isOrdinal && any (diff (sort (index)) != 1))
error (strcat ("categorical.mergecats: only consecutive categories", ...
" can be merged in ordinal categorical arrays."));
endif
## Merge categories
TF = ismember (A.code, index);
[Findex, Fidx] = min (index);
index(Fidx) = [];
B = A;
B.code(TF) = Findex;
B.cats(Findex) = newcat;
B.cats(index) = [];
## Fix codes due to removed categories
index = sort (index, 'descend');
for idx = index(:)'
B.code(B.code > idx) -= 1;
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} removecats (@var{A})
## @deftypefnx {categorical} {@var{B} =} removecats (@var{A}, @var{oldcats})
##
## Remove categories from categorical array.
##
## @code{@var{B} = removecats (@var{A})} removes all unused categories from
## categorical array @var{A}. The output categorical array @var{B} has the
## same size and values as @var{A}, but potentially fewer categories.
##
## @code{@var{B} = removecats (@var{A}, @var{oldcats})} removes the
## categories specified by @var{oldcats}. The elements of @var{B} that
## correspond to the removed categories are undefined.
##
## @var{oldcats} can be a string array, a cell array of character vectors,
## or any type of array that can be converted to a cell array of character
## vectors with the @code{cellstr} function. Any names in @var{oldcats}
## that do not reference an existing category are ignored.
##
## When removing a single category, @var{oldcats} can also be specified as a
## character vector.
##
## @end deftypefn
function B = removecats (A, varargin)
## Remove unused categories
if (nargin == 1)
usedcodes = __unique__ (A.code);
usedcodes(usedcodes == 0) = [];
remcodes = setdiff (1:numel (A.cats), usedcodes);
B = A;
B.cats(remcodes) = [];
remcodes = sort (remcodes, 'descend');
for code = remcodes(:)'
B.code(B.code > code) -= 1;
endfor
else
oldcats = varargin{1};
## Some input validation
if (isempty (oldcats))
## Handle MATLAB compatibility here
if (iscell (oldcats))
B = A;
return;
endif
error ("categorical.removecats: OLDCATS cannot be empty.");
elseif (isnumeric (oldcats) || islogical (oldcats))
error (strcat ("categorical.removecats: OLDCATS cannot be", ...
" numeric or logical."));
endif
## Convert to cellstring
if (! iscellstr (oldcats))
try
oldcats = cellstr (oldcats);
catch
error (strcat ("categorical.removecats: OLDCATS", ...
" cannot be converted to cellstr."));
end_try_catch
endif
## Keep old cat names that reference existing categories, ignore the
## rest
[TF, remcodes] = ismember (oldcats, A.cats);
if (! any (TF, 'all'))
B = A;
return;
endif
remcodes(! TF) = [];
[TF] = ismember (A.code, remcodes);
B = A;
B.code(TF) = 0;
B.cats(remcodes) = [];
B.isMissing = B.isMissing | TF;
remcodes = sort (remcodes, 'descend');
for code = remcodes(:)'
B.code(B.code > code) -= 1;
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} renamecats (@var{A}, @var{newnames})
## @deftypefnx {categorical} {@var{B} =} renamecats (@var{A}, @var{oldnames}, @var{newnames})
##
## Rename categories in categorical array.
##
## @code{@var{B} = renamecats (@var{A}, @var{newnames})} renames all the
## categories in @var{A}, without changing any of its values, with the names
## specified in @var{newnames}. @var{newnames} can be specified as a string
## array, a cell array of character vectors, or any type of array that can
## be converted to a cell array of character vectors with the @code{cellstr}
## function, as long as it has the same number of elements as the categories
## in @var{A}.
##
## @code{@var{B} = renamecats (@var{A}, @var{oldnames}, @var{newnames})}
## renames the categories of @var{A} specified in @var{oldnames} with the
## names specified in @var{newnames}. Both @var{oldnames} and
## @var{newnames} can be a string array, a cell array of character vectors,
## or any type of array that can be converted to a cell array of character
## vectors with the @code{cellstr} function, as long as they have the same
## number of elements. @var{oldnames} must specify a subset of existing
## categories in @var{A}.
##
## When renaming a single category, both @var{oldnames} and @var{newnames}
## can also be specified as character vectors.
##
## @end deftypefn
function B = renamecats (A, varargin)
## Check input arguments
if (nargin < 2)
error ("categorical.renamecats: too few input arguments.");
endif
## Process 2 input arguments
if (nargin == 2)
oldnames = A.cats;
newnames = varargin{1};
## Some input validation
if (isempty (newnames))
## Handle MATLAB compatibility here
if (iscell (newnames))
B = A;
return;
endif
error ("categorical.renamecats: NEWNAMES cannot be empty.");
elseif (isnumeric (newnames) || islogical (newnames))
error (strcat ("categorical.renamecats: NEWNAMES cannot be", ...
" numeric or logical."));
endif
## Convert to cellstring
if (! iscellstr (newnames))
try
newnames = cellstr (newnames);
catch
error (strcat ("categorical.renamecats: NEWNAMES", ...
" cannot be converted to cellstr."));
end_try_catch
endif
## Make sure categories match
if (numel (oldnames) != numel (newnames))
error (strcat ("categorical.renamecats: NEWNAMES must equal the", ...
" number of existing categories in input array."));
endif
## Process 3 input arguments
else
oldnames = varargin{1};
newnames = varargin{2};
## OLDNAMES input validation
if (isempty (oldnames) && ! iscell (oldnames))
error ("categorical.renamecats: OLDNAMES cannot be empty.");
elseif (isnumeric (oldnames) || islogical (oldnames))
error (strcat ("categorical.renamecats: OLDNAMES cannot be", ...
" numeric or logical."));
endif
## Convert to cellstring
if (! iscellstr (oldnames))
try
oldnames = cellstr (oldnames);
catch
error (strcat ("categorical.renamecats: OLDNAMES", ...
" cannot be converted to cellstr."));
end_try_catch
endif
## NEWNAMES input validation
if (isempty (newnames) && ! iscell (newnames))
error ("categorical.renamecats: NEWNAMES cannot be empty.");
elseif (isnumeric (newnames) || islogical (newnames))
error (strcat ("categorical.renamecats: NEWNAMES cannot be", ...
" numeric or logical."));
endif
## Convert to cellstring
if (! iscellstr (newnames))
try
newnames = cellstr (newnames);
catch
error (strcat ("categorical.renamecats: NEWNAMES", ...
" cannot be converted to cellstr."));
end_try_catch
endif
## Make sure category names match
if (numel (oldnames) != numel (newnames))
error (strcat ("categorical.renamecats: OLDNAMES and NEWNAMES", ...
" must have the same number of elements."));
endif
endif
## Find and rename existing categories
[TF, index] = ismember (oldnames, A.cats);
if (! all (TF))
error (strcat ("categorical.renamecats: OLDNAMES must be", ...
" a subset of existing categories."));
endif
B = A;
B.cats(index) = newnames;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} reordercats (@var{A})
## @deftypefnx {categorical} {@var{B} =} reordercats (@var{A}, @var{neworder})
##
## Reorder categories in categorical array.
##
## @code{@var{B} = reordercats (@var{A})} reorders the categories of @var{A}
## in alphanumeric order.
##
## @code{@var{B} = reordercats (@var{A}, @var{neworder})} reorders the
## categories of @var{A} according to the order specified by @var{neworder},
## which must define a permutation of @code{categories (@var{A})}.
##
## @var{neworder} can be a numeric vector, a string array, a cell array of
## character vectors, or any type of array that can be converted to a cell
## array of character vectors with the @code{cellstr} function as long as it
## indexes all existing categories in @var{A}.
##
## @end deftypefn
function B = reordercats (A, varargin)
## Get NEWORDER
if (nargin == 1)
neworder = sort (A.cats);
else
neworder = varargin{1};
## NEWORDER input validation
if (isnumeric (neworder))
catidx = 1:numel (A.cats);
if (! (isvector (neworder) && neworder > 0 && ...
fix (neworder) == neworder))
error (strcat ("categorical.reordercats: NEWORDER numeric", ...
" input must be a vector of positive integers."));
endif
if (! isequal (sort (neworder)(:), catidx(:)))
error (strcat ("categorical.reordercats: NEWORDER numeric", ...
" input must index a permutation of existing", ...
" categories."));
endif
neworder = A.cats(neworder);
elseif (isempty (neworder))
error ("categorical.reordercats: NEWORDER cannot be empty.");
elseif (islogical (neworder))
error ("categorical.reordercats: NEWORDER cannot be logical.");
elseif (ischar (neworder))
error (strcat ("categorical.reordercats: NEWORDER cannot be", ...
" a character vector."));
endif
## Convert to cellstring
if (! iscellstr (neworder))
try
neworder = cellstr (varargin{1});
catch
error (strcat ("categorical.reordercats: NEWORDER", ...
" cannot be converted to cellstr."));
end_try_catch
endif
## Make sure categories match
if (! all (ismember (neworder, A.cats)))
error (strcat ("categorical.reordercats: NEWORDER must contain", ...
" the same set with the existing categories."));
endif
endif
## Reorder
[~, newidx] = ismember (A.cats, neworder);
B = A;
B.code(! B.isMissing) = newidx(A.code(! A.isMissing));
B.cats = neworder(:);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} setcats (@var{A}, @var{newcats})
##
## Set categories in categorical array.
##
## @code{@var{B} = setcats (@var{A}, @var{newcats})} sets categories in the
## categorical array @var{B} according to the elements of the input array
## @var{A} and the categories specified by @var{newcats} according to the
## following rules:
##
## @itemize
## @item Any element of @var{A} that corresponds to a category listed in
## @var{newcats} is copied to @var{B} with the same categorical value.
## @item Any categories of @var{A} not listed in @var{newcats} are not
## copied to @var{B} and the corresponding elements of @var{B} are
## undefined.
## @item New categories listed in @var{newcats} that are not present in
## @var{A} are added in @var{B}, but without any elements equal to these
## new categories.
## @end itemize
##
## @var{newcats} can be a string array, a cell array of character vectors
## or any type of array that can be converted to a cell array of character
## vectors with the @code{cellstr} function. When setting a single new
## category, @var{newcats} can also be specified as a character vector.
##
## @end deftypefn
function B = setcats (A, newcats)
## Check input arguments
if (nargin < 2)
error ("categorical.setcats: too few input arguments.");
endif
## NEWCATS input validation
if (isempty (newcats))
## Empty cell removes all categories
if (iscell (newcats))
B = A;
B.cats = {};
sz = size (A);
B.code = uint16 (zeros (sz));
B.isMissing = true (sz);
return;
endif
error ("categorical.setcats: NEWCATS cannot be empty.");
elseif (isnumeric (newcats) || islogical (newcats))
error ("categorical.setcats: NEWCATS cannot be numeric or logical.");
endif
## Convert to cellstring
if (! iscellstr (newcats))
try
newcats = cellstr (newcats);
catch
error (strcat ("categorical.setcats: NEWCATS cannot be", ...
" converted to cellstr."));
end_try_catch
endif
## Find existing categories
[TF, index] = ismember (A.cats, newcats);
## Remove and reorder categories
if (all (TF, 'all'))
B = A;
else
B = removecats (A, A.cats(! TF));
endif
[TF, index] = ismember (newcats, B.cats);
index(! TF) = [];
B = reordercats (B, B.cats(index));
[TF, index] = ismember (newcats, B.cats);
index(! TF) = [];
## For each new category added before previously existing categories
## we need to increase the code indexing respectively
for i = 1:numel (TF)
if (! TF(i))
B.code(B.code >= i) += 1;
endif
endfor
B.cats = newcats(:);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} times (@var{A}, @var{B})
##
## Combine categorical arrays.
##
## @code{@var{C} = times (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} .* @var{B}} and returns a categorical array whose
## categories are the Cartesian product of the categories in @var{A} and
## @var{B} and each element is indexed to a new category which is the
## combination of the categories of the corresponding elements in @var{A}
## and @var{B}.
##
## @var{A} and @var{B} must be of common size or scalar categorical arrays.
##
## @end deftypefn
function C = times (A, B)
## Check input arguments
if (nargin < 2)
error ("categorical.times: too few input arguments.");
endif
if (! isa (A, 'categorical') || ! isa (B, 'categorical'))
error ("categorical.times: A and B must be categorical arrays.");
endif
newcats = {};
n_Bcats = numel (B.cats);
for i = 1:numel (A.cats)
for j = 1:n_Bcats
newcats = [newcats; strjoin({A.cats{i}, B.cats{j}})];
endfor
endfor
C = addcats (categorical, newcats);
C.code = A.code .* n_Bcats - (n_Bcats - B.code);
C.isMissing = A.isMissing | B.isMissing;
endfunction
endmethods
################################################################################
## ** Relational Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'eq' 'ge' 'gt' 'le' ##
## 'lt' 'ne' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} eq (@var{A}, @var{B})
##
## Equality for categorical arrays.
##
## @code{@var{TF} = eq (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} == @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} and @var{B} are equal and set
## to @qcode{false} where they are not. @var{A} and @var{B} must be size
## compatible, which translates to they can be the same size, one can be
## scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories. If neither are ordinal, the
## category names of each pair of elements are compared. Hence, they do
## not need to have the same set of categories.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for equality by comparing
## its category with that specified by the string argument.
##
## Undefined elements always return @qcode{false}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = eq (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.eq: any text representation must", ...
" specify a single categorical value."));
endif
TF = strcmp (B, cellstr (A));
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.eq: any text representation must", ...
" specify a single categorical value."));
endif
TF = strcmp (A, cellstr (B));
elseif (iscategorical (A) && iscategorical (B))
if (A.isOrdinal && B.isOrdinal)
## Check that both categorical arrays have the same categories
## and they are in the same order
cats = cellfun (@(x) categories (x), {A, B}, 'UniformOutput', false);
if (! isequal (cats{:}))
error (strcat ("categorical.eq: comparison between ordinal", ...
" arrays requires that both have the same", ...
" categories, which must be ordered in the", ...
" same way."));
endif
TF = double (A) == double (B);
elseif (A.isOrdinal || B.isOrdinal)
error (strcat ("categorical.eq: cannot compare a categorical", ...
" array that is ordinal with one that is not."));
else
[A, B, err] = csize_expand (A, B);
if (err)
error ("categorical.eq: arrays have incompatible sizes.");
endif
TF = strcmp (cellstr (A), cellstr (B));
endif
else
error (strcat ("categorical.eq: comparison is not defined between", ...
" '%s' and '%s' arrays."), class (A), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} ge (@var{A}, @var{B})
##
## Greater than or equal to for ordinal categorical arrays.
##
## @code{@var{TF} = ge (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} >= @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} are greater than or equal to
## @var{B} and set to @qcode{false} where they are not. @var{A} and @var{B}
## must be size compatible, which translates to they can be the same size,
## one can be scalar, or for every dimension, their dimension sizes must be
## equal or one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are both ordinal, they must
## have the same set and ordering of categories. Unordered categorical
## arrays cannot be compared for greater than or equal to inequality.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for greater than or equal to
## inequality by comparing its category with that specified by the string
## argument.
##
## Undefined elements always return @qcode{false}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = ge (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
if (! A.isOrdinal)
error ("categorical.ge: categorical array is not ordinal.");
endif
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.ge: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (A), B));
if (isempty (code))
error ("categorical.ge: category does not exist in array.");
endif
TF = double (A) >= code;
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
if (! B.isOrdinal)
error ("categorical.ge: categorical array is not ordinal.");
endif
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.ge: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (B), A));
if (isempty (code))
error ("categorical.ge: category does not exist in array.");
endif
TF = code >= double (B);
elseif (! iscategorical (A) || ! iscategorical (B))
error (strcat ("categorical.ge: relational comparison is not", ...
" defined between '%s' and '%s' arrays."), ...
class (A), class (B));
elseif (! A.isOrdinal || ! B.isOrdinal)
error (strcat ("categorical.ge: relational comparison is not", ...
" allowed between non-ordinal categorical arrays."));
else
TF = double (A) >= double (B);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} gt (@var{A}, @var{B})
##
## Greater than for ordinal categorical arrays.
##
## @code{@var{TF} = gt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} > @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} are greater than @var{B} and
## set to @qcode{false} where they are not. @var{A} and @var{B} must be
## size compatible, which translates to they can be the same size, one can
## be scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are both ordinal, they must
## have the same set and ordering of categories. Unordered categorical
## arrays cannot be compared for greater than inequality.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for greater than inequality
## by comparing its category with that specified by the string argument.
##
## Undefined elements always return @qcode{false}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = gt (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
if (! A.isOrdinal)
error ("categorical.gt: categorical array is not ordinal.");
endif
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.gt: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (A), B));
if (isempty (code))
error ("categorical.gt: category does not exist in array.");
endif
TF = double (A) > code;
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
if (! B.isOrdinal)
error ("categorical.gt: categorical array is not ordinal.");
endif
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.gt: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (B), A));
if (isempty (code))
error ("categorical.gt: category does not exist in array.");
endif
TF = code > double (B);
elseif (! iscategorical (A) || ! iscategorical (B))
error (strcat ("categorical.gt: relational comparison is not", ...
" defined between '%s' and '%s' arrays."), ...
class (A), class (B));
elseif (! A.isOrdinal || ! B.isOrdinal)
error (strcat ("categorical.gt: relational comparison is not", ...
" allowed between non-ordinal categorical arrays."));
else
TF = double (A) > double (B);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} le (@var{A}, @var{B})
##
## Less than or equal to for ordinal categorical arrays.
##
## @code{@var{TF} = le (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} <= @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} are less than or equal to
## @var{B} and set to @qcode{false} where they are not. @var{A} and @var{B}
## must be size compatible, which translates to they can be the same size,
## one can be scalar, or for every dimension, their dimension sizes must be
## equal or one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are both ordinal, they must
## have the same set and ordering of categories. Unordered categorical
## arrays cannot be compared for less than or equal to inequality.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for less than or equal to
## inequality by comparing its category with that specified by the string
## argument.
##
## Undefined elements always return @qcode{false}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = le (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
if (! A.isOrdinal)
error ("categorical.le: categorical array is not ordinal.");
endif
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.le: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (A), B));
if (isempty (code))
error ("categorical.le: category does not exist in array.");
endif
TF = double (A) <= code;
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
if (! B.isOrdinal)
error ("categorical.le: categorical array is not ordinal.");
endif
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.le: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (B), A));
if (isempty (code))
error ("categorical.le: category does not exist in array.");
endif
TF = code <= double (B);
elseif (! iscategorical (A) || ! iscategorical (B))
error (strcat ("categorical.le: relational comparison is not", ...
" defined between '%s' and '%s' arrays."), ...
class (A), class (B));
elseif (! A.isOrdinal || ! B.isOrdinal)
error (strcat ("categorical.le: relational comparison is not", ...
" allowed between non-ordinal categorical arrays."));
else
TF = double (A) <= double (B);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} lt (@var{A}, @var{B})
##
## Less than for ordinal categorical arrays.
##
## @code{@var{TF} = lt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} < @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} are less than @var{B} and
## set to @qcode{false} where they are not. @var{A} and @var{B} must be
## size compatible, which translates to they can be the same size, one can
## be scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are both ordinal, they must
## have the same set and ordering of categories. Unordered categorical
## arrays cannot be compared for less than inequality.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for less than inequality
## by comparing its category with that specified by the string argument.
##
## Undefined elements always return @qcode{false}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = lt (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
if (! A.isOrdinal)
error ("categorical.lt: categorical array is not ordinal.");
endif
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.lt: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (A), B));
if (isempty (code))
error ("categorical.lt: category does not exist in array.");
endif
TF = double (A) < code;
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
if (! B.isOrdinal)
error ("categorical.lt: categorical array is not ordinal.");
endif
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.lt: any text representation must", ...
" specify a single categorical value."));
endif
code = find (ismember (categories (B), A));
if (isempty (code))
error ("categorical.lt: category does not exist in array.");
endif
TF = code < double (B);
elseif (! iscategorical (A) || ! iscategorical (B))
error (strcat ("categorical.lt: relational comparison is not", ...
" defined between '%s' and '%s' arrays."), ...
class (A), class (B));
elseif (! A.isOrdinal || ! B.isOrdinal)
error (strcat ("categorical.lt: relational comparison is not", ...
" allowed between non-ordinal categorical arrays."));
else
TF = double (A) < double (B);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{TF} =} ne (@var{A}, @var{B})
##
## Not equal for categorical arrays.
##
## @code{@var{TF} = ne (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} != @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{true}
## where the corresponding elements of @var{A} and @var{B} are not equal and
## set to @qcode{false} where they are equal. @var{A} and @var{B} must be
## size compatible, which translates to they can be the same size, one can
## be scalar, or for every dimension, their dimension sizes must be equal or
## one of them must be 1.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories. If neither are ordinal, the
## category names of each pair of elements are compared. Hence, they do
## not need to have the same set of categories.
##
## One of the input arguments can also be a character vector, a cellstr
## scalar or a string scalar as long as the other is a categorical array.
## In this case, a logical array of the same size as the categorical array
## is returned in which every element is tested for inequality by comparing
## its category with that specified by the string argument.
##
## Undefined elements always return @qcode{true}, since they are not
## comparable to any other categorical values including other undefined
## elements.
##
## @end deftypefn
function TF = ne (A, B)
if (iscellstr (B) || isa (B, 'string') || ischar (B))
B = cellstr (B);
if (! isscalar (B))
error (strcat ("categorical.ne: any text representation must", ...
" specify a single categorical value."));
endif
TF = ! strcmp (B, cellstr (A));
elseif (iscellstr (A) || isa (A, 'string') || ischar (A))
A = cellstr (A);
if (! isscalar (A))
error (strcat ("categorical.ne: any text representation must", ...
" specify a single categorical value."));
endif
TF = ! strcmp (A, cellstr (B));
elseif (iscategorical (A) && iscategorical (B))
if (A.isOrdinal && B.isOrdinal)
## Check that both categorical arrays have the same categories
## and they are in the same order
cats = cellfun (@(x) categories (x), {A, B}, 'UniformOutput', false);
if (! isequal (cats{:}))
error (strcat ("categorical.ne: comparison between ordinal", ...
" arrays requires that both have the same", ...
" categories, which must be ordered in the", ...
" same way."));
endif
TF = double (A) != double (B);
elseif (A.isOrdinal || B.isOrdinal)
error (strcat ("categorical.ne: cannot compare a categorical", ...
" array that is ordinal with one that is not."));
else
[A, B, err] = csize_expand (A, B);
if (err)
error ("categorical.ne: arrays have incompatible sizes.");
endif
TF = ! strcmp (cellstr (A), cellstr (B));
endif
else
error (strcat ("categorical.ne: comparison is not defined between", ...
" '%s' and '%s' arrays."), class (A), class (B));
endif
endfunction
endmethods
################################################################################
## ** Arithmetic Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'min' 'max' 'median' 'mode' ##
## 'histcounts' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} min (@var{A})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} min (@var{A})
## @deftypefnx {categorical} {@var{C} =} min (@var{A}, @qcode{[]}, @var{dim})
## @deftypefnx {categorical} {@var{C} =} min (@var{A}, @qcode{[]}, @var{vecdim})
## @deftypefnx {categorical} {@var{C} =} min (@var{A}, @qcode{[]}, @qcode{'all'})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} min (@var{A}, @qcode{[]}, @qcode{'linear'})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} min (@var{A}, @qcode{[]}, @dots{}, @qcode{'linear'})
## @deftypefnx {categorical} {@var{C} =} min (@var{A}, @var{B})
## @deftypefnx {categorical} {[@dots{}] =} min (@dots{}, @var{missingflag})
##
## Smallest elements in ordinal categorical arrays.
##
## @code{@var{C} = min (@var{A})} returns the smallest element in ordinal
## categorical vector @var{A}. If @var{A} is a matrix, @code{min (@var{A})}
## returns a row vector with the smallest element from each column. For
## multidimensional arrays, @code{min (@var{A})} operates along the first
## non-singleton dimension.
##
## @code{[@var{C}, @var{index}] = min (@var{A})} also returns the indices of
## the minimum values in @var{index}, which has the same size as @var{C}.
## When the operating dimension contains more than one minimal elements, the
## index of the first one is returned.
##
## @code{@var{C} = min (@var{A}, @qcode{[]}, @var{dim})} operates along the
## dimension specified by @var{dim}.
##
## @code{@var{C} = min (@var{A}, @qcode{[]}, @var{vecdim})} operates on all
## the elements contained in the dimensions specified by @var{vecdim}, which
## must be a numeric vector of non-repeating positive integers. Any values
## in @var{vecdim} indexing dimensions larger that the actual array @var{A}
## are ignored.
##
## @code{@var{C} = min (@var{A}, @qcode{[]}, @qcode{'all'})} operates on all
## dimensions and returns the smallest element in @var{A}.
##
## @code{[@var{C}, @var{index}] = min (@var{A}, @qcode{[]}, @dots{})} also
## returns the first index of the minimum values in @var{index}. The second
## output is only valid when @code{min} operates on a single input array.
## Setting the @qcode{'linear'} flag returns the linear index to the
## corresponding minimum values in @var{A}.
##
## @code{@var{C} = min (@var{A}, @var{B})} returns an ordinal categorical
## array @var{C} with the smallest elements from @var{A} and @var{B}, which
## both must be ordinal categorical arrays of compatible sizes with the same
## set and ordering of categories. Compatible size means that @var{A} and
## @var{B} can be the same size, one can be scalar, or for every dimension,
## their dimension sizes must be equal or one of them must be 1.
##
## @code{[@dots{}] = min (@dots{}, @var{missingflag})} specifies how to
## handle undefined elements in any of the previous syntaxes.
## @var{missingflag} must be a character vector or a string scalar with one
## of the following values:
##
## @itemize
## @item @qcode{'omitundefined'}, which is the default, ignores all
## undefined elements and returns the minimum of the remaining elements.
## If all elements along the operating dimension are undefined, then it
## returns an undefined element. @qcode{'omitnan'} can also be used as
## equivalent to @qcode{'omitundefined'}.
## @item @qcode{'includeundefined'} returns an undefined element if there
## are any undefined elements along the operating dimension.
## @qcode{'includenan'} can also be used as equivalent to
## @qcode{'includeundefined'}.
## @end itemize
##
## @end deftypefn
function [C, index] = min (A, B = [], varargin)
## Check for ordinal categorical array
if (! A.isOrdinal)
error ("categorical.min: categorical array A is not ordinal.");
endif
if (numel (varargin) > 3)
error ("categorical.min: too many input arguments.");
endif
## Handle categorical specific missing flag
idx = strcmp ('omitundefined', varargin);
if (any (idx))
varargin(idx) = 'omitnan';
endif
idx = strcmp ('includeundefined', varargin);
if (any (idx))
varargin(idx) = 'includenan';
endif
## Create output array
C = A;
## Minimum of one array
if (isempty (B) && isa (B, 'double'))
A_d = double (A);
if (nargin == 1)
[C_d, index] = min (A_d);
else
[C_d, index] = min (A_d, [], varargin{:});
endif
## Fix missing codes
C.isMissing = isnan (C_d);
C.code = uint16 (C_d);
## Minimum of two arrays
else
## No second output allowed
if (nargout > 1)
error (strcat ("categorical.min: two output arguments are", ...
" not supported for two input arrays."));
endif
## Check for ordinal categorical array
if (! isa (B, 'categorical'))
error ("categorical.min: input array B must be categorical.");
endif
if (! B.isOrdinal)
error ("categorical.min: categorical array B must be ordinal.");
endif
## Check for same categories (including their order)
Acats = categories (A);
Bcats = categories (B);
if (! isequal (Acats, Bcats))
error (strcat ("categorical.min: categorical arrays must have", ...
" the same set of categories, including their", ...
" order."));
endif
## Process codes and missing values
A_d = double (A);
B_d = double (B);
C_d = min (A_d, B_d, varargin{:});
## Fix missing codes
C.isMissing = isnan (C_d);
C.code = uint16 (C_d);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} max (@var{A})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} max (@var{A})
## @deftypefnx {categorical} {@var{C} =} max (@var{A}, @qcode{[]}, @var{dim})
## @deftypefnx {categorical} {@var{C} =} max (@var{A}, @qcode{[]}, @var{vecdim})
## @deftypefnx {categorical} {@var{C} =} max (@var{A}, @qcode{[]}, @qcode{'all'})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} max (@var{A}, @qcode{[]}, @qcode{'linear'})
## @deftypefnx {categorical} {[@var{C}, @var{index}] =} max (@var{A}, @qcode{[]}, @dots{}, @qcode{'linear'})
## @deftypefnx {categorical} {@var{C} =} max (@var{A}, @var{B})
## @deftypefnx {categorical} {[@dots{}] =} max (@dots{}, @var{missingflag})
##
## Largest elements in ordinal categorical arrays.
##
## @code{@var{C} = max (@var{A})} returns the largest element in ordinal
## categorical vector @var{A}. If @var{A} is a matrix, @code{max (@var{A})}
## returns a row vector with the largest element from each column. For
## multidimensional arrays, @code{max (@var{A})} operates along the first
## non-singleton dimension.
##
## @code{[@var{C}, @var{index}] = max (@var{A})} also returns the indices of
## the maximum values in @var{index}, which has the same size as @var{C}.
## When the operating dimension contains more than one maximal elements, the
## index of the first one is returned.
##
## @code{@var{C} = max (@var{A}, @qcode{[]}, @var{dim})} operates along the
## dimension specified by @var{dim}.
##
## @code{@var{C} = max (@var{A}, @qcode{[]}, @var{vecdim})} operates on all
## the elements contained in the dimensions specified by @var{vecdim}, which
## must be a numeric vector of non-repeating positive integers. Any values
## in @var{vecdim} indexing dimensions larger that the actual array @var{A}
## are ignored.
##
## @code{@var{C} = max (@var{A}, @qcode{[]}, @qcode{'all'})} operates on all
## dimensions and returns the largest element in @var{A}.
##
## @code{[@var{C}, @var{index}] = max (@var{A}, @qcode{[]}, @dots{})} also
## returns the first index of the maximum values in @var{index}. The second
## output is only valid when @code{max} operates on a single input array.
## Setting the @qcode{'linear'} flag returns the linear index to the
## corresponding maximum values in @var{A}.
##
## @code{@var{C} = max (@var{A}, @var{B})} returns an ordinal categorical
## array @var{C} with the largest elements from @var{A} and @var{B}, which
## both must be ordinal categorical arrays of compatible sizes with the same
## set and ordering of categories. Compatible size means that @var{A} and
## @var{B} can be the same size, one can be scalar, or for every dimension,
## their dimension sizes must be equal or one of them must be 1.
##
## @code{[@dots{}] = max (@dots{}, @var{missingflag})} specifies how to
## handle undefined elements in any of the previous syntaxes.
## @var{missingflag} must be a character vector or a string scalar with one
## of the following values:
##
## @itemize
## @item @qcode{'omitundefined'}, which is the default, ignores all
## undefined elements and returns the maximum of the remaining elements. If
## all elements along the operating dimension are undefined, then it returns
## an undefined element. @qcode{'omitnan'} may also be used as equivalent
## to @qcode{'omitundefined'}.
## @item @qcode{'includeundefined'} returns an undefined element if there
## any undefined elements along the operating dimension.
## @qcode{'includenan'} may also be used as equivalent to
## @qcode{'includeundefined'}.
## @end itemize
##
## @end deftypefn
function [C, index] = max (A, B = [], varargin)
## Check for ordinal categorical array
if (! A.isOrdinal)
error ("categorical.max: categorical array A is not ordinal.");
endif
if (numel (varargin) > 3)
error ("categorical.max: too many input arguments.");
endif
## Handle categorical specific missing flag
idx = strcmp ('omitundefined', varargin);
if (any (idx))
varargin(idx) = 'omitnan';
endif
idx = strcmp ('includeundefined', varargin);
if (any (idx))
varargin(idx) = 'includenan';
endif
## Create output array
C = A;
## Minimum of one array
if (isempty (B) && isa (B, 'double'))
A_d = double (A);
if (nargin == 1)
[C_d, index] = max (A_d);
else
[C_d, index] = max (A_d, [], varargin{:});
endif
## Fix missing codes
C.isMissing = isnan (C_d);
C.code = uint16 (C_d);
## Minimum of two arrays
else
## No second output allowed
if (nargout > 1)
error (strcat ("categorical.max: two output arguments are", ...
" not supported for two input arrays."));
endif
## Check for ordinal categorical array
if (! isa (B, 'categorical'))
error ("categorical.max: input array B must be categorical.");
endif
if (! B.isOrdinal)
error ("categorical.max: categorical array B must be ordinal.");
endif
## Check for same categories (including their order)
Acats = categories (A);
Bcats = categories (B);
if (! isequal (Acats, Bcats))
error (strcat ("categorical.max: categorical arrays must have", ...
" the same set of categories, including their", ...
" order."));
endif
## Process codes and missing values
A_d = double (A);
B_d = double (B);
C_d = max (A_d, B_d, varargin{:});
## Fix missing codes
C.isMissing = isnan (C_d);
C.code = uint16 (C_d);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} median (@var{A})
## @deftypefnx {categorical} {@var{B} =} median (@var{A}, @var{dim})
## @deftypefnx {categorical} {@var{B} =} median (@var{A}, @var{vecdim})
## @deftypefnx {categorical} {@var{B} =} median (@var{A}, @qcode{'all'})
## @deftypefnx {categorical} {@var{B} =} median (@dots{}, @var{missingflag})
##
## Median value of an ordinal categorical array.
##
## @code{@var{B} = median (@var{A})} returns the median of the elements in
## ordinal categorical vector @var{A}. If @var{A} is a matrix,
## @code{median (@var{A})} returns a row vector with the median element
## from each column. For multidimensional arrays, @code{median (@var{A})}
## operates along the first non-singleton dimension. @var{B} is also
## ordinal with the same ordered categories as @var{A}. For even number of
## elements along the operating dimension, the returned median value is
## either the midway category between the two middle elements or the larger
## of the two categories midway between the two middle elements.
##
## @code{@var{B} = median (@var{A}, @var{dim})} operates along the dimension
## specified by @var{dim}.
##
## @code{@var{B} = median (@var{A}, @var{vecdim})} operates on all the
## elements contained in the dimensions specified by @var{vecdim}, which
## must be a numeric vector of non-repeating positive integers. Any values
## in @var{vecdim} indexing dimensions larger that the actual array @var{A}
## are ignored.
##
## @code{@var{C} = median (@var{A}, @qcode{[]}, @qcode{'all'})} operates on
## all dimensions and returns the median element in @var{A}.
##
## @code{@var{C} = median (@dots{}, @var{missingflag})} specifies how to
## handle undefined elements in any of the previous syntaxes.
## @var{missingflag} must be a character vector or a string scalar with one
## of the following values:
##
## @itemize
## @item @qcode{'omitundefined'} ignores all undefined elements and returns
## the median of the remaining elements. If all elements along the
## operating dimension are undefined, then it returns an undefined element.
## @qcode{'omitnan'} may also be used as equivalent to
## @qcode{'omitundefined'}.
## @item @qcode{'includeundefined'}, which is the default, returns an
## undefined element if there any undefined elements along the operating
## dimension. @qcode{'includenan'} may also be used as equivalent to
## @qcode{'includeundefined'}.
## @end itemize
##
## @end deftypefn
function B = median (A, varargin)
## Check for ordinal categorical array
if (! A.isOrdinal)
error ("categorical.median: categorical array A is not ordinal.");
endif
if (numel (varargin) > 2)
error ("categorical.median: too many input arguments.");
endif
## Handle categorical specific missing flag
idx = strcmp ('omitundefined', varargin);
if (any (idx))
varargin(idx) = 'omitnan';
endif
idx = strcmp ('includeundefined', varargin);
if (any (idx))
varargin(idx) = 'includenan';
endif
## Compute median
B_d = median (double (A), varargin{:});
## Save median to output array
B = A;
B.isMissing = isnan (B_d);
B.code = uint16 (round (B_d));
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{M} =} mode (@var{A})
## @deftypefnx {categorical} {[@var{M}, @var{F}] =} mode (@var{A})
## @deftypefnx {categorical} {[@var{M}, @var{F}, @var{C}] =} mode (@var{A})
## @deftypefnx {categorical} {[@dots{}] =} mode (@var{A}, @var{dim})
## @deftypefnx {categorical} {[@dots{}] =} mode (@var{A}, @var{vecdim})
## @deftypefnx {categorical} {[@dots{}] =} mode (@var{A}, @qcode{'all'})
##
## Most frequent element in a categorical array.
##
## @code{@var{M} = mode (@var{A})} returns the most frequent element in the
## categorical vector @var{A}. If @var{A} is a matrix,
## @code{mode (@var{A})} returns a row vector with the most frequent element
## from each column. For multidimensional arrays, @code{mode (@var{A})}
## operates along the first non-singleton dimension. @var{B} is also a
## categorical array with the same categories as @var{A}. For multiple
## elements with the same maximum frequency along the operating dimension,
## the element from the category that occurs first in @var{A} is returned.
##
## @code{[@var{M}, @var{F}] = mode (@var{A})} also returns a numeric array
## @var{F}, which has the same size as @var{M} and it contains the number of
## occurrences of each corresponding element of @var{M}.
##
## @code{[@var{M}, @var{F}, @var{C}] = mode (@var{A})} also returns a cell
## array @var{C}, which has the same size as @var{M} and each element is a
## sorted categorical vector of all the values with the same maximum
## frequency of the corresponding element of @var{M}.
##
## @code{@var{B} = mode (@var{A}, @var{dim})} operates along the dimension
## specified by @var{dim}.
##
## @code{@var{B} = mode (@var{A}, @var{vecdim})} operates on all the
## elements contained in the dimensions specified by @var{vecdim}, which
## must be a numeric vector of non-repeating positive integers. Any values
## in @var{vecdim} indexing dimensions larger that the actual array @var{A}
## are ignored.
##
## @code{@var{C} = mode (@var{A}, @qcode{[]}, @qcode{'all'})} operates on
## all dimensions and returns the most frequent element in @var{A}.
##
## @end deftypefn
function [M, F, C] = mode (A, dim = [])
## Handle 'all' option first
if (strcmpi (dim, 'all'))
A = subset (A, ':');
dim = [];
endif
## Simple case, only one input argument (or 'all' flag used)
if (isempty (dim))
[m, F, c] = mode (double (A));
M = A;
M.code = uint16 (m);
M.isMissing = isnan (m);
C = cell (size (c));
for i = 1:numel (c)
tmp = A;
tmp.code = uint16 (c{i});
tmp.isMissing = isnan (c{i});
C(i) = tmp;
endfor
## Second input argument is either DIM or VECDIM
else
[m, F, c] = mode (double (A), dim);
M = A;
M.code = uint16 (m);
M.isMissing = isnan (m);
C = cell (size (c));
for i = 1:numel (c)
tmp = A;
tmp.code = uint16 (c{i});
tmp.isMissing = isnan (c{i});
C(i) = tmp;
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{N} =} histcounts (@var{A})
## @deftypefnx {categorical} {@var{N} =} histcounts (@var{A}, @var{cats})
## @deftypefnx {categorical} {@var{N} =} histcounts (@dots{}, @qcode{'Normalization'}, @var{normtype})
## @deftypefnx {categorical} {[@var{N}, @var{cats}] =} histcounts (@dots{})
##
## Histogram bin counts of a categorical array.
##
## @code{@var{N} = histcounts (@var{A})} returns a numeric vector @var{N}
## with the number of elements of each category in @var{A}. @var{A} can be
## a categorical array of any dimensions, but it is converted internally to
## a single column vector.
##
## @code{@var{N} = histcounts (@var{A}, @var{cats})} returns the number of
## elements only for the categories of @var{A} specified in @var{cats},
## which may be a categorical array, a string array, or a cell array of
## character vectors, as long as it specifies unique existing categories in
## @var{A}.
##
## @code{@var{N} = histcounts (@dots{}, @qcode{'Normalization'},
## @var{normtype})} specifies how to normalize the histogram values returned
## in @var{N} with any of the following options specified in @var{normtype}:
##
## @itemize
## @item @qcode{'count'}, which is the default, returns the number of
## elements in each category.
## @item @qcode{'countdensity'} is the same as @qcode{'count'}, since the
## bin width in categorical arrays is always equal to 1.
## @item @qcode{'probability'} returns the number of elements in each
## category relative to the total number of elements in @var{A}.
## @item @qcode{'pdf'} is the same as @qcode{'probability'}, since the bin
## width in categorical arrays is always equal to 1.
## @item @qcode{'cumcount'} returns the cumulative number of elements in
## each category and all previous categories.
## @item @qcode{'cdf'} returns the cumulative number of elements in
## each category and all previous categories relative to the total number of
## elements in @var{A}.
## @end itemize
##
## @code{[@var{N}, @var{cats}] = histcounts (@dots{})} also returns the
## corresponding categories of @var{A} for each count in @var{N}.
## @var{cats} is a cell array of character vectors with the same size as
## @var{N}.
##
## @end deftypefn
function [N, cats] = histcounts (A, varargin)
## Parse and validate optional Name-Value paired argument
optNames = {'Normalization'};
dfValues = {'count'};
[normtype, args] = parsePairedArguments (optNames, dfValues, varargin(:));
vnt = {'count', 'countdensity', 'probability', 'pdf', 'cumcount', 'cdf'};
if (! ismember (normtype, vnt))
error ("categorical.histcounts: invalid 'Normalization' type.");
endif
## Check for selected categories
if (! isempty (args))
cats = args{1};
if (isa (cats, 'categorical'))
cats = categories (cats);
elseif (isa (cats, 'string'))
cats = cellstr (cats);
elseif (! iscellstr (cats))
error (strcat ("categorical.histcounts: invalid", ...
" type for CATS input argument."));
endif
if (! all (ismember (cats, A.cats)))
error (strcat ("categorical.histcounts: input argument", ...
" CATS references non-existing categories in A."));
endif
else
cats = A.cats;
endif
## Force cats to row vector
cats = cats(:)';
## Count elements in selected categories
codes = A.code(:);
ccats = find (ismember (A.cats, cats));
ncats = numel (ccats);
N = zeros (1, ncats);
for i = 1:ncats
N(i) = sum (codes == ccats(i));
endfor
## Apply normalization scheme
if (any (strcmp (normtype, {'probability', 'pdf'})))
N = N ./ numel (codes);
elseif (strcmp (normtype, 'cumcount'))
N = cumsum (N);
elseif (strcmp (normtype, 'cdf'))
N = cumsum (N ./ numel (codes));
endif
endfunction
endmethods
################################################################################
## ** Sort, Filter, and Set Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'sort' 'sortrows' 'topkrows' 'unique' ##
## 'intersect' 'setdiff' 'setxor' 'union' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} sort (@var{A})
## @deftypefnx {categorical} {@var{B} =} sort (@var{A}, @var{dim})
## @deftypefnx {categorical} {@var{B} =} sort (@var{A}, @var{direction})
## @deftypefnx {categorical} {@var{B} =} sort (@var{A}, @var{dim}, @var{direction})
## @deftypefnx {categorical} {@var{B} =} sort (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {categorical} {[@var{B}, @var{index}] =} sort (@var{A}, @dots{})
##
## Sort elements in a categorical array.
##
## @code{@var{B} = sort (@var{A})} sorts the categorical array @var{A} in
## ascending order. The sorted array @var{B} has the same categories as
## @var{A}. If @var{A} is a matrix, @code{sort (@var{A})} sorts each column
## of @var{A} in ascending order. For multidimensional arrays,
## @code{mode (@var{A})} sorts along the first non-singleton dimension.
##
## @code{@var{B} = sort (@var{A}, @var{dim})} sorts along the dimension
## specified by @var{dim}.
##
## @code{@var{B} = sort (@var{A}, @var{direction})} also specifies the
## sorting direction, which can be either @qcode{'ascend'} (default) or
## @qcode{'descend'}.
##
## @code{@var{B} = sort (@dots{}, @qcode{'MissingPlacement'}, @var{MP})}
## specifies where to place the missing elements (@qcode{})
## returned in @var{B} with any of the following options specified in
## @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{[@var{B}, @var{index}] = sort (@var{A}, @dots{})} also returns a
## sorting index containing the original indices of the elements in the
## sorted array.
##
## @itemize
## @item If @var{A} is a vector, then @var{index} contains the original
## linear indices of the elements in the sorted vector @var{B} such that
## @code{@var{B} = @var{A}(@var{index})}.
## @item If @var{A} is an @math{M*N} matrix and @qcode{@var{dim} = 1}, then
## @var{index} contains the original row indices of the elements in the
## sorted vector @var{B} such that for @qcode{j = 1:N},
## @code{@var{B}(:,j) = @var{A}(@var{index}(:,j),j)}.
## @end itemize
##
## @end deftypefn
function [B, index] = sort (A, varargin)
## Parse and validate optional 'MissingPlacement' paired argument
optNames = {'MissingPlacement'};
dfValues = {'auto'};
[MP, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! ismember (MP, {'auto', 'first', 'last'}))
error ("categorical.sort: invalid value for 'MissingPlacement'.");
endif
## Force strings to character vectors
[args{:}] = convertStringsToChars (args{:});
## Get direction
cid = cellfun (@ischar, args);
if (any (cid))
dir = args{cid};
else
dir = 'ascend';
endif
## Since codes are positive integers and 0 is used for undefined elements,
## we assume A.code == 0 for NaN. However, in ascending order NaNs go to
## the end, while 0s at the very top and vice versa. So we have to
## mitigate this in tandem with the 'MissingPlacement' option, by setting
## 0s to max(code) + 1 for certain combinations of options.
code = A.code;
is_nan = code == 0;
if (any (is_nan(:)))
if ((strcmp (dir, 'ascend') && any (strcmp (MP, {'auto', 'last'}))) ||
(strcmp (dir, 'descend') && any (strcmp (MP, {'auto', 'first'}))))
## Get new value for missing elements code
nan_code = max (code(:)) + 1;
code(is_nan) = nan_code;
## Sort values
[code, index] = sort (code, args{:});
## Get indices of missing values and change them back to 0
is_nan = code == nan_code;
code(is_nan) = 0;
else
## ## Sort values without swaping code for undefined elements
[code, index] = sort (code, args{:});
is_nan = code == 0;
endif
else
## Sort values with no undefined elements
[code, index] = sort (code, args{:});
endif
## Populate output categorical array
B = A;
B.code = uint16 (code);
B.isMissing = is_nan;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} sortrows (@var{A})
## @deftypefnx {categorical} {@var{B} =} sortrows (@var{A}, @var{col})
## @deftypefnx {categorical} {@var{B} =} sortrows (@var{A}, @var{direction})
## @deftypefnx {categorical} {@var{B} =} sortrows (@var{A}, @var{col}, @var{direction})
## @deftypefnx {categorical} {@var{B} =} sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {categorical} {[@var{B}, @var{index}] =} sortrows (@var{A}, @dots{})
##
## Sort rows in a categorical array.
##
## @code{@var{B} = sortrows (@var{A})} sorts the rows of the 2-D categorical
## array @var{A} in ascending order. The sorted array @var{B} has the same
## categories as @var{A}.
##
## @code{@var{B} = sortrows (@var{A}, @var{col})} sorts @var{A} according to
## to the columns specified by the numeric vector @var{col}, which must
## explicitly contain non-zero integers whose absolute values index existing
## columns in @var{A}. Positive elements sort the corresponding columns in
## ascending order, while negative elements sort the corresponding columns
## in descending order.
##
## @code{@var{B} = sortrows (@var{A}, @var{direction})} also specifies the
## sorting direction, which can be either @qcode{'ascend'} (default) or
## @qcode{'descend'} applying to all columns in @var{A}. Alternatively,
## @var{direction} can be a cell array of character vectors specifying
## the sorting direction for each individual column of @var{A}, in which
## case the number of elements in @var{direction} must equal the number of
## columns in @var{A}.
##
## @code{@var{B} = sortrows (@var{A}, @var{col}, @var{direction})} sorts the
## categorical array @var{A} according to the columns specified in @var{col}
## using the corresponding sorting direction specified in @var{direction}.
## In this case, the sign of the values in @var{col} is ignored. @var{col}
## and @var{direction} must have the same length, but not necessarily the
## same number of elements as the columns in @var{A}.
##
## @code{@var{B} = sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})}
## specifies where to place the missing elements (@qcode{})
## returned in @var{B} with any of the following options specified in
## @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{[@var{B}, @var{index}] = sortrows (@var{A}, @dots{})} also returns
## an index vector containing the original row indices of @var{A} in the
## sorted matrix @var{B} such that @code{@var{B} = @var{A}(@var{index},:)}.
##
## @end deftypefn
function [B, index] = sortrows (A, varargin)
if (ndims (A) != 2)
error ("categorical.sortrows: A must be a 2-D matrix.");
endif
## Parse and validate optional 'MissingPlacement' paired argument
optNames = {'MissingPlacement'};
dfValues = {'auto'};
[MP, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! any (strcmp (MP, {'auto', 'first', 'last'})))
error ("categorical.sort: invalid value for 'MissingPlacement'.");
endif
## Parse COL / DIRECTION input
nc = size (A, 2);
col = [1:nc]; # default ascending direction
dir_flag = false;
if (numel (args) > 2)
error ("categorical.sortrows: too many input arguments.");
endif
if (numel (args) > 0)
col = args{1};
if (isnumeric (col))
if (! isvector (col) || fix (col) != col)
error (strcat ("categorical.sortrows: COL must be a vector", ...
" of nonzero integers indexing columns in A."));
endif
if (max (abs (col)) > nc)
error ("categorical.sortrows: COL indexes non-existing column.");
endif
elseif (isvector (col) && (ischar (col) || iscellstr (col) ||
isa (col, 'string')))
direction = cellstr (col);
if (! all (ismember (direction, {'ascend', 'descend'})))
error (strcat ("categorical.sortrows: DIRECTION input must", ...
" contain either 'ascend' or 'descend' values."));
endif
## Apply scalar expansion
if (isscalar (direction))
direction = repmat (direction, 1, nc);
endif
if (numel (direction) != nc)
error (strcat ("categorical.sortrows: DIRECTION", ...
" does not match the columns in A."));
endif
## Assign DIRECTION to COL
col = [1:nc];
idx = strcmp (direction, 'descend');
col(idx) = - col(idx);
dir_flag = true;
else
error ("categorical.sortrows: invalid type for COL argument.");
endif
endif
if (numel (args) > 1)
if (dir_flag)
error ("categorical.sortrows: invalid third input argument.");
endif
if ((isvector (args{2}) && ischar (args{2})) || isa (args{2}, 'string'))
direction = cellstr (args{2});
elseif (isvector (args{2}) && iscellstr (args{2}))
direction = args{2};
else
error ("categorical.sortrows: invalid type for DIRECTION argument.");
endif
if (! all (ismember (direction, {'ascend', 'descend'})))
error (strcat ("categorical.sortrows: DIRECTION input must", ...
" contain either 'ascend' or 'descend' values."));
endif
## Assign DIRECTION to COL
if (isscalar (direction) && strcmp (direction, 'ascend'))
col = abs (col);
elseif (isscalar (direction) && strcmp (direction, 'descend'))
col = - abs (col);
else
if (numel (direction) != numel (col))
error (strcat ("categorical.sortrows: DIRECTION", ...
" does not match the elements in COL."));
endif
col = abs (col);
idx = strcmp (direction, 'descend');
col(idx) = - col(idx);
endif
endif
## Since codes are positive integers and 0 is used for undefined elements,
## we assume A.code == 0 for NaN. However, in ascending order NaNs go to
## the end, while 0s at the very top and vice versa. So we have to
## mitigate this in tandem with the 'MissingPlacement' option, by setting
## 0s to max(code) + 1 for certain combinations of options.
code = A.code;
is_nan = code == 0;
if (any (is_nan(:)))
## Get new value for missing elements code
nan_code = max (code(:)) + 1;
asc_cols = [];
des_cols = [];
if (any (strcmp (MP, {'auto', 'last'})))
## Change codes only in ascending columns
asc_cols = col(col > 0);
if (! isempty (asc_cols))
asc_code = code(:, asc_cols);
a_is_nan = asc_code == 0;
asc_code(a_is_nan) = nan_code;
code(:, asc_cols) = asc_code;
endif
endif
if (any (strcmp (MP, {'auto', 'first'})))
## Change codes only in descending columns
des_cols = abs (col(col < 0));
if (! isempty (des_cols))
des_code = code(:, des_cols);
d_is_nan = des_code == 0;
des_code(d_is_nan) = nan_code;
code(:, des_cols) = des_code;
endif
endif
## Sort values
[code, index] = sortrows (code, col);
## Get indices of missing values and change them back to 0
adcols = [asc_cols, des_cols];
if (! isempty (adcols))
adcode = code(:, [asc_cols, des_cols]);
is_nan = adcode == nan_code;
adcode(is_nan) = 0;
code(:, [asc_cols, des_cols]) = adcode;
endif
## Re-index missing values after sorting
is_nan = code == 0;
else
## Sort values with no undefined elements
[code, index] = sortrows (code, col);
endif
## Populate output categorical array
B = A;
B.code = uint16 (code);
B.isMissing = is_nan;
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} topkrows (@var{A}, @var{K})
## @deftypefnx {categorical} {@var{B} =} topkrows (@var{A}, @var{K}, @var{col})
## @deftypefnx {categorical} {@var{B} =} topkrows (@var{A}, @var{K}, @var{direction})
## @deftypefnx {categorical} {@var{B} =} topkrows (@var{A}, @var{K}, @var{col}, @var{direction})
##
## Top K sorted rows of categorical array.
##
## @code{@var{B} = topkrows (@var{A}, @var{K})} returns the top @var{K} rows
## of the 2-D categorical array @var{A} sorted in descending order as a
## group.
##
## @code{@var{B} = topkrows (@var{A}, @var{K}, @var{col})} returns the top
## @var{K} rows of the 2-D categorical array @var{A} sorted according to the
## columns specified by the numeric vector @var{col}, which must explicitly
## contain non-zero integers whose absolute values index existing columns in
## @var{A}. Positive elements sort the corresponding columns in ascending
## order, while negative elements sort the corresponding columns in
## descending order.
##
## @code{@var{B} = topkrows (@var{A}, @var{K}, @var{direction})} returns the
## top @var{K} rows of the 2-D categorical array @var{A} sorted according to
## @var{direction}, which can be either @qcode{'ascend'} (default) or
## @qcode{'descend'} applying to all columns in @var{A}. Alternatively,
## @var{direction} can be a cell array of character vectors specifying
## the sorting direction for each individual column of @var{A}, in which
## case the number of elements in @var{direction} must equal the number of
## columns in @var{A}.
##
## @code{@var{B} = topkrows (@var{A}, @var{K}, @var{col}, @var{direction})}
## returns the top @var{K} rows of the 2-D categorical array @var{A} sorted
## according to the columns specified in @var{col} using the corresponding
## sorting direction specified in @var{direction}. In this case, the sign
## of the values in @var{col} is ignored. @var{col} and @var{direction}
## must have the same length, but not necessarily the same number of
## elements as the columns in @var{A}.
##
## @end deftypefn
function [B, index] = topkrows (A, K, varargin)
## Check input argument
if (nargin < 2)
error ("categorical.topkrows: too few input arguments.");
endif
if (! (isscalar (K) && fix (K) == K && K > 0))
error ("categorical.topkrows: K must be a positive integer scalar.");
endif
## Sort rows
if (numel (varargin) == 0)
[B, index] = sortrows (A, 'descend');
else
[B, index] = sortrows (A, varargin{:});
endif
## Return top K rows
if (K < numel (index))
B = subset (B, 1:K, ':');
index = index(1:K);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} unique (@var{A})
## @deftypefnx {categorical} {@var{B} =} unique (@var{A}, @var{setOrder})
## @deftypefnx {categorical} {@var{B} =} unique (@var{A}, @var{occurrence})
## @deftypefnx {categorical} {@var{B} =} unique (@var{A}, @var{setOrder}, @var{occurrence})
## @deftypefnx {categorical} {@var{B} =} unique (@var{A}, @var{occurrence}, @var{setOrder})
## @deftypefnx {categorical} {@var{B} =} unique (@var{A}, @dots{}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{B}, @var{ixA}, @var{ixB}] =} unique (@dots{})
##
## Unique values in a categorical array.
##
## @code{@var{B} = unique (@var{A})} returns the unique values of the
## categorical array @var{A} in the categorical vector @var{B} sorted
## according to the order of categories in @var{A}. @var{B} retains the
## same categories as @var{A}. If @var{A} is a row vector, then @var{B}
## is also a row vector, otherwise @code{unique} returns a column vector.
##
## @code{@var{B} = unique (@var{A}, @var{setOrder})} returns the unique
## values of the categorical array @var{A} in an order as specified by
## @var{setOrder}, which can be either of the following values:
##
## @itemize
## @item @qcode{'sorted'} (default) returns the unique values sorted in
## ascending order.
## @item @qcode{'stable'} returns the unique values according to their order
## of occurrence.
## @end itemize
##
## @code{@var{B} = unique (@var{A}, @var{occurrence})} returns the unique
## values of the categorical array @var{A} according to their order of
## occurrence. @var{occurrence} can be either of the following values:
##
## @itemize
## @item @qcode{'first'} (default) returns the first occurrence of each
## unique value, i.e. the lowest possible indices are returned.
## @item @qcode{'last'} returns the last occurrence of each unique value,
## i.e. the highest possible indices are returned.
## @end itemize
##
## You can specify @var{setOrder} and @var{occurrence} arguments together.
##
## @code{@var{B} = unique (@var{A}, @dots{}, @qcode{'rows'})} returns the
## unique rows of @var{A} by treating each row as a single entity. The
## @qcode{'rows'} option can be used alone or in any combination with the
## @var{setOrder} and @var{occurrence} arguments. @qcode{'rows'} can be
## placed at any position in the function's argument list after the input
## array @var{A}. However, this syntax is only valid for 2-dimensional
## categorical arrays.
##
## @code{[@var{B}, @var{ixA}, @var{ixB}] = unique (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} using any of the previous syntaxes.
## @var{ixA} and @var{ixB} map the arrays @var{A} and @var{B} to one another
## such that @qcode{@var{B} = @var{A}(@var{ixA})} and
## @qcode{@var{A} = @var{B}(@var{ixB})}. When the @qcode{'rows'} optional
## argument is specified, then @qcode{@var{B} = @var{A}(@var{ixA},:)} and
## @qcode{@var{A} = @var{B}(@var{ixB},:)}.
##
## @end deftypefn
function [B, ixA, ixB] = unique (A, varargin)
## 'legacy' option is not supported
if (any (strcmp ('legacy', varargin)))
error ("duration.unique: 'legacy' option is not supported.");
endif
code = double (A);
[~, ixA, ixB] = __unique__ (code, varargin{:});
if (any (strcmp ('rows', varargin)))
B = subset (A, ixA, ':');
else
B = subset (A, ixA);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} intersect (@var{A}, @var{B})
## @deftypefnx {categorical} {@var{C} =} intersect (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{C}, @var{ixA}, @var{ixB}] =} intersect (@dots{})
## @deftypefnx {categorical} {@dots{} =} intersect (@dots{}, @var{order})
##
## Set intersection of two categorical arrays.
##
## @code{@var{C} = intersect (@var{A}, @var{B})} returns the unique common
## values of the categorical arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments may be a character vector, a string array, or a
## cell array of character vectors, which is promoted to a categorical array
## prior to set intersection. If both @var{A} and @var{B} are row vectors,
## then @var{C} is also a row vector, otherwise @code{intersect} returns a
## column vector.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories, which is transfered to @var{C}.
## If neither are ordinal, the category names of each pair of elements are
## compared (they do not need to have the same set of categories) in which
## case the categories in @var{C} are the sorted union of the categories in
## @var{A} and @var{B}.
##
## @code{@var{C} = intersect (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the categorical matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## categorical matrix @var{C} are in sorted order.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = intersect (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @code{@dots{} = intersect (@dots{}, @var{order})} also specifies the
## order of the returned unique values. @var{order} may be either
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'},
## in which case the unique values are returned in order of appearance.
##
## @end deftypefn
function [C, ixA, ixB] = intersect (A, B, varargin)
[C, ixA, ixB] = setop (A, B, 'intersect', varargin{:});
if (! iscategorical (C))
error (C);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} setdiff (@var{A}, @var{B})
## @deftypefnx {categorical} {@var{C} =} setdiff (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{C}, @var{ixA}] =} setdiff (@dots{})
## @deftypefnx {categorical} {@dots{} =} setdiff (@dots{}, @var{order})
##
## Set difference of two categorical arrays.
##
## @code{@var{C} = setdiff (@var{A}, @var{B})} returns the unique common
## values of the categorical arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments may be a character vector, a string array, or a
## cell array of character vectors, which is promoted to a categorical array
## prior to set difference. If both @var{A} and @var{B} are row vectors,
## then @var{C} is also a row vector, otherwise @code{intersect} returns a
## column vector.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories, which is transfered to @var{C}.
## If neither are ordinal, the category names of each pair of elements are
## compared (they do not need to have the same set of categories) in which
## case the categories in @var{C} are the sorted union of the categories in
## @var{A} and @var{B}.
##
## @code{@var{C} = setdiff (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the categorical matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## categorical matrix @var{C} are in sorted order.
##
## @code{[@var{C}, @var{ixA}] = setdiff (@dots{})} also returns the index
## vector @var{ixA} such that @code{@var{C} = @var{A}(@var{ixA})}, unless
## the @qcode{'rows'} optional argument is given, in which case
## @code{@var{C} = @var{A}(@var{ixA},:)}.
##
## @code{@dots{} = setdiff (@dots{}, @var{order})} also specifies the
## order of the returned unique values. @var{order} may be either
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'},
## in which case the unique values are returned in order of appearance.
##
## @end deftypefn
function [C, ixA] = setdiff (A, B, varargin)
[C, ixA] = setop (A, B, 'setdiff', varargin{:});
if (! iscategorical (C))
error (C);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} setxor (@var{A}, @var{B})
## @deftypefnx {categorical} {@var{C} =} setxor (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{C}, @var{ixA}, @var{ixB}] =} setxor (@dots{})
## @deftypefnx {categorical} {@dots{} =} setxor (@dots{}, @var{order})
##
## Set exclusive-or of two categorical arrays.
##
## @code{@var{C} = setxor (@var{A}, @var{B})} returns the unique common
## values of the categorical arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments may be a character vector, a string array, or a
## cell array of character vectors, which is promoted to a categorical array
## prior to set exclusive-or. If both @var{A} and @var{B} are row vectors,
## then @var{C} is also a row vector, otherwise @code{setxor} returns a
## column vector.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories, which is transfered to @var{C}.
## If neither are ordinal, the category names of each pair of elements are
## compared (they do not need to have the same set of categories) in which
## case the categories in @var{C} are the sorted union of the categories in
## @var{A} and @var{B}.
##
## @code{@var{C} = setxor (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the categorical matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## categorical matrix @var{C} are in sorted order.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = setxor (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @code{@dots{} = setxor (@dots{}, @var{order})} also specifies the
## order of the returned unique values. @var{order} may be either
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'},
## in which case the unique values are returned in order of appearance.
##
## @end deftypefn
function [C, ixA, ixB] = setxor (A, B, varargin)
[C, ixA, ixB] = setop (A, B, 'setxor', varargin{:});
if (! iscategorical (C))
error (C);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} union (@var{A}, @var{B})
## @deftypefnx {categorical} {@var{C} =} union (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {categorical} {[@var{C}, @var{ixA}, @var{ixB}] =} union (@dots{})
## @deftypefnx {categorical} {@dots{} =} union (@dots{}, @var{order})
##
## Set union of two categorical arrays.
##
## @code{@var{C} = union (@var{A}, @var{B})} returns the unique common
## values of the categorical arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments may be a character vector, a string array, or a
## cell array of character vectors, which is promoted to a categorical array
## prior to set exclusive-or. If both @var{A} and @var{B} are row vectors,
## then @var{C} is also a row vector, otherwise @code{union} returns a
## column vector.
##
## If categorical arrays @var{A} and @var{B} are ordinal, they must have
## the same set and ordering of categories, which is transfered to @var{C}.
## If neither are ordinal, the category names of each pair of elements are
## compared (they do not need to have the same set of categories) in which
## case the categories in @var{C} are the sorted union of the categories in
## @var{A} and @var{B}.
##
## @code{@var{C} = union (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the categorical matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## categorical matrix @var{C} are in sorted order.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = union (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @code{@dots{} = union (@dots{}, @var{order})} also specifies the
## order of the returned unique values. @var{order} may be either
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'},
## in which case the unique values are returned in order of appearance.
##
## @end deftypefn
function [C, ixA, ixB] = union (A, B, varargin)
[C, ixA, ixB] = setop (A, B, 'union', varargin{:});
if (! iscategorical (C))
error (C);
endif
endfunction
endmethods
################################################################################
## ** Array Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'cat' 'horzcat' 'vertcat' 'repmat' ##
## 'repelem' 'repelems' 'reshape' 'circshift' ##
## 'permute' 'ipermute' 'transpose' 'ctranspose' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} cat (@var{dim}, @var{A}, @var{B}, @dots{})
##
## Concatenate categorical arrays.
##
## @code{@var{C} = cat (@var{dim}, @var{A}, @var{B}, @dots{})} concatenates
## categorical arrays @var{A}, @var{B}, @dots{} along dimension @var{dim}.
## All input arrays must have the same size except along the operating
## dimension @var{dim}. Any of the input arrays may also be string arrays
## or cell arrays of character vectors of compatible size.
##
## If any input array is an ordinal categorical array, then all inputs must
## be ordinal categorical arrays with the same set and ordering of
## categories. In this case, @var{C} is also an ordinal categorical array
## with the same set and ordering of categories. If none of the input
## arrays are ordinal, then they do not need to have the same set of
## categories. In this case, categorical array @var{C} contains the union
## of the categories from all input arrays. Protected categorical arrays
## can only be concatenated with other arrays that have the same set of
## categories but not necessarily in the same order.
##
## @end deftypefn
function out = cat (dim, varargin)
## Remove empty cell inputs
varargin(cellfun (@(x) isempty (x) && iscell (x), varargin)) = [];
if (numel (varargin) == 1)
out = varargin{1};
return;
endif
## Identify non-categorical inputs for reordering categories
firstcatid = find (cellfun (@(x) iscategorical (x), varargin), 1);
## Promote everything into categorical arrays
args = varargin;
[args{:}] = promote (varargin{:});
## Check that all dimensions except DIM are equal
if (fix (dim) != dim | dim < 1)
error ("categorical.cat: DIM must be a valid dimension.");
endif
sz_dim = cellfun (@(x) size (x), args, "UniformOutput", false);
n_dims = cellfun (@(x) ndims (x), args, "UniformOutput", false);
if (! isequal (n_dims{:}))
error ("categorical.cat: dimensions mismatch.");
elseif (dim <= n_dims{1})
idx = 1:n_dims{1};
idx(dim) = [];
rem_dims = cellfun (@(x) (x(idx)), sz_dim, "UniformOutput", false);
if (! isequal (rem_dims{:}))
error ("categorical.cat: size mismatch.");
endif
endif
## If any categorical value is ordinal, all must be
is_ordinal = cellfun (@isordinal, args);
if (all (is_ordinal))
## Check that all categorical arrays have the same categories
## and they are in the same order
cats = cellfun (@(x) categories (x), args, 'UniformOutput', false);
if (! isequal (cats{:}))
error (strcat ("categorical.cat: cannot concatenate ordinal", ...
" categorical arrays unless they have the same", ...
" ordered set of categories."));
endif
out = args{1};
fieldArgs = cellfun (@(x) x.code, args, 'UniformOutput', false);
out.code = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(x) x.isMissing, args, 'UniformOutput', false);
out.isMissing = cat (dim, fieldArgs{:});
return;
elseif (any (is_ordinal))
error (strcat ("categorical.cat: cannot concatenate ordinal", ...
" with non-ordinal categorical arrays."));
endif
## If any categorical array is protected, all must have the same
## categories
is_protected = cellfun (@isprotected, args);
if (any (is_protected))
## Check that all categorical arrays have the same categories
## but they are not necessarily in the same order
cats = cellfun (@(x) categories (x), args, 'UniformOutput', false);
if (! all (ismember (cats{:})))
error (strcat ("categorical.cat: cannot concatenate protected", ...
" categorical arrays that do not have the same", ...
" set of categories."));
endif
out = args{1};
out.isProtected = true; # returning array must also be protected
## Go through remaining categorical arrays and reorder codes accordingly
idx = cell (1, numel (cats{1}));
for i = 2:numel (args)
for j = 1:numel (out.cats)
new_code = find (strcmp (args{i}.cats, out.cats(j)));
idx{j} = args{i}.code == new_code;
endfor
for j = 1:numel (out.cats)
args{i}.code(idx{j}) = j;
endfor
endfor
fieldArgs = cellfun (@(x) x.code, args, 'UniformOutput', false);
out.code = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(x) x.isMissing, args, 'UniformOutput', false);
out.isMissing = cat (dim, fieldArgs{:});
return;
endif
## No constrains, add new categories as necessary and bump code indexing
## to reflect the changes in category list of concatenated output array
out = args{1};
for i = 2:numel (args)
n_cats = numel (categories (args{i}));
idx = cell (2, n_cats);
newcat = {};
n_code = 0;
for j = 1:n_cats
new_code = find (strcmp (out.cats, args{i}.cats(j)));
if (! isempty (new_code))
idx{1,j} = args{i}.code == j;
idx{2,j} = new_code;
else
idx{1,j} = args{i}.code == j;
idx{2,j} = numel (out.cats) + n_code + 1;
n_code += 1;
newcat = [newcat; args{i}.cats(j)];
endif
endfor
out.cats = [out.cats; newcat];
for j = 1:n_cats
args{i}.code(idx{1,j}) = idx{2,j};
endfor
fieldArgs = cellfun (@(x) x.code, args, 'UniformOutput', false);
out.code = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(x) x.isMissing, args, 'UniformOutput', false);
out.isMissing = cat (dim, fieldArgs{:});
endfor
## The categories of the first categorical input array need go first
if (firstcatid > 1)
catstostart = categories (args{firstcatid});
catsremoved = out.cats(! ismember (out.cats, catstostart));
catsreorder = [catstostart; catsremoved];
out = reordercats (out, catsreorder);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} horzcat (@var{A}, @var{B}, @dots{})
##
## Horizontal concatenation of categorical arrays.
##
## @code{@var{C} = horzcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}, @var{B}, @dots{}]} and horizontally
## concatenates the categorical arrays @var{A}, @var{B}, @dots{}. All input
## arrays must have the same size except along the second dimension. Any of
## the input arrays may also be string arrays or cell arrays of character
## vectors of compatible size.
##
## If any input array is an ordinal categorical array, then all inputs must
## be ordinal categorical arrays with the same set and ordering of
## categories. In this case, @var{C} is also an ordinal categorical array
## with the same set and ordering of categories. If none of the input
## arrays are ordinal, then they do not need to have the same set of
## categories. In this case, categorical array @var{C} contains the union
## of the categories from all input arrays. Protected categorical arrays
## can only be concatenated with other arrays that have the same set of
## categories but not necessarily in the same order.
##
## @end deftypefn
function out = horzcat (varargin)
out = cat (2, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{C} =} vertcat (@var{A}, @var{B}, @dots{})
##
## Vertical concatenation of categorical arrays.
##
## @code{@var{C} = vertcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}; @var{B}; @dots{}]} and vertically
## concatenates the categorical arrays @var{A}, @var{B}, @dots{}. All input
## arrays must have the same size except along the first dimension. Any of
## the input arrays may also be string arrays or cell arrays of character
## vectors of compatible size.
##
## If any input array is an ordinal categorical array, then all inputs must
## be ordinal categorical arrays with the same set and ordering of
## categories. In this case, @var{C} is also an ordinal categorical array
## with the same set and ordering of categories. If none of the input
## arrays are ordinal, then they do not need to have the same set of
## categories. In this case, categorical array @var{C} contains the union
## of the categories from all input arrays. Protected categorical arrays
## can only be concatenated with other arrays that have the same set of
## categories but not necessarily in the same order.
##
## @end deftypefn
function out = vertcat (varargin)
out = cat (1, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} repmat (@var{A}, @var{n})
## @deftypefnx {categorical} {@var{B} =} repmat (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {categorical} {@var{B} =} repmat (@var{A}, @var{dimvec})
##
## Repeat copies of a categorical array.
##
## @code{@var{B} = repmat (@var{A}, @var{n})} returns a categorical array
## @var{B} containing @var{n} copies of the input categorical array @var{A}
## along every dimension of @var{A}.
##
## @code{@var{B} = repmat (@var{A}, @var{d1}, @dots{}, @var{dN})} returns an
## array @var{B} containing copies of @var{A} along the dimensions specified
## by the list of scalar integer values @var{d1}, @dots{}, @var{dN}, which
## specify how many copies of @var{A} are made in each dimension.
##
## @code{@var{B} = repmat (@var{A}, @var{dimvec})} is equivalent to the
## previous syntax with @code{@var{dimvec} = [@var{d1}, @dots{}, @var{dN}]}.
##
## @end deftypefn
function this = repmat (this, varargin)
this.code = repmat (this.code, varargin{:});
this.isMissing = repmat (this.isMissing, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} repelem (@var{A}, @var{n})
## @deftypefnx {categorical} {@var{B} =} repelem (@var{A}, @var{d1}, @dots{}, @var{dN})
##
## Repeat copies of categorical array elements.
##
## @code{@var{B} = repelem (@var{A}, @var{n})} returns a categorical vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a categorical vector. If @var{n} is a scalar, each element of @var{A} is
## repeated @var{n} times along the non-singleton dimension of @var{A}. If
## @var{n} is a vector, it must have the same elements as @var{A}, in which
## case it specifies the number of times to repeat each corresponding
## element of @var{A}.
##
## @code{@var{B} = repelem (@var{A}, @var{d1}, @dots{}, @var{dN})} returns
## an array @var{B} with each element of @var{A} repeated according to the
## the list of input arguments @code{@var{d1}, @dots{}, @var{dN}} each
## corresponding to a different dimension @code{1:ndims (@var{A})} of the
## input array @var{A}. @var{d1}, @dots{}, @var{dN} must be either scalars
## or vectors with the same length as the corresponding dimension of
## @var{A} containing non-negative integer values specifying the number of
## repetitions of each element along the corresponding dimension.
##
## @end deftypefn
function this = repelem (this, varargin)
this.code = repelem (this.code, varargin{:});
this.isMissing = repelem (this.isMissing, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} repelems (@var{A}, @var{R})
##
## Construct a vector of repeated elements from a categorical array.
##
## @code{@var{B} = repelems (@var{A}, @var{R})} returns a categorical vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a categorical vector. @var{R} must be a @math{2*N} matrix of integers.
## Entries in the first row of @var{R} correspond to the linear indexing of
## the elements in @var{A} to be repeated. The corresponding entries in the
## second row of @var{R} specify the repeat count of each element.
##
## @end deftypefn
function this = repelems (this, R)
this.code = repelems (this.code, R);
this.isMissing = repelems (this.isMissing, R);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} reshape (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {categorical} {@var{B} =} reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})
## @deftypefnx {categorical} {@var{B} =} reshape (@var{A}, @var{dimvec})
##
## Repeat copies of categorical array elements.
##
## @code{@var{B} = reshape (@var{A}, @var{d1}, @dots{}, @var{dN})} returns a
## categorical array @var{B} with specified dimensions @var{d1}, @dots{},
## @var{dN}, whose elements are taken columnwise from the categorical array
## @var{A}. The product of @var{d1}, @dots{}, @var{dN} must equal the total
## number of elements in @var{A}.
##
## @code{@var{B} = reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})} returns
## a categorical array @var{B} with one dimension unspecified which is
## calculated automatically so that the product of dimensions in @var{B}
## matches the total elements in @var{A}, which must be divisible the
## product of specified dimensions. An empty matrix @qcode{([])} is used to
## flag the unspecified dimension.
##
## @end deftypefn
function this = reshape (this, varargin)
this.code = reshape (this.code, varargin{:});
this.isMissing = reshape (this.isMissing, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} circshift (@var{A}, @var{n})
## @deftypefnx {categorical} {@var{B} =} circshift (@var{A}, @var{n}, @var{dim})
##
## Circularly shift the elements in a categorical array.
##
## @code{@var{B} = circshift (@var{A}, @var{n})} circularly shifts the
## elements of the categorical array @var{A} according to @var{n}. If
## @var{n} is a nonzero integer scalar, then the elements of @var{A} are
## shifted by @var{n} elements along the first non-singleton dimension of
## @var{A}. If @var{n} is a vector, it must not be longer that the number
## of dimensions of @var{A} with each value of @var{n} corresponding to a
## dimension in @var{A}. The sign of the value(s) in @var{n} specify the
## direction in the elements of @var{A} are shifted.
##
## @code{@var{B} = circshift (@var{A}, @var{n}, @var{dim})} circularly
## shifts the elements of the categorical array @var{A} along the dimension
## specified by @var{dim}. In this case, @var{n} must be a scalar integer
## value.
##
## @end deftypefn
function this = circshift (this, varargin)
this.code = circshift (this.code, varargin{:});
this.isMissing = circshift (this.isMissing, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} permute (@var{A}, @var{dims})
##
## Generalized transpose for a categorical N-D array.
##
## @code{@var{B} = permute (@var{A}, @var{dims})} returns the generalized
## transpose of the categorical array @var{A} by rearranging its dimensions
## according to the permutation vector specified in @var{dims}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{A})} of the
## input array @var{A}, in any order, but only once. The @var{N}th
## dimension of @var{A} gets remapped to the dimension in @var{B} specified
## by @code{@var{dims}(@var{N})}.
##
## @end deftypefn
function this = permute (this, dims)
this.code = permute (this.code, dims);
this.isMissing = permute (this.isMissing, dims);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{A} =} ipermute (@var{B}, @var{dims})
##
## Inverse of the generalized transpose for a categorical N-D array.
##
## @code{@var{A} = ipermute (@var{B}, @var{dims})} returns the inverse of
## the generalized transpose performed by the @code{permute} function. The
## expression @code{ipermute (permute (@var{A}, @var{dims}), @var{dims})}
## returns the original array @var{A}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{B})} of the
## input array @var{B}, in any order, but only once. The dimension of
## @var{B} specified in @code{@var{dims}(@var{N})} gets remapped to the
## @var{N}th dimension of @var{A}.
##
## @end deftypefn
function this = ipermute (this, dims)
this.code = ipermute (this.code, dims);
this.isMissing = ipermute (this.isMissing, dims);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} transpose (@var{A})
##
## Transpose a categorical matrix.
##
## @code{@var{B} = transpose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}.'} and returns the transpose of the categorical
## matrix @var{A}.
##
## @end deftypefn
function this = transpose (this)
if (ndims (this) != 2)
error ("categorical.transpose: not defined for N-D arrays.");
endif
this.code = transpose (this.code);
this.isMissing = transpose (this.isMissing);
endfunction
## -*- texinfo -*-
## @deftypefn {categorical} {@var{B} =} ctranspose (@var{A})
##
## Transpose a categorical matrix.
##
## @code{@var{B} = ctranspose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}'} and returns the transpose of the categorical
## matrix @var{A}. For categorical arrays, @code{ctranspose} is identical
## to @code{transpose}.
##
## @end deftypefn
function this = ctranspose (this)
if (ndims (this) != 2)
error ("categorical.ctranspose: not defined for N-D arrays.");
endif
this.code = ctranspose (this.code);
this.isMissing = ctranspose (this.isMissing);
endfunction
endmethods
################################################################################
## ** Reference and Assignment Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'end' 'subsref' 'subsasgn' ##
## ##
################################################################################
methods (Hidden)
## Overload 'end' keyword
function last_index = end (this, end_dim, ndim_obj)
lastdim = ndims (this);
if (end_dim == ndim_obj && ndim_obj == 1)
last_index = prod (size (this));
elseif (end_dim == ndim_obj && end_dim < lastdim)
last_index = prod (size (this)(end_dim:lastdim));
else
last_index = size (this, end_dim);
endif
endfunction
## Class specific subscripted reference
function varargout = subsref (this, s)
chain_s = s(2:end);
s = s(1);
switch (s.type)
case '()'
out = this;
out.code = this.code(s.subs{:});
out.isMissing = this.isMissing(s.subs{:});
case '{}'
error (strcat ("categorical.subsref: '{}' invalid indexing", ...
" for referencing values. Use '()' instead."));
case '.'
error (strcat ("categorical.subsref: '.' invalid indexing", ...
" for referencing field of non-structure array."));
endswitch
## Chained references
if (! isempty (chain_s))
out = subsref (out, chain_s);
endif
varargout{1} = out;
endfunction
## Class specific subscripted assignment
function this = subsasgn (this, s, val)
if (numel (s) > 1)
error ("categorical.subsasgn: chained subscripts not allowed.");
endif
switch s.type
case '()'
if (isempty (val) && isa (val, 'double'))
this.code(s.subs{:}) = [];
this.isMissing(s.subs{:}) = [];
return;
elseif (isa (val, 'missing'))
this.code(s.subs{:}) = 0;
this.isMissing(s.subs{:}) = true;
return;
elseif (iscellstr (val) || ischar (val) || isstring (val))
## Convert to unprotected unordered categorical array and
## handle it as usual below
if (ischar (val))
val = cellstr (val);
elseif (isempty (val))
error ("categorical.subsasgn: assignment value has no elements.");
endif
val = categorical (val);
elseif (! isa (val, 'categorical'))
error (strcat ("categorical.subsasgn: assignment value must", ...
" be a categorical array or text representing", ...
" a single or multiple categories."));
endif
## After this point VAL is a categorical array
## If any categorical array is ordinal, all must be
if (isordinal (this) && isordinal (val))
## Check that all categorical arrays have the same categories
## and they are in the same order
if (! isequal (categories (this), categories (val)))
error (strcat ("categorical.subsasgn: cannot assign value", ...
" to ordinal categorical array unless they", ...
" have the same ordered set of categories."));
endif
this.code(s.subs{:}) = val.code;
this.isMissing(s.subs{:}) = val.isMissing;
return;
elseif (isordinal (this))
error (strcat ("categorical.subsasgn: cannot assign unordered", ...
" categorical array to ordinal categorical array."));
elseif (isordinal (val))
error (strcat ("categorical.subsasgn: cannot assign ordinal", ...
" categorical array to unordered categorical", ...
" array."));
endif
## If protected, no new categories can be assigned
if (isprotected (this))
if (! all (ismember (val.cats, this.cats)))
error (strcat ("categorical.subsasgn: cannot assign new", ...
" categories to protected categorical array."));
endif
## Reorder codes accordingly
n_cats = numel (val.cats);
idx = cell (2, n_cats);
for j = 1:n_cats
new_code = find (strcmp (this.cats, val.cats(j)));
idx{1,j} = val.code == j;
idx{2,j} = new_code;
endfor
for j = 1:n_cats
val.code(idx{1,j}) = idx{2,j};
endfor
this.code(s.subs{:}) = val.code;
this.isMissing(s.subs{:}) = val.isMissing;
return;
endif
## No constrains, add new categories as necessary and bump code
## indexing to reflect the changes in category list of assigned
## categorical array
n_cats = numel (val.cats);
maxcat = numel (this.cats);
idx = cell (2, n_cats);
newcat = {};
n_code = 0;
for j = 1:n_cats
new_code = find (strcmp (this.cats, val.cats(j)));
if (! isempty (new_code))
idx{1,j} = val.code == j;
idx{2,j} = new_code;
else
idx{1,j} = val.code == j;
idx{2,j} = maxcat + n_code + 1;
n_code += 1;
newcat = [newcat; val.cats(j)];
endif
endfor
this.cats = [this.cats; newcat];
for j = 1:n_cats
val.code(idx{1,j}) = idx{2,j};
endfor
this.code(s.subs{:}) = val.code;
this.isMissing(s.subs{:}) = val.isMissing;
case '{}'
error (strcat ("categorical.subsasgn: '{}' invalid indexing", ...
" for assigning values. Use '()' instead."));
case '.'
error (strcat ("categorical.subsasgn: '.' invalid indexing", ...
" for assigning field of non-structure array."));
endswitch
endfunction
endmethods
methods (Access = private)
## Return a subset of the array
function this = subset (this, varargin)
this = this;
this.code = this.code(varargin{:});
this.isMissing = this.isMissing(varargin{:});
endfunction
## Common function for set operations
function [C, ixA, ixB] = setop (A, B, fname, varargin)
ixA = ixB = [];
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
C = sprintf (strcat ("categorical.%s: 'legacy'", ...
" option is not supported."), fname);
return;
endif
if (ischar (A))
A = categorical (cellstr (A));
elseif (iscellstr (A) || isa (A, 'string'))
A = categorical (A);
elseif (ischar (B))
B = categorical (cellstr (B));
elseif (iscellstr (B) || isa (B, 'string'))
B = categorical (B);
endif
if (! isa (A, 'categorical') || ! isa (B, 'categorical'))
C = sprintf ("categorical.%s: invalid type input arrays.", fname);
return;
endif
if (xor (A.isOrdinal, B.isOrdinal))
C = sprintf (strcat ("categorical.%s: if A is", ...
" ordinal, B must be ordinal."), fname);
return;
endif
C = A;
if (A.isOrdinal && B.isOrdinal)
if (! isequal (A.cats, B.cats))
C = sprintf (strcat ("categorical.%s: ordinal arrays must", ...
" have the same set of categories in", ...
" the same order."), fname);
return;
endif
## For ordinal arrays, operate directly on codes
Acodes = double (A);
Bcodes = double (B);
else
## For unordered arrays, operate on categorical values
allcats = unique ([A.cats(:); B.cats(:)]);
A_cats_idx = cellfun (@(x) find (ismember (allcats, x)), A.cats);
Acodes = nan (size (A.code));
for i = 1:numel (A_cats_idx)
Acodes(A.code == i) = A_cats_idx(i);
endfor
B_cats_idx = cellfun (@(x) find (ismember (allcats, x)), B.cats);
Bcodes = nan (size (B.code));
for i = 1:numel (B_cats_idx)
Bcodes(B.code == i) = B_cats_idx(i);
endfor
C.cats = allcats;
endif
## Apply set operation
switch (fname)
case 'intersect'
[code, ixA, ixB] = intersect (Acodes, Bcodes, varargin{:});
case 'setdiff'
[code, ixA] = setdiff (Acodes, Bcodes, varargin{:});
case 'setxor'
[code, ixA, ixB] = setxor (Acodes, Bcodes, varargin{:});
case 'union'
[code, ixA, ixB] = union (Acodes, Bcodes, varargin{:});
endswitch
## Add codes and missing arrays
C.code = uint16 (code);
C.isMissing = C.code == 0;
endfunction
## Expand categorical arrays of compatible sizes
function [A, B, err] = csize_expand (A, B)
err = false;
szA = size (A);
szB = size (B);
if (isscalar (A) && ! isscalar (B))
A = repmat (A, szB);
elseif (! isscalar (A) && isscalar (B))
B = repmat (B, szA);
elseif (! isequal (szA, szB))
ndA = numel (szA);
ndB = numel (szB);
if (ndA > ndB)
padones = ones (1, ndA - ndB);
szB = [szB, padones];
elseif (ndA < ndB)
padones = ones (1, ndB - ndA);
szA = [szA, padones];
endif
## Check that sizes are compatible
must_equal = szA != 1 & szB != 1;
if (! isequal (szA(must_equal), szB(must_equal)))
err = true;
return;
endif
## Create expansion vectors
dims = max (ndA, ndB);
repA = ones (1, dims);
repB = ones (1, dims);
## Get dimensions that should be expanded
expA = szA == 1 & szB != 1;
repA(expA) = szB(expA);
expB = szB == 1 & szA != 1;
repB(expB) = szA(expB);
## Expand accordingly
A = repmat (A, repA);
B = repmat (B, repB);
endif
endfunction
endmethods
endclassdef
## Promote text arrays to categorical objects
function varargout = promote (varargin)
for i = 1:numel (varargin)
val = varargin{i};
if (isa (val, "categorical"))
varargout{i} = val;
elseif (iscellstr (val) || isa (val, "string") || ischar (val))
val = cellstr (val);
varargout{i} = categorical (val);
elseif (isnumeric (val) || islogical (val))
varargout{i} = categorical (val);
elseif (isa (val, 'missing'))
varargout{i} = categorical (nan (size (missing)));
else
error ("categorical: invalid input to constructor.");
endif
endfor
endfunction
## Custom function for displaying categorical summary
function dispcellmatrix (C)
sz = terminal_size ();
cols = sz(2) - 4;
colgap = " ";
dispstr = {};
optLens = [];
for iCol = 1:size (C, 2)
[outstr, optLen] = mixedcell2str (C(:, iCol));
dispstr = [dispstr, outstr];
optLens = [optLens, optLen];
endfor
if (sum (optLens + 6) <= cols) # all columns fit in terminal size
rowSpat = "";
for iCol = 1:size (C, 2)
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,:});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
else # we need to split rows
optLen_cs = cumsum (optLens + 6);
startCol = 1;
while (! isempty (find (optLen_cs > cols)))
stopCol = find (optLen_cs > cols, 1) - 1;
rowSpat = "";
for iCol = 1:stopCol
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
optLens(1:iCol) = [];
optLen_cs = cumsum (optLens + 6);
stopCol = stopCol + startCol - 1;
fprintf ("Columns %d through %d:\n\n", startCol, stopCol);
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,[startCol:stopCol]});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
startCol = stopCol + 1;
endwhile
if (! isempty (optLens))
for iCol = 1:length (optLens)
rowSpat = [rowSpat, sprintf("%%-%ds", optLens(iCol)), colgap];
endfor
stopCol = startCol + iCol - 1;
if (startCol == stopCol)
fprintf ("Column %d:\n\n", startCol);
else
fprintf ("Columns %d through %d:\n\n", startCol, stopCol);
endif
for iRow = 1:size (C, 1)
strrow = sprintf (rowSpat, dispstr{iRow,[startCol:stopCol]});
fprintf (" %s\n", strrow);
endfor
fprintf ("\n");
endif
endif
endfunction
## Custom function to convert a mixed cell array to cellstr array
function [dispstr, optLen] = mixedcell2str (data)
dispstr = cell (size (data));
## Preallocate indexes to avoid truncation when last elements are 0
is_char = logical (zeros (size (data)));
is_numb = is_char;
## Index numeric scalar and character row vector
ve = cell2mat (cellfun (@(x) size (x,1), data, "UniformOutput", false)) == 1;
## Catch 'char' row vectors
is_char(ve) = cellfun ('ischar', data(ve));
sf = @(x) sprintf ("%s", x);
dispstr(is_char) = cellfun (sf, data(is_char), "UniformOutput", false);
## Catch 'numeric' scalars
is_numb(ve) = cellfun ('isnumeric', data(ve));
sf = @(x) sprintf ("%d", x);
dispstr(is_numb) = cellfun (sf, data(is_numb), "UniformOutput", false);
## Get optimal length
optLen = max (cellfun (@length, dispstr));
## Pad data according to optimal length
Ra_wB = sprintf ("%%-%ds", optLen);
fcn = @(x) sprintf (Ra_wB, x);
dispstr(is_numb) = cellfun (fcn, dispstr(is_numb), "UniformOutput", false);
La_wB = sprintf ("%%+%ds", optLen);
fcn = @(x) sprintf (La_wB, x);
dispstr(is_char) = cellfun (fcn, dispstr(is_char), "UniformOutput", false);
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/cell2table.m 0000664 0000000 0000000 00000016222 15227665741 0021224 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{tbl} =} cell2table (@var{C})
## @deftypefnx {datatypes} {@var{tbl} =} cell2table (@var{C}, @var{Name}, @var{Value})
##
## Convert a cell array to a table.
##
## @code{@var{tbl} = cell2table (@var{C})} converts the 2-D cell array @var{C}
## to the table @var{tbl}, where the contents of each column of @var{C} becomes
## a variable in @var{tbl}. The contents of each column are concatenated into
## their common data type (i.e. if a column of @var{C} contains explicitly
## @qcode{double} numbers, then the corresponding variable in @var{tbl} is of
## the same type), otherwise they are added as a column of cells.
##
## @code{@var{tbl} = cell2table (@var{C}, @var{Name}, @var{Value})} specifies
## optional parameters for creating the table @var{tbl} with the following
## Name-Value paired arguments.
##
## @multitable @columnfractions 0.23 0.75
## @headitem @var{Name} @tab @var{Value}
##
## @item @qcode{'VariableNames'} @tab A cell array of character vectors or
## a string array defining the variable names of @var{tbl}. The names must be
## valid variable names and unique.
##
## @item @qcode{'RowNames'} @tab A cell array of character vectors or
## a string array defining the row names of @var{tbl}. The names must be unique
## but not necessarily valid variable names.
##
## @item @qcode{'DimensionNames'} @tab A cell array of character vectors or
## a string array defining the dimension names of @var{tbl}. The names must be
## unique and not in conflict with variable names. By default, dimension names
## are @qcode{'Row', 'Variables'}.
## @end multitable
##
## @seealso{array2table, struct2table, table}
## @end deftypefn
function tbl = cell2table (C, varargin)
## Check input is a matrix
if (ndims (C) > 2)
error ("cell2table: input array must be a 2-D cell array.");
endif
if (! iscell (C))
error ("cell2table: input array must be a cell array.");
endif
## Parse optional Name-Value paired arguments
optNames = {'VariableNames', 'RowNames', 'DimensionNames'};
dfValues = {{}, {}, {}};
[varNames, rowNames, dimNames, args] = parsePairedArguments ...
(optNames, dfValues, varargin);
## Split columns into separate input data arguments for table
varN = size (C, 2);
varValues = cell (1, varN);
for ix = 1:varN
tmp = C(:,ix);
if (iscellstr (tmp))
varValues{ix} = tmp;
else
## Try to concatenate into array
try
warning ('off', 'Octave:num-to-str');
newArray = cat (1, tmp{:});
warning ('on', 'Octave:num-to-str');
if (size (newArray, 1) == size (tmp, 1))
varValues{ix} = newArray;
continue;
else
error ();
endif
catch
varValues{ix} = tmp;
end_try_catch
endif
endfor
## Handle variable names
if (! isempty (varNames))
if (numel (varNames) != varN)
error (strcat ("cell2table: 'VariableNames' must match the", ...
" columns in input cell."));
endif
else
varName = inputname (1);
if (isempty (varName))
varName = 'Var';
endif
varNames = cell (1, varN);
for ix = 1:varN
varNames{ix} = sprintf ('%s%d', varName, ix);
endfor
endif
optArgs = {'VariableNames', varNames};
## Handle remaining paired arguments
if (! isempty (rowNames))
if (numel (rowNames) != size (C, 1))
error ("cell2table: 'RowNames' must match the rows in input cell.");
endif
optArgs = [optArgs {'RowNames', rowNames}];
endif
if (! isempty (dimNames))
if (numel (dimNames) != 2)
error ("cell2table: 'DimensionNames' must be a two-element vector.");
endif
optArgs = [optArgs {'DimensionNames', dimNames}];
endif
## Construct table
tbl = table (varValues{:}, optArgs{:});
endfunction
%!demo
%! ## `cell2table` turns a 2-D cell array into a table, one column per variable.
%! ## Unlike a matrix, the cell columns may hold different types.
%!
%! C = {'Sanchez', 38, true; 'Johnson', 43, false; 'Li', 38, true};
%! cell2table (C, 'VariableNames', {'LastName', 'Age', 'Smoker'})
%!test
%! C = {1, 2; 3, 4};
%! tbl = cell2table (C);
%! assert_equal (tbl.C1, [1; 3]);
%! assert_equal (tbl.C2, [2; 4]);
%! assert_equal (size (C), size (tbl));
%! assert_equal (isa (tbl.C1, 'double'), true);
%!test
%! tbl = cell2table ({1, 2; 3, 4});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, [2; 4]);
%! assert_equal (size (tbl), [2, 2]);
%! assert_equal (isa (tbl.Var1, 'double'), true);
%!test
%! tbl = cell2table ({1, ''; 3, 4}, 'VariableNames', {'A', 'B'});
%! assert_equal (tbl.A, [1; 3]);
%! assert_equal (tbl.B, {''; 4});
%! assert_equal (isa (tbl.A, 'double'), true);
%! assert_equal (isa (tbl.B, 'double'), false);
%!test
%! tbl = cell2table ({1, ''; 3, 4}, "RowNames", {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, {''; 4});
%! assert_equal (tbl.Properties.RowNames, {'A'; 'B'});
%! assert_equal (class (tbl('A', :)), 'table');
%!test
%! tbl = cell2table ({1, ''; 3, 4}, string ('DimensionNames'), {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, {""; 4});
%! assert_equal (tbl.A, {});
%! assert_equal (tbl.B, {1, ''; 3, 4});
%!test
%! tbl = cell2table ({1, ''; 3, 4}, "RowNames", {'A', 'B'}, ...
%! "DimensionNames", {'A', 'B'});
%! assert_equal (tbl.Var1, [1; 3]);
%! assert_equal (tbl.Var2, {''; 4});
%! assert_equal (tbl.A, {'A'; 'B'});
%! assert_equal (tbl.B, {1, ''; 3, 4});
%!test
%! tbl = cell2table ({1, string(''); 3, 4}, "RowNames", {'R1', 'R2'}, ...
%! "DimensionNames", {'A', 'B'});
%! assert_equal (class (tbl('R1', :)), 'table');
%! assert_equal (class (tbl{'R1', :}), 'string');
%! assert_equal (cellstr (tbl{'R1', :}), {'1', ''});
%! assert_equal (tbl.A, {'R1'; 'R2'});
%! assert_equal (class (tbl.B), 'string');
%! assert_equal (cellstr (tbl.B), {'1', ''; '3', '4'});
%!error ...
%! cell2table (cell (3, 3, 3));
%!error cell2table ([3; 3; 3]);
%!error ...
%! cell2table ({1; 2; 3}, 'VariableNames', {'A', 'B'});
%!error ...
%! cell2table ({1; 2; 3}, 'RowNames', {'A', 'B'});
%!error ...
%! cell2table ({1; 2; 3}, 'DimensionNames', {'A', 'B', 'C'});
pr0m1th3as-datatypes-9c9a8d3/inst/convertCharsToStrings.m 0000664 0000000 0000000 00000005404 15227665741 0023531 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} convertCharsToStrings (@var{A})
## @deftypefnx {datatypes} {[@var{B1}, @dots{}, @var{Bn}] =} convertCharsToStrings (@var{A1}, @dots{}, @var{An})
##
## Convert character arrays to a string arrays, where applicable.
##
## @code{@var{B} = convertCharsToStrings (@var{A})} converts @var{A} to a string
## scalar, if @var{A} is a character vector or array, or to a string array, if
## @var{A} is a cell array of character vectors. Otherwise, @var{A} is returned
## unaltered.
##
## @code{[@var{B1}, @dots{}, @var{Bn}] = convertCharsToStrings (@var{A1},
## @dots{}, @var{An})} converts any of the input arguments that are either
## character arrays or cell arrays of character vectors to string scalars or
## string arrays, respectively. Otherwise, @code{convertCharsToStrings} returns
## the input arguments unaltered.
##
## @seealso{convertStringsToChars, string}
## @end deftypefn
function varargout = convertCharsToStrings (varargin)
for i = 1:numel (varargin)
if (ischar (varargin{i}))
varargout{i} = string (varargin{i}(:)');
elseif (iscellstr (varargin{i}))
varargout{i} = string (varargin{i});
else
varargout{i} = varargin{i};
endif
endfor
endfunction
%!test
%! A = 'text';
%! B = [1, 2, 3];
%! C = string ("test");
%! [A1, B1, C1] = convertCharsToStrings (A, B, C);
%! assert_equal (isstring (A1), true);
%! assert_equal (B, B1);
%! assert_equal (C == C1, true);
%!test
%! A = {'asd', 'ert'; 'xcv', 'dfg'};
%! A1 = convertCharsToStrings (A);
%! assert_equal (isequal (size (A), size (A1)), true);
%! assert_equal (isstring (A1), true);
%!test
%! A = categorical (NaN);
%! B = duration;
%! C = 'text';
%! [A1, B1, C1] = convertCharsToStrings (A, B, C);
%! assert_equal (iscategorical (A1), true);
%! assert_equal (isduration (B1), true);
%! assert_equal (isstring (C1), true);
%!test
%! A = ['e','r';'v','b'];
%! A1 = convertCharsToStrings (A);
%! assert_equal (isscalar (A1), true);
%! assert_equal (strcmp (char (A1), 'evrb'), true);
pr0m1th3as-datatypes-9c9a8d3/inst/convertStringsToChars.m 0000664 0000000 0000000 00000005030 15227665741 0023524 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} convertStringsToChars (@var{A})
## @deftypefnx {datatypes} {[@var{B1}, @dots{}, @var{Bn}] =} convertStringsToChars (@var{A1}, @dots{}, @var{An})
##
## Convert string arrays to a character arrays, where applicable.
##
## @code{@var{B} = convertStringsToChars (@var{A})} converts @var{A} to a
## character vector, if @var{A} is a string scalar, or to a cell array of
## character vectors, if @var{A} is a string array. Otherwise, @var{A} is
## returned unaltered.
##
## @code{[@var{B1}, @dots{}, @var{Bn}] = convertStringsToChars (@var{A1},
## @dots{}, @var{An})} converts any of the input arguments that are of string
## type to character vectors or to cell array of character vectors, or leaves
## them unaltered.
##
## @seealso{convertCharsToStrings, string}
## @end deftypefn
function varargout = convertStringsToChars (varargin)
for i = 1:numel (varargin)
if (isa (varargin{i}, 'string'))
if (isscalar (varargin{i}))
varargout{i} = char (varargin{i});
else
varargout{i} = cellstr (varargin{i});
endif
else
varargout{i} = varargin{i};
endif
endfor
endfunction
%!test
%! A = 'text';
%! B = [1, 2, 3];
%! C = string ("test");
%! [A1, B1, C1] = convertStringsToChars (A, B, C);
%! assert_equal (A, A1);
%! assert_equal (B, B1);
%! assert_equal (ischar (C1), true);
%!test
%! A = string ({'asd', 'ert'; 'xcv', 'dfg'});
%! A1 = convertStringsToChars (A);
%! assert_equal (isequal (size (A), size (A1)), true);
%! assert_equal (iscellstr (A1), true);
%!test
%! A = categorical (NaN);
%! B = duration;
%! C = 'text';
%! [A1, B1, C1] = convertStringsToChars (A, B, C);
%! assert_equal (iscategorical (A1), true);
%! assert_equal (isduration (B1), true);
%! assert_equal (ischar (C1), true);
pr0m1th3as-datatypes-9c9a8d3/inst/csv2table.m 0000664 0000000 0000000 00000100170 15227665741 0021074 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2025-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{tbl} =} csv2table (@var{filename})
## @deftypefnx {datatypes} {@var{tbl} =} csv2table (@var{filename}, @var{Name}, @var{Value})
##
## Load a CSV file into a table.
##
## @code{@var{tbl} = csv2table (@var{filename})} creates a table @var{tbl} by
## reading the data in CSV file specified by @var{filename}, which can be either
## character vector or a string scalar. If the CSV file was saved by the
## @code{table2csv} method, then it reads the custom comment line in the first
## element of the CSV file and reconstructs the table as specified including
## variable types, variable names, and possibly any nested tables or structures
## it may contain. If no such special comment is found, then it treats the CSV
## file as simple columnar data and loads with the following default options.
##
## @enumerate
## @item The first column is considered as @qcode{RowNames} and it is converted
## to cell array of character vectors and it is subsequently removed from the
## remaining data contained in the CSV file. To change the default behavior,
## you need to specify the @qcode{ReadRowNames} and @qcode{RowNamesColumn}
## paired arguments accordingly.
## @item The first line is treated as a header containing the variable names of
## the table. Any numeric values in the header line are converted to character
## vectors and all variable names are automatically modified to valid Octave
## variable names. To change the default behavior, you need to specify the
## @qcode{ReadVariableNames}, @qcode{VariableNamingRule}, and
## @qcode{VariableNamesLine} paired arguments accordingly.
## @item The data type of each column in the remaining data is automatically
## detected according to its contents. Consequently, text is converted to
## character vectors, datetime and duration strings are converted to datetime
## and duration arrays, respectively, and hexadecimal strings are converted to
## the smallest integer type that can represent all variable values. To change
## the default behavior, you need to specify the @qcode{TextType},
## @qcode{DatetimeType}, @qcode{DurationType}, and @qcode{HexType} accordingly.
## @end enumerate
##
## @code{@var{tbl} = csv2table (@var{filename}, @var{Name}, @var{Value})}
## specifies optional parameters for creating the table @var{tbl} with the
## following Name-Value paired arguments.
##
## @multitable @columnfractions 0.33 0.65
## @headitem @var{Name} @tab @var{Value}
##
## @item @qcode{'NumHeaderLines'} @tab A positive integer scalar value
## specifying the number of rows to omit reading from the CSV file. If the CSV
## contains the custom comment line in its first element, then the
## @qcode{'NumHeaderLines'} applies to the top number of rows to remove from the
## created table. If CSV is a generic case, then @qcode{'NumHeaderLines'}
## specifies the number of lines to omit parsing from the CSV file itself.
##
## @item @qcode{'VariableNames'} @tab A cell array of character vectors or
## a string array specifying the names of the variables of the created table.
## The names must be unique but not necessarily valid variable names. If not
## empty, it overrides any variable names extracted from the CSV file. This
## applies both to custom and generic CSV files.
##
## @item @qcode{'ReadVariableNames'} @tab A logical scalar specifying
## whether to parse or not the CSV files for variable names. If your CSV file
## only contains data, set @qcode{'ReadVariableNames'} to @qcode{false} so that
## @code{csv2table} parses all lines as data rows in the returned table.
## Variable names will be automatically generated to the default style as done
## by @code{table}, unless otherwise specified by the @qcode{'VariableNames'}
## paired argument. The default value is @qcode{true}.
##
## @item @qcode{'VariableNamingRule'} @tab A character vector or a string
## scalar specifying whether the variable names should be modified to valid
## Octave variable names or the original names should be preserved. Valid
## options are @qcode{"modify"} and @qcode{"preserve"}. By default,
## @code{csv2table} modifies the parsed variable names.
##
## @item @qcode{'VariableNamesLine'} @tab A nonnegative integer scalar
## value specifying the line number in the CSV file, which should be parsed for
## variable names. This only applies if the @qcode{'ReadVariableNames'} option
## is @qcode{true}. The specified line is subsequently removed from the
## remaining data contained in the CSV file. If @qcode{'VariableNamesLine'} is
## set to zero, then it is equivalent to setting @qcode{'ReadVariableNames'} to
## @qcode{false}.
##
## @item @qcode{'VariableTypes'} @tab A cell array of character vectors or
## a string array specifying the data type of the variables of the created
## table. The number of elements must much the number of variable in the table.
## This optional argument only has an effect on generic CSV files. When
## specified, it overrides any other data type specification or automatic
## detection by the @code{csv2table} function.
##
## @item @qcode{'VariableUnitsLine'} @tab A nonnegative integer scalar
## value specifying the line number in the CSV file, which should be parsed for
## variable units. The specified line is subsequently removed from the
## remaining data contained in the CSV file.
##
## @item @qcode{'VariableDescriptionsLine'} @tab A nonnegative integer
## scalar value specifying the line number in the CSV file, which should be
## parsed for variable descriptions. The specified line is subsequently removed
## from the remaining data contained in the CSV file.
##
## @item @qcode{'ReadRowNames'} @tab A logical scalar specifying whether to
## parse or not the CSV files for row names. If your CSV file only contains
## data, set @qcode{'ReadRowNames'} to @qcode{false} so that @code{csv2table}
## parses all columns as data columms in the returned table. The default value
## is @qcode{true}.
##
## @item @qcode{'RowNamesColumn'} @tab A nonnegative integer scalar value
## specifying the column number in the CSV file, which should be parsed for
## row names. This only applies if the @qcode{'ReadRowNames'} option is
## @qcode{true}. The specified column is subsequently removed from the
## remaining data contained in the CSV file. If @qcode{'RowNamesColumn'} is set
## to zero, then it is equivalent to setting @qcode{'ReadRowNames'} to
## @qcode{false}. Note that the values in the column specified by
## @qcode{'RowNamesColumn'} must be unique, otherwise @code{csv2table} will
## return an error.
##
## @item @qcode{'TextType'} @tab A character vector or a string scalar
## specifying whether the text data in the CSV file should be stored in the
## table as character vectors or string arrays. Valid options are
## @qcode{"char"} and @qcode{"string"}. By default, @code{csv2table} stores
## text data as character vectors.
##
## @item @qcode{'DatetimeType'} @tab A character vector or a string scalar
## specifying whether the datetime strings found in the CSV file should be
## stored in the table as datetime arrays or as text data. Valid options are
## @qcode{"datetime"} and @qcode{"text"}. By default, @code{csv2table} stores
## datetime strings as datetime arrays. If @qcode{"text"} is specified, then
## the data type depends on the @qcode{'TextType'} option.
##
## @item @qcode{'DurationType'} @tab A character vector or a string scalar
## specifying whether the duration strings found in the CSV file should be
## stored in the table as duration arrays or as text data. Valid options are
## @qcode{"duration"} and @qcode{"text"}. By default, @code{csv2table} stores
## duration strings as duration arrays. If @qcode{"text"} is specified, then
## the data type depends on the @qcode{'TextType'} option.
##
## @item @qcode{'HexType'} @tab A character vector or a string scalar
## specifying whether the hexadecimal text found in the CSV file should be
## stored as a suitable integer type, @qcode{"auto"} (default), as unaltered
## input text, @qcode{"text"}, (in which case the data type depends on the
## @qcode{'TextType'} option), or as any of the integer types supported by
## Octave. Valid options are @qcode{"auto"}, @qcode{"text"}, @qcode{"int8"},
## @qcode{"int16"}, @qcode{"int32"}, @qcode{"int64"}, @qcode{"uint8"},
## @qcode{"uint16"}, @qcode{"uint32"}, and @qcode{"uint64"}.
## @end multitable
##
## The following round-trip limitations apply when reading a file written by
## @code{table2csv}: @code{calendarDuration} and @code{categorical} variables
## are returned as cell arrays of character vectors (their values are not
## reconstructed), missing @code{string} values are read back as empty strings,
## and datetime and duration display formats are not preserved, although the
## values themselves are exact.
##
## @seealso{array2table, struct2table, table}
## @end deftypefn
function tbl = csv2table (name, varargin)
## The field delimiter must be known before the file is read, so pre-scan the
## optional arguments for it (it is also parsed as a normal option below).
delim = ',';
for i = 1:2:numel (varargin) - 1
if (ischar (varargin{i}) && strcmpi (varargin{i}, 'Delimiter'))
delim = varargin{i+1};
if (isa (delim, 'string'))
delim = char (delim);
endif
endif
endfor
if (! (ischar (delim) && isscalar (delim)))
error ("csv2table: 'Delimiter' must be a single character.");
endif
## Check first input is a character vector or a string scalar
if (ischar (name) && isvector (name))
C = __csv2table__ (name, delim);
elseif (isa (name, 'string') && isscalar (name))
C = __csv2table__ (char (name), delim);
else
error ("csv2table: NAME must be a character vector or a string scalar.");
endif
if (ischar (C))
error ("csv2table: %s.", C);
endif
## Get first comment line (as saved by 'table2csv' method). A generic CSV
## may carry a number in its first cell, so only attempt to split a string.
if (ischar (C{1,1}))
H_key = strsplit (C{1,1});
else
H_key = {};
endif
if (numel (H_key) == 13)
H_txt = strjoin (H_key([1,2,4,5,7,8,10,11,13]));
else
H_txt = '';
endif
txt = '# varTypes rows; varNames rows; varDescriptions rows; varUnits rows.';
if (strcmpi (H_txt, txt))
Trows = str2num (H_key{3});
Nrows = str2num (H_key{6});
Drows = str2num (H_key{9});
Urows = str2num (H_key{12});
C(1,:) = []; # remove comment line
else
Trows = 0;
Nrows = 0;
Drows = 0;
Urows = 0;
endif
## Handle CSV file with vartype header (as saved by table2csv method)
if (Trows > 0)
Hrows = Trows + Nrows + Drows + Urows;
## Check for RowNames
if (strcmp (C{1,1}, 'RowNames') && isempty (C{Trows+1,1}))
RowNames = C([Hrows+1:end],1);
C(:,1) = []; # remove row names
else
RowNames = {};
endif
## Split cell into headers and data
T = C(1:Trows,:); # variable types
C(1:Trows,:) = [];
N = C(1:Nrows,:); # variable names
C(1:Nrows,:) = [];
if (Drows)
D = C(1:Drows,:); # variable descriptions
C(1:Drows,:) = [];
else
D = {};
endif
if (Urows)
U = C(1:Urows,:); # variable units
C(1:Urows,:) = [];
else
U = {};
endif
## After this point C contains only data
## Construct table
tbl = cell2tbl (C, T, N, D, U, RowNames);
endif
## Parse optional Name-Value paired arguments
optNames = {'NumHeaderLines', 'VariableNames', 'ReadVariableNames', ...
'VariableNamingRule', 'VariableNamesLine', 'VariableTypes', ...
'VariableUnitsLine', 'VariableDescriptionsLine', ...
'ReadRowNames', 'RowNamesColumn', 'TextType', ...
'DatetimeType', 'DurationType', 'HexType', 'Delimiter'};
dfValues = {0, {}, true, 'modify', 1, {}, 0, 0, true, 1, 'char', ...
'datetime', 'duration', 'auto', ','};
[numHeaderLines, varNames, readVarNames, varNamingRule, varNamesLine, ...
varTypes, varUnitsLine, varDescrLine, readRowNames, rowNamesColumn, ...
textType, datetimeType, durationTypes, hexType, delim, args] = ...
parsePairedArguments (optNames, dfValues, varargin(:));
## Apply optional arguments to CSV files with vartype header
if (Trows > 0)
if (numHeaderLines)
tbl(1:numHeaderLines,:) = [];
endif
if (! isempty (varNames))
tbl = tbl(:,varNames);
endif
if (! readRowNames)
tbl.Properties.RowNames = [];
endif
return
endif
## After this point handle generic CSV file
## Remove unnecessary header lines
if (numHeaderLines)
C(1:numHeaderLines,:) = [];
endif
## Read row names
has_RowNames = false;
if (readRowNames && rowNamesColumn)
has_RowNames = true;
RowNames = C(:,rowNamesColumn);
## Force RowNames into cellstr
if (! iscellstr (RowNames))
RowNames = cellstr (string (RowNames));
endif
## Remove RowNames column from data
C(:,rowNamesColumn) = [];
endif
## Read variable names, descriptions, and units from their respective lines.
## All line numbers refer to the same frame, so the values are read first and
## the consumed header rows are removed together below -- removing them one at
## a time would shift the indices of the lines still to be read.
cols = size (C, 2);
if (readVarNames && varNamesLine)
N = C(varNamesLine,:);
isnum = cellfun ('isnumeric', N);
N(isnum) = cellfun ('num2str', N(isnum), "UniformOutput", false);
## Force to valid variable names
if (strcmpi (varNamingRule, 'modify'))
N = matlab.lang.makeValidName (N);
endif
else # Generate default variable names
N = arrayfun (@(x) sprintf ("Var%d", x), [1:cols], "UniformOutput", false);
endif
## Override variable names with user supplied
if (! isempty (varNames))
N = varNames;
endif
## Read variable descriptions and units
if (varDescrLine)
D = C(varDescrLine,:);
## Force variable descriptions into cellstr
if (! iscellstr (D))
D = cellstr (string (D));
endif
endif
if (varUnitsLine)
U = C(varUnitsLine,:);
## Force variable units into cellstr
if (! iscellstr (U))
U = cellstr (string (U));
endif
endif
## Remove all consumed header rows from data and RowNames at once
droprows = [];
if (readVarNames && varNamesLine)
droprows = [droprows, varNamesLine];
endif
if (varDescrLine)
droprows = [droprows, varDescrLine];
endif
if (varUnitsLine)
droprows = [droprows, varUnitsLine];
endif
droprows = unique (droprows);
if (! isempty (droprows))
C(droprows,:) = [];
if (has_RowNames)
RowNames(droprows,:) = [];
endif
endif
## Check that RowNames are unique
if (has_RowNames)
if (numel (unique (RowNames)) != numel (RowNames))
error ("csv2table: 'RowNames' must be unique.");
endif
endif
## Parse columns into variables with user defined variable types
varValues = cell (1, cols);
if (! isempty (varTypes))
if (numel (varTypes) != cols)
error ("csv2table: 'VariableTypes' do not match columns in CSV.");
endif
for ix = 1:cols
varValues{ix} = cell2var (C(:,ix), varTypes{ix});
endfor
## Parse columns into variables by identifying the variable type
else
for ix = 1:cols
varValues{ix} = cell2auto (C(:,ix), textType, datetimeType, ...
durationTypes, hexType);
endfor
endif
## Create table
if (has_RowNames)
tbl = table (varValues{:}, 'VariableNames', N, 'RowNames', RowNames);
else
tbl = table (varValues{:}, 'VariableNames', N);
endif
## Add variable descriptions and units
if (varDescrLine)
tbl.Properties.VariableDescriptions = D;
endif
if (varUnitsLine)
tbl.Properties.VariableUnits = U;
endif
endfunction
function varValue = cell2var (C, T)
## Numeric vartypes
numvartype = {'double', 'single', 'int8', 'uint8', 'int16', ...
'uint16', 'int32', 'uint32', 'int64', 'uint64'};
if (strcmp (T, "cell"))
varValue = C;
elseif (strcmp (T, "logical"))
varValue = logical (cell2mat (C));
elseif (ismember (T, numvartype))
## Cast each element to the declared type directly. Large integers may
## have been read as int64/uint64 (to avoid double precision loss); casting
## the whole cell2mat result would let a mixed signed/unsigned column be
## promoted to a type that drops some values, so cast element-wise instead.
if (all (cellfun (@(x) isa (x, 'double'), C(:))))
varValue = cast (cell2mat (C), T);
else
varValue = cellfun (@(x) cast (x, T), C);
endif
elseif (strcmp (T, "calendarDuration"))
warning ("csv2table: 'calendarDuration' strings are not converted.");
varValue = C;
elseif (strcmp (T, "categorical"))
warning ("csv2table: 'categorical' strings are not converted.");
varValue = C;
elseif (strncmp (T, "datetime", 8))
## A zone-aware datetime carries its TimeZone after 'datetime '; the date
## strings are the wall-clock time in that zone.
tzargs = {};
if (numel (T) > 9)
tzargs = {'TimeZone', T(10:end)};
endif
## A 'NaT' token cannot be parsed alongside date strings (the format
## cannot be inferred), so reconstruct missing entries explicitly. This
## mirrors how a 'NaN' token round-trips for a duration variable.
isNaT = strcmp (strtrim (C), 'NaT');
if (any (isNaT(:)))
varValue = NaT (size (C, 1), size (C, 2), tzargs{:});
if (! all (isNaT(:)))
varValue(! isNaT) = datetime (C(! isNaT), tzargs{:});
endif
else
varValue = datetime (C, tzargs{:});
endif
elseif (strcmp (T, "duration"))
varValue = duration (C);
elseif (strcmp (T, "string"))
varValue = string (C);
endif
endfunction
function tbl = cell2tbl (C, T, N, D, U, RowNames);
## Get names, number, and positions of top level variables
[varNames, ii, varIdx] = __unique__ (N(1,:), 'stable');
varlen = numel (ii);
varValues = cell (1, varlen);
## No nested table or structure
if (size (T, 1) == 1)
for ix = 1:varlen
colIdx = varIdx == ix;
varC = C(:,colIdx);
varValues{ix} = cell2var (varC, T{ii(ix)});
endfor
## Table contains nested tables or structures
else
## For each top level variable search for nested tables or structures
for ix = 1:varlen
colIdx = varIdx == ix;
varC = C(:,colIdx);
varN = N(:,colIdx);
varT = T(:,colIdx);
## No nested table or structure in this variable
if (all (__ismissing__ (varT(2,:))))
varValues{ix} = cell2var (varC, varT{1});
## Check for structure
elseif (all (strcmp (varT(1,:), 'struct')))
varValues{ix} = cell2struct (varC, varN(2,:), 2);
## Check for table
elseif (all (strcmp (varT(1,:), 'table')))
## Pass the nested descriptions/units (rows below the top-level one)
## down so the recursive call restores them on the inner table.
if (isempty (D))
varD = [];
else
varD = D(2:end,colIdx);
endif
if (isempty (U))
varU = [];
else
varU = U(2:end,colIdx);
endif
varValues{ix} = cell2tbl (varC, varT(2:end,:), varN(2:end,:), ...
varD, varU, []);
endif
endfor
endif
## Create table
if (isempty (RowNames))
tbl = table (varValues{:}, 'VariableNames', varNames);
else
tbl = table (varValues{:}, 'VariableNames', varNames, 'RowNames', RowNames);
endif
## Restore variable descriptions and units, when present. The first header
## row holds each top-level variable's metadata (deeper rows belong to nested
## tables and are restored by the recursive calls above). Multicolumn
## variables repeat the entry across split columns, so take the first column
## belonging to each variable.
if (! isempty (D))
tbl.Properties.VariableDescriptions = D(1,ii);
endif
if (! isempty (U))
tbl.Properties.VariableUnits = U(1,ii);
endif
endfunction
function varValue = cell2auto (C, textType, datetimeType, durationTypes, ...
hexType)
## Index empty cells
idx = cellfun ('isempty', C);
## Numeric columns are returned as doubles, unless they hold large integers
## that were read as int64/uint64 to avoid double precision loss.
if (all (cellfun ('isnumeric', C)))
if (all (cellfun (@(x) isa (x, 'double'), C)))
varValue = cell2mat (C);
elseif (any (cellfun (@(x) isa (x, 'int64'), C)))
varValue = cellfun (@(x) int64 (x), C); # a negative large integer present
else
varValue = cellfun (@(x) uint64 (x), C);
endif
elseif (all (cellfun ('isnumeric', C(! idx))))
C(idx) = NaN;
varValue = cell2mat (C);
## Mixed cells are forced to text
elseif (! iscellstr (C))
if (strcmpi (textType, 'char'))
varValue = cellstr (C);
else
varValue = string (C);
endif
else # cellstr
## Each detection is attempted in turn and stops at the first success, so a
## later attempt never clobbers an already-recognised datetime or duration.
is_datetime = false;
is_duration = false;
is_hex = false;
## Check for datetime strings
if (strcmpi (datetimeType, 'datetime'))
try
varValue = datetime (C);
is_datetime = true;
catch
is_datetime = false;
end_try_catch
endif
## Check for duration strings
if (! is_datetime && strcmpi (durationTypes, 'duration'))
try
varValue = duration (C);
is_duration = true;
catch
is_duration = false;
end_try_catch
endif
## Check for hexadecimal strings (convert to integers)
if (! is_datetime && ! is_duration && ! strcmpi (hexType, 'text'))
hexval = hex2dec (C);
if (any (isnan (hexval)))
is_hex = false;
else
is_hex = true;
varValue = hexval;
## Detect smallest integer type or cast user defined
if (strcmpi (hexType, 'auto'))
minval = min (varValue);
maxval = max (varValue);
if (minval < 0) # signed integers
if (minval >= intmin ('int8') && maxval <= intmax ('int8'))
varValue = cast (varValue, 'int8');
elseif (minval >= intmin ('int16') && maxval <= intmax ('int16'))
varValue = cast (varValue, 'int16');
elseif (minval >= intmin ('int32') && maxval <= intmax ('int32'))
varValue = cast (varValue, 'int32');
elseif (minval >= intmin ('int64') && maxval <= intmax ('int64'))
varValue = cast (varValue, 'int64');
endif
else # unsigned integers
if (maxval <= intmax ('uint8'))
varValue = cast (varValue, 'uint8');
elseif (maxval <= intmax ('uint16'))
varValue = cast (varValue, 'uint16');
elseif (maxval <= intmax ('uint32'))
varValue = cast (varValue, 'uint32');
elseif (maxval <= intmax ('uint64'))
varValue = cast (varValue, 'uint64');
endif
endif
else
varValue = cast (varValue, hexType);
endif
endif
endif
## Leave it unaltered as cellstr or convert to strings
if (! is_datetime && ! is_duration && ! is_hex)
varValue = C;
if (strcmpi (textType, 'string'))
varValue = string (varValue);
endif
endif
endif
endfunction
%!demo
%! ## `csv2table` reads a CSV back into a table. When the file was written by
%! ## `table2csv`, the typed header lets it restore each variable's type exactly.
%!
%! T = table ([38; 43], [71.5; 69.0], 'VariableNames', {'Age', 'Height'});
%! filename = fullfile (tempdir (), 'patients.csv');
%! table2csv (T, filename);
%! csv2table (filename)
%!demo
%! ## For a plain CSV that has no type header, the first line is taken as the
%! ## variable names and each column's type is detected automatically. Use
%! ## `'ReadRowNames'` to turn the first column into row names instead of data.
%!
%! filename = fullfile (tempdir (), 'plain.csv');
%! fid = fopen (filename, 'w');
%! fputs (fid, "Patient,Age,Height\nLi,38,64\nDiaz,40,67\n");
%! fclose (fid);
%! csv2table (filename, 'ReadRowNames', true)
%!
%! delete (filename);
## Test user-defined 'VariableTypes' are applied per column
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B,C\n1,2.5,10\n3,4.5,20\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false, ...
%! 'VariableTypes', {'double', 'single', 'int32'});
%! assert_equal (class (t{:, 1}), 'double');
%! assert_equal (class (t{:, 2}), 'single');
%! assert_equal (class (t{:, 3}), 'int32');
%! assert_equal (t{:, 3}, int32 ([10; 20]));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
%!error ...
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B,C\n1,2,3\n");
%! fclose (fid);
%! unwind_protect
%! csv2table (fn, 'ReadRowNames', false, 'VariableTypes', {'double', 'double'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test a generic CSV (no vartype header) reads names and auto-detects types
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B,C\n1,2.5,foo\n3,4.5,bar\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'A', 'B', 'C'});
%! assert_equal (t.A, [1; 3]);
%! assert_equal (t.B, [2.5; 4.5]);
%! assert_equal (t.C, {'foo'; 'bar'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'ReadVariableNames' false generates default Var1, Var2, ... names
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "1,2\n3,4\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadVariableNames', false, 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'Var1', 'Var2'});
%! assert_equal (height (t), 2);
%! assert_equal (t.Var1, [1; 3]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'VariableNames' overrides the names read from the header line
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B\n1,2\n3,4\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'VariableNames', {'x', 'y'}, 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'x', 'y'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'NumHeaderLines' skips leading lines before the header row
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "junk,more\nA,B\n1,2\n3,4\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'NumHeaderLines', 1, 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'A', 'B'});
%! assert_equal (t.A, [1; 3]);
%! assert_equal (t.B, [2; 4]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'RowNamesColumn' reads a column as the table row names
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "id,v\nr1,10\nr2,20\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', true, 'RowNamesColumn', 1);
%! assert_equal (t.Properties.RowNames, {'r1'; 'r2'});
%! assert_equal (t.v, [10; 20]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'TextType' string returns text columns as a string array
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B\nfoo,bar\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'TextType', 'string', 'ReadRowNames', false);
%! assert_equal (class (t.A), 'string');
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test 'VariableUnitsLine' and 'VariableDescriptionsLine' read the right lines
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A,B\nkg,m\nd1,d2\n1,2\n3,4\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'VariableUnitsLine', 2, 'VariableDescriptionsLine', 3, ...
%! 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableUnits, {'kg', 'm'});
%! assert_equal (t.Properties.VariableDescriptions, {'d1', 'd2'});
%! assert_equal (t.A, [1; 3]);
%! assert_equal (t.B, [2; 4]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test hexadecimal columns auto-detect to the smallest integer type
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "h\nFF\n0A\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (class (t.h), 'uint8');
%! assert_equal (t.h, uint8 ([255; 10]));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test header names with spaces are made into valid variable names
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "my col,other one\n1,2\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'myCol', 'otherOne'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test a generic CSV whose first cell is numeric does not error on read
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "10,20\n30,40\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadVariableNames', false, 'ReadRowNames', false);
%! assert_equal (height (t), 2);
%! assert_equal (t.Var1, [10; 30]);
%! assert_equal (t.Var2, [20; 40]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test duplicate row names are rejected
%!error ...
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "id,v\nr1,10\nr1,20\n");
%! fclose (fid);
%! unwind_protect
%! csv2table (fn, 'ReadRowNames', true, 'RowNamesColumn', 1);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test a large integer column is read exactly as a 64-bit integer (no double loss)
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "v\n18446744073709551615\n18446744073709551614\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (class (t.v), 'uint64');
%! assert_equal (t.v, [intmax('uint64'); intmax('uint64') - uint64(1)]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Test NAME input validation
%!error ...
%! csv2table (42);
## Test reading a non-existent file reports a clear error
%!error ...
%! csv2table (fullfile (tempname (), 'no_such_file.csv'));
## Test the 'Delimiter' option selects the field separator
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "A;B;C\n1;2.5;foo\n3;4.5;bar\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'Delimiter', ';', 'ReadRowNames', false);
%! assert_equal (t.Properties.VariableNames, {'A', 'B', 'C'});
%! assert_equal (t.A, [1; 3]);
%! assert_equal (t.C, {'foo'; 'bar'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## A datetime column is not clobbered by the later duration/hex detection
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "id,d\n1,2024-01-15\n2,2024-02-20\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (class (t.d), 'datetime');
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Hexadecimal auto-detection still works after the detection-order fix
%!test
%! fn = tempname ();
%! fid = fopen (fn, "w");
%! fputs (fid, "h\nFF\n0A\n");
%! fclose (fid);
%! unwind_protect
%! t = csv2table (fn, 'ReadRowNames', false);
%! assert_equal (t.h, uint8 ([255; 10]));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
pr0m1th3as-datatypes-9c9a8d3/inst/datetime.m 0000664 0000000 0000000 00000555323 15227665741 0021021 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
classdef datetime
## -*- texinfo -*-
## @deftp {datatypes} datetime
##
## Array representing points in time using the Gregorian calendar.
##
## A @qcode{datetime} array stores internally the datetime points as double
## arrays representing whole years, months, days, hours, and minutes, as well
## as seconds including their fractional part. The underlying implementation
## relies on the @qcode{'date.h'} C++ library. The precision of this
## implementation is set at microseconds, which is substantial for typical
## times.
##
## A @code{datetime} array is a collection of date/time elements, with each
## element holding a complete date/time. The @code{datetime} array also has
## @qcode{TimeZone} and @qcode{Format} properties associated with it, which
## apply to all elements in the array.
##
## @seealso{calendarDuration, duration}
## @end deftp
properties (Constant)
## -*- texinfo -*-
## @deftp {datetime} {property} SystemTimeZone
##
## System time zone setting
##
## A read-only property specifying the local time zone of the system, where
## Octave is running.
##
## @end deftp
SystemTimeZone = localtime (time ()).zone;
endproperties
properties (Access = private, Hidden)
## Whole years
Year = 0
## Whole months
Month = 0
## Whole days
Day = 0
## Whole hours
Hour = 0
## Whole minutes
Minute = 0
## Seconds (including fractional seconds)
Second = 0
endproperties
properties
## -*- texinfo -*-
## @deftp {datetime} {property} Format
##
## Display format
##
## Display format, specified as a character vector or string scalar. If
## specified as a string scalar, it is converted and stored internally as
## a character vector.
##
## @end deftp
Format = 'default'
## -*- texinfo -*-
## @deftp {datetime} {property} TimeZone
##
## Time zone
##
## Time zone, specified as a character vector or string scalar. If
## specified as a string scalar, it is converted and stored internally as
## a character vector.
##
## @end deftp
TimeZone = ''
endproperties
methods (Hidden)
## Custom display
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, 'datetime', in_name);
endfunction
## Custom display
function disp (this)
__disp__ (this, 'datetime');
endfunction
endmethods
################################################################################
## ** Create and convert 'datetime' type ** ##
################################################################################
## Available Methods ##
## ##
## 'datetime' 'dispstrings' 'cellstr' 'char' ##
## 'ymd' 'hms' 'year' 'quarter' ##
## 'month' 'week' 'day' 'hour' ##
## 'minute' 'second' 'timeofday' 'tzoffset' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{T} =} datetime (@qcode{'now'})
## @deftypefnx {datetime} {@var{T} =} datetime (@qcode{'today'})
## @deftypefnx {datetime} {@var{T} =} datetime (@qcode{'tomorrow'})
## @deftypefnx {datetime} {@var{T} =} datetime (@qcode{'yesterday'})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{DateStrings})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{DateStrings}, @qcode{'InputFormat'}, @var{INFMT})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{DateStrings},@
## @qcode{'InputFormat'}, @var{INFMT}, @qcode{'PivotYear'}, @var{PIVOT})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{DateVectors})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{Y}, @var{MO}, @var{D})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}, @var{S})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI}, @var{S}, @var{MS})
## @deftypefnx {datetime} {@var{T} =} datetime (@var{X}, @qcode{'ConvertFrom'}, @var{TYPE})
## @deftypefnx {datetime} {@var{T} =} datetime (@dots{}, @qcode{'Format'}, @var{FMT})
## @deftypefnx {datetime} {@var{T} =} datetime (@dots{}, @qcode{'TimeZone'}, @var{TZ})
##
## Create a new array of datetime values.
##
## @code{@var{T} = datetime (@qcode{'now'})} returns a scalar datetime array
## corresponding to the current date and time. @code{@var{T} = datetime
## (@qcode{'now'})} is the same as @code{@var{T} = datetime ()}. Except for
## @qcode{'now'}, the same syntax can be used with @qcode{'today'},
## @qcode{'tomorrow'} and @qcode{'yesterday'}. These options return the
## respective date but with time set at midnight.
##
## @code{@var{T} = datetime (@var{DateStrings})} creates a datetime array
## from the text in @var{DateStrings} representing points in time. In
## current implementation, @var{DateStrings} are parsed by Octave's core
## @code{datevec} function, hence supported text formats are currently those
## supported by @code{datevec}.
##
## @code{@var{T} = datetime (@var{DateStrings}, @qcode{'InputFormat'},
## @var{INFMT})} also allows to specify a particular input text format to
## parse @var{DateStrings}. It is always preferable to specify the format
## @var{INFMT} if it is known. Formats which do not specify a particular
## time component will have the value set to zero. Formats which do not
## a date will default to January 1st of the current year.
##
## @code{@var{T} = datetime (@var{DateStrings}, @qcode{'InputFormat'},
## @var{INFMT}, @qcode{'PivotYear'}, @var{PIVOT})} also allows to specify a
## pivot year, which refers to the year at the start of the century to which
## two-digit years will be referenced. When not specified, it defaults to
## the current years minus 50.
##
## @code{@var{T} = datetime (@var{DateVectors})} creates a column vector of
## datetime values from the date vectors in @var{DateVectors}.
##
## @code{@var{T} = datetime (@var{Y}, @var{MO}, @var{D}} creates an array of
## datetime values for corresponding elements of the @var{Y}, @var{MO}, and
## @var{D} arrays, which must be of the same size or scalars, must contain
## integer values, and they correspond to years, months, and days,
## respectively.
##
## @code{@var{T} = datetime (@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI},
## @var{S})} also adds time components to the constructed datetime arrays.
## @var{H}, @var{MI}, and @var{S} must be of the same size or scalars.
## @var{H} and @var{MI} must contain integer values, whereas @var{S} may
## also contain a fractional part.
##
## @code{@var{T} = datetime (@var{Y}, @var{MO}, @var{D}, @var{H}, @var{MI},
## @var{S}, @var{MS})} also adds a milliseconds component, @var{MS}, which
## may also have a fractional part.
##
## @code{@var{T} = datetime (@var{X}, @qcode{'ConvertFrom'}, @var{TYPE})}
## converts the numeric values in @var{X} to a datetime array according to
## the data type specified by @var{TYPE}. The following types are
## supported:
##
## @itemize
## @item @qcode{'datenum'}
## @item @qcode{'excel'}
## @item @qcode{'posixtime'}
## @item @qcode{'epochtime'}
## @end itemize
##
## @code{@var{T} = datetime (@dots{}, @qcode{'Format'}, @var{FMT})}
## specifies the display format of the values in the output datetime array.
## Currently, only the default display format is implemented.
##
## @code{@var{T} = datetime (@dots{}, @qcode{'TimeZone'}, @var{TZ})} sets
## the time zone to the values in the output datetime array. If not
## specified, the computer's local timezone is used. Supported time zones
## are specified in the IANA's Time Zone Database. You may specify a new
## time zone by setting the @qcode{'TimeZone'} property of the datetime
## array, in which case the new datetime values may include Daylight Saving
## Time (DST) in their computation.
##
## @seealso{NaT, datetime, isdatetime, calendarDuration, duration}
## @end deftypefn
function this = datetime (varargin)
## Return an scalar datetime object with current local time
if (nargin == 0)
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ ('now');
return;
endif
## Parse optional Name-Value paired arguments
optNames = {'ConvertFrom', 'Format', 'InputFormat', ...
'Locale', 'PivotYear', 'TimeZone'};
dfValues = {[], [], [], [], [], []};
[ConvertFrom, Format, inputFormat, Locale, PivotYear, TimeZone, args] =...
parsePairedArguments (optNames, dfValues, varargin(:));
## Check optional 'Format' and 'InputFormat' arguments
if (! isempty (ConvertFrom))
## Call __datetime__ to check for valid ConvertFrom string and
## data input
[~,~,~,~,~,~,errmsg] = __datetime__ (args{:}, 'ConvertFrom', ...
ConvertFrom);
if (! isnumeric (errmsg))
error ("datetime: %s ", errmsg);
elseif (! isempty (inputFormat))
error ("datetime: 'ConvertFrom' cannot be used with 'InputFormat'.");
endif
endif
if (! isempty (Format))
if (! (ischar (Format) && isvector (Format)))
error ("datetime: 'Format' must be a character vector.");
endif
this.Format = Format;
endif
if (! isempty (inputFormat))
if (! (ischar (inputFormat) && isvector (inputFormat)))
error ("datetime: 'InputFormat' must be a character vector.");
elseif (! isempty (ConvertFrom))
error ("datetime: 'InputFormat' cannot be used with 'ConvertFrom'.");
elseif (strcmpi (this.Format, 'preserveinput'))
this.Format = inputFormat;
endif
endif
if (! isempty (Locale))
if (! (ischar (Locale) && isvector (Locale)))
error ("datetime: 'Locale' must be a character vector.");
else
warning ("datetime: 'Locale' is currently unimplemented.");
endif
endif
if (! isempty (PivotYear))
if (isempty (inputFormat))
error ("datetime: 'PivotYear' can only be used with 'InputFormat'.");
elseif (! (isnumeric (PivotYear) && isscalar (PivotYear)))
error ("datetime: 'PivotYear' must be a numeric scalar.");
elseif (fix (PivotYear) != PivotYear)
error ("datetime: 'PivotYear' must be an integer value.");
endif
endif
if (! isempty (TimeZone))
## Call __datetime__ to check for valid timezone string
[~,~,~,~,~,~,errmsg] = __datetime__ (0, 0, 0, 'TimeZone', TimeZone);
if (! isnumeric (errmsg))
error ("datetime: %s ", errmsg);
endif
this.TimeZone = TimeZone;
endif
## Datestrings are currently handled by 'datevec'
if (iscellstr (args{1}) || isstring (args{1}) || ischar (args{1}))
DateStrings = "";
if (ischar (args{1}) && ! isvector (args{1}))
error ("datetime: invalid type for 'DateStrings'.");
elseif (ischar (args{1}) && !
any (strcmpi (args, {'now', 'today', 'yesterday', 'tomorrow'})))
DateStrings = cellstr (args{1});
elseif (! ischar (args{1}))
DateStrings = cellstr (args{1});
endif
if (! isempty (DateStrings))
if (! isempty (inputFormat) && ! isempty (PivotYear))
fcn = @(x) datevec (x, inputFormat, PivotYear);
elseif (! isempty (inputFormat) && isempty (PivotYear))
fcn = @(x) datevec (x, inputFormat);
elseif (isempty (inputFormat) && ! isempty (PivotYear))
fcn = @(x) datevec (x, PivotYear);
else
fcn = @(x) datevec (x);
endif
try
DATEVEC = cellfun (fcn, DateStrings, "UniformOutput", false);
DATEVEC = cell2mat (DATEVEC(:));
catch
if (! isempty (inputFormat))
error ("datetime: invalid 'inputFormat'.");
else
error (strcat ("datetime: could not recognize date/time", ...
" format from input."));
endif
end_try_catch
## Split DATEVEC into individual date/time units and reshape
this.Year = reshape (DATEVEC(:,1), size (DateStrings));
this.Month = reshape (DATEVEC(:,2), size (DateStrings));
this.Day = reshape (DATEVEC(:,3), size (DateStrings));
this.Hour = reshape (DATEVEC(:,4), size (DateStrings));
this.Minute = reshape (DATEVEC(:,5), size (DateStrings));
this.Second = reshape (DATEVEC(:,6), size (DateStrings));
return;
endif
endif
## Handle inputs (no errors here)
if (! isempty (ConvertFrom) && ! isempty (TimeZone))
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ (args{1}, 'ConvertFrom', ConvertFrom, ...
'TimeZone', TimeZone);
elseif (! isempty (ConvertFrom) && isempty (TimeZone))
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ (args{1}, 'ConvertFrom', ConvertFrom);
else
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ (args{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{cstr} =} dispstrings (@var{T})
##
## Get display formatted strings for each element of a datetime object.
##
## @code{@var{cstr} = dispstrings (@var{T})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## datetime @var{T}.
##
## @end deftypefn
function cstr = dispstrings (this)
## Default display format
mnames = {'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', ...
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'};
## Process all elements
sz = size (this);
cstr = cell (sz);
for i = 1:prod (sz)
if (isnan (this.Year(i)))
cstr{i} = 'NaT';
elseif (isinf (this.Year(i)))
cstr{i} = num2str (this.Year(i));
else
if (this.Hour(i) != 0 || this.Minute(i) != 0 || this.Second(i) != 0)
if (fix (this.Second(i)) == this.Second(i))
str = sprintf ("%02d-%s-%04d %02d:%02d:%02d", this.Day(i), ...
mnames{this.Month(i)}, this.Year(i), ...
this.Hour(i), this.Minute(i), this.Second(i));
else
fmt = "%02d-%s-%04d %02d:%02d:%02d.%03d";
sec = this.Second(i);
str = sprintf (fmt, this.Day(i), mnames{this.Month(i)}, ...
this.Year(i), this.Hour(i), this.Minute(i), ...
fix (sec), rem (sec, 1) * 1000);
endif
else
str = sprintf ("%02d-%s-%04d", this.Day(i), ...
mnames{this.Month(i)}, this.Year(i));
endif
cstr{i} = str;
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{cstr} =} cellstr (@var{T})
## @deftypefnx {datetime} {@var{cstr} =} cellstr (@var{T}, @var{Format})
##
## Convert datetime array to a cell array of character vectors.
##
## @code{@var{cstr} = cellstr (@var{T})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## datetime @var{T}.
##
## @end deftypefn
function cstr = cellstr (this, Format = '')
if (! isempty (Format))
if (! (ischar (Format) && isvector (Format)))
error ("datetime.cellstr: FORMAT must be a character vector.");
endif
this.Format = Format;
endif
cstr = dispstrings (this);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{cmat} =} char (@var{T})
## @deftypefnx {datetime} {@var{cmat} =} char (@var{T}, @var{Format})
##
## Convert datetime array to a character matrix.
##
## @code{@var{cmat} = char (@var{T})} returns a character matrix with one
## row per element in @var{T}.
##
## @end deftypefn
function cmat = char (this, Format = '')
cmat = char (cellstr (this, Format));
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {[@var{Y}, @var{M}, @var{D}] =} ymd (@var{T})
##
## Year, Month, and Day components of datetime array.
##
## @code{[@var{Y}, @var{M}, @var{D}] = ymd (@var{T})} returns the year,
## month, and day components of the corresponding datetime values in @var{T}
## as separate numeric arrays. @var{Y}, @var{M}, @var{D} contain integer
## values and have the same size as @var{T}. Not-A-Time (@qcode{NaT})
## values in @var{T} are returned as @qcode{NaN} in the output arrays.
##
## @end deftypefn
function [Y, M, D] = ymd (this)
Y = this.Year;
M = this.Month;
D = this.Day;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {[@var{h}, @var{m}, @var{s}] =} hms (@var{T})
##
## Hour, Minute, and Second components of a datetime array.
##
## @code{[@var{h}, @var{m}, @var{s}] = hms (@var{T})} returns the hour,
## minute, and second components of the corresponding datetime values in
## @var{T} as separate numeric arrays. @var{h} and @var{m} contain integer
## values and @var{s} may also contain a fractional part. All outputs have
## the same size as @var{T}. Not-A-Time (@qcode{NaT}) values in @var{T} are
## returned as @qcode{NaN} in the output arrays.
##
## @end deftypefn
function [h, m, s] = hms (this)
h = this.Hour;
m = this.Minute;
s = this.Second;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{Y} =} year (@var{T})
##
## Year component of a datetime array.
##
## @code{@var{Y} = year (@var{T})} returns the year number for each element
## of the input datetime array @var{T}. The output @var{Y} is a
## @qcode{double} array and it has the same size as @var{T}. Not-A-Time
## (@qcode{NaT}) values in @var{T} are returned as @qcode{NaN} in the output
## array.
##
## @end deftypefn
function out = year (this)
out = this.Year;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{Q} =} quarter (@var{T})
##
## Quarter component of a datetime array.
##
## @code{@var{Q} = quarter (@var{T})} returns the quarter number for each
## element of the input datetime array @var{T}. The output @var{Q} is a
## @qcode{double} array containing integer values in the range @math{[1, 4]}
## and it has the same size as @var{T}. Not-A-Time (@qcode{NaT}) values in
## @var{T} are returned as @qcode{NaN} in the output array.
##
## @end deftypefn
function out = quarter (this)
out = ceil (this.Month / 3);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} month (@var{T})
## @deftypefnx {datetime} {@var{M} =} month (@var{T}, @var{monthType})
##
## Month component of a datetime array.
##
## @code{@var{M} = month (@var{T})} returns the month number for each
## element of the input datetime array @var{T}. The output @var{M} is a
## @qcode{double} array containing integer values in the range
## @math{[1, 12]} and it has the same size as @var{T}. Not-A-Time
## (@qcode{NaT}) values in @var{T} are returned as @qcode{NaN} in the output
## array.
##
## @code{@var{M} = month (@var{T}, @var{monthType})} returns the month
## number or name for each element of the input datetime array @var{T} as
## specified by @var{monthType}, which may have any of the following
## options:
##
## @itemize
## @item @qcode{'monthofyear'} (default) returns the month number in a
## numeric array.
## @item @qcode{'name'} returns the corresponding full name of the month in
## a cell array of character vectors.
## @item @qcode{'shortname'} returns the corresponding 3-letter abbreviation
## of the month in a cell array of character vectors.
## @end itemize
##
## @end deftypefn
function out = month (this, type = 'monthofyear')
if (strcmpi (type, 'monthofyear'))
out = this.Month;
elseif (strcmpi (type, 'name'))
mn = {'January', 'February', 'March', 'April', 'May', 'June', ...
'July', 'August', 'September', 'October', 'November', 'December'};
out = mn(this.Month);
elseif (strcmpi (type, 'shortname'))
mn = {'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', ...
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'};
out = mn(this.Month);
else
error ("datetime: unrecognized MONTHTYPE.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{D} =} day (@var{T})
## @deftypefnx {datetime} {@var{D} =} day (@var{T}, @var{dayType})
##
## Day component of a datetime array.
##
## @code{@var{D} = day (@var{T})} returns the day number for each element of
## the input datetime array @var{T}. The output @var{D} is a @qcode{double}
## array containing integer values in the range @math{[1, 31]}, depending on
## the month and year, and it has the same size as @var{T}. Not-A-Time
## (@qcode{NaT}) values in @var{T} are returned as @qcode{NaN} in the output
## array.
##
## @code{@var{D} = day (@var{T}, @var{dayType})} returns the day number or
## name for each element of the input datetime array @var{T} as specified by
## @var{dayType}, which may have any of the following options:
##
## @itemize
## @item @qcode{'dayofmonth'} (default) returns the day-of-month number in a
## numeric array. Depending on the month and year, it can range from 1 to
## 28, 29, 30, or 31.
## @item @qcode{'dayofweek'} returns the day-of-week number in a numeric
## array of @qcode{double} integer values ranging from 1 to 7, where 1
## corresponds to Sunday.
## @item @qcode{'iso-dayofweek'} returns the day-of-week number in a numeric
## array of @qcode{double} integer values ranging from 1 to 7, where 1
## corresponds to Monday according to the ISO 8601 standard.
## @item @qcode{'dayofyear'} returns the day-of-year number in a numeric
## array of @qcode{double} integer values ranging from 1 to 365 or 366,
## depending on the year.
## @item @qcode{'name'} returns the corresponding full name of the day in
## a cell array of character vectors.
## @item @qcode{'shortname'} returns the corresponding 3-letter abbreviation
## of the day in a cell array of character vectors.
## @end itemize
##
## @end deftypefn
function out = day (this, type = 'dayofmonth')
vtypes = {'dayofweek', 'iso-dayofweek', 'name', 'shortname'};
if (strcmpi (type, 'dayofmonth'))
out = this.Day;
elseif (any (strcmpi (type, vtypes)))
m = this.Month - 2;
y = this.Year;
## Compute the Jan/Feb borrow mask once, before mutating 'm'; adjusting
## 'm' first would clear the mask before 'y' is decremented.
janfeb = m < 1;
m(janfeb) += 12;
y(janfeb) -= 1;
K = mod (y, 100);
J = floor (y ./ 100);
code = floor ((26 .* m - 2) ./ 10);
out = mod ((this.Day + code + K + floor (K ./ 4) ...
+ floor (J ./ 4) + 5 .* J), 7) + 1;
if (strcmpi (type, 'iso-dayofweek'))
out = mod (out - 1, 7);
out(out == 0) = 7;
elseif (strcmpi (type, 'name'))
dn = {'Sunday', 'Monday', 'Tuesday', 'Wednesday', ...
'Thursday', 'Friday', 'Saturday'};
out = dn(out);
elseif (strcmpi (type, 'shortname'))
dn = {'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'};
out = dn(out);
endif
elseif (strcmpi (type, 'dayofyear'))
m = this.Month;
y = this.Year;
## Column vector so that logical-indexed lookups keep column shape.
cumdays = [0; 31; 59; 90; 120; 151; 181; 212; 243; 273; 304; 334];
isly = mod (y, 4) == 0 & (mod (y, 100) != 0 | mod (y, 400) == 0);
out = nan (size (m));
valid = isfinite (m) & isfinite (this.Day);
out(valid) = cumdays(m(valid)) + this.Day(valid)(:) ...
+ double (isly(valid) & m(valid) > 2)(:);
else
error ("datetime: unrecognized DAYTYPE.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{h} =} hour (@var{T})
##
## Hour component of a datetime array.
##
## @code{@var{h} = hour (@var{T})} returns the hour number for each element
## of the input datetime array @var{T}. The output @var{h} is a
## @qcode{double} array containing integer values in the range
## @math{[0, 23]} and it has the same size as @var{T}. Not-A-Time
## (@qcode{NaT}) values in @var{T} are returned as @qcode{NaN} in the output
## array.
##
## @end deftypefn
function out = hour (this)
out = this.Hour;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{m} =} minute (@var{T})
##
## Minute component of a datetime array.
##
## @code{@var{m} = minute (@var{T})} returns the minute number for each
## element of the input datetime array @var{T}. The output @var{m} is a
## @qcode{double} array containing integer values in the range
## @math{[0, 59]} and it has the same size as @var{T}. Not-A-Time
## (@qcode{NaT}) values in @var{T} are returned as @qcode{NaN} in the output
## array.
##
## @end deftypefn
function out = minute (this)
out = this.Minute;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{s} =} second (@var{T})
## @deftypefnx {datetime} {@var{s} =} second (@var{T}, @var{secondType})
##
## Seconds component of a datetime array.
##
## @code{@var{s} = second (@var{T})} returns the number of seconds for each
## element of the input datetime array @var{T}. The output @var{s} is a
## @qcode{double} array containing values in the range @math{[0, 60)},
## including any fractional part of the second, and it has the same size as
## @var{T}. Not-A-Time (@qcode{NaT}) values in @var{T} are returned as
## @qcode{NaN} in the output array.
##
## @code{@var{s} = second (@var{T}, @var{secondType})} returns the seconds
## for each element of the input datetime array @var{T} as specified by
## @var{secondType}, which may have any of the following options:
##
## @itemize
## @item @qcode{'secondofminute'} (default) returns the second of the minute
## in a numeric array, in the range @math{[0, 60)}.
## @item @qcode{'secondofday'} returns the second of the day in a numeric
## array, in the range @math{[1, 86400)}.
## @end itemize
##
## @end deftypefn
function out = second (this, secondType = 'secondofminute')
if (strcmpi (secondType, 'secondofminute'))
out = this.Second;
elseif (strcmpi (secondType, 'secondofday'))
out = this.Hour * 3600 + this.Minute * 60 + this.Second;
else
error ("datetime.second: unrecognized SECONDTYPE.");
endif
endfunction
endmethods
methods (Hidden)
function out = week (this)
error ("datetime.week: not implemented yet.");
endfunction
function out = timeofday (this)
error ("datetime.timeofday: not implemented yet.");
endfunction
function out = tzoffset (this)
error ("datetime.tzoffset: not implemented yet.");
endfunction
endmethods
################################################################################
## ** Summary Information ** ##
################################################################################
## Available Methods ##
## ##
## 'size' 'ndims' 'numel' 'length' ##
## 'keyHash' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{sz} =} size (@var{T})
## @deftypefnx {datetime} {@var{dim_sz} =} size (@var{T}, @var{dim})
## @deftypefnx {datetime} {@var{dim_sz} =} size (@var{T}, @var{d1}, @var{d2}, @dots{})
## @deftypefnx {datetime} {[@var{rows}, @var{columns}, @dots{}, @var{dim_n_sz}] =} size (@dots{})
##
## Size of a datetime array.
##
## @code{@var{sz} = size (@var{T})} returns a row vector with the size
## (number of elements) of each dimension for the datetime array @var{T}.
##
## @code{@var{dim_sz} = size (@var{T}, @var{dim})} returns the size of
## the corresponding dimension specified in @var{dim}. If @var{dim} is a
## vector, then @var{dim_sz} is a vector of the same length and with each
## element corresponding to a specified dimension. Multiple dimensions may
## also be specified as separate arguments.
##
## With a single output argument, @code{size} returns a row vector. When
## called with multiple output arguments, @code{size} returns the size of
## dimension N in the Nth argument.
##
## @end deftypefn
function varargout = size (this, varargin)
if (! isempty (varargin))
sz = size (this.Year, varargin{:});
else
sz = size (this.Year);
endif
if (nargout == 0 || nargout == 1)
varargout{1} = sz;
elseif (numel (sz) != nargout)
error (["datetime.size: nargout > 1 but does not", ...
" match number of requested dimensions."]);
else
for i = 1:nargout
varargout{i} = sz(i);
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{out} =} ndims (@var{T})
##
## Number of dimensions in a datetime array.
##
## @code{@var{out} = ndims (@var{T})} returns the number of dimensions of
## the datetime array @var{T}.
##
## @end deftypefn
function out = ndims (this)
out = ndims (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{out} =} numel (@var{T})
##
## Total number of elements in a datetime array.
##
## @code{@var{out} = numel (@var{T})} returns the number of elements in the
## datetime array @var{T}, which is the product of the sizes of its
## dimensions.
##
## @end deftypefn
function out = numel (this, varargin)
out = prod (size (this));
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{N} =} length (@var{T})
##
## Length of a datetime vector.
##
## @code{@var{N} = length (@var{T})} returns the size of the longest
## dimension of the datetime array @var{T}, unless any of its dimensions
## has zero length, in which case @code{length (@var{T})} returns 0.
##
## @end deftypefn
function N = length (this)
if (isempty (this.Year))
N = 0;
else
N = max (size (this.Year));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{hey} =} keyHash (@var{T})
##
## Generate a hash code for datetime array.
##
## @code{@var{h} = keyHash (@var{T})} generates a @qcode{uint64} scalar that
## represents the input array @var{T}. @code{keyHash} utilizes the 64-bit
## FNV-1a variant of the Fowler-Noll-Vo non-cryptographic hash function.
##
## @code{@var{h} = keyHash (@var{T}), @var{base}} also generates a 64-bit
## hash code using @var{base} as the offset basis for the FNV-1a hash
## algorithm. @var{base} must be a @qcode{uint64} integer type scalar. Use
## this syntax to cascade @code{keyHash} on multiple objects for which a
## single hash code is required.
##
## Note that unlike MATLAB, this implementation does not use any random
## seed. As a result, @code{keyHash} will always generate the exact same
## hash key for any particular input across different workers and Octave
## sessions.
##
## @end deftypefn
function key = keyHash (this, base = [])
## Initialize string with size and class name
size_str = sprintf ('%dx', size (this.Year))(1:end-1);
flag_str = sprintf ('-TZ%s:', this.TimeZone);
init_str = [size_str 'datetime' flag_str];
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("datetime.keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__(init_str, base);
else
key = __ckeyHash__(init_str);
endif
if (! isempty (this.Year))
key = __nkeyHash__(this.Year(:), key);
key = __nkeyHash__(this.Month(:), key);
key = __nkeyHash__(this.Day(:), key);
key = __nkeyHash__(this.Hour(:), key);
key = __nkeyHash__(this.Minute(:), key);
key = __nkeyHash__(this.Second(:), key);
endif
endfunction
endmethods
################################################################################
## ** Convert to other Numeric Representations ** ##
################################################################################
## Available Methods ##
## ##
## 'convertTo' 'exceltime' 'posixtime' 'juliandate' ##
## 'yyyymmdd' 'datevec' ##
## ##
################################################################################
methods (Hidden)
function out = convertTo (this, varargin)
error ("datetime.convertTo: not implemented yet.");
endfunction
function out = exceltime (this, varargin)
error ("datetime.exceltime: not implemented yet.");
endfunction
function out = posixtime (this, varargin)
error ("datetime.posixtime: not implemented yet.");
endfunction
function out = juliandate (this, varargin)
error ("datetime.juliandate: not implemented yet.");
endfunction
function out = yyyymmdd (this, varargin)
error ("datetime.yyyymmdd: not implemented yet.");
endfunction
endmethods
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{DV} =} datevec (@var{T})
##
## Convert datetime array to date vectors.
##
## @code{@var{DV} = datevec (@var{T})} returns a numeric matrix with one row
## per element in @var{T}.
##
## @end deftypefn
function varargout = datevec (this)
DV = [this.Year(:), this.Month(:), this.Day(:), ...
this.Hour(:), this.Minute(:), this.Second(:)];
if (nargout == 0 || nargout == 1)
varargout{1} = DV;
elseif (nargout <= 6)
for i = 1:nargout
varargout{i} = DV(:,i);
endfor
else
error ("datetime.datevec: too many output arguments.");
endif
endfunction
endmethods
################################################################################
## ** Query Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'isbetween' 'iscolumn' 'isdst' 'isempty' ##
## 'isequal' 'isequaln' 'isfinite' 'isinf' ##
## 'ismatrix' 'ismember' 'isnat' 'isregular' ##
## 'isrow' 'isscalar' 'issorted' 'issortedrows' ##
## 'isvector' 'isweekend' ##
## ##
################################################################################
methods (Hidden)
function TF = isdst (this)
error ("datetime.isdst: not implemented yet.");
endfunction
function TF = isregular (this)
error ("datetime.isregular: not implemented yet.");
endfunction
function TF = isweekend (this)
error ("datetime.isweekend: not implemented yet.");
endfunction
endmethods
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isbetween (@var{X}, @var{lower}, @var{upper})
## @deftypefnx {datetime} {@var{TF} =} isbetween (@var{X}, @var{lower}, @var{upper}, @var{intervalType})
##
## Determine which datetime values lie within an interval.
##
## @code{@var{TF} = isbetween (@var{X}, @var{lower}, @var{upper})} returns a
## logical array @var{TF}, the same size as the broadcast of its inputs,
## containing @qcode{true} where the element of @var{X} lies between the
## corresponding @var{lower} and @var{upper} bounds. @var{lower} and
## @var{upper} may each be a datetime array or a date/time character vector,
## string array, or cell array of character vectors, and either may be scalar
## to broadcast against @var{X}. The comparison is made on the absolute
## instant, so zoned inputs may be in different time zones. A Not-A-Time
## element in any input makes the corresponding result @qcode{false}.
##
## @code{@var{TF} = isbetween (@var{X}, @var{lower}, @var{upper},
## @var{intervalType})} selects which endpoints are included.
## @var{intervalType} is @qcode{'closed'} (the default,
## @w{@var{lower} @leq{} @var{X} @leq{} @var{upper}}), @qcode{'open'}
## (both endpoints excluded), @qcode{'openleft'} (exclude @var{lower}), or
## @qcode{'openright'} (exclude @var{upper}).
##
## @end deftypefn
function TF = isbetween (X, varargin)
if (numel (varargin) < 2)
error ("datetime.isbetween: not enough input arguments.");
endif
if (numel (varargin) > 3)
error ("datetime.isbetween: too many input arguments.");
endif
lo = varargin{1};
hi = varargin{2};
itype = 'closed';
if (numel (varargin) == 3)
itype = varargin{3};
if (! (ischar (itype) && isrow (itype) && any (strcmpi (itype, ...
{'closed', 'open', 'openleft', 'openright'}))))
error (strcat ("datetime.isbetween: interval type must be", ...
" 'closed', 'open', 'openleft', or 'openright'."));
endif
endif
if (isa (X, 'datetime'))
ref = X;
elseif (isa (lo, 'datetime'))
ref = lo;
else
ref = hi;
endif
X = dtIsbetweenArg (X, ref);
lo = dtIsbetweenArg (lo, ref);
hi = dtIsbetweenArg (hi, ref);
zoned = [! isempty(X.TimeZone), ! isempty(lo.TimeZone), ! isempty(hi.TimeZone)];
if (any (zoned) && ! all (zoned))
error (strcat ("datetime.isbetween: cannot combine a datetime array", ...
" with a time zone with one without a time zone."));
endif
sX = serial (X); sL = serial (lo); sU = serial (hi);
switch (lower (itype))
case 'closed'
TF = sL <= sX & sX <= sU;
case 'open'
TF = sL < sX & sX < sU;
case 'openleft'
TF = sL < sX & sX <= sU;
case 'openright'
TF = sL <= sX & sX < sU;
endswitch
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} issorted (@var{A})
## @deftypefnx {datetime} {@var{TF} =} issorted (@var{A}, @var{dim})
## @deftypefnx {datetime} {@var{TF} =} issorted (@var{A}, @var{direction})
## @deftypefnx {datetime} {@var{TF} =} issorted (@var{A}, @var{dim}, @var{direction})
##
## Determine whether a datetime array is sorted.
##
## @code{@var{TF} = issorted (@var{A})} returns @qcode{true} if the elements
## of the datetime array @var{A} are sorted in ascending (non-decreasing)
## order along its first non-singleton dimension, and @qcode{false}
## otherwise. For a matrix, every column (or row, depending on the operating
## dimension) must be sorted for @var{TF} to be @qcode{true}. Not-A-Time
## (@qcode{NaT}) elements are treated as greater than any other value, so an
## array is sorted in ascending order only when its @qcode{NaT} elements
## come last.
##
## @code{@var{TF} = issorted (@var{A}, @var{dim})} operates along dimension
## @var{dim}.
##
## @code{@var{TF} = issorted (@var{A}, @var{direction})} tests whether the
## elements are sorted according to @var{direction}, which may be one of:
##
## @itemize
## @item @qcode{'ascend'} (default) tests non-decreasing order.
## @item @qcode{'descend'} tests non-increasing order.
## @item @qcode{'monotonic'} tests non-decreasing or non-increasing order.
## @item @qcode{'strictascend'} tests strictly increasing order.
## @item @qcode{'strictdescend'} tests strictly decreasing order.
## @item @qcode{'strictmonotonic'} tests strictly monotonic order.
## @end itemize
##
## @end deftypefn
function TF = issorted (A, varargin)
dim = [];
direction = 'ascend';
valid = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
for i = 1:numel (varargin)
arg = varargin{i};
if (isnumeric (arg))
if (! isscalar (arg) || arg < 1 || arg != fix (arg))
error ("datetime.issorted: DIM must be a positive integer.");
endif
dim = arg;
elseif (ischar (arg) && isrow (arg))
didx = find (strcmpi (arg, valid));
if (isempty (didx))
error ("datetime.issorted: invalid DIRECTION '%s'.", arg);
endif
direction = valid{didx};
else
error ("datetime.issorted: invalid input argument.");
endif
endfor
if (isempty (dim))
dim = find (size (A) != 1, 1);
if (isempty (dim))
dim = 1;
endif
endif
## NaT sorts as greater than any value; map it to +Inf on the serial.
M = serial (A);
M(isnan (M)) = Inf;
if (dim > 2 || size (M, dim) < 2)
TF = true;
return;
endif
if (dim == 2)
M = M.';
endif
lo = M(1:end-1, :);
hi = M(2:end, :);
switch (direction)
case 'ascend'
ok = all (lo <= hi, 1);
case 'descend'
ok = all (lo >= hi, 1);
case 'strictascend'
ok = all (lo < hi, 1);
case 'strictdescend'
ok = all (lo > hi, 1);
case 'monotonic'
ok = all (lo <= hi, 1) | all (lo >= hi, 1);
case 'strictmonotonic'
ok = all (lo < hi, 1) | all (lo > hi, 1);
endswitch
TF = all (ok(:));
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} issortedrows (@var{A})
## @deftypefnx {datetime} {@var{TF} =} issortedrows (@var{A}, @var{column})
## @deftypefnx {datetime} {@var{TF} =} issortedrows (@var{A}, @var{direction})
## @deftypefnx {datetime} {@var{TF} =} issortedrows (@var{A}, @var{column}, @var{direction})
##
## Determine whether the rows of a datetime array are sorted.
##
## @code{@var{TF} = issortedrows (@var{A})} returns @qcode{true} if the rows
## of the 2-D datetime array @var{A} are sorted in ascending order, i.e.@:
## lexicographically by the first column, ties broken by the second column,
## and so on, and @qcode{false} otherwise. Not-A-Time (@qcode{NaT}) elements
## are treated as greater than any other value.
##
## @code{@var{TF} = issortedrows (@var{A}, @var{column})} checks the order
## using only the columns listed in @var{column}, in the given priority. A
## negative entry checks the corresponding column for descending order.
##
## @code{@var{TF} = issortedrows (@var{A}, @var{direction})} checks for the
## order given by @var{direction}, which may be one of @qcode{'ascend'}
## (default), @qcode{'descend'}, @qcode{'monotonic'}, @qcode{'strictascend'},
## @qcode{'strictdescend'}, or @qcode{'strictmonotonic'}. It may also be a
## cell array of @qcode{'ascend'}/@qcode{'descend'} strings, one per sort
## column. For the strict options a matrix qualifies only when its first
## sort column is strictly monotonic and free of @qcode{NaT}.
##
## @code{@var{TF} = issortedrows (@var{A}, @var{column}, @var{direction})}
## combines an explicit column list with a @var{direction}.
##
## @end deftypefn
function TF = issortedrows (A, varargin)
if (ndims (A) != 2)
error ("datetime.issortedrows: A must be a 2-D datetime array.");
endif
ncol = size (A, 2);
keywords = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
column = [];
direction = [];
if (numel (varargin) >= 1)
if (isnumeric (varargin{1}))
column = varargin{1};
if (numel (varargin) > 2)
error ("datetime.issortedrows: too many input arguments.");
elseif (numel (varargin) == 2)
direction = varargin{2};
endif
else
direction = varargin{1};
if (numel (varargin) > 1)
error ("datetime.issortedrows: COLUMN must precede DIRECTION.");
endif
endif
endif
if (isempty (column))
column = 1:ncol;
endif
column = column(:).';
if (any (column == 0) || any (column != fix (column)) ...
|| any (abs (column) > ncol))
error ("datetime.issortedrows: COLUMN out of range.");
endif
colmag = abs (column);
desc = column < 0;
check = 'ascend';
if (! isempty (direction))
if (ischar (direction) && isrow (direction))
check = lower (direction);
if (! any (strcmp (check, keywords)))
error ("datetime.issortedrows: invalid DIRECTION '%s'.", direction);
endif
if (any (strcmp (check, {'ascend', 'strictascend'})))
desc = false (size (colmag));
elseif (any (strcmp (check, {'descend', 'strictdescend'})))
desc = true (size (colmag));
endif
elseif (iscellstr (direction))
if (numel (direction) != numel (colmag))
error (strcat ("datetime.issortedrows: DIRECTION must have one", ...
" entry per sort column."));
endif
desc = false (size (colmag));
for j = 1:numel (direction)
if (strcmpi (direction{j}, 'descend'))
desc(j) = true;
elseif (! strcmpi (direction{j}, 'ascend'))
error ("datetime.issortedrows: invalid DIRECTION '%s'.", ...
direction{j});
endif
endfor
else
error ("datetime.issortedrows: invalid DIRECTION argument.");
endif
endif
if (isempty (colmag))
TF = true;
return;
endif
S = serial (A);
if (any (strcmp (check, {'strictascend', 'strictdescend', ...
'strictmonotonic'})))
## Strict: only the first sort column matters; it must be strictly
## monotonic and contain no NaT.
p = S(:, colmag(1));
if (any (isnan (p)))
TF = false;
else
d = diff (p);
if (strcmp (check, 'strictascend'))
TF = all (d > 0);
elseif (strcmp (check, 'strictdescend'))
TF = all (d < 0);
else
TF = all (d > 0) || all (d < 0);
endif
endif
return;
endif
## Non-strict: lexicographic check on the selected columns. NaT maps to
## +Inf (largest); each column is negated to fold in a descending key.
K = S(:, colmag);
K(isnan (K)) = Inf;
Kd = K;
for j = 1:numel (colmag)
if (desc(j))
Kd(:, j) = -Kd(:, j);
endif
endfor
if (strcmp (check, 'monotonic'))
TF = rowsNonDecreasing (A, Kd) || rowsNonDecreasing (A, -Kd);
else
TF = rowsNonDecreasing (A, Kd);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} iscolumn (@var{T})
##
## Return true if datetime array is a column vector.
##
## @code{@var{TF} = iscolumn (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the datetime array @var{T} is a column
## vector, and @qcode{false} otherwise. A column vector is a 2-D array for
## which @code{size (@var{X})} returns @code{[@var{N}, 1]} with non-negative
## @var{N}.
##
## @end deftypefn
function TF = iscolumn (this)
TF = iscolumn (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isempty (@var{T})
##
## Return true if datetime array is empty.
##
## @code{@var{TF} = isempty (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the datetime array @var{T} is empty, and
## @qcode{false} otherwise.
##
## @end deftypefn
function TF = isempty (this)
TF = isempty (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isequal (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{TF} =} isequal (@var{A}, @var{B}, @dots{})
##
## Test datetime arrays for equality.
##
## @code{@var{TF} = isequal (@var{A}, @var{B})} returns a logical scalar
## @var{TF}, which is @qcode{true} if the datetime arrays @var{A} and
## @var{B} are the same size and each pair of corresponding elements is the
## same point in time, and @qcode{false} otherwise. As with @qcode{NaN},
## Not-A-Time (@qcode{NaT}) elements are never equal, so any @qcode{NaT} in
## either array makes the result @qcode{false}; use @code{isequaln} to treat
## @qcode{NaT} elements as equal.
##
## Additional arrays may be supplied, as in @code{isequal (@var{A}, @var{B},
## @var{C}, @dots{})}, in which case @var{TF} is @qcode{true} only when all
## of the arrays are equal to one another. Any input argument that is not a
## datetime array, or a datetime array whose time zone is not compatible
## with the others (one zoned and one unzoned), makes the result
## @qcode{false} rather than raising an error. Zoned arrays are compared by
## their absolute instants, so equal instants in different time zones are
## equal.
##
## @end deftypefn
function TF = isequal (varargin)
if (nargin < 2)
print_usage ();
endif
TF = do_isequal (varargin, false);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isequaln (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{TF} =} isequaln (@var{A}, @var{B}, @dots{})
##
## Test datetime arrays for equality, treating Not-A-Time as equal.
##
## @code{@var{TF} = isequaln (@var{A}, @var{B})} is identical to
## @code{isequal (@var{A}, @var{B})} except that Not-A-Time (@qcode{NaT})
## elements are treated as equal to one another, in the same way that
## @code{isequaln} treats @qcode{NaN}. It returns a logical scalar @var{TF},
## which is @qcode{true} if the datetime arrays @var{A} and @var{B} are the
## same size and each pair of corresponding elements is either the same
## point in time or both @qcode{NaT}, and @qcode{false} otherwise.
##
## Additional arrays may be supplied, as in @code{isequaln (@var{A},
## @var{B}, @var{C}, @dots{})}, in which case @var{TF} is @qcode{true} only
## when all of the arrays are equal to one another. Any input argument that
## is not a datetime array, or a datetime array whose time zone is not
## compatible with the others (one zoned and one unzoned), makes the result
## @qcode{false} rather than raising an error. Zoned arrays are compared by
## their absolute instants, so equal instants in different time zones are
## equal.
##
## @end deftypefn
function TF = isequaln (varargin)
if (nargin < 2)
print_usage ();
endif
TF = do_isequal (varargin, true);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{out} =} isfinite (@var{T})
##
## Test for finite elements in datetime array.
##
## @code{@var{TF} = isfinite (@var{T})} returns a logical array @var{TF} of
## the same size as @var{T} containing @qcode{true} for each corresponding
## element of @var{T} that is finite and @qcode{false} otherwise. Finite
## elements in datetime arrays are those which are neither @qcode{Inf} nor
## @qcode{NaT}.
##
## @end deftypefn
function TF = isfinite (this)
TF = isfinite (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{out} =} isinf (@var{T})
##
## Test for infinite elements in datetime array.
##
## @code{@var{TF} = isinf (@var{T})} returns a logical array @var{TF} of the
## same size as @var{T} containing @qcode{true} for each corresponding
## element of @var{T} that is infinite and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isinf (this)
TF = isinf (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} ismatrix (@var{T})
##
## Return true if datetime array is a 2-D array.
##
## @code{@var{TF} = ismatrix (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the datetime array @var{T} is a matrix, and
## @qcode{false} otherwise. A matrix is an array of any type where
## @code{ndims (@var{X}) == 2} and for which @code{size (@var{X})} returns
## @code{[@var{H}, @var{W}]} with non-negative @var{H} and @var{W}.
##
## @end deftypefn
function TF = ismatrix (this)
TF = ismatrix (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} ismissing (@var{T})
## @deftypefnx {datetime} {@var{TF} =} ismissing (@var{T}, @var{indicator})
##
## Test for missing elements in datetime array.
##
## @var{TF} is a logical array of the same size as @var{T}.
##
## @end deftypefn
function TF = ismissing (this, varargin)
if (nargin > 2)
error ("datetime.ismissing: too many input arguments.");
endif
if (! isempty (varargin))
indicator = varargin{1};
TF = false (size (this));
if (isvector (indicator))
if (isa (indicator, 'datetime'))
for i = 1:numel (indicator.Year)
is_eq = indicator.Year(i) == this.Year & ...
indicator.Month(i) == this.Month & ...
indicator.Day(i) == this.Day & ...
indicator.Hour(i) == this.Hour & ...
indicator.Minute(i) == this.Minute & ...
indicator.Second(i) == this.Second;
TF(is_eq) = true;
endfor
else
error ("datetime.ismissing: INDICATOR must be a 'datetime' array.");
endif
else
error ("datetime.ismissing: INDICATOR must be a vector.");
endif
else
TF = isnan (this.Year);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isnat (@var{T})
##
## Test for Not-A-Time elements in datetime array.
##
## @code{@var{TF} = isnat (@var{T})} returns a logical array @var{TF} of the
## same size as @var{T} containing @qcode{true} for each corresponding
## element of @var{T} that is Not-A-Time (@qcode{NaT}) and @qcode{false}
## otherwise. @qcode{NaT} is the equivalent of @qcode{NaN} in numeric
## arrays.
##
## If @var{T} is not a datetime array, @code{isnat} returns an error.
##
## @end deftypefn
function TF = isnat (this)
TF = isnan (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isrow (@var{T})
##
## Return true if datetime array is a row vector.
##
## @code{@var{TF} = isrow (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the datetime array @var{T} is a row vector,
## and @qcode{false} otherwise. A row vector is a 2-D array for which
## @code{size (@var{X})} returns @code{[1, @var{N}]} with non-negative
## @var{N}.
##
## @end deftypefn
function TF = isrow (this)
TF = isrow (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isscalar (@var{T})
##
## Return true if datetime array is a scalar.
##
## @code{@var{TF} = isscalar (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the datetime array @var{T} is also a scalar,
## and @qcode{false} otherwise. A scalar is a single element object for
## which @code{size (@var{X})} returns @code{[1, 1]}.
##
## @end deftypefn
function TF = isscalar (this)
TF = isscalar (this.Year);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} isvector (@var{T})
##
## Return true if datetime array is a vector.
##
## @code{@var{TF} = isvector (@var{T})} returns a logical scalar @var{TF},
## which is @qcode{true} if the datetime array @var{T} is a vector and
## @qcode{false} otherwise. A vector is a 2-D array for which one of the
## dimensions is equal to 1 (either @math{1*N} or @math{N*1}). By
## definition, a scalar is also a vector.
##
## @end deftypefn
function TF = isvector (this)
TF = isvector (this.Year);
endfunction
endmethods
################################################################################
## ** Sort, Filter, and Set Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'sort' 'sortrows' 'unique' 'interp1' ##
## 'intersect' 'setdiff' 'setxor' 'union' ##
## 'min' 'max' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} sort (@var{A})
## @deftypefnx {datetime} {@var{B} =} sort (@var{A}, @var{dim})
## @deftypefnx {datetime} {@var{B} =} sort (@var{A}, @var{direction})
## @deftypefnx {datetime} {@var{B} =} sort (@var{A}, @var{dim}, @var{direction})
## @deftypefnx {datetime} {@var{B} =} sort (@dots{}, @qcode{'MissingPlacement'}, @var{mp})
## @deftypefnx {datetime} {[@var{B}, @var{I}] =} sort (@dots{})
##
## Sort a datetime array.
##
## @code{@var{B} = sort (@var{A})} returns the elements of the datetime array
## @var{A} sorted in ascending order along its first non-singleton
## dimension. For a matrix, each column is sorted independently. Sorting is
## stable: elements that compare as equal keep their original relative order.
##
## @code{@var{B} = sort (@var{A}, @var{dim})} sorts along dimension
## @var{dim}.
##
## @code{@var{B} = sort (@var{A}, @var{direction})} sorts in the order given
## by @var{direction}, which is either @qcode{'ascend'} (default) or
## @qcode{'descend'}.
##
## @code{@var{B} = sort (@dots{}, @qcode{'MissingPlacement'}, @var{mp})}
## controls where Not-A-Time (@qcode{NaT}) elements are placed. @var{mp} may
## be @qcode{'auto'} (default; @qcode{NaT} last for ascending order and first
## for descending order), @qcode{'first'}, or @qcode{'last'}.
##
## @code{[@var{B}, @var{I}] = sort (@dots{})} also returns an index array
## @var{I} of the same size as @var{A} such that @var{B} is @var{A} indexed
## by @var{I} along the operating dimension.
##
## @end deftypefn
function [B, I] = sort (A, varargin)
dim = [];
direction = 'ascend';
placement = 'auto';
i = 1;
while (i <= numel (varargin))
arg = varargin{i};
if (ischar (arg) && isrow (arg) && strcmpi (arg, 'MissingPlacement'))
if (i == numel (varargin))
error ("datetime.sort: 'MissingPlacement' requires a value.");
endif
placement = lower (varargin{i+1});
if (! any (strcmp (placement, {'auto', 'first', 'last'})))
error ("datetime.sort: invalid 'MissingPlacement' value.");
endif
i += 2;
elseif (isnumeric (arg))
if (! isscalar (arg) || arg < 1 || arg != fix (arg))
error ("datetime.sort: DIM must be a positive integer.");
endif
dim = arg;
i += 1;
elseif (ischar (arg) && isrow (arg))
if (strcmpi (arg, 'ascend'))
direction = 'ascend';
elseif (strcmpi (arg, 'descend'))
direction = 'descend';
else
error ("datetime.sort: invalid DIRECTION '%s'.", arg);
endif
i += 1;
else
error ("datetime.sort: invalid input argument.");
endif
endwhile
if (isempty (dim))
dim = find (size (A) != 1, 1);
if (isempty (dim))
dim = 1;
endif
endif
## Sorting along a singleton or higher dimension is a no-op.
if (dim > 2 || size (A, dim) < 2)
B = A;
I = ones (size (A));
return;
endif
descend = strcmp (direction, 'descend');
## Resolve 'auto': NaT goes last for ascending, first for descending.
if (strcmp (placement, 'auto'))
if (descend)
placement = 'first';
else
placement = 'last';
endif
endif
## Work on the numeric serial (NaT -> NaN); sort along columns, so
## transpose for a row-wise sort and transpose the result back.
S = serial (A);
Y = A.Year; MO = A.Month; D = A.Day;
H = A.Hour; MI = A.Minute; SE = A.Second;
if (dim == 2)
S = S.';
Y = Y.'; MO = MO.'; D = D.'; H = H.'; MI = MI.'; SE = SE.';
endif
[nr, nc] = size (S);
idx = zeros (nr, nc);
for j = 1:nc
col = S(:, j);
nat = isnan (col);
finidx = find (! nat);
natidx = find (nat);
## Stable order: sort by value, breaking ties by original position.
if (descend)
[~, ord] = sortrows ([-col(finidx), finidx]);
else
[~, ord] = sortrows ([col(finidx), finidx]);
endif
finsorted = finidx(ord);
if (strcmp (placement, 'first'))
idx(:, j) = [natidx; finsorted];
else
idx(:, j) = [finsorted; natidx];
endif
endfor
## Reorder the component arrays column-wise using linear indexing.
lin = idx + repmat ((0:nc-1) .* nr, nr, 1);
Y = Y(lin); MO = MO(lin); D = D(lin);
H = H(lin); MI = MI(lin); SE = SE(lin);
I = idx;
if (dim == 2)
Y = Y.'; MO = MO.'; D = D.'; H = H.'; MI = MI.'; SE = SE.';
I = idx.';
endif
B = A;
B.Year = Y; B.Month = MO; B.Day = D;
B.Hour = H; B.Minute = MI; B.Second = SE;
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} sortrows (@var{A})
## @deftypefnx {datetime} {@var{B} =} sortrows (@var{A}, @var{column})
## @deftypefnx {datetime} {@var{B} =} sortrows (@var{A}, @var{direction})
## @deftypefnx {datetime} {@var{B} =} sortrows (@var{A}, @var{column}, @var{direction})
## @deftypefnx {datetime} {@var{B} =} sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{mp})
## @deftypefnx {datetime} {[@var{B}, @var{index}] =} sortrows (@dots{})
##
## Sort the rows of a datetime array.
##
## @code{@var{B} = sortrows (@var{A})} sorts the rows of the 2-D datetime
## array @var{A} in ascending order. Rows are ordered lexicographically: by
## the first column, ties broken by the second column, and so on. The sort
## is stable, so rows that compare as equal keep their original order.
##
## @code{@var{B} = sortrows (@var{A}, @var{column})} sorts using only the
## columns listed in @var{column}, in the given priority. A negative entry
## sorts the corresponding column in descending order. Columns not listed
## are not used as sort keys.
##
## @code{@var{B} = sortrows (@var{A}, @var{direction})} sorts every column in
## the given @var{direction}, either @qcode{'ascend'} (default) or
## @qcode{'descend'}. @var{direction} may also be a cell array of strings
## with one such value per sort column.
##
## @code{@var{B} = sortrows (@var{A}, @var{column}, @var{direction})} combines
## an explicit column list with a per-column @var{direction}.
##
## @code{@var{B} = sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{mp})}
## controls where Not-A-Time (@qcode{NaT}) elements are placed. @var{mp} may
## be @qcode{'auto'} (default; @qcode{NaT} sorts as the largest value, i.e.@:
## last for ascending and first for descending columns), @qcode{'first'}, or
## @qcode{'last'}.
##
## @code{[@var{B}, @var{index}] = sortrows (@dots{})} also returns a column
## index vector @var{index} that maps the rows of @var{A} to @var{B}, such
## that @code{@var{B} = @var{A}(@var{index}, :)}.
##
## @end deftypefn
function [B, index] = sortrows (A, varargin)
if (ndims (A) != 2)
error ("datetime.sortrows: A must be a 2-D datetime array.");
endif
ncol = size (A, 2);
## Split the 'MissingPlacement' (and ignored 'ComparisonMethod') name-value
## pairs off from the positional COLUMN/DIRECTION arguments.
placement = 'auto';
pos = {};
k = 1;
while (k <= numel (varargin))
a = varargin{k};
if (ischar (a) && isrow (a) && strcmpi (a, 'MissingPlacement'))
if (k == numel (varargin))
error ("datetime.sortrows: 'MissingPlacement' requires a value.");
endif
placement = lower (varargin{k+1});
if (! any (strcmp (placement, {'auto', 'first', 'last'})))
error ("datetime.sortrows: invalid 'MissingPlacement' value.");
endif
k += 2;
elseif (ischar (a) && isrow (a) && strcmpi (a, 'ComparisonMethod'))
k += 2;
else
pos{end+1} = a;
k += 1;
endif
endwhile
if (numel (pos) > 2)
error ("datetime.sortrows: too many input arguments.");
endif
## Resolve the column selection and the per-column sort direction.
column = [];
direction = [];
if (numel (pos) >= 1)
if (isnumeric (pos{1}))
column = pos{1};
if (numel (pos) == 2)
direction = pos{2};
endif
else
direction = pos{1};
if (numel (pos) == 2)
error ("datetime.sortrows: COLUMN must precede DIRECTION.");
endif
endif
endif
if (isempty (column))
column = 1:ncol;
endif
column = column(:).';
if (any (column == 0) || any (column != fix (column)) ...
|| any (abs (column) > ncol))
error ("datetime.sortrows: COLUMN out of range.");
endif
colmag = abs (column);
desc = column < 0;
if (! isempty (direction))
if (ischar (direction) && isrow (direction))
if (strcmpi (direction, 'descend'))
desc = true (size (colmag));
elseif (strcmpi (direction, 'ascend'))
desc = false (size (colmag));
else
error ("datetime.sortrows: invalid DIRECTION '%s'.", direction);
endif
elseif (iscellstr (direction))
if (numel (direction) != numel (colmag))
error (strcat ("datetime.sortrows: DIRECTION must have one", ...
" entry per sort column."));
endif
desc = false (size (colmag));
for j = 1:numel (direction)
if (strcmpi (direction{j}, 'descend'))
desc(j) = true;
elseif (! strcmpi (direction{j}, 'ascend'))
error ("datetime.sortrows: invalid DIRECTION '%s'.", ...
direction{j});
endif
endfor
else
error ("datetime.sortrows: invalid DIRECTION argument.");
endif
endif
## Build the numeric key matrix from each selected column's instant. NaT
## maps to a signed-Inf sentinel that places it per MissingPlacement in the
## column's own direction ('auto' treats NaT as the largest value).
S = serial (A);
N = size (S, 1);
K = S(:, colmag);
for j = 1:numel (colmag)
if (strcmp (placement, 'auto'))
sentinel = Inf;
elseif (strcmp (placement, 'last'))
if (desc(j))
sentinel = -Inf;
else
sentinel = Inf;
endif
else
if (desc(j))
sentinel = Inf;
else
sentinel = -Inf;
endif
endif
col = K(:, j);
col(isnan (col)) = sentinel;
K(:, j) = col;
endfor
## Append the original row index as a final ascending tie-break so equal
## rows keep their order, then defer to the built-in lexicographic sort.
nkey = numel (colmag);
spec = (1:nkey) .* (1 - 2 * desc);
[~, index] = sortrows ([K, (1:N)'], [spec, nkey + 1]);
index = index(:);
B = subset (A, index, ':');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} min (@var{A})
## @deftypefnx {datetime} {@var{M} =} min (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{M} =} min (@var{A}, [], @var{dim})
## @deftypefnx {datetime} {@var{M} =} min (@dots{}, @var{nanflag})
## @deftypefnx {datetime} {@var{M} =} min (@var{A}, [], @qcode{'all'})
## @deftypefnx {datetime} {[@var{M}, @var{I}] =} min (@dots{})
##
## Minimum of a datetime array.
##
## @code{@var{M} = min (@var{A})} returns the smallest element of the
## datetime array @var{A} along its first non-singleton dimension. For a
## matrix, @var{M} is a row vector with the minimum of each column.
## Not-A-Time (@qcode{NaT}) elements are omitted; a reduction over
## @qcode{NaT} elements only yields @qcode{NaT}.
##
## @code{@var{M} = min (@var{A}, @var{B})} returns an array the same size as
## @var{A} and @var{B} (after broadcasting) holding the element-wise minimum
## of the two datetime arrays.
##
## @code{@var{M} = min (@var{A}, [], @var{dim})} operates along dimension
## @var{dim}. The empty second argument distinguishes this from the
## element-wise form.
##
## @code{@var{M} = min (@dots{}, @var{nanflag})} sets the treatment of
## @qcode{NaT}: @qcode{'omitnan'} (default) ignores @qcode{NaT}, while
## @qcode{'includenan'} returns @qcode{NaT} whenever a @qcode{NaT} takes
## part in the comparison.
##
## @code{@var{M} = min (@var{A}, [], @qcode{'all'})} returns the smallest
## element of the whole array.
##
## @code{[@var{M}, @var{I}] = min (@dots{})} also returns the indices of the
## minima. A second output is not available for the element-wise form.
##
## @end deftypefn
function [M, I] = min (A, varargin)
[M, I] = minmaxImpl (A, varargin, false, nargout);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} max (@var{A})
## @deftypefnx {datetime} {@var{M} =} max (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{M} =} max (@var{A}, [], @var{dim})
## @deftypefnx {datetime} {@var{M} =} max (@dots{}, @var{nanflag})
## @deftypefnx {datetime} {@var{M} =} max (@var{A}, [], @qcode{'all'})
## @deftypefnx {datetime} {[@var{M}, @var{I}] =} max (@dots{})
##
## Maximum of a datetime array.
##
## @code{@var{M} = max (@var{A})} returns the largest element of the datetime
## array @var{A} along its first non-singleton dimension. For a matrix,
## @var{M} is a row vector with the maximum of each column. Not-A-Time
## (@qcode{NaT}) elements are omitted; a reduction over @qcode{NaT} elements
## only yields @qcode{NaT}.
##
## @code{@var{M} = max (@var{A}, @var{B})} returns an array the same size as
## @var{A} and @var{B} (after broadcasting) holding the element-wise maximum
## of the two datetime arrays.
##
## @code{@var{M} = max (@var{A}, [], @var{dim})} operates along dimension
## @var{dim}. The empty second argument distinguishes this from the
## element-wise form.
##
## @code{@var{M} = max (@dots{}, @var{nanflag})} sets the treatment of
## @qcode{NaT}: @qcode{'omitnan'} (default) ignores @qcode{NaT}, while
## @qcode{'includenan'} returns @qcode{NaT} whenever a @qcode{NaT} takes
## part in the comparison.
##
## @code{@var{M} = max (@var{A}, [], @qcode{'all'})} returns the largest
## element of the whole array.
##
## @code{[@var{M}, @var{I}] = max (@dots{})} also returns the indices of the
## maxima. A second output is not available for the element-wise form.
##
## @end deftypefn
function [M, I] = max (A, varargin)
[M, I] = minmaxImpl (A, varargin, true, nargout);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} unique (@var{A})
## @deftypefnx {datetime} {@var{B} =} unique (@var{A}, @var{setOrder})
## @deftypefnx {datetime} {@var{B} =} unique (@var{A}, @var{occurrence})
## @deftypefnx {datetime} {@var{B} =} unique (@var{A}, @var{setOrder}, @var{occurrence})
## @deftypefnx {datetime} {@var{B} =} unique (@var{A}, @var{occurrence}, @var{setOrder})
## @deftypefnx {datetime} {@var{B} =} unique (@var{A}, @dots{}, @qcode{'rows'})
## @deftypefnx {datetime} {[@var{B}, @var{ixA}, @var{ixB}] =} unique (@dots{})
##
## Unique values in a datetime array.
##
## @code{@var{B} = unique (@var{A})} returns the unique values of the
## datetime array @var{A} in sorted order.
##
## @code{@var{B} = unique (@var{A}, @var{setOrder})} returns the unique
## values of the datetime array @var{A} in an order as specified by
## @var{setOrder}, which can be either of the following values:
##
## @itemize
## @item @qcode{'sorted'} (default) returns the unique values sorted in
## ascending order.
## @item @qcode{'stable'} returns the unique values according to their order
## of occurrence.
## @end itemize
##
## @code{@var{B} = unique (@var{A}, @var{occurrence})} returns the unique
## values of the datetime array @var{tblA} according to their order of
## occurrence. @var{occurrence} can be either of the following values:
##
## @itemize
## @item @qcode{'first'} (default) returns the first occurrence of each
## unique value, i.e. the lowest possible indices are returned.
## @item @qcode{'last'} returns the last occurrence of each unique value,
## i.e. the highest possible indices are returned.
## @end itemize
##
## You can specify @var{setOrder} and @var{occurrence} arguments together.
##
## @code{@var{B} = unique (@var{A}, @dots{}, @qcode{'rows'})} returns the
## unique rows of @var{A} by treating each row as a single entity. The
## @qcode{'rows'} option can be used alone or in any combination with the
## @var{setOrder} and @var{occurrence} arguments. @qcode{'rows'} can be
## placed at any position in the function's argument list after the input
## array @var{A}. However, this syntax is only valid for 2-dimensional
## datetime arrays.
##
## @code{[@var{tblB}, @var{ixA}, @var{ixB}] = unique (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} using any of the previous syntaxes.
## @var{ixA} and @var{ixB} map the arrays @var{A} and @var{B} to one another
## such that @qcode{@var{B} = @var{A}(@var{ixA})} and
## @qcode{@var{A} = @var{B}(@var{ixB})}. When the @qcode{'rows'} optional
## argument is specified, then @qcode{@var{B} = @var{A}(@var{ixA},:)} and
## @qcode{@var{tblA} = @var{tblB}(@var{ixB},:)}.
##
## @end deftypefn
function [B, ixA, ixB] = unique (A, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("datetime.unique: 'legacy' option is not supported.");
endif
## Handle each property array separately
[~, ~, Yidx] = __unique__ (A.Year, varargin{:});
[~, ~, MOidx] = __unique__ (A.Month, varargin{:});
[~, ~, Didx] = __unique__ (A.Day, varargin{:});
[~, ~, Hidx] = __unique__ (A.Hour, varargin{:});
[~, ~, MIidx] = __unique__ (A.Minute, varargin{:});
[~, ~, Sidx] = __unique__ (A.Second, varargin{:});
DT = [Yidx, MOidx, Didx, Hidx, MIidx, Sidx];
## Use indices to find unique datetime values
if (any (strcmp ('rows', varargin)))
[~, ixA, ixB] = __unique__ (DT, varargin{:});
if (any (strcmp ('last', varargin)))
[~, ixA, ~] = __unique__ (ixB, 'last');
endif
B = subset (A, ixA, ':');
else
[~, ixA, ixB] = __unique__ (DT, 'rows', varargin{:});
if (any (strcmp ('last', varargin)))
[~, ixA, ~] = __unique__ (ixB, 'last');
endif
B = subset (A, ixA);
## Match MATLAB: a non-row input yields a column (so an empty 0-by-0
## input returns a 0-by-1 result rather than 0-by-0).
if (isempty (B) && ! isrow (A))
B = reshape (B, numel (B), 1);
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} intersect (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{C} =} intersect (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {datetime} {@var{C} =} intersect (@dots{}, @var{order})
## @deftypefnx {datetime} {[@var{C}, @var{ixA}, @var{ixB}] =} intersect (@dots{})
##
## Set intersection of two datetime arrays.
##
## @code{@var{C} = intersect (@var{A}, @var{B})} returns the unique datetime
## values common to both @var{A} and @var{B}. Either input may instead be a
## date/time character vector, string array, or cell array of character
## vectors, which is promoted to a datetime array before the operation.
## Membership is decided on the absolute instant, so two zoned inputs may be
## in different time zones; the result carries the time zone and display
## format of @var{A}. Not-A-Time (@qcode{NaT}) elements are treated like
## @qcode{NaN} and never match. @var{C} is a row vector when both @var{A}
## and @var{B} are row vectors and a column vector otherwise.
##
## @code{@var{C} = intersect (@var{A}, @var{B}, @qcode{'rows'})} treats each
## row of the datetime matrices @var{A} and @var{B}, which must have the same
## number of columns, as a single element and returns their common rows.
##
## @code{@dots{} = intersect (@dots{}, @var{order})} returns the values in
## @qcode{'sorted'} order (the default) or in @qcode{'stable'} order, i.e.@:
## the order in which they appear in @var{A}.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = intersect (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that @code{@var{C} =
## @var{A}(@var{ixA})} and @code{@var{C} = @var{B}(@var{ixB})}, or the
## corresponding row selections when @qcode{'rows'} is used.
##
## @end deftypefn
function [C, ixA, ixB] = intersect (A, B, varargin)
if (any (strcmpi ('legacy', varargin)))
error ("datetime.intersect: 'legacy' option is not supported.");
endif
A = dtSetPromote (A, B, 'intersect');
B = dtSetPromote (B, A, 'intersect');
[A, B] = prepSetOp (A, B, 'intersect');
SA = serial (A);
SB = serial (B);
if (any (strcmpi ('rows', varargin)))
[~, ixA, ixB] = intersect (SA, SB, varargin{:});
C = subset (A, ixA, ':');
else
[~, ixA, ixB] = intersect (SA(:), SB(:), varargin{:});
C = subset (A, ixA);
C = reshapeSetResult (C, isrow (A) && isrow (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} union (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{C} =} union (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {datetime} {@var{C} =} union (@dots{}, @var{order})
## @deftypefnx {datetime} {[@var{C}, @var{ixA}, @var{ixB}] =} union (@dots{})
##
## Set union of two datetime arrays.
##
## @code{@var{C} = union (@var{A}, @var{B})} returns the unique datetime
## values present in either @var{A} or @var{B}. Either input may instead be
## a date/time character vector, string array, or cell array of character
## vectors, which is promoted to a datetime array before the operation.
## Membership is decided on the absolute instant, so two zoned inputs may be
## in different time zones; the result carries the time zone and display
## format of @var{A}. Distinct @qcode{NaT} elements are all retained.
## @var{C} is a row vector when both @var{A} and @var{B} are row vectors and
## a column vector otherwise.
##
## @code{@var{C} = union (@var{A}, @var{B}, @qcode{'rows'})} treats each row
## of the datetime matrices @var{A} and @var{B}, which must have the same
## number of columns, as a single element and returns their combined unique
## rows.
##
## @code{@dots{} = union (@dots{}, @var{order})} returns the values in
## @qcode{'sorted'} order (the default) or in @qcode{'stable'} order.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = union (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that @var{C} is the combination
## of @code{@var{A}(@var{ixA})} and @code{@var{B}(@var{ixB})}, or the
## corresponding row selections when @qcode{'rows'} is used.
##
## @end deftypefn
function [C, ixA, ixB] = union (A, B, varargin)
if (any (strcmpi ('legacy', varargin)))
error ("datetime.union: 'legacy' option is not supported.");
endif
A = dtSetPromote (A, B, 'union');
B = dtSetPromote (B, A, 'union');
[A, B] = prepSetOp (A, B, 'union');
SA = serial (A);
SB = serial (B);
stable = any (strcmpi ('stable', varargin));
if (any (strcmpi ('rows', varargin)))
[~, ixA, ixB] = union (SA, SB, varargin{:});
C = combineSets (A, B, ixA, ixB, SA, SB, true, stable);
else
[~, ixA, ixB] = union (SA(:), SB(:), varargin{:});
C = combineSets (A, B, ixA, ixB, SA, SB, false, stable);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} setdiff (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{C} =} setdiff (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {datetime} {@var{C} =} setdiff (@dots{}, @var{order})
## @deftypefnx {datetime} {[@var{C}, @var{ixA}] =} setdiff (@dots{})
##
## Set difference of two datetime arrays.
##
## @code{@var{C} = setdiff (@var{A}, @var{B})} returns the unique datetime
## values in @var{A} that are not in @var{B}. Either input may instead be a
## date/time character vector, string array, or cell array of character
## vectors, which is promoted to a datetime array before the operation.
## Membership is decided on the absolute instant, so two zoned inputs may be
## in different time zones; the result carries the time zone and display
## format of @var{A}. @qcode{NaT} elements in @var{A} are all retained, as
## they never match an element of @var{B}. @var{C} is a row vector when both
## @var{A} and @var{B} are row vectors and a column vector otherwise.
##
## @code{@var{C} = setdiff (@var{A}, @var{B}, @qcode{'rows'})} treats each
## row of the datetime matrices @var{A} and @var{B}, which must have the same
## number of columns, as a single element and returns the rows of @var{A}
## that are not rows of @var{B}.
##
## @code{@dots{} = setdiff (@dots{}, @var{order})} returns the values in
## @qcode{'sorted'} order (the default) or in @qcode{'stable'} order.
##
## @code{[@var{C}, @var{ixA}] = setdiff (@dots{})} also returns an index
## vector @var{ixA} such that @code{@var{C} = @var{A}(@var{ixA})}, or
## @code{@var{C} = @var{A}(@var{ixA},:)} when @qcode{'rows'} is used.
##
## @end deftypefn
function [C, ixA] = setdiff (A, B, varargin)
if (any (strcmpi ('legacy', varargin)))
error ("datetime.setdiff: 'legacy' option is not supported.");
endif
A = dtSetPromote (A, B, 'setdiff');
B = dtSetPromote (B, A, 'setdiff');
[A, B] = prepSetOp (A, B, 'setdiff');
SA = serial (A);
SB = serial (B);
if (any (strcmpi ('rows', varargin)))
[~, ixA] = setdiff (SA, SB, varargin{:});
C = subset (A, ixA, ':');
else
[~, ixA] = setdiff (SA(:), SB(:), varargin{:});
C = subset (A, ixA);
C = reshapeSetResult (C, isrow (A) && isrow (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} setxor (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{C} =} setxor (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {datetime} {@var{C} =} setxor (@dots{}, @var{order})
## @deftypefnx {datetime} {[@var{C}, @var{ixA}, @var{ixB}] =} setxor (@dots{})
##
## Set exclusive-or of two datetime arrays.
##
## @code{@var{C} = setxor (@var{A}, @var{B})} returns the unique datetime
## values that are in @var{A} or in @var{B} but not in both. Either input
## may instead be a date/time character vector, string array, or cell array
## of character vectors, which is promoted to a datetime array before the
## operation. Membership is decided on the absolute instant, so two zoned
## inputs may be in different time zones; the result carries the time zone
## and display format of @var{A}. Distinct @qcode{NaT} elements are all
## retained. @var{C} is a row vector when both @var{A} and @var{B} are row
## vectors and a column vector otherwise.
##
## @code{@var{C} = setxor (@var{A}, @var{B}, @qcode{'rows'})} treats each row
## of the datetime matrices @var{A} and @var{B}, which must have the same
## number of columns, as a single element and returns the rows that are in
## one input but not both.
##
## @code{@dots{} = setxor (@dots{}, @var{order})} returns the values in
## @qcode{'sorted'} order (the default) or in @qcode{'stable'} order.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = setxor (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that @var{C} is the combination
## of @code{@var{A}(@var{ixA})} and @code{@var{B}(@var{ixB})}, or the
## corresponding row selections when @qcode{'rows'} is used.
##
## @end deftypefn
function [C, ixA, ixB] = setxor (A, B, varargin)
if (any (strcmpi ('legacy', varargin)))
error ("datetime.setxor: 'legacy' option is not supported.");
endif
A = dtSetPromote (A, B, 'setxor');
B = dtSetPromote (B, A, 'setxor');
[A, B] = prepSetOp (A, B, 'setxor');
SA = serial (A);
SB = serial (B);
stable = any (strcmpi ('stable', varargin));
if (any (strcmpi ('rows', varargin)))
[~, ixA, ixB] = setxor (SA, SB, varargin{:});
C = combineSets (A, B, ixA, ixB, SA, SB, true, stable);
else
[~, ixA, ixB] = setxor (SA(:), SB(:), varargin{:});
C = combineSets (A, B, ixA, ixB, SA, SB, false, stable);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} ismember (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{TF} =} ismember (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {datetime} {[@var{TF}, @var{index}] =} ismember (@dots{})
##
## Test for datetime elements in a set.
##
## @code{@var{TF} = ismember (@var{A}, @var{B})} returns a logical array
## @var{TF} of the same size as @var{A} containing @qcode{true} for each
## corresponding element of @var{A} that is in @var{B} and @qcode{false}
## otherwise. Either input may instead be a date/time character vector,
## string array, or cell array of character vectors, which is promoted to a
## datetime array before the test. Membership is decided on the absolute
## instant, so two zoned inputs may be in different time zones. Similarly to
## @qcode{NaN} values, Not-A-Time (@qcode{NaT}) elements are not equal with
## each other and always return @qcode{false}.
##
## @code{@var{TF} = ismember (@var{A}, @var{B}, @qcode{'rows'})} only
## applies to datetime matrices with the same number of columns, in which
## case the logical vector @var{TF} contains @qcode{true} for each row of
## @var{A} that is also a row in @var{B}. @var{TF} has the same number of
## rows as @var{A}.
##
## @code{[@var{TF}, @var{index}] = ismember (@var{A}, @var{B})} also returns
## an index array of the same size as @var{A} containing the lowest index in
## @var{B} for each element of @var{A} that is a member of @var{B} and 0
## otherwise. If the @qcode{'rows'} optional argument is used, then the
## returning index is a column vector with the same rows as @var{A} and it
## contains the lowest index in @var{B} for each row of @var{A} that is a
## member of @var{B} and 0 otherwise.
##
## @end deftypefn
function [TF, index] = ismember (A, B, varargin)
do_rows = false;
if (! isempty (varargin))
if (strcmpi (varargin{1}, 'rows'))
do_rows = true;
if (ndims (A) != 2 || ndims (A) != ndims (B))
error ("datetime.ismember: 'rows' applies only to 2-D matrices.");
endif
if (size (A, 2) != size (B, 2))
error (strcat ("datetime.ismember: 'rows' requires same", ...
" number of columns."));
endif
else
error ("datetime.ismember: invalid optional argument.");
endif
endif
A = dtSetPromote (A, B, 'ismember');
B = dtSetPromote (B, A, 'ismember');
[A, B] = prepSetOp (A, B, 'ismember');
SA = serial (A);
SB = serial (B);
if (do_rows)
[TF, index] = __ismember__ (SA, SB, 'rows');
else
[TF, index] = __ismember__ (SA, SB);
endif
endfunction
endmethods
methods (Hidden)
function BI = interp1 (A, B, AI, varargin)
error ("datetime.interp1: not implemented yet.");
endfunction
endmethods
################################################################################
## ** Descriptive Statistics ** ##
################################################################################
## Available Methods ##
## ##
## 'mean' 'median' 'mode' 'std' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} mean (@var{A})
## @deftypefnx {datetime} {@var{M} =} mean (@var{A}, @var{dim})
## @deftypefnx {datetime} {@var{M} =} mean (@var{A}, @qcode{'all'})
## @deftypefnx {datetime} {@var{M} =} mean (@dots{}, @var{nanflag})
##
## Mean of a datetime array.
##
## @code{@var{M} = mean (@var{A})} returns the mean of the datetime array
## @var{A} as a scalar datetime, computed as the average of the absolute
## instants along the first non-singleton dimension. A @var{dim} or
## @qcode{'all'} argument selects the dimension(s) to operate on. The result
## carries the @code{Format} and @code{TimeZone} of @var{A}.
##
## By default a Not-A-Time element makes the corresponding result
## @qcode{NaT}; pass @qcode{'omitnat'} (equivalently @qcode{'omitmissing'})
## to ignore missing values, or @qcode{'includenat'} to keep the default.
##
## @end deftypefn
function R = mean (A, varargin)
args = dtStatFlags (varargin);
R = fromReducedSerial (A, mean (serial (A), args{:}));
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} median (@var{A})
## @deftypefnx {datetime} {@var{M} =} median (@var{A}, @var{dim})
## @deftypefnx {datetime} {@var{M} =} median (@var{A}, @qcode{'all'})
## @deftypefnx {datetime} {@var{M} =} median (@dots{}, @var{nanflag})
##
## Median of a datetime array.
##
## @code{@var{M} = median (@var{A})} returns the median of the datetime array
## @var{A} as a datetime, computed on the absolute instants along the first
## non-singleton dimension (for an even number of elements the average of the
## two middle instants). A @var{dim} or @qcode{'all'} argument selects the
## dimension(s). The result carries the @code{Format} and @code{TimeZone} of
## @var{A}. Missing-value handling matches @code{mean}.
##
## @end deftypefn
function R = median (A, varargin)
args = dtStatFlags (varargin);
R = fromReducedSerial (A, median (serial (A), args{:}));
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{M} =} mode (@var{A})
## @deftypefnx {datetime} {@var{M} =} mode (@var{A}, @var{dim})
## @deftypefnx {datetime} {@var{M} =} mode (@var{A}, @qcode{'all'})
## @deftypefnx {datetime} {[@var{M}, @var{F}, @var{C}] =} mode (@dots{})
##
## Most frequent value of a datetime array.
##
## @code{@var{M} = mode (@var{A})} returns the most frequently occurring
## datetime in @var{A} along the first non-singleton dimension; when several
## values are equally frequent the smallest is returned. A @var{dim} or
## @qcode{'all'} argument selects the dimension(s). Not-A-Time elements are
## ignored. The result carries the @code{Format} and @code{TimeZone} of
## @var{A}.
##
## @code{[@var{M}, @var{F}, @var{C}] = mode (@dots{})} also returns the
## frequency @var{F} of the modal value and a cell array @var{C} whose
## elements list all values that achieve that frequency.
##
## @end deftypefn
function [R, F, C] = mode (A, varargin)
if (nargout > 2)
[ser, F, C] = mode (serial (A), varargin{:});
C = cellfun (@(x) fromReducedSerial (A, x), C, 'UniformOutput', false);
elseif (nargout == 2)
[ser, F] = mode (serial (A), varargin{:});
else
ser = mode (serial (A), varargin{:});
endif
R = fromReducedSerial (A, ser);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{S} =} std (@var{A})
## @deftypefnx {datetime} {@var{S} =} std (@var{A}, @var{w})
## @deftypefnx {datetime} {@var{S} =} std (@var{A}, @var{w}, @var{dim})
## @deftypefnx {datetime} {@var{S} =} std (@var{A}, @var{w}, @qcode{'all'})
## @deftypefnx {datetime} {@var{S} =} std (@dots{}, @var{nanflag})
## @deftypefnx {datetime} {[@var{S}, @var{M}] =} std (@dots{})
##
## Standard deviation of a datetime array.
##
## @code{@var{S} = std (@var{A})} returns the standard deviation of the
## absolute instants of @var{A} as a @code{duration}. The weight @var{w}
## selects the normalisation (@code{0}, the default, divides by @math{N-1};
## @code{1} divides by @math{N}), and a @var{dim} or @qcode{'all'} argument
## selects the dimension(s). Missing-value handling matches @code{mean}.
##
## @code{[@var{S}, @var{M}] = std (@dots{})} also returns the mean @var{M} as
## a datetime.
##
## @end deftypefn
function [S, M] = std (A, varargin)
args = dtStatFlags (varargin);
if (nargout > 1)
[sSec, mSec] = std (serial (A), args{:});
M = fromReducedSerial (A, mSec);
else
sSec = std (serial (A), args{:});
endif
S = duration (0, 0, sSec);
endfunction
endmethods
################################################################################
## ** Arithmetic Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'plus' 'minus' 'colon' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{R} =} colon (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{R} =} colon (@var{A}, @var{step}, @var{B})
##
## Create a range of datetime values.
##
## @code{@var{R} = colon (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{R} = @var{A}:@var{B}} and returns a row vector of datetime
## values starting at @var{A} and increasing in steps of one calendar day up
## to, and possibly including, @var{B}.
##
## @code{@var{R} = colon (@var{A}, @var{step}, @var{B})} is the equivalent of
## the syntax @code{@var{R} = @var{A}:@var{step}:@var{B}} and uses the
## specified @var{step} between consecutive elements. @var{step} may be:
##
## @itemize
## @item a @code{duration} or a numeric scalar (a number of fixed 24-hour
## days), in which case successive elements advance by a fixed amount of
## elapsed time; for a zoned range this is aware of daylight saving time.
##
## @item a @code{calendarDuration}, in which case successive elements advance
## in calendar units. Each element is computed as @code{@var{A} + k*@var{step}}
## for @code{k = 0, 1, 2, @dots{}}, so month and year steps clamp the day of
## month independently for every element (e.g.@: a one-month step from
## 31 January yields 31 January, 28 February, 31 March, @dots{}).
## @end itemize
##
## The default step of @code{@var{A}:@var{B}} is one calendar day
## (@code{caldays (1)}), which preserves the time of day across daylight
## saving time changes. A range whose @var{step} points away from @var{B}
## (for example an increasing step with @code{@var{A} > @var{B}}) is empty.
## @var{A} and @var{B} must be datetime scalars that are either both zoned or
## both unzoned, and must be finite.
##
## @end deftypefn
function R = colon (varargin)
if (nargin == 2)
A = varargin{1};
step = caldays (1);
B = varargin{2};
elseif (nargin == 3)
A = varargin{1};
step = varargin{2};
B = varargin{3};
else
print_usage ();
endif
if (! (isa (A, 'datetime') && isa (B, 'datetime')))
error ("datetime.colon: range endpoints must be datetime arrays.");
endif
if (! (isscalar (A) && isscalar (B)))
error ("datetime.colon: range endpoints must be datetime scalars.");
endif
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
error (strcat ("datetime.colon: cannot create a range between a", ...
" datetime with a time zone and one without a time", ...
" zone."));
endif
if (! (isfinite (A) && isfinite (B)))
error (strcat ("datetime.colon: range endpoints must be finite", ...
" (neither NaT nor Inf)."));
endif
if (! isscalar (step))
error ("datetime.colon: STEP must be a scalar.");
endif
if (isa (step, 'calendarDuration'))
R = colonCalendar (A, step, B);
elseif (isa (step, 'duration'))
R = colonLinear (A, days (step) * 86400, B);
elseif (isnumeric (step) && isreal (step))
R = colonLinear (A, double (step) * 86400, B);
else
error (strcat ("datetime.colon: STEP must be a duration,", ...
" calendarDuration, or numeric scalar."));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} plus (@var{A}, @var{B})
##
## Addition for datetime arrays.
##
## @code{@var{C} = plus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} + @var{B}} and supports the following operand
## combinations, in either order.
##
## @itemize
## @item @code{datetime + duration} returns a @code{datetime} array shifted
## later by a fixed number of 24-hour days. For a zoned array the shift is
## applied to the absolute instant, so it is aware of daylight saving time
## transitions.
##
## @item @code{datetime + calendarDuration} returns a @code{datetime} array
## shifted later in calendar units. Whole months (and years) are applied
## first, clamping the day of month to the last day of the target month when
## necessary (e.g.@: 31 January plus one month is 28 February), then whole
## calendar days, and finally the time-of-day component as an instant.
##
## @item @code{datetime + X}, where @var{X} is a numeric or logical array,
## treats the elements of @var{X} as a number of fixed 24-hour days.
## @end itemize
##
## Adding two datetime arrays is not defined and raises an error. @var{A}
## and @var{B} must be size compatible: they can be the same size, one can be
## scalar, or for every dimension their sizes must be equal or one of them
## must be 1. Not-A-Time and infinite elements propagate to the result.
##
## @end deftypefn
function C = plus (A, B)
## Addition is symmetric for every supported operand type, so commute the
## operands to keep the datetime array on the left.
if (! isa (A, 'datetime'))
[A, B] = deal (B, A);
endif
if (isa (B, 'datetime'))
## datetime + datetime is not defined (MATLAB parity)
error (strcat ("datetime.plus: addition is not defined between two", ...
" datetime arrays."));
elseif (isa (B, 'duration'))
## datetime + duration -> datetime (fixed-length instant shift)
C = addSeconds (A, days (B) * 86400);
elseif (isa (B, 'calendarDuration'))
## datetime + calendarDuration -> datetime (calendar-aware shift)
C = addCalendar (A, B, 1);
elseif (islogical (B) || (isnumeric (B) && isfloat (B)))
## numeric/logical operand: a number of fixed 24-hour days
C = addSeconds (A, double (B) * 86400);
elseif (isinteger (B))
error (strcat ("datetime.plus: cannot add a '%s' array to a datetime", ...
" array; convert it to double or a duration first."), ...
class (B));
else
error (strcat ("datetime.plus: cannot add a '%s' array to a datetime", ...
" array."), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} minus (@var{A}, @var{B})
##
## Subtraction for datetime arrays.
##
## @code{@var{C} = minus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} - @var{B}} and supports the following operand
## combinations.
##
## @itemize
## @item @code{datetime - datetime} returns a @code{duration} array holding
## the elapsed time between the corresponding elements. Both operands must
## either both have a time zone or both be unzoned; a zoned difference is
## computed from the absolute instants, so the two time zones may differ.
##
## @item @code{datetime - duration} returns a @code{datetime} array shifted
## earlier by a fixed number of 24-hour days. For a zoned array the shift
## is applied to the absolute instant, so it is aware of daylight saving
## time transitions.
##
## @item @code{datetime - calendarDuration} returns a @code{datetime} array
## shifted earlier in calendar units. Whole months (and years) are applied
## first, clamping the day of month to the last day of the target month when
## necessary (e.g.@: 31 March minus one month is 28 February), then whole
## calendar days, and finally the time-of-day component as an instant.
##
## @item @code{datetime - X}, where @var{X} is a numeric or logical array,
## treats the elements of @var{X} as a number of fixed 24-hour days.
## @end itemize
##
## @var{A} and @var{B} must be size compatible: they can be the same size,
## one can be scalar, or for every dimension their sizes must be equal or one
## of them must be 1. Not-A-Time and infinite elements propagate to the
## result.
##
## @end deftypefn
function C = minus (A, B)
## Only 'datetime - ' is defined; a datetime array cannot be
## subtracted from a non-datetime left operand (MATLAB parity).
if (! isa (A, 'datetime'))
error (strcat ("datetime.minus: cannot subtract a datetime array", ...
" from a '%s' array."), class (A));
endif
if (isa (B, 'datetime'))
## datetime - datetime -> duration (elapsed time)
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
error (strcat ("datetime.minus: cannot subtract a datetime array", ...
" with a time zone from one without a time zone."));
endif
C = duration (0, 0, serial (A) - serial (B));
elseif (isa (B, 'duration'))
## datetime - duration -> datetime (fixed-length instant shift)
C = addSeconds (A, - days (B) * 86400);
elseif (isa (B, 'calendarDuration'))
## datetime - calendarDuration -> datetime (calendar-aware shift)
C = addCalendar (A, B, -1);
elseif (islogical (B) || (isnumeric (B) && isfloat (B)))
## numeric/logical operand: a number of fixed 24-hour days
C = addSeconds (A, - double (B) * 86400);
elseif (isinteger (B))
error (strcat ("datetime.minus: cannot subtract a '%s' array from a", ...
" datetime array; convert it to double or a duration", ...
" first."), class (B));
else
error (strcat ("datetime.minus: cannot subtract a '%s' array from a", ...
" datetime array."), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{D} =} diff (@var{A})
## @deftypefnx {datetime} {@var{D} =} diff (@var{A}, @var{N})
## @deftypefnx {datetime} {@var{D} =} diff (@var{A}, @var{N}, @var{dim})
##
## Differences between successive datetime elements.
##
## @code{@var{D} = diff (@var{A})} returns a @code{duration} array holding the
## elapsed time between successive elements of @var{A} along its first
## non-singleton dimension. The differences are computed from the absolute
## instants, so for a zoned array they are aware of daylight saving time
## transitions (a calendar day spanning a transition is 23 or 25 hours, not
## 24). Not-A-Time elements propagate as @qcode{NaN} durations.
##
## @code{@var{D} = diff (@var{A}, @var{N})} applies @code{diff}
## recursively @var{N} times, returning the @var{N}-th order difference.
## @var{N} must be a positive integer scalar.
##
## @code{@var{D} = diff (@var{A}, @var{N}, @var{dim})} operates along
## dimension @var{dim}.
##
## @end deftypefn
function D = diff (A, varargin)
n = 1;
dim = [];
if (numel (varargin) > 2)
error ("datetime.diff: too many input arguments.");
endif
if (numel (varargin) >= 1)
n = varargin{1};
if (! (isnumeric (n) && isscalar (n) && n > 0 && n == fix (n)))
error (strcat ("datetime.diff: order N must be a positive integer", ...
" scalar."));
endif
endif
if (numel (varargin) >= 2)
dim = varargin{2};
if (! (isnumeric (dim) && isscalar (dim) && dim > 0 ...
&& dim == fix (dim)))
error (strcat ("datetime.diff: DIM must be a positive integer", ...
" scalar."));
endif
endif
S = serial (A);
if (! isempty (dim) && dim > ndims (S))
## Differencing along a trailing singleton dimension leaves at most one
## element there, so the result is empty along DIM (MATLAB parity).
sz = size (S);
sz(end+1:dim) = 1;
sz(dim) = 0;
DS = zeros (sz);
elseif (isempty (dim))
DS = diff (S, n);
else
DS = diff (S, n, dim);
endif
D = duration (0, 0, DS);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{D} =} caldiff (@var{A})
## @deftypefnx {datetime} {@var{D} =} caldiff (@var{A}, @var{components})
## @deftypefnx {datetime} {@var{D} =} caldiff (@var{A}, @var{components}, @var{dim})
##
## Calendar differences between successive datetime elements.
##
## @code{@var{D} = caldiff (@var{A})} returns a @code{calendarDuration} array
## holding the calendar difference between successive elements of @var{A}
## along its first non-singleton dimension. Unlike @code{diff}, the result
## is expressed in whole calendar units (years, months, days) plus a leftover
## time, so it is aware of month lengths and, for a zoned array, of daylight
## saving time. Not-A-Time elements yield @qcode{NaN}.
##
## @code{@var{D} = caldiff (@var{A}, @var{components})} expresses each
## difference using only the requested calendar components.
## @var{components} is one of @qcode{'Years'}, @qcode{'Quarters'},
## @qcode{'Months'}, @qcode{'Weeks'}, @qcode{'Days'}, or @qcode{'Time'}, or a
## cell array or string array containing several of them. The default is
## @qcode{@{'Years', 'Months', 'Days', 'Time'@}}.
##
## @code{@var{D} = caldiff (@var{A}, @var{components}, @var{dim})} operates
## along dimension @var{dim}.
##
## @end deftypefn
function D = caldiff (A, varargin)
comps = [];
dim = [];
for k = 1:numel (varargin)
x = varargin{k};
if (ischar (x) || iscellstr (x) || isa (x, 'string'))
comps = x;
elseif (isnumeric (x) && isscalar (x))
dim = x;
else
error ("datetime.caldiff: invalid input argument.");
endif
endfor
if (isempty (dim))
dim = find (size (A) != 1, 1);
if (isempty (dim))
dim = 1;
endif
endif
n = size (A, dim);
idx = repmat ({':'}, 1, max (ndims (A), dim));
i1 = idx; i1{dim} = 1:n-1;
i2 = idx; i2{dim} = 2:n;
D = calDiff (subset (A, i1{:}), subset (A, i2{:}), comps, 'caldiff');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{D} =} between (@var{A}, @var{B})
## @deftypefnx {datetime} {@var{D} =} between (@var{A}, @var{B}, @var{components})
##
## Calendar difference between two datetime arrays.
##
## @code{@var{D} = between (@var{A}, @var{B})} returns a
## @code{calendarDuration} array holding the calendar difference from each
## element of @var{A} to the corresponding element of @var{B}. The result is
## signed (it is negative where @var{B} precedes @var{A}) and is expressed in
## whole calendar units plus a leftover time, taking month lengths and
## daylight saving time into account. @var{A} and @var{B} must be the same
## size or one of them must be scalar. Not-A-Time elements yield @qcode{NaN}.
##
## @code{@var{D} = between (@var{A}, @var{B}, @var{components})} expresses
## each difference using only the requested calendar components (see
## @code{caldiff}). The default is @qcode{@{'Years', 'Months', 'Days',
## 'Time'@}}.
##
## @end deftypefn
function D = between (A, B, varargin)
if (numel (varargin) > 1)
error ("datetime.between: too many input arguments.");
endif
comps = [];
if (numel (varargin) == 1)
comps = varargin{1};
endif
A = dtSetPromote (A, B, 'between');
B = dtSetPromote (B, A, 'between');
[A, B] = prepSetOp (A, B, 'between');
[A, B] = broadcastPair (A, B, 'between');
D = calDiff (A, B, comps, 'between');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{R} =} dateshift (@var{A}, @qcode{'start'}, @var{unit})
## @deftypefnx {datetime} {@var{R} =} dateshift (@var{A}, @qcode{'end'}, @var{unit})
## @deftypefnx {datetime} {@var{R} =} dateshift (@dots{}, @var{rule})
## @deftypefnx {datetime} {@var{R} =} dateshift (@var{A}, @qcode{'dayofweek'}, @var{dow})
## @deftypefnx {datetime} {@var{R} =} dateshift (@var{A}, @qcode{'dayofweek'}, @var{dow}, @var{rule})
##
## Shift datetime values to calendar boundaries.
##
## @code{@var{R} = dateshift (@var{A}, @qcode{'start'}, @var{unit})} returns a
## datetime array in which each element of @var{A} is moved back to the start
## of the calendar @var{unit} that contains it, with the finer components set
## to zero. @var{unit} is @qcode{'second'}, @qcode{'minute'},
## @qcode{'hour'}, @qcode{'day'}, @qcode{'week'}, @qcode{'month'},
## @qcode{'quarter'}, or @qcode{'year'}. A week starts on Sunday.
##
## @code{@var{R} = dateshift (@var{A}, @qcode{'end'}, @var{unit})} moves each
## element to the end of its unit: the start of the next second, minute,
## hour, or day, and the last day (at midnight) of the week, month, quarter,
## or year.
##
## @code{@var{R} = dateshift (@dots{}, @var{rule})} first shifts each element
## by @var{rule} whole units. @var{rule} is @qcode{'current'} (the default),
## @qcode{'next'}, @qcode{'previous'}, @qcode{'nearest'}, or an integer
## number of units.
##
## @code{@var{R} = dateshift (@var{A}, @qcode{'dayofweek'}, @var{dow})} moves
## each element to the next date, on or after it, whose day of the week is
## @var{dow} (a number from 1 for Sunday to 7 for Saturday, or a day name),
## keeping the time of day. A trailing @var{rule} of @qcode{'previous'},
## @qcode{'nearest'}, @qcode{'current'} (the day within the current week), or
## an integer occurrence selects a different date.
##
## Not-A-Time and infinite elements are returned unchanged.
##
## @end deftypefn
function R = dateshift (this, op, varargin)
ops = {'start', 'end', 'dayofweek'};
if (! (ischar (op) && isrow (op) && any (strcmpi (op, ops))))
error (strcat ("datetime.dateshift: second input must be 'start',", ...
" 'end', or 'dayofweek'."));
endif
op = lower (op);
if (numel (varargin) < 1)
error ("datetime.dateshift: not enough input arguments.");
endif
if (numel (varargin) > 2)
error ("datetime.dateshift: too many input arguments.");
endif
Y = this.Year; M = this.Month; D = this.Day;
h = this.Hour; mi = this.Minute; s = this.Second;
keep = isnan (Y) | isinf (Y);
if (any (keep(:)))
Y(keep) = 2000; M(keep) = 1; D(keep) = 1;
h(keep) = 0; mi(keep) = 0; s(keep) = 0;
endif
if (strcmp (op, 'dayofweek'))
dow = varargin{1};
if (ischar (dow) && isrow (dow))
dow = dsDayName (dow);
elseif (! (isnumeric (dow) && isscalar (dow)))
dow = NaN;
endif
if (! (isscalar (dow) && dow >= 1 && dow <= 7 && dow == fix (dow)))
error (strcat ("datetime.dateshift: day of week must be a number", ...
" from 1 to 7 or a day name."));
endif
kind = 'next'; n = 0;
if (numel (varargin) == 2)
[kind, n] = dsRule (varargin{2});
endif
dowT = weekday (datenum (Y, M, D));
dNext = mod (dow - dowT, 7);
dPrev = mod (dowT - dow, 7);
switch (kind)
case 'next'
delta = dNext;
case 'previous'
delta = -dPrev;
case 'current'
delta = dow - dowT;
case 'nearest'
delta = dNext;
useprev = dPrev < dNext;
delta(useprev) = -dPrev(useprev);
case 'int'
if (n >= 1)
delta = dNext + (n - 1) * 7;
elseif (n <= -1)
delta = -(dPrev + (- n - 1) * 7);
else
delta = dow - dowT;
endif
endswitch
[Y, M, D] = dtAddDays (Y, M, D, delta);
else
unit = varargin{1};
units = {'second', 'minute', 'hour', 'day', 'week', 'month', ...
'quarter', 'year'};
if (! (ischar (unit) && isrow (unit) && any (strcmpi (unit, units))))
error (strcat ("datetime.dateshift: unit must be 'second',", ...
" 'minute', 'hour', 'day', 'week', 'month',", ...
" 'quarter', or 'year'."));
endif
unit = lower (unit);
n = 0;
if (numel (varargin) == 2)
[kind, nint] = dsRule (varargin{2});
switch (kind)
case 'current'
n = 0;
case 'next'
n = 1;
case 'previous'
n = -1;
case 'int'
n = nint;
case 'nearest'
[cY, cM, cD, ch, cm, cs] = dsStartComp (Y, M, D, h, mi, s, unit);
sc = dsSerialOf (this, cY, cM, cD, ch, cm, cs);
[nY, nM, nD, nh, nm, ns] = ...
dsShiftUnits (cY, cM, cD, ch, cm, cs, unit, 1);
sn = dsSerialOf (this, nY, nM, nD, nh, nm, ns);
st = serial (this);
st(keep) = sc(keep);
n = double ((st - sc) >= (sn - st));
endswitch
endif
[Y, M, D, h, mi, s] = dsShiftUnits (Y, M, D, h, mi, s, unit, n);
if (strcmp (op, 'start'))
[Y, M, D, h, mi, s] = dsStartComp (Y, M, D, h, mi, s, unit);
else
[Y, M, D, h, mi, s] = dsEndComp (Y, M, D, h, mi, s, unit);
endif
endif
R = this;
R.Year = Y; R.Month = M; R.Day = D;
R.Hour = h; R.Minute = mi; R.Second = s;
R = normalize (R);
if (any (keep(:)))
R.Year(keep) = this.Year(keep); R.Month(keep) = this.Month(keep);
R.Day(keep) = this.Day(keep); R.Hour(keep) = this.Hour(keep);
R.Minute(keep) = this.Minute(keep); R.Second(keep) = this.Second(keep);
endif
endfunction
endmethods
################################################################################
## ** Relational Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'lt' 'le' 'gt' 'ge' ##
## 'eq' 'ne' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} lt (@var{A}, @var{B})
##
## Less-than comparison for datetime arrays.
##
## @code{@var{TF} = lt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} < @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding element of @var{A} is an earlier
## point in time than that of @var{B}, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time compares as @qcode{false} against anything, just
## like @code{NaN}.
##
## @end deftypefn
function TF = lt (A, B)
TF = relcompare (A, B, 'lt');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} le (@var{A}, @var{B})
##
## Less-than-or-equal comparison for datetime arrays.
##
## @code{@var{TF} = le (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} <= @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding element of @var{A} is an earlier or
## equal point in time to that of @var{B}, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time compares as @qcode{false} against anything, just
## like @code{NaN}.
##
## @end deftypefn
function TF = le (A, B)
TF = relcompare (A, B, 'le');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} gt (@var{A}, @var{B})
##
## Greater-than comparison for datetime arrays.
##
## @code{@var{TF} = gt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} > @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding element of @var{A} is a later point
## in time than that of @var{B}, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time compares as @qcode{false} against anything, just
## like @code{NaN}.
##
## @end deftypefn
function TF = gt (A, B)
TF = relcompare (A, B, 'gt');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} ge (@var{A}, @var{B})
##
## Greater-than-or-equal comparison for datetime arrays.
##
## @code{@var{TF} = ge (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} >= @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding element of @var{A} is a later or
## equal point in time to that of @var{B}, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time compares as @qcode{false} against anything, just
## like @code{NaN}.
##
## @end deftypefn
function TF = ge (A, B)
TF = relcompare (A, B, 'ge');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} eq (@var{A}, @var{B})
##
## Equality comparison for datetime arrays.
##
## @code{@var{TF} = eq (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} == @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding elements of @var{A} and @var{B} are
## the same point in time, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time is never equal to anything, including another
## Not-A-Time, just like @code{NaN}.
##
## @end deftypefn
function TF = eq (A, B)
TF = relcompare (A, B, 'eq');
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{TF} =} ne (@var{A}, @var{B})
##
## Inequality comparison for datetime arrays.
##
## @code{@var{TF} = ne (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} != @var{B}} and returns a logical array set to
## @qcode{true} where the corresponding elements of @var{A} and @var{B} are
## not the same point in time, and @qcode{false} otherwise.
##
## Both operands must be datetime arrays and either both have a time zone or
## both be unzoned; zoned arrays are compared by their absolute instants, so
## the two time zones may differ. @var{A} and @var{B} must be size
## compatible. Not-A-Time is never equal to anything, so it compares as
## @qcode{true} against everything, including another Not-A-Time, just like
## @code{NaN}.
##
## @end deftypefn
function TF = ne (A, B)
TF = relcompare (A, B, 'ne');
endfunction
endmethods
################################################################################
## ** Array Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'cat' 'horzcat' 'vertcat' 'repmat' ##
## 'repelem' 'repelems' 'reshape' 'circshift' ##
## 'permute' 'ipermute' 'transpose' 'ctranspose' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} cat (@var{dim}, @var{A}, @var{B}, @dots{})
##
## Concatenate datetime arrays.
##
## @code{@var{C} = cat (@var{dim}, @var{A}, @var{B}, @dots{})} concatenates
## datetime arrays @var{A}, @var{B}, @dots{} along dimension @var{dim}. All
## input arrays must be datetime arrays and have the same size except along
## the operating dimension @var{dim}.
##
## @end deftypefn
function out = cat (dim, varargin)
args = varargin;
f = @(x) isa (x, 'datetime');
if (! all (cellfun (f, args)))
error ("datetime: invalid input to constructor.");
endif
out = args{1};
fieldArgs = cellfun (@(obj) obj.Year, args, 'UniformOutput', false);
out.Year = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Month, args, 'UniformOutput', false);
out.Month = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Day, args, 'UniformOutput', false);
out.Day = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Hour, args, 'UniformOutput', false);
out.Hour = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Minute, args, 'UniformOutput', false);
out.Minute = cat (dim, fieldArgs{:});
fieldArgs = cellfun (@(obj) obj.Second, args, 'UniformOutput', false);
out.Second = cat (dim, fieldArgs{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} horzcat (@var{A}, @var{B}, @dots{})
##
## Horizontal concatenation of datetime arrays.
##
## @code{@var{C} = horzcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}, @var{B}, @dots{}]} and horizontally
## concatenates the datetime arrays @var{A}, @var{B}, @dots{}. All input
## arrays must be datetime arrays and have the same size except along the
## second dimension.
##
## @end deftypefn
function out = horzcat (varargin)
out = cat (2, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{C} =} vertcat (@var{A}, @var{B}, @dots{})
##
## Vertical concatenation of datetime arrays.
##
## @code{@var{C} = vertcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}; @var{B}; @dots{}]} and vertically
## concatenates the datetime arrays @var{A}, @var{B}, @dots{}. All input
## arrays must be datetime arrays and have the same size except along the
## second dimension.
##
## @end deftypefn
function out = vertcat (varargin)
out = cat (1, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} repmat (@var{A}, @var{n})
## @deftypefnx {datetime} {@var{B} =} repmat (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {datetime} {@var{B} =} repmat (@var{A}, @var{dimvec})
##
## Repeat copies of a datetime array.
##
## @code{@var{B} = repmat (@var{A}, @var{n})} returns a datetime array
## @var{B} containing @var{n} copies of the input datetime array @var{A}
## along every dimension of @var{A}.
##
## @code{@var{B} = repmat (@var{A}, @var{d1}, @dots{}, @var{dN})} returns an
## array @var{B} containing copies of @var{A} along the dimensions specified
## by the list of scalar integer values @var{d1}, @dots{}, @var{dN}, which
## specify how many copies of @var{A} are made in each dimension.
##
## @code{@var{B} = repmat (@var{A}, @var{dimvec})} is equivalent to the
## previous syntax with @code{@var{dimvec} = [@var{d1}, @dots{}, @var{dN}]}.
##
## @end deftypefn
function this = repmat (this, varargin)
this.Year = repmat (this.Year, varargin{:});
this.Month = repmat (this.Month, varargin{:});
this.Day = repmat (this.Day, varargin{:});
this.Hour = repmat (this.Hour, varargin{:});
this.Minute = repmat (this.Minute, varargin{:});
this.Second = repmat (this.Second, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} repelem (@var{A}, @var{n})
## @deftypefnx {datetime} {@var{B} =} repelem (@var{A}, @var{d1}, @dots{}, @var{dN})
##
## Repeat copies of datetime array elements.
##
## @code{@var{B} = repelem (@var{A}, @var{n})} returns a datetime vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a datetime vector. If @var{n} is a scalar, each element of @var{A} is
## repeated @var{n} times along the non-singleton dimension of @var{A}. If
## @var{n} is a vector, it must have the same elements as @var{A}, in which
## case it specifies the number of times to repeat each corresponding
## element of @var{A}.
##
## @code{@var{B} = repelem (@var{A}, @var{d1}, @dots{}, @var{dN})} returns
## an array @var{B} with each element of @var{A} repeated according to the
## the list of input arguments @code{@var{d1}, @dots{}, @var{dN}} each
## corresponding to a different dimension @code{1:ndims (@var{A})} of the
## input array @var{A}. @var{d1}, @dots{}, @var{dN} must be either scalars
## or vectors with the same length as the corresponding dimension of
## @var{A} containing non-negative integer values specifying the number of
## repetitions of each element along the corresponding dimension.
##
## @end deftypefn
function this = repelem (this, varargin)
this.Year = repelem (this.Year, varargin{:});
this.Month = repelem (this.Month, varargin{:});
this.Day = repelem (this.Day, varargin{:});
this.Hour = repelem (this.Hour, varargin{:});
this.Minute = repelem (this.Minute, varargin{:});
this.Second = repelem (this.Second, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} repelems (@var{A}, @var{R})
##
## Construct a vector of repeated elements from a datetime array.
##
## @code{@var{B} = repelems (@var{A}, @var{R})} returns a datetime vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a datetime vector. @var{R} must be a @math{2*N} matrix of integers.
## Entries in the first row of @var{R} correspond to the linear indexing of
## the elements in @var{A} to be repeated. The corresponding entries in the
## second row of @var{R} specify the repeat count of each element.
##
## @end deftypefn
function this = repelems (this, R)
this.Year = repelems (this.Year, R);
this.Month = repelems (this.Month, R);
this.Day = repelems (this.Day, R);
this.Hour = repelems (this.Hour, R);
this.Minute = repelems (this.Minute, R);
this.Second = repelems (this.Second, R);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} reshape (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {datetime} {@var{B} =} reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})
## @deftypefnx {datetime} {@var{B} =} reshape (@var{A}, @var{dimvec})
##
## Reshape datetime array.
##
## @code{@var{B} = reshape (@var{A}, @var{d1}, @dots{}, @var{dN})} returns
## a datetime array @var{B} with specified dimensions @var{d1}, @dots{},
## @var{dN}, whose elements are taken columnwise from the datetime array
## @var{A}. The product of @var{d1}, @dots{}, @var{dN} must equal the total
## number of elements in @var{A}.
##
## @code{@var{B} = reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})} returns
## a datetime array @var{B} with one dimension unspecified which is
## calculated automatically so that the product of dimensions in @var{B}
## matches the total elements in @var{A}, which must be divisible the
## product of specified dimensions. An empty matrix @qcode{([])} is used to
## flag the unspecified dimension.
##
## @end deftypefn
function this = reshape (this, varargin)
this.Year = reshape (this.Year, varargin{:});
this.Month = reshape (this.Month, varargin{:});
this.Day = reshape (this.Day, varargin{:});
this.Hour = reshape (this.Hour, varargin{:});
this.Minute = reshape (this.Minute, varargin{:});
this.Second = reshape (this.Second, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} circshift (@var{A}, @var{n})
## @deftypefnx {datetime} {@var{B} =} circshift (@var{A}, @var{n}, @var{dim})
##
## Circularly shift the elements in a datetime array.
##
## @code{@var{B} = circshift (@var{A}, @var{n})} circularly shifts the
## elements of the datetime array @var{A} according to @var{n}. If @var{n}
## is a nonzero integer scalar, then the elements of @var{A} are shifted by
## @var{n} elements along the first non-singleton dimension of @var{A}. If
## @var{n} is a vector, it must not be longer that the number of dimensions
## of @var{A} with each value of @var{n} corresponding to a dimension in
## @var{A}. The sign of the value(s) in @var{n} specify the direction in
## the elements of @var{A} are shifted.
##
## @code{@var{B} = circshift (@var{A}, @var{n}, @var{dim})} circularly
## shifts the elements of the datetime array @var{A} along the dimension
## specified by @var{dim}. In this case, @var{n} must be a scalar integer
## value.
##
## @end deftypefn
function this = circshift (this, varargin)
this.Year = circshift (this.Year, varargin{:});
this.Month = circshift (this.Month, varargin{:});
this.Day = circshift (this.Day, varargin{:});
this.Hour = circshift (this.Hour, varargin{:});
this.Minute = circshift (this.Minute, varargin{:});
this.Second = circshift (this.Second, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} permute (@var{A}, @var{dims})
##
## Generalized transpose for a datetime N-D array.
##
## @code{@var{B} = permute (@var{A}, @var{dims})} returns the generalized
## transpose of the datetime array @var{A} by rearranging its dimensions
## according to the permutation vector specified in @var{dims}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{A})} of the
## input array @var{A}, in any order, but only once. The @var{N}th
## dimension of @var{A} gets remapped to the dimension in @var{B} specified
## by @code{@var{dims}(@var{N})}.
##
## @end deftypefn
function this = permute (this, order)
this.Year = permute (this.Year, order);
this.Month = permute (this.Month, order);
this.Day = permute (this.Day, order);
this.Hour = permute (this.Hour, order);
this.Minute = permute (this.Minute, order);
this.Second = permute (this.Second, order);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{A} =} ipermute (@var{B}, @var{dims})
##
## Inverse of the generalized transpose for a datetime N-D array.
##
## @code{@var{A} = ipermute (@var{B}, @var{dims})} returns the inverse of
## the generalized transpose performed by the @code{permute} function. The
## expression @code{ipermute (permute (@var{A}, @var{dims}), @var{dims})}
## returns the original array @var{A}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{B})} of the
## input array @var{B}, in any order, but only once. The dimension of
## @var{B} specified in @code{@var{dims}(@var{N})} gets remapped to the
## @var{N}th dimension of @var{A}.
##
## @end deftypefn
function this = ipermute (this, order)
this.Year = ipermute (this.Year, order);
this.Month = ipermute (this.Month, order);
this.Day = ipermute (this.Day, order);
this.Hour = ipermute (this.Hour, order);
this.Minute = ipermute (this.Minute, order);
this.Second = ipermute (this.Second, order);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} transpose (@var{A})
##
## Transpose a datetime matrix.
##
## @code{@var{B} = transpose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}.'} and returns the transpose of the datetime
## matrix @var{A}.
##
## @end deftypefn
function this = transpose (this)
this.Year = transpose (this.Year);
this.Month = transpose (this.Month);
this.Day = transpose (this.Day);
this.Hour = transpose (this.Hour);
this.Minute = transpose (this.Minute);
this.Second = transpose (this.Second);
endfunction
## -*- texinfo -*-
## @deftypefn {datetime} {@var{B} =} ctranspose (@var{A})
##
## Transpose a datetime matrix.
##
## @code{@var{B} = ctranspose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}'} and returns the transpose of the datetime
## matrix @var{A}. For datetime arrays, @code{ctranspose} is identical to
## @code{transpose}.
##
## @end deftypefn
function this = ctranspose (this)
this.Year = ctranspose (this.Year);
this.Month = ctranspose (this.Month);
this.Day = ctranspose (this.Day);
this.Hour = ctranspose (this.Hour);
this.Minute = ctranspose (this.Minute);
this.Second = ctranspose (this.Second);
endfunction
endmethods
################################################################################
## ** Reference and Assignment Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'end' 'subsref' 'subsasgn' ##
## ##
################################################################################
methods (Hidden)
## Overloaded end keyword
function last_index = end (this, end_dim, ndim_obj)
lastdim = ndims (this);
if (end_dim == ndim_obj && ndim_obj == 1)
last_index = prod (size (this));
elseif (end_dim == ndim_obj && end_dim < lastdim)
last_index = prod (size (this)(end_dim:lastdim));
else
last_index = size (this, end_dim);
endif
endfunction
## Class specific subscripted reference
function varargout = subsref (this, s)
chain_s = s(2:end);
s = s(1);
switch (s.type)
case '()'
out = this;
out.Year = this.Year(s.subs{:});
out.Month = this.Month(s.subs{:});
out.Day = this.Day(s.subs{:});
out.Hour = this.Hour(s.subs{:});
out.Minute = this.Minute(s.subs{:});
out.Second = this.Second(s.subs{:});
case '{}'
error (["datetime.subsref: '{}' invalid indexing", ...
" for referencing values. Use '()' instead."]);
case '.'
if (! ischar (s.subs))
error (["datetime.subsref: '.' index argument", ...
" must be a character vector."]);
endif
switch (s.subs)
case 'proxyArray' # used by 'table' class
out = proxyArray (this);
case 'Format'
out = this.Format;
case 'SystemTimeZone'
out = this.SystemTimeZone;
case 'TimeZone'
out = this.TimeZone;
case {'Year'}
out = this.Year;
case {'Month'}
out = this.Month;
case {'Day'}
out = this.Day;
case {'Hour'}
out = this.Hour;
case {'Minute'}
out = this.Minute;
case {'Second'}
out = this.Second;
otherwise
error ("datetime.subsref: unrecognized property: %s", s.subs);
endswitch
endswitch
## Chained references
if (! isempty (chain_s))
out = subsref (out, chain_s);
endif
varargout{1} = out;
endfunction
## Class specific subscripted assignment
function this = subsasgn (this, s, val)
if (numel (s) > 1)
# error ("duration.subsasgn: chained subscripts not allowed.");
p = s(2);
s = s(1);
if (! strcmp (p.type, '()'))
error (["datetime.subsasgn: '%s' invalid indexing", ...
" for assigning values. Use '()' instead."], p.type);
endif
else
p.subs = {':'};
endif
switch s.type
case '()'
if (isempty (val))
this.Year(s.subs{:}) = [];
this.Month(s.subs{:}) = [];
this.Day(s.subs{:}) = [];
this.Hour(s.subs{:}) = [];
this.Minute(s.subs{:}) = [];
this.Second(s.subs{:}) = [];
return;
elseif (! isa (val, "datetime"))
error (["datetime.subsasgn: cannot assign %s values", ...
"to a datetime array."], class (val));
endif
this.Year(s.subs{:}) = val.Year;
this.Month(s.subs{:}) = val.Month;
this.Day(s.subs{:}) = val.Day;
this.Hour(s.subs{:}) = val.Hour;
this.Minute(s.subs{:}) = val.Minute;
this.Second(s.subs{:}) = val.Second;
case '{}'
error (["datetime.subsasgn: '{}' invalid indexing", ...
" for assigning values. Use '()' instead."]);
case '.'
if (! ischar (s.subs))
error (["datetime.subsasgn: '.' index argument", ...
" must be a character vector."]);
endif
switch (s.subs)
case 'Format'
this.Format = val;
case 'TimeZone'
toTimeZone = val;
if (! (ischar (toTimeZone) && (isrow (toTimeZone) ...
|| isempty (toTimeZone))))
error (["datetime.subsasgn: 'TimeZone' must be a", ...
" character vector."]);
endif
## Validate the target zone (empty means an unzoned array).
if (! isempty (toTimeZone))
[~,~,~,~,~,~,errmsg] = __datetime__ (0, 0, 0, ...
'TimeZone', toTimeZone);
if (! isnumeric (errmsg))
error ("datetime.subsasgn: %s", errmsg);
endif
endif
if (isempty (this.TimeZone) || isempty (toTimeZone))
## Attaching a zone to an unzoned array, or dropping the zone,
## reinterprets/keeps the wall-clock values without converting.
this.TimeZone = toTimeZone;
else
## Switching between two zones preserves the absolute instant,
## so the wall-clock values shift by the offset difference.
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second, errmsg] = __datetime__ (this.Year, this.Month, ...
this.Day, this.Hour, this.Minute, this.Second, ...
'TimeZone', this.TimeZone, 'toTimeZone', toTimeZone, ...
'Precision', 'microseconds');
if (! isnumeric (errmsg))
error ("datetime.subsasgn: %s", errmsg);
endif
this.TimeZone = toTimeZone;
endif
case {'Year'}
this.Year(p.subs{:}) = val;
this = normalize (this);
case {'Month'}
this.Month(p.subs{:}) = val;
this = normalize (this);
case {'Day'}
this.Day(p.subs{:}) = val;
this = normalize (this);
case {'Hour'}
this.Hour(p.subs{:}) = val;
this = normalize (this);
case {'Minute'}
this.Minute(p.subs{:}) = val;
this = normalize (this);
case {'Second'}
this.Second(p.subs{:}) = val;
this = normalize (this);
otherwise
error ("datetime.subsasgn: unrecognized property: %s", s.subs);
endswitch
endswitch
endfunction
endmethods
methods (Access = private)
## Return true if the rows of the numeric matrix KD are in lexicographic
## non-decreasing order (used by 'issortedrows'). Equal entries (including
## the +Inf sentinel used for NaT, and genuine infinities) count as ties and
## are resolved by the next column.
function tf = rowsNonDecreasing (this, KD)
m = rows (KD);
if (m < 2)
tf = true;
return;
endif
a = KD(1:end-1, :);
b = KD(2:end, :);
undecided = true (m - 1, 1);
bad = false (m - 1, 1);
for j = 1:columns (KD)
lt = a(:, j) < b(:, j);
gt = a(:, j) > b(:, j);
bad = bad | (undecided & gt);
undecided = undecided & ! (lt | gt);
endfor
tf = ! any (bad);
endfunction
## Shared engine for 'min' and 'max'. ARGS is the method's varargin, ISMAX
## selects max over min, and NOUT is the caller's nargout. Handles both the
## reduction form (min (A), min (A, [], DIM), '-all', nan flags) and the
## two-array elementwise form (min (A, B)).
function [M, I] = minmaxImpl (A, args, ismax, nout)
if (ismax)
fname = 'max';
else
fname = 'min';
endif
I = [];
## Two-array elementwise form is signalled by a non-'[]' second argument.
elementwise = ! isempty (args) ...
&& ! (isnumeric (args{1}) && isempty (args{1}));
if (elementwise)
if (nout > 1)
error (strcat ("datetime.", fname, ": a second output is not", ...
" supported when comparing two arrays."));
endif
B = args{1};
if (! isa (B, 'datetime'))
error (strcat ("datetime.", fname, ": comparison of two arrays", ...
" requires both to be datetime."));
endif
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
error (strcat ("datetime.", fname, ": cannot compare a datetime", ...
" with a time zone to one without a time zone."));
endif
nanflag = 'omitnan';
for k = 2:numel (args)
x = args{k};
if (ischar (x) && isrow (x) && strcmpi (x, 'omitnan'))
nanflag = 'omitnan';
elseif (ischar (x) && isrow (x) && strcmpi (x, 'includenan'))
nanflag = 'includenan';
else
error (strcat ("datetime.", fname, ": invalid option in a", ...
" two-array comparison."));
endif
endfor
## Compare by absolute instant (zone-independent), but pick exact
## component values from whichever operand wins to avoid a lossy
## instant round-trip.
SA = serial (A);
SB = serial (B);
common = size (SA + SB);
SA = SA + zeros (common);
SB = SB + zeros (common);
if (ismax)
takeA = (SA >= SB) | isnan (SB);
else
takeA = (SA <= SB) | isnan (SB);
endif
## Express B's components in A's time zone so selected values are exact.
if (isempty (A.TimeZone) || strcmp (A.TimeZone, B.TimeZone))
YB = B.Year; MB = B.Month; DB = B.Day;
hB = B.Hour; mB = B.Minute; sB = B.Second;
else
[YB, MB, DB, hB, mB, sB] = __datetime__ (B.Year, B.Month, B.Day, ...
B.Hour, B.Minute, B.Second, 'TimeZone', B.TimeZone, ...
'toTimeZone', A.TimeZone, 'Precision', 'microseconds');
endif
z = zeros (common);
Y = A.Year + z; Mo = A.Month + z; D = A.Day + z;
h = A.Hour + z; mi = A.Minute + z; s = A.Second + z;
YB = YB + z; MB = MB + z; DB = DB + z;
hB = hB + z; mB = mB + z; sB = sB + z;
takeB = ! takeA;
Y(takeB) = YB(takeB); Mo(takeB) = MB(takeB); D(takeB) = DB(takeB);
h(takeB) = hB(takeB); mi(takeB) = mB(takeB); s(takeB) = sB(takeB);
if (strcmp (nanflag, 'includenan'))
nanpos = isnan (SA) | isnan (SB);
Y(nanpos) = NaN; Mo(nanpos) = NaN; D(nanpos) = NaN;
h(nanpos) = NaN; mi(nanpos) = NaN; s(nanpos) = NaN;
endif
M = A;
M.Year = Y; M.Month = Mo; M.Day = D;
M.Hour = h; M.Minute = mi; M.Second = s;
return;
endif
## Reduction form. Skip the '[]' placeholder, then read DIM / 'all' /
## the NaN flag from the remaining arguments.
rest = args;
if (! isempty (rest))
rest = rest(2:end);
endif
dim = [];
allflag = false;
nanflag = 'omitnan';
for k = 1:numel (rest)
x = rest{k};
if (isnumeric (x))
if (! isscalar (x) || x < 1 || x != fix (x))
error (strcat ("datetime.", fname, ...
": DIM must be a positive integer."));
endif
dim = x;
elseif (ischar (x) && isrow (x))
if (strcmpi (x, 'all'))
allflag = true;
elseif (strcmpi (x, 'omitnan'))
nanflag = 'omitnan';
elseif (strcmpi (x, 'includenan'))
nanflag = 'includenan';
else
error (strcat ("datetime.", fname, ": invalid option '", x, "'."));
endif
else
error (strcat ("datetime.", fname, ": invalid input argument."));
endif
endfor
if (isempty (A))
M = A;
return;
endif
S = serial (A);
if (allflag)
Sv = S(:);
if (ismax)
[~, iv] = max (Sv, [], 1);
else
[~, iv] = min (Sv, [], 1);
endif
if (strcmp (nanflag, 'includenan') && any (isnan (Sv)))
iv = find (isnan (Sv), 1);
endif
M = subset (A, iv);
I = iv;
return;
endif
if (isempty (dim))
dim = find (size (A) != 1, 1);
if (isempty (dim))
dim = 1;
endif
endif
if (dim > 2 || size (A, dim) < 2)
M = A;
I = ones (size (A));
return;
endif
if (ismax)
[~, I] = max (S, [], dim);
else
[~, I] = min (S, [], dim);
endif
if (strcmp (nanflag, 'includenan'))
nanmask = any (isnan (S), dim);
[~, firstnan] = max (isnan (S), [], dim);
I(nanmask) = firstnan(nanmask);
endif
[nr, nc] = size (S);
if (dim == 1)
lin = I + (0:nc-1) * nr;
else
lin = (1:nr)' + (I - 1) * nr;
endif
M = subset (A, lin);
endfunction
## Return a subset of the array
function this = subset (this, varargin)
this = this;
this.Year = this.Year(varargin{:});
this.Month = this.Month(varargin{:});
this.Day = this.Day(varargin{:});
this.Hour = this.Hour(varargin{:});
this.Minute = this.Minute(varargin{:});
this.Second = this.Second(varargin{:});
endfunction
## Numeric proxy used by 'table' and set operations for sorting, grouping,
## and set membership. Each datetime element maps to its six canonical
## components [Year, Month, Day, Hour, Minute, Second]; for a datetime
## matrix, each column contributes a six-column block. Not-A-Time (NaT)
## elements map to NaN across their components, just like the stored arrays.
function out = proxyArray (this)
[~, cols] = size (this.Year);
if (cols > 1)
out = [];
for i = 1:cols
SC = [this.Year(:,i), this.Month(:,i), this.Day(:,i), ...
this.Hour(:,i), this.Minute(:,i), this.Second(:,i)];
out = [out, SC];
endfor
else
out = [this.Year(:), this.Month(:), this.Day(:), ...
this.Hour(:), this.Minute(:), this.Second(:)];
endif
endfunction
## Re-canonicalise the component arrays after a direct component assignment
## (e.g. 'd.Month = 13' rolls the extra month into the year). This routes
## the raw values back through the same C++ normaliser used by the
## constructor, at microsecond precision so no sub-second detail is lost.
## Not-A-Time and infinite elements are passed through unchanged.
function this = normalize (this)
if (isempty (this.Year))
return;
endif
if (isempty (this.TimeZone))
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ (this.Year, this.Month, this.Day, ...
this.Hour, this.Minute, this.Second, 'Precision', 'microseconds');
else
[this.Year, this.Month, this.Day, this.Hour, this.Minute, ...
this.Second] = __datetime__ (this.Year, this.Month, this.Day, ...
this.Hour, this.Minute, this.Second, 'TimeZone', this.TimeZone, ...
'toTimeZone', this.TimeZone, 'Precision', 'microseconds');
endif
endfunction
## Absolute instant of each element as POSIX seconds (double, microsecond
## precision). Unzoned arrays are treated as UTC so the serial carries no
## system-zone daylight-saving offset; zoned arrays honour their zone (and
## DST). Not-A-Time maps to NaN and infinite elements keep their sign.
## Used by the arithmetic and relational instant-based comparisons.
function s = serial (this)
if (isempty (this.TimeZone))
tz = 'UTC';
else
tz = this.TimeZone;
endif
s = __datetime__ (this.Year, this.Month, this.Day, this.Hour, ...
this.Minute, this.Second, 'ConvertTo', 'posixtime', ...
'TimeZone', tz, 'Precision', 'microseconds');
endfunction
## Enforce the zone-compatibility rule for a set operation and express B in
## A's time zone so membership is decided on a shared wall clock (the
## absolute instants are preserved by the conversion). Both operands are
## already datetime arrays here; text/numeric promotion and rejection is
## done by the 'dtSetPromote' local function before this is called.
function [A, B] = prepSetOp (A, B, op)
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
error (strcat ("datetime.%s: cannot combine a datetime array with a", ...
" time zone with one without a time zone."), op);
endif
if (! isempty (A.TimeZone) && ! strcmp (A.TimeZone, B.TimeZone))
[B.Year, B.Month, B.Day, B.Hour, B.Minute, B.Second] = __datetime__ ...
(B.Year, B.Month, B.Day, B.Hour, B.Minute, B.Second, 'TimeZone', ...
B.TimeZone, 'toTimeZone', A.TimeZone, 'Precision', 'microseconds');
B.TimeZone = A.TimeZone;
endif
endfunction
## Broadcast two datetime arrays to a common size for an element-wise
## operation, erroring if their sizes are incompatible.
function [A, B] = broadcastPair (A, B, op)
try
z = zeros (size (A.Year + B.Year));
catch
error (strcat ("datetime.%s: A and B must be of common size or", ...
" scalars."), op);
end_try_catch
A.Year = A.Year + z; A.Month = A.Month + z; A.Day = A.Day + z;
A.Hour = A.Hour + z; A.Minute = A.Minute + z; A.Second = A.Second + z;
B.Year = B.Year + z; B.Month = B.Month + z; B.Day = B.Day + z;
B.Hour = B.Hour + z; B.Minute = B.Minute + z; B.Second = B.Second + z;
endfunction
## Assemble the result of a two-source set operation ('union'/'setxor'),
## whose values are drawn from both A (at IXA) and B (at IXB). The built-in
## returns those indices grouped A-then-B, which is exactly the 'stable'
## order; for the default 'sorted' order the gathered elements are reordered
## by their absolute instant (SA/SB), NaT sorting last. DOROWS selects the
## row-wise variant.
function C = combineSets (A, B, ixA, ixB, SA, SB, doRows, stable)
if (doRows)
C = vertcat (subset (A, ixA, ':'), subset (B, ixB, ':'));
if (! stable)
[~, perm] = sortrows ([SA(ixA,:); SB(ixB,:)]);
C = subset (C, perm, ':');
endif
else
Ca = subset (A, ixA); Cb = subset (B, ixB);
C = vertcat (reshape (Ca, numel (Ca), 1), reshape (Cb, numel (Cb), 1));
if (! stable)
sa = SA(ixA); sb = SB(ixB);
[~, perm] = sort ([sa(:); sb(:)]);
C = subset (C, perm);
endif
C = reshapeSetResult (C, isrow (A) && isrow (B));
endif
endfunction
## Calendar-aware difference from A to B, element-wise on equal-sized inputs,
## expressed in the requested COMPS. Whole units are taken greedily from the
## largest requested down to the smallest (years, quarters, months, then
## weeks, days), each taking the most that does not step past B; the day of
## month is clamped on month steps and a whole unit is only borrowed if the
## time of day allows it (31 Jan 10:00 to 28 Feb 08:00 is 27 days 22 hours,
## not one month). When 'Time' is requested the leftover is its absolute
## instant difference, so it is daylight-saving aware. Returns a
## calendarDuration; NaT operands yield NaN.
function C = calDiff (A, B, comps, op)
[f, fmt] = parseCalComponents (comps, op);
Y1 = A.Year; M1 = A.Month; D1 = A.Day;
h1 = A.Hour; mi1 = A.Minute; s1 = A.Second;
Y2 = B.Year; M2 = B.Month; D2 = B.Day;
h2 = B.Hour; mi2 = B.Minute; s2 = B.Second;
sz = size (Y1);
## A Not-A-Time operand yields a NaN result. Replace NaN components with a
## harmless placeholder for the calendar arithmetic, then restore NaN in
## the outputs, so month/day indexing never hits a NaN subscript.
bad = isnan (Y1) | isnan (Y2);
if (any (bad(:)))
Y1(bad) = 2000; M1(bad) = 1; D1(bad) = 1;
h1(bad) = 0; mi1(bad) = 0; s1(bad) = 0;
Y2(bad) = 2000; M2(bad) = 1; D2(bad) = 1;
h2(bad) = 0; mi2(bad) = 0; s2(bad) = 0;
endif
## Direction: +1 where A < B (forward), -1 where A > B, 0 where equal.
fwd = lexlt (Y1, M1, D1, h1, mi1, s1, Y2, M2, D2, h2, mi2, s2);
bwd = lexlt (Y2, M2, D2, h2, mi2, s2, Y1, M1, D1, h1, mi1, s1);
sgn = double (fwd) - double (bwd);
Yc = Y1; Mc = M1; Dc = D1; # current date; time stays A's throughout
monthsOut = zeros (sz);
daysOut = zeros (sz);
munits = [];
if (f.y)
munits(end+1) = 12;
endif
if (f.q)
munits(end+1) = 3;
endif
if (f.m)
munits(end+1) = 1;
endif
for u = munits
totalM = (Y2 - Yc) .* 12 + (M2 - Mc);
kApprox = fix (totalM ./ u);
[Yk, Mk, Dk] = dtAddMonths (Yc, Mc, Dc, kApprox .* u);
candGT = lexlt (Y2, M2, D2, h2, mi2, s2, Yk, Mk, Dk, h1, mi1, s1);
candLT = lexlt (Yk, Mk, Dk, h1, mi1, s1, Y2, M2, D2, h2, mi2, s2);
over = (sgn > 0 & candGT) | (sgn < 0 & candLT);
k = kApprox - sgn .* double (over);
monthsOut = monthsOut + k .* u;
[Yc, Mc, Dc] = dtAddMonths (Yc, Mc, Dc, k .* u);
endfor
dunits = [];
if (f.w)
dunits(end+1) = 7;
endif
if (f.d)
dunits(end+1) = 1;
endif
if (! isempty (dunits))
tLT = lexlt (0, 0, 0, h2, mi2, s2, 0, 0, 0, h1, mi1, s1);
tGT = lexlt (0, 0, 0, h1, mi1, s1, 0, 0, 0, h2, mi2, s2);
for u = dunits
totalD = datenum (Y2, M2, D2) - datenum (Yc, Mc, Dc);
wholeD = totalD - (sgn > 0 & tLT) + (sgn < 0 & tGT);
k = fix (wholeD ./ u);
daysOut = daysOut + k .* u;
[Yc, Mc, Dc] = dtAddDays (Yc, Mc, Dc, k .* u);
endfor
endif
if (f.t)
cur = A;
cur.Year = Yc; cur.Month = Mc; cur.Day = Dc;
remSec = serial (B) - serial (cur);
else
remSec = zeros (sz);
endif
monthsOut(bad) = NaN;
daysOut(bad) = NaN;
remSec(bad) = NaN;
Tdur = duration (0, 0, remSec);
C = calendarDuration (zeros (sz), monthsOut, daysOut, Tdur, 'Format', fmt);
endfunction
## Absolute instant of the given wall-clock components, interpreted in this
## array's time zone. Used by dateshift's 'nearest' rule to measure how far
## an element sits into its current unit.
function ser = dsSerialOf (this, Y, M, D, h, m, s)
tmp = this;
tmp.Year = Y; tmp.Month = M; tmp.Day = D;
tmp.Hour = h; tmp.Minute = m; tmp.Second = s;
ser = serial (normalize (tmp));
endfunction
## Build a datetime from reduced POSIX seconds (the result of mean/median/
## mode/std on this array's serial), preserving the Format and TimeZone.
function R = fromReducedSerial (this, ser)
R = this;
[Y, M, D, h, m, s] = serial2components (this, ser);
R.Year = Y; R.Month = M; R.Day = D;
R.Hour = h; R.Minute = m; R.Second = s;
endfunction
## Inverse of 'serial': map POSIX seconds back to the wall-clock components
## of this array's time zone. For a zoned array the serial is first read as
## a UTC wall clock and then converted into the target zone (honouring DST).
function [Y, M, D, h, m, s] = serial2components (this, ser)
if (isempty (this.TimeZone))
[Y, M, D, h, m, s] = __datetime__ (ser, 'ConvertFrom', 'posixtime', ...
'Precision', 'microseconds');
else
[Y, M, D, h, m, s] = __datetime__ (ser, 'ConvertFrom', 'posixtime', ...
'Precision', 'microseconds');
[Y, M, D, h, m, s] = __datetime__ (Y, M, D, h, m, s, ...
'TimeZone', 'UTC', 'toTimeZone', this.TimeZone, ...
'Precision', 'microseconds');
endif
endfunction
## Shift each element by a fixed number of seconds applied to its absolute
## instant (daylight-saving aware for zoned arrays), then rebuild the
## wall-clock components. DSEC may broadcast against the array size. The
## Format and TimeZone properties are preserved.
function this = addSeconds (this, dsec)
ser = serial (this) + dsec;
[Y, M, D, h, m, s] = serial2components (this, ser);
this.Year = Y; this.Month = M; this.Day = D;
this.Hour = h; this.Minute = m; this.Second = s;
endfunction
## Shift each element by a calendarDuration (SGN is +1 for addition, -1 for
## subtraction). Whole months are applied first with end-of-month day
## clamping, then whole calendar days (wall-clock preserving), then the
## time-of-day component as an instant. Not-A-Time and infinite elements are
## carried through unchanged.
function this = addCalendar (this, calD, sgn)
dMonths = sgn * calmonths (calD);
dDays = sgn * caldays (calD);
dTime = sgn * days (time (calD)) * 86400; # seconds
## Broadcast the instant components and the calendar deltas to a common
## size so the month math and the Not-A-Time / infinite masks all align.
base = zeros (size (this.Year)) + zeros (size (this.Month)) ...
+ zeros (size (this.Day)) + zeros (size (this.Hour)) ...
+ zeros (size (this.Minute)) + zeros (size (this.Second)) ...
+ zeros (size (dMonths)) + zeros (size (dDays));
Y = this.Year + base; M = this.Month + base; D = this.Day + base;
h = this.Hour + base; m = this.Minute + base; s = this.Second + base;
dM = dMonths + base; dD = dDays + base;
## An element is "live" only when both the instant and the calendar delta
## are finite; Not-A-Time and infinite inputs (from either operand)
## propagate straight through as the corresponding non-finite marker.
ok = isfinite (Y) & isfinite (dM) & isfinite (dD);
mk = Y + dM + dD;
## Add whole months, clamping the day to the last day of the target month
## (e.g. 31 Jan + 1 month -> 28 Feb), then add whole calendar days.
total = Y * 12 + (M - 1) + dM;
Y(ok) = floor (total(ok) / 12);
M(ok) = mod (total(ok), 12) + 1;
D(ok) = min (D(ok), eomday (Y(ok), M(ok))) + dD(ok);
Y(! ok) = mk(! ok); M(! ok) = mk(! ok); D(! ok) = mk(! ok);
h(! ok) = mk(! ok); m(! ok) = mk(! ok); s(! ok) = mk(! ok);
this.Year = Y; this.Month = M; this.Day = D;
this.Hour = h; this.Minute = m; this.Second = s;
this = normalize (this);
## Add the time-of-day component as an instant (daylight-saving aware).
if (any (dTime(:) != 0))
this = addSeconds (this, dTime + zeros (size (this.Year)));
endif
endfunction
## Range with a fixed-length (duration/numeric) step of STEPSEC seconds.
## The endpoints' absolute instants are stepped by the ordinary numeric
## colon (so the inclusive-endpoint tolerance matches numeric ranges), then
## rebuilt into this array's time zone. Empty and reversed ranges fall out
## naturally from the numeric colon.
function R = colonLinear (A, stepSec, B)
ser = serial (A) : stepSec : serial (B);
[Y, M, D, h, m, s] = serial2components (A, ser);
R = A;
R.Year = Y; R.Month = M; R.Day = D;
R.Hour = h; R.Minute = m; R.Second = s;
endfunction
## Range with a calendarDuration STEP. Each element is A + k*STEP for
## k = 0, 1, 2, ... (non-iterative, so month/year steps clamp the day of
## month per element). The number of steps is found by bracketing then
## binary-searching the largest k whose element has not passed B, which
## keeps calendar arithmetic exact without assuming a fixed element spacing.
function R = colonCalendar (A, step, B)
first = A + step;
if (first == A)
error ("datetime.colon: STEP must be nonzero.");
endif
incr = first > A;
if ((incr && A > B) || (! incr && A < B))
R = A + (0:-1) .* step; # empty range, keeps A's Format and TimeZone
return;
endif
hi = 1;
while (colon_within (A + hi .* step, B, incr) && hi < 2^40)
hi *= 2;
endwhile
lo = 0;
while (hi - lo > 1)
mid = floor ((lo + hi) / 2);
if (colon_within (A + mid .* step, B, incr))
lo = mid;
else
hi = mid;
endif
endwhile
R = A + (0:lo) .* step;
endfunction
## Shared implementation of the six relational operators. Both operands
## must be datetime and either both zoned or both unzoned; a zoned pair with
## differing zones is aligned onto A's zone (preserving the instant) so the
## wall-clock components can be compared directly. Comparison is
## lexicographic on [Year Month Day Hour Minute Second] and therefore exact
## at every magnitude. Not-A-Time (NaN components) never compares
## less/greater/equal, so only 'ne' returns true when a NaT is involved.
function TF = relcompare (A, B, op)
if (! (isa (A, 'datetime') && isa (B, 'datetime')))
error ("datetime.%s: both operands must be datetime arrays.", op);
endif
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
error (strcat ("datetime.%s: cannot compare a datetime array with a", ...
" time zone to one without a time zone."), op);
endif
aY = A.Year; aM = A.Month; aD = A.Day;
ah = A.Hour; am = A.Minute; asec = A.Second;
if (! isempty (A.TimeZone) && ! strcmp (A.TimeZone, B.TimeZone))
[bY, bM, bD, bh, bm, bsec] = __datetime__ (B.Year, B.Month, B.Day, ...
B.Hour, B.Minute, B.Second, 'TimeZone', B.TimeZone, ...
'toTimeZone', A.TimeZone, 'Precision', 'microseconds');
else
bY = B.Year; bM = B.Month; bD = B.Day;
bh = B.Hour; bm = B.Minute; bsec = B.Second;
endif
switch (op)
case 'eq'
TF = (aY == bY) & (aM == bM) & (aD == bD) ...
& (ah == bh) & (am == bm) & (asec == bsec);
case 'ne'
TF = ! ((aY == bY) & (aM == bM) & (aD == bD) ...
& (ah == bh) & (am == bm) & (asec == bsec));
case 'lt'
TF = lexlt (aY, aM, aD, ah, am, asec, bY, bM, bD, bh, bm, bsec);
case 'gt'
TF = lexlt (bY, bM, bD, bh, bm, bsec, aY, aM, aD, ah, am, asec);
case 'le'
TF = lexlt (aY, aM, aD, ah, am, asec, bY, bM, bD, bh, bm, bsec) ...
| ((aY == bY) & (aM == bM) & (aD == bD) ...
& (ah == bh) & (am == bm) & (asec == bsec));
case 'ge'
TF = lexlt (bY, bM, bD, bh, bm, bsec, aY, aM, aD, ah, am, asec) ...
| ((aY == bY) & (aM == bM) & (aD == bD) ...
& (ah == bh) & (am == bm) & (asec == bsec));
endswitch
endfunction
endmethods
endclassdef
## Shared back-end for 'isequal' (NANEQUAL false) and 'isequaln' (NANEQUAL
## true). ARGS is the cell array of operands. Returns true only when every
## operand is a datetime of the same size as the first and each pair of
## corresponding elements is the same point in time. A non-datetime operand or
## a time-zone mismatch (one zoned, one unzoned) yields false rather than an
## error. Zoned arrays are compared by absolute instant. When NANEQUAL is
## true, Not-A-Time elements compare equal to one another (component-wise NaN
## matches NaN); otherwise any NaT makes the result false, as with NaN.
function TF = do_isequal (args, nanEqual)
A = args{1};
TF = true;
for i = 2:numel (args)
B = args{i};
if (! (isa (A, 'datetime') && isa (B, 'datetime')))
TF = false;
return;
endif
if (! isequal (size (A), size (B)))
TF = false;
return;
endif
if (xor (isempty (A.TimeZone), isempty (B.TimeZone)))
TF = false;
return;
endif
if (isempty (A))
continue; # two empties of equal size compare equal
endif
## Align B onto A's zone so the wall-clock components compare by instant.
aY = A.Year; aM = A.Month; aD = A.Day;
ah = A.Hour; am = A.Minute; asec = A.Second;
if (! isempty (A.TimeZone) && ! strcmp (A.TimeZone, B.TimeZone))
[bY, bM, bD, bh, bm, bsec] = __datetime__ (B.Year, B.Month, B.Day, ...
B.Hour, B.Minute, B.Second, 'TimeZone', B.TimeZone, ...
'toTimeZone', A.TimeZone, 'Precision', 'microseconds');
else
bY = B.Year; bM = B.Month; bD = B.Day;
bh = B.Hour; bm = B.Minute; bsec = B.Second;
endif
if (nanEqual)
E = ceq (aY, bY) & ceq (aM, bM) & ceq (aD, bD) ...
& ceq (ah, bh) & ceq (am, bm) & ceq (asec, bsec);
else
E = (aY == bY) & (aM == bM) & (aD == bD) ...
& (ah == bh) & (am == bm) & (asec == bsec);
endif
if (! all (E(:)))
TF = false;
return;
endif
endfor
endfunction
## Component equality that also treats NaN as equal to NaN (used by isequaln).
function TF = ceq (x, y)
TF = (x == y) | (isnan (x) & isnan (y));
endfunction
## True while a candidate datetime X has not yet passed the range endpoint B,
## for an increasing (INCR true) or decreasing calendar range. Used to bracket
## and binary-search the element count in 'colonCalendar'.
function TF = colon_within (X, B, incr)
if (incr)
TF = X <= B;
else
TF = X >= B;
endif
endfunction
## Lexicographic strictly-less-than on datetime component arrays. Returns true
## where the [Year Month Day Hour Minute Second] tuple of the first operand is
## strictly earlier than that of the second. Any NaN component (Not-A-Time)
## makes the element false, matching NaN comparison semantics. All arguments
## broadcast against each other element-wise.
function TF = lexlt (aY, aM, aD, ah, am, asec, bY, bM, bD, bh, bm, bsec)
eqY = aY == bY; eqM = aM == bM; eqD = aD == bD;
eqh = ah == bh; eqm = am == bm;
TF = (aY < bY) ...
| (eqY & aM < bM) ...
| (eqY & eqM & aD < bD) ...
| (eqY & eqM & eqD & ah < bh) ...
| (eqY & eqM & eqD & eqh & am < bm) ...
| (eqY & eqM & eqD & eqh & eqm & asec < bsec);
endfunction
## Promote a set-operation operand to a datetime array. A datetime is returned
## unchanged; text (character vector, string, or cellstr) is parsed by the
## constructor, inheriting REF's time zone so the two operands share a frame;
## numeric, logical, and duration operands are rejected the way MATLAB rejects
## them. Defined at file scope (not as a method) so it dispatches correctly
## when the first set-operation argument is text rather than a datetime.
function d = dtSetPromote (x, ref, op)
if (isa (x, 'datetime'))
d = x;
elseif (ischar (x) || iscellstr (x) || isa (x, 'string'))
if (isempty (ref.TimeZone))
d = datetime (x);
else
d = datetime (x, 'TimeZone', ref.TimeZone);
endif
elseif (isa (x, 'duration') || isa (x, 'calendarDuration'))
error (strcat ("datetime.%s: comparison is not defined between datetime", ...
" and duration arrays."), op);
else
error (strcat ("datetime.%s: comparison is not defined between datetime", ...
" and numeric arrays."), op);
endif
endfunction
## Orient a (non-'rows') set-operation result: a row vector when both operands
## were row vectors, and a column vector otherwise (matching MATLAB, so an empty
## result is 0-by-1 rather than 0-by-0). C is a datetime array.
function C = reshapeSetResult (C, bothRows)
if (bothRows)
C = reshape (C, 1, numel (C));
else
C = reshape (C, numel (C), 1);
endif
endfunction
## Promote a bound of 'isbetween' to a datetime array. A datetime is returned
## unchanged; text is parsed by the constructor, inheriting REF's time zone;
## anything else (numeric, duration, ...) is rejected. Defined at file scope so
## it dispatches correctly when the argument is text rather than a datetime.
function d = dtIsbetweenArg (x, ref)
if (isa (x, 'datetime'))
d = x;
elseif (ischar (x) || iscellstr (x) || isa (x, 'string'))
if (isempty (ref.TimeZone))
d = datetime (x);
else
d = datetime (x, 'TimeZone', ref.TimeZone);
endif
else
error (strcat ("datetime.isbetween: LOWER and UPPER must be datetime", ...
" arrays or date/time text."));
endif
endfunction
## Translate datetime missing-value flags into the 'omitnan'/'includenan' flags
## understood by the core reduction functions, leaving dims, 'all', and the core
## flags untouched.
function args = dtStatFlags (args)
for i = 1:numel (args)
if (ischar (args{i}) && isrow (args{i}))
switch (lower (args{i}))
case {'omitnat', 'omitmissing'}
args{i} = 'omitnan';
case {'includenat', 'includemissing'}
args{i} = 'includenan';
endswitch
endif
endfor
endfunction
## Number of days in month M of year Y (element-wise, proleptic Gregorian).
function d = dtDaysInMonth (Y, M)
dpm = [31 28 31 30 31 30 31 31 30 31 30 31];
d = dpm(M);
d = reshape (d, size (M));
leap = (mod (Y, 4) == 0 & mod (Y, 100) != 0) | (mod (Y, 400) == 0);
d(M == 2 & leap) = 29;
endfunction
## Add K whole calendar months to the date (Y, M, D), clamping the day of month
## to the last valid day of the target month (e.g. 31 Jan + 1 month -> 28 Feb).
## Time of day is not represented here; it is carried unchanged by the caller.
function [Yo, Mo, Do] = dtAddMonths (Y, M, D, K)
idx = Y .* 12 + (M - 1) + K;
Yo = floor (idx ./ 12);
Mo = idx - Yo .* 12 + 1;
Do = min (D, dtDaysInMonth (Yo, Mo));
endfunction
## Add K whole calendar days to the date (Y, M, D), element-wise.
function [Yo, Mo, Do] = dtAddDays (Y, M, D, K)
dn = datenum (Y(:), M(:), D(:)) + K(:);
dv = datevec (dn);
Yo = reshape (dv(:,1), size (Y));
Mo = reshape (dv(:,2), size (Y));
Do = reshape (dv(:,3), size (Y));
endfunction
## Map a day-of-week name to its number (Sunday = 1 .. Saturday = 7); NaN for an
## unrecognised name.
function n = dsDayName (name)
names = {'sunday', 'monday', 'tuesday', 'wednesday', 'thursday', ...
'friday', 'saturday'};
n = find (strcmpi (name, names), 1);
if (isempty (n))
n = NaN;
endif
endfunction
## Parse a dateshift RULE into a kind ('current'/'next'/'previous'/'nearest'/
## 'int') and, for the integer kind, its value.
function [kind, n] = dsRule (r)
n = 0;
msg = strcat ("datetime.dateshift: rule must be an integer, 'next',", ...
" 'previous', 'current', or 'nearest'.");
if (ischar (r) && isrow (r))
if (any (strcmpi (r, {'current', 'next', 'previous', 'nearest'})))
kind = lower (r);
else
error (msg);
endif
elseif (isnumeric (r) && isscalar (r) && isreal (r) && r == fix (r))
kind = 'int';
n = r;
else
error (msg);
endif
endfunction
## Shift a date/time by N whole units (used by dateshift's rule). Calendar units
## produce a canonical date; sub-day units may overflow and are canonicalised by
## the caller's final normalisation.
function [Y, M, D, h, mi, s] = dsShiftUnits (Y, M, D, h, mi, s, unit, n)
switch (unit)
case 'year'
[Y, M, D] = dtAddMonths (Y, M, D, 12 .* n);
case 'quarter'
[Y, M, D] = dtAddMonths (Y, M, D, 3 .* n);
case 'month'
[Y, M, D] = dtAddMonths (Y, M, D, n);
case 'week'
[Y, M, D] = dtAddDays (Y, M, D, 7 .* n);
case 'day'
[Y, M, D] = dtAddDays (Y, M, D, n);
case 'hour'
h = h + n;
case 'minute'
mi = mi + n;
case 'second'
s = s + n;
endswitch
endfunction
## Truncate a date/time down to the start of the given calendar unit.
function [Y, M, D, h, mi, s] = dsStartComp (Y, M, D, h, mi, s, unit)
z = zeros (size (Y));
switch (unit)
case 'year'
M = ones (size (M)); D = ones (size (D)); h = z; mi = z; s = z;
case 'quarter'
M = 3 .* floor ((M - 1) / 3) + 1; D = ones (size (D));
h = z; mi = z; s = z;
case 'month'
D = ones (size (D)); h = z; mi = z; s = z;
case 'week'
dow = weekday (datenum (Y, M, D));
[Y, M, D] = dtAddDays (Y, M, D, -(dow - 1));
h = z; mi = z; s = z;
case 'day'
h = z; mi = z; s = z;
case 'hour'
mi = z; s = z;
case 'minute'
s = z;
case 'second'
s = floor (s);
endswitch
endfunction
## Compute the end of the given calendar unit. For the sub-day units and 'day'
## this is the start of the next unit; for a week it is the last day (Saturday);
## for month/quarter/year it is the last day of the unit at midnight. The
## results may overflow and are canonicalised by the caller's normalisation.
function [Y, M, D, h, mi, s] = dsEndComp (Y, M, D, h, mi, s, unit)
z = zeros (size (Y));
switch (unit)
case 'year'
M = 12 .* ones (size (M)); D = 31 .* ones (size (D));
h = z; mi = z; s = z;
case 'quarter'
qm = 3 .* ceil (M / 3);
D = dtDaysInMonth (Y, qm); M = qm; h = z; mi = z; s = z;
case 'month'
D = dtDaysInMonth (Y, M); h = z; mi = z; s = z;
case 'week'
dow = weekday (datenum (Y, M, D));
[Y, M, D] = dtAddDays (Y, M, D, 7 - dow);
h = z; mi = z; s = z;
case 'day'
[Y, M, D] = dtAddDays (Y, M, D, 1);
h = z; mi = z; s = z;
case 'hour'
h = h + 1; mi = z; s = z;
case 'minute'
mi = mi + 1; s = z;
case 'second'
s = floor (s) + 1;
endswitch
endfunction
## Error message shared by caldiff and between for an invalid COMPONENTS input.
function msg = calCompError (op)
msg = strcat ("datetime.", op, ": COMPONENTS must be 'Years', 'Quarters',", ...
" 'Months', 'Weeks', 'Days', or 'Time', or a string array or", ...
" cell array containing those components.");
endfunction
## Parse the COMPONENTS argument of caldiff/between into presence flags for each
## calendar unit and the display Format string of the resulting calendarDuration
## (which always contains 'm', 'd', and 't', with 'y'/'q'/'w' added only when
## those units are requested). An empty COMPONENTS selects the default set
## {Years, Months, Days, Time}.
function [f, fmt] = parseCalComponents (comps, op)
if (isempty (comps))
f = struct ('y', true, 'q', false, 'm', true, ...
'w', false, 'd', true, 't', true);
else
if (ischar (comps) && isrow (comps))
toks = {comps};
elseif (iscellstr (comps))
toks = comps(:)';
elseif (isa (comps, 'string'))
toks = cellstr (comps)(:)';
else
error (calCompError (op));
endif
f = struct ('y', false, 'q', false, 'm', false, ...
'w', false, 'd', false, 't', false);
for i = 1:numel (toks)
switch (lower (toks{i}))
case {'years', 'year', 'y'}
f.y = true;
case {'quarters', 'quarter', 'q'}
f.q = true;
case {'months', 'month', 'mo', 'm'}
f.m = true;
case {'weeks', 'week', 'w'}
f.w = true;
case {'days', 'day', 'd'}
f.d = true;
case {'time', 't'}
f.t = true;
otherwise
error (calCompError (op));
endswitch
endfor
if (! (f.y || f.q || f.m || f.w || f.d || f.t))
error (calCompError (op));
endif
endif
## The calendarDuration Format must contain 'm', 'd', and 't', so a
## single-component result such as caldiff (..., 'Years') keeps them even
## though only years are populated. This is invisible for a non-zero result
## (the other fields are zero and are not shown) but means an all-zero result
## displays as '0d' rather than MATLAB's '0y'/'0q'/'0w'; the stored value is
## the same.
fmt = '';
if (f.y)
fmt = [fmt, 'y'];
endif
if (f.q)
fmt = [fmt, 'q'];
endif
fmt = [fmt, 'm'];
if (f.w)
fmt = [fmt, 'w'];
endif
fmt = [fmt, 'dt'];
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/days.m 0000664 0000000 0000000 00000004112 15227665741 0020146 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{D} =} days (@var{X})
##
## Fixed-time duration in days.
##
## @code{@var{D} = days (@var{X})} returns a @qcode{duration} array representing
## fixed-time duration days equivalent to the values in @var{X}, which must be a
## numeric array.
##
## @code{days} is also available as a method for @qcode{duration} arrays, in
## which case it performs the opposite conversion.
##
## @seealso{duration, years, hours, minutes, seconds, milliseconds,
## duration.days}
## @end deftypefn
function out = days (x)
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("days: input array must be numeric.");
elseif (! isreal (x))
error ("days: input array must be real.");
endif
out = duration (double (x) * 24, 0, 0, 'Format', 'd');
endfunction
%!demo
%! ## `days` builds a *fixed-length* day of 24 hours (contrast a calendar day,
%! ## whose length varies across DST changes).
%!
%! days (2.5)
%!test
%! X = magic (3);
%! D = days (X);
%! assert_equal (size (D), size (X));
%!test
%! D = days ([1, 2, 3]);
%! assert_equal (days (D), [1, 2, 3]);
%!test
%! D = days (int16 (1));
%! assert_equal (days (D), 1);
%!test
%! D = days ();
%! assert_equal (days (D), 1);
%!error days ("asd");
%!error days (1+i);
pr0m1th3as-datatypes-9c9a8d3/inst/demos/ 0000775 0000000 0000000 00000000000 15227665741 0020141 5 ustar 00root root 0000000 0000000 pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.caldays 0000664 0000000 0000000 00000000256 15227665741 0024765 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `calendarDuration` method, `caldays` returns the day part of the span
%! ## as a whole number of days.
%!
%! d = calendarDuration (2, 3, 40)
%! caldays (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.calendarDuration 0000664 0000000 0000000 00000002464 15227665741 0026627 0 ustar 00root root 0000000 0000000 %!demo
%! ## `calendarDuration` represents a span in *calendar* units — years, months,
%! ## days, and a time-of-day. A calendar month or year is a real calendar step,
%! ## not a fixed number of days, which is what sets it apart from `duration`.
%! ## Give years, months and days:
%!
%! calendarDuration (1, 3, 10)
%!demo
%! ## Overflowing whole units normalise: 14 months rolls up into 1 year 2 months.
%! ## Days are kept separate (a month has no fixed number of days), so 40 stays 40.
%!
%! calendarDuration (1, 14, 40)
%!demo
%! ## The six-argument form adds a time-of-day: years, months, days, hours,
%! ## minutes, seconds.
%!
%! calendarDuration (0, 2, 5, 6, 30, 0)
%!demo
%! ## The `'Format'` option controls how the SAME span is broken down for display.
%! ## A format must contain `m`, `d` and `t`; it may also use `y` (years),
%! ## `q` (quarters) and `w` (weeks), listed in the order y q m w d t. Here one
%! ## span shown four ways:
%!
%! calendarDuration (1, 14, 40, 'Format', 'ymdt')
%! calendarDuration (1, 14, 40, 'Format', 'mdt')
%! calendarDuration (1, 14, 40, 'Format', 'qmwdt')
%! calendarDuration (1, 14, 40, 'Format', 'ymwdt')
%!demo
%! ## A numeric matrix with three (or six) columns builds a whole array at once —
%! ## one calendar duration per row.
%!
%! calendarDuration ([1, 2, 15; 0, 6, 3])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.calmonths 0000664 0000000 0000000 00000000461 15227665741 0025333 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `calendarDuration` *method*, `calmonths` inverts the builder: it returns
%! ## the whole span expressed as a number of months (years and months rolled
%! ## together). Compare `split`, which instead decomposes the span into parts.
%!
%! d = calendarDuration (2, 3, 40)
%! calmonths (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.calquarters 0000664 0000000 0000000 00000000305 15227665741 0025666 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `calendarDuration` method, `calquarters` returns the year-and-month part
%! ## of the span as a whole number of quarters.
%!
%! d = calendarDuration (2, 3, 40)
%! calquarters (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.calweeks 0000664 0000000 0000000 00000000261 15227665741 0025137 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `calendarDuration` method, `calweeks` returns the day part of the span
%! ## as a whole number of weeks.
%!
%! d = calendarDuration (0, 0, 40)
%! calweeks (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.calyears 0000664 0000000 0000000 00000000313 15227665741 0025142 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `calendarDuration` method, `calyears` returns the number of whole years
%! ## in the span (the inverse of the `calyears` builder).
%!
%! d = calendarDuration (2, 3, 40)
%! calyears (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.cellstr 0000664 0000000 0000000 00000000205 15227665741 0025007 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cellstr` converts the array into a cell array of its display strings.
%!
%! d = calmonths ([1, 13, 25])
%! cellstr (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.char 0000664 0000000 0000000 00000000276 15227665741 0024264 0 ustar 00root root 0000000 0000000 %!demo
%! ## `char` converts the array into a character matrix of its display strings,
%! ## one row per element (shorter rows padded with spaces).
%!
%! d = calmonths ([1, 13])
%! char (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.datevec 0000664 0000000 0000000 00000000331 15227665741 0024752 0 ustar 00root root 0000000 0000000 %!demo
%! ## `datevec` returns the span as a numeric row `[Y MO D H MI S]` per element,
%! ## handy for feeding the raw components into other calculations.
%!
%! d = calendarDuration (1, 2, 3, 4, 5, 6)
%! datevec (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.eq 0000664 0000000 0000000 00000000326 15227665741 0023750 0 ustar 00root root 0000000 0000000 %!demo
%! ## `eq` (`==`) tests calendar durations for equality. Equivalent spans compare
%! ## equal even when written with different builders.
%!
%! calmonths (12) == calyears (1)
%! calweeks (2) == caldays (14)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.ismissing 0000664 0000000 0000000 00000000356 15227665741 0025353 0 ustar 00root root 0000000 0000000 %!demo
%! ## For a calendar duration `ismissing` is the same test as `isnan`: a NaN span
%! ## is the missing value, so calendar durations plug into the generic
%! ## missing-data tools.
%!
%! d = calmonths ([1, NaN, 3])
%! ismissing (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.isnan 0000664 0000000 0000000 00000000213 15227665741 0024446 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isnan` flags the elements built from a NaN component — a Not-a-Number span.
%!
%! d = calmonths ([1, NaN, 3])
%! isnan (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.minus 0000664 0000000 0000000 00000000205 15227665741 0024472 0 ustar 00root root 0000000 0000000 %!demo
%! ## `minus` (`-`) subtracts one calendar duration from another.
%!
%! a = calyears (2) + calmonths (2)
%! a - calmonths (5)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.plus 0000664 0000000 0000000 00000000341 15227665741 0024323 0 ustar 00root root 0000000 0000000 %!demo
%! ## `plus` (`+`) adds calendar durations. Because the units are calendar units,
%! ## the sum normalises on display (here 6 + 9 months rolls into a year).
%!
%! a = calyears (1) + calmonths (6)
%! a + calmonths (9)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.split 0000664 0000000 0000000 00000000570 15227665741 0024477 0 ustar 00root root 0000000 0000000 %!demo
%! ## `split` decomposes a calendar duration into the whole-unit components you
%! ## request, distributing the span across them. (Contrast the single-unit
%! ## extractors such as `calmonths`, which each return the span as a *total* in
%! ## one unit.)
%!
%! d = calendarDuration (2, 3, 40)
%! [y, mo, days] = split (d, {'years', 'months', 'days'});
%! [y, mo, days]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.time 0000664 0000000 0000000 00000000263 15227665741 0024301 0 ustar 00root root 0000000 0000000 %!demo
%! ## `time` extracts the time-of-day part as a `duration`, discarding the
%! ## calendar (year/month/day) part.
%!
%! d = calendarDuration (0, 1, 2, 6, 30, 0)
%! time (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.times 0000664 0000000 0000000 00000000305 15227665741 0024461 0 ustar 00root root 0000000 0000000 %!demo
%! ## `times` (`.*`) scales a calendar duration by an integer factor.
%!
%! q = calmonths (3)
%! q * 4
%!
%! ## Scaling by an array yields an array of durations.
%! caldays (7) .* [1, 2, 3]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.unique 0000664 0000000 0000000 00000000250 15227665741 0024645 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unique` returns the distinct calendar durations in an array (equivalent
%! ## spans count as one).
%!
%! d = calmonths ([1, 13, 1, 25, 13])
%! unique (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/calendarDuration.vertcat 0000664 0000000 0000000 00000000263 15227665741 0025013 0 ustar 00root root 0000000 0000000 %!demo
%! ## Calendar durations concatenate like ordinary arrays; `[a; b]` stacks them
%! ## into a single column.
%!
%! a = calyears ([1; 2])
%! b = calmonths ([3; 4])
%! [a; b]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.addcats 0000664 0000000 0000000 00000000655 15227665741 0023751 0 ustar 00root root 0000000 0000000 %!demo
%! ## `addcats` adds new, initially-empty categories without changing any values —
%! ## handy to reserve labels that may appear later. For an ordinal array place
%! ## the new category with `'Before'`/`'After'` so the order stays sensible.
%!
%! C = categorical ({'S'; 'M'; 'S'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! categories (C)
%!
%! ## Reserve `XL` just after `L`.
%! categories (addcats (C, 'XL', 'After', 'L'))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.categorical 0000664 0000000 0000000 00000001542 15227665741 0024617 0 ustar 00root root 0000000 0000000 %!demo
%! ## `categorical` stores discrete labels compactly: each value becomes an index
%! ## into a shared list of *categories*. Starting from repeated text labels ...
%!
%! sizes = {'M'; 'S'; 'L'; 'M'; 'S'; 'L'; 'M'}
%!
%! ## ... the categories are detected automatically — the sorted unique values.
%! C = categorical (sizes)
%! categories (C)
%!demo
%! ## Supply a *valueset* with `'Ordinal', true` to impose a meaningful order, so
%! ## the values compare with `<` and `>`, not only `==`.
%!
%! raw = {'M'; 'S'; 'L'; 'M'}
%! C = categorical (raw, {'S', 'M', 'L'}, 'Ordinal', true)
%!
%! ## Ordering questions now make sense.
%! C >= 'M'
%!demo
%! ## A third argument renames the categories as you build; empty labels become
%! ## the special `` element.
%!
%! codes = {'1'; '2'; ''; '1'}
%! C = categorical (codes, {'1', '2'}, {'low', 'high'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.categories 0000664 0000000 0000000 00000000572 15227665741 0024471 0 ustar 00root root 0000000 0000000 %!demo
%! ## `categories` lists an array's categories — the full declared label set, not
%! ## merely the values that happen to be present.
%!
%! C = categorical ({'M'; 'S'; 'M'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! categories (C)
%!
%! ## `L` is a declared category (and, being ordinal, keeps its place in the
%! ## order) even though no element currently takes that value.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.cellstr 0000664 0000000 0000000 00000000340 15227665741 0024005 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cellstr` converts the array back into a cell array of character vectors —
%! ## the labels themselves. `` elements become empty strings.
%!
%! C = categorical ({'M'; 'S'; ''; 'L'})
%! cellstr (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.char 0000664 0000000 0000000 00000000351 15227665741 0023254 0 ustar 00root root 0000000 0000000 %!demo
%! ## `char` converts the array to a character matrix of its labels, one row per
%! ## element (shorter labels are padded with spaces, as for any `char` matrix).
%!
%! C = categorical ({'small'; 'large'; 'small'})
%! char (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.countcats 0000664 0000000 0000000 00000000501 15227665741 0024337 0 ustar 00root root 0000000 0000000 %!demo
%! ## `countcats` tallies how many elements fall in each category, in category
%! ## order. Categories with no elements are counted as zero, so the result lines
%! ## up one-to-one with `categories`.
%!
%! C = categorical ({'M'; 'S'; 'L'; 'M'; 'S'; 'M'}, {'S', 'M', 'L', 'XL'})
%! categories (C)
%! countcats (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.double 0000664 0000000 0000000 00000000421 15227665741 0023607 0 ustar 00root root 0000000 0000000 %!demo
%! ## `double` returns the integer *category codes* — each value's 1-based index
%! ## into the category list. `` elements map to `NaN`.
%!
%! C = categorical ({'S'; 'M'; 'L'; ''; 'S'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! categories (C)
%! double (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.eq 0000664 0000000 0000000 00000000645 15227665741 0022752 0 ustar 00root root 0000000 0000000 %!demo
%! ## `eq` (the `==` operator) compares a categorical array element by element,
%! ## either to a single category name or to another categorical array. Equality
%! ## works for every categorical — nominal or ordinal.
%!
%! C = categorical ({'M'; 'S'; 'L'; 'M'})
%!
%! ## Which elements equal a given category?
%! C == 'M'
%!
%! ## Element-wise against a second array.
%! C == categorical ({'M'; 'M'; 'L'; 'S'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.histcounts 0000664 0000000 0000000 00000000457 15227665741 0024551 0 ustar 00root root 0000000 0000000 %!demo
%! ## `histcounts` bins a categorical array by category and returns the count in
%! ## each — the histogram companion of `countcats`, with a second output naming
%! ## the bins.
%!
%! C = categorical ({'M'; 'S'; 'L'; 'M'; 'S'; 'M'}, {'S', 'M', 'L'})
%! [N, cats] = histcounts (C);
%! N
%! cats
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.intersect 0000664 0000000 0000000 00000000345 15227665741 0024342 0 ustar 00root root 0000000 0000000 %!demo
%! ## `intersect` returns the categories common to the values of two arrays — set
%! ## arithmetic over categorical data.
%!
%! A = categorical ({'S'; 'M'; 'L'})
%! B = categorical ({'M'; 'L'; 'XL'})
%! intersect (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.iscategory 0000664 0000000 0000000 00000000452 15227665741 0024512 0 ustar 00root root 0000000 0000000 %!demo
%! ## `iscategory` tests whether names are categories of the array — independently
%! ## of whether any element currently takes those values.
%!
%! C = categorical ({'M'; 'S'}, {'S', 'M', 'L'})
%! iscategory (C, {'M', 'L', 'XL'})
%!
%! ## `M` and `L` are declared categories; `XL` is not.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.ismember 0000664 0000000 0000000 00000000347 15227665741 0024147 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ismember` tests, element by element, whether each value appears in a second
%! ## set given as category names or as another categorical array.
%!
%! C = categorical ({'M'; 'S'; 'XL'; 'L'})
%! ismember (C, {'S', 'M'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.ismissing 0000664 0000000 0000000 00000000463 15227665741 0024350 0 ustar 00root root 0000000 0000000 %!demo
%! ## For a categorical array `ismissing` is the same test as `isundefined`: the
%! ## missing value *is* the `` element. It exists so categoricals
%! ## plug into the generic missing-data tools (`rmmissing`, `standardizeMissing`).
%!
%! C = categorical ({'M'; ''; 'L'})
%! ismissing (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.isordinal 0000664 0000000 0000000 00000000730 15227665741 0024324 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isordinal` reports whether the categories carry an order. A plain array is
%! ## *nominal* — its categories are just labels with no ranking ...
%!
%! N = categorical ({'red'; 'green'; 'blue'})
%! isordinal (N)
%!
%! ## ... while one built with `'Ordinal', true` is ordered, which is what lets it
%! ## be compared with `<` and `>` and sorted meaningfully.
%!
%! O = categorical ({'lo'; 'hi'; 'mid'}, {'lo', 'mid', 'hi'}, 'Ordinal', true)
%! isordinal (O)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.isprotected 0000664 0000000 0000000 00000000711 15227665741 0024664 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isprotected` reports whether the category list is locked. A nominal array
%! ## is *unprotected*: assigning a new label simply extends its categories ...
%!
%! N = categorical ({'M'; 'S'})
%! isprotected (N)
%!
%! ## ... whereas ordinal arrays (and ones built with `'Protected', true`) are
%! ## protected, so only their declared categories may be used.
%!
%! O = categorical ({'M'; 'S'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! isprotected (O)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.issorted 0000664 0000000 0000000 00000000551 15227665741 0024175 0 ustar 00root root 0000000 0000000 %!demo
%! ## `issorted` checks whether an ordinal array is already in non-decreasing
%! ## category order — a cheap test to skip a needless `sort`.
%!
%! C = categorical ({'S'; 'M'; 'L'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! issorted (C)
%!
%! ## The same categories out of order:
%! issorted (categorical ({'M'; 'S'; 'L'}, {'S', 'M', 'L'}, 'Ordinal', true))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.isundefined 0000664 0000000 0000000 00000000563 15227665741 0024641 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isundefined` flags the elements that belong to no category — the
%! ## `` values that stand in for missing data. Empty labels become
%! ## undefined at construction time.
%!
%! C = categorical ({'M'; ''; 'L'; 'M'})
%! isundefined (C)
%!
%! ## Dropping a category also undefines every element that used it.
%! isundefined (removecats (C, 'M'))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.lt 0000664 0000000 0000000 00000000733 15227665741 0022762 0 ustar 00root root 0000000 0000000 %!demo
%! ## `lt` (the `<` operator) ranks values by category order, so it needs an
%! ## *ordinal* array. It compares against a category name or another ordinal
%! ## array.
%!
%! C = categorical ({'M'; 'S'; 'L'; 'M'}, {'S', 'M', 'L'}, 'Ordinal', true)
%!
%! ## Which sizes are strictly smaller than `L`?
%! C < 'L'
%!
%! ## `>`, `<=` and `>=` behave the same way; the same test on a nominal array
%! ## would raise an error, because unordered categories cannot be ranked.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.max 0000664 0000000 0000000 00000000334 15227665741 0023125 0 ustar 00root root 0000000 0000000 %!demo
%! ## `max` returns the highest-ranked category present in an ordinal array,
%! ## by category order rather than by label.
%!
%! C = categorical ({'M'; 'L'; 'S'; 'M'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! max (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.median 0000664 0000000 0000000 00000000355 15227665741 0023600 0 ustar 00root root 0000000 0000000 %!demo
%! ## `median` returns the middle category by rank — defined for ordinal arrays,
%! ## where the categories have a genuine order.
%!
%! C = categorical ({'S'; 'M'; 'L'; 'M'; 'L'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! median (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.mergecats 0000664 0000000 0000000 00000000510 15227665741 0024306 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mergecats` collapses several categories into one, relabelling every element
%! ## that used them — a quick way to coarsen a classification.
%!
%! C = categorical ({'S'; 'M'; 'L'; 'S'; 'M'}, {'S', 'M', 'L'})
%!
%! ## Fold `S` and `M` together into a single `small` category.
%! mergecats (C, {'S', 'M'}, 'small')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.min 0000664 0000000 0000000 00000000546 15227665741 0023130 0 ustar 00root root 0000000 0000000 %!demo
%! ## `min` returns the lowest-ranked category present in an ordinal array —
%! ## ranking follows the category order, not the alphabetical label.
%!
%! C = categorical ({'M'; 'L'; 'S'; 'M'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! min (C)
%!
%! ## A second output gives the index of that element (as for numeric `min`).
%! [lo, idx] = min (C);
%! idx
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.mode 0000664 0000000 0000000 00000000415 15227665741 0023264 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mode` returns the most frequent category. It is the one central-tendency
%! ## statistic that also works for *nominal* arrays, since it counts occurrences
%! ## rather than ranking them.
%!
%! C = categorical ({'M'; 'S'; 'M'; 'L'; 'M'; 'S'})
%! mode (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.removecats 0000664 0000000 0000000 00000000604 15227665741 0024510 0 ustar 00root root 0000000 0000000 %!demo
%! ## `removecats` drops categories from an array.
%!
%! C = categorical ({'S'; 'M'; 'S'}, {'S', 'M', 'L'})
%!
%! ## Naming a category removes it and turns its elements into ``.
%! removecats (C, 'M')
%!
%! ## With no list only the *unused* categories go (values unchanged) — here the
%! ## unused `L` disappears from the category list.
%! categories (removecats (C))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.renamecats 0000664 0000000 0000000 00000000602 15227665741 0024460 0 ustar 00root root 0000000 0000000 %!demo
%! ## `renamecats` changes category *names* while leaving the values in place.
%!
%! C = categorical ({'S'; 'M'; 'L'; 'S'}, {'S', 'M', 'L'})
%!
%! ## Give a full set of new names (in category order) to rename them all ...
%! renamecats (C, {'Small', 'Medium', 'Large'})
%!
%! ## ... or rename only specific categories by old-name to new-name.
%! renamecats (C, {'S'}, {'Small'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.reordercats 0000664 0000000 0000000 00000000662 15227665741 0024661 0 ustar 00root root 0000000 0000000 %!demo
%! ## `reordercats` changes the order of the categories. For an *ordinal* array
%! ## this redefines the ranking used by `<`, `>`, `sort`, `min` and `max`.
%!
%! C = categorical ({'M'; 'S'; 'L'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! categories (C)
%!
%! ## Reverse the order so that `S` now ranks highest.
%! B = reordercats (C, {'L', 'M', 'S'});
%! categories (B)
%!
%! ## The comparison follows the new ranking.
%! B >= 'M'
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.setcats 0000664 0000000 0000000 00000000610 15227665741 0024003 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setcats` replaces the whole category list with the one you give: values
%! ## that fall outside the new set become ``, and the categories end
%! ## up as exactly the names you specified (in that order).
%!
%! C = categorical ({'S'; 'M'; 'L'; 'M'}, {'S', 'M', 'L'})
%!
%! ## Keep only `S` and `M`; the `L` element is dropped to .
%! setcats (C, {'S', 'M'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.setdiff 0000664 0000000 0000000 00000000271 15227665741 0023764 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setdiff` returns the values present in the first array but not the second.
%!
%! A = categorical ({'S'; 'M'; 'L'})
%! B = categorical ({'M'; 'L'; 'XL'})
%! setdiff (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.setxor 0000664 0000000 0000000 00000000311 15227665741 0023657 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setxor` returns the symmetric difference — values in exactly one of the two
%! ## arrays.
%!
%! A = categorical ({'S'; 'M'; 'L'})
%! B = categorical ({'M'; 'L'; 'XL'})
%! setxor (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.sort 0000664 0000000 0000000 00000000410 15227665741 0023322 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sort` orders an ordinal array by its category *ranking*, not alphabetically
%! ## by label.
%!
%! C = categorical ({'L'; 'S'; 'M'; 'S'; 'L'}, {'S', 'M', 'L'}, 'Ordinal', true)
%! sort (C)
%!
%! ## Any `` values sort to the end by default.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.summary 0000664 0000000 0000000 00000000364 15227665741 0024040 0 ustar 00root root 0000000 0000000 %!demo
%! ## `summary` tabulates the count of each category — including the
%! ## `` element — giving a quick frequency overview of the array.
%!
%! C = categorical ({'M'; 'S'; 'L'; 'M'; ''; 'M'}, {'S', 'M', 'L'})
%! summary (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.union 0000664 0000000 0000000 00000000272 15227665741 0023471 0 ustar 00root root 0000000 0000000 %!demo
%! ## `union` returns the distinct values present in either array — the set union.
%!
%! A = categorical ({'S'; 'M'; 'L'})
%! B = categorical ({'M'; 'L'; 'XL'})
%! union (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.unique 0000664 0000000 0000000 00000000426 15227665741 0023650 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unique` returns the distinct values *present* in the array, as a categorical
%! ## array. (Contrast `categories`, which lists the full declared label set even
%! ## when some categories are unused.)
%!
%! C = categorical ({'M'; 'S'; 'M'; 'L'; 'S'})
%! unique (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/categorical.vertcat 0000664 0000000 0000000 00000000426 15227665741 0024012 0 ustar 00root root 0000000 0000000 %!demo
%! ## Concatenating categorical arrays *unions* their category lists, so the result
%! ## can hold categories that neither operand had alone. `[A; B]` stacks them.
%!
%! A = categorical ({'S'; 'M'})
%! B = categorical ({'L'; 'XL'})
%! C = [A; B];
%! C
%! categories (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.abs 0000664 0000000 0000000 00000000172 15227665741 0022455 0 ustar 00root root 0000000 0000000 %!demo
%! ## `abs` returns the magnitude of a (possibly negative) duration.
%!
%! d = minutes (30) - hours (2)
%! abs (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.bounds 0000664 0000000 0000000 00000000223 15227665741 0023177 0 ustar 00root root 0000000 0000000 %!demo
%! ## `bounds` returns the smallest and largest durations in one call.
%!
%! d = hours ([2, 5, 3, 9])
%! [lo, hi] = bounds (d);
%! [lo, hi]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.ceil 0000664 0000000 0000000 00000000146 15227665741 0022625 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ceil` rounds a duration up to a whole unit.
%!
%! d = minutes (90)
%! ceil (d, 'hours')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.cellstr 0000664 0000000 0000000 00000000201 15227665741 0023351 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cellstr` converts the array into a cell array of its display strings.
%!
%! d = minutes ([90, 150])
%! cellstr (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.center 0000664 0000000 0000000 00000000301 15227665741 0023162 0 ustar 00root root 0000000 0000000 %!demo
%! ## `center` subtracts the mean from each element, so the result is centred on
%! ## zero — the deviations from the average duration.
%!
%! d = hours ([1, 2, 3, 4, 5])
%! center (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.char 0000664 0000000 0000000 00000000234 15227665741 0022624 0 ustar 00root root 0000000 0000000 %!demo
%! ## `char` converts the array into a character matrix of its display strings,
%! ## one row per element.
%!
%! d = hours ([1.5; 2.25])
%! char (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.colon 0000664 0000000 0000000 00000000273 15227665741 0023024 0 ustar 00root root 0000000 0000000 %!demo
%! ## The colon operator builds an evenly-spaced range of durations, using a
%! ## duration step — here every half hour from 0 to 2 hours.
%!
%! hours (0):minutes (30):hours (2)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.cummax 0000664 0000000 0000000 00000000236 15227665741 0023203 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cummax` returns the running maximum — each element is the largest duration
%! ## seen so far.
%!
%! d = hours ([2, 4, 3, 7, 5])
%! cummax (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.cummin 0000664 0000000 0000000 00000000237 15227665741 0023202 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cummin` returns the running minimum — each element is the smallest duration
%! ## seen so far.
%!
%! d = hours ([7, 4, 5, 2, 3])
%! cummin (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.cumsum 0000664 0000000 0000000 00000000204 15227665741 0023215 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cumsum` returns the running total of the durations — a cumulative sum.
%!
%! d = hours ([1, 2, 3, 4])
%! cumsum (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.datevec 0000664 0000000 0000000 00000000321 15227665741 0023317 0 ustar 00root root 0000000 0000000 %!demo
%! ## `datevec` returns the components as a numeric row `[Y MO D H MI S]` per
%! ## element (a duration has no year/month/day, so those columns are zero).
%!
%! d = duration (26, 30, 15)
%! datevec (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.days 0000664 0000000 0000000 00000000222 15227665741 0022644 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` method, `days` returns the duration expressed in
%! ## fixed-length (24-hour) days.
%!
%! d = hours (36)
%! days (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.diff 0000664 0000000 0000000 00000000267 15227665741 0022625 0 ustar 00root root 0000000 0000000 %!demo
%! ## `diff` returns the differences between successive durations — for example the
%! ## gaps between a series of elapsed times.
%!
%! d = hours ([1, 3, 6, 10])
%! diff (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.duration 0000664 0000000 0000000 00000002343 15227665741 0023537 0 ustar 00root root 0000000 0000000 %!demo
%! ## `duration` represents a *fixed-length* elapsed time — unlike
%! ## `calendarDuration`, here a day is always 24 hours and a year a fixed number
%! ## of days. Give hours, minutes and seconds:
%!
%! duration (1, 30, 15)
%!demo
%! ## Values need not lie in the usual ranges — 25 hours is fine and stays 25
%! ## hours in the default `hh:mm:ss` display. A fourth argument adds milliseconds.
%!
%! duration (25, 30, 0)
%! duration (0, 0, 1, 500)
%!demo
%! ## Build from time strings, optionally naming the `'InputFormat'`.
%!
%! duration ('36:15:00')
%! duration ('06:15', 'InputFormat', 'mm:ss')
%!demo
%! ## The `'Format'` option controls display: a digital timer (`hh:mm:ss`,
%! ## `dd:hh:mm:ss`, `mm:ss`, ...) or a single number in one unit (`y`, `d`, `h`,
%! ## `m`, `s`). Here the SAME duration shown six ways:
%!
%! duration (30, 15, 0, 'Format', 'hh:mm:ss')
%! duration (30, 15, 0, 'Format', 'dd:hh:mm:ss')
%! duration (30, 15, 0, 'Format', 'h')
%! duration (30, 15, 0, 'Format', 'm')
%! duration (30, 15, 0, 'Format', 's')
%! duration (30, 15, 0, 'Format', 'd')
%!demo
%! ## A numeric matrix builds a column of durations, one per row — columns are
%! ## hours, minutes and seconds.
%!
%! duration ([1, 30, 0; 0, 45, 30])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.eq 0000664 0000000 0000000 00000000365 15227665741 0022321 0 ustar 00root root 0000000 0000000 %!demo
%! ## `eq` (`==`) tests durations for equality; equal spans compare equal even when
%! ## built from different units.
%!
%! hours (1) == minutes (60)
%!
%! ## Element-wise against a scalar duration.
%! minutes ([30, 60, 90]) == hours (1)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.floor 0000664 0000000 0000000 00000000174 15227665741 0023033 0 ustar 00root root 0000000 0000000 %!demo
%! ## `floor` rounds a duration down to a whole unit (default: seconds).
%!
%! d = hours (2.9)
%! floor (d, 'hours')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.hms 0000664 0000000 0000000 00000000271 15227665741 0022477 0 ustar 00root root 0000000 0000000 %!demo
%! ## `hms` splits each duration into its hours, minutes and seconds as three
%! ## separate numeric outputs.
%!
%! d = duration (1, 30, 45)
%! [h, m, s] = hms (d);
%! [h, m, s]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.hours 0000664 0000000 0000000 00000000401 15227665741 0023043 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` *method*, `hours` returns the duration expressed as a number
%! ## of hours — the inverse of the `hours` builder. A single duration can be read
%! ## out in any unit this way.
%!
%! d = hours (30) + minutes (15)
%! hours (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.interp1 0000664 0000000 0000000 00000000356 15227665741 0023276 0 ustar 00root root 0000000 0000000 %!demo
%! ## `interp1` interpolates duration-valued data at new sample points — useful for
%! ## resampling a time series measured in durations.
%!
%! t = hours ([0, 1, 2]);
%! v = minutes ([10, 20, 40]);
%! interp1 (t, v, hours (0.5))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.intersect 0000664 0000000 0000000 00000000216 15227665741 0023707 0 ustar 00root root 0000000 0000000 %!demo
%! ## `intersect` returns the durations common to two arrays.
%!
%! A = hours ([1, 2, 3])
%! B = hours ([2, 3, 4])
%! intersect (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.iqr 0000664 0000000 0000000 00000000261 15227665741 0022502 0 ustar 00root root 0000000 0000000 %!demo
%! ## `iqr` returns the interquartile range (the 75th minus the 25th percentile) —
%! ## a robust measure of spread.
%!
%! d = hours ([2, 4, 4, 4, 5, 7, 9])
%! iqr (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.isbetween 0000664 0000000 0000000 00000000306 15227665741 0023674 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isbetween` tests, element by element, whether each duration lies within the
%! ## closed interval `[lower, upper]`.
%!
%! d = hours ([1, 5, 10])
%! isbetween (d, hours (2), hours (8))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.isfinite 0000664 0000000 0000000 00000000201 15227665741 0023513 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isfinite` flags the elements that are neither infinite nor NaN.
%!
%! d = hours ([1, Inf, NaN, 4])
%! isfinite (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.isinf 0000664 0000000 0000000 00000000171 15227665741 0023017 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isinf` flags infinite durations (from an infinite input value).
%!
%! d = hours ([1, Inf, 3])
%! isinf (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.ismember 0000664 0000000 0000000 00000000247 15227665741 0023516 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ismember` tests, element by element, whether each duration appears in a
%! ## second set.
%!
%! d = hours ([1, 2, 5])
%! ismember (d, hours ([2, 3, 5]))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.ismissing 0000664 0000000 0000000 00000000326 15227665741 0023716 0 ustar 00root root 0000000 0000000 %!demo
%! ## For a duration `ismissing` is the same test as `isnan`: a NaN duration is the
%! ## missing value, so durations plug into the generic missing-data tools.
%!
%! d = hours ([1, NaN, 3])
%! ismissing (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.isnan 0000664 0000000 0000000 00000000160 15227665741 0023015 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isnan` flags the elements whose value is Not-a-Number.
%!
%! d = hours ([1, NaN, 3])
%! isnan (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.issorted 0000664 0000000 0000000 00000000235 15227665741 0023544 0 ustar 00root root 0000000 0000000 %!demo
%! ## `issorted` checks whether the durations are already in non-decreasing order.
%!
%! issorted (hours ([1, 2, 3]))
%! issorted (hours ([2, 1, 3]))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.kurtosis 0000664 0000000 0000000 00000000313 15227665741 0023570 0 ustar 00root root 0000000 0000000 %!demo
%! ## `kurtosis` measures the "tailedness" of the duration distribution — a
%! ## dimensionless shape statistic, returned as a plain number.
%!
%! d = hours ([1, 2, 2, 2, 3, 9])
%! kurtosis (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.linspace 0000664 0000000 0000000 00000000217 15227665741 0023506 0 ustar 00root root 0000000 0000000 %!demo
%! ## `linspace` builds a fixed number of durations evenly spaced between two
%! ## endpoints.
%!
%! linspace (hours (0), hours (2), 5)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.lt 0000664 0000000 0000000 00000000267 15227665741 0022334 0 ustar 00root root 0000000 0000000 %!demo
%! ## `lt` (`<`) compares durations by length. `<`, `<=`, `>` and `>=` all work,
%! ## since durations have a natural order.
%!
%! d = minutes ([30, 60, 90])
%! d < hours (1)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.mad 0000664 0000000 0000000 00000000246 15227665741 0022453 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mad` returns the mean absolute deviation of the durations — another robust
%! ## spread statistic.
%!
%! d = hours ([2, 4, 4, 4, 5, 7, 9])
%! mad (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.mape 0000664 0000000 0000000 00000000402 15227665741 0022626 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mape` returns the mean absolute percentage error between two duration
%! ## arrays. Being a ratio it is dimensionless — a plain percentage number.
%!
%! predicted = hours ([1, 2, 4])
%! actual = hours ([1, 2, 3])
%! mape (predicted, actual)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.max 0000664 0000000 0000000 00000000323 15227665741 0022473 0 ustar 00root root 0000000 0000000 %!demo
%! ## `max` returns the longest duration in an array.
%!
%! d = minutes ([90, 30, 150, 45])
%! max (d)
%!
%! ## A second output gives its index (as for numeric `max`).
%! [longest, idx] = max (d);
%! idx
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.mean 0000664 0000000 0000000 00000000174 15227665741 0022632 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mean` averages the durations in an array, returning a duration.
%!
%! d = hours ([1, 2, 3, 4, 5])
%! mean (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.median 0000664 0000000 0000000 00000000173 15227665741 0023146 0 ustar 00root root 0000000 0000000 %!demo
%! ## `median` returns the middle duration of an array by value.
%!
%! d = minutes ([10, 20, 30, 90])
%! median (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.milliseconds 0000664 0000000 0000000 00000000226 15227665741 0024375 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` method, `milliseconds` returns the duration expressed in
%! ## milliseconds.
%!
%! d = seconds (2.5)
%! milliseconds (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.min 0000664 0000000 0000000 00000000157 15227665741 0022476 0 ustar 00root root 0000000 0000000 %!demo
%! ## `min` returns the shortest duration in an array.
%!
%! d = minutes ([90, 30, 150, 45])
%! min (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.minus 0000664 0000000 0000000 00000000150 15227665741 0023037 0 ustar 00root root 0000000 0000000 %!demo
%! ## `minus` (`-`) subtracts one duration from another.
%!
%! a = hours (3)
%! a - minutes (45)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.minutes 0000664 0000000 0000000 00000000230 15227665741 0023367 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` method, `minutes` returns the whole duration expressed in
%! ## minutes.
%!
%! d = hours (1) + minutes (30)
%! minutes (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.mode 0000664 0000000 0000000 00000000162 15227665741 0022633 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mode` returns the most frequent duration in an array.
%!
%! d = hours ([1, 2, 2, 3, 2])
%! mode (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.plus 0000664 0000000 0000000 00000000175 15227665741 0022676 0 ustar 00root root 0000000 0000000 %!demo
%! ## `plus` (`+`) adds durations together, giving a duration.
%!
%! a = hours (2) + minutes (30)
%! a + seconds (45)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.prctile 0000664 0000000 0000000 00000000226 15227665741 0023352 0 ustar 00root root 0000000 0000000 %!demo
%! ## `prctile` returns the requested percentiles of a duration array.
%!
%! d = hours ([1, 2, 3, 4, 5, 6, 7, 8])
%! prctile (d, [25, 50, 75])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.quantile 0000664 0000000 0000000 00000000232 15227665741 0023527 0 ustar 00root root 0000000 0000000 %!demo
%! ## `quantile` is the same idea as `prctile` but on a 0–1 scale.
%!
%! d = hours ([1, 2, 3, 4, 5, 6, 7, 8])
%! quantile (d, [0.25, 0.5, 0.75])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.range 0000664 0000000 0000000 00000000174 15227665741 0023006 0 ustar 00root root 0000000 0000000 %!demo
%! ## `range` returns the span from shortest to longest — `max - min`.
%!
%! d = hours ([2, 5, 3, 9])
%! range (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.rdivide 0000664 0000000 0000000 00000000314 15227665741 0023334 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rdivide` (`./`) divides a duration by a number to scale it down.
%!
%! hours (3) ./ 2
%!
%! ## Dividing one duration by another gives their dimensionless ratio.
%! hours (3) ./ minutes (30)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.rmse 0000664 0000000 0000000 00000000352 15227665741 0022656 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rmse` returns the root-mean-square error between two duration arrays — a
%! ## duration measuring their typical difference.
%!
%! predicted = hours ([1, 2, 3])
%! actual = hours ([1, 2, 5])
%! rmse (predicted, actual)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.round 0000664 0000000 0000000 00000000377 15227665741 0023046 0 ustar 00root root 0000000 0000000 %!demo
%! ## `round` rounds a duration. With no unit it rounds to the nearest second;
%! ## pass a unit to round to whole hours, minutes, and so on.
%!
%! d = hours (2.4)
%! round (d, 'hours')
%!
%! ## Default (nearest second):
%! round (seconds (90.7))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.seconds 0000664 0000000 0000000 00000000216 15227665741 0023345 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` method, `seconds` returns the duration expressed in seconds.
%!
%! d = minutes (2) + seconds (30)
%! seconds (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.setdiff 0000664 0000000 0000000 00000000233 15227665741 0023332 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setdiff` returns the durations in the first array but not the second.
%!
%! A = hours ([1, 2, 3])
%! B = hours ([2, 3, 4])
%! setdiff (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.setxor 0000664 0000000 0000000 00000000241 15227665741 0023231 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setxor` returns the symmetric difference — durations in exactly one array.
%!
%! A = hours ([1, 2, 3])
%! B = hours ([2, 3, 4])
%! setxor (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.sign 0000664 0000000 0000000 00000000173 15227665741 0022651 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sign` returns -1, 0 or 1 for negative, zero and positive durations.
%!
%! d = hours ([-2, 0, 3])
%! sign (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.skewness 0000664 0000000 0000000 00000000332 15227665741 0023550 0 ustar 00root root 0000000 0000000 %!demo
%! ## `skewness` measures the asymmetry of the duration distribution. Being a
%! ## shape statistic it is dimensionless, so it comes back as a plain number.
%!
%! d = hours ([1, 1, 1, 2, 3, 8])
%! skewness (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.sort 0000664 0000000 0000000 00000000165 15227665741 0022701 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sort` orders the durations from shortest to longest.
%!
%! d = minutes ([180, 30, 90, 45])
%! sort (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.std 0000664 0000000 0000000 00000000204 15227665741 0022476 0 ustar 00root root 0000000 0000000 %!demo
%! ## `std` returns the standard deviation of the durations, itself a duration.
%!
%! d = hours ([1, 2, 3, 4, 5])
%! std (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.sum 0000664 0000000 0000000 00000000140 15227665741 0022507 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sum` adds up the durations in an array.
%!
%! d = hours ([1, 2, 3, 4])
%! sum (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.times 0000664 0000000 0000000 00000000276 15227665741 0023036 0 ustar 00root root 0000000 0000000 %!demo
%! ## `times` (`.*`) scales a duration by a numeric factor.
%!
%! hours (1.5) * 4
%!
%! ## Element-wise scaling by an array yields an array of durations.
%! minutes (30) .* [1, 2, 3]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.union 0000664 0000000 0000000 00000000222 15227665741 0023034 0 ustar 00root root 0000000 0000000 %!demo
%! ## `union` returns the distinct durations present in either array.
%!
%! A = hours ([1, 2, 3])
%! B = hours ([2, 3, 4])
%! union (A, B)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.unique 0000664 0000000 0000000 00000000213 15227665741 0023212 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unique` returns the distinct durations in an array (equal spans count once).
%!
%! d = hours ([2, 1, 2, 3, 1])
%! unique (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.vertcat 0000664 0000000 0000000 00000000276 15227665741 0023365 0 ustar 00root root 0000000 0000000 %!demo
%! ## Durations concatenate like ordinary arrays; `[a; b]` stacks them into one
%! ## column, converting units as needed.
%!
%! a = hours ([1; 2])
%! b = minutes ([90; 30])
%! [a; b]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/duration.years 0000664 0000000 0000000 00000000240 15227665741 0023027 0 ustar 00root root 0000000 0000000 %!demo
%! ## As a `duration` method, `years` returns the duration expressed in
%! ## fixed-length years (365.2425 days).
%!
%! d = days (365.2425)
%! years (d)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.append 0000664 0000000 0000000 00000000323 15227665741 0022636 0 ustar 00root root 0000000 0000000 %!demo
%! ## `append` joins its arguments end to end, element-wise — like `strcat`, but it
%! ## keeps trailing whitespace.
%!
%! first = string ({'Ann'; 'Bob'})
%! append (first, ' ', string ({'Lee'; 'Ng'}))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.cell 0000664 0000000 0000000 00000000204 15227665741 0022304 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cell` also returns a cell array of character vectors (like `cellstr`).
%!
%! s = string ({'a'; 'b'; 'c'})
%! cell (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.cellstr 0000664 0000000 0000000 00000000307 15227665741 0023041 0 ustar 00root root 0000000 0000000 %!demo
%! ## `cellstr` converts a string array into a cell array of character vectors —
%! ## the inverse of building a string from a cellstr.
%!
%! s = string ({'apple'; 'banana'})
%! cellstr (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.char 0000664 0000000 0000000 00000000271 15227665741 0022306 0 ustar 00root root 0000000 0000000 %!demo
%! ## `char` converts a string array to a plain character matrix, one row per
%! ## element (shorter rows padded with spaces).
%!
%! s = string ({'small'; 'medium'})
%! char (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.compose 0000664 0000000 0000000 00000000370 15227665741 0023036 0 ustar 00root root 0000000 0000000 %!demo
%! ## `compose` applies a `printf`-style format to data, returning a string array —
%! ## one element per row of the data. (The format itself is given as a string.)
%!
%! compose (string ('%s scored %d'), string ({'Ann'; 'Bob'}), [7; 9])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.contains 0000664 0000000 0000000 00000000255 15227665741 0023211 0 ustar 00root root 0000000 0000000 %!demo
%! ## `contains` tests, element-wise, whether each string contains a substring.
%!
%! files = string ({'cat.txt'; 'dog.csv'; 'fish.txt'})
%! contains (files, '.txt')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.count 0000664 0000000 0000000 00000000210 15227665741 0022512 0 ustar 00root root 0000000 0000000 %!demo
%! ## `count` returns how many times a substring occurs in each string.
%!
%! s = string ({'banana'; 'apple'})
%! count (s, 'a')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.double 0000664 0000000 0000000 00000000243 15227665741 0022642 0 ustar 00root root 0000000 0000000 %!demo
%! ## `double` parses numeric text back into numbers; entries that are not numbers
%! ## become `NaN`.
%!
%! s = string ({'3.14'; '42'; 'x'})
%! double (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.endsWith 0000664 0000000 0000000 00000000242 15227665741 0023154 0 ustar 00root root 0000000 0000000 %!demo
%! ## `endsWith` tests whether each string ends with a given suffix.
%!
%! files = string ({'cat.txt'; 'dog.csv'; 'fish.txt'})
%! endsWith (files, '.csv')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.eq 0000664 0000000 0000000 00000000203 15227665741 0021771 0 ustar 00root root 0000000 0000000 %!demo
%! ## `eq` (`==`) compares strings for equality, element by element.
%!
%! a = string ({'cat'; 'dog'; 'cat'})
%! a == 'cat'
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.erase 0000664 0000000 0000000 00000000226 15227665741 0022470 0 ustar 00root root 0000000 0000000 %!demo
%! ## `erase` deletes every occurrence of a substring from each string.
%!
%! files = string ({'cat.txt'; 'dog.txt'})
%! erase (files, '.txt')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.eraseBetween 0000664 0000000 0000000 00000000274 15227665741 0024005 0 ustar 00root root 0000000 0000000 %!demo
%! ## `eraseBetween` deletes the text between two delimiters, keeping the
%! ## delimiters themselves.
%!
%! s = string ({'ab'; 'xy'})
%! eraseBetween (s, '<', '>')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.extract 0000664 0000000 0000000 00000000266 15227665741 0023047 0 ustar 00root root 0000000 0000000 %!demo
%! ## `extract` pulls out every occurrence of a pattern, returning the matched
%! ## pieces as a string array.
%!
%! s = string ('cat dog cat bird cat')
%! extract (s, 'cat')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.extractAfter 0000664 0000000 0000000 00000000344 15227665741 0024026 0 ustar 00root root 0000000 0000000 %!demo
%! ## `extractAfter` returns the part of each string after the first occurrence of
%! ## a substring — for example the extension after the dot.
%!
%! files = string ({'cat.txt'; 'dog.csv'})
%! extractAfter (files, '.')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.extractBefore 0000664 0000000 0000000 00000000363 15227665741 0024170 0 ustar 00root root 0000000 0000000 %!demo
%! ## `extractBefore` returns the part of each string before the first occurrence
%! ## of a substring — for example a file's base name before its extension.
%!
%! files = string ({'cat.txt'; 'dog.csv'})
%! extractBefore (files, '.')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.extractBetween 0000664 0000000 0000000 00000000225 15227665741 0024354 0 ustar 00root root 0000000 0000000 %!demo
%! ## `extractBetween` returns the text lying between two delimiters.
%!
%! s = string ({'[abc]'; '[hello]'})
%! extractBetween (s, '[', ']')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.insertAfter 0000664 0000000 0000000 00000000243 15227665741 0023656 0 ustar 00root root 0000000 0000000 %!demo
%! ## `insertAfter` inserts text right after each occurrence of a substring.
%!
%! s = string ({'hello world'; 'good day'})
%! insertAfter (s, ' ', 'big ')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.insertBefore 0000664 0000000 0000000 00000000350 15227665741 0024016 0 ustar 00root root 0000000 0000000 %!demo
%! ## `insertBefore` inserts text right before each occurrence of a substring —
%! ## for example a suffix just before a file extension.
%!
%! files = string ({'cat.txt'; 'dog.txt'})
%! insertBefore (files, '.txt', '_bak')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.ismember 0000664 0000000 0000000 00000000277 15227665741 0023202 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ismember` tests, element by element, whether each string appears in a second
%! ## set.
%!
%! s = string ({'apple'; 'kiwi'; 'pear'})
%! ismember (s, string ({'apple'; 'pear'}))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.ismissing 0000664 0000000 0000000 00000000335 15227665741 0023377 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ismissing` flags the `` elements — the string form of missing data,
%! ## distinct from an empty string `""`.
%!
%! s = string ({'a'; 'b'; 'c'});
%! s(2) = string (missing);
%! s
%! ismissing (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.issorted 0000664 0000000 0000000 00000000247 15227665741 0023230 0 ustar 00root root 0000000 0000000 %!demo
%! ## `issorted` checks whether the strings are already in alphabetical order.
%!
%! issorted (string ({'a'; 'b'; 'c'}))
%! issorted (string ({'b'; 'a'; 'c'}))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.isstring 0000664 0000000 0000000 00000000367 15227665741 0023241 0 ustar 00root root 0000000 0000000 %!demo
%! ## `isstring` returns true only for string arrays — the reliable way to tell a
%! ## string from a character vector, which (see `string`) look alike in source.
%!
%! isstring (string ('text'))
%! isstring ('text')
%! isstring ("text")
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.join 0000664 0000000 0000000 00000000273 15227665741 0022332 0 ustar 00root root 0000000 0000000 %!demo
%! ## `join` combines the elements of a string array into a single string, placing
%! ## a delimiter between them.
%!
%! parts = string ({'2024', '01', '15'})
%! join (parts, '-')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.lower 0000664 0000000 0000000 00000000154 15227665741 0022521 0 ustar 00root root 0000000 0000000 %!demo
%! ## `lower` converts each string to lower case.
%!
%! s = string ({'Hello'; 'WORLD'})
%! lower (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.matches 0000664 0000000 0000000 00000000331 15227665741 0023012 0 ustar 00root root 0000000 0000000 %!demo
%! ## `matches` tests, element-wise, whether each string equals a pattern *exactly*
%! ## (contrast `contains`, which tests for a substring).
%!
%! s = string ({'cat'; 'category'; 'cat'})
%! matches (s, 'cat')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.pad 0000664 0000000 0000000 00000000246 15227665741 0022137 0 ustar 00root root 0000000 0000000 %!demo
%! ## `pad` pads each string with spaces to a common width — handy for aligning
%! ## text into columns.
%!
%! s = string ({'a'; 'bb'; 'ccc'})
%! pad (s, 5)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.plus 0000664 0000000 0000000 00000000374 15227665741 0022360 0 ustar 00root root 0000000 0000000 %!demo
%! ## `plus` (`+`) concatenates two strings — a compact alternative to `append`.
%! ## Both operands must be strings (a bare `'-'` is a char, so wrap it).
%!
%! a = string ({'Ann'; 'Bob'})
%! b = string ({'Lee'; 'Ng'})
%! a + string (' ') + b
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.replace 0000664 0000000 0000000 00000000241 15227665741 0023001 0 ustar 00root root 0000000 0000000 %!demo
%! ## `replace` substitutes every occurrence of a substring with another.
%!
%! files = string ({'cat.txt'; 'dog.txt'})
%! replace (files, '.txt', '.md')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.replaceBetween 0000664 0000000 0000000 00000000234 15227665741 0024315 0 ustar 00root root 0000000 0000000 %!demo
%! ## `replaceBetween` substitutes the text lying between two delimiters.
%!
%! s = string ({'ab'; 'cd'})
%! replaceBetween (s, '<', '>', 'Z')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.reverse 0000664 0000000 0000000 00000000170 15227665741 0023042 0 ustar 00root root 0000000 0000000 %!demo
%! ## `reverse` reverses the characters within each string.
%!
%! s = string ({'Hello'; 'World'})
%! reverse (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.sort 0000664 0000000 0000000 00000000171 15227665741 0022357 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sort` orders the strings alphabetically.
%!
%! s = string ({'pear'; 'apple'; 'fig'; 'banana'})
%! sort (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.split 0000664 0000000 0000000 00000000232 15227665741 0022521 0 ustar 00root root 0000000 0000000 %!demo
%! ## `split` breaks a string at each occurrence of a delimiter — the inverse of
%! ## `join`.
%!
%! s = string ('2024-01-15')
%! split (s, '-')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.splitlines 0000664 0000000 0000000 00000000253 15227665741 0023557 0 ustar 00root root 0000000 0000000 %!demo
%! ## `splitlines` breaks a string at its newline characters into one element per
%! ## line.
%!
%! s = string (sprintf ('first\nsecond\nthird'))
%! splitlines (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.startsWith 0000664 0000000 0000000 00000000240 15227665741 0023541 0 ustar 00root root 0000000 0000000 %!demo
%! ## `startsWith` tests whether each string begins with a given prefix.
%!
%! files = string ({'img_1'; 'img_2'; 'doc_1'})
%! startsWith (files, 'img')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.strcat 0000664 0000000 0000000 00000000231 15227665741 0022665 0 ustar 00root root 0000000 0000000 %!demo
%! ## `strcat` concatenates strings horizontally, element-wise across its inputs.
%!
%! name = string ({'Ann'; 'Bob'})
%! strcat (name, ' Smith')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.strcmp 0000664 0000000 0000000 00000000314 15227665741 0022677 0 ustar 00root root 0000000 0000000 %!demo
%! ## `strcmp` compares strings for exact equality — the same idea as `==`, kept
%! ## for compatibility with the classic string functions.
%!
%! a = string ({'cat'; 'dog'})
%! strcmp (a, 'cat')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.string 0000664 0000000 0000000 00000002064 15227665741 0022701 0 ustar 00root root 0000000 0000000 %!demo
%! ## A `string` is MATLAB's string-array type. There is a crucial Octave
%! ## difference to keep in mind: in core Octave BOTH `'text'` and `"text"` produce
%! ## ordinary **character vectors** (class `char`) — unlike MATLAB, the double
%! ## quote does *not* make a string. Only the `string` constructor produces a
%! ## string array.
%!
%! class ('text') % single quotes -> char
%! class ("text") % double quotes -> ALSO char in Octave
%! class (string ('text')) % the constructor -> string
%!demo
%! ## Build a string array from a cell array of character vectors — one element
%! ## per cell. A string array prints its elements in double quotes.
%!
%! string ({'apple'; 'banana'; 'cherry'})
%!demo
%! ## Numbers convert to their text form.
%!
%! string ([3.14, 42, -1])
%!demo
%! ## The special `` value is the string counterpart of `NaN`, and is
%! ## distinct from an empty string `""`. Assign `string (missing)` to introduce
%! ## one.
%!
%! s = string ({'a'; 'b'; 'c'})
%! s(2) = string (missing)
%! ismissing (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.strip 0000664 0000000 0000000 00000000206 15227665741 0022530 0 ustar 00root root 0000000 0000000 %!demo
%! ## `strip` removes leading and trailing whitespace from each string.
%!
%! s = string ({' spaced '; 'tidy'})
%! strip (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.strlength 0000664 0000000 0000000 00000000320 15227665741 0023376 0 ustar 00root root 0000000 0000000 %!demo
%! ## `strlength` returns the number of characters in each string (contrast
%! ## `length`/`numel`, which count the array's elements).
%!
%! s = string ({'a'; 'four'; 'twelve chars'})
%! strlength (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.unique 0000664 0000000 0000000 00000000203 15227665741 0022672 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unique` returns the distinct strings in an array, sorted.
%!
%! s = string ({'b'; 'a'; 'b'; 'c'; 'a'})
%! unique (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.upper 0000664 0000000 0000000 00000000154 15227665741 0022524 0 ustar 00root root 0000000 0000000 %!demo
%! ## `upper` converts each string to upper case.
%!
%! s = string ({'Hello'; 'World'})
%! upper (s)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/string.vertcat 0000664 0000000 0000000 00000000302 15227665741 0023034 0 ustar 00root root 0000000 0000000 %!demo
%! ## String arrays concatenate like ordinary arrays; `[a; b]` stacks them into a
%! ## single column.
%!
%! a = string ({'apple'; 'banana'})
%! b = string ({'cherry'; 'date'})
%! [a; b]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.DimensionNames 0000664 0000000 0000000 00000001624 15227665741 0024066 0 ustar 00root root 0000000 0000000 %!demo
%! ## Create a table and display its dimension names. You can access row
%! ## names and data using dimension names with dot syntax.
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'; 'Diaz'; 'Brown'};
%! Age = [38;43;38;40;49];
%! Smoker = logical ([1; 0; 1; 0; 1]);
%! Height = [71; 69; 64; 67; 64];
%! Weight = [176; 163; 131; 133; 119];
%! BloodPressure = [124, 93; 109, 77; 125, 83; 117, 75; 122, 80];
%! T = table (Age, Smoker, Height, Weight, BloodPressure, 'RowNames', LastName)
%! T.Properties.DimensionNames
%!
%! ## Access the row names using the first dimension name.
%! T.Row
%!
%! ## Access the data using the second dimension name.
%! T.Variables
%!
%! ## Modify the names of its dimensions using the Properties
%! T.Properties.DimensionNames = {'Patient', 'Data'};
%! T.Properties
%!
%! ## Change a single dimension name
%! T.Properties.DimensionNames(1) = 'Patients'
%! T.Properties
%! T.Patients
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.RowNames 0000664 0000000 0000000 00000002070 15227665741 0022704 0 ustar 00root root 0000000 0000000 %!demo
%! ## Access rows by selecting row names
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
%! Age = [38;43;38;40;49];
%! Height = [71;69;64;67;64];
%! Weight = [176;163;131;133;119];
%! T = table (Age, Weight, Height, 'RowNames', LastName)
%! T('Lee',:)
%! T{'Lee',:}
%! T({'Lee', 'Diaz'},:)
%! T{{'Lee', 'Diaz'},:}
%!demo
%! ## Set row names by assigning a new variable
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
%! Age = [38;43;38;40;49];
%! Height = [71;69;64;67;64];
%! Weight = [176;163;131;133;119];
%! T = table (Age, Weight, Height)
%! T.Properties.RowNames = LastName
%!demo
%! ## Set row names by assigning an existing variable
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
%! Age = [38;43;38;40;49];
%! Height = [71;69;64;67;64];
%! Weight = [176;163;131;133;119];
%! T = table (Age, Weight, Height, LastName)
%!
%! ## In this case the variable persists in the table
%! T.Properties.RowNames = T.LastName
%!
%! ## In this case the variable is removed from the table
%! T.Properties.RowNames = 'LastName'
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.VariableNames 0000664 0000000 0000000 00000001210 15227665741 0023655 0 ustar 00root root 0000000 0000000 %!demo
%! ## Store patient data in a table
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'; 'Diaz'; 'Brown'};
%! Age = [38;43;38;40;49];
%! Smoker = logical ([1; 0; 1; 0; 1]);
%! Height = [71; 69; 64; 67; 64];
%! Weight = [176; 163; 131; 133; 119];
%! BloodPressure = [124, 93; 109, 77; 125, 83; 117, 75; 122, 80];
%! T = table (LastName, Age, Smoker, Height, Weight, BloodPressure)
%!
%! ## Use indexing to access variables
%! meanHeight = mean (T.Height)
%!
%! ## Calculate body mass index (BMI), and add it as a new table variable.
%! pounds2kg = 0.4535924;
%! inch2meter = 0.0254;
%! T.BMI = (T.Weight * pounds2kg) ./ (T.Height * inch2meter) .^ 2
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.addprop 0000664 0000000 0000000 00000002125 15227665741 0022603 0 ustar 00root root 0000000 0000000 %!demo
%! ## `addprop` attaches your own metadata to a table. Each property is declared
%! ## with a *scope*: a `'table'`-scoped property holds a single value for the whole
%! ## table, while a `'variable'`-scoped property holds one value per variable,
%! ## aligned with the table's columns.
%!
%! Age = [38; 43; 40];
%! Height = duration (0, 0, 0) + hours ([1.9; 1.8; 1.7]);
%! Gender = categorical ({'M'; 'F'; 'M'});
%! T = table (Age, Height, Gender)
%! T = addprop (T, {'DataSource', 'Instrument'}, {'table', 'variable'});
%!
%! ## The table-scoped `DataSource` takes one value; the variable-scoped
%! ## `Instrument` takes a cell with one entry per variable (Age, Height, Gender).
%! T.Properties.CustomProperties.DataSource = 'Clinic A';
%! T.Properties.CustomProperties.Instrument = {'form', 'stadiometer', 'form'};
%! T.Properties.CustomProperties
%!
%! ## Because it is variable-scoped, `Instrument` follows column operations — after
%! ## removing `Height` its entry drops out too, staying aligned with the columns.
%! T2 = removevars (T, 'Height');
%! T2.Properties.CustomProperties.Instrument
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.addvars 0000664 0000000 0000000 00000001204 15227665741 0022573 0 ustar 00root root 0000000 0000000 %!demo
%! ## `addvars` inserts one or more variables into a table. Appended at the end by
%! ## default, the new columns can be named with `'NewVariableNames'` and may be of
%! ## any type — here a `datetime` is added to a table of mixed variables.
%!
%! Name = string ({'Sanchez'; 'Johnson'; 'Li'});
%! Age = [38; 43; 40];
%! Gender = categorical ({'M'; 'M'; 'F'});
%! T = table (Name, Age, Gender)
%! Visit = datetime (2024, [1; 2; 3], [5; 6; 7]);
%! addvars (T, Visit)
%!
%! ## Use `'Before'` or `'After'` to place the new variable at a chosen position.
%! addvars (T, logical ([1; 0; 1]), 'After', 'Age', 'NewVariableNames', {'Smoker'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.anymissing 0000664 0000000 0000000 00000001016 15227665741 0023331 0 ustar 00root root 0000000 0000000 %!demo
%! ## `anymissing` is a fast scalar check: `true` as soon as *any* element of the
%! ## table is missing, across every variable and type — `NaN` for numeric,
%! ## `NaT` for datetime, `` for string, `` for categorical.
%!
%! Name = string ({'Li'; 'Diaz'; 'Brown'});
%! Age = [38; 43; 40];
%! Grade = categorical ({'A'; ''; 'B'});
%! T = table (Name, Age, Grade)
%! anymissing (T)
%!
%! ## A table with no gaps of any kind returns `false`.
%! anymissing (table (string ({'Li'; 'Diaz'}), [38; 40]))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.convertvars 0000664 0000000 0000000 00000001022 15227665741 0023521 0 ustar 00root root 0000000 0000000 %!demo
%! ## `convertvars` changes the data type of selected variables, leaving the rest
%! ## alone. The target type is given as a name, or as a conversion function.
%!
%! T = table ([1; 0; 1], [38; 43; 40], 'VariableNames', {'Smoker', 'Age'})
%! convertvars (T, 'Smoker', 'logical')
%!
%! ## Select several variables at once and hand them a conversion function.
%! T2 = table ({'M'; 'F'; 'M'}, {'NY'; 'CA'; 'MA'}, ...
%! 'VariableNames', {'Gender', 'State'})
%! convertvars (T2, {'Gender', 'State'}, 'categorical')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.fillmissing 0000664 0000000 0000000 00000001317 15227665741 0023474 0 ustar 00root root 0000000 0000000 %!demo
%! ## `fillmissing` replaces gaps rather than dropping rows. Fill with a constant,
%! ## applied across the (numeric) variables.
%!
%! T = table ([38; NaN; 40], [71; 69; NaN], 'VariableNames', {'Age', 'Height'})
%! fillmissing (T, 'constant', 0)
%!demo
%! ## Interpolation rules fill from neighbouring rows and work across types —
%! ## `'previous'` carries the last value forward (here through both a `datetime`
%! ## and a numeric column), while `'linear'` interpolates numeric gaps.
%!
%! Date = datetime (2024, 1, [1; NaN; 3; NaN]);
%! Reading = [10; NaN; 30; 40];
%! T = table (Date, Reading)
%! fillmissing (T, 'previous')
%!
%! fillmissing (table ([1; NaN; NaN; 4], 'VariableNames', {'v'}), 'linear')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.findgroups 0000664 0000000 0000000 00000001125 15227665741 0023331 0 ustar 00root root 0000000 0000000 %!demo
%! ## `findgroups` assigns each row an integer group number based on its grouping
%! ## variable(s) — the setup step for a `splitapply` computation. A second output
%! ## returns a table naming each group.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! Petal = [1.4; 5.1; 1.5; 5.9; 1.3];
%! T = table (Species, Petal)
%! [G, groupNames] = findgroups (T(:, 'Species'));
%! G'
%! groupNames
%!
%! ## The group numbers index into `groupNames`, and feed straight into
%! ## `splitapply` to aggregate `Petal` per species.
%! splitapply (@mean, T(:, 'Petal'), G)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.groupcounts 0000664 0000000 0000000 00000000441 15227665741 0023541 0 ustar 00root root 0000000 0000000 %!demo
%! ## `groupcounts` tallies how many rows fall in each group — a frequency table.
%! ## It also reports each group's share as a percentage of the total.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! T = table (Species)
%! groupcounts (T, 'Species')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.groupfilter 0000664 0000000 0000000 00000000767 15227665741 0023526 0 ustar 00root root 0000000 0000000 %!demo
%! ## `groupfilter` keeps the rows belonging to groups that satisfy a predicate —
%! ## it filters *whole groups*, not individual rows. Here only species with more
%! ## than two observations are retained.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! Petal = [1.4; 5.1; 1.5; 5.9; 1.3];
%! T = table (Species, Petal)
%! groupfilter (T, 'Species', @(x) numel (x) > 2)
%!
%! ## `setosa` has three rows and stays; `virginica` has two and is dropped
%! ## entirely.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.groupsummary 0000664 0000000 0000000 00000001011 15227665741 0023715 0 ustar 00root root 0000000 0000000 %!demo
%! ## `groupsummary` is the one-call grouped aggregation: group by one or more
%! ## variables, then apply a summary method to the data variables. It reports the
%! ## group count alongside each requested statistic.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! Petal = [1.4; 5.1; 1.5; 5.9; 1.3];
%! T = table (Species, Petal)
%! groupsummary (T, 'Species', 'mean', 'Petal')
%!
%! ## Several methods can be requested at once.
%! groupsummary (T, 'Species', {'min', 'max'}, 'Petal')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.grouptransform 0000664 0000000 0000000 00000000672 15227665741 0024247 0 ustar 00root root 0000000 0000000 %!demo
%! ## `grouptransform` applies a group-wise transform but returns a table of the
%! ## *same height* as the input — each value replaced by its transformed version.
%! ## Here every petal length is centred on its own species mean.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! Petal = [1.4; 5.1; 1.5; 5.9; 1.3];
%! T = table (Species, Petal)
%! grouptransform (T, 'Species', @(x) x - mean (x), 'Petal')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.head 0000664 0000000 0000000 00000001054 15227665741 0022053 0 ustar 00root root 0000000 0000000 %!demo
%! ## `head` previews the top of a table without you having to know its size.
%! ## With no count it returns the first 8 rows (or fewer if the table is short) —
%! ## handy for glancing at a wide, mixed-type table.
%!
%! n = (1:20)';
%! T = table (string (num2str (n, 'ID%02d')), datetime (2024, 1, n), ...
%! categorical (mod (n, 3), 0:2, {'low', 'mid', 'hi'}), n .^ 2, ...
%! 'VariableNames', {'Tag', 'Date', 'Band', 'Score'});
%! head (T)
%!
%! ## Pass a count to ask for a specific number of leading rows.
%! head (T, 3)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.height 0000664 0000000 0000000 00000000715 15227665741 0022425 0 ustar 00root root 0000000 0000000 %!demo
%! ## `height` counts rows, independent of how many columns each variable spans.
%! ## Here `BloodPressure` occupies two columns, yet the table still has 5 rows.
%!
%! Age = [38; 43; 38; 40; 49];
%! BloodPressure = [124, 93; 109, 77; 125, 83; 117, 75; 122, 80];
%! T = table (Age, BloodPressure)
%! height (T)
%!
%! ## It is the row count you index against, so `height` is the natural bound
%! ## for a loop or a final-row reference.
%! T(height (T), :)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.horzcat 0000664 0000000 0000000 00000002657 15227665741 0022636 0 ustar 00root root 0000000 0000000 %!demo
%! ## `horzcat` joins tables side by side, keeping all their variables. The tables
%! ## must have the same number of rows and distinct variable names. The `[A, B]`
%! ## bracket syntax calls it for you, and variables of any type combine freely.
%!
%! A = table ([38; 43; 40], 'VariableNames', {'Age'})
%! B = table (categorical ({'M'; 'F'; 'M'}), logical ([1; 0; 1]), ...
%! 'VariableNames', {'Gender', 'Smoker'})
%! [A, B]
%!demo
%! ## Custom properties are carried through the concatenation. A *variable*-scoped
%! ## property is concatenated alongside its columns, so the merged table keeps one
%! ## entry per variable; a *table*-scoped property is preserved when the operands
%! ## agree on it.
%!
%! A = table ([38; 43], categorical ({'M'; 'F'}), 'VariableNames', {'Age', 'Gender'})
%! A = addprop (A, {'Study', 'Source'}, {'table', 'variable'});
%! A.Properties.CustomProperties.Study = 'Cohort-7';
%! A.Properties.CustomProperties.Source = {'intake', 'intake'};
%!
%! B = table (duration (0, [15; 30], 0), 'VariableNames', {'Wait'})
%! B = addprop (B, {'Study', 'Source'}, {'table', 'variable'});
%! B.Properties.CustomProperties.Study = 'Cohort-7';
%! B.Properties.CustomProperties.Source = {'clock'};
%!
%! H = [A, B];
%! ## The variable-scoped Source now spans all three variables ...
%! H.Properties.CustomProperties.Source
%! ## ... and the shared table-scoped Study is retained.
%! H.Properties.CustomProperties.Study
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.inner2outer 0000664 0000000 0000000 00000000626 15227665741 0023432 0 ustar 00root root 0000000 0000000 %!demo
%! ## `inner2outer` swaps the nesting of a table whose variables are themselves
%! ## tables: the inner (nested) variables are lifted to the top level.
%!
%! Inner = table ([1; 2; 3], [4; 5; 6], 'VariableNames', {'x', 'y'})
%! NT = table ([10; 20; 30], Inner, 'VariableNames', {'id', 'inner'})
%! NT
%!
%! ## After `inner2outer` the nested `x` and `y` become ordinary variables.
%! inner2outer (NT)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.innerjoin 0000664 0000000 0000000 00000001476 15227665741 0023155 0 ustar 00root root 0000000 0000000 %!demo
%! ## `innerjoin` keeps only rows whose key exists in *both* tables — unmatched
%! ## rows are dropped — and, unlike `join`, the right key need not be unique.
%! ## Pass `'Keys'` to match on several variables at once; here a row must agree on
%! ## both `Name` and `Year` to match.
%!
%! L = table ({'Li'; 'Li'; 'Diaz'}, [2023; 2024; 2023], [10; 11; 12], ...
%! 'VariableNames', {'Name', 'Year', 'Visits'})
%! R = table ({'Li'; 'Diaz'}, [2023; 2023], categorical ({'NY'; 'CA'}), ...
%! 'VariableNames', {'Name', 'Year', 'State'})
%! innerjoin (L, R, 'Keys', {'Name', 'Year'})
%!
%! ## Li's 2024 row has no match on the right, so it is excluded. Extra outputs
%! ## give the source row indices in the left and right tables.
%! [T, iL, iR] = innerjoin (L, R, 'Keys', {'Name', 'Year'});
%! [iL, iR]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.intersect 0000664 0000000 0000000 00000001237 15227665741 0023155 0 ustar 00root root 0000000 0000000 %!demo
%! ## `intersect` returns the rows common to both tables — the set intersection.
%! ## A row matches only when *every* variable agrees, so mixed-type rows are
%! ## compared field by field.
%!
%! A = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! categorical ({'NY'; 'CA'; 'MA'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! B = table ({'Diaz'; 'Brown'; 'Lee'}, [40; 49; 30], ...
%! categorical ({'CA'; 'MA'; 'TX'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! intersect (A, B)
%!
%! ## The extra outputs locate the shared rows within each input.
%! [C, iA, iB] = intersect (A, B);
%! [iA, iB]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.iscolumn 0000664 0000000 0000000 00000000724 15227665741 0023006 0 ustar 00root root 0000000 0000000 %!demo
%! ## A table is a *column* when it has a single variable — regardless of how
%! ## many columns that variable spans internally.
%!
%! T1 = table ([1; 2; 3], 'VariableNames', {'x'})
%! iscolumn (T1)
%!
%! ## The lone variable may itself be multi-column; the table is still a column.
%! T2 = table ([1 2; 3 4; 5 6], 'VariableNames', {'xy'})
%! iscolumn (T2)
%!
%! ## Two or more variables make it no longer a column.
%! iscolumn (table ([1; 2; 3], [4; 5; 6]))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.isempty 0000664 0000000 0000000 00000000533 15227665741 0022645 0 ustar 00root root 0000000 0000000 %!demo
%! ## A table is empty when it has no rows **or** no variables. Note that a
%! ## table with named variables but zero rows still counts as empty.
%!
%! T = table ('Size', [0, 3], 'VariableTypes', {'double', 'string', 'double'})
%! isempty (T)
%!
%! ## Adding a row makes it non-empty.
%! T(1, :) = {42, string('S1'), 3.14};
%! isempty (T)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.ismember 0000664 0000000 0000000 00000001325 15227665741 0022756 0 ustar 00root root 0000000 0000000 %!demo
%! ## `ismember` tests, row by row, whether each row of the first table also occurs
%! ## in the second — returning a logical column, not a new table. A row counts as
%! ## a member only when all of its variables match a row of `B`.
%!
%! A = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! categorical ({'NY'; 'CA'; 'MA'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! B = table ({'Diaz'; 'Brown'; 'Lee'}, [40; 49; 30], ...
%! categorical ({'CA'; 'MA'; 'TX'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! ismember (A, B)
%!
%! ## A second output gives, for each matching row, its position in `B` (0 if none).
%! [TF, loc] = ismember (A, B);
%! loc
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.ismissing 0000664 0000000 0000000 00000001066 15227665741 0023162 0 ustar 00root root 0000000 0000000 %!demo
%! ## Where `anymissing` gives a single yes/no, `ismissing` locates *every* gap,
%! ## returning a logical array the size of the table — one flag per element. It
%! ## recognises the missing value proper to each type at once.
%!
%! Name = string ({'Li'; 'Diaz'; 'Brown'});
%! Age = [38; NaN; 40];
%! Grade = categorical ({'A'; 'B'; ''});
%! Visit = datetime (2024, 1, [5; NaN; 7]);
%! T = table (Name, Age, Grade, Visit)
%! ismissing (T)
%!
%! ## Pass an indicator to also treat specific sentinel values as missing.
%! ismissing (table ([1; -99; 3]), -99)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.isrow 0000664 0000000 0000000 00000000505 15227665741 0022315 0 ustar 00root root 0000000 0000000 %!demo
%! ## A table is a *row* when it has exactly one row of data, whatever the
%! ## number of variables.
%!
%! T1 = table (38, true, 71, 'VariableNames', {'Age', 'Smoker', 'Height'})
%! isrow (T1)
%!
%! ## Add a second row and it is no longer a row vector.
%! T2 = table ([38; 43], [true; false], [71; 69])
%! isrow (T2)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.issortedrows 0000664 0000000 0000000 00000000767 15227665741 0023733 0 ustar 00root root 0000000 0000000 %!demo
%! ## `issortedrows` tests whether the rows are already in sorted order, using the
%! ## same key/direction syntax as `sortrows` — handy to skip a needless sort.
%!
%! T = table ([1; 3; 2], [10; 20; 30], 'VariableNames', {'Age', 'Height'})
%! issortedrows (T, 'Age')
%!
%! ## The `Height` column *is* ascending, so a check on that variable succeeds.
%! issortedrows (T, 'Height')
%!
%! ## Directions are checked too: this asks whether `Age` is descending.
%! issortedrows (T, 'Age', 'descend')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.isvector 0000664 0000000 0000000 00000000651 15227665741 0023012 0 ustar 00root root 0000000 0000000 %!demo
%! ## A table is a *vector* when it is a single row **or** a single variable —
%! ## the table analogue of a 1-by-N or N-by-1 array.
%!
%! ## One variable, several rows: a column, hence a vector.
%! isvector (table ([1; 2; 3]))
%!
%! ## One row, several variables: a row, hence a vector.
%! isvector (table (1, 2, 3))
%!
%! ## Multiple rows and multiple variables: not a vector.
%! isvector (table ([1; 2], [3; 4]))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.join 0000664 0000000 0000000 00000001246 15227665741 0022114 0 ustar 00root root 0000000 0000000 %!demo
%! ## `join` performs a key-based merge: every row of the left table is matched to
%! ## the one row of the right table sharing its key. The key is the variable the
%! ## two tables have in common (`Name`), and it must be *unique* on the right.
%! ## The remaining right-hand variables — here of several different types — are
%! ## appended to each matched left row.
%!
%! L = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! 'VariableNames', {'Name', 'Age'})
%! R = table ({'Li'; 'Diaz'; 'Brown'}, categorical ({'NY'; 'CA'; 'MA'}), ...
%! logical ([1; 0; 1]), ...
%! 'VariableNames', {'Name', 'State', 'Smoker'})
%! join (L, R)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.mergevars 0000664 0000000 0000000 00000000600 15227665741 0023141 0 ustar 00root root 0000000 0000000 %!demo
%! ## `mergevars` combines several variables into one multi-column variable — the
%! ## inverse of `splitvars`. Name the merged variable with `'NewVariableName'`.
%!
%! T = table ([38; 43; 40], [124; 109; 125], [93; 77; 83], ...
%! 'VariableNames', {'Age', 'Systolic', 'Diastolic'})
%! mergevars (T, {'Systolic', 'Diastolic'}, 'NewVariableName', 'BloodPressure')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.movevars 0000664 0000000 0000000 00000001024 15227665741 0023011 0 ustar 00root root 0000000 0000000 %!demo
%! ## `movevars` reorders variables, placing one (or several) `'Before'` or
%! ## `'After'` another — the data is unchanged, only the column order shifts.
%!
%! Name = string ({'Sanchez'; 'Johnson'; 'Li'});
%! Age = [38; 43; 40];
%! Gender = categorical ({'M'; 'M'; 'F'});
%! Visit = datetime (2024, [1; 2; 3], [5; 6; 7]);
%! T = table (Name, Age, Gender, Visit)
%! movevars (T, 'Visit', 'After', 'Name')
%!
%! ## Move a variable to the front by placing it before the first one.
%! movevars (T, 'Gender', 'Before', 'Name')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.numel 0000664 0000000 0000000 00000000750 15227665741 0022274 0 ustar 00root root 0000000 0000000 %!demo
%! ## For a table `numel` returns rows times variables — the number of table
%! ## *cells* — not the count of underlying data elements. This 3-by-2 table
%! ## therefore has 6 cells even though `BloodPressure` holds two columns.
%!
%! Age = [38; 43; 40];
%! Smoker = logical ([1; 0; 1]);
%! BloodPressure = [124, 93; 109, 77; 117, 75];
%! T = table (Age, Smoker, BloodPressure)
%! numel (T)
%!
%! ## It is simply the product of `height` and `width`.
%! height (T) * width (T)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.outerjoin 0000664 0000000 0000000 00000001241 15227665741 0023166 0 ustar 00root root 0000000 0000000 %!demo
%! ## `outerjoin` keeps *all* rows from both tables, filling in missing values
%! ## where a key has no match — each variable is filled with the missing value
%! ## proper to its type (`NaN`, ``, empty string, ...).
%!
%! L = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! 'VariableNames', {'Name', 'Age'})
%! R = table ({'Li'; 'Diaz'; 'Lee'}, categorical ({'NY'; 'CA'; 'TX'}), ...
%! [176; 163; 150], ...
%! 'VariableNames', {'Name', 'State', 'Weight'})
%! outerjoin (L, R, 'MergeKeys', true)
%!
%! ## Brown (left only) and Lee (right only) both survive, each with the other
%! ## table's variables left missing.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.pivot 0000664 0000000 0000000 00000001510 15227665741 0022310 0 ustar 00root root 0000000 0000000 %!demo
%! ## `pivot` builds a cross-tabulation. With only `'Rows'` it counts the rows in
%! ## each group — a one-way frequency table.
%!
%! Region = {'N'; 'N'; 'S'; 'S'; 'N'; 'S'};
%! Quarter = categorical ({'Q1'; 'Q2'; 'Q1'; 'Q2'; 'Q1'; 'Q2'});
%! Sales = [10; 20; 30; 40; 15; 25];
%! T = table (Region, Quarter, Sales)
%! pivot (T, 'Rows', 'Region')
%!demo
%! ## Add `'Columns'` to spread a second grouping variable across the columns, and
%! ## aggregate a data variable in each cell — here total `Sales` by region and
%! ## quarter.
%!
%! Region = {'N'; 'N'; 'S'; 'S'; 'N'; 'S'};
%! Quarter = categorical ({'Q1'; 'Q2'; 'Q1'; 'Q2'; 'Q1'; 'Q2'});
%! Sales = [10; 20; 30; 40; 15; 25];
%! T = table (Region, Quarter, Sales)
%! pivot (T, 'Rows', 'Region', 'Columns', 'Quarter', ...
%! 'DataVariable', 'Sales', 'Method', 'sum')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.removevars 0000664 0000000 0000000 00000000652 15227665741 0023346 0 ustar 00root root 0000000 0000000 %!demo
%! ## `removevars` drops variables, selected by name or by position index.
%!
%! Name = string ({'Sanchez'; 'Johnson'; 'Li'});
%! Age = [38; 43; 40];
%! Gender = categorical ({'M'; 'M'; 'F'});
%! Visit = datetime (2024, [1; 2; 3], [5; 6; 7]);
%! T = table (Name, Age, Gender, Visit)
%! removevars (T, 'Gender')
%!
%! ## Several variables can go at once, here selected by their column numbers.
%! removevars (T, [2, 4])
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.renamevars 0000664 0000000 0000000 00000000625 15227665741 0023320 0 ustar 00root root 0000000 0000000 %!demo
%! ## `renamevars` changes variable names in place, matching old names to new ones
%! ## position by position. It touches only the names — the data, of whatever
%! ## type, is untouched.
%!
%! Nm = string ({'Sanchez'; 'Johnson'; 'Li'});
%! Yrs = [38; 43; 40];
%! Sex = categorical ({'M'; 'M'; 'F'});
%! T = table (Nm, Yrs, Sex)
%! renamevars (T, {'Nm', 'Yrs', 'Sex'}, {'Name', 'Age', 'Gender'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.repelem 0000664 0000000 0000000 00000000671 15227665741 0022607 0 ustar 00root root 0000000 0000000 %!demo
%! ## `repelem` repeats each row in place. With a scalar count every row is
%! ## duplicated the same number of times, carrying all variable types along.
%!
%! Name = string ({'Li'; 'Diaz'; 'Brown'});
%! Grade = categorical ({'A'; 'B'; 'A'});
%! T = table (Name, Grade)
%! repelem (T, 2, 1)
%!
%! ## A vector count sets the repeat count per row — here row 1 once, row 2 twice,
%! ## row 3 three times.
%! repelem (T, [1; 2; 3], 1)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.repmat 0000664 0000000 0000000 00000000450 15227665741 0022441 0 ustar 00root root 0000000 0000000 %!demo
%! ## `repmat` tiles a whole table, repeating the full block of rows. Contrast with
%! ## `repelem`, which repeats each row in place: `repmat` copies the sequence.
%!
%! Name = string ({'Li'; 'Diaz'});
%! Visit = datetime (2024, 1, [5; 6]);
%! T = table (Name, Visit)
%! repmat (T, 3, 1)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.rmmissing 0000664 0000000 0000000 00000001131 15227665741 0023156 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rmmissing` drops every row that has a missing value in any variable —
%! ## listwise deletion — counting gaps of every type (`NaN`, `NaT`, ``,
%! ## ``). Here the rows with a missing age, grade, or visit all go.
%!
%! Name = string ({'Li'; 'Diaz'; 'Brown'; 'Lee'});
%! Age = [38; NaN; 40; 49];
%! Grade = categorical ({'A'; 'B'; ''; 'C'});
%! Visit = datetime (2024, 1, [5; 6; 7; 8]);
%! T = table (Name, Age, Grade, Visit)
%! rmmissing (T)
%!
%! ## A second output is the logical mask of the rows that were removed.
%! [C, removed] = rmmissing (T);
%! removed'
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.rmprop 0000664 0000000 0000000 00000001277 15227665741 0022500 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rmprop` removes custom properties previously added with `addprop`, whatever
%! ## their scope. Here a table starts with one property of each kind.
%!
%! Age = [38; 43];
%! Gender = categorical ({'M'; 'F'});
%! T = table (Age, Gender)
%! T = addprop (T, {'DataSource', 'Instrument'}, {'table', 'variable'});
%! T.Properties.CustomProperties.DataSource = 'Clinic A';
%! T.Properties.CustomProperties.Instrument = {'form', 'form'};
%! T.Properties.CustomProperties
%!
%! ## Remove the variable-scoped `Instrument`; the table-scoped `DataSource`
%! ## remains. The built-in properties (names, units, ...) are never affected.
%! T = rmprop (T, 'Instrument');
%! T.Properties.CustomProperties
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.rowfun 0000664 0000000 0000000 00000000510 15227665741 0022466 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rowfun` applies a function to each row, passing that row's variables as
%! ## separate arguments — a row-wise map, complementing the column-wise `varfun`.
%!
%! Weight = [176; 163; 133];
%! Height = [71; 69; 64];
%! T = table (Weight, Height)
%! rowfun (@(w, h) 703 * w / h^2, T, 'OutputVariableNames', {'BMI'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.rows2vars 0000664 0000000 0000000 00000000566 15227665741 0023131 0 ustar 00root root 0000000 0000000 %!demo
%! ## `rows2vars` transposes a table: the original variables become rows and the
%! ## original rows become variables. The old variable names move into a new
%! ## leading variable, and the row names (if any) become the new headers.
%!
%! Age = [38; 43; 40];
%! Height = [71; 69; 64];
%! T = table (Age, Height, 'RowNames', {'Li', 'Diaz', 'Brown'})
%! rows2vars (T)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.setdiff 0000664 0000000 0000000 00000001156 15227665741 0022601 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setdiff` returns the rows that are in the first table but not the second,
%! ## comparing whole multi-variable rows across all their types.
%!
%! A = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! categorical ({'NY'; 'CA'; 'MA'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! B = table ({'Diaz'; 'Brown'; 'Lee'}, [40; 49; 30], ...
%! categorical ({'CA'; 'MA'; 'TX'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! setdiff (A, B)
%!
%! ## Only Li is unique to `A`; a second output gives its row index in `A`.
%! [C, iA] = setdiff (A, B);
%! iA
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.setxor 0000664 0000000 0000000 00000001156 15227665741 0022501 0 ustar 00root root 0000000 0000000 %!demo
%! ## `setxor` returns the symmetric difference: rows in exactly one of the two
%! ## tables, but not in both. Row identity spans every variable, of any type.
%!
%! A = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! categorical ({'NY'; 'CA'; 'MA'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! B = table ({'Diaz'; 'Brown'; 'Lee'}, [40; 49; 30], ...
%! categorical ({'CA'; 'MA'; 'TX'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! setxor (A, B)
%!
%! ## Diaz and Brown, shared by both, drop out — leaving Li (from `A`) and Lee
%! ## (from `B`).
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.size 0000664 0000000 0000000 00000000744 15227665741 0022131 0 ustar 00root root 0000000 0000000 %!demo
%! ## `size` reports `[height, width]` — rows by *variables*. A variable that
%! ## spans several columns still counts as one, so the second element matches
%! ## `width`, not the total number of underlying columns.
%!
%! Age = [38; 43; 38; 40; 49];
%! BloodPressure = [124, 93; 109, 77; 125, 83; 117, 75; 122, 80];
%! T = table (Age, BloodPressure)
%! size (T)
%!
%! ## Query a single dimension, or capture both at once.
%! nRows = size (T, 1)
%! [nRows, nVars] = size (T)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.sortrows 0000664 0000000 0000000 00000001765 15227665741 0023065 0 ustar 00root root 0000000 0000000 %!demo
%! ## `sortrows` orders the rows by one or more variables of any comparable type.
%! ## Name the variables to sort by; a trailing direction (or one per key) flips
%! ## ascending to descending. Here an *ordinal* categorical `Grade` sets the
%! ## primary order, with a `datetime` breaking ties.
%!
%! Name = string ({'Li'; 'Diaz'; 'Brown'; 'Lee'});
%! Visit = datetime (2024, [3; 1; 2; 1], [7; 5; 6; 2]);
%! Grade = categorical ({'B'; 'A'; 'A'; 'B'}, {'A', 'B', 'C'}, 'Ordinal', true);
%! T = table (Name, Visit, Grade)
%! sortrows (T, {'Grade', 'Visit'})
%!
%! ## Sort the same table by `Grade` descending instead.
%! sortrows (T, 'Grade', 'descend')
%!demo
%! ## A second output returns the permutation index, and passing `'RowNames'`
%! ## sorts by the row names themselves rather than by a data variable.
%!
%! Age = [38; 43; 38; 40];
%! Smoker = logical ([1; 0; 1; 0]);
%! T = table (Age, Smoker, 'RowNames', {'Sanchez', 'Johnson', 'Li', 'Diaz'})
%! [S, idx] = sortrows (T, 'RowNames');
%! S
%! idx
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.splitapply 0000664 0000000 0000000 00000001202 15227665741 0023346 0 ustar 00root root 0000000 0000000 %!demo
%! ## `splitapply` divides a table by the group numbers from `findgroups`, applies
%! ## a function to each group, and concatenates the results. Here it computes a
%! ## mean petal length per species.
%!
%! Species = {'setosa'; 'virginica'; 'setosa'; 'virginica'; 'setosa'};
%! Petal = [1.4; 5.1; 1.5; 5.9; 1.3];
%! T = table (Species, Petal)
%! G = findgroups (T(:, 'Species'));
%! splitapply (@mean, T(:, 'Petal'), G)
%!
%! ## The applied function may return several outputs — one column each — and can
%! ## read several variables at once.
%! [lo, hi] = splitapply (@(x) deal (min (x), max (x)), T(:, 'Petal'), G);
%! [lo, hi]
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.splitvars 0000664 0000000 0000000 00000000757 15227665741 0023212 0 ustar 00root root 0000000 0000000 %!demo
%! ## `splitvars` expands a multi-column variable into several single-column
%! ## variables — the inverse of `mergevars`. Auto-generated names get a numeric
%! ## suffix; pass `'NewVariableNames'` to choose your own.
%!
%! BloodPressure = [124, 93; 109, 77; 125, 83];
%! T = table ([38; 43; 40], BloodPressure, 'VariableNames', {'Age', 'BP'})
%! splitvars (T, 'BP')
%!
%! ## Name the resulting columns explicitly.
%! splitvars (T, 'BP', 'NewVariableNames', {'Systolic', 'Diastolic'})
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.stack 0000664 0000000 0000000 00000001140 15227665741 0022253 0 ustar 00root root 0000000 0000000 %!demo
%! ## `stack` reshapes wide data to tall: it stacks several data variables into a
%! ## single variable and adds an indicator recording which one each value came
%! ## from. Here the monthly columns collapse into one `Value` column.
%!
%! Name = {'Li'; 'Diaz'};
%! Jan = [1; 2];
%! Feb = [3; 4];
%! T = table (Name, Jan, Feb)
%! stack (T, {'Jan', 'Feb'}, ...
%! 'NewDataVariableName', 'Value', 'IndexVariableName', 'Month')
%!
%! ## The unstacked variables (`Name`) are repeated down each group; the indicator
%! ## `Month` is a categorical naming the source column. `unstack` reverses this.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.standardizeMissing 0000664 0000000 0000000 00000000725 15227665741 0025020 0 ustar 00root root 0000000 0000000 %!demo
%! ## `standardizeMissing` turns your own sentinel codes into the *standard*
%! ## missing value for each type (`NaN` here), so later `ismissing`/`rmmissing`/
%! ## `fillmissing` calls recognise them. This dataset uses `-99` for "no data".
%!
%! T = table ([38; -99; 40], [71; 69; -99], 'VariableNames', {'Age', 'Height'})
%! S = standardizeMissing (T, -99)
%!
%! ## The sentinels are now genuine missing values, ready to be filled or dropped.
%! rmmissing (S)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.summary 0000664 0000000 0000000 00000000720 15227665741 0022646 0 ustar 00root root 0000000 0000000 %!demo
%! ## Create a Table from patient data
%!
%! load patients
%! BloodPressure = [Systolic Diastolic];
%! T = table (Gender, Age, Smoker, BloodPressure, 'RowNames', LastName);
%!
%! ## Add descriptions and units to table
%!
%! T.Properties.Description = 'Simulated patient data';
%! T.Properties.VariableUnits = {'', 'Yrs', '', 'mm Hg'};
%! T.Properties.VariableDescriptions(4) = {'Systolic/Diastolic'};
%!
%! ## Print a summary of the table
%!
%! summary (T)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table 0000664 0000000 0000000 00000010150 15227665741 0022236 0 ustar 00root root 0000000 0000000 %!demo
%! ## Preallocate a table by specifying its size and the variable data types
%!
%! sz = [4, 3];
%! varTypes = {'double', 'datetime', 'string'};
%! T = table ('Size', sz, 'VariableTypes', varTypes)
%!demo
%! ## Specify variable names with the `VariableNames` name-value pair argument
%! sz = [4, 3];
%! varTypes = {'double', 'datetime', 'string'};
%! varNames = {'Temperature', 'Time', 'Station'};
%! T2 = table ('Size', sz, 'VariableTypes', varTypes, 'VariableNames', varNames)
%!
%! ## Add rows of data to the first two rows of table T2
%! T2(1,:) = {75, datetime(2024, 2, 5), string('S1')};
%! T2(2,:) = {75, datetime(2024, 2, 6), string('S2')}
%!demo
%! ## Create a table from various types of arrays
%!
%! T = table (string ({'M';'F';'M'}), [45;32;34], ...
%! {'NY';'CA';'MA'}, logical ([1;0;0]), ...
%! 'VariableNames', {'Gender', 'Age', 'State', 'Vote'})
%!demo
%! ## Create the same table using the state names as row names
%!
%! T = table (string ({'M';'F';'M'}), [45;32;34], logical ([1;0;0]), ...
%! 'VariableNames', {'Gender', 'Age', 'Vote'}, ...
%! 'RowNames', {'NY';'CA';'MA'})
%!demo
%! ## Display a table with mixed cell arrays as unicolumnar variables
%! ## and other types as multicolumnar variables
%!
%! Data_A = {[34, 32]; ['text';'picture']; 'text'; struct('c', 'data'); ...
%! [true, false]; ['some','text']; {'some','text'}; 25.34};
%! Data_B = {32, 25; 0.2, 135; 0.123, 456; 42, 5; 154, 12; 32, 10; 4, 4; 9, 94};
%! Data_C = datetime (2000, [1:8;9:16]', 1);
%!
%! T = table (Data_A, Data_B, Data_C)
%!demo
%! ## Create a nested table
%! T1 = table ([1; 2; 3], [4; 5; 6], [7; 8; 9])
%! T2 = table ({'a'; 'b'; 'c'}, {'d'; 'e'; 'f'}, {'g'; 'h'; 'i'})
%! NT = table ([1; 2; 3], T1, [4; 5; 6], T2, {5; 6; 7}, ...
%! 'VariableNames', {'A', 'B', 'C', 'D', 'E'})
%!demo
%! ## A table is *read* with three complementary indexing styles. Build a table
%! ## whose variables span several types to see how each one behaves.
%!
%! Name = string ({'Sanchez'; 'Johnson'; 'Li'; 'Diaz'});
%! Age = [38; 43; 38; 40];
%! Visit = datetime (2024, [1; 2; 3; 4], [5; 6; 7; 8]);
%! Gender = categorical ({'M'; 'M'; 'F'; 'F'});
%! T = table (Name, Age, Visit, Gender)
%!
%! ## Dot indexing extracts one variable as its own native type.
%! T.Visit
%!
%! ## Parenthesis indexing selects a sub-table — the result is still a table.
%! T(1:2, {'Name', 'Age'})
%!
%! ## Brace indexing pulls the raw contents out of the selected variables.
%! T{1:2, 'Age'}
%!demo
%! ## Assignment mirrors the three styles. Starting from a mixed-type table:
%!
%! Name = string ({'Sanchez'; 'Johnson'; 'Li'});
%! Age = [38; 43; 38];
%! Gender = categorical ({'M'; 'M'; 'F'});
%! T = table (Name, Age, Gender)
%!
%! ## Dot assignment adds or overwrites a whole variable (here computed from Age).
%! T.Senior = T.Age >= 40
%!
%! ## Parenthesis assignment with a cell sets a sub-table; a new row index grows
%! ## the table, taking one cell per variable in variable order.
%! T(4, :) = {string('Diaz'), 40, categorical({'F'}), true}
%!
%! ## Dot-then-index writes into part of an existing variable.
%! T.Age(1) = 39;
%! T.Age'
%!demo
%! ## This implementation fully supports **chained** referencing and assignment —
%! ## indexing that reaches through several levels in a single expression. (Octave
%! ## extension: MATLAB permits chained *reference* but not chained *assignment*.)
%!
%! Age = [38; 43; 38; 40];
%! Height = [71; 69; 64; 67];
%! T = table (Age, Height)
%!
%! ## Chained reference: select a sub-table, then a variable, then an element.
%! T(2:3, :).Age(1)
%!
%! ## Chained assignment writes straight through that same path.
%! T(2:3, :).Age(1) = 99;
%! T.Age'
%!demo
%! ## Chaining is most useful with nested tables, reaching an inner variable
%! ## directly — again both for reading and, unlike MATLAB, for writing.
%!
%! Inner = table ([1; 2; 3], [4; 5; 6], 'VariableNames', {'p', 'q'})
%! NT = table ([10; 20; 30], Inner, 'VariableNames', {'id', 'inner'})
%!
%! ## Read the 2nd element of inner variable q.
%! NT.inner.q(2)
%!
%! ## Assign straight into it in one chained expression.
%! NT.inner.q(2) = 55;
%! NT.inner
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table2array 0000664 0000000 0000000 00000000777 15227665741 0023375 0 ustar 00root root 0000000 0000000 %!demo
%! ## `table2array` horizontally concatenates the variables into a single array,
%! ## so it is meant for tables whose variables share a common type. Multi-column
%! ## variables keep all their columns, so the result can be wider than the table.
%!
%! Age = [38; 43; 40];
%! BloodPressure = [124, 93; 109, 77; 117, 75];
%! T = table (Age, BloodPressure)
%! A = table2array (T)
%!
%! ## The 3-by-2 table becomes a 3-by-3 numeric matrix, because `BloodPressure`
%! ## contributes two columns.
%! size (A)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table2cell 0000664 0000000 0000000 00000000745 15227665741 0023171 0 ustar 00root root 0000000 0000000 %!demo
%! ## `table2cell` unpacks a table into a cell array with one cell per element,
%! ## preserving heterogeneous variable types that `table2array` could not merge.
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'};
%! Age = [38; 43; 38];
%! Smoker = logical ([1; 0; 1]);
%! T = table (LastName, Age, Smoker)
%! C = table2cell (T)
%!
%! ## Each column of the cell array corresponds to one table variable, so the
%! ## result is independent of the original variable types.
%! class (C)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table2csv 0000664 0000000 0000000 00000001166 15227665741 0023043 0 ustar 00root root 0000000 0000000 %!demo
%! ## `table2csv` writes a table to CSV in the package's round-trippable format:
%! ## a metadata comment line, then header rows for the variable types, names,
%! ## and units, followed by one row of data per table row.
%!
%! Age = [38; 43; 40];
%! Height = [71; 69; 64];
%! T = table (Age, Height)
%! T.Properties.VariableUnits = {'Yrs', 'in'};
%!
%! filename = fullfile (tempdir (), 'patients.csv');
%! table2csv (T, filename);
%! type (filename)
%!
%! ## Because the type and unit metadata is preserved in the header, `csv2table`
%! ## reconstructs the table faithfully.
%! csv2table (filename)
%!
%! delete (filename);
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table2ods 0000664 0000000 0000000 00000001461 15227665741 0023033 0 ustar 00root root 0000000 0000000 %!demo
%! ## `table2ods` writes a table to an OpenDocument spreadsheet, one natively
%! ## typed cell per value. The data lands on `Sheet1` by default.
%!
%! Age = [38; 43; 40];
%! Height = [71; 69; 64];
%! T = table (Age, Height)
%! filename = fullfile (tempdir (), 'patients.ods');
%! table2ods (T, filename);
%! ods2table (filename)
%!demo
%! ## Writing to a named `'Sheet'` of an existing workbook adds or replaces just
%! ## that sheet, leaving the others intact — so several tables can share one file.
%!
%! filename = fullfile (tempdir (), 'workbook.ods');
%! table2ods (table ([38; 43], 'VariableNames', {'Age'}), filename, 'Sheet', 'Patients');
%! table2ods (table ([1; 2; 3], 'VariableNames', {'Visit'}), filename, 'Sheet', 'Visits');
%! ods2table (filename, 'Sheet', 'Visits')
%!
%! delete (filename);
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.table2struct 0000664 0000000 0000000 00000001377 15227665741 0023600 0 ustar 00root root 0000000 0000000 %!demo
%! ## By default `table2struct` returns a **struct array**, one element per row,
%! ## with one field per variable — handy for row-wise iteration.
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'};
%! Age = [38; 43; 38];
%! Height = [71; 69; 64];
%! T = table (LastName, Age, Height)
%! S = table2struct (T);
%! S(2).LastName
%! S(2).Age
%!demo
%! ## Pass `'ToScalar', true` to instead get a **scalar struct** whose fields are
%! ## whole columns — the layout used by `struct2table` with `'AsArray', true`.
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'};
%! Age = [38; 43; 38];
%! Height = [71; 69; 64];
%! T = table (LastName, Age, Height)
%! S = table2struct (T, 'ToScalar', true)
%!
%! ## Now each field holds every value of that variable at once.
%! S.Age
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.tail 0000664 0000000 0000000 00000000747 15227665741 0022113 0 ustar 00root root 0000000 0000000 %!demo
%! ## `tail` mirrors `head`, previewing the *bottom* of a table. With no count it
%! ## returns the last 8 rows (or fewer if the table is short).
%!
%! n = (1:20)';
%! T = table (string (num2str (n, 'ID%02d')), datetime (2024, 1, n), ...
%! categorical (mod (n, 3), 0:2, {'low', 'mid', 'hi'}), n .^ 2, ...
%! 'VariableNames', {'Tag', 'Date', 'Band', 'Score'});
%! tail (T)
%!
%! ## Pass a count to ask for a specific number of trailing rows.
%! tail (T, 3)
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.topkrows 0000664 0000000 0000000 00000001122 15227665741 0023036 0 ustar 00root root 0000000 0000000 %!demo
%! ## `topkrows` returns the top `k` rows by a sort key without sorting the whole
%! ## table — like `sortrows` followed by `head`, but stated in one call. The
%! ## default direction is descending, so the largest values come first.
%!
%! LastName = {'Sanchez'; 'Johnson'; 'Li'; 'Diaz'; 'Brown'};
%! Age = [38; 43; 38; 40; 49];
%! T = table (Age, 'RowNames', LastName)
%! topkrows (T, 3, 'Age')
%!
%! ## Add a direction to take the *smallest* instead, and capture the index of
%! ## the selected rows in the original table.
%! [B, idx] = topkrows (T, 2, 'Age', 'ascend');
%! B
%! idx
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.union 0000664 0000000 0000000 00000001335 15227665741 0022304 0 ustar 00root root 0000000 0000000 %!demo
%! ## `union` returns the rows present in either table, with duplicates removed —
%! ## set arithmetic over *whole rows*, comparing all variables together. Both
%! ## tables must share the same variables; here each row spans three types.
%!
%! A = table ({'Li'; 'Diaz'; 'Brown'}, [38; 40; 49], ...
%! categorical ({'NY'; 'CA'; 'MA'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! B = table ({'Diaz'; 'Brown'; 'Lee'}, [40; 49; 30], ...
%! categorical ({'CA'; 'MA'; 'TX'}), ...
%! 'VariableNames', {'Name', 'Age', 'State'})
%! union (A, B)
%!
%! ## Diaz and Brown match on every variable, so they appear once; the result has
%! ## four distinct rows out of the six inputs.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.unique 0000664 0000000 0000000 00000001072 15227665741 0022460 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unique` removes duplicate rows, comparing whole rows across all variables
%! ## regardless of their types. By default the surviving rows come back sorted.
%!
%! Gender = categorical ({'M'; 'F'; 'M'; 'F'; 'M'});
%! State = string ({'NY'; 'CA'; 'NY'; 'CA'; 'NY'});
%! Visits = [1; 2; 1; 3; 1];
%! T = table (Gender, State, Visits)
%! unique (T)
%!
%! ## Use `'stable'` to keep the rows in their order of first appearance instead,
%! ## and capture the index vectors relating the inputs to the unique rows.
%! [U, ia, ic] = unique (T, 'stable');
%! U
%! ic'
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.unstack 0000664 0000000 0000000 00000001003 15227665741 0022614 0 ustar 00root root 0000000 0000000 %!demo
%! ## `unstack` reshapes tall data to wide — the inverse of `stack`. It spreads
%! ## the values of one data variable across new columns, one per level of an
%! ## indicator variable, grouping by the remaining variables.
%!
%! Name = categorical ({'Li'; 'Li'; 'Diaz'; 'Diaz'});
%! Month = categorical ({'Jan'; 'Feb'; 'Jan'; 'Feb'});
%! Value = [1; 3; 2; 4];
%! T = table (Name, Month, Value)
%! unstack (T, 'Value', 'Month')
%!
%! ## Each distinct `Month` becomes its own column, with one row per `Name`.
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.varfun 0000664 0000000 0000000 00000000614 15227665741 0022454 0 ustar 00root root 0000000 0000000 %!demo
%! ## `varfun` applies a function to each variable of a table — a column-wise map.
%! ## The result is itself a table, its variable names prefixed by the function.
%!
%! T = table ([38; 43; 40], [71; 69; 64], 'VariableNames', {'Age', 'Height'})
%! varfun (@mean, T)
%!
%! ## Ask for a plain array instead of a table with `'OutputFormat'`.
%! varfun (@mean, T, 'OutputFormat', 'uniform')
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.vertcat 0000664 0000000 0000000 00000002532 15227665741 0022624 0 ustar 00root root 0000000 0000000 %!demo
%! ## `vertcat` stacks tables on top of one another, appending rows. The tables
%! ## must share the same variables (same names, compatible types). The `[A; B]`
%! ## bracket syntax calls it for you.
%!
%! A = table (string ({'Li'; 'Diaz'}), [38; 40], categorical ({'M'; 'F'}), ...
%! 'VariableNames', {'Name', 'Age', 'Gender'})
%! B = table (string ({'Brown'; 'Lee'}), [49; 30], categorical ({'M'; 'M'}), ...
%! 'VariableNames', {'Name', 'Age', 'Gender'})
%! [A; B]
%!demo
%! ## Because vertical concatenation only adds rows, the column-aligned metadata is
%! ## unchanged: a *variable*-scoped custom property carries straight through, and a
%! ## *table*-scoped one is kept when the operands agree.
%!
%! A = table ([38; 40], categorical ({'M'; 'F'}), 'VariableNames', {'Age', 'Gender'})
%! A = addprop (A, {'Study', 'Source'}, {'table', 'variable'});
%! A.Properties.CustomProperties.Study = 'Cohort-7';
%! A.Properties.CustomProperties.Source = {'intake', 'intake'};
%!
%! B = table ([49; 30], categorical ({'M'; 'M'}), 'VariableNames', {'Age', 'Gender'})
%! B = addprop (B, {'Study', 'Source'}, {'table', 'variable'});
%! B.Properties.CustomProperties.Study = 'Cohort-7';
%! B.Properties.CustomProperties.Source = {'intake', 'intake'};
%!
%! V = [A; B];
%! V.Properties.CustomProperties.Source
%! V.Properties.CustomProperties.Study
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.width 0000664 0000000 0000000 00000000717 15227665741 0022276 0 ustar 00root root 0000000 0000000 %!demo
%! ## `width` counts *variables*, not the underlying columns. `BloodPressure`
%! ## is a single variable spanning two columns, so the width is 2, not 3.
%!
%! Age = [38; 43; 38; 40; 49];
%! Smoker = logical ([1; 0; 1; 0; 1]);
%! BloodPressure = [124, 93; 109, 77; 125, 83; 117, 75; 122, 80];
%! T = table (Age, Smoker, BloodPressure)
%! width (T)
%!
%! ## Splitting the multi-column variable into scalar columns raises the width.
%! width (splitvars (T))
pr0m1th3as-datatypes-9c9a8d3/inst/demos/table.writetable 0000664 0000000 0000000 00000001771 15227665741 0023322 0 ustar 00root root 0000000 0000000 %!demo
%! ## `writetable` writes a table in a **MATLAB-interoperable** format — a plain
%! ## header row of variable names followed by the data, with no package-specific
%! ## metadata. The file type follows the extension; `'Delimiter'` sets the
%! ## separator for text files.
%!
%! T = table ([38; 43; 40], [71; 69; 64], 'VariableNames', {'Age', 'Height'})
%! filename = fullfile (tempdir (), 'patients.txt');
%! writetable (T, filename, 'Delimiter', 'tab');
%! type (filename)
%!
%! delete (filename);
%!demo
%! ## For spreadsheets, choose the target `'Sheet'` and, with `'WriteRowNames'`,
%! ## emit the row names as the leading column — `readtable` reads it straight back.
%!
%! T = table ([38; 43], [71; 69], 'VariableNames', {'Age', 'Height'}, ...
%! 'RowNames', {'Li', 'Diaz'})
%! filename = fullfile (tempdir (), 'patients.ods');
%! writetable (T, filename, 'Sheet', 'Cohort', 'WriteRowNames', true);
%! readtable (filename, 'Sheet', 'Cohort', 'ReadRowNames', true)
%!
%! delete (filename);
pr0m1th3as-datatypes-9c9a8d3/inst/duration.m 0000664 0000000 0000000 00000544561 15227665741 0021054 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
classdef duration
## -*- texinfo -*-
## @deftp {datatypes} duration
##
## Array representing durations of time using fixed-length time units.
##
## @qcode{duration} values are stored internally as @qcode{double} type array
## representing numbers of elapsed days as a fixed-length time unit. By
## default, fractional seconds of duration values are not displayed, but their
## actual precision is closer to nanoseconds for typical time lengths.
##
## @code{duration} arrays can be created through their constructor by
## combining numeric arrays representing individual fixed-length elapsed time
## units or through the functions @code{years}, @code{days}, @code{hours},
## @code{minutes}, @code{seconds}, and @code{calyears}, which create
## fixed-length durations in terms of a single duration units. These
## functions are also available as methods of @code{duration} arrays to
## extract individual duration units as numeric arrays.
##
## @seealso{calendarDuration, datetime}
## @end deftp
properties
## -*- texinfo -*-
## @deftp {duration} {property} Format
##
## Display format
##
## Display format, specified as a character vector or string scalar. If
## specified as a string scalar, it is converted and stored internally as
## a character vector.
##
## @end deftp
Format = 'hh:mm:ss'
endproperties
properties (SetAccess = private, Hidden)
## Duration length in days
Days = 0
endproperties
methods (Hidden)
## Custom display
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, 'duration', in_name);
endfunction
## Custom display
function disp (this)
__disp__ (this, 'duration');
endfunction
endmethods
################################################################################
## ** Create and convert 'duration' type ** ##
################################################################################
## Available Methods ##
## ##
## 'duration' 'dispstrings' 'cellstr' 'char' ##
## 'datevec' 'hms' 'years' 'days' ##
## 'hours' 'minutes' 'seconds' 'milliseconds' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{D} =} duration (@var{X})
## @deftypefnx {duration} {@var{D} =} duration (@var{H}, @var{MI}, @var{S})
## @deftypefnx {duration} {@var{D} =} duration (@var{H}, @var{MI}, @var{S}, @var{MS})
## @deftypefnx {duration} {@var{D} =} duration (@var{TimeStrings})
## @deftypefnx {duration} {@var{D} =} duration (@var{TimeStrings}, @qcode{'InputFormat'}, @var{INFMT})
## @deftypefnx {duration} {@var{D} =} duration (@dots{}, @qcode{'Format'}, @var{FMT})
##
## Create a new array of fixed-length time durations.
##
## @code{@var{D} = duration (@var{X})} creates a column vector of durations
## from a numeric matrix.
##
## @code{@var{D} = duration (@var{H}, @var{MI}, @var{S})} creates a duration
## array from numeric arrays containing the number of hours, minutes, and
## seconds specified by @var{H}, @var{MI} and @var{S}, respectively.
##
## @code{@var{D} = duration (@var{H}, @var{MI}, @var{S}, @var{MS})} creates
## a duration array from numeric arrays containing the number of hours,
## minutes, seconds, and milliseconds specified by @var{H}, @var{MI},
## @var{S}, and @var{MS}, respectively.
##
## @code{@var{D} = duration (@var{TimeStrings})} creates a duration array
## from text that represents elapsed times. @var{TimeStrings} can be a
## character vector, a cell array of character vectors, or a string array
## representing times using either the @qcode{'hh:mm:ss'} or the
## @qcode{'dd:hh:mm:ss'} format.
##
## @code{@var{D} = duration (@var{TimeStrings}, @qcode{'InputFormat'},
## @var{INFMT})} creates a duration array from text that represents elapsed
## times according to the format specified by @var{INFMT}, which can be any
## of the following:
##
## @itemize
## @item @qcode{'dd:hh:mm:ss'}
## @item @qcode{'hh:mm:ss'}
## @item @qcode{'mm:ss'}
## @item @qcode{'hh:mm'}
## @item Any of the first three formats can also be appended with up to nine
## @qcode{S} characters to indicate fractional second digits, such as
## @qcode{'dd:hh:mm:ss.SS'} or @qcode{'mm:ss.SS'}.
## @end itemize
##
## @code{@var{D} = duration (@dots{}, @qcode{'Format'}, @var{FMT})}
## specifies the format in which @var{D} is displayed. @var{FMT} can
## specify either a digital timer, which can have any of the valid formats
## for @qcode{'InputFormat'} as shown above or a single number with time
## units by specifying one of the following:
##
## @itemize
## @item @qcode{'y'} fixed-length years (1 year equals 365.2425 days)
## @item @qcode{'d'} fixed-length days (1 day equals 24 hours)
## @item @qcode{'h'} hours
## @item @qcode{'m'} minutes
## @item @qcode{'s'} seconds
## @end itemize
##
## @code{@var{D} = duration ()} returns a scalar array of durations with an
## elapsed time value of zero. To create an empty duration array, use
## @code{duration ([], [], [])}.
##
## @seealso{years, days, hours, minutes, seconds, milliseconds, duration,
## isduration, calendarDuration, datetime}
## @end deftypefn
function this = duration (varargin)
## Return a scalar duration object
if (nargin == 0)
return
endif
## Parse optional Name-Value paired arguments
optNames = {'Format', 'InputFormat'};
dfValues = {[], []};
[Format, inputFormat, args] = ...
parsePairedArguments (optNames, dfValues, varargin(:));
## Check optional 'Format' and 'InputFormat' arguments
if (! isempty (Format))
## Convert string to character vector if necessary
if (isstring (Format))
if (! isscalar (Format))
error (strcat ("duration: 'Format' must be a character", ...
" vector or a string scalar."));
endif
Format = char (Format);
elseif (! (ischar (Format) && isrow (Format)))
error (strcat ("duration: 'Format' must be a character", ...
" vector or a string scalar."));
endif
errmsg = checkFormatString (Format);
if (! isempty (errmsg))
error ("duration: %s", errmsg);
endif
this.Format = Format;
endif
if (! isempty (inputFormat))
## Convert string to character vector if necessary
if (isstring (inputFormat))
if (! isscalar (inputFormat))
error (strcat ("duration: 'InputFormat' must be a", ...
" character vector or a string scalar."));
endif
inputFormat = char (inputFormat);
elseif (! (ischar (inputFormat) && isrow (inputFormat)))
error (strcat ("duration: 'InputFormat' must be a character", ...
" vector or a string scalar."));
endif
errmsg = checkInputFormatString (inputFormat);
if (! isempty (errmsg))
error ("duration: %s", errmsg);
endif
endif
## Parse inputs
switch (numel (args))
## this = duration ()
case 0
return
## this = duration (X)
case 1
X = args{1};
if (isnumeric (X))
if (! ismatrix (X))
error ("duration: numeric X must be a matrix.");
endif
if (! isreal (X))
error ("duration: numeric X must be real.");
endif
if (size (X, 2) == 3)
H = X(:,1);
MI = X(:,2);
S = X(:,3);
else
error ("duration: X must have 3 columns.");
endif
[~, this.Days] = hms2days (H, MI, S);
## Return a warning if InputFormat is defined
if (! isempty (inputFormat))
warning (strcat ("duration: 'InputFormat' has no effect", ...
" on numeric data."));
endif
elseif (iscellstr (X) || ischar (X) || isa (X, "string"))
if (! iscellstr (X))
X = cellstr (X);
endif
this.Days = timestrings2days (X, inputFormat);
else
error ("duration: invalid type of single input data argument.");
endif
## this = duration (H, MI, S)
case 3
[H, MI, S] = args{:};
if (! (isnumeric (H) && isnumeric (MI) && isnumeric (S)))
error ("duration: H, MI, and S must be numeric arrays.");
endif
if (! (isreal (H) && isreal (MI) && isreal (S)))
error ("duration: H, MI, and S must be real.");
endif
## Expansion is handled by the helper function
[err, days] = hms2days (H, MI, S);
if (err > 0)
error ("duration: H, MI, and S must be of common size or scalars.");
endif
this.Days = days;
## Return a warning if InputFormat is defined
if (! isempty (inputFormat))
warning ("duration: 'InputFormat' has no effect on numeric data.");
endif
## this = duration (H, MI, S, MS)
case 4
[H, MI, S, MS] = args{:};
if (! (isnumeric (H) && isnumeric (MI) && isnumeric (S) && ...
isnumeric (MS)))
error ("duration: H, MI, S, and MS must be numeric arrays.");
endif
if (! (isreal (H) && isreal (MI) && isreal (S) && isreal (MS)))
error ("duration: H, MI, S, and MS must be real.");
endif
## Expansion is handled by the helper function
[err, days] = hms2days (H, MI, S, MS);
if (err > 0)
error (strcat ("duration: H, MI, S, and MS must be of", ...
" common size or scalars."));
endif
this.Days = days;
## Return a warning if InputFormat is defined
if (! isempty (inputFormat))
warning ("duration: 'InputFormat' has no effect on numeric data.");
endif
otherwise
error ("duration: invalid number of input arguments.");
endswitch
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{cstr} =} dispstrings (@var{D})
##
## Get display formatted strings for each element of a duration array.
##
## @code{@var{cstr} = dispstrings (@var{D})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## duration @var{D}.
##
## @end deftypefn
function cstr = dispstrings (this)
## Get display format
fmt = strsplit (this.Format, '.')';
if (numel (fmt) == 1)
fmt = fmt{1};
fracSec = false;
else
fracSec = true;
fdigits = numel (fmt{2});
pat = sprintf ('.%%0%dd', fdigits);
fmt = fmt{1};
endif
## Process all elements
sz = size (this);
cstr = cell (sz);
for i = 1:prod (sz)
d = this.Days(i);
## Handle NaNs and Infs early
if (! isfinite (d))
switch (fmt)
case 'y'
cstr{i} = sprintf ('%g yrs', d);
case 'd'
cstr{i} = sprintf ('%g days', d);
case 'h'
cstr{i} = sprintf ('%g hr', d);
case 'm'
cstr{i} = sprintf ('%g min', d);
case 's'
cstr{i} = sprintf ('%g sec', d);
otherwise
cstr{i} = sprintf ('%g', d);
endswitch
else
## Get sign for positive/negative duration
str = '';
if (d < 0)
str = [str, '-'];
d = abs (d);
endif
## Build string according to display format
if (strcmp (fmt, 'y'))
years = d / 365.2425;
if (years == 1)
str = [str, sprintf('%g yr', years)];
else
str = [str, sprintf('%g yrs', years)];
endif
elseif (strcmp (fmt, 'd'))
if (d == 1)
str = [str, sprintf('%g day', d)];
else
str = [str, sprintf('%g days', d)];
endif
elseif (strcmp (fmt, 'h'))
str = [str, sprintf('%g hr', d * 24)];
elseif (strcmp (fmt, 'm'))
str = [str, sprintf('%g min', d * 1440)];
elseif (strcmp (fmt, 's'))
str = [str, sprintf('%g sec', d * 86400)];
elseif (strcmp (fmt, 'hh:mm'))
## Convert to minutes
x = d * 1440;
## Calculate hours
tmp = x / 60;
h = fix (tmp);
## Fix round-off errors with threshold scaled by hours
if (abs (tmp - h - 1) < 1e-13 * (1 + h))
h++;
endif
## Calculate remaining minutes
tmp = x - h * 60;
m = fix (tmp);
## Fix round-off errors with threshold scaled by minutes
if (abs (tmp - m - 1) < 1e-13 * (1 + m))
m++;
endif
str = [str, sprintf('%02d:%02d', h, m)];
elseif (strcmp (fmt, 'mm:ss'))
## Convert to seconds
x = d * 86400;
## Calculate minutes
tmp = x / 60;
m = fix (tmp);
## Fix round-off errors with threshold scaled by minutes
if (abs (tmp - m - 1) < 1e-13 * (1 + m))
m++;
endif
## Calculate remaining seconds
tmp = x - m * 60;
s = fix (tmp);
## Fix round-off errors with threshold scaled by seconds
if (abs (tmp - s - 1) < 1e-12 * (1 + s))
s++;
endif
str = [str, sprintf('%02d:%02d', m, s)];
if (fracSec)
fs = rem (x, 60) - s; # fraction of a second
## Promote to integer value according to requested digits
ms = abs (fix (fs * 10 ^ fdigits));
str = [str, sprintf(pat, ms)];
endif
elseif (strcmp (fmt, 'hh:mm:ss'))
## Convert to seconds
x = d * 86400;
## Calculate hours
tmp = x / 3600;
h = fix (tmp);
## Fix round-off errors with threshold scaled by hours
if (abs (tmp - h - 1) < 1e-13 * (1 + h))
h++;
endif
## Calculate remaining duration in seconds
x = x - h * 3600;
## Calculate remaining minutes
tmp = x / 60;
m = fix (tmp);
## Fix round-off errors with threshold scaled by minutes
if (abs (tmp - m - 1) < 1e-13 * (1 + m))
m++;
endif
## Calculate remaining seconds
x = x - m * 60;
s = fix (x);
## Fix round-off errors with threshold scaled by seconds
if (abs (x - s - 1) < 1e-12 * (1 + s))
s++;
endif
str = [str, sprintf('%02d:%02d:%02d', h, m, s)];
if (fracSec)
fs = x - s; # fraction of a second
## Round to nearest nanosecond
fs = round (fs * 1e+9) * 1e-9;
## Promote to integer value according to requested digits
ms = floor (fs * 10 ^ fdigits);
str = [str, sprintf(pat, ms)];
endif
elseif (strcmp (fmt, 'dd:hh:mm:ss'))
## Calculate days
tmp = fix (d);
## Fix round-off errors with threshold scaled by days
if (abs (d - tmp - 1) < 1e-15 * (1 + d))
tmp++;
endif
x = d - tmp;
d = tmp;
## Calculate remaining duration in seconds
x = x * 86400;
## Calculate hours
tmp = x / 3600;
h = fix (tmp);
## Fix round-off errors with threshold scaled by hours
if (abs (tmp - h - 1) < 1e-13 * (1 + h))
h++;
endif
## Calculate remaining duration in seconds
x = x - h * 3600;
## Calculate remaining minutes
tmp = x / 60;
m = fix (tmp);
## Fix round-off errors with threshold scaled by minutes
if (abs (tmp - m - 1) < 1e-13 * (1 + m))
m++;
endif
## Calculate remaining seconds
x = x - m * 60;
s = fix (x);
## Fix round-off errors with threshold scaled by seconds
if (abs (x - s - 1) < 1e-12 * (1 + s))
s++;
endif
if (fix (d) > 0)
str = [str, sprintf('%02d:%02d:%02d:%02d', d, h, m, s)];
else
str = [str, sprintf('%02d:%02d:%02d', h, m, s)];
endif
if (fracSec)
fs = x - s; # fraction of a second
## Round to nearest nanosecond
fs = round (fs * 1e+9) * 1e-9;
## Promote to integer value according to requested digits
ms = floor (fs * 10 ^ fdigits);
str = [str, sprintf(pat, ms)];
endif
endif
cstr{i} = str;
endif
endfor
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{cstr} =} cellstr (@var{D})
## @deftypefnx {duration} {@var{cstr} =} cellstr (@var{D}, @var{Format})
##
## Convert duration array to a cell array of character vectors.
##
## @code{@var{cstr} = cellstr (@var{D})} returns a cellstr array of
## character vectors, @var{cstr}, which has the same size as the input
## duration @var{D}.
##
## @end deftypefn
function cstr = cellstr (this, Format = '')
if (! isempty (Format))
## Convert string to character vector if necessary
if (isstring (Format))
if (! isscalar (Format))
error (strcat ("duration.cellstr: FORMAT must be a", ...
" character vector or a string scalar."));
endif
Format = char (Format);
elseif (! (ischar (Format) && isrow (Format)))
error (strcat ("duration.cellstr: FORMAT must be a", ...
" character vector or a string scalar."));
endif
errmsg = checkFormatString (Format);
if (! isempty (errmsg))
error ("duration.cellstr: %s", errmsg);
endif
this.Format = Format;
endif
cstr = dispstrings (this);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{cmat} =} char (@var{D})
##
## Convert duration array to a character matrix.
##
## @code{@var{cmat} = char (@var{D})} returns a character matrix with one
## row per element in @var{D}.
##
## @end deftypefn
function cmat = char (this, Format = '')
if (! isempty (Format))
## Convert string to character vector if necessary
if (isstring (Format))
if (! isscalar (Format))
error (strcat ("duration.char: FORMAT must be a", ...
" character vector or a string scalar."));
endif
Format = char (Format);
elseif (! (ischar (Format) && isrow (Format)))
error (strcat ("duration.char: FORMAT must be a", ...
" character vector or a string scalar."));
endif
errmsg = checkFormatString (Format);
if (! isempty (errmsg))
error ("duration.char: %s", errmsg);
endif
this.Format = Format;
endif
cmat = char (dispstrings (this));
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{DV} =} datevec (@var{DT})
## @deftypefnx {duration} {[@var{Y}, @var{MO}, @var{D}, @var{h}, @var{mi}, @var{s}] =} datevec (@var{DT})
##
## Convert duration array to date vectors.
##
## @code{@var{DV} = datevec (@var{DT})} returns an @math{N*6} numeric matrix
## whose rows represent each element in @var{DT} and each column corresponds
## to years, months, days, hours, minutes, and seconds, respectively. Since
## months cannot be represented as a fixed length of time, the second column
## of @var{DV} is always zero. @var{DV} represents a length of time split
## across different fixed-length elapsed time units. The number of rows in
## @var{DV} equals to the number of elements in the duration array @var{DT}.
##
## @code{[@var{Y}, @var{MO}, @var{D}, @var{h}, @var{mi}, @var{s}] = datevec
## (@var{DT})} returns the components of @var{DT} as individual variables,
## but unlike @var{DV} in the previous syntax, each variable has the same
## size as the duration array @var{DT}.
##
## Values containing a fractional portion less than 1 picosecond are rounded
## to the nearest picosecond.
##
## @end deftypefn
function varargout = datevec (this)
d = this.Days;
tmp = d / 365.2425;
y = fix (tmp);
## Fix round-off errors with threshold scaled by years
idx = abs (tmp - y - 1) < 1e-15 * y;
y(idx) += 1;
x = rem (d, 365.2425);
d = fix (x);
x = x - d;
## Get remaining duration in seconds
x = x * 86400;
tmp = x / 3600;
h = fix (tmp);
idx = abs (tmp - h - 1) < 1e-15 * h;
h(idx) += 1;
x = x - h * 3600;
tmp = x / 60;
m = fix (tmp);
idx = abs (tmp - m - 1) < 1e-15 * m;
m(idx) += 1;
s = x - m * 60;
## Fix floating point precision to nearest picosecond
s = round (s * 1e+12) * 1e-12;
## Add months column
mo = zeros (size (s));
mo(isnan (d)) = NaN;
## Transform to matrix
DV = [y(:), mo(:), d(:), h(:), m(:), s(:)];
if (nargout == 0 || nargout == 1)
varargout{1} = DV;
elseif (nargout <= 6)
for i = 1:nargout
## Multiple outputs are reshaped to original input size
varargout{i} = reshape (DV(:,i), size (this));
endfor
else
error ("duration.datevec: too many output arguments.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{H} =} hms (@var{D})
## @deftypefnx {duration} {[@var{H}, @var{M}] =} hms (@var{D})
## @deftypefnx {duration} {[@var{H}, @var{M}, @var{S}] =} hms (@var{D})
##
## Split duration array into separate time unit values.
##
## @code{[@var{H}, @var{M}, @var{S}] = hms (@var{D})} splits the duration
## array @var{D} into separate numeric arrays @var{H}, @var{M}, and @var{S},
## which correspond to hours, minutes, and seconds, respectively. Hours and
## minutes are returned as whole numbers, while seconds may also have a
## fractional part.
##
## Values containing a fractional portion less than 1 picosecond are rounded
## to the nearest picosecond.
##
## @end deftypefn
function varargout = hms (this)
x = this.Days * 86400;
h = fix (x / 3600);
tmp = x - h * 3600;
idx = 3600 - tmp < 1e-12; # find round-off errors to whole hours
if (any (idx, 'all'))
h(idx) += 1;
x(idx) -= h(idx) * 3600;
x(! idx) = tmp(! idx);
else
x = tmp;
endif
m = fix (x / 60);
tmp = x - m * 60;
idx = 60 - tmp < 1e-12; # find round-off errors to whole minutes
if (any (idx, 'all'))
m(idx) += 1;
x(idx) -= m(idx) * 60;
x(! idx) = tmp(! idx);
else
x = tmp;
endif
s = x;
idx = x < 1e-12; # find round-off errors to whole seconds
if (any (idx, 'all'))
s(idx) = 0;
endif
## Fix floating point precision to nearest picosecond
s = round (s * 1e12) / 1e12;
if (nargout == 0 || nargout == 1)
varargout{1} = h;
elseif (nargout == 2)
varargout{1} = h;
varargout{2} = m;
elseif (nargout == 3)
varargout{1} = h;
varargout{2} = m;
varargout{3} = s;
else
error ("duration.hms: too many output arguments.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} years (@var{D})
##
## Duration equivalent numeric values in fixed-length years.
##
## @code{@var{X} = years (@var{D})} converts durations in @var{D} to the
## equivalent number of fixed-length years (1 year equals 365.2425 days).
## @var{X} is a double array of the same size as @var{D}.
##
## @end deftypefn
function out = years (this)
out = this.Days / 365.2425;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} days (@var{D})
##
## Duration equivalent numeric values in fixed-length days.
##
## @code{@var{X} = days (@var{D})} converts durations in @var{D} to the
## equivalent number of fixed-length days (1 day equals 24 hours). @var{X}
## is a double array of the same size as @var{D}.
##
## @end deftypefn
function out = days (this)
out = this.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} hours (@var{D})
##
## Duration equivalent numeric values in hours.
##
## @code{@var{X} = hours (@var{D})} converts durations in @var{D} to the
## equivalent number of hours. @var{X} is a double array of the same size
## as @var{D}.
##
## @end deftypefn
function out = hours (this)
out = this.Days * 24;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} minutes (@var{D})
##
## Duration equivalent numeric values in minutes.
##
## @code{@var{X} = minutes (@var{D})} converts durations in @var{D} to the
## equivalent number of minutes. @var{X} is a double array of the same size
## as @var{D}.
##
## Values containing a fractional portion less than 1 picosecond are rounded
## to the nearest picosecond.
##
## @end deftypefn
function out = minutes (this)
out = this.Days * 1440;
## Fix floating point precision to nearest picosecond
out = round (out * 1e13) / 1e13;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} seconds (@var{D})
##
## Duration equivalent numeric values in seconds.
##
## @code{@var{X} = seconds (@var{D})} converts durations in @var{D} to the
## equivalent number of seconds. @var{X} is a double array of the same size
## as @var{D}.
##
## Values containing a fractional portion less than 1 picosecond are rounded
## to the nearest picosecond.
##
## @end deftypefn
function out = seconds (this)
out = this.Days * 86400;
## Fix floating point precision to nearest picosecond
out = round (out * 1e12) / 1e12;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{X} =} milliseconds (@var{D})
##
## Duration equivalent numeric values in milliseconds.
##
## @code{@var{X} = milliseconds (@var{D})} converts durations in @var{D} to
## the equivalent number of milliseconds. @var{X} is a double array of the
## same size as @var{D}.
##
## Values containing a fractional portion less than 1 picosecond are rounded
## to the nearest picosecond.
##
## @end deftypefn
function out = milliseconds (this)
out = this.Days * 86400000;
## Fix floating point precision to nearest picosecond
out = round (out * 1e9) / 1e9;
endfunction
endmethods
################################################################################
## ** Summary Information ** ##
################################################################################
## Available Methods ##
## ##
## 'size' 'ndims' 'numel' 'nnz' ##
## 'length' 'keyHash' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{sz} =} size (@var{D})
## @deftypefnx {duration} {@var{dim_sz} =} size (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{dim_sz} =} size (@var{D}, @var{d1}, @var{d2}, @dots{})
## @deftypefnx {duration} {[@var{rows}, @var{columns}, @dots{}, @var{dim_n_sz}] =} size (@dots{})
##
## Return the size of a duration array.
##
## @code{@var{sz} = size (@var{D})} returns a row vector with the size
## (number of elements) of each dimension for the duration array @var{D}.
##
## @code{@var{dim_sz} = size (@var{D}, @var{dim})} returns the size of
## the corresponding dimension specified in @var{dim}. If @var{dim} is a
## vector, then @var{dim_sz} is a vector of the same length and with each
## element corresponding to a specified dimension. Multiple dimensions may
## also be specified as separate arguments.
##
## With a single output argument, @code{size} returns a row vector. When
## called with multiple output arguments, @code{size} returns the size of
## dimension N in the Nth argument.
##
## @end deftypefn
function varargout = size (this, varargin)
if (! isempty (varargin))
sz = size (this.Days, varargin{:});
else
sz = size (this.Days);
endif
if (nargout == 0 || nargout == 1)
varargout{1} = sz;
elseif (numel (sz) != nargout)
error (strcat ("duration.size: nargout > 1 but does not", ...
" match number of requested dimensions."));
else
for i = 1:nargout
varargout{i} = sz(i);
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{out} =} ndims (@var{D})
##
## Number of dimensions in a duration array.
##
## @code{@var{out} = ndims (@var{D})} returns the number of dimensions of
## the duration array @var{D}.
##
## @end deftypefn
function out = ndims (this)
out = ndims (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{out} =} numel (@var{D})
##
## Total number of elements in a duration array.
##
## @code{@var{out} = numel (@var{D})} returns the number of elements in the
## duration array @var{D}.
##
## @end deftypefn
function out = numel (this, varargin)
out = numel (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{out} =} nnz (@var{D})
##
## Number of nonzero elements in duration array.
##
## @code{@var{out} = nnz (@var{D})} returns the number of nonzero
## elements in the duration array @var{D}.
##
## @end deftypefn
function out = nnz (this)
d = this.Days(:);
out = numel (d) - sum (d == 0);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{N} =} length (@var{D})
##
## Length of a duration vector.
##
## @code{@var{N} = length (@var{D})} returns the size of the longest
## dimension of the duration array @var{D}, unless any of its dimensions has
## zero length, in which case @code{length (@var{D})} returns 0.
##
## @end deftypefn
function N = length (this)
if (isempty (this.Days))
N = 0;
else
N = max (size (this.Days));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{hey} =} keyHash (@var{D})
##
## Generate a hash code for duration array.
##
## @code{@var{h} = keyHash (@var{D})} generates a @qcode{uint64} scalar that
## represents the input array @var{D}. @code{keyHash} utilizes the 64-bit
## FNV-1a variant of the Fowler-Noll-Vo non-cryptographic hash function.
##
## @code{@var{h} = keyHash (@var{D}, @var{base})} also generates a 64-bit
## hash code using @var{base} as the offset basis for the FNV-1a hash
## algorithm. @var{base} must be a @qcode{uint64} integer type scalar. Use
## this syntax to cascade @code{keyHash} on multiple objects for which a
## single hash code is required.
##
## Note that unlike MATLAB, this implementation does not use any random
## seed. As a result, @code{keyHash} will always generate the exact same
## hash key for any particular input across different workers and Octave
## sessions.
##
## @end deftypefn
function key = keyHash (this, base = [])
## Initialize string with size and class name
size_str = sprintf ('%dx', size (this.Days))(1:end-1);
init_str = [size_str 'duration'];
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("duration.keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__(init_str, base);
else
key = __ckeyHash__(init_str);
endif
if (! isempty (this.Days))
key = __nkeyHash__(this.Days(:), key);
endif
endfunction
endmethods
################################################################################
## ** Query Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'isbetween' 'iscolumn' 'isempty' 'isequal' ##
## 'isequaln' 'isfinite' 'isinf' 'ismatrix' ##
## 'ismember' 'ismissing' 'isnan' 'isregular' ##
## 'isrow' 'isscalar' 'issorted' 'issortedrows' ##
## 'isvector' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isbetween (@var{D}, @var{lower}, @var{upper})
## @deftypefnx {duration} {@var{TF} =} isbetween (@var{D}, @var{lower}, @var{upper}, @var{intervalType})
##
## Find duration elements within specified range.
##
## @code{@var{TF} = isbetween (@var{D}, @var{lower}, @var{upper})} returns a
## logical array, @var{TF}, which is the same size as the input duration
## array @var{D} and it contains @qcode{true} for each corresponding element
## which is within the range specified by @var{lower} and @var{upper} and
## @qcode{false} otherwise. @var{lower} and @var{upper} must be duration
## arrays of compatible size with @var{D} or alternatively they can be
## specified as a character vector, a cell array of character vectors or a
## string array containing valid text duration representations.
##
## @code{@var{TF} = isbetween (@var{D}, @var{lower}, @var{upper},
## @var{intervalType})} specifies the type of interval for the @var{lower}
## and @var{upper} bounds and it can be one of the following values.
##
## @itemize
## @item @qcode{'closed'} (default) includes lower and upper bounds.
##
## @item @qcode{'open'} excludes lower and upper bounds.
##
## @item @qcode{'openleft'} or @qcode{'closedright'} exclude the lower and
## include the upper bound. They have identical behavior.
##
## @item @qcode{'closedleft'} or @qcode{'openright'} include the lower and
## exclude the upper bound. They have identical behavior.
## @end itemize
##
## @var{intervalType} can be specified either as a character vector or a
## string scalar.
##
## @end deftypefn
function TF = isbetween (this, lower, upper, varargin)
if (nargin < 3)
error ("duration.isbetween: too few input arguments.");
elseif (nargin == 3)
intervaltype = 'closed';
elseif (nargin == 4)
intervaltype = varargin{1};
elseif (nargin > 4)
error (strcat ("duration.isbetween: optional paired arguments", ...
" are not supported for duration arrays."));
endif
if (isnumeric (lower) || isnumeric (upper))
error ("duration.isbetween: LOWER and UPPER cannot be numeric.");
endif
if (strcmpi (intervaltype, 'closed'))
TF = lower <= this & this <= upper;
elseif (strcmpi (intervaltype, 'open'))
TF = lower < this & this < upper;
elseif (any (strcmpi (intervaltype, {'openleft', 'closedright'})))
TF = lower < this & this <= upper;
elseif (any (strcmpi (intervaltype, {'openright', 'closedleft'})))
TF = lower <= this & this < upper;
else
error ("duration.isbetween: invalid INTERVALTYPE option.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} iscolumn (@var{D})
##
## Return true if duration array is a column vector.
##
## @code{@var{TF} = iscolumn (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is a column vector
## and @qcode{false} otherwise. A column vector is a 2-D array for which
## @code{size (@var{D})} returns @code{[@var{N}, 1]} with non-negative
## @var{N}. By definition, a scalar is also a column vector.
##
## @end deftypefn
function TF = iscolumn (this)
TF = iscolumn (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isempty (@var{D})
##
## Return true if duration array is empty.
##
## @code{@var{TF} = isempty (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is empty and
## @qcode{false} otherwise.
##
## @end deftypefn
function TF = isempty (this)
TF = isempty (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isequal (@var{D1}, @var{D2})
## @deftypefnx {duration} {@var{TF} =} isequal (@var{D1}, @var{D2}, @dots{})
##
## Return true if duration arrays are equal.
##
## @code{@var{TF} = isequal (@var{D1}, @var{D2})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the duration arrays @var{D1} and
## @var{D2} contain the same values, and @qcode{false} otherwise. Either
## @var{D1} or @var{D2} can also be specified as a character vector, a cell
## array of character vectors or a string array containing valid text
## duration representations.
##
## @code{@var{TF} = isequal (@var{D1}, @var{D2}, @dots{})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if all input arguments are equal,
## and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequal (varargin)
args = varargin;
[args{:}] = promote (varargin{:});
days = cellfun (@(obj) obj.Days, args, 'UniformOutput', false);
TF = isequal (days{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isequaln (@var{D1}, @var{D2})
## @deftypefnx {duration} {@var{TF} =} isequaln (@var{D1}, @var{D2}, @dots{})
##
## Return true if duration arrays are equal under the assumption that
## missing elements are equal.
##
## @code{@var{TF} = isequaln (@var{D1}, @var{D2})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the duration arrays @var{D1} and
## @var{D2} contain the same values or corresponding missing elements, and
## @qcode{false} otherwise. Either @var{D1} or @var{D2} can also be
## specified as a character vector, a cell array of character vectors or a
## string array containing valid text duration representations.
##
## @code{@var{TF} = isequaln (@var{D1}, @var{D2}, @dots{})} returns a
## logical scalar @var{TF}, which is @qcode{true}, if all input arguments
## are equal under the assumption that missing elements are equal, and
## @qcode{false} otherwise.
##
## @end deftypefn
function TF = isequaln (varargin)
args = varargin;
[args{:}] = promote (varargin{:});
days = cellfun (@(obj) obj.Days, args, 'UniformOutput', false);
TF = isequaln (days{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isfinite (@var{D})
##
## Return true for duration elements that are finite.
##
## @code{@var{TF} = isfinite (@var{D})} returns a logical array @var{TF}
## of the same size as @var{calD} containing @qcode{true} for each
## corresponding element of @var{D} that is finite and @qcode{false}
## otherwise. Finite elements are those which are neither infinite nor
## Not-A-Number.
##
## @end deftypefn
function TF = isfinite (this)
TF = isfinite (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isinf (@var{D})
##
## Return true for duration elements that are infinite.
##
## @code{@var{TF} = isinf (@var{D})} returns a logical array @var{TF}
## of the same size as @var{D} containing @qcode{true} for each
## corresponding element of @var{calD} that is either @qcode{Inf} or
## @qcode{-Inf} and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isinf (this)
TF = isinf (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} ismatrix (@var{D})
##
## Return true if duration array is a 2-D array.
##
## @code{@var{TF} = ismatrix (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is a matrix and
## @qcode{false} otherwise. A matrix is an array of any type where
## @code{ndims (@var{D}) == 2}. By definition, a scalar is also a matrix.
##
## @end deftypefn
function TF = ismatrix (this)
TF = ismatrix (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} ismember (@var{A}, @var{B})
## @deftypefnx {duration} {@var{TF} =} ismember (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {duration} {[@var{TF}, @var{index}] =} ismember (@dots{})
## @deftypefnx {duration} {[@var{TF}, @var{index}] =} ismember (@dots{}, @qcode{'legacy'})
##
## Find duration elements in a set.
##
## @code{@var{TF} = ismember (@var{A}, @var{B})} returns a logical array
## @var{TF} of the same size as @var{A} containing @qcode{true} for each
## corresponding element of @var{A} that is in @var{B} and @qcode{false}
## otherwise. @qcode{NaN} elements are not equal with each other and always
## return @qcode{false}.
##
## @code{@var{TF} = ismember (@var{A}, @var{B}, @qcode{'rows'})} only
## applies to duration matrices with the same number of columns, in which
## case the logical vector @var{TF} contains @qcode{true} for each row of
## @var{A} that is also a row in @var{B}. @var{TF} has the same number of
## rows as @var{A}.
##
## @code{[@var{TF}, @var{index}] = ismember (@var{A}, @var{B})} also returns
## an index array of the same size as @var{A} containing the lowest index in
## @var{B} for each element of @var{A} that is a member of @var{B} and 0
## otherwise. If the @qcode{'rows'} optional argument is used, then the
## returning index is a column vector with the same rows as @var{A} and it
## contains the lowest index in @var{B} for each row of @var{A} that is a
## member of @var{B} and 0 otherwise. If the @qcode{'legacy'} optional
## argument is specified, then the highest index of matched elements is
## returned. Unless multiple matches exist, the @qcode{'legacy'} option has
## no effect on the returned @var{index}.
##
## @end deftypefn
function varargout = ismember (A, B, varargin)
## Check input arguments
if (! isa (B, 'duration'))
B = promote (B);
endif
## Check for 'rows' and 'legacy' optional arguments
if (! isempty (varargin))
if (! cellfun ('ischar', varargin));
error ("duration.ismember: all options must be character vectors.");
elseif (! all (strcmpi (varargin, 'rows') | ...
strcmpi (varargin, 'legacy')))
error (strcat ("duration.ismember: only 'rows' and 'legacy'", ...
" are valid options."));
endif
do_rows = any (strcmpi ('rows', varargin));
if (do_rows)
if (ndims (A) != 2 || ndims (A) != ndims (B))
error ("duration.ismember: 'rows' applies only to 2-D matrices.");
endif
if (size (A, 2) != size (B, 2))
error (strcat ("duration.ismember: 'rows' requires same", ...
" number of columns."));
endif
endif
if (nargout > 1)
[varargout{1}, varargout{2}] = __ismember__ (A.Days, B.Days, ...
varargin{:});
else
varargout{1} = __ismember__ (A.Days, B.Days, varargin{:});
endif
else
if (nargout > 1)
[varargout{1}, varargout{2}] = __ismember__ (A.Days, B.Days);
else
varargout{1} = __ismember__ (A.Days, B.Days);
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} ismissing (@var{D})
## @deftypefnx {duration} {@var{TF} =} ismissing (@var{D}, @var{indicator})
##
## Find missing elements in duration array.
##
## @code{@var{TF} = ismissing (@var{D})} returns a logical array, @var{TF},
## with the same dimensions as @var{D}, where @code{true} values match the
## standard missing values in the input duration array.
##
## The optional input @var{indicator} can be a scalar or a vector duration
## array, specifying alternative missing values in the input data. When
## specifying @var{indicator} values, the standard missing values are
## ignored, unless explicitly stated in the @var{indicator}.
##
## @end deftypefn
function TF = ismissing (this, varargin)
if (nargin > 2)
error ("duration.ismissing: too many input arguments.");
endif
if (! isempty (varargin))
indicator = varargin{1};
TF = false (size (this));
if (isvector (indicator))
if (isa (indicator, 'duration'))
for i = 1:length (indicator)
TF(this.Days == indicator.Days(i)) = true;
endfor
else
error ("duration.ismissing: INDICATOR must be a 'duration' array.");
endif
else
error ("duration.ismissing: INDICATOR must be a vector.");
endif
else
TF = isnan (this.Days);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isnan (@var{D})
##
## Return true for duration elements that are Not-A-Number.
##
## @code{@var{TF} = isnan (@var{D})} returns a logical array @var{TF} of
## the same size as @var{D} containing @qcode{true} for each corresponding
## element of @var{calD} that is @qcode{NaN} and @qcode{false} otherwise.
##
## @end deftypefn
function TF = isnan (this)
TF = isnan (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isrow (@var{D})
##
## Return true if duration array is a row vector.
##
## @code{@var{TF} = isrow (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is a row vector
## and @qcode{false} otherwise. A row vector is a 2-D array for which
## @code{size (@var{D})} returns @code{[1, @var{N}]} with non-negative
## @var{N}. By definition, a scalar is also a row vector.
##
## @end deftypefn
function TF = isrow (this)
TF = isrow (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isscalar (@var{D})
##
## Return true if duration array is a scalar.
##
## @code{@var{TF} = isscalar (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is also a scalar
## and @qcode{false} otherwise. A scalar is a single element object for
## which @code{size (@var{D})} returns @code{[1, 1]}.
##
## @end deftypefn
function TF = isscalar (this)
TF = isscalar (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} issorted (@var{D})
## @deftypefnx {duration} {@var{TF} =} issorted (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{TF} =} issorted (@var{D}, @var{direction})
## @deftypefnx {duration} {@var{TF} =} issorted (@var{D}, @var{dim}, @var{direction})
## @deftypefnx {duration} {@var{TF} =} issorted (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {duration} {@var{TF} =} issorted (@dots{}, @qcode{'ComparisonMethod'}, @var{CM})
##
## Return true if duration array is sorted.
##
## @code{@var{TF} = issorted (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true}, if the duration array @var{D} is sorted in
## ascending order, and @qcode{false} otherwise.
##
## @code{@var{TF} = issorted (@var{D}, @var{dim})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the duration array @var{D} is
## sorted in ascending order along the dimension @var{dim}, and
## @qcode{false} otherwise.
##
## @code{@var{TF} = issorted (@var{D}, @var{direction})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if the duration array @var{D}
## is sorted in the direction specified by @var{direction}, and
## @qcode{false} otherwise. @var{direction} can be any of the following
## options:
##
## @itemize
## @item @qcode{'ascend'}, which is the default, checks is elements are in
## ascending order.
## @item @qcode{'descend'} checks if elements are in descending order.
## @item @qcode{'monotonic'} checks if elements are either in ascending or
## descending order.
## @item @qcode{'strictascend'} checks if elements are in ascending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictdescend'} checks if elements are in descending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictmonotonic'} checks if elements are either in
## ascending or descending order and there are no duplicate or undefined
## elements.
## @end itemize
##
## @code{@var{TF} = issorted (@dots{}, @qcode{'MissingPlacement'},
## @var{MP})}
## specifies where missing elements (@qcode{NaN}) are placed with one of the
## following options specified in @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{@var{TF} = issorted (@dots{}, @qcode{'ComparisonMethod'},
## @var{CM})}
## specifies the comparison method for determining the order of elements
## with one of following options specified in @var{CM}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, sorts by @code{real (A)}.
## @item @qcode{'real'} sorts by @code{real (A)}.
## @item @qcode{'abs'} sorts by @code{abs (A)}.
## @end itemize
##
## @end deftypefn
function TF = issorted (this, varargin)
## Single input argument
if (nargin == 1)
TF = isequaln (this, sort (this));
return;
endif
## Get operating dimension
cid = cellfun (@isnumeric, varargin);
if (any (cid))
dim = varargin{cid};
else
sz = size (this);
dim = find (sz != 1, 1);
if (isempty (dim)) # scalar
dim = 1;
endif
endif
## Force strings to character vectors
[varargin{:}] = convertStringsToChars (varargin{:});
## Get direction from input argument list
valid_direction = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
fcn = @(x) ischar (x) && ismember (x, valid_direction);
cid = cellfun (fcn, varargin);
if (any (cid))
direction = varargin{cid};
switch (direction)
case {'ascend', 'descend'}
TF = isequaln (this, sort (this, varargin{:}));
case 'monotonic'
## Check for either ascending or descending
varargin{cid} = 'ascend';
TF = isequaln (this, sort (this, varargin{:}));
if (TF)
return;
endif
varargin{cid} = 'descend';
TF = isequaln (this, sort (this, varargin{:}));
case 'strictascend'
## Check for missing values first (fast)
if (any (ismissing (this), 'all'))
TF = false;
return;
endif
varargin{cid} = strrep (direction, 'strict', '');
sorted = sort (this, varargin{:});
if (any (diff (sorted, 1, dim) <= 0, 'all'))
TF = false;
return;
endif
TF = isequaln (this, sorted);
case 'strictdescend'
## Check for missing values first (fast)
if (any (ismissing (this), 'all'))
TF = false;
return;
endif
varargin{cid} = strrep (direction, 'strict', '');
sorted = sort (this, varargin{:});
if (any (diff (sorted, 1, dim) >= 0, 'all'))
TF = false;
return;
endif
TF = isequaln (this, sorted);
case 'strictmonotonic'
## Check missing values first (fast)
if (any (ismissing (this), 'all'))
TF = false;
return;
endif
## Check for either ascending or descending
varargin{cid} = 'ascend';
sorted = sort (this, varargin{:});
if (any (diff (sorted, 1, dim) <= 0, 'all'))
TF = false;
return;
endif
TF = isequaln (this, sorted);
if (TF)
return;
endif
varargin{cid} = 'descend';
sorted = sort (this, varargin{:});
if (any (diff (sorted, 1, dim) >= 0, 'all'))
TF = false;
return;
endif
TF = isequaln (this, sorted);
endswitch
else
## No DIRECTION input argument
TF = isequaln (this, sort (this, varargin{:}));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} issortedrows (@var{D})
## @deftypefnx {duration} {@var{TF} =} issortedrows (@var{D}, @var{col})
## @deftypefnx {duration} {@var{TF} =} issortedrows (@var{D}, @var{direction})
## @deftypefnx {duration} {@var{TF} =} issortedrows (@var{D}, @var{col}, @var{direction})
## @deftypefnx {duration} {@var{TF} =} issortedrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {duration} {@var{TF} =} issortedrows (@dots{}, @qcode{'ComparisonMethod'}, @var{CM})
##
## Return true if duration matrix rows are sorted.
##
## @code{@var{TF} = issortedrows (@var{D})} returns a logical scalar
## @var{TF}, which is @qcode{true}, if the rows in the 2-D duration array
## @var{D} are sorted in ascending order, and @qcode{false} otherwise.
##
## @code{@var{TF} = issortedrows (@var{D}, @var{col})} returns a logical
## scalar @var{TF}, which is @qcode{true}, if the duration array @var{D}
## is sorted according to the columns specified by the vector @var{col}, and
## @qcode{false} otherwise. @var{col} must explicitly contain non-zero
## integers whose absolute values index existing columns in @var{D}.
## Positive elements sort the corresponding columns in ascending order,
## while negative elements sort the corresponding columns in descending
## order.
##
## @code{@var{TF} = issortedrows (@var{D}, @var{direction})} checks if the
## rows in @var{D} are sorted according to the specified direction, which
## can be one of the following options:
##
## @itemize
## @item @qcode{'ascend'}, which is the default, checks is elements are in
## ascending order.
## @item @qcode{'descend'} checks if elements are in descending order.
## @item @qcode{'monotonic'} checks if elements are either in ascending or
## descending order.
## @item @qcode{'strictascend'} checks if elements are in ascending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictdescend'} checks if elements are in descending order
## and there are no duplicate or undefined elements.
## @item @qcode{'strictmonotonic'} checks if elements are either in
## ascending or descending order and there are no duplicate or undefined
## elements.
## @end itemize
##
## Alternatively, @var{direction} can be a cell array of character
## vectors specifying the sorting direction for each individual column of
## @var{D}, in which case the number of elements in @var{direction} must
## equal the number of columns in @var{D}.
##
## @code{@var{TF} = issortedrows (@var{D}, @var{col}, @var{direction})}
## checks if the rows in the duration array @var{D} are sorted according
## to the columns specified in @var{col} using the corresponding sorting
## direction specified in @var{direction}. In this case, the sign of the
## values in @var{col} is ignored. @var{col} and @var{direction} must have
## the same length, but not necessarily the same number of elements as the
## columns in @var{D}.
##
## @code{@var{TF} = issortedrows (@dots{}, @qcode{'MissingPlacement'},
## @var{MP})} specifies where missing elements (@qcode{}) are
## placed with one of the following options specified in @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{@var{TF} = issortedrows (@dots{}, @qcode{'ComparisonMethod'},
## @var{CM})} specifies the comparison method for determining the order of
## elements with one of following options specified in @var{CM}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, sorts by @code{real (A)}.
## @item @qcode{'real'} sorts by @code{real (A)}.
## @item @qcode{'abs'} sorts by @code{abs (A)}.
## @end itemize
##
## @end deftypefn
function TF = issortedrows (this, varargin)
## Single input argument
if (nargin == 1)
TF = isequaln (this, sortrows (this));
return;
endif
## Force strings to character vectors or cell arrays of character vectors
[varargin{:}] = convertStringsToChars (varargin{:});
## Get valid direction(s) from input argument list
valid = {'ascend', 'descend', 'monotonic', 'strictascend', ...
'strictdescend', 'strictmonotonic'};
fcn = @(x) (ischar (x) && ismember (x, valid)) || iscellstr (x);
cid = cellfun (fcn, varargin);
if (any (cid))
direction = cellstr (varargin{cid});
## Check for valid type of directions in cellstring
if (! all (cellfun (@(x) ismember (x, valid), direction)))
error ("duration.issortedrows: invalid DIRECTION value.");
endif
## Handle non-strict modes first
if (all (cellfun (@(x) ismember (x, {'ascend', 'descend'}), direction)))
TF = isequaln (this, sortrows (this, varargin{:}));
return;
endif
simple_types = {'ascend', 'descend', 'monotonic'};
if (all (cellfun (@(x) ismember (x, simple_types), direction)))
idx = strcmp (direction, 'monotonic');
direction{idx} = 'ascend';
varargin{cid} = direction;
TF = isequaln (this, sortrows (this, varargin{:}));
if (TF)
return;
endif
direction{idx} = 'descend';
varargin{cid} = direction;
TF = isequaln (this, sortrows (this, varargin{:}));
return;
endif
## Handle strict modes. Determine the sort-key column order and the
## sort position holding the first strict direction, then derive the
## prefix (the columns sorted up to and including that position, on
## which the duplicate test operates) and the binding strict column
## (the single column on which the missing test operates). A missing
## value in the binding column, or two consecutive sorted rows equal
## across the prefix columns, rules out a strict ordering; strict
## positions after the first are subsumed by it.
strict_types = {'strictascend', 'strictdescend', 'strictmonotonic'};
sflag = cellfun (@(x) ismember (x, strict_types), direction);
nc = size (this, 2);
nummask = cellfun (@isnumeric, varargin);
if (any (nummask))
col = varargin{nummask};
ocols = abs (col(:)');
if (isscalar (direction))
sflag = repmat (sflag, 1, numel (col));
elseif (numel (direction) != numel (col))
error ("duration.issortedrows: COL and DIRECTION mismatch.");
endif
else
ocols = 1:nc;
if (isscalar (direction))
sflag = repmat (sflag, 1, nc);
endif
endif
K = find (sflag, 1);
prefix = ocols(1:K);
bindcol = ocols(K);
## A missing value in the binding strict column rules out strictness.
if (any (isnan (this.Days(:,bindcol)), 'all'))
TF = false;
return;
endif
## Replace strict modes with their plain counterparts for the sort.
direction = strrep (direction, 'strict', '');
varargin{cid} = direction;
if (all (cellfun (@(x) ismember (x, {'ascend', 'descend'}), direction)))
sorted = sortrows (this, varargin{:});
## No two consecutive rows may tie across the prefix columns.
tmpcol = sorted.Days(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
else # a 'monotonic' position also exists
idx = strcmp (direction, 'monotonic');
direction(idx) = {'ascend'};
varargin{cid} = direction;
sorted = sortrows (this, varargin{:});
tmpcol = sorted.Days(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
if (TF)
return;
endif
direction(idx) = {'descend'};
varargin{cid} = direction;
sorted = sortrows (this, varargin{:});
tmpcol = sorted.Days(:, prefix);
if (any (all (diff (tmpcol, 1, 1) == 0, 2)))
TF = false;
return;
endif
TF = isequaln (this, sorted);
endif
else
## No DIRECTION input argument
TF = isequaln (this, sortrows (this, varargin{:}));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} isvector (@var{D})
##
## Return true if duration array is a vector.
##
## @code{@var{TF} = isvector (@var{D})} returns a logical scalar @var{TF},
## which is @qcode{true} if the duration array @var{D} is a vector and
## @qcode{false} otherwise. A vector is a 2-D array for which one of the
## dimensions is equal to 1 (either @math{1*N} or @math{N*1}). By
## definition, a scalar is also a vector.
##
## @end deftypefn
function TF = isvector (this)
TF = isvector (this.Days);
endfunction
endmethods
################################################################################
## ** Relational Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'eq' 'ge' 'gt' 'le' ##
## 'lt' 'ne' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} eq (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = eq (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} == @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## and @var{B} are equal and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = eq (A, B)
[A, B] = promote (A, B);
TF = A.Days == B.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} ge (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = ge (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} >= @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## are greater than or equal to @var{B} and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = ge (A, B)
[A, B] = promote (A, B);
TF = A.Days >= B.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} gt (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = gt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} > @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## are greater than @var{B} and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = gt (A, B)
[A, B] = promote (A, B);
TF = A.Days > B.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} le (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = le (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} <= @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## are less than or equal to @var{B} and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = le (A, B)
[A, B] = promote (A, B);
TF = A.Days <= B.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} lt (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = lt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} < @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## are less than @var{B} and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = lt (A, B)
[A, B] = promote (A, B);
TF = A.Days < B.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{TF} =} ne (@var{A}, @var{B})
##
## Equality for duration arrays.
##
## @code{@var{TF} = ne (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} != @var{B}} and returns a logical array whose
## elements set to @qcode{true} where the corresponding elements of @var{A}
## and @var{B} are not equal and set to @qcode{false} otherwise.
##
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a character vector, a cell array
## of character vectors, or a string array representing duration strings or
## a numeric array representing days.
##
## @end deftypefn
function TF = ne (A, B)
[A, B] = promote (A, B);
TF = A.Days != B.Days;
endfunction
endmethods
################################################################################
## ** Mathematical Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'abs' 'plus' 'uplus' 'minus' ##
## 'uminus' 'times' 'mtimes' 'ldivide' ##
## 'rdivide' 'colon' 'linspace' 'diff' ##
## 'sum' 'cumsum' 'min' 'cummin' ##
## 'max' 'cummax' 'floor' 'ceil' ##
## 'round' 'sign' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} abs (@var{A})
##
## Absolute value of the elements of a duration array.
##
## @code{@var{B} = abs (@var{A})} returns the absolute value of each element
## in the duration array @var{A}. The returned duration array @var{B} has
## the same size as the input array @var{A}.
##
## @end deftypefn
function this = abs (this)
this.Days = abs (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} plus (@var{A}, @var{B})
##
## Addition for duration arrays.
##
## @code{@var{C} = plus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} + @var{B}} and returns the sum of @var{A} and
## @var{B} by adding the corresponding elements. @var{A} and @var{B} must
## be size compatible, which translates to they can be the same size, one
## can be scalar, or for every dimension, their dimension sizes must be
## equal or one of them must be 1. The size of @var{C} is determined by the
## size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a numeric array in which case its
## elements are treated as a number of 24-hour days. If the second argument
## @var{B} is a calendarDuration arrays, then the returned array @var{C} is
## also a calendarDuration array.
##
## @end deftypefn
function C = plus (A, B)
## Overload methods for certain data types
if (isa (B, 'datetime'))
C = B + A;
return;
endif
if (isa (B, 'calendarDuration'))
C = B + A;
return;
endif
if (isa (A, 'duration') && isa (B, 'duration'))
C = A;
C.Days = A.Days + B.Days;
elseif (isnumeric (A))
C = B;
C.Days = double (A) + B.Days;
elseif (isnumeric (B))
C = A;
C.Days = A.Days + double (B);
else
error (strcat ("duration: addition is not defined between", ...
" '%s' and '%s' arrays."), class (A), class (B));
endif
C = fix_zero_precision (C);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} uplus (@var{A})
##
## Unary plus for duration arrays.
##
## @code{@var{B} = uplus (@var{A})} is the equivalent of the syntax
## @code{@var{B} = + @var{A}} and returns the input array unaltered.
##
## @end deftypefn
function this = uplus (this)
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} minus (@var{A}, @var{B})
##
## Subtraction for duration arrays.
##
## @code{@var{C} = minus (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} - @var{B}} and returns the subtraction of @var{B}
## from @var{A} by subtracting the corresponding elements. @var{A} and
## @var{B} must be size compatible, which translates to they can be the same
## size, one can be scalar, or for every dimension, their dimension sizes
## must be equal or one of them must be 1. The size of @var{C} is
## determined by the size compatibility of @var{A} and @var{B}.
##
## One of the input arguments can also be a numeric array in which case its
## elements are treated as a number of 24-hour days. If the second argument
## @var{B} is a calendarDuration arrays, then the returned array @var{C} is
## also a calendarDuration array.
##
## @end deftypefn
function C = minus (A, B)
## Overload methods for certain data types
if (isa (B, 'calendarDuration'))
C = -B + A;
return;
endif
if (isa (A, 'duration') && isa (B, 'duration'))
C = A;
C.Days = A.Days - B.Days;
elseif (isnumeric (A))
C = B;
C.Days = double (A) - B.Days;
elseif (isnumeric (B))
C = A;
C.Days = A.Days - double (B);
else
error (strcat ("duration: subtraction is not defined between", ...
" '%s' and '%s' arrays."), class (A), class (B));
endif
C = fix_zero_precision (C);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} uminus (@var{A})
##
## Unary minus for duration arrays.
##
## @code{@var{B} = uminus (@var{A})} is the equivalent of the syntax
## @code{@var{B} = - @var{A}} and returns the input array with its elements
## negated.
##
## @end deftypefn
function this = uminus (this)
this.Days = - this.Days;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} times (@var{A}, @var{B})
##
## Element-wise multiplication for duration arrays.
##
## @code{@var{C} = times (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{C} = @var{A} .* @var{B}} and returns the element-by-element
## multiplication product between the corresponding elements of input arrays
## @var{A} and @var{B}, one of which must be a numeric array and the other a
## duration array.
##
## @var{A} and @var{B} must be size compatible, which translates to they
## can be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## @end deftypefn
function C = times (A, B)
if (isa (A, 'duration') && isnumeric (B))
C = A;
C.Days = A.Days .* double (B);
elseif (isnumeric (A) && isa (B, 'duration'))
C = B;
C.Days = double (A) .* B.Days;
else
error (strcat ("duration: multiplication is not defined between", ...
" '%s' and '%s' arrays."), class (A), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} times (@var{A}, @var{B})
##
## Matrix multiplication for duration arrays.
##
## @code{@var{C} = mtimes (@var{A}, @var{B})} is the equivalent of the
## syntax @code{@var{C} = @var{A} * @var{B}} and returns the matrix
## multiplication product of input arrays @var{A} and @var{B}, one of which
## must be a numeric array and the other a duration array.
##
## The columns of @var{A} must equal the rows of @var{B} and the size of
## @var{C} is determined by the rows of @var{A} and the columns of @var{B}.
##
## @end deftypefn
function C = mtimes (A, B)
if (isa (A, 'duration') && isnumeric (B))
C = A;
C.Days = A.Days * double (B);
elseif (isnumeric (A) && isa (B, 'duration'))
C = B;
C.Days = double (A) * B.Days;
else
error (strcat ("duration: matrix multiplication is not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} ldivide (@var{A}, @var{B})
##
## Element-wise left division for duration arrays.
##
## @code{@var{C} = ldivide (@var{A}, @var{B})} is the equivalent of the
## syntax @code{@var{C} = @var{A} .\ @var{B}} and returns the element-wise
## division of the duration array @var{B} by the corresponding elements of
## input array @var{A}, which can either be a duration or a numeric array.
## If @var{A} is a duration array, then @var{C} is a double numeric array.
## If @var{A} is a numeric array, then @var{C} is a duration array.
##
## @var{A} and @var{B} must be size compatible, which translates to they
## can be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## @end deftypefn
function C = ldivide (A, B)
if (! isa (B, 'duration'))
error (strcat ("duration: right-hand side must be a duration", ...
" array for left division: got '%s'"), class (B));
endif
if (isa (A, 'duration'))
C = A.Days .\ B.Days;
elseif (isnumeric (A))
C = B;
C.Days = double (A) .\ B.Days;
C = fix_zero_precision (C);
else
error (strcat ("duration: left division is not defined", ...
" between '%s' and 'duration' arrays."), class (A));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} rdivide (@var{A}, @var{B})
##
## Element-wise right division for duration arrays.
##
## @code{@var{C} = rdivide (@var{A}, @var{B})} is the equivalent of the
## syntax @code{@var{C} = @var{A} ./ @var{B}} and returns the element-wise
## division of the duration array @var{A} by the corresponding elements of
## input array @var{B}, which can either be a duration or a numeric array.
## If @var{B} is a duration array, then @var{C} is a double numeric array.
## If @var{B} is a numeric array, then @var{C} is a duration array.
##
## @var{A} and @var{B} must be size compatible, which translates to they
## can be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## @end deftypefn
function C = rdivide (A, B)
if (! isa (A, 'duration'))
error (strcat ("duration: left-hand side must be a duration", ...
" array for right division: got '%s'"), class (A));
endif
if (isa (B, 'duration'))
C = A.Days ./ B.Days;
elseif (isnumeric (B))
C = A;
C.Days = A.Days ./ double (B);
C = fix_zero_precision (C);
else
error (strcat ("duration: right division is not defined", ...
" between 'duration' and '%s' arrays."), class (B));
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{R} =} colon (@var{Base}, @var{Limit})
## @deftypefnx {duration} {@var{R} =} colon (@var{Base}, @var{Increment}, @var{Limit})
##
## Create a range of durations in a vector.
##
## @code{@var{R} = colon (@var{Base}, @var{Limit})} is the equivalent of the
## syntax @code{@var{C} = @var{Base}:@var{Limit}} and returns a duration
## vector in the range from @var{Base} to @var{Limit} incremented by 24-hour
## days.
##
## @code{@var{R} = colon (@var{Base}, @var{Increment}, @var{Limit})} is
## equivalent to @code{@var{C} = @var{Base}:@var{Increment}:@var{Limit}}.
## dimension sizes must be equal or one of them must be 1. The size of
## @var{C} is determined by the size compatibility of @var{A} and @var{B}.
##
## As long as one of the inputs is a duration scalar, the following types
## are additionally supported for the remaining input arguments:
##
## @itemize
## @item numeric scalar (24-hour day)
## @item character vector (duration string)
## @item cellstr scalar (duration string)
## @item string scalar (duration string)
## @end itemize
##
## @end deftypefn
function R = colon (varargin)
if (nargin < 2 || nargin > 3)
error ("duration.colon: invalid number of input arguments.");
endif
idx = find (cellfun ('isduration', varargin), 1);
R = varargin{idx};
if (nargin == 2)
[from, to] = promote (varargin{:});
if (! isscalar (from) || ! isscalar (to))
error ("duration.colon: input arguments must be scalars.");
endif
increment = days (1);
else
[from, increment, to] = promote (varargin{:});
if (! isscalar (from) || ! isscalar (increment) || ! isscalar (to))
error ("duration.colon: input arguments must be scalars.");
endif
endif
R.Days = from.Days:increment.Days:to.Days;
R = fix_zero_precision (R);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{R} =} linspace (@var{Start}, @var{End})
## @deftypefnx {duration} {@var{R} =} linspace (@var{Start}, @var{End}, @var{N})
##
## Create linearly spaced duration elements.
##
## @code{@var{R} = linspace (@var{Start}, @var{End})} returns 100 linearly
## spaced elements between @var{Start} and @var{End}. If @var{Start} and
## @var{End} are scalars, then @var{R} is a vector. If one or both inputs
## are vectors, then @var{R} is a matrix where each row is an independent
## sequence between @code{@var{Start}(idx_N)} and @code{@var{End}(idx_N)}.
##
## @code{@var{R} = linspace (@var{Start}, @var{End}, @var{N})} specifies the
## number (default is 100) of equally spaced elements between @var{Start}
## and @var{End}. If @var{N} is not an integer value, then it is floored
## to the nearest integer. If @var{N} is zero or negative, then an empty
## matrix is returned. If @var{N} is one, then @var{End} is returned.
## If @var{N} greater than one, then @var{Start} and @var{End} are always
## included in the range.
##
## Either @var{Start} or @var{End} input arguments can also be one of the
## following types:
##
## @itemize
## @item numeric scalar or vector (24-hour days)
## @item character vector (duration string)
## @item cellstr scalar or vector (duration strings)
## @item string scalar or vector (duration strings)
## @end itemize
##
## @end deftypefn
function R = linspace (A, B, n = 100)
if (nargin < 2)
error ("duration.linspace: too few input arguments.");
endif
if (isduration (A))
R = A;
else
R = B;
endif
[A, B] = promote (A, B);
R.Days = linspace (A.Days, B.Days, n);
R = fix_zero_precision (R);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{DT} =} diff (@var{D})
## @deftypefnx {duration} {@var{DT} =} diff (@var{D}, @var{K})
## @deftypefnx {duration} {@var{DT} =} diff (@var{D}, @var{K}, @var{DIM})
##
## Compute differences between adjacent elements in a duration array.
##
## This method overloads the core @code{diff} function for duration arrays.
## The functionality is identical to core @code{diff} function. Type
## @code{help diff} for more information.
##
## @end deftypefn
function this = diff (this, varargin)
this.Days = diff (this.Days, varargin{:});
this = fix_zero_precision (this);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{S} =} sum (@var{D})
## @deftypefnx {duration} {@var{S} =} sum (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{S} =} sum (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{S} =} sum (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{S} =} sum (@dots{}, @var{nanflag})
##
## Compute the sum of the elements of a duration array.
##
## This method overloads the core @code{sum} function for duration arrays.
## The functionality is identical to core @code{sum} function. Type
## @code{help sum} for more information.
##
## @end deftypefn
function this = sum (this, varargin)
## Force strings to character vectors or cell arrays of character vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
this.Days = sum (this.Days, varargin{:});
this = fix_zero_precision (this);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{CS} =} cumsum (@var{D})
## @deftypefnx {duration} {@var{CS} =} cumsum (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{CS} =} cumsum (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{CS} =} cumsum (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{CS} =} cumsum (@dots{}, @var{direction})
## @deftypefnx {duration} {@var{CS} =} cumsum (@dots{}, @var{nanflag})
##
## Compute the cumulative sum of the elements of a duration array.
##
## This method overloads the core @code{cumsum} function for duration
## arrays. The functionality is identical to core @code{cumsum} function.
## Type @code{help cumsum} for more information.
##
## @end deftypefn
function this = cumsum (this, varargin)
## Force strings to character vectors or cell arrays of character vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
this.Days = cumsum (this.Days, varargin{:});
this = fix_zero_precision (this);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} min (@var{D})
## @deftypefnx {duration} {@var{M} =} min (@var{D}, @qcode{[]}, @var{dim})
## @deftypefnx {duration} {@var{M} =} min (@var{D}, @qcode{[]}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} min (@var{D}, @qcode{[]}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} min (@var{D}, @qcode{[]}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} min (@var{D}, @qcode{[]}, @dots{}, @var{nanflag})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} min (@dots{})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} min (@dots{}, @qcode{'linear'})
## @deftypefnx {duration} {@var{M} =} min (@var{D1}, @var{D2})
## @deftypefnx {duration} {@var{M} =} min (@var{D1}, @var{D2}, @var{nanflag})
## @deftypefnx {duration} {@dots{} =} min (@dots{}, @qcode{'ComparisonMethod'}, @var{method})
##
## Find minimum values in duration arrays.
##
## This method overloads the core @code{min} function for duration
## arrays. The functionality is identical to core @code{min} function.
## Type @code{help min} for more information.
##
## @end deftypefn
function varargout = min (D, varargin)
M = D;
if (isempty (varargin))
if (nargout > 1)
[M.Days, varargout{2}] = min (D.Days);
else
M.Days = min (D.Days);
endif
varargout{1} = M;
else
## Force strings to character vectors or cell arrays of character
## vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
## Second argument is a duration
if (isduration (varargin{1}))
D2 = varargin{1};
varargin(1) = [];
## Make sure first argument is also a duration
if (! isduration (D))
D = promote (D);
M = D2;
endif
M.Days = min (D.Days, D2.Days, varargin{:});
varargout{1} = M;
else
if (nargout > 1)
[M.Days, varargout{2}] = min (D.Days, varargin{:});
else
M.Days = min (D.Days, varargin{:});
endif
varargout{1} = M;
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} cummin (@var{D})
## @deftypefnx {duration} {@var{M} =} cummin (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{M} =} cummin (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} cummin (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} cummin (@qcode{[]}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} cummin (@qcode{[]}, @var{direction})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} cummin (@dots{})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} cummin (@dots{}, @qcode{'linear'})
## @deftypefnx {duration} {@dots{} =} cummin (@dots{}, @qcode{'ComparisonMethod'}, @var{method})
##
## Return the cumulative minimum values in duration arrays.
##
## This method overloads the core @code{cummin} function for duration
## arrays. The functionality is identical to core @code{cummin} function.
## Type @code{help cummin} for more information.
##
## @end deftypefn
function varargout = cummin (this, varargin)
if (isempty (varargin))
if (nargout > 1)
[this.Days, varargout{2}] = cummin (this.Days);
else
this.Days = cummin (this.Days);
endif
varargout{1} = this;
else
## Force strings to character vectors or cell arrays of character
## vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
if (nargout > 1)
[this.Days, varargout{2}] = cummin (this.Days, varargin{:});
else
this.Days = cummin (this.Days, varargin{:});
endif
varargout{1} = this;
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} max (@var{D})
## @deftypefnx {duration} {@var{M} =} max (@var{D}, @qcode{[]}, @var{dim})
## @deftypefnx {duration} {@var{M} =} max (@var{D}, @qcode{[]}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} max (@var{D}, @qcode{[]}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} max (@var{D}, @qcode{[]}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} max (@var{D}, @qcode{[]}, @dots{}, @var{nanflag})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} max (@dots{})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} max (@dots{}, @qcode{'linear'})
## @deftypefnx {duration} {@var{M} =} max (@var{D1}, @var{D2})
## @deftypefnx {duration} {@var{M} =} max (@var{D1}, @var{D2}, @var{nanflag})
## @deftypefnx {duration} {@dots{} =} max (@dots{}, @qcode{'ComparisonMethod'}, @var{method})
##
## Find maximum values in duration arrays.
##
## This method overloads the core @code{max} function for duration
## arrays. The functionality is identical to core @code{max} function.
## Type @code{help max} for more information.
##
## @end deftypefn
function varargout = max (D, varargin)
M = D;
if (isempty (varargin))
if (nargout > 1)
[M.Days, varargout{2}] = max (D.Days);
else
M.Days = max (D.Days);
endif
varargout{1} = M;
else
## Force strings to character vectors or cell arrays of character
## vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
## Second argument is a duration
if (isduration (varargin{1}))
D2 = varargin{1};
varargin(1) = [];
## Make sure first argument is also a duration
if (! isduration (D))
D = promote (D);
M = D2;
endif
M.Days = max (D.Days, D2.Days, varargin{:});
varargout{1} = M;
else
if (nargout > 1)
[M.Days, varargout{2}] = max (D.Days, varargin{:});
else
M.Days = max (D.Days, varargin{:});
endif
varargout{1} = M;
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} cummax (@var{D})
## @deftypefnx {duration} {@var{M} =} cummax (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{M} =} cummax (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} cummax (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} cummax (@qcode{[]}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} cummax (@qcode{[]}, @var{direction})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} cummax (@dots{})
## @deftypefnx {duration} {[@var{M}, @var{index}] =} cummax (@dots{}, @qcode{'linear'})
## @deftypefnx {duration} {@dots{} =} cummax (@dots{}, @qcode{'ComparisonMethod'}, @var{method})
##
## Return the cumulative maximum values in duration arrays.
##
## This method overloads the core @code{cummax} function for duration
## arrays. The functionality is identical to core @code{cummax} function.
## Type @code{help cummax} for more information.
##
## @end deftypefn
function varargout = cummax (this, varargin)
if (isempty (varargin))
if (nargout > 1)
[this.Days, varargout{2}] = cummax (this.Days);
else
this.Days = cummax (this.Days);
endif
varargout{1} = this;
else
## Force strings to character vectors or cell arrays of character
## vectors
if (any (cellfun ('isstring', varargin)))
[varargin{:}] = convertStringsToChars (varargin{:});
endif
if (nargout > 1)
[this.Days, varargout{2}] = cummax (this.Days, varargin{:});
else
this.Days = cummax (this.Days, varargin{:});
endif
varargout{1} = this;
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{Y} =} floor (@var{D})
## @deftypefnx {duration} {@var{Y} =} floor (@var{D}, @var{unit})
##
## Round toward negative infinity for duration arrays.
##
## @code{@var{Y} = floor (@var{D})} rounds each element of the duration
## array @var{D} to the largest integer number of seconds not greater than
## that element.
##
## @code{@var{Y} = floor (@var{D}, @var{unit})} rounds each element of the
## duration array @var{D} to the largest integer number of the specified
## unit of time not greater than that element. @var{unit} must be one of
## the following values:
##
## @itemize
## @item @qcode{'seconds'} (default)
## @item @qcode{'minutes'}
## @item @qcode{'hours'}
## @item @qcode{'days'}
## @item @qcode{'years'}
## @end itemize
##
## @end deftypefn
function this = floor (this, unit = 'seconds')
if (strcmpi (unit, 'seconds'))
this.Days = floor (seconds (this)) / 86400;
elseif (strcmpi (unit, 'minutes'))
this.Days = floor (minutes (this)) / 1440;
elseif (strcmpi (unit, 'hours'))
this.Days = floor (hours (this)) / 24;
elseif (strcmpi (unit, 'days'))
this.Days = floor (this.Days);
elseif (strcmpi (unit, 'years'))
this.Days = floor (years (this)) * 365.2425;
else
error ("duration.floor: invalid UNIT.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{Y} =} ceil (@var{D})
## @deftypefnx {duration} {@var{Y} =} ceil (@var{D}, @var{unit})
##
## Round toward negative infinity for duration arrays.
##
## @code{@var{Y} = ceil (@var{D})} rounds each element of the duration
## array @var{D} to the smallest integer number of seconds not less than
## that element.
##
## @code{@var{Y} = ceil (@var{D}, @var{unit})} rounds each element of the
## duration array @var{D} to the smallest integer number of the specified
## unit of time not less than that element. @var{unit} must be one of the
## following values:
##
## @itemize
## @item @qcode{'seconds'} (default)
## @item @qcode{'minutes'}
## @item @qcode{'hours'}
## @item @qcode{'days'}
## @item @qcode{'years'}
## @end itemize
##
## @end deftypefn
function this = ceil (this, unit = 'seconds')
if (strcmpi (unit, 'seconds'))
this.Days = ceil (seconds (this)) / 86400;
elseif (strcmpi (unit, 'minutes'))
this.Days = ceil (minutes (this)) / 1440;
elseif (strcmpi (unit, 'hours'))
this.Days = ceil (hours (this)) / 24;
elseif (strcmpi (unit, 'days'))
this.Days = ceil (this.Days);
elseif (strcmpi (unit, 'years'))
this.Days = ceil (years (this)) * 365.2425;
else
error ("duration.ceil: invalid UNIT.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{Y} =} round (@var{D})
## @deftypefnx {duration} {@var{Y} =} round (@var{D}, @var{unit})
##
## Round to the nearest integer time unit for duration arrays.
##
## @code{@var{Y} = round (@var{D})} rounds each element of the duration
## array @var{D} to the nearest integer number of seconds to that element.
## In case of a tie, return the one further away from zero.
##
## @code{@var{Y} = round (@var{D}, @var{unit})} rounds each element of the
## duration array @var{D} to the nearest integer number of the specified
## unit of time to that element. @var{unit} must be one of the following
## values:
##
## @itemize
## @item @qcode{'seconds'} (default)
## @item @qcode{'minutes'}
## @item @qcode{'hours'}
## @item @qcode{'days'}
## @item @qcode{'years'}
## @end itemize
##
## @end deftypefn
function this = round (this, unit = 'seconds')
if (strcmpi (unit, 'seconds'))
this.Days = round (seconds (this)) / 86400;
elseif (strcmpi (unit, 'minutes'))
this.Days = round (minutes (this)) / 1440;
elseif (strcmpi (unit, 'hours'))
this.Days = round (hours (this)) / 24;
elseif (strcmpi (unit, 'days'))
this.Days = round (this.Days);
elseif (strcmpi (unit, 'years'))
this.Days = round (years (this)) * 365.2425;
else
error ("duration.round: invalid UNIT.");
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{out} =} sign (@var{D})
## @deftypefnx {duration} {@var{out} =} sign (@var{D}, @var{unit})
##
## Compute the signum function for duration arrays.
##
## @code{@var{out} = sign (@var{D})} returns an array of doubles, @var{out},
## the same size as the duration array @var{D}, where each element has one
## following values:
##
## @itemize
## @item @qcode{1} if the corresponding element of D is greater than 0.
## @item @qcode{0} if the corresponding element of D is equal to 0.
## @item @qcode{-1} if the corresponding element of D is less than 0.
## @item @qcode{NaN} if the corresponding element of D is a missing value.
## @end itemize
##
## @end deftypefn
function out = sign (this)
out = sign (this.Days);
endfunction
endmethods
################################################################################
## ** Statistical Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'bounds' 'center' 'histc' 'iqr' ##
## 'kurtosis' 'mad' 'mape' 'mean' ##
## 'median' 'mode' 'prctile' 'quantile' ##
## 'range' 'rmse' 'skewness' 'std' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {[@var{s}, @var{l}] =} bounds (@var{D})
## @deftypefnx {duration} {[@var{s}, @var{l}] =} bounds (@var{D}, @var{dim})
## @deftypefnx {duration} {[@var{s}, @var{l}] =} bounds (@var{D}, @var{vecdim})
## @deftypefnx {duration} {[@var{s}, @var{l}] =} bounds (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {[@var{s}, @var{l}] =} bounds (@dots{}, @var{nanflag})
##
## Return the smallest and largest values of a duration array.
##
## This method is a specialization of the core @code{bounds} function for
## duration arrays. The functionality is identical to core @code{bounds}
## function. Type @code{help bounds} for more information.
##
## @end deftypefn
function [s, l] = bounds (this, varargin)
if (nargin < 1 || nargin > 3)
error ("duration.bounds: invalid number of input arguments.");
endif
if (isempty (varargin))
s = min (this);
l = max (this);
else
s = min (this, [], varargin{:});
l = max (this, [], varargin{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} center (@var{D})
## @deftypefnx {duration} {@var{C} =} center (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{C} =} center (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{C} =} center (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{C} =} center (@dots{}, @var{nanflag})
##
## Center values in a duration array.
##
## This method overloads the core @code{center} function for duration
## arrays. The functionality is identical to core @code{center} function.
## Type @code{help center} for more information.
##
## @end deftypefn
function this = center (this, varargin)
this.Days = center (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{n} =} histc (@var{D}, @var{edges})
## @deftypefnx {duration} {@var{n} =} histc (@var{D}, @var{edges}, @var{dim})
## @deftypefnx {duration} {[@var{n}, @var{idx}] =} histc (@dots{})
##
## Compute histogram counts in a duration array.
##
## This method overloads the core @code{histc} function for duration
## arrays. The functionality is identical to core @code{histc} function.
## Type @code{help histc} for more information.
##
## @end deftypefn
function varargout = histc (D, varargin)
if (nargout > 1)
[varargout{1}, varargout{2}] = histc (D.Days, varargin{:});
else
varargout{1} = histc (D.Days, varargin{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{r} =} iqr (@var{D})
## @deftypefnx {duration} {@var{r} =} iqr (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{r} =} iqr (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{r} =} iqr (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {[@var{r}, @var{q}] =} iqr (@dots{})
##
## Compute the interquartile range of a duration array.
##
## This method overloads the core @code{iqr} function for duration arrays.
## The functionality is identical to core @code{iqr} function.
## Type @code{help iqr} for more information.
##
## @end deftypefn
function varargout = iqr (this, varargin)
if (nargout > 1)
[this.Days, varargout{2}] = iqr (this.Days, varargin{:});
else
this.Days = iqr (this.Days, varargin{:});
endif
varargout{1} = this;
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{k} =} kurtosis (@var{D})
## @deftypefnx {duration} {@var{k} =} kurtosis (@var{D}, @var{flag})
## @deftypefnx {duration} {@var{k} =} kurtosis (@var{D}, @var{flag}, @var{dim})
## @deftypefnx {duration} {@var{k} =} kurtosis (@var{D}, @var{flag}, @var{vecdim})
## @deftypefnx {duration} {@var{k} =} kurtosis (@var{D}, @var{flag}, @qcode{'all'})
##
## Compute the sample kurtosis of a duration array.
##
## This method overloads the core @code{kurtosis} function for duration
## arrays. The functionality is identical to core @code{kurtosis} function.
## Type @code{help kurtosis} for more information.
##
## Note that kurtosis is a dimensionless quantity Thus, the returned
## argument is a numeric array of double type and not a duration array.
##
## @end deftypefn
function k = kurtosis (D, varargin)
k = kurtosis (D.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} mad (@var{D})
## @deftypefnx {duration} {@var{M} =} mad (@var{D}, @var{opt})
## @deftypefnx {duration} {@var{M} =} mad (@var{D}, @var{opt}, @var{dim})
## @deftypefnx {duration} {@var{M} =} mad (@var{D}, @var{opt}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} mad (@var{D}, @var{opt}, @qcode{'all'})
##
## Compute the mean or median absolute deviation of a duration array.
##
## This method overloads the core @code{mad} function for duration arrays.
## The functionality is identical to core @code{mad} function.
## Type @code{help mad} for more information.
##
## @end deftypefn
function this = mad (this, varargin)
this.Days = mad (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{E} =} mape (@var{F}, @var{A})
## @deftypefnx {duration} {@var{E} =} mape (@var{F}, @var{A}, @var{dim})
## @deftypefnx {duration} {@var{E} =} mape (@var{F}, @var{A}, @var{vecdim})
## @deftypefnx {duration} {@var{E} =} mape (@var{F}, @var{A}, @qcode{'all'})
## @deftypefnx {duration} {@var{E} =} mape (@dots{}, @var{nanflag})
## @deftypefnx {duration} {@var{E} =} mape (@dots{}, @var{zeroflag})
## @deftypefnx {duration} {@var{E} =} mape (@dots{}, @qcode{'Weights'}, @var{W})
##
## Compute the mean absolute percentage error between duration arrays.
##
## This method overloads the core @code{mape} function for duration arrays.
## The functionality is identical to core @code{mape} function.
## Type @code{help mape} for more information.
##
## Note that MAPE is expressed as a percentage. Thus, the returned argument
## is a numeric array of double type and not a duration array. However,
## both @var{F} and @var{A} must be duration arrays.
##
## @end deftypefn
function E = mape (F, A, varargin)
if (! isduration (F) || ! isduration (A))
error ("duration.mape: both F and A must be duration arrays.");
endif
E = mape (F.Days, A.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} mean (@var{D})
## @deftypefnx {duration} {@var{M} =} mean (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{M} =} mean (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} mean (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} mean (@dots{}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} mean (@dots{}, @var{outtype})
## @deftypefnx {duration} {@var{M} =} mean (@dots{}, @qcode{'Weights'}, @var{W})
##
## Compute the mean of the elements of a duration array.
##
## This method overloads the core @code{mean} function for duration arrays.
## The functionality is identical to core @code{mean} function.
## Type @code{help mean} for more information.
##
## @end deftypefn
function this = mean (this, varargin)
this.Days = mean (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} median (@var{D})
## @deftypefnx {duration} {@var{M} =} median (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{M} =} median (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} median (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{M} =} median (@dots{}, @var{nanflag})
## @deftypefnx {duration} {@var{M} =} median (@dots{}, @var{outtype})
##
## Compute the median value of the elements of a duration array.
##
## This method overloads the core @code{median} function for duration
## arrays. The functionality is identical to core @code{median} function.
## Type @code{help median} for more information.
##
## @end deftypefn
function this = median (this, varargin)
this.Days = median (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{M} =} mode (@var{D})
## @deftypefnx {duration} {@var{M} =} mode (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{M} =} mode (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{M} =} mode (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {[@var{M}, @var{F}, @var{C}] =} mode (@dots{})
##
## Compute the most frequently occurring value in a duration array.
##
## This method overloads the core @code{mode} function for duration arrays.
## The functionality is identical to core @code{mode} function.
## Type @code{help mode} for more information.
##
## @end deftypefn
function [this, F, C] = mode (this, varargin)
[this.Days, F, C] = mode (this.Days, varargin{:});
if (nargout == 3)
C = cellfun ('days', C, 'UniformOutput', false);
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{Q} =} prctile (@var{D})
## @deftypefnx {duration} {@var{q} =} prctile (@var{D}, @var{p})
## @deftypefnx {duration} {@var{Q} =} prctile (@var{D}, @var{p}, @var{dim})
## @deftypefnx {duration} {@var{Q} =} prctile (@var{D}, @var{p}, @var{vecdim})
## @deftypefnx {duration} {@var{Q} =} prctile (@var{D}, @var{p}, @qcode{'all'})
## @deftypefnx {duration} {@var{Q} =} prctile (@var{D}, @var{p}, @dots{}, @var{method})
##
## Compute the percentiles of a duration array.
##
## This method overloads the core @code{prctile} function for duration
## arrays. The functionality is identical to core @code{prctile} function.
## Type @code{help prctile} for more information.
##
## @end deftypefn
function this = prctile (this, varargin)
this.Days = prctile (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{Q} =} quantile (@var{D})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @var{p})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @var{n})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @dots{}, @var{dim})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @dots{}, @var{vecdim})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @dots{}, @qcode{'all'})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @var{p}, @dots{}, @var{method})
## @deftypefnx {duration} {@var{Q} =} quantile (@var{D}, @var{n}, @dots{}, @var{method})
##
## Compute the quantiles of a duration array.
##
## This method overloads the core @code{quantile} function for duration
## arrays. The functionality is identical to core @code{quantile} function.
## Type @code{help quantile} for more information.
##
## @end deftypefn
function this = quantile (this, varargin)
this.Days = quantile (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{R} =} range (@var{D})
## @deftypefnx {duration} {@var{R} =} range (@var{D}, @var{dim})
## @deftypefnx {duration} {@var{R} =} range (@var{D}, @var{vecdim})
## @deftypefnx {duration} {@var{R} =} range (@var{D}, @qcode{'all'})
## @deftypefnx {duration} {@var{R} =} range (@dots{}, @var{nanflag})
##
## Compute the range of a duration array.
##
## This method overloads the core @code{range} function for duration arrays.
## The functionality is identical to core @code{range} function.
## Type @code{help range} for more information.
##
## @end deftypefn
function this = range (this, varargin)
this.Days = range (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{E} =} rmse (@var{F}, @var{A})
## @deftypefnx {duration} {@var{E} =} rmse (@var{F}, @var{A}, @var{dim})
## @deftypefnx {duration} {@var{E} =} rmse (@var{F}, @var{A}, @var{vecdim})
## @deftypefnx {duration} {@var{E} =} rmse (@var{F}, @var{A}, @qcode{'all'})
## @deftypefnx {duration} {@var{E} =} rmse (@dots{}, @var{nanflag})
## @deftypefnx {duration} {@var{E} =} rmse (@dots{}, @qcode{'Weights'}, @var{W})
##
## Compute the root mean squared error between duration arrays.
##
## This method overloads the core @code{rmse} function for duration arrays.
## The functionality is identical to core @code{rmse} function.
## Type @code{help rmse} for more information.
##
## @end deftypefn
function this = rmse (this, A, varargin)
if (! isduration (this) || ! isduration (A))
error ("duration.rmse: both F and A must be duration arrays.");
endif
this.Days = rmse (this.Days, A.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{y} =} skewness (@var{D})
## @deftypefnx {duration} {@var{y} =} skewness (@var{D}, @var{flag})
## @deftypefnx {duration} {@var{y} =} skewness (@var{D}, @var{flag}, @var{dim})
## @deftypefnx {duration} {@var{y} =} skewness (@var{D}, @var{flag}, @var{vecdim})
## @deftypefnx {duration} {@var{y} =} skewness (@var{D}, @var{flag}, @qcode{'all'})
##
## Compute the sample skewness of a duration array.
##
## This method overloads the core @code{skewness} function for duration
## arrays. The functionality is identical to core @code{skewness} function.
## Type @code{help skewness} for more information.
##
## Note that skewness is a dimensionless quantity Thus, the returned
## argument is a numeric array of double type and not a duration array.
##
## @end deftypefn
function y = skewness (D, varargin)
y = skewness (D.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{S} =} std (@var{D})
## @deftypefnx {duration} {@var{S} =} std (@var{D}, @var{w})
## @deftypefnx {duration} {@var{S} =} std (@var{D}, @var{w}, @var{dim})
## @deftypefnx {duration} {@var{S} =} std (@var{D}, @var{w}, @var{vecdim})
## @deftypefnx {duration} {@var{S} =} std (@var{D}, @var{w}, @qcode{'all'})
## @deftypefnx {duration} {@var{S} =} std (@dots{}, @var{nanflag})
## @deftypefnx {duration} {[@var{S}, @var{M}] =} std (@dots{})
##
## Compute the standard deviation of a duration array.
##
## This method overloads the core @code{std} function for duration arrays.
## The functionality is identical to core @code{std} function.
## Type @code{help std} for more information.
##
## @end deftypefn
function varargout = std (this, varargin)
if (nargout > 1)
M = this;
[this.Days, M.Days] = std (this.Days, varargin{:});
varargout{1} = this;
varargout{2} = M;
else
this.Days = std (this.Days, varargin{:});
varargout{1} = this;
endif
endfunction
endmethods
################################################################################
## ** Sort, Filter, and Set Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'sort' 'sortrows' 'unique' 'interp1' ##
## 'intersect' 'setdiff' 'setxor' 'union' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} sort (@var{A})
## @deftypefnx {duration} {@var{B} =} sort (@var{A}, @var{dim})
## @deftypefnx {duration} {@var{B} =} sort (@var{A}, @var{direction})
## @deftypefnx {duration} {@var{B} =} sort (@var{A}, @var{dim}, @var{direction})
## @deftypefnx {duration} {@var{B} =} sort (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {duration} {@var{B} =} sort (@dots{}, @qcode{'ComparisonMethod'}, @var{CM})
## @deftypefnx {duration} {[@var{B}, @var{index}] =} sort (@var{A}, @dots{})
##
## Sort elements in a duration array.
##
## @code{@var{B} = sort (@var{A})} sorts the duration array @var{A} in
## ascending order. If @var{A} is a matrix, @code{sort (@var{A})} sorts
## each column of @var{A} in ascending order. For multidimensional arrays,
## @code{mode (@var{A})} sorts along the first non-singleton dimension.
##
## @code{@var{B} = sort (@var{A}, @var{dim})} sorts along the dimension
## specified by @var{dim}.
##
## @code{@var{B} = sort (@var{A}, @var{direction})} also specifies the
## sorting direction, which can be either @qcode{'ascend'} (default) or
## @qcode{'descend'}.
##
## @code{@var{B} = sort (@dots{}, @qcode{'MissingPlacement'}, @var{MP})}
## specifies where to place the missing elements (@qcode{})
## returned in @var{B} with one of the following options specified in
## @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{@var{B} = sort (@dots{}, @qcode{'ComparisonMethod'}, @var{CM})}
## specifies the comparison method for determining the order of elements
## returned in @var{B} with one of following options:
##
## @itemize
## @item @qcode{'auto'}, which is the default, sorts by @code{real (A)}.
## @item @qcode{'real'} sorts by @code{real (A)}.
## @item @qcode{'abs'} sorts by @code{abs (A)}.
## @end itemize
##
## @code{[@var{B}, @var{index}] = sort (@var{A}, @dots{})} also returns a
## sorting index containing the original indices of the elements in the
## sorted array. @var{index} is the same size as @var{A} and it comprises
## indexing vectors oriented along the operating dimensions.
##
## @itemize
## @item If @var{A} is a vector, then @var{index} contains the original
## linear indices of the elements in the sorted vector @var{B} such that
## @code{@var{B} = @var{A}(@var{index})}.
## @item If @var{A} is an @math{M*N} matrix and @qcode{@var{dim} = 1}, then
## @var{index} contains the original row indices of the elements in the
## sorted vector @var{B} such that for @qcode{j = 1:N},
## @code{@var{B}(:,j) = @var{A}(@var{index}(:,j),j)}.
## @end itemize
##
## @end deftypefn
function [B, index] = sort (A, varargin)
## Parse and validate optional paired arguments
optNames = {'MissingPlacement', 'ComparisonMethod'};
dfValues = {'auto', 'auto'};
[MP, CM, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! ismember (MP, {'auto', 'first', 'last'}))
error ("duration.sort: invalid value for 'MissingPlacement'.");
endif
if (! ismember (CM, {'auto', 'real', 'abs'}))
error ("duration.sort: invalid value for 'ComparisonMethod'.");
endif
## Force strings to character vectors
[args{:}] = convertStringsToChars (args{:});
## Get direction
cid = cellfun (@ischar, args);
if (any (cid))
dir = args{cid};
else
dir = 'ascend';
endif
## Get operating dimension
szA = size (A);
cid = cellfun (@isnumeric, args);
if (any (cid))
dim = args{cid};
else
dim = find (szA != 1, 1);
if (isempty (dim)) # scalar
dim = 1;
endif
endif
## Apply comparison method (Octave specific)
data = A.Days;
if (strcmp (CM, 'abs'))
data = abs (data);
endif
## Special handling for missing elements when missing placement overrides
## default behavior (only if missing data actually exist).
is_nan = isnan (data);
if (any (is_nan, 'all'))
## FIX ME: this workaround will be removed once the 'sort' function
## in core Octave supports 'MissingPlacement' optional argument.
## This implementation fails the edge case where -Inf and -realmax
## elements are present along the operating dimension.
if ((strcmp (dir, 'ascend') && strcmp (MP, {'first'})) ||
(strcmp (dir, 'descend') && strcmp (MP, {'last'})))
## Convert missing values to -Inf so that they are placed
## appropriately according to 'MissingPlacement' specification.
## If -Inf values already exist in data, then convert them to the
## next smallest possible value
is_m_inf = data == -Inf;
if (any (is_m_inf, 'all'))
m_inf_rep = - realmax;
data(is_m_inf) = m_inf_rep;
endif
data(is_nan) = -Inf;
endif
endif
## Sort values
[~, index] = sort (data, args{:});
## Calculate linear index
n_dims = ndims (A);
dimarg = cell (1, n_dims);
for i = 1:n_dims
if (i == dim)
dimarg{i} = index;
else
dim_sz = szA(i);
tmpvec = ones (1, n_dims);
tmpvec(i) = dim_sz;
tmp_sz = szA;
tmp_sz(i) = 1;
dimarg{i} = repmat (reshape ([1:dim_sz], tmpvec), tmp_sz);
endif
endfor
## Return sorted duration array
B = subset (A, sub2ind (szA, dimarg{:}));
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} sortrows (@var{A})
## @deftypefnx {duration} {@var{B} =} sortrows (@var{A}, @var{col})
## @deftypefnx {duration} {@var{B} =} sortrows (@var{A}, @var{direction})
## @deftypefnx {duration} {@var{B} =} sortrows (@var{A}, @var{col}, @var{direction})
## @deftypefnx {duration} {@var{B} =} sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})
## @deftypefnx {duration} {[@var{B}, @var{index}] =} sortrows (@var{A}, @dots{})
##
## Sort rows in a duration array.
##
## @code{@var{B} = sortrows (@var{A})} sorts the rows of the 2-D duration
## array @var{A} in ascending order. The sorted array @var{B} has the same
## size as @var{A}.
##
## @code{@var{B} = sortrows (@var{A}, @var{col})} sorts @var{A} according to
## to the columns specified by the numeric vector @var{col}, which must
## explicitly contain non-zero integers whose absolute values index existing
## columns in @var{A}. Positive elements sort the corresponding columns in
## ascending order, while negative elements sort the corresponding columns
## in descending order.
##
## @code{@var{B} = sortrows (@var{A}, @var{direction})} also specifies the
## sorting direction, which can be either @qcode{'ascend'} (default) or
## @qcode{'descend'} applying to all columns in @var{A}. Alternatively,
## @var{direction} can be either a string array or a cell array of character
## vectors specifying the sorting direction for each individual column of
## @var{A}, in which case the number of elements in @var{direction} must
## equal the number of columns in @var{A}.
##
## @code{@var{B} = sortrows (@var{A}, @var{col}, @var{direction})} sorts the
## categorical array @var{A} according to the columns specified in @var{col}
## using the corresponding sorting direction specified in @var{direction}.
## In this case, the sign of the values in @var{col} is ignored. @var{col}
## and @var{direction} must have the same number of elements, but not
## necessarily equal to the columns of @var{A}.
##
## @code{@var{B} = sortrows (@dots{}, @qcode{'MissingPlacement'}, @var{MP})}
## specifies where to place the missing elements (@qcode{NaN}) returned in
## @var{B} with any of the following options specified in @var{MP}:
##
## @itemize
## @item @qcode{'auto'}, which is the default, places missing elements last
## for ascending sort and first for descending sort.
## @item @qcode{'first'} places missing elements first.
## @item @qcode{'last'} places missing elements last.
## @end itemize
##
## @code{[@var{B}, @var{index}] = sortrows (@var{A}, @dots{})} also returns
## an index vector containing the original row indices of @var{A} in the
## sorted matrix @var{B} such that @code{@var{B} = @var{A}(@var{index},:)}.
##
## @end deftypefn
function [B, index] = sortrows (A, varargin)
## Input array must be a matrix
if (ndims (A) != 2)
error ("duration.sortrows: A must be a 2-D matrix.");
endif
## Parse and validate optional paired arguments
optNames = {'MissingPlacement', 'ComparisonMethod'};
dfValues = {'auto', 'auto'};
[MP, CM, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! any (strcmp (MP, {'auto', 'first', 'last'})))
error ("duration.sortrows: invalid value for 'MissingPlacement'.");
endif
if (! any (strcmp (CM, {'auto', 'real', 'abs'})))
error ("duration.sortrows: invalid value for 'ComparisonMethod'.");
endif
## Parse COL / DIRECTION input
nc = size (A, 2);
col = [1:nc]; # default ascending direction
dir_flag = false;
if (numel (args) > 2)
error ("duration.sortrows: too many input arguments.");
endif
if (numel (args) > 0)
col = args{1};
if (isnumeric (col))
if (! isvector (col) || any (fix (col) != col) || any (col == 0))
error (strcat ("duration.sortrows: COL must be a vector", ...
" of nonzero integers indexing columns in A."));
endif
if (max (abs (col)) > nc)
error ("duration.sortrows: COL indexes non-existing column.");
endif
elseif (isvector (col) && (ischar (col) || iscellstr (col) ||
isa (col, 'string')))
direction = cellstr (col);
if (! all (ismember (direction, {'ascend', 'descend'})))
error (strcat ("duration.sortrows: DIRECTION input must", ...
" contain either 'ascend' or 'descend' values."));
endif
## Apply scalar expansion
if (isscalar (direction))
direction = repmat (direction, 1, nc);
endif
if (numel (direction) != nc)
error (strcat ("duration.sortrows: DIRECTION", ...
" does not match the columns in A."));
endif
## Assign DIRECTION to COL
col = [1:nc];
idx = strcmp (direction, 'descend');
col(idx) = - col(idx);
dir_flag = true;
else
error ("duration.sortrows: invalid type for COL argument.");
endif
endif
if (numel (args) > 1)
if (dir_flag)
error ("duration.sortrows: invalid third input argument.");
endif
if ((isvector (args{2}) && ischar (args{2})) || isa (args{2}, 'string'))
direction = cellstr (args{2});
elseif (isvector (args{2}) && iscellstr (args{2}))
direction = args{2};
else
error ("duration.sortrows: invalid type for DIRECTION argument.");
endif
if (! all (ismember (direction, {'ascend', 'descend'})))
error (strcat ("duration.sortrows: DIRECTION input must", ...
" contain either 'ascend' or 'descend' values."));
endif
## Assign DIRECTION to COL
if (isscalar (direction) && strcmp (direction, 'ascend'))
col = abs (col);
elseif (isscalar (direction) && strcmp (direction, 'descend'))
col = - abs (col);
else
if (numel (direction) != numel (col))
error (strcat ("duration.sortrows: DIRECTION does", ...
" not match the elements in COL."));
endif
col = abs (col);
idx = strcmp (direction, 'descend');
col(idx) = - col(idx);
endif
endif
## Apply comparison method (Octave specific)
data = A.Days;
if (strcmp (CM, 'abs'))
data = abs (data);
endif
## FIX ME: this workaround will be removed once the 'sortrows' function
## in core Octave supports 'MissingPlacement' optional argument.
## This implementation fails the edge case where -Inf and -realmax
## elements are present along the operating dimension.
pos_dir = col > 0;
neg_dir = col < 0;
fix_pos_dir = any (pos_dir) && strcmp (MP, {'first'});
fix_neg_dir = any (neg_dir) && strcmp (MP, {'last'});
if (fix_pos_dir || fix_neg_dir)
## Apply on selected columns
if (fix_pos_dir)
col_idx = col(pos_dir);
else # must be fix_neg_dir
col_idx = - col(neg_dir);
endif
cdata = data(:,col_idx);
## Only if missing data exist in operating columns.
is_nan = isnan (cdata);
if (any (is_nan, 'all'))
## Convert missing values to -Inf so that they are placed
## appropriately according to 'MissingPlacement' specification.
## If -Inf values already exist in data, then convert them to the
## next smallest possible value
is_m_inf = cdata == -Inf;
if (any (is_m_inf, 'all'))
m_inf_rep = - realmax;
cdata(is_m_inf) = m_inf_rep;
endif
cdata(is_nan) = -Inf;
data(:,col_idx) = cdata;
## Sort values
[~, index] = sortrows (data, col);
else
## Sort values without special handling
[~, index] = sortrows (data, col);
endif
else
## Sort values with no undefined elements
[~, index] = sortrows (data, col);
endif
## Return sorted duration array
B = subset (A, index, ':');
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} unique (@var{A})
## @deftypefnx {duration} {@var{B} =} unique (@var{A}, @var{setOrder})
## @deftypefnx {duration} {@var{B} =} unique (@var{A}, @var{occurrence})
## @deftypefnx {duration} {@var{B} =} unique (@var{A}, @var{setOrder}, @var{occurrence})
## @deftypefnx {duration} {@var{B} =} unique (@var{A}, @var{occurrence}, @var{setOrder})
## @deftypefnx {duration} {@var{B} =} unique (@var{A}, @dots{}, @qcode{'rows'})
## @deftypefnx {duration} {[@var{B}, @var{ixA}, @var{ixB}] =} unique (@dots{})
##
## Unique values in a duration array.
##
## @code{@var{B} = unique (@var{A})} returns the unique values of the
## duration array @var{A} in sorted order.
##
## @code{@var{B} = unique (@var{A}, @var{setOrder})} returns the unique
## values of the duration array @var{A} in an order as specified by
## @var{setOrder}, which can be either of the following values:
##
## @itemize
## @item @qcode{'sorted'} (default) returns the unique values sorted in
## ascending order.
## @item @qcode{'stable'} returns the unique values according to their order
## of occurrence.
## @end itemize
##
## @code{@var{B} = unique (@var{A}, @var{occurrence})} returns the unique
## values of the duration array @var{A} according to their order of
## occurrence. @var{occurrence} can be either of the following values:
##
## @itemize
## @item @qcode{'first'} (default) returns the first occurrence of each
## unique value, i.e. the lowest possible indices are returned.
## @item @qcode{'last'} returns the last occurrence of each unique value,
## i.e. the highest possible indices are returned.
## @end itemize
##
## You can specify @var{setOrder} and @var{occurrence} arguments together.
##
## @code{@var{B} = unique (@var{A}, @dots{}, @qcode{'rows'})} returns the
## unique rows of @var{A} by treating each row as a single entity. The
## @qcode{'rows'} option can be used alone or in any combination with the
## @var{setOrder} and @var{occurrence} arguments. @qcode{'rows'} can be
## placed at any position in the function's argument list after the input
## array @var{A}. However, this syntax is only valid for 2-dimensional
## duration arrays.
##
## @code{[@var{B}, @var{ixA}, @var{ixB}] = unique (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} using any of the previous syntaxes.
## @var{ixA} and @var{ixB} map the arrays @var{A} and @var{B} to one another
## such that @qcode{@var{B} = @var{A}(@var{ixA})} and
## @qcode{@var{A} = @var{B}(@var{ixB})}. When the @qcode{'rows'} optional
## argument is specified, then @qcode{@var{B} = @var{A}(@var{ixA},:)} and
## @qcode{@var{A} = @var{B}(@var{ixB},:)}.
##
## @end deftypefn
function [this, ixA, ixB] = unique (this, varargin)
## 'legacy' option is not supported
if (any (strcmp ('legacy', varargin)))
error ("duration.unique: 'legacy' option is not supported.");
endif
[this.Days, ixA, ixB] = __unique__ (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{YI} =} interp1 (@var{X}, @var{Y}, @var{XI})
## @deftypefnx {duration} {@var{YI} =} interp1 (@var{Y}, @var{XI})
## @deftypefnx {duration} {@var{YI} =} interp1 (@dots{}, @var{method})
## @deftypefnx {duration} {@var{YI} =} interp1 (@dots{}, @var{method}, @var{extrapolation})
## @deftypefnx {duration} {@var{pp} =} interp1 (@var{X}, @var{Y}, @qcode{'pp'})
## @deftypefnx {duration} {@var{pp} =} interp1 (@var{X}, @var{Y}, @var{method}, @qcode{'pp'})
##
## One-dimensional interpolation for duration arrays.
##
## @code{@var{YI} = interp1 (@var{X}, @var{Y}, @var{XI})} computes the
## linearly interpolated values of a one-dimensional function, which is
## represented by sample points @var{X} and corresponding values @var{Y},
## at specific query points @var{XI}. @var{X} must be a vector. If @var{Y}
## is vector, then it must have the same length as @var{X}. If @var{Y} is
## matrix, then each column is treated as a different set of one-dimensional
## sample values and the number of rows must equal the length of @var{X}.
## @var{XI} must be a vector and the same data type as @var{X}. The output
## @var{XI} is the same data type as @var{Y} and its size depends on @var{Y}
## and @var{XI}. @var{X} and @var{Y} can both be duration arrays or one of
## them can be a numeric array.
##
## @code{@var{YI} = interp1 (@var{Y}, @var{XI})} computes the linearly
## interpolated values of a one-dimensional function assuming a default set
## of sampling points determined by the shape of @var{Y}:
##
## @itemize
## @item If @var{Y} is a vector, then the default sampling points are
## @code{[1:length(@var{Y})}.
##
## @item If @var{Y} is an array, then the default sampling points are
## @code{[1:size(@var{Y})}.
## @end itemize
##
## @code{@var{YI} = interp1 (@dots{}, @var{method})} specifies one of the
## following interpolation methods to be used:
##
## @itemize
## @item @qcode{'linear'} (default) computes the linear interpolation from
## nearest neighbors.
##
## @item @qcode{'nearest'} returns the nearest neighbor.
##
## @item @qcode{'next'} returns the next neighbor.
##
## @item @qcode{'previous'} returns the previous neighbor.
##
## @item @qcode{'pchip'} computes the piecewise cubic Hermite interpolating
## polynomial, which corresponds to shape-preserving interpolation with
## smooth first derivative.
##
## @item @qcode{'cubic'} computes the cubic interpolation.
##
## @item @qcode{'spline'} computes the cubic spline interpolation, which
## corresponds to smooth first and second derivatives throughout the curve.
## @end itemize
##
## @code{@var{YI} = interp1 (@dots{}, @var{method}, @var{extrapolation})}
## further specifies a strategy for evaluating points that lie outside the
## range of the sample points in @var{X}. Set @var{extrapolation} to
## @qcode{'extrap'} to use the current @var{method} to extrapolate values.
## Set @var{extrapolation} to a scalar value of the same data type as
## @var{Y} to return a constant value outside the range of @var{X}. When
## unspecified, @var{extrapolation} defaults to @qcode{NaN}.
##
## @code{@var{pp} = interp1 (@var{X}, @var{Y}, @qcode{'pp'}} returns a
## piecewise polynomial object, using the default linear interpolation
## algorithm, which can be later used with @code{ppval} to evaluate the
## interpolation at new query points.
##
## @code{@var{pp} = interp1 (@var{X}, @var{Y}, @var{method}, @qcode{'pp'}}
## return a piecewise polynomial object, using the interpolation algorithm
## specified by @var{method}, which can be later used with @code{ppval} to
## evaluate the interpolation at new query points.
##
## @end deftypefn
function YI = interp1 (X, Y, varargin)
if (isempty (varargin))
## YI = interp1 (Y, XI)
if (isduration (Y))
Y = Y.days;
endif
if (isduration (X))
YI = duration ('Format', X.Format);
YI.Days = interp1 (X.Days, Y);
else
YI = interp1 (X, Y);
endif
else
[varargin{:}] = convertStringsToChars (varargin{:});
method = varargin{1};
if (ischar (method))
## YI = interp1 (Y, XI, method)
## YI = interp1 (Y, XI, method, extrap)
## PP = interp1 (X, Y, pp)
## PP = interp1 (X, Y, method, pp)
X_isDur = isa (X, 'duration');
Y_isDur = isa (Y, 'duration');
if (X_isDur)
F = X.Format;
X = X.days;
endif
if (Y_isDur)
Y = Y.days;
endif
## Handle numeric extrapolation input
extrap = cellfun (@(x) isduration (x) || isnumeric (x), varargin);
if (any (extrap))
tmp = varargin{extrap};
ExtDur = isduration (tmp);
if (xor (ExtDur, X_isDur))
error (strcat ("duration.interp1: EXTRAPOLATION scalar", ...
" value must match Y."));
elseif (ExtDur)
varargin{extrap} = days (tmp);
endif
endif
YI = interp1 (X, Y, varargin{:});
if (isnumeric (YI) && X_isDur)
YI = days (YI);
YI.Format = F;
endif
else
XI = method;
varargin(1) = [];
## YI = interp1 (X, Y, XI)
## YI = interp1 (X, Y, XI, method)
## YI = interp1 (X, Y, XI, method, extrap)
X_isDur = isa (X, 'duration');
Y_isDur = isa (Y, 'duration');
XIisDur = isa (XI, 'duration');
if (xor (X_isDur, XIisDur))
error (strcat ("duration.interp1: if X is a duration array,", ...
" XI must be also."));
endif
## Handle numeric extrapolation input
extrap = cellfun (@(x) isduration (x) || isnumeric (x), varargin);
if (any (extrap))
tmp = varargin{extrap};
ExtDur = isduration (tmp);
if (xor (ExtDur, Y_isDur))
error (strcat ("duration.interp1: EXTRAPOLATION scalar", ...
" value must match Y."));
elseif (ExtDur)
varargin{extrap} = days (tmp);
endif
endif
if (Y_isDur)
YI = duration ('Format', Y.Format);
if (X_isDur)
YI.Days = interp1 (X.Days, Y.Days, XI.Days, varargin{:});
else
YI.Days = interp1 (X, Y.Days, XI, varargin{:});
endif
YI = fix_zero_precision (YI);
elseif (isnumeric (Y))
YI = interp1 (X.Days, Y, XI.Days, varargin{:});
else
error ("duration.interp1: Y must be a duration or numeric array.");
endif
endif
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} intersect (@var{A}, @var{B})
## @deftypefnx {duration} {@var{C} =} intersect (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {duration} {@var{C} =} intersect (@var{A}, @var{B}, @dots{}, @var{order})
## @deftypefnx {duration} {[@var{C}, @var{ixA}, @var{ixB}] =} intersect (@dots{})
##
## Set intersection of two duration arrays.
##
## @code{@var{C} = intersect (@var{A}, @var{B})} returns the unique common
## values of the duration arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments can also be a duration string specified as a
## character vector, a string array, or a cell array of character vectors,
## or a numeric array representing 24-hour days. In such case, the input is
## promoted to a duration array prior to calculating the intersection. If
## both @var{A} and @var{B} are row vectors, then @var{C} is also a row
## vector, otherwise @code{intersect} returns a column vector.
##
## @code{@var{C} = intersect (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the duration matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in duration
## matrix @var{C} are in sorted order.
##
## @code{@dots{} = intersect (@var{A}, @var{B}, @dots{}, @var{order})} also
## specifies the order of the returned unique values. @var{order} can be
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'}, in
## which case the unique values are returned in order of appearance.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = intersect (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @end deftypefn
function [C, ixA, ixB] = intersect (A, B, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("duration.intersect: 'legacy' option is not supported.");
endif
if (ischar (A) || isstring (A) || iscellstr (A) || isnumeric (A))
C = duration ('Format', B.Format);
A = promote (A);
elseif (ischar (B) || isstring (B) || iscellstr (B) || isnumeric (B))
C = duration ('Format', A.Format);
B = promote (B);
elseif (isduration (A) && isduration (B))
C = duration ('Format', A.Format);
else
error (strcat ("duration.intersect: set operation not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
[C.Days, ixA, ixB] = intersect (A.Days, B.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} setdiff (@var{A}, @var{B})
## @deftypefnx {duration} {@var{C} =} setdiff (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {duration} {@var{C} =} setdiff (@var{A}, @var{B}, @dots{}, @var{order})
## @deftypefnx {duration} {[@var{C}, @var{ixA}] =} setdiff (@dots{})
##
## Set difference of two duration arrays.
##
## @code{@var{C} = setdiff (@var{A}, @var{B})} returns the unique common
## values of the duration arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments can also be a duration string specified as a
## character vector, a string array, or a cell array of character vectors,
## or a numeric array representing 24-hour days. In such case, the input is
## promoted to a duration array prior to calculating the intersection. If
## both @var{A} and @var{B} are row vectors, then @var{C} is also a row
## vector, otherwise @code{intersect} returns a column vector.
##
## @code{@var{C} = setdiff (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the duration matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in duration
## matrix @var{C} are in sorted order.
##
## @code{@dots{} = setdiff (@var{A}, @var{B}, @dots{}, @var{order})} also
## specifies the order of the returned unique values. @var{order} can be
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'}, in
## which case the unique values are returned in order of appearance.
##
## @code{[@var{C}, @var{ixA}] = setdiff (@dots{})} also returns the index
## vector @var{ixA} such that @code{@var{C} = @var{A}(@var{ixA})}, unless
## the @qcode{'rows'} optional argument is given, in which case
## @code{@var{C} = @var{A}(@var{ixA},:)}.
##
## @end deftypefn
function [C, index] = setdiff (A, B, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("duration.setdiff: 'legacy' option is not supported.");
endif
if (ischar (A) || isstring (A) || iscellstr (A) || isnumeric (A))
C = duration ('Format', B.Format);
A = promote (A);
elseif (ischar (B) || isstring (B) || iscellstr (B) || isnumeric (B))
C = duration ('Format', A.Format);
B = promote (B);
elseif (isduration (A) && isduration (B))
C = duration ('Format', A.Format);
else
error (strcat ("duration.setdiff: set operation not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
[C.Days, index] = setdiff (A.Days, B.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} setxor (@var{A}, @var{B})
## @deftypefnx {duration} {@var{C} =} setxor (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {duration} {@var{C} =} setxor (@var{A}, @var{B}, @dots{}, @var{order})
## @deftypefnx {duration} {[@var{C}, @var{ixA}, @var{ixB}] =} setxor (@dots{})
##
## Set exclusive-or of two duration arrays.
##
## @code{@var{C} = setxor (@var{A}, @var{B})} returns the unique common
## values of the duration arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments can also be a duration string specified as a
## character vector, a string array, or a cell array of character vectors,
## or a numeric array representing 24-hour days. In such case, the input is
## promoted to a duration array prior to calculating the intersection. If
## both @var{A} and @var{B} are row vectors, then @var{C} is also a row
## vector, otherwise @code{intersect} returns a column vector.
##
## @code{@var{C} = setxor (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the duration matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## duration matrix @var{C} are in sorted order.
##
## @code{@dots{} = setxor (@var{A}, @var{B}, @dots{}, @var{order})} also
## specifies the order of the returned unique values. @var{order} can be
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'}, in
## which case the unique values are returned in order of appearance.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = setxor (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @end deftypefn
function [C, ixA, ixB] = setxor (A, B, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("duration.setxor: 'legacy' option is not supported.");
endif
if (ischar (A) || isstring (A) || iscellstr (A) || isnumeric (A))
C = duration ('Format', B.Format);
A = promote (A);
elseif (ischar (B) || isstring (B) || iscellstr (B) || isnumeric (B))
C = duration ('Format', A.Format);
B = promote (B);
elseif (isduration (A) && isduration (B))
C = duration ('Format', A.Format);
else
error (strcat ("duration.setxor: set operation not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
[C.Days, ixA, ixB] = setxor (A.Days, B.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} union (@var{A}, @var{B})
## @deftypefnx {duration} {@var{C} =} union (@var{A}, @var{B}, @qcode{'rows'})
## @deftypefnx {duration} {@var{C} =} union (@var{A}, @var{B}, @dots{}, @var{order})
## @deftypefnx {duration} {[@var{C}, @var{ixA}, @var{ixB}] =} union (@dots{})
##
## Set union of two duration arrays.
##
## @code{@var{C} = union (@var{A}, @var{B})} returns the unique common
## values of the duration arrays @var{A} and @var{B}. Either @var{A} or
## @var{B} input arguments can also be a duration string specified as a
## character vector, a string array, or a cell array of character vectors,
## or a numeric array representing 24-hour days. In such case, the input is
## promoted to a duration array prior to calculating the intersection. If
## both @var{A} and @var{B} are row vectors, then @var{C} is also a row
## vector, otherwise @code{intersect} returns a column vector.
##
## @code{@var{C} = union (@var{A}, @var{B}, @qcode{'rows'}} returns the
## unique common rows of the duration matrices @var{A} and @var{B}, which
## must have the same number of columns. By default, the rows in
## duration matrix @var{C} are in sorted order.
##
## @code{@dots{} = union (@var{A}, @var{B}, @dots{}, @var{order})} also
## specifies the order of the returned unique values. @var{order} can be
## @qcode{'sorted'}, which is the default behavior, or @qcode{'stable'}, in
## which case the unique values are returned in order of appearance.
##
## @code{[@var{C}, @var{ixA}, @var{ixB}] = union (@dots{})} also returns
## index vectors @var{ixA} and @var{ixB} such that
## @code{@var{C} = @var{A}(@var{ixA})} and
## @code{@var{C} = @var{B}(@var{ixB})}, unless the @qcode{'rows'} optional
## argument is given, in which case @code{@var{C} = @var{A}(@var{ixA},:)}
## and @code{@var{C} = @var{B}(@var{ixB},:)}.
##
## @end deftypefn
function [C, ixA, ixB] = union (A, B, varargin)
## 'legacy' option is not supported
if (any (strcmp ("legacy", varargin)))
error ("duration.union: 'legacy' option is not supported.");
endif
if (ischar (A) || isstring (A) || iscellstr (A) || isnumeric (A))
C = duration ('Format', B.Format);
A = promote (A);
elseif (ischar (B) || isstring (B) || iscellstr (B) || isnumeric (B))
C = duration ('Format', A.Format);
B = promote (B);
elseif (isduration (A) && isduration (B))
C = duration ('Format', A.Format);
else
error (strcat ("duration.union: set operation not defined", ...
" between '%s' and '%s' arrays."), class (A), class (B));
endif
[C.Days, ixA, ixB] = union (A.Days, B.Days, varargin{:});
endfunction
endmethods
################################################################################
## ** Array Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'cat' 'horzcat' 'vertcat' 'repmat' ##
## 'repelem' 'repelems' 'reshape' 'circshift' ##
## 'permute' 'ipermute' 'transpose' 'ctranspose' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} cat (@var{dim}, @var{A}, @var{B}, @dots{})
##
## Concatenate duration arrays.
##
## @code{@var{C} = cat (@var{dim}, @var{A}, @var{B}, @dots{})} concatenates
## duration arrays @var{A}, @var{B}, @dots{} along dimension @var{dim}. All
## input arrays must have the same size except along the operating dimension
## @var{dim}. Any of the input arrays may also be string arrays or cell
## arrays of character vectors of compatible size. Additionally, an input
## can be a numeric matrix, which when parsed to the constructor will return
## a duration array of compatible size.
##
## @end deftypefn
function out = cat (dim, varargin)
## If any of the input arrays is a calendarDuration array, then convert
## the first input to calendarDuration array and call the corresponding
## method.
if (any (cellfun ('iscalendarduration', varargin)))
if (isduration (varargin{1}))
varargin{1} = calendarDuration (0, 0, 0, varargin{1});
elseif (isnumeric (varargin{1}))
if (isempty (varargin{1}))
varargout{1} = calendarDuration ([], [], []);
else
varargout{1} = calendarDuration (0, 0, 0, 24 * varargin{i}, 0, 0);
endif
else
error ("calendarDuration: invalid input to constructor.");
endif
out = cat (dim, varargin{:});
else
args = varargin;
[args{:}] = promote (varargin{:});
## Get format from first duration array argument
idx = find (cellfun ('isduration', varargin), 1);
fmt = varargin{idx}.Format;
out = duration ('Format', fmt);
days = cellfun (@(obj) obj.Days, args, 'UniformOutput', false);
out.Days = cat (dim, days{:});
endif
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} horzcat (@var{A}, @var{B}, @dots{})
##
## Horizontal concatenation of duration arrays.
##
## @code{@var{C} = horzcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}, @var{B}, @dots{}]} and horizontally
## concatenates the duration arrays @var{A}, @var{B}, @dots{}. All input
## arrays must have the same size except along the second dimension. Any of
## the input arrays may also be string arrays or cell arrays of character
## vectors of compatible size. Additionally, an input can be a numeric
## matrix, which when parsed to the constructor will return a duration array
## of compatible size.
##
## @end deftypefn
function out = horzcat (varargin)
out = cat (2, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{C} =} vertcat (@var{A}, @var{B}, @dots{})
##
## Vertical concatenation of duration arrays.
##
## @code{@var{C} = vertcat (@var{A}, @var{B}, @dots{}} is the equivalent of
## the syntax @code{@var{B} = [@var{A}; @var{B}; @dots{}]} and vertically
## concatenates the duration arrays @var{A}, @var{B}, @dots{}. All input
## arrays must have the same size except along the first dimension. All of
## the input arrays may also be string arrays or cell arrays of character
## vectors of compatible size. Additionally, an input can be a numeric
## matrix, which when parsed to the constructor will return a duration array
## of compatible size.
##
## @end deftypefn
function out = vertcat (varargin)
out = cat (1, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} repmat (@var{A}, @var{n})
## @deftypefnx {duration} {@var{B} =} repmat (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {duration} {@var{B} =} repmat (@var{A}, @var{dimvec})
##
## Repeat copies of a duration array.
##
## @code{@var{B} = repmat (@var{A}, @var{n})} returns a duration array
## @var{B} containing @var{n} copies of the input duration array @var{A}
## along every dimension of @var{A}.
##
## @code{@var{B} = repmat (@var{A}, @var{d1}, @dots{}, @var{dN})} returns an
## array @var{B} containing copies of @var{A} along the dimensions specified
## by the list of scalar integer values @var{d1}, @dots{}, @var{dN}, which
## specify how many copies of @var{A} are made in each dimension.
##
## @code{@var{B} = repmat (@var{A}, @var{dimvec})} is equivalent to the
## previous syntax with @code{@var{dimvec} = [@var{d1}, @dots{}, @var{dN}]}.
##
## @end deftypefn
function this = repmat (this, varargin)
this.Days = repmat (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} repelem (@var{A}, @var{n})
## @deftypefnx {duration} {@var{B} =} repelem (@var{A}, @var{d1}, @dots{}, @var{dN})
##
## Repeat copies of duration array elements.
##
## @code{@var{B} = repelem (@var{A}, @var{n})} returns a duration vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a duration vector. If @var{n} is a scalar, each element of @var{A} is
## repeated @var{n} times along the non-singleton dimension of @var{A}. If
## @var{n} is a vector, it must have the same elements as @var{A}, in which
## case it specifies the number of times to repeat each corresponding
## element of @var{A}.
##
## @code{@var{B} = repelem (@var{A}, @var{d1}, @dots{}, @var{dN})} returns
## an array @var{B} with each element of @var{A} repeated according to the
## the list of input arguments @code{@var{d1}, @dots{}, @var{dN}} each
## corresponding to a different dimension @code{1:ndims (@var{A})} of the
## input array @var{A}. @var{d1}, @dots{}, @var{dN} must be either scalars
## or vectors with the same length as the corresponding dimension of
## @var{A} containing non-negative integer values specifying the number of
## repetitions of each element along the corresponding dimension.
##
## @end deftypefn
function this = repelem (this, varargin)
this.Days = repelem (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} repelems (@var{A}, @var{R})
##
## Construct a vector of repeated duration array.
##
## @code{@var{B} = repelems (@var{A}, @var{R})} returns a duration vector
## @var{B} containing repeated elements of the input @var{A}, which must be
## a duration vector. @var{R} must be a @math{2*N} matrix of integers.
## Entries in the first row of @var{R} correspond to the linear indexing of
## the elements in @var{A} to be repeated. The corresponding entries in the
## second row of @var{R} specify the repeat count of each element.
##
## @end deftypefn
function this = repelems (this, R)
this.Days = repelems (this.Days, R);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} reshape (@var{A}, @var{d1}, @dots{}, @var{dN})
## @deftypefnx {duration} {@var{B} =} reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})
## @deftypefnx {duration} {@var{B} =} reshape (@var{A}, @var{dimvec})
##
## Reshape duration array.
##
## @code{@var{B} = reshape (@var{A}, @var{d1}, @dots{}, @var{dN})} returns a
## duration array @var{B} with specified dimensions @var{d1}, @dots{},
## @var{dN}, whose elements are taken columnwise from the duration array
## @var{A}. The product of @var{d1}, @dots{}, @var{dN} must equal the total
## number of elements in @var{A}.
##
## @code{@var{B} = reshape (@var{A}, @dots{}, @qcode{[]}, @dots{})} returns
## a duration array @var{B} with one dimension unspecified which is
## calculated automatically so that the product of dimensions in @var{B}
## matches the total elements in @var{A}, which must be divisible the
## product of specified dimensions. An empty matrix @qcode{([])} is used to
## flag the unspecified dimension.
##
## @end deftypefn
function this = reshape (this, varargin)
this.Days = reshape (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} circshift (@var{A}, @var{n})
## @deftypefnx {duration} {@var{B} =} circshift (@var{A}, @var{n}, @var{dim})
##
## Circularly shift the elements in a duration array.
##
## @code{@var{B} = circshift (@var{A}, @var{n})} circularly shifts the
## elements of the duration array @var{A} according to @var{n}. If @var{n}
## is a nonzero integer scalar, then the elements of @var{A} are shifted by
## @var{n} elements along the first non-singleton dimension of @var{A}. If
## @var{n} is a vector, it must not be longer that the number of dimensions
## of @var{A} with each value of @var{n} corresponding to a dimension in
## @var{A}. The sign of the value(s) in @var{n} specify the direction in
## the elements of @var{A} are shifted.
##
## @code{@var{B} = circshift (@var{A}, @var{n}, @var{dim})} circularly
## shifts the elements of the duration array @var{A} along the dimension
## specified by @var{dim}. In this case, @var{n} must be a scalar integer
## value.
##
## @end deftypefn
function this = circshift (this, varargin)
this.Days = circshift (this.Days, varargin{:});
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} permute (@var{A}, @var{dims})
##
## Generalized transpose for a duration N-D array.
##
## @code{@var{B} = permute (@var{A}, @var{dims})} returns the generalized
## transpose of the duration array @var{A} by rearranging its dimensions
## according to the permutation vector specified in @var{dims}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{A})} of the
## input array @var{A}, in any order, but only once. The @var{N}th
## dimension of @var{A} gets remapped to the dimension in @var{B} specified
## by @code{@var{dims}(@var{N})}.
##
## @end deftypefn
function this = permute (this, order)
this.Days = permute (this.Days, order);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{A} =} ipermute (@var{B}, @var{dims})
##
## Inverse of the generalized transpose for a duration N-D array.
##
## @code{@var{A} = ipermute (@var{B}, @var{dims})} returns the inverse of
## the generalized transpose performed by the @code{permute} function. The
## expression @code{ipermute (permute (@var{A}, @var{dims}), @var{dims})}
## returns the original array @var{A}.
##
## @var{dims} must index all the dimensions @code{1:ndims (@var{B})} of the
## input array @var{B}, in any order, but only once. The dimension of
## @var{B} specified in @code{@var{dims}(@var{N})} gets remapped to the
## @var{N}th dimension of @var{A}.
##
## @end deftypefn
function this = ipermute (this, order)
this.Days = ipermute (this.Days, order);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} transpose (@var{A})
##
## Transpose a duration matrix.
##
## @code{@var{B} = transpose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}.'} and returns the transpose of the duration
## matrix @var{A}.
##
## @end deftypefn
function this = transpose (this)
this.Days = transpose (this.Days);
endfunction
## -*- texinfo -*-
## @deftypefn {duration} {@var{B} =} ctranspose (@var{A})
##
## Transpose a duration matrix.
##
## @code{@var{B} = ctranspose (@var{A})} is the equivalent of the syntax
## @code{@var{B} = @var{A}'} and returns the transpose of the duration
## matrix @var{A}. For duration arrays, @code{ctranspose} is identical to
## @code{transpose}.
##
## @end deftypefn
function this = ctranspose (this)
this.Days = ctranspose (this.Days);
endfunction
endmethods
################################################################################
## ** Reference and Assignment Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'end' 'subsref' 'subsasgn' ##
## ##
################################################################################
methods (Hidden)
## Overload 'end' keyword
function last_index = end (this, end_dim, ndim_obj)
lastdim = ndims (this);
if (end_dim == ndim_obj && ndim_obj == 1)
last_index = prod (size (this));
elseif (end_dim == ndim_obj && end_dim < lastdim)
last_index = prod (size (this)(end_dim:lastdim));
else
last_index = size (this, end_dim);
endif
endfunction
## Class specific subscripted reference
function varargout = subsref (this, s)
chain_s = s(2:end);
s = s(1);
switch (s.type)
case '()'
out = this;
out.Days = this.Days(s.subs{:});
case '{}'
error (strcat ("duration.subsref: '{}' invalid indexing", ...
" for referencing values. Use '()' instead."));
case '.'
switch (s.subs)
case 'Format'
out = this.Format;
otherwise
error ("duration.subsref: unrecognized property: '%s'", s.subs);
endswitch
endswitch
## Chained references
if (! isempty (chain_s))
out = subsref (out, chain_s);
endif
varargout{1} = out;
endfunction
## Class specific subscripted assignment
function this = subsasgn (this, s, val)
if (numel (s) > 1)
error ("duration.subsasgn: chained subscripts not allowed.");
endif
switch (s.type)
case '()'
if (isempty (val))
this.Days(s.subs{:}) = [];
elseif (isa (val, 'missing'))
this.Days(s.subs{:}) = NaN;
elseif (iscellstr (val) || ischar (val) || isstring (val))
if (! iscellstr (val))
val = cellstr (val);
endif
this.Days(s.subs{:}) = timestrings2days (val, []);
elseif (isnumeric (val))
this.Days(s.subs{:}) = double (val);
elseif (isa (val, "duration"))
this.Days(s.subs{:}) = val.Days;
else
error (strcat ("duration.subsasgn: assignment value must", ...
" be a duration array, a numeric array of", ...
" days, or a text represention of durations."));
endif
case '{}'
error (strcat ("duration.subsasgn: '{}' invalid indexing", ...
" for assigning values. Use '()' instead."));
case '.'
switch (s.subs)
case 'Format'
## Convert string to character vector if necessary
if (isstring (val))
if (! isscalar (val))
error (strcat ("duration.subsasgn: 'Format' must be a", ...
" character vector or a string scalar."));
endif
val = char (val);
elseif (! (ischar (val) && isrow (val)))
error (strcat ("duration.subsasgn: 'Format' must be a", ...
" character vector or a string scalar."));
endif
errmsg = checkFormatString (val);
if (! isempty (errmsg))
error ("duration.subsasgn: %s", errmsg);
endif
this.Format = val;
otherwise
error ("duration.subsasgn: unrecognized property: '%s'", s.subs);
endswitch
endswitch
endfunction
endmethods
methods (Access = private)
## Return a subset of a duration array
function out = subset (this, varargin)
out = this;
out.Days = this.Days(varargin{:});
endfunction
## Fix floating point precision near zero
function this = fix_zero_precision (this)
this.Days(this.Days > -1e-15 & this.Days < 1e-15) = 0;
endfunction
endmethods
endclassdef
## Promote numeric and string arrays to duration objects
function varargout = promote (varargin)
for i = 1:numel (varargin)
x = varargin{i};
if (isa (x, "duration"))
varargout{i} = x;
elseif (isnumeric (x))
varargout{i} = days (x);
elseif (iscellstr (x) || ischar (x) || isa (x, "string"))
varargout{i} = duration (x);
else
error ("duration: invalid input to constructor.");
endif
endfor
endfunction
## Parse H, M, S, and MS numeric inputs into days
function [err, days] = hms2days (H, MI, S, MS = 0)
err = 0;
if (! isscalar (H) || ! isscalar (MI) || ! isscalar (S) || ! isscalar (MS))
[err, H, MI, S, MS] = common_size (H, MI, S, MS);
if (err > 0)
days = NaN;
return
endif
endif
H = double (H);
MI = double (MI);
S = double (S);
MS = double (MS);
days = (H / 24) + (MI / 1440) + (S / 86400) + (MS / 86400000);
endfunction
## Parse TimeString inputs into days
function days = timestrings2days (TS, inputFormat)
days = NaN (size (TS));
## Find default format (either 'dd:hh:mm:ss' or 'hh:mm:ss') from 1st element
if (isempty (inputFormat))
str1 = TS{1};
nCols = numel (find (str1 == ':'));
nDots = numel (find (str1 == '.'));
if (nDots > 1)
error ("duration: could not recognize time string format of '%s'.", str1);
endif
if (nCols > 3 || nCols < 1)
error ("duration: could not recognize time string format of '%s'.", str1);
endif
if (nCols == 1)
error ("duration: time string format is ambiguous.");
endif
if (nDots)
cstr = strsplit (str1, '.');
if (! isempty (cstr{2}) && isnan (str2double (cstr{2})))
error (strcat ("duration: could not recognize time string", ...
" format of '%s'."), str1);
endif
cstr = strsplit (cstr{1}, ':');
if (numel (cstr) != nCols + 1)
error (strcat ("duration: could not recognize time string", ...
" format of '%s'."), str1);
endif
for i = 1:nCols + 1
if (isnan (str2double (cstr{i})))
error (strcat ("duration: could not recognize time string", ...
" format of '%s'."), str1);
endif
endfor
endif
else
nCols = numel (find (inputFormat == ':'));
nDots = numel (find (inputFormat == '.'));
endif
## Process all elements according to inputFormat (unrecognized return NaN)
for i = 1:numel (TS)
str1 = TS{i};
pnd_sign = 1;
if (numel (find (str1 == '.')))
cstr = strsplit (str1, '.');
if (isempty (cstr{2}))
MS = 0;
else
MSnumber = str2double (cstr{2});
MSdigits = 10 ^ (numel (cstr{2}) - 3);
MS = MSnumber / MSdigits;
endif
cstr = strsplit (cstr{1}, ':');
if (numel (cstr) != nCols + 1)
D = H = MI = S = NaN;
elseif (nCols == 1) # 'mm:ss' only
D = 0;
H = 0;
MI = str2double (cstr{1});
if (MI < 0)
pnd_sign = -1;
MI = -MI;
endif
S = str2double (cstr{2});
if (S >= 60)
S = NaN;
endif
elseif (nCols == 2) # 'hh:mm:ss'
D = 0;
H = str2double (cstr{1});
if (H < 0)
pnd_sign = -1;
H = -H;
endif
MI = str2double (cstr{2});
S = str2double (cstr{3});
if (MI >= 60 || S >= 60)
MI = S = NaN;
endif
else # 'dd:hh:mm:ss'
D = str2double (cstr{1});
if (D < 0)
pnd_sign = -1;
D = -D;
endif
H = str2double (cstr{2});
MI = str2double (cstr{3});
S = str2double (cstr{4});
if (H >= 24 || MI >= 60 || S >= 60)
H = MI = S = NaN;
endif
endif
else
cstr = strsplit (str1, ':');
if (numel (cstr) != nCols + 1)
D = H = MI = S = MS = NaN;
elseif (nCols == 1) # either 'mm:ss' or 'hh:mm'
if (strcmp (inputFormat, 'mm:ss'))
D = 0;
H = 0;
MI = str2double (cstr{1});
if (MI < 0)
pnd_sign = -1;
MI = -MI;
endif
S = str2double (cstr{2});
MS = 0;
else # 'hh:mm'
D = 0;
H = str2double (cstr{1});
if (H < 0)
pnd_sign = -1;
H = -H;
endif
MI = str2double (cstr{2});
if (MI >= 60)
MI = NaN;
endif
S = 0;
MS = 0;
endif
elseif (nCols == 2) # 'hh:mm:ss'
D = 0;
H = str2double (cstr{1});
if (H < 0)
pnd_sign = -1;
H = -H;
endif
MI = str2double (cstr{2});
S = str2double (cstr{3});
if (MI >= 60 || S >= 60)
MI = S = NaN;
endif
MS = 0;
else # 'dd:hh:mm:ss'
D = str2double (cstr{1});
if (D < 0)
pnd_sign = -1;
D = -D;
endif
H = str2double (cstr{2});
MI = str2double (cstr{3});
S = str2double (cstr{4});
if (H >= 24 || MI >= 60 || S >= 60)
H = MI = S = NaN;
endif
MS = 0;
endif
endif
days(i) = D + (H / 24) + (MI / 1440) + (S / 86400) + (MS / 86400000);
days(i) *= pnd_sign;
endfor
endfunction
## Check 'Format' string
function errmsg = checkFormatString (Format)
errmsg = "";
Format = strsplit (Format, '.')';
validFmt = {'y', 'd', 'h', 'm', 's', 'dd:hh:mm:ss', 'hh:mm:ss', ...
'mm:ss', 'hh:mm'};
foundFmt = ismember (validFmt, Format(1));
if (! any (foundFmt) || numel (Format) > 2)
errmsg = "invalid display format.";
endif
if (any (foundFmt([1:5])) && numel (Format) > 1)
errmsg = "invalid display format.";
endif
if (foundFmt(9) && numel (Format) > 1)
errmsg = "'hh:mm' display format cannot indicate fractional second digits.";
endif
if (numel (Format) == 2)
if (any (char (Format(2)) != 'S'))
errmsg = "invalid display format for fractional second digits.";
endif
if (numel (Format{2}) > 9)
errmsg = "more than nine fractional second digits in display format.";
endif
endif
endfunction
## Check 'InputFormat' string
function errmsg = checkInputFormatString (inputFormat)
errmsg = '';
inputFormat = strsplit (inputFormat, '.');
validInFmt = {'dd:hh:mm:ss','hh:mm:ss','mm:ss','hh:mm'};
foundInFmt = ismember (validInFmt, inputFormat(1));
if (! any (foundInFmt) || numel (inputFormat) > 2)
errmsg = "invalid 'InputFormat'.";
endif
if (foundInFmt(4) && numel (inputFormat) > 1)
errmsg = "'hh:mm' input format cannot indicate fractional second digits.";
endif
if (numel (inputFormat) == 2)
if (any (char (inputFormat(2)) != 'S'))
errmsg = "invalid 'InputFormat' for fractional second digits.";
endif
if (numel (inputFormat{2}) > 9)
errmsg = "more than nine fractional second digits in 'InputFormat'.";
endif
endif
endfunction
pr0m1th3as-datatypes-9c9a8d3/inst/findgroups.m 0000664 0000000 0000000 00000016354 15227665741 0021401 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{G} =} findgroups (@var{A})
## @deftypefnx {datatypes} {@var{G} =} findgroups (@var{A1}, @dots{}, @var{AN})
## @deftypefnx {datatypes} {[@var{G}, @var{ID}] =} findgroups (@var{A})
## @deftypefnx {datatypes} {[@var{G}, @var{ID1}, @dots{}, @var{IDN}] =} findgroups (@var{A1}, @dots{}, @var{AN})
##
## Find groups defined by one or more grouping variables.
##
## @code{@var{G} = findgroups (@var{A})} returns @var{G}, a column vector of
## positive integer group numbers with one element per element of the grouping
## variable @var{A}. The groups are the sorted unique values of @var{A}: if
## @var{N} groups are found, every integer between 1 and @var{N} labels a group.
## Elements of @var{A} that are missing (@code{NaN}, @code{NaT},
## @code{}, @code{''}, or @code{}) are labelled @code{NaN}
## in @var{G}. @var{A} can be a numeric, logical, @code{string}, @code{cellstr},
## @code{char}, @code{datetime}, @code{duration}, @code{calendarDuration}, or
## @code{categorical} vector.
##
## @code{@var{G} = findgroups (@var{A1}, @dots{}, @var{AN})} defines groups as
## the sorted unique combinations of values across the grouping variables
## @var{A1}, @dots{}, @var{AN}, which must all have the same number of elements.
##
## @code{[@var{G}, @var{ID}] = findgroups (@var{A})} also returns @var{ID}, the
## sorted unique values of @var{A} that identify each group. With multiple
## grouping variables, @code{[@var{G}, @var{ID1}, @dots{}, @var{IDN}] =
## findgroups (@var{A1}, @dots{}, @var{AN})} returns one identifier vector per
## grouping variable.
##
## To group the variables of a @code{table}, call @code{findgroups (@var{T})},
## which dispatches to the @code{table} method and returns the group identifiers
## as a table.
##
## @seealso{splitapply, table}
## @end deftypefn
function [G, varargout] = findgroups (varargin)
if (nargin < 1)
print_usage ();
endif
## Force each grouping variable to a column (char matrices keep their rows as
## observations); reject anything that is not a vector or a char matrix.
vars = varargin;
for k = 1:numel (vars)
v = vars{k};
if (ischar (v))
if (ndims (v) > 2)
error ("findgroups: grouping variables must be vectors.");
endif
elseif (isvector (v) || isempty (v))
vars{k} = v(:);
else
error ("findgroups: grouping variables must be vectors.");
endif
endfor
## Build the combined proxy matrix and the overall missing-row mask.
nvar = numel (vars);
n = size (vars{1}, 1);
P = [];
miss = false (n, 1);
for k = 1:nvar
if (size (vars{k}, 1) != n)
error ("findgroups: grouping variables must have the same number of elements.");
endif
[p, m, errmsg] = group_col_proxy (vars{k});
if (! isempty (errmsg))
error ("findgroups: %s", errmsg);
endif
P = [P, p];
miss = miss | m;
endfor
## Label the non-missing rows by sorted unique combination.
G = NaN (n, 1);
keep = find (! miss);
repRows = [];
if (! isempty (keep))
[~, ia, ic] = unique (P(keep,:), "rows");
G(keep) = ic;
repRows = keep(ia);
endif
if (nargout > 1)
if (nargout - 1 > nvar)
print_usage ();
endif
varargout = cell (1, nargout - 1);
for k = 1:(nargout - 1)
varargout{k} = vars{k}(repRows,:);
endfor
endif
endfunction
## Build a single-column grouping proxy for one grouping variable COL: a numeric
## matrix P (one row per element) whose sort order matches COL's value order, so
## that 'unique (P, "rows")' recovers the sorted unique groups, together with a
## logical MISS mask flagging the elements that findgroups treats as missing
## (NaN/NaT//''/). Returns an errmsg body (empty on success)
## emitted by the caller under its own name. Self-contained: no table dependency.
function [p, miss, errmsg] = group_col_proxy (col)
p = [];
miss = [];
errmsg = '';
if (isa (col, 'categorical'))
## Categorical groups follow category order (ordinal or reordered), which the
## underlying category codes encode; maps to NaN.
p = double (col)(:);
miss = isnan (p);
elseif (isa (col, 'string') || iscellstr (col) || ischar (col))
c = cellstr (col);
c = c(:);
miss = cellfun (@isempty, c);
[~, ~, ic] = unique (c);
p = ic(:);
elseif (isa (col, 'datetime'))
DV = datevec (col); # (numel)-by-6 in column-major order
nat = any (isnan (DV), 2);
DV(nat,:) = 0;
DV(nat,2:3) = 1; # valid month/day placeholder
p = datenum (DV);
p(nat) = NaN;
p = p(:);
miss = isnan (p);
elseif (isa (col, 'duration'))
p = days (col)(:);
miss = isnan (p);
elseif (isa (col, 'calendarDuration'))
p = proxyArray (col);
miss = any (isnan (p), 2);
elseif (isnumeric (col) || islogical (col))
p = double (col)(:);
miss = isnan (p);
else
errmsg = sprintf ("unsupported grouping variable type '%s'.", class (col));
endif
endfunction
%!assert_equal (findgroups ([1; 3; 1; 2]), [1; 3; 1; 2])
%!assert_equal (findgroups ([30, 10, 10, 20]), [3; 1; 1; 2])
%!assert_equal (findgroups ({'b'; 'a'; 'b'; 'c'}), [2; 1; 2; 3])
%!assert_equal (findgroups (logical ([1; 0; 1; 0])), [2; 1; 2; 1])
%!test
%! ## Missing values map to NaN in G
%! assert_equal (findgroups ([1; NaN; 2; 1]), [1; NaN; 2; 1]);
%! assert_equal (findgroups ({'b'; ''; 'a'}), [2; NaN; 1]);
%!test
%! ## Categorical groups follow category order, not alphabetical order
%! c = categorical ({'medium'; 'low'; 'high'; 'low'}, ...
%! {'low', 'medium', 'high'}, 'Ordinal', true);
%! assert_equal (findgroups (c), [2; 1; 3; 1]);
%! [g, id] = findgroups (c);
%! assert_equal (cellstr (id), {'low'; 'medium'; 'high'});
%!test
%! ## Reordered nominal categoricals also group by category order
%! c = reordercats (categorical ({'b'; 'a'; 'c'; 'a'}), {'c', 'a', 'b'});
%! assert_equal (findgroups (c), [3; 2; 1; 2]);
%!test
%! ## Multiple grouping variables group by sorted unique combinations
%! assert_equal (findgroups ([1; 1; 2; 1], {'b'; 'a'; 'a'; 'b'}), [2; 1; 3; 2]);
%!test
%! ## Second output holds the sorted unique identifiers of each input
%! [G, ID] = findgroups ([30; 10; 10; 20]);
%! assert_equal (G, [3; 1; 1; 2]);
%! assert_equal (ID, [10; 20; 30]);
%!test
%! [G, ID1, ID2] = findgroups ([1; 1; 2], {'b'; 'a'; 'a'});
%! assert_equal (G, [2; 1; 3]);
%! assert_equal (ID1, [1; 1; 2]);
%! assert_equal (ID2, {'a'; 'b'; 'a'});
%!error findgroups ()
%!error findgroups ([1, 2; 3, 4])
pr0m1th3as-datatypes-9c9a8d3/inst/groupcounts.m 0000664 0000000 0000000 00000037227 15227665741 0021613 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} groupcounts (@var{A})
## @deftypefnx {datatypes} {@var{B} =} groupcounts (@var{A}, @var{groupbins})
## @deftypefnx {datatypes} {[@var{B}, @var{BG}, @var{BP}] =} groupcounts (@dots{})
## @deftypefnx {datatypes} {[@dots{}] =} groupcounts (@dots{}, @var{Name}, @var{Value})
##
## Count the number of elements in each group of an array.
##
## @code{@var{B} = groupcounts (@var{A})} groups the rows of @var{A} by their
## values and returns @var{B}, a column vector with the number of elements in
## each group. @var{A} is a grouping vector, a matrix whose columns are grouping
## variables, or a cell array of grouping vectors. Groups are the sorted unique
## combinations of grouping values; rows holding a missing value in a grouping
## variable form their own groups, sorted after the non-missing groups.
##
## @code{[@var{B}, @var{BG}, @var{BP}] = groupcounts (@dots{})} also returns
## @var{BG}, the grouping values that identify each group, and @var{BP}, a column
## vector giving each group's count as a percentage of the total. When @var{A}
## is a single grouping vector, @var{BG} holds its representative value for each
## group; when several grouping variables are given, @var{BG} is a cell array
## with one element per grouping variable.
##
## The optional @var{groupbins} argument bins the grouping variables before
## grouping (a vector of bin edges or a positive integer number of bins, applied
## to a numeric, datetime, or duration grouping variable, or a cell array with
## one scheme per grouping variable); each binned variable becomes a categorical
## of bin interval labels.
##
## The behaviour can be modified with the @qcode{'IncludeMissingGroups'} (default
## @code{true}), @qcode{'IncludeEmptyGroups'} (default @code{false}), and
## @qcode{'IncludedEdge'} (default @qcode{'left'}, the inclusive bin edge)
## @var{Name}/@var{Value} pairs, as for the @code{table} method. When
## @qcode{'IncludeEmptyGroups'} is @code{true}, the unused categories of a
## categorical or binned grouping variable contribute empty groups.
##
## To count the rows in each group of a @code{table}, call @code{groupcounts
## (@var{T}, @var{groupvars}, @dots{})}, which dispatches to the @code{table}
## method and returns the result as a table.
##
## @seealso{groupsummary, findgroups, splitapply, table}
## @end deftypefn
function [B, varargout] = groupcounts (A, varargin)
if (nargin < 1)
print_usage ();
endif
## An optional GROUPBINS positional argument may precede the Name-Value
## options; anything else after A must be a recognised option.
optNames = {'IncludeMissingGroups', 'IncludeEmptyGroups', 'IncludedEdge'};
hasGB = false;
groupbins = [];
if (! isempty (varargin))
a = varargin{1};
isOpt = ((ischar (a) && isrow (a)) || (isa (a, 'string') && isscalar (a))) ...
&& any (strcmpi (char (a), optNames));
if (! isOpt)
if (__groupbins__ ('is_spec', a))
hasGB = true;
groupbins = a;
varargin = varargin(2:end);
else
error (strcat ("groupcounts: invalid argument; expected a GROUPBINS", ...
" binning scheme or a Name-Value option."));
endif
endif
endif
## Parse Name-Value options.
dfValues = {true, false, 'left'};
[incMiss, incEmpty, incEdge] = ...
parsePairedArguments (optNames, dfValues, varargin(:));
if (! (isscalar (incMiss) && (islogical (incMiss) || isnumeric (incMiss))))
error ("groupcounts: 'IncludeMissingGroups' must be a logical scalar.");
endif
incMiss = logical (incMiss);
if (! (isscalar (incEmpty) && (islogical (incEmpty) || isnumeric (incEmpty))))
error ("groupcounts: 'IncludeEmptyGroups' must be a logical scalar.");
endif
incEmpty = logical (incEmpty);
incEdge = check_included_edge ('groupcounts', incEdge);
## Resolve A into a cell array of grouping column vectors: a cell array holds
## one grouping variable per element, a numeric/logical matrix one per column,
## and anything else is a single grouping variable.
if (iscell (A) && ! (iscellstr (A) && isvector (A)))
gvs = A(:)';
elseif (! ischar (A) && ismatrix (A) && size (A, 2) > 1)
gvs = cell (1, size (A, 2));
for j = 1:size (A, 2)
gvs{j} = A(:,j);
endfor
else
gvs = {A};
endif
for j = 1:numel (gvs)
g = gvs{j};
if (ischar (g))
if (ndims (g) > 2)
error ("groupcounts: grouping variables must be vectors.");
endif
elseif (isvector (g) || isempty (g))
gvs{j} = g(:);
else
error ("groupcounts: grouping variables must be vectors.");
endif
endfor
n = size (gvs{1}, 1);
for j = 2:numel (gvs)
if (size (gvs{j}, 1) != n)
error (strcat ("groupcounts: each grouping variable must have the", ...
" same number of elements."));
endif
endfor
## Bin the grouping variables when a GROUPBINS argument was given.
if (hasGB)
names = cell (1, numel (gvs));
for j = 1:numel (gvs)
names{j} = sprintf ("%d", j);
endfor
[gvs, ~, errmsg] = __groupbins__ ('bin', gvs, names, groupbins, incEdge, ...
'groupcounts');
if (! isempty (errmsg))
error ("groupcounts: %s", errmsg);
endif
endif
## Group the rows, treating missing grouping values as their own groups;
## IncludeEmptyGroups adds the unused categories of a categorical or binned
## grouping variable as empty groups.
[Grp, ng, gvals, errmsg] = gb_grouping (gvs, incMiss, incEmpty);
if (! isempty (errmsg))
error ("groupcounts: %s", errmsg);
endif
B = accumarray (Grp(! isnan (Grp)), 1, [ng, 1]);
## Optional outputs: the grouping identifiers and the group percentages.
if (nargout > 1)
if (numel (gvs) == 1)
BG = gvals{1};
else
BG = gvals;
endif
varargout{1} = BG;
endif
if (nargout > 2)
varargout{2} = 100 * B / sum (B);
endif
endfunction
## Group rows by the grouping-variable values GVS (a cell array of column
## vectors), treating each variable's missing values as a single group value.
## Returns G (1..NGROUPS), NGROUPS, REPROWS (a representative row per group), and
## an errmsg body. Groups are sorted by value with missing groups last; when
## INCMISS is false the rows with a missing grouping value are dropped.
## Self-contained: no table dependency.
function [G, ngroups, repRows, errmsg] = gc_group_rows (gvs, incMiss)
errmsg = '';
G = [];
ngroups = 0;
repRows = [];
n = size (gvs{1}, 1);
KEY = [];
SORT = [];
anyMiss = false (n, 1);
for j = 1:numel (gvs)
[p, m, e] = gc_col_proxy (gvs{j});
if (! isempty (e))
errmsg = e;
return;
endif
pc = p;
pc(m,:) = 0;
KEY = [KEY, pc, double(m)];
sp = p;
sp(m,:) = Inf;
SORT = [SORT, sp];
anyMiss = anyMiss | m;
endfor
[~, ia, ic] = unique (KEY, "rows");
ng = numel (ia);
grpMiss = anyMiss(ia);
[~, ord] = sortrows (SORT(ia,:));
reps = ia(ord);
grpMiss = grpMiss(ord);
pos = zeros (ng, 1);
pos(ord) = 1:ng;
G = pos(ic);
if (! incMiss && any (grpMiss))
keep = find (! grpMiss);
newId = NaN (ng, 1);
newId(keep) = 1:numel (keep);
G = newId(G);
reps = reps(keep);
ng = numel (keep);
endif
ngroups = ng;
repRows = reps;
endfunction
## Build a single-column grouping proxy for one grouping variable COL: a numeric
## matrix P whose sort order matches COL's value order, together with a logical
## MISS mask flagging the missing elements. Returns an errmsg body emitted by
## the caller. Self-contained: no table dependency.
function [p, miss, errmsg] = gc_col_proxy (col)
p = [];
miss = [];
errmsg = '';
if (isa (col, 'categorical'))
## Categorical groups follow category order (ordinal or reordered), which the
## underlying category codes encode; maps to NaN.
p = double (col)(:);
miss = isnan (p);
elseif (isa (col, 'string') || iscellstr (col) || ischar (col))
c = cellstr (col);
c = c(:);
miss = cellfun (@isempty, c);
[~, ~, ic] = unique (c);
p = ic(:);
elseif (isa (col, 'datetime'))
DV = datevec (col);
nat = any (isnan (DV), 2);
DV(nat,:) = 0;
DV(nat,2:3) = 1;
p = datenum (DV);
p(nat) = NaN;
p = p(:);
miss = isnan (p);
elseif (isa (col, 'duration'))
p = days (col)(:);
miss = isnan (p);
elseif (isa (col, 'calendarDuration'))
p = proxyArray (col);
miss = any (isnan (p), 2);
elseif (isnumeric (col) || islogical (col))
p = double (col)(:);
miss = isnan (p);
else
errmsg = sprintf ("unsupported grouping variable type '%s'.", class (col));
endif
endfunction
## Validate an 'IncludedEdge' binning option VAL for CALLER, returning it
## lowercased as 'left' or 'right'. Self-contained: no table dependency.
function e = check_included_edge (caller, val)
if (isa (val, 'string') && isscalar (val))
val = char (val);
endif
if (! (ischar (val) && isrow (val) ...
&& any (strcmpi (val, {'left', 'right'}))))
error ("%s: 'IncludedEdge' must be 'left' or 'right'.", caller);
endif
e = lower (val);
endfunction
## Group rows by the grouping-variable values GVS (already binned when a
## GROUPBINS argument was given). Returns G (1..NG, NaN excluded), NG, GVALS (a
## 1-by-K cell of typed level-value columns, one per group), and an errmsg body.
## When INCEMPTY is true the unused categories of a categorical or binned grouping
## variable contribute empty groups, from the full Cartesian product of levels.
function [G, ng, gvals, errmsg] = gb_grouping (gvs, incMiss, incEmpty)
errmsg = '';
G = []; ng = 0; gvals = {};
K = numel (gvs);
n = size (gvs{1}, 1);
if (! incEmpty)
[G, ng, repRows, errmsg] = gc_group_rows (gvs, incMiss);
if (! isempty (errmsg))
return;
endif
gvals = cell (1, K);
for j = 1:K
gvals{j} = gvs{j}(repRows, :);
endfor
return;
endif
idxAll = NaN (n, K);
levVals = cell (1, K);
sizes = zeros (1, K);
for j = 1:K
[idx, lv, errmsg] = gb_levels (gvs{j}, incMiss);
if (! isempty (errmsg))
return;
endif
idxAll(:,j) = idx;
levVals{j} = lv;
sizes(j) = size (lv, 1);
endfor
ng = prod (sizes);
lvlOf = ones (ng, K);
period = 1;
for j = K:-1:1
lvlOf(:,j) = mod (floor ((0:ng-1)' / period), sizes(j)) + 1;
period = period * sizes(j);
endfor
valid = all (! isnan (idxAll), 2);
lin = zeros (n, 1);
period = 1;
for j = K:-1:1
col = idxAll(:,j);
col(isnan (col)) = 1;
lin = lin + (col - 1) * period;
period = period * sizes(j);
endfor
G = NaN (n, 1);
G(valid) = lin(valid) + 1;
gvals = cell (1, K);
for j = 1:K
gvals{j} = levVals{j}(lvlOf(:,j), :);
endfor
endfunction
## Build the level structure of one grouping variable COL for empty-group-aware
## grouping: IDX (n-by-1 level index, NaN excluded), LEVVALS (one representative
## value per level), and an errmsg body. A categorical uses its full category
## order; a missing value forms one extra level, sorted last, when INCMISS.
function [idx, levVals, errmsg] = gb_levels (col, incMiss)
idx = []; levVals = []; errmsg = '';
n = size (col, 1);
[p, miss, errmsg] = gc_col_proxy (col);
if (! isempty (errmsg))
return;
endif
if (isa (col, 'categorical'))
cats = categories (col);
L = numel (cats);
idx = double (col)(:);
levVals = categorical (cats(:), cats, 'Ordinal', isordinal (col));
else
idx = NaN (n, 1);
keep = find (! miss);
if (isempty (keep))
levVals = col([], :);
L = 0;
else
[~, ia, ic] = unique (p(keep,:), "rows");
idx(keep) = ic;
levVals = col(keep(ia), :);
L = numel (ia);
endif
endif
if (any (miss))
if (incMiss)
L = L + 1;
idx(miss) = L;
mrow = find (miss, 1);
levVals = [levVals; col(mrow, :)];
else
idx(miss) = NaN;
endif
endif
endfunction
%!assert_equal (groupcounts ([1; 1; 2; 2; 1]), [3; 2])
%!assert_equal (groupcounts ([30; 10; 10; 20]), [2; 1; 1])
%!test
%! ## The second and third outputs are the group values and the percentages
%! [B, BG, BP] = groupcounts ([1; 1; 2; 2; 1]);
%! assert_equal (B, [3; 2]);
%! assert_equal (BG, [1; 2]);
%! assert_equal (BP, [60; 40]);
%!test
%! ## Groups follow the sorted unique order of the values
%! [B, BG, BP] = groupcounts ([1; 1; 2; 2; 3; 5; 3; 3; 1; 4]);
%! assert_equal (B, [3; 2; 3; 1; 1]);
%! assert_equal (BG, [1; 2; 3; 4; 5]);
%! assert_equal (BP, [30; 20; 30; 10; 10]);
%!test
%! ## A matrix groups by the unique combinations of its columns
%! [B, BG, BP] = groupcounts ([1 0; 1 0; 1 1; 2 1]);
%! assert_equal (B, [2; 1; 1]);
%! assert_equal (BG, {[1; 1; 2], [0; 1; 1]});
%! assert_equal (BP, [50; 25; 25]);
%!test
%! ## A cell array of vectors groups by the unique combinations, BG a cell array
%! [B, BG, BP] = groupcounts ({[1; 1; 2; 2; 1], {'b'; 'a'; 'a'; 'b'; 'b'}});
%! assert_equal (B, [1; 2; 1; 1]);
%! assert_equal (BG, {[1; 1; 2; 2], {'a'; 'b'; 'a'; 'b'}});
%! assert_equal (BP, [20; 40; 20; 20]);
%!test
%! ## A missing value forms its own group, sorted last
%! [B, BG, BP] = groupcounts ([1; 1; 2; NaN; 2]);
%! assert_equal (B, [2; 2; 1]);
%! assert_equal (BG, [1; 2; NaN]);
%! assert_equal (BP, [40; 40; 20]);
%!test
%! ## 'IncludeMissingGroups' false drops the rows with a missing grouping value
%! [B, BG] = groupcounts ([1; 1; 2; NaN; 2], 'IncludeMissingGroups', false);
%! assert_equal (B, [2; 2]);
%! assert_equal (BG, [1; 2]);
%!test
%! ## A categorical vector groups by category order, not alphabetically
%! c = categorical ({'medium'; 'low'; 'high'; 'low'}, ...
%! {'low', 'medium', 'high'}, 'Ordinal', true);
%! [B, BG] = groupcounts (c);
%! assert_equal (B, [2; 1; 1]);
%! assert_equal (cellstr (BG), {'low'; 'medium'; 'high'});
%!test
%! ## A GROUPBINS edge vector groups a numeric variable by bin interval
%! [B, BG, BP] = groupcounts ([1; 3; 5; 7; 9; 11], [0 6 12]);
%! assert_equal (B, [3; 3]);
%! assert_equal (iscategorical (BG), true);
%! assert_equal (cellstr (BG), {'[0, 6)'; '[6, 12]'});
%! assert_equal (BP, [50; 50]);
%!test
%! ## A GROUPBINS number of bins makes equal-width bins over the data range
%! [B, BG] = groupcounts ([1; 2; 3; 4], 3);
%! assert_equal (cellstr (BG), {'[1, 2)'; '[2, 3)'; '[3, 4]'});
%! assert_equal (B, [1; 1; 2]);
%!test
%! ## 'IncludeEmptyGroups' adds unused categorical categories with zero count
%! c = categorical ({'a'; 'a'; 'b'}, {'a', 'b', 'c'});
%! [B, BG] = groupcounts (c, 'IncludeEmptyGroups', true);
%! assert_equal (cellstr (BG), {'a'; 'b'; 'c'});
%! assert_equal (B, [2; 1; 0]);
%!error groupcounts ()
%!error ...
%! groupcounts ([1; 2], 'bogus')
%!error ...
%! groupcounts ([1; 2], 2, 'IncludedEdge', 'mid')
%!error ...
%! groupcounts ([1; 2], 'month')
%!error ...
%! groupcounts ({[1; 2; 3], [1; 2]})
pr0m1th3as-datatypes-9c9a8d3/inst/groupfilter.m 0000664 0000000 0000000 00000031451 15227665741 0021556 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} groupfilter (@var{A}, @var{groupvars}, @var{method})
## @deftypefnx {datatypes} {@var{B} =} groupfilter (@var{A}, @var{groupvars}, @var{groupbins}, @var{method})
## @deftypefnx {datatypes} {[@var{B}, @var{BG}] =} groupfilter (@dots{})
##
## Filter the rows of an array by a per-group condition.
##
## @code{@var{B} = groupfilter (@var{A}, @var{groupvars}, @var{method})} groups
## the rows of the array @var{A} by the grouping variables @var{groupvars},
## applies the filter function @var{method} to each group, and returns @var{B},
## the rows of @var{A} that satisfy the condition, in their original order.
## @var{groupvars} is a grouping vector with one element per row of @var{A}, or a
## cell array of such vectors. Rows holding a missing value in a grouping
## variable form their own groups, to which @var{method} is applied like any
## other group.
##
## @var{method} is a function handle applied to each group's slice of every
## column of @var{A}. It must return either a logical scalar, which keeps or
## drops the whole group, or a logical vector with one element per row of the
## group, which keeps or drops the individual rows. A row is kept only when the
## condition holds for it across all columns of @var{A}.
##
## @code{[@var{B}, @var{BG}] = groupfilter (@dots{})} also returns @var{BG}, the
## grouping values of the kept rows. When @var{groupvars} is a single grouping
## vector, @var{BG} is a column vector with one element per kept row; when several
## grouping variables are given, @var{BG} is a cell array with one element per
## grouping variable.
##
## The optional @var{groupbins} argument bins the grouping variables before
## grouping (a vector of bin edges or a positive integer number of bins, or a
## cell array with one scheme per grouping variable); see @code{groupsummary} for
## details. The @qcode{'IncludedEdge'} Name-Value pair (@qcode{'left'} by
## default, or @qcode{'right'}) selects which bin edge is inclusive.
##
## To filter the rows of a @code{table}, call @code{groupfilter (@var{T},
## @var{groupvars}, @dots{})}, which dispatches to the @code{table} method and
## returns the result as a table.
##
## @seealso{groupsummary, groupcounts, findgroups, splitapply, table}
## @end deftypefn
function [B, varargout] = groupfilter (A, groupvars, varargin)
if (nargin < 3)
print_usage ();
endif
## Split off a trailing 'IncludedEdge' Name-Value option, then an optional
## GROUPBINS positional argument that precedes the filter function METHOD.
args = varargin;
optNames = {'IncludedEdge'};
nvStart = numel (args) + 1;
for k = 1:numel (args)
a = args{k};
if (((ischar (a) && isrow (a)) || (isa (a, 'string') && isscalar (a)))
&& any (strcmpi (char (a), optNames)))
nvStart = k;
break;
endif
endfor
nvArgs = args(nvStart:end);
args = args(1:nvStart-1);
incEdge = parsePairedArguments (optNames, {'left'}, nvArgs(:));
incEdge = check_included_edge ('groupfilter', incEdge);
hasGB = false;
groupbins = [];
if (! isempty (args) && __groupbins__ ('is_spec', args{1}))
hasGB = true;
groupbins = args{1};
args = args(2:end);
endif
if (isempty (args))
print_usage ();
endif
method = args{1};
if (! is_function_handle (method))
error ("groupfilter: METHOD must be a function handle.");
endif
if (numel (args) > 1)
error ("groupfilter: too many positional arguments.");
endif
## Force the grouping variables to a cell array of column vectors.
if (iscell (groupvars)
&& ! (iscellstr (groupvars) && isvector (groupvars)))
gvs = groupvars(:)';
else
gvs = {groupvars};
endif
n = size (A, 1);
for j = 1:numel (gvs)
g = gvs{j};
if (ischar (g))
if (ndims (g) > 2)
error ("groupfilter: grouping variables must be vectors.");
endif
elseif (isvector (g) || isempty (g))
gvs{j} = g(:);
else
error ("groupfilter: grouping variables must be vectors.");
endif
if (size (gvs{j}, 1) != n)
error (strcat ("groupfilter: each grouping variable must have one", ...
" element per row of A."));
endif
endfor
## Bin the grouping variables when a GROUPBINS argument was given.
if (hasGB)
names = cell (1, numel (gvs));
for j = 1:numel (gvs)
names{j} = sprintf ("%d", j);
endfor
[gvs, ~, errmsg] = __groupbins__ ('bin', gvs, names, groupbins, incEdge, ...
'groupfilter');
if (! isempty (errmsg))
error ("groupfilter: %s", errmsg);
endif
endif
## Group the rows, treating missing grouping values as their own groups so
## that every row belongs to exactly one group.
[Grp, ng, errmsg] = gf_group_rows (gvs);
if (! isempty (errmsg))
error ("groupfilter: %s", errmsg);
endif
## Build the row keep-mask by applying METHOD to each column of A.
dataCols = cell (1, size (A, 2));
for c = 1:size (A, 2)
dataCols{c} = A(:,c);
endfor
[keep, errmsg] = gf_keep_mask (method, dataCols, Grp, ng);
if (! isempty (errmsg))
error ("groupfilter: %s", errmsg);
endif
B = A(keep,:);
## Optional output: the grouping values of the kept rows.
if (nargout > 1)
if (numel (gvs) == 1)
BG = gvs{1}(keep,:);
else
BG = cell (1, numel (gvs));
for j = 1:numel (gvs)
BG{j} = gvs{j}(keep,:);
endfor
endif
varargout{1} = BG;
endif
endfunction
## Build the row keep-mask by applying the filter function METHOD to each data
## column's per-group slice. DATACOLS is a cell array of column values; G the
## n-by-1 group numbers (1..NG), every row assigned to a group. For each group
## METHOD receives the slice and must return a logical scalar (keep/drop the
## whole group) or a logical vector with one element per group row. The
## per-column masks are combined with logical AND. Returns KEEP (n-by-1
## logical) and an errmsg body emitted by the caller. Self-contained.
function [keep, errmsg] = gf_keep_mask (method, dataCols, G, ng)
errmsg = '';
n = numel (G);
keep = true (n, 1);
for d = 1:numel (dataCols)
col = dataCols{d};
for g = 1:ng
rows = find (G == g);
if (isempty (rows))
continue;
endif
r = method (col(rows,:));
if (! (islogical (r) || isnumeric (r)))
errmsg = "the filter function must return a logical result.";
return;
endif
r = logical (r(:));
if (isscalar (r))
m = repmat (r, numel (rows), 1);
elseif (numel (r) == numel (rows))
m = r;
else
errmsg = strcat ("the filter function must return a logical scalar", ...
" or a logical vector with one element per group", ...
" row.");
return;
endif
keep(rows) = keep(rows) & m;
endfor
endfor
endfunction
## Group rows by the grouping-variable values GVS (a cell array of column
## vectors), treating each variable's missing values as a single group value so
## that every row is assigned to a group. Returns G (1..NGROUPS), NGROUPS, and
## an errmsg body emitted by the caller. Self-contained: no table dependency.
function [G, ngroups, errmsg] = gf_group_rows (gvs)
errmsg = '';
G = [];
ngroups = 0;
n = size (gvs{1}, 1);
KEY = [];
for j = 1:numel (gvs)
[p, m, e] = gf_col_proxy (gvs{j});
if (! isempty (e))
errmsg = e;
return;
endif
pc = p;
pc(m,:) = 0;
KEY = [KEY, pc, double(m)];
endfor
[~, ~, ic] = unique (KEY, "rows");
G = ic;
ngroups = max (ic);
endfunction
## Build a single-column grouping proxy for one grouping variable COL: a numeric
## matrix P whose value order matches COL's, together with a logical MISS mask
## flagging the missing elements. Returns an errmsg body emitted by the caller.
## Self-contained: no table dependency.
function [p, miss, errmsg] = gf_col_proxy (col)
p = [];
miss = [];
errmsg = '';
if (isa (col, 'categorical'))
p = double (col)(:);
miss = isnan (p);
elseif (isa (col, 'string') || iscellstr (col) || ischar (col))
c = cellstr (col);
c = c(:);
miss = cellfun (@isempty, c);
[~, ~, ic] = unique (c);
p = ic(:);
elseif (isa (col, 'datetime'))
DV = datevec (col);
nat = any (isnan (DV), 2);
DV(nat,:) = 0;
DV(nat,2:3) = 1;
p = datenum (DV);
p(nat) = NaN;
p = p(:);
miss = isnan (p);
elseif (isa (col, 'duration'))
p = days (col)(:);
miss = isnan (p);
elseif (isa (col, 'calendarDuration'))
p = proxyArray (col);
miss = any (isnan (p), 2);
elseif (isnumeric (col) || islogical (col))
p = double (col)(:);
miss = isnan (p);
else
errmsg = sprintf ("unsupported grouping variable type '%s'.", class (col));
endif
endfunction
## Validate an 'IncludedEdge' binning option VAL for CALLER, returning it
## lowercased as 'left' or 'right'. Self-contained: no table dependency.
function e = check_included_edge (caller, val)
if (isa (val, 'string') && isscalar (val))
val = char (val);
endif
if (! (ischar (val) && isrow (val) ...
&& any (strcmpi (val, {'left', 'right'}))))
error ("%s: 'IncludedEdge' must be 'left' or 'right'.", caller);
endif
e = lower (val);
endfunction
%!test
%! ## A scalar-returning method keeps or drops whole groups
%! g = [1; 1; 1; 2; 2; 3];
%! x = [3; 1; 2; 9; 8; 5];
%! assert_equal (groupfilter (x, g, @(v) numel (v) > 2), [3; 1; 2]);
%!test
%! ## A vector-returning method keeps individual rows within each group
%! d = [1; 1; 1; 1; 2; 2; 2; 2];
%! t = [67; 65; 71; 55; 61; 79; 58; 78];
%! assert_equal (groupfilter (t, d, @(x) x == max (x)), [71; 79]);
%!test
%! ## Output rows keep their original order, not group order
%! g = [2; 1; 2; 1];
%! x = [1; 2; 3; 4];
%! assert_equal (groupfilter (x, g, @(v) numel (v) >= 1), [1; 2; 3; 4]);
%!test
%! ## The second output returns the grouping values of the kept rows
%! d = [1; 1; 1; 1; 2; 2; 2; 2];
%! t = [67; 65; 71; 55; 61; 79; 58; 78];
%! [B, BG] = groupfilter (t, d, @(x) x == max (x));
%! assert_equal (B, [71; 79]);
%! assert_equal (BG, [1; 2]);
%!test
%! ## A matrix groups by its grouping vector; a row is kept only when the
%! ## condition holds across all columns of A
%! A = [5 1; 1 9; 9 1; 2 9];
%! g = [1; 1; 2; 2];
%! assert_equal (groupfilter (A, g, @(v) v > 3), zeros (0, 2));
%!test
%! ## Rows with a missing grouping value form their own group and are filtered
%! g = [1; 1; NaN; 2; 2];
%! x = [10; 20; 30; 40; 50];
%! [B, BG] = groupfilter (x, g, @(v) mean (v) > 25);
%! assert_equal (B, [30; 40; 50]);
%! assert_equal (BG, [NaN; 2; 2]);
%!test
%! ## Several grouping vectors return BG as a cell array, one per variable
%! x = [3; 1; 9; 2; 8];
%! g1 = [1; 1; 2; 2; 1];
%! g2 = {'a'; 'a'; 'b'; 'b'; 'a'};
%! [B, BG] = groupfilter (x, {g1, g2}, @(v) v == max (v));
%! assert_equal (B, [9; 8]);
%! assert_equal (BG, {[2; 1], {'b'; 'a'}});
%!test
%! ## A categorical grouping vector groups by category
%! c = categorical ({'a'; 'b'; 'a'; 'b'; 'a'});
%! x = [1; 5; 2; 6; 9];
%! [B, BG] = groupfilter (x, c, @(v) v == max (v));
%! assert_equal (B, [6; 9]);
%! assert_equal (cellstr (BG), {'b'; 'a'});
%!test
%! ## A GROUPBINS edge vector filters within bins of a numeric grouping variable
%! x = (1:6)';
%! g = [1; 3; 5; 7; 9; 11];
%! B = groupfilter (x, g, [0 6 12], @(v) numel (v) > 2);
%! assert_equal (B, (1:6)');
%! B2 = groupfilter (x, g, [0 6 12], @(v) mean (v) > 4, 'IncludedEdge', 'right');
%! assert_equal (B2, [4; 5; 6]);
%!error groupfilter ([1; 2], [1; 2])
%!error ...
%! groupfilter ([1; 2], [1; 2], 'sum')
%!error ...
%! groupfilter ([1; 2], [1; 2], 'month', @(x) x > 0)
%!error ...
%! groupfilter ([1; 2], [1; 2], @(x) x > 0, 5)
%!error ...
%! groupfilter ([1; 2; 3], [1; 2], @(x) x > 0)
%!error ...
%! groupfilter ([1; 1], [1; 1], @(x) [true; true; true])
pr0m1th3as-datatypes-9c9a8d3/inst/groupsummary.m 0000664 0000000 0000000 00000054410 15227665741 0021766 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} groupsummary (@var{A}, @var{groupvars}, @var{method})
## @deftypefnx {datatypes} {@var{B} =} groupsummary (@var{A}, @var{groupvars}, @var{groupbins}, @var{method})
## @deftypefnx {datatypes} {[@var{B}, @var{BG}, @var{BC}] =} groupsummary (@dots{})
##
## Compute summary statistics by group for an array.
##
## @code{@var{B} = groupsummary (@var{A}, @var{groupvars}, @var{method})} groups
## the rows of the array @var{A} by the grouping variables @var{groupvars} and
## applies @var{method} to each column of @var{A} within each group, returning
## the results in @var{B}, which has one row per group. @var{groupvars} is a
## grouping vector with one element per row of @var{A}, or a cell array of such
## vectors. Groups are the sorted unique combinations of grouping values; rows
## holding a missing value in a grouping variable form their own groups, sorted
## after the non-missing groups.
##
## @var{method} is one of the names @qcode{'sum'}, @qcode{'mean'},
## @qcode{'median'}, @qcode{'mode'}, @qcode{'var'}, @qcode{'std'}, @qcode{'min'},
## @qcode{'max'}, @qcode{'range'}, @qcode{'nnz'}, @qcode{'nummissing'}, or
## @qcode{'numunique'}, a function handle, or a cell
## array of method names and@/or function handles. @code{NaN} values are omitted
## for every named method except @qcode{'nummissing'}; a function handle receives
## the values with @code{NaN} included and must return a single row. When
## several methods are requested the columns of @var{B} are ordered by column of
## @var{A} first, then by method.
##
## @code{[@var{B}, @var{BG}, @var{BC}] = groupsummary (@dots{})} also returns
## @var{BG}, the grouping values that identify each group, and @var{BC}, a column
## vector with the number of rows in each group. When @var{groupvars} is a
## single grouping vector, @var{BG} holds its representative value for each group;
## when several grouping variables are given, @var{BG} is a cell array with one
## element per grouping variable.
##
## The optional @var{groupbins} argument bins the grouping variables before
## grouping: a vector of bin edges or a positive integer number of equal-width
## bins, applied to a numeric, datetime, or duration grouping variable, or a cell
## array with one scheme per grouping variable. Each binned variable becomes a
## categorical of bin interval labels.
##
## The behaviour can be modified with the @qcode{'IncludeMissingGroups'} (default
## @code{true}), @qcode{'IncludeEmptyGroups'} (default @code{false}), and
## @qcode{'IncludedEdge'} (default @qcode{'left'}, the inclusive bin edge)
## @var{Name}/@var{Value} pairs, as for the @code{table} method. When
## @qcode{'IncludeEmptyGroups'} is @code{true}, the unused categories of a
## categorical or binned grouping variable contribute empty groups.
##
## To summarise the variables of a @code{table}, call @code{groupsummary
## (@var{T}, @var{groupvars}, @dots{})}, which dispatches to the @code{table}
## method and returns the result as a table.
##
## @seealso{findgroups, splitapply, table}
## @end deftypefn
function [B, varargout] = groupsummary (A, groupvars, varargin)
if (nargin < 3)
print_usage ();
endif
## An optional GROUPBINS positional argument precedes the method; the method is
## the next trailing argument, and the rest are Name-Value pairs.
args = varargin;
hasGB = false;
groupbins = [];
if (! isempty (args) && __groupbins__ ('is_spec', args{1}))
hasGB = true;
groupbins = args{1};
args = args(2:end);
endif
if (isempty (args))
print_usage ();
endif
method = args{1};
nvArgs = args(2:end);
optNames = {'IncludeMissingGroups', 'IncludeEmptyGroups', 'IncludedEdge'};
dfValues = {true, false, 'left'};
[incMiss, incEmpty, incEdge] = ...
parsePairedArguments (optNames, dfValues, nvArgs(:));
if (! (isscalar (incMiss) && (islogical (incMiss) || isnumeric (incMiss))))
error ("groupsummary: 'IncludeMissingGroups' must be a logical scalar.");
endif
incMiss = logical (incMiss);
if (! (isscalar (incEmpty) && (islogical (incEmpty) || isnumeric (incEmpty))))
error ("groupsummary: 'IncludeEmptyGroups' must be a logical scalar.");
endif
incEmpty = logical (incEmpty);
incEdge = check_included_edge ('groupsummary', incEdge);
[methods, methNames, errmsg] = gs_normalise_methods (method);
if (! isempty (errmsg))
error ("groupsummary: %s", errmsg);
endif
if (isempty (methods))
error ("groupsummary: a method is required for array input.");
endif
## Force the grouping variables to a cell array of column vectors.
if (iscell (groupvars)
&& ! (iscellstr (groupvars) && isvector (groupvars)))
gvs = groupvars(:)';
else
gvs = {groupvars};
endif
n = size (A, 1);
for j = 1:numel (gvs)
g = gvs{j};
if (ischar (g))
if (ndims (g) > 2)
error ("groupsummary: grouping variables must be vectors.");
endif
elseif (isvector (g) || isempty (g))
gvs{j} = g(:);
else
error ("groupsummary: grouping variables must be vectors.");
endif
if (size (gvs{j}, 1) != n)
error (strcat ("groupsummary: each grouping variable must have one", ...
" element per row of A."));
endif
endfor
## Bin the grouping variables when a GROUPBINS argument was given.
if (hasGB)
names = cell (1, numel (gvs));
for j = 1:numel (gvs)
names{j} = sprintf ("%d", j);
endfor
[gvs, ~, errmsg] = __groupbins__ ('bin', gvs, names, groupbins, incEdge, ...
'groupsummary');
if (! isempty (errmsg))
error ("groupsummary: %s", errmsg);
endif
endif
## Group the rows, treating missing grouping values as their own groups;
## IncludeEmptyGroups adds the unused categories of a categorical or binned
## grouping variable as empty groups.
[Grp, ng, gvals, errmsg] = gb_grouping (gvs, incMiss, incEmpty);
if (! isempty (errmsg))
error ("groupsummary: %s", errmsg);
endif
## Compute each method over each column of A (column first, then method).
ncol = size (A, 2);
B = [];
for c = 1:ncol
for mi = 1:numel (methods)
vals = cell (ng, 1);
for g = 1:ng
rows = (Grp == g);
[v, errmsg] = gs_apply_method (methods{mi}, A(rows,c));
if (! isempty (errmsg))
error ("groupsummary: %s for column %d of A.", errmsg, c);
endif
vals{g} = v;
endfor
B = [B, vertcat(vals{:})];
endfor
endfor
## Optional outputs: the grouping identifiers and the group counts.
if (nargout > 1)
if (numel (gvs) == 1)
BG = gvals{1};
else
BG = gvals;
endif
varargout{1} = BG;
endif
if (nargout > 2)
varargout{2} = accumarray (Grp(! isnan (Grp)), 1, [ng, 1]);
endif
endfunction
## Normalise the METHOD argument into a cell array of method specs METHODS (each
## a method-name char vector or a function handle) and a parallel cell array of
## display names METHNAMES. Returns an errmsg body emitted by the caller.
## Self-contained: no table dependency.
function [methods, methNames, errmsg] = gs_normalise_methods (method)
methods = {};
methNames = {};
errmsg = '';
if (isempty (method) && ! iscell (method) && ! ischar (method)
&& ! is_function_handle (method))
return;
endif
if (is_function_handle (method) || (ischar (method) && isrow (method))
|| isa (method, 'string'))
items = {method};
elseif (iscell (method))
items = method(:)';
else
errmsg = strcat ("METHOD must be a method name, a function handle, or a", ...
" cell array of method names and function handles.");
return;
endif
known = {'sum', 'mean', 'median', 'mode', 'var', 'std', 'min', 'max', ...
'range', 'nnz', 'nummissing', 'numunique'};
nfun = 0;
for k = 1:numel (items)
it = items{k};
if (is_function_handle (it))
nfun++;
methods{end+1} = it;
methNames{end+1} = sprintf ("fun%d", nfun);
elseif ((ischar (it) && isrow (it)) || (isa (it, 'string') && isscalar (it)))
nm = lower (char (it));
if (! any (strcmp (nm, known)))
errmsg = sprintf ("'%s' is not a supported method name.", char (it));
return;
endif
methods{end+1} = nm;
methNames{end+1} = nm;
else
errmsg = strcat ("each method must be a method name or a function", ...
" handle.");
return;
endif
endfor
endfunction
## Group rows by the grouping-variable values GVS (a cell array of column
## vectors), treating each variable's missing values as a single group value.
## Returns G (1..NGROUPS), NGROUPS, REPROWS (a representative row per group), and
## an errmsg body. Groups are sorted by value with missing groups last; when
## INCMISS is false the rows with a missing grouping value are dropped.
function [G, ngroups, repRows, errmsg] = gs_group_rows (gvs, incMiss)
errmsg = '';
G = [];
ngroups = 0;
repRows = [];
n = size (gvs{1}, 1);
KEY = [];
SORT = [];
anyMiss = false (n, 1);
for j = 1:numel (gvs)
[p, m, e] = group_col_proxy (gvs{j});
if (! isempty (e))
errmsg = e;
return;
endif
pc = p;
pc(m,:) = 0;
KEY = [KEY, pc, double(m)];
sp = p;
sp(m,:) = Inf;
SORT = [SORT, sp];
anyMiss = anyMiss | m;
endfor
[~, ia, ic] = unique (KEY, "rows");
ng = numel (ia);
grpMiss = anyMiss(ia);
[~, ord] = sortrows (SORT(ia,:));
reps = ia(ord);
grpMiss = grpMiss(ord);
pos = zeros (ng, 1);
pos(ord) = 1:ng;
G = pos(ic);
if (! incMiss && any (grpMiss))
keep = find (! grpMiss);
newId = NaN (ng, 1);
newId(keep) = 1:numel (keep);
G = newId(G);
reps = reps(keep);
ng = numel (keep);
endif
ngroups = ng;
repRows = reps;
endfunction
## Build a single-column grouping proxy for one grouping variable COL: a numeric
## matrix P whose sort order matches COL's value order, together with a logical
## MISS mask flagging the missing elements. Returns an errmsg body emitted by
## the caller. Self-contained: no table dependency.
function [p, miss, errmsg] = group_col_proxy (col)
p = [];
miss = [];
errmsg = '';
if (isa (col, 'categorical'))
## Categorical groups follow category order (ordinal or reordered), which the
## underlying category codes encode; maps to NaN.
p = double (col)(:);
miss = isnan (p);
elseif (isa (col, 'string') || iscellstr (col) || ischar (col))
c = cellstr (col);
c = c(:);
miss = cellfun (@isempty, c);
[~, ~, ic] = unique (c);
p = ic(:);
elseif (isa (col, 'datetime'))
DV = datevec (col);
nat = any (isnan (DV), 2);
DV(nat,:) = 0;
DV(nat,2:3) = 1;
p = datenum (DV);
p(nat) = NaN;
p = p(:);
miss = isnan (p);
elseif (isa (col, 'duration'))
p = days (col)(:);
miss = isnan (p);
elseif (isa (col, 'calendarDuration'))
p = proxyArray (col);
miss = any (isnan (p), 2);
elseif (isnumeric (col) || islogical (col))
p = double (col)(:);
miss = isnan (p);
else
errmsg = sprintf ("unsupported grouping variable type '%s'.", class (col));
endif
endfunction
## Apply a single method M (a method-name char vector or a function handle) to
## the column slice X of one group, returning a row result V. Named methods omit
## missing values (except 'nummissing'); a function handle receives X unchanged
## and must return a single row. Returns an errmsg body emitted by the caller.
function [v, errmsg] = gs_apply_method (m, x)
v = [];
errmsg = '';
if (is_function_handle (m))
v = m (x);
if (size (v, 1) != 1)
errmsg = "a function handle method must return a single row";
endif
return;
endif
if (strcmp (m, 'nummissing'))
v = sum (gs_missing_mask (x), 1);
return;
endif
if (strcmp (m, 'numunique'))
miss = gs_missing_mask (x);
if (size (x, 2) == 1)
v = numel (unique (x(! miss,:)));
else
v = zeros (1, size (x, 2));
for c = 1:size (x, 2)
col = x(:,c);
v(c) = numel (unique (col(! miss(:,c))));
endfor
endif
return;
endif
if (! (isnumeric (x) || islogical (x)))
errmsg = sprintf (strcat ("named method '%s' is not supported for data", ...
" of type '%s'; use a function handle"), m, ...
class (x));
return;
endif
x = double (x);
## An empty group (e.g. an unused IncludeEmptyGroups category) takes the
## method's empty value: 0 for the additive 'sum'/'nnz', NaN otherwise.
if (rows (x) == 0)
if (any (strcmp (m, {'sum', 'nnz'})))
v = zeros (1, columns (x));
else
v = NaN (1, columns (x));
endif
return;
endif
nan = isnan (x);
cnt = sum (! nan, 1);
z = x;
z(nan) = 0;
switch (m)
case 'sum'
v = sum (z, 1);
case 'mean'
v = sum (z, 1) ./ cnt;
case 'min'
v = min (x, [], 1);
case 'max'
v = max (x, [], 1);
case 'range'
v = max (x, [], 1) - min (x, [], 1);
case 'nnz'
v = sum (x != 0 & ! nan, 1);
case {'median', 'mode', 'var', 'std'}
v = NaN (1, size (x, 2));
for c = 1:size (x, 2)
col = x(! nan(:,c), c);
if (! isempty (col))
switch (m)
case 'median'
v(c) = median (col);
case 'mode'
v(c) = mode (col);
case 'var'
v(c) = var (col);
case 'std'
v(c) = std (col);
endswitch
endif
endfor
endswitch
endfunction
## Return a logical mask the size of X flagging its missing elements. Supports
## the numeric, logical, text, datetime, duration, calendarDuration, and
## categorical types. Self-contained: no table dependency.
function mask = gs_missing_mask (x)
if (isa (x, 'datetime'))
DV = datevec (x);
mask = any (isnan (DV), 2);
mask = reshape (mask, size (x, 1), size (x, 2));
elseif (isa (x, 'duration'))
mask = isnan (days (x));
elseif (isa (x, 'calendarDuration'))
mask = any (isnan (proxyArray (x)), 2);
elseif (isa (x, 'categorical') || isa (x, 'string'))
mask = ismissing (x);
elseif (iscellstr (x))
mask = cellfun (@isempty, x);
elseif (islogical (x))
mask = false (size (x));
elseif (isnumeric (x))
mask = isnan (x);
else
mask = false (size (x));
endif
endfunction
## Validate an 'IncludedEdge' binning option VAL for CALLER, returning it
## lowercased as 'left' or 'right'. Self-contained: no table dependency.
function e = check_included_edge (caller, val)
if (isa (val, 'string') && isscalar (val))
val = char (val);
endif
if (! (ischar (val) && isrow (val) ...
&& any (strcmpi (val, {'left', 'right'}))))
error ("%s: 'IncludedEdge' must be 'left' or 'right'.", caller);
endif
e = lower (val);
endfunction
## Group rows by the grouping-variable values GVS (already binned when a
## GROUPBINS argument was given). Returns G (1..NG, NaN for an excluded row),
## NG, GVALS (a 1-by-K cell of the typed level-value columns, one per group), and
## an errmsg body. When INCEMPTY is true the unused categories of a categorical
## or binned grouping variable contribute empty groups, built from the full
## Cartesian product of the per-variable levels; otherwise only the observed
## groups are returned.
function [G, ng, gvals, errmsg] = gb_grouping (gvs, incMiss, incEmpty)
errmsg = '';
G = []; ng = 0; gvals = {};
K = numel (gvs);
n = size (gvs{1}, 1);
if (! incEmpty)
[G, ng, repRows, errmsg] = gs_group_rows (gvs, incMiss);
if (! isempty (errmsg))
return;
endif
gvals = cell (1, K);
for j = 1:K
gvals{j} = gvs{j}(repRows, :);
endfor
return;
endif
idxAll = NaN (n, K);
levVals = cell (1, K);
sizes = zeros (1, K);
for j = 1:K
[idx, lv, errmsg] = gb_levels (gvs{j}, incMiss);
if (! isempty (errmsg))
return;
endif
idxAll(:,j) = idx;
levVals{j} = lv;
sizes(j) = size (lv, 1);
endfor
ng = prod (sizes);
lvlOf = ones (ng, K);
period = 1;
for j = K:-1:1
lvlOf(:,j) = mod (floor ((0:ng-1)' / period), sizes(j)) + 1;
period = period * sizes(j);
endfor
valid = all (! isnan (idxAll), 2);
lin = zeros (n, 1);
period = 1;
for j = K:-1:1
col = idxAll(:,j);
col(isnan (col)) = 1;
lin = lin + (col - 1) * period;
period = period * sizes(j);
endfor
G = NaN (n, 1);
G(valid) = lin(valid) + 1;
gvals = cell (1, K);
for j = 1:K
gvals{j} = levVals{j}(lvlOf(:,j), :);
endfor
endfunction
## Build the level structure of one grouping variable COL for empty-group-aware
## grouping: IDX (n-by-1 level index, NaN for an excluded row), LEVVALS (a typed
## column of one representative value per level), and an errmsg body. A
## categorical uses its full category order (so unused categories are levels); a
## missing value forms one extra level, sorted last, when INCMISS is true.
function [idx, levVals, errmsg] = gb_levels (col, incMiss)
idx = []; levVals = []; errmsg = '';
n = size (col, 1);
[p, miss, errmsg] = group_col_proxy (col);
if (! isempty (errmsg))
return;
endif
if (isa (col, 'categorical'))
cats = categories (col);
L = numel (cats);
idx = double (col)(:);
levVals = categorical (cats(:), cats, 'Ordinal', isordinal (col));
else
idx = NaN (n, 1);
keep = find (! miss);
if (isempty (keep))
levVals = col([], :);
L = 0;
else
[~, ia, ic] = unique (p(keep,:), "rows");
idx(keep) = ic;
levVals = col(keep(ia), :);
L = numel (ia);
endif
endif
if (any (miss))
if (incMiss)
L = L + 1;
idx(miss) = L;
mrow = find (miss, 1);
levVals = [levVals; col(mrow, :)];
else
idx(miss) = NaN;
endif
endif
endfunction
%!assert_equal (groupsummary ([10; 20; 30; 40], [1; 1; 2; 2], 'mean'), [15; 35])
%!assert_equal (groupsummary ([10; 20; 30; 40], [1; 1; 2; 2], 'sum'), [30; 70])
%!test
%! ## Multiple outputs return the group identifiers and the group counts
%! [B, BG, BC] = groupsummary ([10; 20; 30; 40], [1; 1; 2; 2], 'mean');
%! assert_equal (B, [15; 35]);
%! assert_equal (BG, [1; 2]);
%! assert_equal (BC, [2; 2]);
%!test
%! ## A matrix is summarised column by column
%! assert_equal (groupsummary ([10 1; 20 2; 30 3; 40 4], [1; 1; 2; 2], 'sum'), ...
%! [30, 3; 70, 7]);
%!test
%! ## Several methods order the columns of B by data column first, then method
%! B = groupsummary ([10; 20; 30; 40], [1; 1; 2; 2], {'mean', 'sum'});
%! assert_equal (B, [15, 30; 35, 70]);
%!test
%! ## Named methods omit NaN in the data
%! assert_equal (groupsummary ([10; 20; NaN; 40], [1; 1; 2; 2], 'mean'), [15; 40]);
%!test
%! ## A missing value in a grouping variable forms its own group, sorted last
%! [B, BG, BC] = groupsummary ([10; 20; 30; 40], [1; 1; NaN; 2], 'mean');
%! assert_equal (B, [15; 40; 30]);
%! assert_equal (BG, [1; 2; NaN]);
%! assert_equal (BC, [2; 1; 1]);
%!test
%! ## 'IncludeMissingGroups' false drops the rows with a missing grouping value
%! B = groupsummary ([10; 20; 30; 40], [1; 1; NaN; 2], 'mean', ...
%! 'IncludeMissingGroups', false);
%! assert_equal (B, [15; 40]);
%!test
%! ## A function handle is applied to each group's slice
%! B = groupsummary ([10; 20; 30; 40], [1; 1; 2; 2], @(v) max (v) - min (v));
%! assert_equal (B, [10; 10]);
%!test
%! ## Several grouping vectors return BG as a cell array, one per variable
%! [B, BG, BC] = groupsummary ([10; 20; 30; 40; 50], ...
%! {[1; 1; 2; 2; 1], {'b'; 'a'; 'a'; 'b'; 'b'}}, 'sum');
%! assert_equal (B, [20; 60; 30; 40]);
%! assert_equal (BG, {[1; 1; 2; 2], {'a'; 'b'; 'a'; 'b'}});
%! assert_equal (BC, [1; 2; 1; 1]);
%!test
%! ## A categorical grouping vector groups by category order, not alphabetically
%! c = categorical ({'medium'; 'low'; 'high'; 'low'}, ...
%! {'low', 'medium', 'high'}, 'Ordinal', true);
%! [B, BG, BC] = groupsummary ((1:4)', c, 'sum');
%! assert_equal (B, [6; 1; 3]);
%! assert_equal (cellstr (BG), {'low'; 'medium'; 'high'});
%! assert_equal (BC, [2; 1; 1]);
%!test
%! ## A GROUPBINS edge vector groups a numeric variable by bin interval
%! [B, BG, BC] = groupsummary ((1:6)', [1; 3; 5; 7; 9; 11], [0 6 12], 'sum');
%! assert_equal (B, [6; 15]);
%! assert_equal (iscategorical (BG), true);
%! assert_equal (cellstr (BG), {'[0, 6)'; '[6, 12]'});
%! assert_equal (BC, [3; 3]);
%!test
%! ## A GROUPBINS number of bins makes equal-width bins over the data range
%! [B, BG] = groupsummary ((1:4)', [1; 2; 3; 4], 3, 'sum');
%! assert_equal (cellstr (BG), {'[1, 2)'; '[2, 3)'; '[3, 4]'});
%! assert_equal (B, [1; 2; 7]);
%!test
%! ## 'IncludedEdge' 'right' makes the right bin edge the inclusive one
%! [B, BG, BC] = groupsummary ((1:3)', [0; 6; 12], [0 6 12], 'sum', ...
%! 'IncludedEdge', 'right');
%! assert_equal (cellstr (BG), {'[0, 6]'; '(6, 12]'});
%! assert_equal (BC, [2; 1]);
%!test
%! ## 'IncludeEmptyGroups' adds unused categorical categories as empty groups
%! c = categorical ({'a'; 'a'; 'b'}, {'a', 'b', 'c'});
%! [B, BG, BC] = groupsummary ([10; 20; 30], c, 'sum', ...
%! 'IncludeEmptyGroups', true);
%! assert_equal (cellstr (BG), {'a'; 'b'; 'c'});
%! assert_equal (B, [30; 30; 0]);
%! assert_equal (BC, [2; 1; 0]);
%!error groupsummary ([1; 2], [1; 2])
%!error ...
%! groupsummary ([1; 2], [1; 2], 'bogus')
%!error ...
%! groupsummary ([1; 2], [1; 2], 2, 'sum', 'IncludedEdge', 'mid')
%!error ...
%! groupsummary ([1; 2], [1; 2], 'month', 'sum')
%!error ...
%! groupsummary ([1; 2; 3], [1; 2], 'sum')
pr0m1th3as-datatypes-9c9a8d3/inst/grouptransform.m 0000664 0000000 0000000 00000041466 15227665741 0022313 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{B} =} grouptransform (@var{A}, @var{groupvars}, @var{method})
## @deftypefnx {datatypes} {@var{B} =} grouptransform (@var{A}, @var{groupvars}, @var{groupbins}, @var{method})
## @deftypefnx {datatypes} {[@var{B}, @var{BG}] =} grouptransform (@dots{})
## @deftypefnx {datatypes} {[@dots{}] =} grouptransform (@dots{}, @var{Name}, @var{Value})
##
## Transform the columns of an array group by group.
##
## @code{@var{B} = grouptransform (@var{A}, @var{groupvars}, @var{method})}
## groups the rows of the array @var{A} by the grouping variables
## @var{groupvars}, applies @var{method} to each column of @var{A} within each
## group, and returns @var{B}, the transformed values, one row per row of @var{A}
## and in the original order. @var{groupvars} is a grouping vector with one
## element per row of @var{A}, or a cell array of such vectors. Rows holding a
## missing value in a grouping variable form their own groups, which are
## transformed like any other group.
##
## @var{method} is one of the names @qcode{'zscore'}, @qcode{'norm'},
## @qcode{'meancenter'}, @qcode{'rescale'}, @qcode{'meanfill'},
## @qcode{'linearfill'}, or a function handle. @qcode{'zscore'} centers and
## scales each group to zero mean and unit standard deviation; @qcode{'norm'}
## divides by the group 2-norm; @qcode{'meancenter'} subtracts the group mean;
## @qcode{'rescale'} rescales to the range @code{[0, 1]}; @qcode{'meanfill'}
## replaces missing values with the group mean; and @qcode{'linearfill'} fills
## missing values by linear interpolation within the group (leaving leading and
## trailing missing values unchanged). For the named methods @code{NaN} values
## are omitted when computing the group statistics. A function handle is applied
## to each group's column slice and must return either a single row (broadcast)
## or one row per row of the group.
##
## @code{[@var{B}, @var{BG}] = grouptransform (@dots{})} also returns @var{BG},
## the grouping values of each row. When @var{groupvars} is a single grouping
## vector, @var{BG} is that vector; when several grouping variables are given,
## @var{BG} is a cell array with one element per grouping variable.
##
## The @qcode{'ReplaceValues'} @var{Name}/@var{Value} pair (default @code{true})
## controls whether the transformed values replace the columns of @var{A} or, when
## @code{false}, are appended to them. The optional @var{groupbins} argument bins
## the grouping variables before grouping (a vector of bin edges or a positive
## integer number of bins, or a cell array with one scheme per grouping variable);
## see @code{groupsummary} for details. The @qcode{'IncludedEdge'} pair
## (@qcode{'left'} by default, or @qcode{'right'}) selects the inclusive bin edge.
##
## To transform the variables of a @code{table}, call @code{grouptransform
## (@var{T}, @var{groupvars}, @dots{})}, which dispatches to the @code{table}
## method and returns the result as a table.
##
## @seealso{groupsummary, groupfilter, findgroups, splitapply, table}
## @end deftypefn
function [B, varargout] = grouptransform (A, groupvars, varargin)
if (nargin < 3)
print_usage ();
endif
## An optional GROUPBINS positional argument precedes the transform METHOD (a
## known method name or a function handle).
args = varargin;
hasGB = false;
groupbins = [];
if (! isempty (args) && __groupbins__ ('is_spec', args{1}))
hasGB = true;
groupbins = args{1};
args = args(2:end);
endif
if (isempty (args))
print_usage ();
endif
method = args{1};
knownMethods = {'zscore', 'norm', 'meancenter', 'rescale', ...
'meanfill', 'linearfill'};
if (is_function_handle (method))
## ok
elseif (((ischar (method) && isrow (method))
|| (isa (method, 'string') && isscalar (method)))
&& any (strcmpi (char (method), knownMethods)))
method = lower (char (method));
else
error (strcat ("grouptransform: METHOD must be one of 'zscore', 'norm',", ...
" 'meancenter', 'rescale', 'meanfill', 'linearfill', or a", ...
" function handle."));
endif
## Anything after METHOD must be the 'ReplaceValues' or 'IncludedEdge'
## Name-Value pair (the array form has no DATAVARS argument; A's columns are
## the data).
rest = args(2:end);
optNames = {'ReplaceValues', 'IncludedEdge'};
nvStart = numel (rest) + 1;
for k = 1:numel (rest)
a = rest{k};
if (((ischar (a) && isrow (a)) || (isa (a, 'string') && isscalar (a)))
&& any (strcmpi (char (a), optNames)))
nvStart = k;
break;
endif
endfor
if (nvStart > 1)
error ("grouptransform: too many positional arguments.");
endif
dfValues = {true, 'left'};
[replaceVals, incEdge] = parsePairedArguments (optNames, dfValues, rest(:));
if (! (isscalar (replaceVals)
&& (islogical (replaceVals) || isnumeric (replaceVals))))
error ("grouptransform: 'ReplaceValues' must be a logical scalar.");
endif
replaceVals = logical (replaceVals);
incEdge = check_included_edge ('grouptransform', incEdge);
## Force the grouping variables to a cell array of column vectors.
if (iscell (groupvars)
&& ! (iscellstr (groupvars) && isvector (groupvars)))
gvs = groupvars(:)';
else
gvs = {groupvars};
endif
n = size (A, 1);
for j = 1:numel (gvs)
g = gvs{j};
if (ischar (g))
if (ndims (g) > 2)
error ("grouptransform: grouping variables must be vectors.");
endif
elseif (isvector (g) || isempty (g))
gvs{j} = g(:);
else
error ("grouptransform: grouping variables must be vectors.");
endif
if (size (gvs{j}, 1) != n)
error (strcat ("grouptransform: each grouping variable must have one", ...
" element per row of A."));
endif
endfor
## Bin the grouping variables when a GROUPBINS argument was given.
if (hasGB)
names = cell (1, numel (gvs));
for j = 1:numel (gvs)
names{j} = sprintf ("%d", j);
endfor
[gvs, ~, errmsg] = __groupbins__ ('bin', gvs, names, groupbins, incEdge, ...
'grouptransform');
if (! isempty (errmsg))
error ("grouptransform: %s", errmsg);
endif
endif
## Group the rows, treating missing grouping values as their own groups so
## that every row belongs to exactly one group.
[Grp, ng, errmsg] = gt_group_rows (gvs);
if (! isempty (errmsg))
error ("grouptransform: %s", errmsg);
endif
## Transform the columns of A, group by group.
[trans, errmsg] = gt_transform_col (method, A, Grp, ng);
if (! isempty (errmsg))
error ("grouptransform: %s.", errmsg);
endif
if (replaceVals)
B = trans;
else
B = [A, trans];
endif
## Optional output: the grouping values of each row.
if (nargout > 1)
if (numel (gvs) == 1)
BG = gvs{1};
else
BG = gvs;
endif
varargout{1} = BG;
endif
endfunction
## Transform one data column COL (n-by-k) group by group, applying METHOD (a
## transform-name char vector or a function handle) to each group's slice and
## returning OUT the same size as COL. G is the n-by-1 group-number vector
## (1..NG), every row assigned to a group. A function handle must return a
## single row (broadcast) or one row per group row. Returns an errmsg body
## emitted by the caller. Self-contained: no table dependency.
function [out, errmsg] = gt_transform_col (method, col, G, ng)
out = [];
errmsg = '';
if (! (isnumeric (col) || islogical (col)))
errmsg = sprintf (strcat ("grouptransform requires numeric or logical", ...
" data; got '%s'"), class (col));
return;
endif
x = double (col);
out = x;
for g = 1:ng
rows = find (G == g);
if (isempty (rows))
continue;
endif
slice = x(rows,:);
if (is_function_handle (method))
r = method (slice);
if (! (isnumeric (r) || islogical (r)))
errmsg = "the transform function must return a numeric result";
out = [];
return;
endif
if (size (r, 1) == 1)
r = repmat (r, numel (rows), 1);
endif
if (! isequal (size (r), size (slice)))
errmsg = strcat ("the transform function must return a result the", ...
" same size as the group, or a single row");
out = [];
return;
endif
out(rows,:) = r;
else
for c = 1:columns (slice)
out(rows,c) = gt_apply_named (method, slice(:,c));
endfor
endif
endfor
endfunction
## Apply a single named transform METHOD to the column vector X, returning the
## transformed values V the same size as X. NaN values are omitted when
## computing the group statistics; the centring and scaling methods leave NaN in
## place, while 'meanfill'/'linearfill' fill them. Self-contained.
function v = gt_apply_named (method, x)
nan = isnan (x);
xo = x(! nan);
switch (method)
case 'meancenter'
v = x - mean (xo);
case 'zscore'
v = (x - mean (xo)) / std (xo);
case 'norm'
v = x / norm (xo);
case 'rescale'
mn = min (xo);
mx = max (xo);
v = (x - mn) / (mx - mn);
case 'meanfill'
v = x;
v(nan) = mean (xo);
case 'linearfill'
v = gt_linearfill (x);
endswitch
endfunction
## Fill the missing values of the column vector X by linear interpolation over
## the non-missing positions, leaving leading and trailing missing values (and
## any group with fewer than two non-missing values) unchanged. Self-contained.
function v = gt_linearfill (x)
v = x;
idx = find (! isnan (x));
if (numel (idx) >= 2)
pos = (1:numel (x))';
vi = interp1 (idx, x(idx), pos, "linear");
fill = isnan (x) & pos > idx(1) & pos < idx(end);
v(fill) = vi(fill);
endif
endfunction
## Group rows by the grouping-variable values GVS (a cell array of column
## vectors), treating each variable's missing values as a single group value so
## that every row is assigned to a group. Returns G (1..NGROUPS), NGROUPS, and
## an errmsg body emitted by the caller. Self-contained: no table dependency.
function [G, ngroups, errmsg] = gt_group_rows (gvs)
errmsg = '';
G = [];
ngroups = 0;
KEY = [];
for j = 1:numel (gvs)
[p, m, e] = gt_col_proxy (gvs{j});
if (! isempty (e))
errmsg = e;
return;
endif
pc = p;
pc(m,:) = 0;
KEY = [KEY, pc, double(m)];
endfor
[~, ~, ic] = unique (KEY, "rows");
G = ic;
ngroups = max (ic);
endfunction
## Build a single-column grouping proxy for one grouping variable COL: a numeric
## matrix P whose value order matches COL's, together with a logical MISS mask
## flagging the missing elements. Returns an errmsg body emitted by the caller.
## Self-contained: no table dependency.
function [p, miss, errmsg] = gt_col_proxy (col)
p = [];
miss = [];
errmsg = '';
if (isa (col, 'categorical'))
p = double (col)(:);
miss = isnan (p);
elseif (isa (col, 'string') || iscellstr (col) || ischar (col))
c = cellstr (col);
c = c(:);
miss = cellfun (@isempty, c);
[~, ~, ic] = unique (c);
p = ic(:);
elseif (isa (col, 'datetime'))
DV = datevec (col);
nat = any (isnan (DV), 2);
DV(nat,:) = 0;
DV(nat,2:3) = 1;
p = datenum (DV);
p(nat) = NaN;
p = p(:);
miss = isnan (p);
elseif (isa (col, 'duration'))
p = days (col)(:);
miss = isnan (p);
elseif (isa (col, 'calendarDuration'))
p = proxyArray (col);
miss = any (isnan (p), 2);
elseif (isnumeric (col) || islogical (col))
p = double (col)(:);
miss = isnan (p);
else
errmsg = sprintf ("unsupported grouping variable type '%s'.", class (col));
endif
endfunction
## Validate an 'IncludedEdge' binning option VAL for CALLER, returning it
## lowercased as 'left' or 'right'. Self-contained: no table dependency.
function e = check_included_edge (caller, val)
if (isa (val, 'string') && isscalar (val))
val = char (val);
endif
if (! (ischar (val) && isrow (val) ...
&& any (strcmpi (val, {'left', 'right'}))))
error ("%s: 'IncludedEdge' must be 'left' or 'right'.", caller);
endif
e = lower (val);
endfunction
%!test
%! ## 'meancenter' subtracts the group mean
%! g = [1; 1; 1; 2; 2];
%! x = [10; 20; 30; 40; 60];
%! assert_equal (grouptransform (x, g, 'meancenter'), [-10; 0; 10; -10; 10]);
%!test
%! ## 'zscore', 'norm', and 'rescale' spot checks
%! g = [1; 1; 1; 2; 2];
%! x = [10; 20; 30; 40; 60];
%! assert_equal (grouptransform (x, g, 'zscore'), ...
%! [-1; 0; 1; -1/sqrt(2); 1/sqrt(2)], 8 * eps);
%! assert_equal (grouptransform (x, g, 'norm'), ...
%! [[10; 20; 30] ./ norm([10; 20; 30]); ...
%! [40; 60] ./ norm([40; 60])], 8 * eps);
%! assert_equal (grouptransform (x, g, 'rescale'), [0; 0.5; 1; 0; 1]);
%!test
%! ## 'meanfill' replaces missing values with the group mean
%! g = [1; 1; 2; 2];
%! x = [10; NaN; 30; 40];
%! assert_equal (grouptransform (x, g, 'meanfill'), [10; 10; 30; 40]);
%!test
%! ## 'linearfill' interpolates interior missing values, leaving the edges NaN
%! g = [1; 1; 1; 1; 2; 2; 2];
%! x = [1; NaN; NaN; 4; NaN; 10; NaN];
%! assert_equal (grouptransform (x, g, 'linearfill'), [1; 2; 3; 4; NaN; 10; NaN]);
%!test
%! ## A function handle is applied to each group's slice
%! g = [1; 1; 1; 2; 2];
%! x = [10; 20; 30; 40; 60];
%! assert_equal (grouptransform (x, g, @(v) v - mean (v)), [-10; 0; 10; -10; 10]);
%!test
%! ## The second output returns the grouping values of each row
%! g = [1; 1; 2; 2];
%! x = [10; 20; 30; 40];
%! [B, BG] = grouptransform (x, g, 'norm');
%! assert_equal (B, [[10; 20] ./ norm([10; 20]); [30; 40] ./ norm([30; 40])], ...
%! 8 * eps);
%! assert_equal (BG, [1; 1; 2; 2]);
%!test
%! ## A matrix transforms each column independently per group
%! A = [10 1; 20 2; 30 3; 40 4];
%! g = [1; 1; 2; 2];
%! assert_equal (grouptransform (A, g, 'meancenter'), ...
%! [-5 -0.5; 5 0.5; -5 -0.5; 5 0.5]);
%!test
%! ## 'ReplaceValues' false appends the transformed columns to A
%! g = [1; 1; 1; 2; 2];
%! x = [10; 20; 30; 40; 60];
%! B = grouptransform (x, g, 'meancenter', 'ReplaceValues', false);
%! assert_equal (B, [10 -10; 20 0; 30 10; 40 -10; 60 10]);
%!test
%! ## Rows with a missing grouping value form their own group, in original order
%! g = [1; 1; NaN; 2; 2];
%! x = [10; 20; 30; 40; 60];
%! [B, BG] = grouptransform (x, g, 'meancenter');
%! assert_equal (B, [-5; 5; 0; -10; 10]);
%! assert_equal (BG, [1; 1; NaN; 2; 2]);
%!test
%! ## Several grouping vectors return BG as a cell array, one per variable
%! x = [10; 20; 30; 40; 60];
%! g1 = [1; 1; 2; 2; 1];
%! g2 = {'a'; 'a'; 'b'; 'b'; 'a'};
%! [B, BG] = grouptransform (x, {g1, g2}, 'meancenter');
%! assert_equal (B, [-20; -10; -5; 5; 30]);
%! assert_equal (BG, {[1; 1; 2; 2; 1], {'a'; 'a'; 'b'; 'b'; 'a'}});
%!test
%! ## A GROUPBINS edge vector bins the grouping variable before transforming
%! x = [10; 20; 30; 40];
%! v = [1; 2; 3; 4];
%! [B, BG] = grouptransform (x, v, [0 2.5 5], 'meancenter');
%! assert_equal (B, [-5; 5; -5; 5]);
%! assert_equal (iscategorical (BG), true);
%! assert_equal (cellstr (BG), {'[0, 2.5)'; '[0, 2.5)'; '[2.5, 5]'; '[2.5, 5]'});
%!test
%! ## A GROUPBINS number of bins makes equal-width bins over the data range
%! x = [10; 20; 30; 40];
%! v = [1; 2; 3; 4];
%! B = grouptransform (x, v, 2, 'meancenter');
%! assert_equal (B, [-5; 5; -5; 5]);
%!error grouptransform ([1; 2], [1; 2])
%!error ...
%! grouptransform ([1; 2], [1; 2], 'bogus')
%!error ...
%! grouptransform ([1; 2], [1; 2], 2, 'zscore', 'IncludedEdge', 'mid')
%!error ...
%! grouptransform ([1; 2], [1; 2], 'month', 'meancenter')
%!error ...
%! grouptransform ([1; 2], [1; 2], 'zscore', 'ReplaceValues', 'yes')
%!error ...
%! grouptransform ([1; 2], [1; 2], 'zscore', 5)
%!error ...
%! grouptransform ([1; 2; 3], [1; 2], 'zscore')
pr0m1th3as-datatypes-9c9a8d3/inst/hours.m 0000664 0000000 0000000 00000004106 15227665741 0020351 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{D} =} hours (@var{X})
##
## Fixed-time duration in hours.
##
## @code{@var{D} = hours (@var{X})} returns a @qcode{duration} array
## representing fixed-time duration hours equivalent to the values in @var{X},
## which must be a numeric array.
##
## @code{hours} is also available as a method for @qcode{duration} arrays, in
## which case it performs the opposite conversion.
##
## @seealso{duration, years, days, minutes, seconds, milliseconds,
## duration.hours}
## @end deftypefn
function out = hours (x)
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("hours: input array must be numeric.");
elseif (! isreal (x))
error ("hours: input array must be real.");
endif
out = duration (double (x), 0, 0, 'Format', 'h');
endfunction
%!demo
%! ## `hours` builds a duration from a number of hours; fractional values are fine.
%!
%! hours (1.5)
%! hours ([1, 2.5, 8])
%!test
%! X = magic (3);
%! D = hours (X);
%! assert_equal (size (D), size (X));
%!test
%! D = hours ([1, 2, 3]);
%! assert_equal (hours (D), [1, 2, 3]);
%!test
%! D = hours (int16 (1));
%! assert_equal (hours (D), 1);
%!test
%! D = hours ();
%! assert_equal (hours (D), 1);
%!error hours ("asd");
%!error hours (1+i);
pr0m1th3as-datatypes-9c9a8d3/inst/iscalendarduration.m 0000664 0000000 0000000 00000002747 15227665741 0023075 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} iscalendarduration (@var{X})
##
## True if input is a @code{calendarDuration} array, false otherwise.
##
## @code{@var{TF} = iscalendarduration (@var{X})} always returns a logical
## scalar, irrespective of the size of @var{X}.
##
## @end deftypefn
function TF = iscalendarduration (x)
TF = isa (x, 'calendarDuration');
endfunction
%!assert_equal (iscalendarduration (calendarDuration (0, 0, 0)), true);
%!assert_equal (iscalendarduration (calendarDuration ([1, 2], 0, 0)), true);
%!assert_equal (iscalendarduration ([0, 0, 0]), false);
%!assert_equal (iscalendarduration ({0, 0, 0}), false);
%!assert_equal (iscalendarduration ({calendarDuration(0, 0, 0)}), false);
pr0m1th3as-datatypes-9c9a8d3/inst/iscategorical.m 0000664 0000000 0000000 00000002656 15227665741 0022032 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} iscategorical (@var{X})
##
## True if input is a @code{categorical} array, false otherwise.
##
## @code{@var{TF} = iscategorical (@var{X})} always returns a logical scalar,
## irrespective of the size of @var{X}.
##
## @end deftypefn
function TF = iscategorical (x)
TF = isa (x, 'categorical');
endfunction
%!assert_equal (iscategorical (categorical ([1, 2, 3])), true);
%!assert_equal (iscategorical (categorical ([1, 2; 1, 4])), true);
%!assert_equal (iscategorical ([0, 1, 2]), false);
%!assert_equal (iscategorical ({true, false}), false);
%!assert_equal (iscategorical ({categorical([1, 2, 2])}), false);
pr0m1th3as-datatypes-9c9a8d3/inst/isdatetime.m 0000664 0000000 0000000 00000002615 15227665741 0021344 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} isdatetime (@var{X})
##
## True if input is a @code{datetime} array, false otherwise.
##
## @code{@var{TF} = isdatetime (@var{X})} always returns a logical scalar,
## irrespective of the size of @var{X}.
##
## @end deftypefn
function TF = isdatetime (x)
TF = isa (x, 'datetime');
endfunction
%!assert_equal (isdatetime (datetime ([1, 2, 3])), true);
%!assert_equal (isdatetime (datetime ([1, 2, 0; 1, 4, 0])), true);
%!assert_equal (isdatetime ([0, 1, 2]), false);
%!assert_equal (isdatetime ({true, false}), false);
%!assert_equal (isdatetime ({datetime([1, 2, 3])}), false);
pr0m1th3as-datatypes-9c9a8d3/inst/isduration.m 0000664 0000000 0000000 00000002615 15227665741 0021375 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} isduration (@var{X})
##
## True if input is a @code{duration} array, false otherwise.
##
## @code{@var{TF} = isduration (@var{X})} always returns a logical scalar,
## irrespective of the size of @var{X}.
##
## @end deftypefn
function TF = isduration (x)
TF = isa (x, 'duration');
endfunction
%!assert_equal (isduration (duration ([1, 2, 3])), true);
%!assert_equal (isduration (duration ([1, 2, 0; 1, 4, 0])), true);
%!assert_equal (isduration ([0, 1, 2]), false);
%!assert_equal (isduration ({true, false}), false);
%!assert_equal (isduration ({duration([1, 2, 3])}), false);
pr0m1th3as-datatypes-9c9a8d3/inst/isnat.m 0000664 0000000 0000000 00000003357 15227665741 0020336 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2025-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} isnat (@var{T})
##
## Test for Not-A-Time elements in datetime array.
##
## @code{@var{TF} = isnat (@var{T})} returns a logical array @var{TF} of the
## same size as @var{T} containing @qcode{true} for each corresponding
## element of @var{T} that is Not-A-Time (@qcode{NaT}) and @qcode{false}
## otherwise. @qcode{NaT} is the equivalent of @qcode{NaN} in numeric
## arrays.
##
## If @var{T} is not a datetime array, @code{isnat} returns an error.
##
## @end deftypefn
function TF = isnat (T)
error ("isnat: input argument must be a datetime array.");
endfunction
%!error isnat (1)
%!error isnat ({'asd'})
%!error isnat ('er')
%!error isnat (ones (2, 3))
%!error isnat (days (2))
pr0m1th3as-datatypes-9c9a8d3/inst/istable.m 0000664 0000000 0000000 00000002540 15227665741 0020634 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} istable (@var{X})
##
## True if input is a @code{table}, false otherwise.
##
## @code{@var{TF} = istable (@var{X})} always returns a logical scalar,
## irrespective of the size of @var{X}.
##
## @end deftypefn
function TF = istable (x)
TF = isa (x, 'table');
endfunction
%!assert_equal (istable (table ([1, 2, 3])), true);
%!assert_equal (istable (table ([1, 2, 0; 1, 4, 0])), true);
%!assert_equal (istable ([0, 1, 2]), false);
%!assert_equal (istable ({true, false}), false);
%!assert_equal (istable ({table([1, 2, 3])}), false);
pr0m1th3as-datatypes-9c9a8d3/inst/keyHash.m 0000664 0000000 0000000 00000013544 15227665741 0020613 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2025-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{hey} =} keyHash (@var{X})
## @deftypefnx {datatypes} {@var{hey} =} keyHash (@var{X}, @var{base})
##
## Generate a hash code for an array.
##
## @code{@var{h} = keyHash (@var{X})} generates a @qcode{uint64} scalar that
## represents the input @var{X}, which may be numeric, logical, or character
## array or cell array of character vectors. @code{keyHash} utilizes the 64-bit
## FNV-1a variant of the Fowler-Noll-Vo non-cryptographic hash function.
##
## @code{@var{h} = keyHash (@var{X}, @var{base})} also generates a 64-bit
## hash code using @var{base} as the offset basis for the FNV-1a hash
## algorithm. @var{base} must be a @qcode{uint64} integer type scalar. Use
## this syntax to cascade @code{keyHash} on multiple objects for which a
## single hash code is required.
##
## Note that unlike MATLAB, this implementation does not use any random seed.
## As a result, @code{keyHash} will always generate the exact same hash key
## for any particular input across different workers and Octave sessions.
##
## @end deftypefn
function key = keyHash (x = [], base = [])
## Validate input
if (nargin < 1)
print_usage;
endif
## Initialize string with size and class name
size_str = sprintf ('%dx', size (x))(1:end-1);
init_str = [size_str class(x)];
if (base)
if (! (isscalar (base) && isa (base, 'uint64')))
error ("keyHash: BASE must be a UINT64 scalar.");
endif
key = __ckeyHash__ (init_str, base);
else
key = __ckeyHash__ (init_str);
endif
## Select data type
if (isnumeric (x) || islogical (x))
key = __nkeyHash__ (x(:), key);
elseif (ischar (x))
key = __ckeyHash__ (x(:), key);
elseif (iscellstr (x))
key = __ckeyHash__ ([x{:}], key);
else
error ("keyHash: unsupported input type.");
endif
endfunction
%!test
%! key = keyHash (1);
%! assert_equal (isscalar (key), true);
%! key = keyHash ([1:5]);
%! assert_equal (isscalar (key), true);
%!test
%! key1 = keyHash (1);
%! key2 = keyHash (1, 0xcbf29ce484222325); # default offset basis
%! assert_equal (key1, key2);
%!test
%! key1 = keyHash (0);
%! assert_equal (class (key1), 'uint64');
%!test
%! A = [1:5];
%! B = [1:5];
%! key1 = keyHash (A);
%! key2 = keyHash (B);
%! assert_equal (key1, key2);
%!test
%! A = [1:5];
%! B = [1:5]';
%! key1 = keyHash (A);
%! key2 = keyHash (B);
%! assert_equal (isequal (key1, key2), false);
%!test
%! A = '';
%! E = uint64 (15921358368119480423);
%! key = keyHash (A);
%! assert (isequal (key, E), sprintf ("k: %lx e: %lx d: %lx", key, E, key - E));
%! assert_equal (key, E);
%!test
%! A = uint64 (128);
%! E = uint64 (8038837787959150693);
%! key = keyHash (A);
%! assert (isequal (key, E), sprintf ("k: %lx e: %lx d: %lx", key, E, key - E));
%! assert_equal (key, E);
## Add more tests on endianness (see GitHub issue 43)
%!assert_equal (keyHash ([1, 2]), uint64 (1291405323040189622))
%!assert_equal (keyHash ([1+2i]), uint64 (4391366703481493027))
%!assert_equal (keyHash (single ([1, 2])), uint64 (10607299016200876763))
%!assert_equal (keyHash (int64 ([1, 2])), uint64 (8387921810608003298))
%!assert_equal (keyHash (uint64 ([1, 2])), uint64 (15129359585364357711))
%!assert_equal (keyHash (int32 ([1, 2])), uint64 (7340059757986521701))
%!assert_equal (keyHash (uint32 ([1, 2])), uint64 (6705001899901839972))
%!assert_equal (keyHash (int16 ([1, 2])), uint64 (2451959940856797955))
%!assert_equal (keyHash (uint16 ([1, 2])), uint64 (10303904549507999050))
%!assert_equal (keyHash (int8 ([1, 2])), uint64 (3623669810820070662))
%!assert_equal (keyHash (uint8 ([1, 2])), uint64 (12877398120156278681))
%!assert_equal (keyHash (logical ([1, 2])), uint64 (16918259908176314871))
%!assert_equal (__nkeyHash__ ([1, 2]), uint64 (4062974330926783736))
%!assert_equal (__nkeyHash__ ([1+2i]), uint64 (4062974330926783736))
%!assert_equal (__nkeyHash__ (single ([1, 2])), uint64 (10375111465485032152))
%!assert_equal (__nkeyHash__ (int64 ([1, 2])), uint64 (8581494755304202342))
%!assert_equal (__nkeyHash__ (uint64 ([1, 2])), uint64 (8581494755304202342))
%!assert_equal (__nkeyHash__ (int32 ([1, 2])), uint64 (14538333428393601222))
%!assert_equal (__nkeyHash__ (uint32 ([1, 2])), uint64 (14538333428393601222))
%!assert_equal (__nkeyHash__ (int16 ([1, 2])), uint64 (12479921481467174326))
%!assert_equal (__nkeyHash__ (uint16 ([1, 2])), uint64 (12479921481467174326))
%!assert_equal (__nkeyHash__ (int8 ([1, 2])), uint64 (589729691727335466))
%!assert_equal (__nkeyHash__ (uint8 ([1, 2])), uint64 (589729691727335466))
%!assert_equal (__nkeyHash__ (logical ([1, 2])), uint64 (589728592215707255))
## Add more tests on different architectures (see GitHub issues 38 and 40)
%!assert_equal (__nkeyHash__ (uint8 (128)), uint64 (5808531584386460767))
%!assert_equal (keyHash (uint8 (128)), uint64 (10759574069356082695))
%!assert_equal (__nkeyHash__ (uint32 (0xdeadbeef)), ...
%! uint64 (12840711468051582507))
%!assert_equal (keyHash (uint32 (0xdeadbeef)), uint64 (3790509136731937468))
%!error keyHash ();
%!error keyHash (1, 1);
%!error keyHash (@(x) x);
pr0m1th3as-datatypes-9c9a8d3/inst/keyMatch.m 0000664 0000000 0000000 00000003235 15227665741 0020760 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2025-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{TF} =} keyMatch (@var{A}, @var{B})
##
## Return true if both inputs have the same hash code.
##
## @code{@var{TF} = keyMatch (@var{A}, @var{B})} returns a logical scalar,
## which is @qcode{true}, if both inputs, @var{A} and @var{B}, have the same
## FNV-1a 64-bit hash code, and @qcode{false} otherwise.
##
## @end deftypefn
function TF = keyMatch (A, B)
if (nargin != 2)
print_usage;
endif
if (! strcmp (class (A), class (B)))
TF = false;
elseif (! isequal (size (A), size (B)))
TF = false;
else
A_key = keyHash (A);
B_key = keyHash (B);
TF = A_key == B_key;
endif
endfunction
%!assert_equal (keyMatch (1, {'1'}), false);
%!assert_equal (keyMatch (ones (2), 2), false);
%!assert_equal (keyMatch (1, 2), false);
%!assert_equal (keyMatch (1, 1), true);
%!error keyMatch (2);
pr0m1th3as-datatypes-9c9a8d3/inst/milliseconds.m 0000664 0000000 0000000 00000004265 15227665741 0021704 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{D} =} milliseconds (@var{X})
##
## Fixed-time duration in milliseconds.
##
## @code{@var{D} = milliseconds (@var{X})} returns a @qcode{duration} array
## representing fixed-time duration milliseconds equivalent to the values in
## @var{X}, which must be a numeric array.
##
## @code{milliseconds} is also available as a method for @qcode{duration}
## arrays, in which case it performs the opposite conversion.
##
## @seealso{duration, years, days, hours, minutes, seconds,
## duration.milliseconds}
## @end deftypefn
function out = milliseconds (x)
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("milliseconds: input array must be numeric.");
elseif (! isreal (x))
error ("milliseconds: input array must be real.");
endif
out = duration (0, 0, double (x) / 1000, 'Format', 's');
endfunction
%!demo
%! ## `milliseconds` builds a duration from a number of milliseconds.
%!
%! milliseconds (1500)
%!test
%! X = magic (3);
%! D = milliseconds (X);
%! assert_equal (size (D), size (X));
%!test
%! D = milliseconds ([1, 2, 3]);
%! assert_equal (milliseconds (D), [1, 2, 3]);
%!test
%! D = milliseconds (int16 (1));
%! assert_equal (milliseconds (D), 1);
%!test
%! D = milliseconds ();
%! assert_equal (milliseconds (D), 1);
%!error milliseconds ("asd");
%!error milliseconds (1+i);
pr0m1th3as-datatypes-9c9a8d3/inst/minutes.m 0000664 0000000 0000000 00000004204 15227665741 0020674 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{D} =} minutes (@var{X})
##
## Fixed-time duration in minutes.
##
## @code{@var{D} = minutes (@var{X})} returns a @qcode{duration} array
## representing fixed-time duration minutes equivalent to the values in @var{X},
## which must be a numeric array.
##
## @code{minutes} is also available as a method for @qcode{duration} arrays, in
## which case it performs the opposite conversion.
##
## @seealso{duration, years, days, hours, seconds, milliseconds,
## duration.minutes}
## @end deftypefn
function out = minutes (x)
if (nargin == 0)
x = 1;
elseif (! isnumeric (x))
error ("minutes: input array must be numeric.");
elseif (! isreal (x))
error ("minutes: input array must be real.");
endif
out = duration (0, double (x), 0, 'Format', 'm');
endfunction
%!demo
%! ## `minutes` builds a duration from a number of minutes.
%!
%! minutes (90)
%!
%! ## Combine builders by adding them.
%! hours (1) + minutes (30)
%!test
%! X = magic (3);
%! D = minutes (X);
%! assert_equal (size (D), size (X));
%!test
%! D = minutes ([1, 2, 3]);
%! assert_equal (minutes (D), [1, 2, 3]);
%!test
%! D = minutes (int16 (1));
%! assert_equal (minutes (D), 1);
%!test
%! D = minutes ();
%! assert_equal (minutes (D), 1);
%!error minutes ("asd");
%!error minutes (1+i);
pr0m1th3as-datatypes-9c9a8d3/inst/missing.m 0000664 0000000 0000000 00000060701 15227665741 0020665 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2024-2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
classdef missing
## -*- texinfo -*-
## @deftp {datatypes} missing
##
## Array of missing values.
##
## A special class to represent missing data to other data types.
##
## @end deftp
properties (SetAccess = private, Hidden)
data = NaN
endproperties
methods (Hidden)
## Custom display
function display (this)
in_name = inputname (1);
if (! isempty (in_name))
fprintf ('%s =\n', in_name);
endif
__disp__ (this, 'missing', in_name);
endfunction
## Custom display
function disp (this)
__disp__ (this, 'missing');
endfunction
endmethods
################################################################################
## ** Create and convert 'missing' type ** ##
################################################################################
## Available Methods ##
## ##
## 'missing' 'dispstrings' 'cellstr' 'double' ##
## 'single' 'calendarDuration' 'categorical' 'datetime' ##
## 'duration' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {missing} {@var{M} =} missing ()
##
## Create missing values.
##
## @code{missing} always returns a scalar missing value. Use @code{repmat}
## to expand a scalar missing value to a missing array of desired
## dimensions.
##
## @end deftypefn
function this = missing ()
if (nargin > 0 )
error ("missing: too many input arguments.");
endif
endfunction
endmethods
methods (Hidden)
function cstr = dispstrings (this)
cstr = repmat ({''}, size (this));
endfunction
function cstr = cellstr (this)
cstr = dispstrings (this);
endfunction
function out = double (this)
out = this.data;
endfunction
function out = single (this)
out = single (this.data);
endfunction
function out = calendarDuration (this)
out = calendarDuration (NaN (size (this)), NaN, NaN);
endfunction
function out = categorical (this)
out = categorical (NaN (size (this)));
endfunction
function out = datetime (this)
out = NaT (size (this));
endfunction
function out = duration (this)
out = duration (NaN (size (this)));
endfunction
## Overload isequal for categorical support
function TF = isequal (varargin)
## Check for categorical input
idx = find (cellfun ('iscategorical', varargin), 1);
if (isempty (idx))
if (any (cellfun (@(x) ! isa (x, 'missing'), varargin)))
error ("missing.isequal: unsupported input types.");
endif
data = cellfun (@(x) x.data, varargin, 'UniformOutput', false);
TF = isequal (data{:});
else
## Convert first input (missing) to categorical
varargin{1} = categorical (varargin{1});
## Call categorical overloaded method
TF = isequal (varargin{:});
endif
endfunction
## Overload isequaln for categorical support
function TF = isequaln (varargin)
## Check for categorical input
idx = find (cellfun ('iscategorical', varargin), 1);
if (isempty (idx))
if (any (cellfun (@(x) ! isa (x, 'missing'), varargin)))
error ("missing.isequaln: unsupported input types.");
endif
data = cellfun (@(x) x.data, varargin, 'UniformOutput', false);
TF = isequaln (data{:});
else
## Convert first input (missing) to categorical
varargin{1} = categorical (varargin{1});
## Call categorical overloaded method
TF = isequaln (varargin{:});
endif
endfunction
endmethods
################################################################################
## ** Summary Information ** ##
################################################################################
## Available Methods ##
## ##
## 'size' 'ndims' 'numel' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {missing} {@var{sz} =} size (@var{M})
## @deftypefnx {missing} {@var{dim_sz} =} size (@var{M}, @var{dim})
## @deftypefnx {missing} {@var{dim_sz} =} size (@var{M}, @var{d1}, @var{d2}, @dots{})
## @deftypefnx {missing} {[@var{rows}, @var{columns}, @dots{}, @var{dim_n_sz}] =} size (@dots{})
##
## Return the size of a missing array.
##
## @code{@var{sz} = size (@var{M})} returns a row vector with the size
## (number of elements) of each dimension for the missing array @var{M}.
##
## @code{@var{dim_sz} = size (@var{M}, @var{dim})} returns the size of
## the corresponding dimension specified in @var{dim}. If @var{dim} is a
## vector, then @var{dim_sz} is a vector of the same length and with each
## element corresponding to a specified dimension. Multiple dimensions may
## also be specified as separate arguments.
##
## With a single output argument, @code{size} returns a row vector. When
## called with multiple output arguments, @code{size} returns the size of
## dimension N in the Nth argument.
##
## @end deftypefn
function varargout = size (this, varargin)
if (! isempty (varargin))
sz = size (this.data, varargin{:});
else
sz = size (this.data);
endif
if (nargout == 0 || nargout == 1)
varargout{1} = sz;
elseif (numel (sz) != nargout)
error (["missing.size: nargout > 1 but does not", ...
" match number of requested dimensions."]);
else
for i = 1:nargout
varargout{i} = sz(i);
endfor
endif
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{out} =} ndims (@var{M})
##
## Number of dimensions in a missing array.
##
## @code{@var{out} = ndims (@var{M})} returns the number of dimensions of
## the missing array @var{M}.
##
## @end deftypefn
function out = ndims (this)
out = ndims (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{out} =} numel (@var{M})
##
## Total number of elements in a missing array.
##
## @code{@var{out} = numel (@var{M})} returns the number of elements in the
## missing array @var{M}.
##
## @end deftypefn
function out = numel (this)
out = numel (this.data);
endfunction
endmethods
################################################################################
## ** Query Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'iscolumn' 'isempty' 'ismatrix' 'ismissing' ##
## 'isrow' 'isscalar' 'isvector' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} iscolumn (@var{M})
##
## Return true if missing array is a column vector.
##
## @code{@var{TF} = iscolumn (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is a column vector
## and @qcode{false} otherwise. A column vector is a 2-D array for which
## @code{size (@var{X})} returns @code{[@var{N}, 1]} with non-negative
## @var{N}.
##
## @end deftypefn
function out = iscolumn (this)
out = iscolumn (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} isempty (@var{M})
##
## Return true if missing array is empty.
##
## @code{@var{TF} = isempty (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is empty and
## @qcode{false} otherwise.
##
## @end deftypefn
function out = isempty (this)
out = isempty (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} ismatrix (@var{M})
##
## Return true if missing array is a 2-D array.
##
## @code{@var{TF} = ismatrix (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is a matrix and
## @qcode{false} otherwise. A matrix is an array of any type where
## @code{ndims (@var{X}) == 2} and for which @code{size (@var{X})} returns
## @code{[@var{H}, @var{W}]} with non-negative @var{H} and @var{W}.
##
## @end deftypefn
function out = ismatrix (this)
out = ismatrix (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{out} =} ismissing (@var{M})
##
## Return true for each element in missing array.
##
## @code{@var{TF} = ismissing (@var{M})} returns a logical array @var{TF}
## of the same size as @var{M} containing @qcode{true} in every element.
##
## @end deftypefn
function out = ismissing (this)
out = true (size (this));
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} isrow (@var{M})
##
## Return true if missing array is a row vector.
##
## @code{@var{TF} = isrow (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is a row vector
## and @qcode{false} otherwise. A row vector is a 2-D array for which
## @code{size (@var{X})} returns @code{[1, @var{N}]} with non-negative
## @var{N}.
##
## @end deftypefn
function out = isrow (this)
out = isrow (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} isscalar (@var{M})
##
## Return true if missing array is a scalar.
##
## @code{@var{TF} = isscalar (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is also a scalar
## and @qcode{false} otherwise. A scalar is a single element object for
## which @code{size (@var{X})} returns @code{[1, 1]}.
##
## @end deftypefn
function out = isscalar (this)
out = isscalar (this.data);
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} isvector (@var{M})
##
## Return true if missing array is a vector.
##
## @code{@var{TF} = isvector (@var{M})} returns a logical scalar @var{TF},
## which is @qcode{true} if the missing array @var{M} is a vector and
## @qcode{false} otherwise. A vector is a 2-D array for which one of the
## dimensions is equal to 1 (either @math{1*N} or @math{N*1}). By
## definition, a scalar is also a vector.
##
## @end deftypefn
function out = isvector (this)
out = isvector (this.data);
endfunction
endmethods
################################################################################
## ** Relational Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'eq' 'ge' 'gt' 'le' ##
## 'lt' 'ne' ##
## ##
################################################################################
methods (Access = public)
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} eq (@var{A}, @var{B})
##
## Equality for missing arrays.
##
## @code{@var{TF} = eq (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} == @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = eq (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A == B;
catch
error ("missing.eq: arrays have incompatible sizes.");
end_try_catch
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} ge (@var{A}, @var{B})
##
## Greater than or equal to for missing arrays.
##
## @code{@var{TF} = ge (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} >= @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = ge (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A >= B;
catch
error ("missing.ge: arrays have incompatible sizes.");
end_try_catch
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} gt (@var{A}, @var{B})
##
## Greater than for missing arrays.
##
## @code{@var{TF} = gt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} > @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = gt (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A > B;
catch
error ("missing.gt: arrays have incompatible sizes.");
end_try_catch
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} le (@var{A}, @var{B})
##
## Less than or equal to for missing arrays.
##
## @code{@var{TF} = le (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} <= @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = le (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A <= B;
catch
error ("missing.le: arrays have incompatible sizes.");
end_try_catch
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} lt (@var{A}, @var{B})
##
## Less than for missing arrays.
##
## @code{@var{TF} = lt (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} < @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = lt (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A < B;
catch
error ("missing.lt: arrays have incompatible sizes.");
end_try_catch
endfunction
## -*- texinfo -*-
## @deftypefn {missing} {@var{TF} =} ne (@var{A}, @var{B})
##
## Not equal for missing arrays.
##
## @code{@var{TF} = ne (@var{A}, @var{B})} is the equivalent of the syntax
## @code{@var{TF} = @var{A} != @var{B}} and returns a logical array of the
## same size as the largest input with its elements set to @qcode{false}.
## @var{A} and @var{B} must be size compatible, which translates to they can
## be the same size, one can be scalar, or for every dimension, their
## dimension sizes must be equal or one of them must be 1.
##
## One of the input arguments may also be any type of array. Any comparison
## with missing arrays always returns @qcode{false}.
##
## @end deftypefn
function TF = ne (A, B)
A = nan (size (A));
B = nan (size (B));
try
TF = A != B;
catch
error ("missing.ne: arrays have incompatible sizes.");
end_try_catch
endfunction
endmethods
################################################################################
## ** Array Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'cat' 'horzcat' 'vertcat' 'repmat' ##
## 'reshape' 'squeeze' 'transpose' 'ctranspose' ##
## ##
################################################################################
methods (Hidden)
function out = cat (dim, varargin)
datatype = '';
for i = 1:numel (varargin)
if (isa (varargin{i}, 'missing'))
continue
elseif (isa (varargin{i}, 'calendarDuration'))
datatype = 'calendarDuration';
elseif (iscellstr (varargin{i}))
datatype = 'cellstr';
elseif (isa (varargin{i}, 'categorical'))
datatype = 'categorical';
elseif (isa (varargin{i}, 'datetime'))
datatype = 'datetime';
elseif (isa (varargin{i}, 'double'))
datatype = 'double';
elseif (isa (varargin{i}, 'duration'))
datatype = 'duration';
elseif (isa (varargin{i}, 'single'))
datatype = 'single';
elseif (isa (varargin{i}, 'string'))
datatype = 'string';
else
error ("missing.cat: cannot convert 'missing' to '%s' type.", ...
class (varargin{i}));
endif
endfor
if (isempty (datatype))
sz = cellfun (@(x) x.data, varargin, 'UniformOutput', false);
out = varargin{1};
out.data = cat (dim, sz{:});
else
args = varargin;
for i = 1:numel (varargin)
if (isa (varargin{i}, 'missing'))
switch datatype
case 'calendarDuration'
args{i} = calendarDuration (NaN (size (varargin{i})), NaN, NaN);
case 'cellstr'
args{i} = repmat ({''}, size (varargin{i}));
case 'categorical'
args{i} = categorical (NaN (size (varargin{i})));
case 'datetime'
args{i} = NaT (size (varargin{i}));
case 'double'
args{i} = NaN (size (varargin{i}));
case 'single'
args{i} = single (NaN (size (varargin{i})));
case 'string'
args{i} = string (NaN (size (varargin{i})));
endswitch
endif
endfor
out = cat (dim, args{:});
endif
endfunction
function out = horzcat (varargin)
out = cat (2, varargin{:});
endfunction
function out = vertcat (varargin)
out = cat (1, varargin{:});
endfunction
function this = repmat (this, varargin)
this.data = repmat (this.data, varargin{:});
endfunction
function this = reshape (this, varargin)
this.data = reshape (this.data, varargin{:});
endfunction
function this = squeeze (this, varargin)
this.data = squeeze (this.data, varargin{:});
endfunction
function this = ctranspose (this, varargin)
this.data = ctranspose (this.data, varargin{:});
endfunction
function this = transpose (this, varargin)
this.data = transpose (this.data, varargin{:});
endfunction
endmethods
################################################################################
## ** Reference and Assignment Operations ** ##
################################################################################
## Available Methods ##
## ##
## 'subsref' 'subsasgn' ##
## ##
################################################################################
methods (Hidden)
## Class specific subscripted reference
function varargout = subsref (this, s)
chain_s = s(2:end);
s = s(1);
switch (s.type)
case '()'
out = this;
out.data = this.data(s.subs{:});
case '{}'
error (["missing.subsref: '{}' invalid indexing", ...
" for referencing values. Use '()' instead."]);
case '.'
error (["missing.subsref: '.' invalid indexing", ...
" for referencing values. Use '()' instead."]);
endswitch
## Chained references
if (! isempty (chain_s))
out = subsref (out, chain_s);
endif
varargout{1} = out;
endfunction
## Class specific subscripted assignment
function this = subsasgn (this, s, val)
if (numel (s) > 1)
error ("missing.subsasgn: chained subscripts not allowed.");
endif
switch (s.type)
case '()'
if (isa (val, "missing"))
this.data(s.subs{:}) = val.data;
elseif (isempty (val))
this.data(s.subs{:}) = [];
else
error ("missing.subsasgn: unable to perform assignment.");
endif
case '{}'
error (["missing.subsasgn: '{}' invalid indexing", ...
" for assigning values. Use '()' instead."]);
case '.'
error (["missing.subsasgn: '.' invalid indexing", ...
" for assigning values. Use '()' instead."]);
endswitch
endfunction
endmethods
endclassdef
pr0m1th3as-datatypes-9c9a8d3/inst/ods2struct.m 0000664 0000000 0000000 00000011427 15227665741 0021331 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{s} =} ods2struct (@var{filename})
##
## Read every sheet of an OpenDocument spreadsheet into a scalar structure.
##
## @code{@var{s} = ods2struct (@var{filename})} reads each data sheet of the
## OpenDocument spreadsheet named by @var{filename} into a @code{table} and
## returns a scalar structure with one field per sheet, in sheet order. Both
## the compressed @qcode{.ods} and the flat @qcode{.fods} formats are read.
## Each sheet is reconstructed exactly as by @code{ods2table}; it is the inverse
## of @code{struct2ods}.
##
## A sheet name that is not a valid structure field name is canonicalised with
## @code{matlab.lang.makeValidName} (and made unique if two sheet names collide).
## Whenever the field name differs from the sheet name, the original sheet name
## is stored on that field's table as the @qcode{'ActualSheetName'} custom
## property, so a subsequent @code{struct2ods} restores the exact sheet name.
##
## @seealso{struct2ods, ods2table, table2ods, readtable}
## @end deftypefn
function s = ods2struct (filename)
if (nargin != 1)
print_usage ();
endif
if (! (ischar (filename) || iscellstr (filename) || isa (filename, 'string')))
error ("ods2struct: FILENAME must be a character vector, cellstr, or string.");
endif
file = char (cellstr (filename));
## Enumerate the data sheet names (the first output doubles as an error probe).
[data, ~, ~, names] = __ods2table__ (file);
if (ischar (data))
error ("ods2struct: %s", data);
endif
s = struct ();
usedFields = {};
for k = 1:numel (names)
sn = names{k};
R = ods2table (file, 'Sheet', sn);
fn = matlab.lang.makeValidName (sn);
## Make the field name unique if canonicalisation collided with an earlier
## one; the ActualSheetName property below preserves the true sheet name.
base = fn;
j = 1;
while (any (strcmp (fn, usedFields)))
fn = sprintf ('%s_%d', base, j);
j += 1;
endwhile
usedFields{end+1} = fn;
## Stash the original sheet name whenever the field name had to change.
if (! strcmp (fn, sn))
R = addprop (R, 'ActualSheetName', 'table');
R.Properties.CustomProperties.ActualSheetName = sn;
endif
s.(fn) = R;
endfor
endfunction
%!demo
%! ## `ods2struct` is the inverse of `struct2ods`: it reads *every* data sheet of
%! ## a workbook into one scalar struct, one field per sheet, in sheet order.
%!
%! wb.Patients = table ({'Li'; 'Diaz'}, [38; 40], 'VariableNames', {'Name', 'Age'});
%! wb.Visits = table ([1; 2; 3], 'VariableNames', {'Visit'});
%! filename = fullfile (tempdir (), 'clinic.ods');
%! struct2ods (filename, wb);
%!
%! s = ods2struct (filename);
%! s.Patients
%!
%! delete (filename);
%!test # round-trip a multi-sheet workbook written by struct2ods
%! s.alpha = table ([1; 2; 3], {'a'; 'b'; 'c'}, 'VariableNames', {'x', 'y'});
%! s.beta = table ([10.5; 20.5], 'VariableNames', {'v'});
%! fn = [tempname() '.ods'];
%! unwind_protect
%! struct2ods (fn, s);
%! r = ods2struct (fn);
%! assert_equal (fieldnames (r), {'alpha'; 'beta'});
%! assert_equal (r.alpha.x, [1; 2; 3]);
%! assert_equal (r.beta.v, [10.5; 20.5]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
%!test # an odd sheet name is canonicalised and stashed in ActualSheetName
%! T = table ([7; 8], 'VariableNames', {'v'});
%! T = addprop (T, 'ActualSheetName', 'table');
%! T.Properties.CustomProperties.ActualSheetName = 'My Sheet!';
%! s.only = T;
%! fn = [tempname() '.fods'];
%! unwind_protect
%! struct2ods (fn, s);
%! r = ods2struct (fn);
%! f = fieldnames (r);
%! assert_equal (numel (f), 1);
%! assert_equal (isvarname (f{1}), true);
%! assert_equal (r.(f{1}).Properties.CustomProperties.ActualSheetName, ...
%! 'My Sheet!');
%! assert_equal (r.(f{1}).v, [7; 8]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
%!error ...
%! ods2struct (42)
%!error ...
%! ods2struct ([tempname() '.ods'])
pr0m1th3as-datatypes-9c9a8d3/inst/ods2table.m 0000664 0000000 0000000 00000057523 15227665741 0021103 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {@var{tbl} =} ods2table (@var{filename})
## @deftypefnx {datatypes} {@var{tbl} =} ods2table (@var{filename}, @qcode{'Sheet'}, @var{sheet})
##
## Read an OpenDocument spreadsheet file into a table.
##
## @code{@var{tbl} = ods2table (@var{filename})} reads the OpenDocument
## spreadsheet named by @var{filename}, which may be a character vector, a
## cellstr, or a string scalar, and returns it as a @code{table}. Both the
## compressed @qcode{.ods} and the flat @qcode{.fods} formats are read; the
## format is detected from the file contents, not its extension.
##
## @code{@var{tbl} = ods2table (@dots{}, @qcode{'Sheet'}, @var{sheet})} reads a
## specific sheet, selected either by its name (a character vector or string
## scalar) or by a 1-based index over the data sheets. Without this option the
## first data sheet is read.
##
## When the file carries the hidden @qcode{__datatypes_meta__} sheet written by
## the @code{table2ods} method, the variable types, names, descriptions, and
## units are restored from it, and @code{date} and @code{time} cells are
## reconstructed as @code{datetime} and @code{duration} arrays. Integers are
## restored without loss of precision and missing cells become @code{NaN},
## @code{NaT}, or missing strings as appropriate.
##
## When the metadata sheet is absent (a spreadsheet written by another
## application) the variable types are inferred from the cell value types and
## the variables are named @qcode{Var1}, @qcode{Var2}, and so on.
##
## The following round-trip limitations apply, mirroring @code{csv2table}:
## @code{calendarDuration} and @code{categorical} variables are returned as cell
## arrays of character vectors (their values are not reconstructed), missing
## @code{string} values are read back as empty strings, and datetime and
## duration display formats are not preserved, although the values themselves
## are exact.
##
## @end deftypefn
function tbl = ods2table (filename, varargin)
if (nargin < 1)
print_usage ();
endif
if (! (ischar (filename) || iscellstr (filename) || isa (filename, 'string')))
error ("ods2table: FILENAME must be a character vector, cellstr, or string.");
endif
file = char (cellstr (filename));
optNames = {'Sheet'};
dfValues = {[]};
[sheet, args] = parsePairedArguments (optNames, dfValues, varargin(:));
if (! isempty (args))
error ("ods2table: unknown option '%s'.", args{1});
endif
if (! (isempty (sheet) || (ischar (sheet) && isrow (sheet)) ...
|| (isa (sheet, 'string') && isscalar (sheet)) ...
|| (isnumeric (sheet) && isscalar (sheet))))
error (strcat ("ods2table: 'Sheet' must be a sheet name or a scalar", ...
" index."));
endif
if (isa (sheet, 'string'))
sheet = char (sheet);
endif
## Read the workbook into raw grids
[data, vtype, meta] = __ods2table__ (file, sheet);
if (ischar (data))
error ("ods2table: %s", data);
endif
## No metadata sheet -> infer everything from the data cell value types
if (isempty (meta))
tbl = ods_autodetect (data, vtype);
return;
endif
## Parse the descriptive comment on the metadata sheet
hdr = sscanf (meta{1,1}, ...
"# varTypes %d rows; varNames %d rows; varDescriptions %d rows; varUnits %d rows.");
if (numel (hdr) != 4)
error ("ods2table: malformed metadata header in '%s'.", file);
endif
Trows = hdr(1); Nrows = hdr(2); Drows = hdr(3); Urows = hdr(4);
## A table with no variables round-trips to an empty table
if (Nrows == 0)
tbl = table ();
return;
endif
## Split the metadata rows into type, name, description, and unit blocks
body = meta(2:end,:);
T = body(1:Trows,:); body(1:Trows,:) = [];
N = body(1:Nrows,:); body(1:Nrows,:) = [];
if (Drows)
D = body(1:Drows,:); body(1:Drows,:) = [];
else
D = {};
endif
if (Urows)
U = body(1:Urows,:);
else
U = {};
endif
## When the table has no rows the data sheet is empty, so the data grid comes
## back without columns; restore the expected column count from the metadata.
metacols = size (T, 2);
if (size (data, 2) != metacols)
data = cell (size (data, 1), metacols);
vtype = cell (size (data, 1), metacols);
endif
## A leading RowNames column is tagged in the type row with an empty name
RowNames = {};
if (strcmp (T{1,1}, 'RowNames') && isempty (N{1,1}))
RowNames = ods_column_strings (data(:,1), vtype(:,1));
data(:,1) = []; vtype(:,1) = [];
T(:,1) = []; N(:,1) = [];
if (! isempty (D)), D(:,1) = []; endif
if (! isempty (U)), U(:,1) = []; endif
endif
## Group consecutive columns that share a variable name (multicolumn
## variables), then reconstruct each variable from its declared type.
names = N(1,:);
ncol = numel (names);
varNames = {};
varValues = {};
descr = {};
units = {};
c = 1;
while (c <= ncol)
c2 = c;
while (c2 < ncol && strcmp (names{c2+1}, names{c}))
c2 += 1;
endwhile
idx = c:c2;
varNames{end+1} = names{c};
varValues{end+1} = ods_cell2var (data(:,idx), vtype(:,idx), T{1,c});
if (! isempty (D)), descr{end+1} = D{1,c}; endif
if (! isempty (U)), units{end+1} = U{1,c}; endif
c = c2 + 1;
endwhile
if (isempty (RowNames))
tbl = table (varValues{:}, 'VariableNames', varNames);
else
tbl = table (varValues{:}, 'VariableNames', varNames, 'RowNames', RowNames);
endif
if (! isempty (descr))
tbl.Properties.VariableDescriptions = descr;
endif
if (! isempty (units))
tbl.Properties.VariableUnits = units;
endif
endfunction
## Reconstruct one table variable (n-by-k) from its data and value-type columns
## and its declared type T. Missing cells (empty value-type) become NaN, NaT,
## or missing strings according to the type.
function v = ods_cell2var (C, VT, T)
numvartype = {'double', 'single', 'int8', 'uint8', 'int16', 'uint16', ...
'int32', 'uint32', 'int64', 'uint64'};
if (strcmp (T, 'cell'))
v = C;
elseif (strcmp (T, 'logical'))
v = logical (cell2mat (C));
elseif (ismember (T, numvartype))
M = ods_column_numeric (C);
if (any (cellfun (@(x) isinteger (x), C(:))))
v = cellfun (@(x) cast (x, T), num2cell (M)); # element-wise, mixed types
else
v = cast (M, T);
endif
elseif (strncmp (T, 'datetime', 8))
## A zone-aware datetime carries its TimeZone after 'datetime '.
tz = '';
if (numel (T) > 9)
tz = T(10:end);
endif
v = ods_iso2datetime (C, tz);
elseif (strcmp (T, 'duration'))
v = ods_iso2duration (C);
elseif (strcmp (T, 'string'))
v = string (ods_column_strings (C, VT));
elseif (strcmp (T, 'calendarDuration'))
warning ("ods2table: 'calendarDuration' strings are not converted.");
v = ods_column_strings (C, VT);
elseif (strcmp (T, 'categorical'))
warning ("ods2table: 'categorical' strings are not converted.");
v = ods_column_strings (C, VT);
else
v = ods_column_strings (C, VT);
endif
endfunction
## Build a numeric matrix from a data cell block, mapping missing cells to NaN.
function M = ods_column_numeric (C)
M = nan (size (C));
for i = 1:numel (C)
if (! isempty (C{i}))
M(i) = double (C{i});
endif
endfor
endfunction
## Build a cellstr block from a data/value-type cell block: missing cells and
## numeric cells are coerced to text; genuine empty-string cells stay empty.
function S = ods_column_strings (C, VT)
S = cell (size (C));
for i = 1:numel (C)
x = C{i};
if (ischar (x))
S{i} = x;
elseif (isempty (x))
S{i} = '';
else
S{i} = num2str (x);
endif
endfor
endfunction
## Parse an ISO 8601 data block into a datetime array; empty cells become NaT.
## A non-empty TZ restores the datetime's TimeZone (the ISO strings are the
## wall-clock time in that zone).
function dt = ods_iso2datetime (C, tz = '')
sz = size (C);
Y = nan (sz); Mo = nan (sz); D = nan (sz);
h = nan (sz); mi = nan (sz); s = nan (sz);
for i = 1:numel (C)
str = C{i};
if (ischar (str) && ! isempty (str))
val = sscanf (str, "%d-%d-%dT%d:%d:%f");
if (numel (val) == 6)
Y(i) = val(1); Mo(i) = val(2); D(i) = val(3);
h(i) = val(4); mi(i) = val(5); s(i) = val(6);
endif
endif
endfor
if (isempty (tz))
dt = datetime (Y, Mo, D, h, mi, s); # NaN components yield NaT
else
dt = datetime (Y, Mo, D, h, mi, s, 'TimeZone', tz);
endif
endfunction
## Parse an ISO 8601 duration block (PTnHnMnS) into a duration array; empty
## cells become NaN durations.
function du = ods_iso2duration (C)
tot = nan (size (C));
for i = 1:numel (C)
str = C{i};
if (ischar (str) && ! isempty (str))
neg = (str(1) == '-');
if (neg)
str(1) = [];
endif
tk = regexp (str, '^PT([\d.]+)H([\d.]+)M([\d.]+)S$', 'tokens');
if (! isempty (tk))
H = str2double (tk{1}{1});
M = str2double (tk{1}{2});
S = str2double (tk{1}{3});
val = H * 3600 + M * 60 + S;
if (neg)
val = -val;
endif
tot(i) = val;
endif
endif
endfor
du = seconds (tot); # NaN yields a missing duration
endfunction
## Foreign-file fallback: no metadata sheet, so infer each column's type from
## its cell value types and name the variables Var1, Var2, ...
function tbl = ods_autodetect (data, vtype)
ncol = size (data, 2);
varNames = arrayfun (@(x) sprintf ("Var%d", x), 1:ncol, ...
'UniformOutput', false);
varValues = cell (1, ncol);
for c = 1:ncol
vt = vtype(:,c);
seen = vt(! cellfun (@isempty, vt));
if (isempty (seen))
kind = 'string';
else
kind = seen{1};
endif
switch (kind)
case 'float'
varValues{c} = ods_column_numeric (data(:,c));
case 'boolean'
varValues{c} = logical (ods_column_numeric (data(:,c)));
case 'date'
varValues{c} = ods_iso2datetime (data(:,c));
case 'time'
varValues{c} = ods_iso2duration (data(:,c));
otherwise
varValues{c} = ods_column_strings (data(:,c), vtype(:,c));
endswitch
endfor
tbl = table (varValues{:}, 'VariableNames', varNames);
endfunction
%!demo
%! ## `ods2table` reads an OpenDocument spreadsheet into a table. With no options
%! ## it reads the first data sheet.
%!
%! T = table ([38; 43], [71; 69], 'VariableNames', {'Age', 'Height'});
%! filename = fullfile (tempdir (), 'patients.ods');
%! table2ods (T, filename);
%! ods2table (filename)
%!demo
%! ## Point `'Sheet'` at a specific sheet, by name or by 1-based index, to read
%! ## one page of a multi-sheet workbook.
%!
%! filename = fullfile (tempdir (), 'workbook.ods');
%! table2ods (table ([38; 43], 'VariableNames', {'Age'}), filename, 'Sheet', 'Patients');
%! table2ods (table ([1; 2; 3], 'VariableNames', {'Visit'}), filename, 'Sheet', 'Visits');
%! ods2table (filename, 'Sheet', 'Visits')
%!
%! delete (filename);
## Round-trip: numeric double and cellstr text
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; 2; 3], {'a'; 'b'; 'c'}, 'VariableNames', {'x', 'g'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.Properties.VariableNames, {'x', 'g'});
%! assert_equal (R.x, [1; 2; 3]);
%! assert_equal (R.g, {'a'; 'b'; 'c'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: full-range int64/uint64 preserved without precision loss
%!test
%! fn = [tempname() '.fods'];
%! T = table (int64 ([9223372036854775807; -5; 0]), ...
%! uint64 ([18446744073709551615; 1; 0]), ...
%! 'VariableNames', {'i', 'u'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.i), 'int64');
%! assert_equal (class (R.u), 'uint64');
%! assert_equal (R.i, int64 ([9223372036854775807; -5; 0]));
%! assert_equal (R.u, uint64 ([18446744073709551615; 1; 0]));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: narrow integer types cast back from the declared metadata type
%!test
%! fn = [tempname() '.fods'];
%! T = table (int8 ([1; -2]), uint16 ([3; 4]), single ([1.5; 2.5]), ...
%! 'VariableNames', {'a', 'b', 'c'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.a), 'int8');
%! assert_equal (class (R.b), 'uint16');
%! assert_equal (class (R.c), 'single');
%! assert_equal (R.a, int8 ([1; -2]));
%! assert_equal (R.c, single ([1.5; 2.5]));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: logical variable
%!test
%! fn = [tempname() '.fods'];
%! T = table ([true; false; true], 'VariableNames', {'flag'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.flag), 'logical');
%! assert_equal (R.flag, [true; false; true]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: datetime with a NaT, restored to native datetime
%!test
%! fn = [tempname() '.fods'];
%! d = [datetime(2024, 1, 15, 10, 30, 15.5); NaT; datetime(1999, 12, 31, 23, 59, 59)];
%! T = table (d, 'VariableNames', {'when'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.when), 'datetime');
%! assert_equal (isequaln (datevec (R.when), datevec (d)), true);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: duration with negative, sub-second, over-24h, and zero values
%!test
%! fn = [tempname() '.fods'];
%! du = [duration(25, 30, 15.5); duration(-1, -30, 0); duration(0, 0, 0)];
%! T = table (du, 'VariableNames', {'elapsed'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.elapsed), 'duration');
%! assert_equal (isequaln (seconds (R.elapsed), seconds (du)), true);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: missing duration (NaN) restored as a missing duration
%!test
%! fn = [tempname() '.fods'];
%! du = [duration(1, 0, 0); duration(NaN, 0, 0)];
%! T = table (du, 'VariableNames', {'d'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (isnan (seconds (R.d)), [false; true]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: string variable
%!test
%! fn = [tempname() '.fods'];
%! T = table (string ({'x'; 'y'; 'z'}), 'VariableNames', {'s'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (class (R.s), 'string');
%! assert_equal (R.s, string ({'x'; 'y'; 'z'}));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: missing numeric value restored as NaN
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; NaN; 3], 'VariableNames', {'v'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.v, [1; NaN; 3]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: row names
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; 2; 3], 'VariableNames', {'v'}, 'RowNames', {'r1', 'r2', 'r3'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.Properties.RowNames, {'r1'; 'r2'; 'r3'});
%! assert_equal (R.v, [1; 2; 3]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: multicolumn variable kept as one matrix-valued variable
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1 2; 3 4; 5 6], {'p'; 'q'; 'r'}, 'VariableNames', {'mat', 'tag'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (size (R.mat), [3, 2]);
%! assert_equal (R.mat, [1 2; 3 4; 5 6]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: descriptions and units restored when every variable carries one
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; 2], {'a'; 'b'}, 'VariableNames', {'n', 'g'});
%! T.Properties.VariableDescriptions = {'count', 'group'};
%! T.Properties.VariableUnits = {'kg', '-'};
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.Properties.VariableDescriptions, {'count', 'group'});
%! assert_equal (R.Properties.VariableUnits, {'kg', '-'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: descriptions/units written when only some variables carry one
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; 2], [3; 4], 'VariableNames', {'a', 'b'});
%! T.Properties.VariableDescriptions = {'first', ''};
%! T.Properties.VariableUnits = {'', 'kg'};
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.Properties.VariableDescriptions, {'first', ''});
%! assert_equal (R.Properties.VariableUnits, {'', 'kg'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: a zone-aware datetime keeps its TimeZone
%!test
%! fn = [tempname() '.ods'];
%! dt = datetime (2024, 6, [15; 16], 10, 30, 0, 'TimeZone', 'America/New_York');
%! T = table (dt, 'VariableNames', {'t'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.t.TimeZone, 'America/New_York');
%! assert_equal (cellstr (char (R.t)), cellstr (char (dt)));
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Foreign spreadsheet with no metadata sheet: infer types, name Var1, Var2, ...
%!test
%! fn = [tempname() '.fods'];
%! T = table ([1; 2; 3], {'a'; 'b'; 'c'}, 'VariableNames', {'x', 'g'});
%! unwind_protect
%! table2ods (T, fn);
%! txt = fileread (fn);
%! txt = regexprep (txt, ...
%! '', '');
%! fid = fopen (fn, 'w'); fputs (fid, txt); fclose (fid);
%! R = ods2table (fn);
%! assert_equal (R.Properties.VariableNames, {'Var1', 'Var2'});
%! assert_equal (R.Var1, [1; 2; 3]);
%! assert_equal (class (R.Var2), 'cell');
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Select a specific sheet by name and by 1-based index from a multi-sheet file
%!test
%! fn = [tempname() '.fods'];
%! doc = ['' ...
%! '' ...
%! '' ...
%! '' ...
%! '11' ...
%! '' ...
%! '' ...
%! '22' ...
%! ''];
%! fid = fopen (fn, 'w'); fputs (fid, doc); fclose (fid);
%! unwind_protect
%! Rdef = ods2table (fn); # default reads the first sheet
%! assert_equal (Rdef.Var1, 11);
%! Rname = ods2table (fn, 'Sheet', 'Two');
%! assert_equal (Rname.Var1, 22);
%! Ridx = ods2table (fn, 'Sheet', 2);
%! assert_equal (Ridx.Var1, 22);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Error: a requested sheet that does not exist
%!error ...
%! fn = [tempname() '.fods']; ...
%! doc = ['' ...
%! '' ...
%! '']; ...
%! fid = fopen (fn, 'w'); fputs (fid, doc); fclose (fid); ...
%! ods2table (fn, 'Sheet', 'X');
## Error: 'Sheet' of an invalid type
%!error ...
%! ods2table ([tempname() '.fods'], 'Sheet', {1, 2});
## Error: FILENAME of the wrong type
%!error ...
%! ods2table (42);
## Error: a file that cannot be read as an OpenDocument spreadsheet
%!error ...
%! ods2table ([tempname() '.fods']);
## Round-trip: a table with no rows preserves its variable types
%!test
%! fn = [tempname() '.fods'];
%! T = table (zeros (0, 1), int64 (zeros (0, 1)), datetime (zeros (0, 1), 1, 1), ...
%! seconds (zeros (0, 1)), string (cell (0, 1)), ...
%! 'VariableNames', {'d', 'i', 'dt', 'du', 's'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (size (R), [0, 5]);
%! assert_equal (class (R.i), 'int64');
%! assert_equal (class (R.dt), 'datetime');
%! assert_equal (class (R.du), 'duration');
%! assert_equal (class (R.s), 'string');
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: a table with no variables comes back as an empty table
%!test
%! fn = [tempname() '.fods'];
%! unwind_protect
%! table2ods (table (), fn);
%! R = ods2table (fn);
%! assert_equal (istable (R), true);
%! assert_equal (size (R), [0, 0]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: XML metacharacters in a string are escaped and restored
%!test
%! fn = [tempname() '.fods'];
%! T = table ({'a&"c"'; 'x&y'}, 'VariableNames', {'s'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.s, {'a&"c"'; 'x&y'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: leading and trailing whitespace in a string is preserved
%!test
%! fn = [tempname() '.fods'];
%! T = table ({' pad '; ''}, 'VariableNames', {'s'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.s, {' pad '; ''});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip: infinite numeric values are preserved
%!test
%! fn = [tempname() '.fods'];
%! T = table ([Inf; -Inf; 1.5], 'VariableNames', {'v'});
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.v, [Inf; -Inf; 1.5]);
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
## Round-trip through the compressed '.ods' (ZIP) container
%!test
%! fn = [tempname() '.ods'];
%! d = [datetime(2024, 1, 15, 10, 30, 15.5); NaT];
%! T = table ([1; 2], int64 ([9223372036854775807; -5]), d, ...
%! seconds ([90; 3661]), {'a&"c"'; 'y'}, ...
%! 'VariableNames', {'x', 'big', 'when', 'dur', 's'});
%! T.Properties.RowNames = {'r1', 'r2'};
%! unwind_protect
%! table2ods (T, fn);
%! R = ods2table (fn);
%! assert_equal (R.Properties.RowNames, {'r1'; 'r2'});
%! assert_equal (R.x, [1; 2]);
%! assert_equal (R.big, int64 ([9223372036854775807; -5]));
%! assert_equal (class (R.when), 'datetime');
%! assert_equal (isequaln (datevec (R.when), datevec (d)), true);
%! assert_equal (isequaln (seconds (R.dur), [90; 3661]), true);
%! assert_equal (R.s, {'a&"c"'; 'y'});
%! unwind_protect_cleanup
%! delete (fn);
%! end_unwind_protect
pr0m1th3as-datatypes-9c9a8d3/inst/parsePairedArguments.m 0000664 0000000 0000000 00000014157 15227665741 0023345 0 ustar 00root root 0000000 0000000 ## Copyright (C) 2026 Andreas Bertsatos
##
## This file is part of the datatypes package for GNU Octave.
##
## This program is free software; you can redistribute it and/or modify it under
## the terms of the GNU General Public License as published by the Free Software
## Foundation; either version 3 of the License, or (at your option) any later
## version.
##
## This program is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public License along with
## this program; if not, see .
## -*- texinfo -*-
## @deftypefn {datatypes} {[@var{optarg_1}, @dots{}, @var{optarg_N}] =} @
## parsePairedArguments (@var{optarg_names}, @var{default_values}, @var{arg_list})
## @deftypefnx {datatypes} {[@var{optarg_1}, @dots{}, @var{optarg_N}, @var{rem_args}] =} @
## parsePairedArguments (@var{optarg_names}, @var{default_values}, @var{arg_list})
##
## Parse optional paired arguments from variable argument list.
##
## @code{parsePairedArguments} parses the optional paired arguments specified
## by @var{optarg_names} from the variable input argument list, @var{arg_list}.
## Any @var{optarg_names} that are not found in @var{arg_list} are returned with
## their default value specified by @var{default_values}, which must be a cell
## array with the same number of elements as @var{optarg_names}.
##
## @var{optarg_names} must be a cell array of character vectors or a string
## array with the same number of elements as the number of output arguments
## specified as @code{[@var{optarg_1}, @dots{}, @var{optarg_N}]}, while an extra
## output argument, @var{rem_args}, may be specified for the remaining input
## arguments in @var{arg_list} that were not specified by @var{optarg_names}.
##
## Each property name specified by @var{optarg_names} is case insensitive.
##
## The following example illustrates how to use @code{parsePairedArguments}
## inside a function to parse optional paired arguments for three properties,
## namely @qcode{'A'}, @qcode{'B'}, and @qcode{'C'}.
##
## @example
## ## Declare optional property Names and their default Values
## optNames = @{'A', 'B', 'C'@};
## dfValues = @{1, 2, 3@};
##
## ## Parse optional Name-Value paired arguments
## [var_A, var_B, var_C, args] = ...
## parsePairedArguments (optNames, dfValues, args);
## @end example
##
## @end deftypefn
function [varargout] = parsePairedArguments (optNames, dfValues, args)
## Input validation
if (nargin != 3)
error ("parsePairedArguments: invalid number of input arguments.");
endif
if (isa (optNames, 'string'))
optNames = cellstr (optNames);
endif
if (! iscellstr (optNames))
error (strcat ("parsePairedArguments: OPTARG_NAMES must be a cell", ...
" array of character vectors or a string array."));
endif
if (! iscell (dfValues))
error ("parsePairedArguments: DFVALUES must be a cell array.");
endif
optN = numel (optNames);
if (optN != numel (dfValues))
error ("parsePairedArguments: OPTARG_NAMES mismatches DFVALUES.");
endif
if (nargout < optN || nargout > optN + 1)
error ("parsePairedArguments: inconsistent number of output arguments.");
endif
if (! iscell (args))
error ("parsePairedArguments: ARG_LIST must be a cell array.");
endif
## Search through all input arguments for Name/Value pairs
foundNames = [];
nargs = numel (args);
for ii = nargs-1:-1:1
tmp_arg = args{ii};
if (isstring (tmp_arg))
tmp_arg = char (tmp_arg);
endif
if (ischar (tmp_arg))
idx = strcmpi (tmp_arg, optNames);
if (any (idx))
idx = find (idx);
varargout{idx} = args{ii+1};
foundNames = [foundNames, idx];
args(ii:ii+1) = [];
endif
endif
endfor
## Find optNames that were not in args and add defaults
allNames = 1:numel (optNames);
notfound = ! ismember (allNames, foundNames);
defNames = optNames(notfound);
for ii = 1:numel (defNames)
idx = find (strcmpi (defNames{ii}, optNames));
varargout{idx} = dfValues{idx};
endfor
## Append remaining input arguments in varargout
if (nargout > optN)
idx = optN + 1;
varargout{idx} = args(:);
endif
endfunction
%!shared optNames, dfValues
%! optNames = {'A', 'B', 'C'};
%! dfValues = {{3}, [1, 2], 'text'};
%!test
%! [a, b, c] = parsePairedArguments (optNames, dfValues, {'A', 5});
%! assert_equal (a, 5);
%! assert_equal (b, [1, 2]);
%! assert_equal (c, 'text');
%!test
%! [a, b, c, args] = parsePairedArguments (optNames, dfValues, {4, 'D', 5});
%! assert_equal (numel (args), 3);
%! assert_equal (args{2}, 'D');
%! assert_equal (a, {3});
%! assert_equal (b, [1, 2]);
%! assert_equal (c, 'text');
%!test
%! [a, b, c] = parsePairedArguments (optNames, dfValues, ...
%! {'A', 5, 'b', 1, 'C', 'test'});
%! assert_equal (a, 5);
%! assert_equal (b, 1);
%! assert_equal (c, 'test');
%!test
%! [a, b, c, args] = parsePairedArguments (optNames, dfValues, {1});
%! assert_equal (args, {1});
%! assert_equal (a, {3});
%! assert_equal (b, [1, 2]);
%! assert_equal (c, 'text');
%!error ...
%! parsePairedArguments (optNames, dfValues)
%!error ...
%! parsePairedArguments ([1, 2, 3], dfValues, {1})
%!error ...
%! parsePairedArguments (optNames, [1, 2, 3], {1})
%!error ...
%! parsePairedArguments (optNames(1:2), dfValues, {1})
%!error ...
%! [a, b] = parsePairedArguments (optNames, dfValues, {1})
%!error ...
%! [a, b, c, d, e] = parsePairedArguments (optNames, dfValues, {1})
%!error ...
%! [a, b, c, e] = parsePairedArguments (optNames, dfValues, 1)
pr0m1th3as-datatypes-9c9a8d3/inst/patients.mat 0000664 0000000 0000000 00000066071 15227665741 0021376 0 ustar 00root root 0000000 0000000 Octave-1-L Age matrixd C@ E@ C@ D@ H@ G@ @@ D@ <@ ?@ F@ E@ 9@ C@ B@ H@ @@ ;@ B@ I@ H@ C@ D@ F@ <@ 9@ C@ 9@ B@ >@ F@ D@ 9@ G@ F@ H@ F@ A@ @@ C@ C@ F@ F@ B@ F@ B@ >@ C@ E@ E@ H@ F@ E@ G@ I@ C@ D@ F@ B@ C@ =@ <@ >@ <@ =@ B@ F@ @@ ?@ H@ 9@ D@ C@ D@ @@ ?@ A@ @@ E@ H@ A@ C@ <@ =@ @@ C@ B@ H@ ?@ B@ C@ F@ >@ H@ H@ 9@ F@ H@ F@ H@ Diastolic matrixd @W@ @S@ T@ R@ T@ Q@ V@ T@ S@ U@ @S@ Q@ R@ W@ S@ W@ W@ S@ @S@ S@ R@ S@ V@ V@ X@ @S@ T@ S@ T@ @V@ W@ T@ T@ U@ W@ T@ V@ @U@ V@ R@ W@ T@ @V@ X@ @V@ @S@ @T@ S@ T@ S@ W@ V@ V@ U@ @V@ S@ R@ T@ S@ @T@ @S@ @R@ @U@ S@ T@ T@ S@ T@ S@ T@ R@ V@ R@ S@ @U@ U@ R@ S@ @T@ S@ @U@ S@ T@ T@ T@ W@ W@ X@ U@ @T@ V@ @S@ V@ S@ @R@ X@ W@ R@ @W@ U@ Gender celld sq_string Male sq_string Male sq_string Female sq_string Female sq_string Female sq_string Female sq_string Female sq_string Male sq_string Male sq_string Female sq_string Female sq_string Female sq_string Male sq_string Male sq_string Female sq_string Male sq_string Male sq_string Female sq_string Male sq_string Male sq_string Female sq_string Female sq_string Female sq_string Female sq_string Female sq_string Male sq_string Female sq_string Female sq_string Male sq_string Male sq_string Female sq_string Female sq_string Female sq_string Male sq_string Male sq_string Female