Mercurial > jwe > octave
changeset 24161:48cf0f4cc7c8
Clarify documentation for isnull (bug #5035950359503595035950359)
* ov-null-mat.cc (Fisnull): Clarify documentation.
author | Rik <rik@octave.org> |
---|---|
date | Sat, 21 Oct 2017 14:35:58 -0700 |
parents | d0cee5e09879 |
children | 312c00dd723a |
files | libinterp/octave-value/ov-null-mat.cc |
diffstat | 1 files changed, 30 insertions(+), 10 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/octave-value/ov-null-mat.cc Fri Oct 20 18:56:29 2017 +0200 +++ b/libinterp/octave-value/ov-null-mat.cc Sat Oct 21 14:35:58 2017 -0700 @@ -99,18 +99,38 @@ Return true if @var{x} is a special null matrix, string, or single quoted string. -Indexed assignment with such a value on the right-hand side should delete -array elements. This function should be used when overloading indexed -assignment for user-defined classes instead of @code{isempty}, to -distinguish the cases: +Indexed assignment with such a null value on the right-hand side should delete +array elements. This function is used in place of @code{isempty} when +overloading the indexed assignment method (@code{subsasgn}) for user-defined +classes. @code{isnull} is used to distinguish between these two cases: + +@code{@var{A}(@var{I}) = []} + +and + +@code{@var{X} = []; @var{A}(@var{I}) = @var{X}} + +In the first assignment, the right-hand side is @code{[]} which is a special +null value. As long as the index @var{I} is not empty, this code should +delete elements from @var{A} rather than perform assignment. -@table @asis -@item @code{A(I) = []} -This should delete elements if @code{I} is nonempty. +In the second assignment, the right-hand side is empty (because @var{X} is +@code{[]}), but it is @strong{not} null. This code should assign the empty +value to elements in @var{A}. + +An example from Octave's built-in char class demonstrates the interpreter +behavior when @code{isnull} is used correctly. -@item @code{X = []; A(I) = X} -This should give an error if @code{I} is nonempty. -@end table +@example +@group +str = "Hello World"; +nm = "Wally"; +str(7:end) = nm # indexed assignment + @result{} str = Hello Wally +str(7:end) = "" # indexed deletion + @result{} str = Hello +@end group +@end example @seealso{isempty, isindex} @end deftypefn */) {