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

@c Copyright (C) 1996-2019 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 {} {} unique (@dots{}, "sorted")
@deftypefnx {} {} unique (@dots{}, "stable")
@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")
@deftypefnx {} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "legacy")
Return the unique elements of @var{x}.

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}.  The input must be a 2-D numeric matrix to use this option.

The optional argument @qcode{"sorted"}/@qcode{"stable"} controls the order
in which unique values appear in the output.  The default is
@qcode{"sorted"} and values in the output are placed in ascending order.
The alternative @qcode{"stable"} preserves the order found in the input
@var{x}.

If requested, return column 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 the flags
@qcode{"first"} or @qcode{"last"} may be given.  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{"first"}.

Example 1 : sort order

@example
@group
unique ([3, 1, 1, 2])
@result{} [1, 2, 3]
unique ([3, 1, 1, 2], "stable")
@result{} [3, 1, 2]
@end group
@end example

Example 2 : index selection

@example
@group
[~, @var{i}] = unique ([3, 1, 1, 2], "first")
@result{} @var{i} = [2; 4; 1]
[~, @var{i}] = unique ([3, 1, 1, 2], "last")
@result{} @var{i} = [3; 4; 1]
@end group
@end example

Programming Notes: The input flag @qcode{"legacy"} changes the algorithm
to be compatible with @sc{matlab} releases prior to R2012b.  Specifically,
The index ordering flag is changed to @qcode{"last"}, and the shape of the
outputs @var{i}, @var{j} will follow the shape of the input @var{x} rather
than always being column vectors.

The third output, @var{j}, has not been implemented yet when the sort
order is @qcode{"stable"}.

@xseealso{@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} =} intersect (@dots{}, "sorted")
@deftypefnx {} {@var{c} =} intersect (@dots{}, "stable")
@deftypefnx {} {@var{c} =} intersect (@dots{}, "legacy")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@dots{})

Return the unique elements common to both @var{a} and @var{b}.

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 numeric matrices to use this
option.

The optional argument @qcode{"sorted"}/@qcode{"stable"} controls the order
in which unique values appear in the output.  The default is
@qcode{"sorted"} and values in the output are placed in ascending order.
The alternative @qcode{"stable"} preserves the order found in the input.

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

Programming Note: The input flag @qcode{"legacy"} changes the algorithm
to be compatible with @sc{matlab} releases prior to R2012b.

@xseealso{@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} =} union (@dots{}, "sorted")
@deftypefnx {} {@var{c} =} union (@dots{}, "stable")
@deftypefnx {} {@var{c} =} union (@dots{}, "legacy")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} union (@dots{})

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

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 numeric matrices to use
this option.

The optional argument @qcode{"sorted"}/@qcode{"stable"} controls the order
in which unique values appear in the output.  The default is
@qcode{"sorted"} and values in the output are placed in ascending order.
The alternative @qcode{"stable"} preserves the order found in the input.

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

Programming Note: The input flag @qcode{"legacy"} changes the algorithm
to be compatible with @sc{matlab} releases prior to R2012b.

@xseealso{@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} =} setdiff (@dots{}, "sorted")
@deftypefnx {} {@var{c} =} setdiff (@dots{}, "stable")
@deftypefnx {} {@var{c} =} setdiff (@dots{}, "legacy")
@deftypefnx {} {[@var{c}, @var{ia}] =} setdiff (@dots{})
Return the unique elements in @var{a} that are not in @var{b}.

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 numeric matrices to
use this option.

The optional argument @qcode{"sorted"}/@qcode{"stable"} controls the order
in which unique values appear in the output.  The default is
@qcode{"sorted"} and values in the output are placed in ascending order.
The alternative @qcode{"stable"} preserves the order found in the input.

If requested, return the index vector @var{ia} such that
@code{@var{c} = @var{a}(@var{ia})}.

Programming Note: The input flag @qcode{"legacy"} changes the algorithm
to be compatible with @sc{matlab} releases prior to R2012b.

@xseealso{@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} =} setxor (@dots{}, "sorted")
@deftypefnx {} {@var{c} =} setxor (@dots{}, "stable")
@deftypefnx {} {@var{c} =} setxor (@dots{}, "legacy")
@deftypefnx {} {[@var{c}, @var{ia}, @var{ib}] =} setxor (@dots{})

Return the unique elements exclusive to sets @var{a} or @var{b}.

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 numeric matrices to use
this option.

The optional argument @qcode{"sorted"}/@qcode{"stable"} controls the order
in which unique values appear in the output.  The default is
@qcode{"sorted"} and values in the output are placed in ascending order.
The alternative @qcode{"stable"} preserves the order found in the input.

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

Programming Note: The input flag @qcode{"legacy"} changes the algorithm
to be compatible with @sc{matlab} releases prior to R2012b.

@xseealso{@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
     @result{} s_idx = 1
@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

@xseealso{@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.

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