octave_packages/general-1.3.1/@dict/dict.m

   1 ## Copyright (C) 2009 VZLU Prague, a.s., Czech Republic
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn{Function File} {d =} dict (@var{keys}, @var{values})
  18 ## @deftypefnx{Function File} {d =} dict ()
  19 ## @deftypefnx{Function File} {d =} dict (@var{str})
  20 ## Creates a dictionary object with given keys and values. @var{keys}
  21 ## should be a cell array of strings; @var{values} should be a cell array
  22 ## with matching size. @var{values} can also be a singleton array, in
  23 ## which case it is expanded to the proper size; or omitted, in which case
  24 ## the default value of empty matrix is used.
  25 ## If neither @var{keys} nor @var{values} are supplied, an empty dictionary
  26 ## is constructed.
  27 ## If a scalar structure is supplied as an argument, it is converted to
  28 ## a dictionary using field names as keys.
  29 ##
  30 ## A dictionary can be indexed either by a single string or cell array of
  31 ## strings, like this:
  32 ##
  33 ## @example
  34 ##   d = dict (keys, values);
  35 ##   d(str) # result is a single value
  36 ##   d(cellstr) # result is a cell array
  37 ## @end example
  38 ##
  39 ## In the first case, the stored value is returned directly; in the second case,
  40 ## a cell array is returned. The cell array returned inherits the shape of the index.
  41 ##
  42 ## Similarly, indexed assignment works like this:
  43 ##
  44 ## @example
  45 ##   d = dict (keys, values);
  46 ##   d(str) = val; # store a single value
  47 ##   d(cellstr) = vals; # store a cell array
  48 ##   d(cellstr) = []; # delete a range of keys
  49 ## @end example
  50 ##
  51 ## Any keys that are not present in the dictionary are added. The values of
  52 ## existing keys are overwritten. In the second case, the lengths of index and
  53 ## rhs should match or rhs should be a singleton array, in which case it is
  54 ## broadcasted.
  55 ##
  56 ## It is also possible to retrieve keys and values as cell arrays, using the
  57 ## "keys" and "values" properties. These properties are read-only.
  58 ##
  59 ## @end deftypefn
  60
  61 ## Author: Jaroslav Hajek <highegg@gmail.com>
  62
  63 function d = dict (keys, values)
  64
  65   if (nargin == 0)
  66     keys = values = cell (0, 1);
  67   elseif (nargin == 1)
  68     if (iscellstr (keys))
  69       keys = sort (keys(:));
  70       values = cell (numel (keys), 1);
  71     elseif (isstruct (keys))
  72       values = struct2cell (keys)(:,:);
  73       if (columns (values) != 1)
  74         error ("dict: structure must be a scalar");
  75       endif
  76       [keys, ind] = sort (fieldnames (keys));
  77       values = values(ind);
  78     else
  79       error ("dict: keys must be a cell vector of strings");
  80     endif
  81   elseif (nargin == 2)
  82     [keys, idx] = sort (keys(:));
  83     values = values (idx)(:);
  84   else
  85     print_usage ();
  86   endif
  87
  88   d = class (struct ("keys", {keys}, "values", {values}), "dict");
  89
  90 endfunction
  91
  92 %!test
  93 %! free = dict ();
  94 %! free({"computing", "society"}) = {true};
  95 %! assert (free("computing"), free("society"));