octave_packages/m/miscellaneous/compare_versions.m

   1 ## Copyright (C) 2006-2012 Bill Denney
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn {Function File} {} compare_versions (@var{v1}, @var{v2}, @var{operator})
  21 ## Compare two version strings using the given @var{operator}.
  22 ##
  23 ## This function assumes that versions @var{v1} and @var{v2} are
  24 ## arbitrarily long strings made of numeric and period characters
  25 ## possibly followed by an arbitrary string (e.g., "1.2.3", "0.3",
  26 ## "0.1.2+", or "1.2.3.4-test1").
  27 ##
  28 ## The version is first split into numeric and character portions
  29 ## and then the parts are padded to be the same length (i.e., "1.1" would be
  30 ## padded to be "1.1.0" when being compared with "1.1.1", and
  31 ## separately, the character parts of the strings are padded with
  32 ## nulls).
  33 ##
  34 ## The operator can be any logical operator from the set
  35 ##
  36 ## @itemize @bullet
  37 ## @item
  38 ## "=="
  39 ## equal
  40 ##
  41 ## @item
  42 ## "<"
  43 ## less than
  44 ##
  45 ## @item
  46 ## "<="
  47 ## less than or equal to
  48 ##
  49 ## @item
  50 ## ">"
  51 ## greater than
  52 ##
  53 ## @item
  54 ## ">="
  55 ## greater than or equal to
  56 ##
  57 ## @item
  58 ## "!="
  59 ## not equal
  60 ##
  61 ## @item
  62 ## "~="
  63 ## not equal
  64 ## @end itemize
  65 ##
  66 ## Note that version "1.1-test2" will compare as greater than
  67 ## "1.1-test10".  Also, since the numeric part is compared first, "a"
  68 ## compares less than "1a" because the second string starts with a
  69 ## numeric part even though @code{double("a")} is greater than
  70 ## @code{double("1").}
  71 ## @end deftypefn
  72
  73 ## Author: Bill Denney <denney@seas.upenn.edu>
  74
  75 function out = compare_versions (v1, v2, operator)
  76
  77   if (nargin != 3)
  78     print_usage ();
  79   endif
  80
  81   ## Make sure that the version numbers are valid.
  82   if (! (ischar (v1) && ischar (v2)))
  83     error ("compare_versions: both version numbers must be strings");
  84   elseif (rows (v1) != 1 || rows (v2) != 1)
  85     error ("compare_versions: version numbers must be a single row");
  86   endif
  87
  88   ## check and make sure that the operator is valid
  89   if (! ischar (operator))
  90     error ("compare_versions: OPERATOR must be a character string");
  91   elseif (numel (operator) > 2)
  92     error("compare_versions: OPERATOR must be 1 or 2 characters long");
  93   endif
  94
  95   ## trim off any character data that is not part of a normal version
  96   ## number
  97   numbers = "0123456789.";
  98
  99   v1firstchar = find (! ismember (v1, numbers), 1);
 100   v2firstchar = find (! ismember (v2, numbers), 1);
 101   if (! isempty (v1firstchar))
 102     v1c = v1(v1firstchar:length(v1));
 103     v1nochar = v1(1:v1firstchar-1);
 104   else
 105     v1c = "";
 106     v1nochar = v1;
 107   endif
 108   if (! isempty (v2firstchar))
 109     v2c = v2(v2firstchar:length(v2));
 110     v2nochar = v2(1:v2firstchar-1);
 111   else
 112     v2c = "";
 113     v2nochar = v2;
 114   endif
 115
 116   v1n = str2num (char (strsplit (v1nochar, ".")));
 117   v2n = str2num (char (strsplit (v2nochar, ".")));
 118   if ((isempty (v1n) && isempty (v1c)) || (isempty (v2n) && isempty(v2c)))
 119     error ("compare_versions: given version strings are not valid: %s %s",
 120            v1, v2);
 121   endif
 122
 123   ## Assume that any additional elements would be 0 if one is longer
 124   ## than the other.
 125   maxnumlen = max ([length(v1n) length(v2n)]);
 126   if (length (v1n) < maxnumlen)
 127     v1n(length(v1n)+1:maxnumlen) = 0;
 128   endif
 129   if (length (v2n) < maxnumlen)
 130     v2n(length(v2n)+1:maxnumlen) = 0;
 131   endif
 132
 133   ## Assume that any additional character elements would be 0 if one is
 134   ## longer than the other.
 135   maxcharlen = max ([length(v1c), length(v2c)]);
 136   if (length (v1c) < maxcharlen)
 137     v1c(length(v1c)+1:maxcharlen) = "\0";
 138   endif
 139   if (length (v2c) < maxcharlen)
 140     v2c(length(v2c)+1:maxcharlen) = "\0";
 141   endif
 142
 143   ## Determine the operator.
 144   if any (ismember (operator, "="))
 145     equal_op = true;
 146   else
 147     equal_op = false;
 148   endif
 149   if any (ismember (operator, "~!"))
 150     not_op = true;
 151   else
 152     not_op = false;
 153   endif
 154   if any (ismember (operator, "<"))
 155     lt_op = true;
 156   else
 157     lt_op = false;
 158   endif
 159   if any (ismember (operator, ">"))
 160     gt_op = true;
 161   else
 162     gt_op = false;
 163   endif
 164
 165   ## Make sure that we don't have conflicting operators.
 166   if (gt_op && lt_op)
 167     error ("compare_versions: OPERATOR cannot contain both greater and less than symbols");
 168   elseif ((gt_op || lt_op) && not_op)
 169     error ("compare_versions: OPERATOR cannot contain not and greater than or less than symbols");
 170   elseif (strcmp (operator, "="))
 171     error ("compare_versions: equality OPERATOR is \"==\", not \"=\"");
 172   elseif (! (equal_op || not_op || lt_op || gt_op))
 173     error ("compare_versions: No valid OPERATOR specified");
 174   endif
 175
 176   ## Compare the versions (making sure that they're the same shape)
 177   vcmp = v1n(:) - v2n(:);
 178   vcmp = [vcmp; (v1c - v2c)(:)];
 179   if (lt_op)
 180     ## so that we only need to check for the output being greater than 1
 181     vcmp = -vcmp;
 182   endif
 183   firstdiff = find (vcmp != 0, 1);
 184
 185   if (isempty (firstdiff))
 186     ## They're equal.
 187     out = equal_op;
 188   elseif (lt_op || gt_op)
 189     ## They're correctly less than or greater than.
 190     out = (vcmp(firstdiff) > 0);
 191   else
 192     ## They're not correctly less than or greater than, and they're not equal.
 193     out = false;
 194   endif
 195
 196   ## Reverse the output if not is given.
 197   if (not_op)
 198     out = !out;
 199   endif
 200
 201 endfunction
 202
 203 ## tests
 204 ## test both equality symbols
 205 ## test arbitrarily long equality
 206 %!assert(compare_versions("1.1.0.0.0", "1.1", "=="), true)
 207 %!assert(compare_versions("1", "1.1", "<"), true)
 208 %!assert(compare_versions("1.1", "1.1", "<="), true)
 209 %!assert(compare_versions("1.1", "1.1.1", "<="), true)
 210 %!assert(compare_versions("1.23", "1.24", "=<"), true)
 211 ## test different length numbers
 212 %!assert(compare_versions("23.2000", "23.1", ">"), true)
 213 %!assert(compare_versions("0.0.2", "0.0.1", ">="), true)
 214 %!assert(compare_versions("0.2", "0.0.100", "=>"), true)
 215 %!assert(compare_versions("0.1", "0.2", "!="), true)
 216 %!assert(compare_versions("0.1", "0.2", "~="), true)
 217
 218 ## test alphanumeric strings
 219 %!assert(compare_versions("1a", "1b", "<"), true)
 220 %!assert(compare_versions("a", "1", "<"), true)
 221 %!assert(compare_versions("1a", "1b", ">"), false)
 222 %!assert(compare_versions("a", "1", ">"), false)
 223 %!assert(compare_versions("1.1.0a", "1.1.0b", "=="), false)
 224 %!assert(compare_versions("1.1.0a", "1.1.0b", "!="), true)
 225 %!assert(compare_versions("1.1.0test", "1.1.0b", "=="), false)
 226 %!assert(compare_versions("1.1.0test", "1.1.0test", "=="), true)
 227
 228 ## make sure that it won't just give true output
 229 %!assert(compare_versions("1", "0", "=="), false)
 230 ## test arbitrarily long equality
 231 %!assert(compare_versions("1.1.1.0.0", "1.1", "=="), false)
 232 %!assert(compare_versions("1.1", "1", "<"), false)
 233 %!assert(compare_versions("2", "1.1", "<="), false)
 234 %!assert(compare_versions("1.1.1", "1.1", "<="), false)
 235 %!assert(compare_versions("1.25", "1.24", "=<"), false)
 236 ## test different length numbers
 237 %!assert(compare_versions("23.2", "23.100", ">"), false)
 238 %!assert(compare_versions("0.0.0.2", "0.0.1", ">="), false)
 239 %!assert(compare_versions("0.0.20", "0.10.2", "=>"), false)
 240 %!assert(compare_versions("0.1", "0.1", "!="), false)
 241 %!assert(compare_versions("0.1", "0.1", "~="), false)
 242
 243 %% Test input validation
 244 %!error(compare_versions(0.1, "0.1", "=="))
 245 %!error(compare_versions("0.1", 0.1, "=="))
 246 %!error(compare_versions(["0";".";"1"], "0.1", "=="))
 247 %!error(compare_versions("0.1", ["0";".";"1"], "=="))
 248 %!error(compare_versions("0.1", "0.1", "<>"))
 249 %!error(compare_versions("0.1", "0.1", "!>"))
 250 %!error(compare_versions("0.1", "0.1", "="))
 251 %!error(compare_versions("0.1", "0.1", "aa"))
 252
 253