@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2018 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Sets
@chapter Sets

Octave has a number of functions for managing sets of data.  A set is defined
as a collection of unique elements and is typically represented by a vector of
numbers sorted in ascending order.  Any vector or matrix can be converted to a
set by removing duplicates through the use of the @code{unique} function.
However, it isn't necessary to explicitly create a set as all of the functions
which operate on sets will convert their input to a set before proceeding.

@c unique scripts/set/unique.m
@anchor{XREFunique}
@deftypefn  {} {} unique (@var{x})
@deftypefnx {} {} unique (@var{x}, "rows")
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{})
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "first")
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "last")
Return the unique elements of @var{x} sorted in ascending order.

If the input @var{x} is a column vector then return a column vector;
Otherwise, return a row vector.  @var{x} may also be a cell array of
strings.

If the optional argument @qcode{"rows"} is given then return the unique
rows of @var{x} sorted in ascending order.  The input must be a 2-D matrix
to use this option.

If requested, return index vectors @var{i} and @var{j} such that
@code{@var{y} = @var{x}(@var{i})} and @code{@var{x} = @var{y}(@var{j})}.

Additionally, if @var{i} is a requested output then one of
@qcode{"first"} or @qcode{"last"} may be given as an input.  If
@qcode{"last"} is specified, return the highest possible indices in
@var{i}, otherwise, if @qcode{"first"} is specified, return the lowest.
The default is @qcode{"last"}.
@seealso{@ref{XREFunion,,union}, @ref{XREFintersect,,intersect}, @ref{XREFsetdiff,,setdiff}, @ref{XREFsetxor,,setxor}, @ref{XREFismember,,ismember}}
@end deftypefn


@menu
* Set Operations::
@end menu

@node Set Operations
@section Set Operations

Octave supports several basic set operations.  Octave can compute the union,
intersection, and difference of two sets.  Octave also supports the
@emph{Exclusive Or} set operation.

The functions for set operations all work in the same way by accepting two
input sets and returning a third set.  As an example, assume that @code{a} and
@code{b} contains two sets, then

@example
union (a, b)
@end example

@noindent
computes the union of the two sets.

Finally, determining whether elements belong to a set can be done with the
@code{ismember} function.  Because sets are ordered this operation is very
efficient and is of order O(log2(n)) which is preferable to the @code{find}
function which is of order O(n).

@c intersect scripts/set/intersect.m
@anchor{XREFintersect}
@deftypefn  {} {@var{c} =} intersect (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} intersect (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@dots{})

Return the unique elements common to both @var{a} and @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the common rows of
@var{a} and @var{b}.  The inputs must be 2-D matrices to use this option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{c} = @var{a}(@var{ia})} and @code{@var{c} = @var{b}(@var{ib})}.

@seealso{@ref{XREFunique,,unique}, @ref{XREFunion,,union}, @ref{XREFsetdiff,,setdiff}, @ref{XREFsetxor,,setxor}, @ref{XREFismember,,ismember}}
@end deftypefn


@c union scripts/set/union.m
@anchor{XREFunion}
@deftypefn  {} {@var{c} =} union (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} union (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} union (@dots{})

Return the unique elements that are in either @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return rows that are in
either @var{a} or @var{b}.  The inputs must be 2-D matrices to use this
option.

The optional outputs @var{ia} and @var{ib} are index vectors such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@seealso{@ref{XREFunique,,unique}, @ref{XREFintersect,,intersect}, @ref{XREFsetdiff,,setdiff}, @ref{XREFsetxor,,setxor}, @ref{XREFismember,,ismember}}
@end deftypefn


@c setdiff scripts/set/setdiff.m
@anchor{XREFsetdiff}
@deftypefn  {} {@var{c} =} setdiff (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} setdiff (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}] =} setdiff (@dots{})
Return the unique elements in @var{a} that are not in @var{b} sorted in
ascending order.

