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

@c Copyright (C) 1996-2025 The Octave Project Developers
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{y} =} unique (@var{x})
@deftypefnx {} {@var{y} =} unique (@var{x}, "rows")
@deftypefnx {} {@var{y} =} unique (@dots{}, "sorted")
@deftypefnx {} {@var{y} =} 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.

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


@c uniquetol scripts/set/uniquetol.m
@anchor{XREFuniquetol}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{c} =} uniquetol (@var{A})
@deftypefnx {} {@var{c} =} uniquetol (@var{A}, @var{tol})
@deftypefnx {} {@var{c} =} uniquetol (@dots{}, @var{property}, @var{value})
@deftypefnx {} {[@var{c}, @var{ia}, @var{ic}] =} uniquetol (@dots{})
Return the unique elements of @var{A} within tolerance @var{tol}.

Two values, @var{x} and @var{y}, are within relative tolerance if
@code{abs (@var{x} - @var{y}) <= @var{tol} * max (abs (@var{A}(:)))}.

The input @var{A} must be a real (non-complex) floating point type (double
or single).

If @var{tol} is unspecified, the default tolerance is 1e-12 for double
precision input or 1e-6 for single precision input.

The function may also be called with the following optional property/value
pairs.  Property/value pairs must be passed after other input arguments:

@table @asis
@item @qcode{"ByRows"} (default: @code{false})
When true, return the unique rows of @var{A}.  @var{A} must be a 2-D array
to use this option.  For rows, the criteria for uniqueness is changed to
@code{all (abs (@var{x} - @var{y}) <= @var{tol}*max (abs (@var{A}),[],1))}
which compares each column component of a row against a column-specific
tolerance.

@item @qcode{"DataScale"}
The tolerance test is changed to
@code{abs (@var{x} - @var{y}) <= @var{tol}*@var{DS}} where @var{DS} is a
scalar unless the property @qcode{"ByRows"} is true.  In that case, @var{DS}
can either be a scalar or a vector with a length equal to the number of
columns in @var{A}.  Using a value of @code{1.0} for @var{DS} will change
the tolerance from a relative one to an absolute tolerance.  Using a value
of @code{Inf} will disable testing.

@item @qcode{"OutputAllIndices"} (default: @code{false})
When true, @var{ia} is a cell array (not a vector) that contains the indices
for @emph{all} elements in @var{A} that are within tolerance of a value in
@var{C}.  That is, each cell in @var{ia} corresponds to a single unique
value in @var{C}, and the values in each cell correspond to locations in
@var{A}.
@end table

The output @var{c} is a row vector if the input @var{A} is a row vector.
For all other cases, a column vector is returned.

The optional output @var{ia} is a column index vector such that
@code{@var{c} = @var{A}(@var{ia})}.  If the @qcode{"ByRows"} property is
true, the condition is @code{@var{c} = @var{A}(@var{ia}, :)}.  If the
@qcode{"OutputAllIndices"} property is true, then the values
@code{@var{A}(@var{ia}@{@var{i}@})} are all within tolerance of the unique
value @code{@var{c}(@var{i})}.

The optional output @var{ic} is a column index vector such that
@code{@var{A} = @var{c}(@var{ic})} when @var{A} is a vector.  When @var{A}
is a matrix, @code{@var{A}(:) = @var{c}(@var{ic})}.  If the @qcode{"ByRows"}
property is true then @code{@var{A} = @var{c}(@var{ic},:)}.

Example: small round-off errors require @code{uniquetol}, not @code{unique}

@example
@group
x = [1:5];
## Inverse_Function (Function (x)) should return exactly x
y = exp (log (x));
D = unique ([x, y])
@result{} [1   2   3   3   4   5   5]
C = uniquetol ([x, y])
@result{} [1   2   3   4   5]
@end group
@end example

@xseealso{@ref{XREFunique,,unique}, @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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@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}, @ref{XREFismembertol,,ismembertol}}
@end deftypefn


@c ismembertol scripts/set/ismembertol.m
@anchor{XREFismembertol}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} ismembertol (@var{a}, @var{s})
@deftypefnx {} {@var{tf} =} ismembertol (@var{a}, @var{s}, @var{tol})
@deftypefnx {} {@var{tf} =} ismembertol (@var{a}, @var{s}, @var{name}, @var{value})
@deftypefnx {} {[@var{tf}, @var{s_idx}] =} ismembertol (@dots{})
Check if values are members of a set within a tolerance.

This functions returns a logical matrix @var{tf} with the same shape as
@var{a} which is true (1) where the element in @var{a} is close to @var{s}
within a tolerance @var{tol} and false (0) if it is not.  If @var{tol} is
not specified, a default tolerance of @code{1e-6} is used.

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

The inputs @var{a} and @var{s} must be numeric values.

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

Optional property/value pairs may be given to change the function's
behavior.  The property may be one of following strings:

@table @asis
@item @qcode{"ByRows"}
If set to @code{false} (default), all elements in @var{a} and @var{s} are
treated separately.  If set to @code{true}, @var{tf} will be @code{true}
for each row in @var{a} that matches a row in @var{s} within the given
tolerance.  Two rows, @var{u} and @var{v}, are within tolerance if they
fulfill the condition @code{all (abs (u-v) <= tol*max (abs ([a;s])))}.

@item @qcode{"OutputAllIndices"}
If set to @code{false} (default), @var{s_idx} contains indices for one
of the matches.  If set to @code{true}, @var{s_idx} is a cell array
containing the indices for all elements in @var{s} that are within tolerance
of the corresponding value in @var{a}.

@item @qcode{"DataScale"}
The provided value @var{DS} is used to change the scale factor in the
tolerance test to @code{abs (u-v) <= tol*@var{DS}}.  By default, the maximum
absolute value in @var{a} and @var{s} is used as the scale factor.
@end table

Example:

@example
@group
s = [1:6].' * pi;
a = 10.^log10 (x);
[tf, s_idx] = ismembertol (a, s);
@end group
@end example

@xseealso{@ref{XREFismember,,ismember}, @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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{p} =} powerset (@var{a})
@deftypefnx {} {@var{p} =} 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