If @var{a} is a row vector return a row vector; Otherwise, return a
column vector.  The inputs may also be cell arrays of strings.

If the optional input @qcode{"rows"} is given then return the rows in
@var{a} that are not in @var{b}.  The inputs must be 2-D matrices to use
this option.

If requested, return the index vector @var{ia} such that
@code{@var{c} = @var{a}(@var{ia})}.
@seealso{@ref{XREFunique,,unique}, @ref{XREFunion,,union}, @ref{XREFintersect,,intersect}, @ref{XREFsetxor,,setxor}, @ref{XREFismember,,ismember}}
@end deftypefn


@c setxor scripts/set/setxor.m
@anchor{XREFsetxor}
@deftypefn  {} {@var{c} =} setxor (@var{a}, @var{b})
@deftypefnx {} {@var{c} =} setxor (@var{a}, @var{b}, "rows")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} setxor (@dots{})

Return the unique elements exclusive to sets @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the rows exclusive
to sets @var{a} and @var{b}.  The inputs must be 2-D matrices to use this
option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@seealso{@ref{XREFunique,,unique}, @ref{XREFunion,,union}, @ref{XREFintersect,,intersect}, @ref{XREFsetdiff,,setdiff}, @ref{XREFismember,,ismember}}
@end deftypefn


@c ismember scripts/set/ismember.m
@anchor{XREFismember}
@deftypefn  {} {@var{tf} =} ismember (@var{a}, @var{s})
@deftypefnx {} {@var{tf} =} ismember (@var{a}, @var{s}, "rows")
@deftypefnx {} {[@var{tf}, @var{s_idx}] =} ismember (@dots{})

Return a logical matrix @var{tf} with the same shape as @var{a} which is
true (1) if the element in @var{a} is found in @var{s} and false (0) if it
is not.

If a second output argument is requested then the index into @var{s} of each
matching element is also returned.

@example
@group
a = [3, 10, 1];
s = [0:9];
[tf, s_idx] = ismember (a, s)
     @result{} tf = [1, 0, 1]
     @result{} s_idx = [4, 0, 2]
@end group
@end example

The inputs @var{a} and @var{s} may also be cell arrays.

@example
@group
a = @{"abc"@};
s = @{"abc", "def"@};
[tf, s_idx] = ismember (a, s)
     @result{} tf = [1, 0]
     @result{} s_idx = [1, 0]
@end group
@end example

If the optional third argument @qcode{"rows"} is given then compare rows
in @var{a} with rows in @var{s}.  The inputs must be 2-D matrices with the
same number of columns to use this option.

@example
@group
a = [1:3; 5:7; 4:6];
s = [0:2; 1:3; 2:4; 3:5; 4:6];
[tf, s_idx] = ismember (a, s, "rows")
     @result{} tf = logical ([1; 0; 1])
     @result{} s_idx = [2; 0; 5];
@end group
@end example

@seealso{@ref{XREFlookup,,lookup}, @ref{XREFunique,,unique}, @ref{XREFunion,,union}, @ref{XREFintersect,,intersect}, @ref{XREFsetdiff,,setdiff}, @ref{XREFsetxor,,setxor}}
@end deftypefn


@c powerset scripts/set/powerset.m
@anchor{XREFpowerset}
@deftypefn  {} {} powerset (@var{a})
@deftypefnx {} {} powerset (@var{a}, "rows")
Compute the powerset (all subsets) of the set @var{a}.

The set @var{a} must be a numerical matrix or a cell array of strings.  The
output will always be a cell array of either vectors or strings.

With the optional argument @qcode{"rows"}, each row of the set @var{a} is
considered one element of the set.  The input must be a 2-D numeric matrix
to use this argument.

@seealso{@ref{XREFunique,,unique}, @ref{XREFunion,,union}, @ref{XREFintersect,,intersect}, @ref{XREFsetdiff,,setdiff}, @ref{XREFsetxor,,setxor}, @ref{XREFismember,,ismember}}
@end deftypefn