update encoding and decoding function help info

base64decode.m

@@ -1,38 +1,49 @@
-function output = base64decode(input)
-%BASE64DECODE Decode Base64 string to a byte array.
+function output = base64decode(varargin)
 %
-%    output = base64decode(input)
+% output = base64decode(input)
 %
-% The function takes a Base64 string INPUT and returns a uint8 array
-% OUTPUT. JAVA must be running to use this function. The result is always
-% given as a 1-by-N array, and doesn't retrieve the original dimensions.
-%
-% See also base64encode
+% Decoding a Base64-encoded byte-stream to recover the original data
+% This function depends on JVM in MATLAB or, can optionally use the ZMat 
+% toolbox (https://github.com/fangq/zmat)
 %
 % Copyright (c) 2012, Kota Yamaguchi
 % URL: https://www.mathworks.com/matlabcentral/fileexchange/39526-byte-encoding-utilities
-% License : BSD, see LICENSE_*.txt
+%
+% Modified by: Qianqian Fang (q.fang <at> neu.edu)
+%
+% input:
+%      input: a base64-encoded string
+%
+% output:
+%      output: the decoded binary byte-stream as a uint8 vector
+%
+% examples:
+%      bytes=base64encode('Test JSONLab');
+%      orig=char(base64decode(bytes))
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+%
+% -- this function is part of JSONLab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
 %
 
 if(nargin==0)
     error('you must provide at least 1 input');
 end
 if(exist('zmat','file')==2 || exist('zmat','file')==3)
-    output=zmat(uint8(input),0,'base64');
+    output=zmat(varargin{1},0,'base64');
     return;
+elseif(isoctavemesh)
+    error('You must install the ZMat toolbox (https://github.com/fangq/zmat) to use this function in Octave');
 end
-if(exist('OCTAVE_VERSION','builtin'))
-    len=rem(numel(input),8)
-    if(len)
-       input=[input(:)', repmat(sprintf('\0'),1,(8-len))];
-    end
-    output = base64_decode(input);
-    return;
-end
-error(javachk('jvm'));
-if ischar(input), input = uint8(input); end
 
-output = typecast(org.apache.commons.codec.binary.Base64.decodeBase64(input), 'uint8')';
+error(javachk('jvm'));
 
+if(ischar(varargin{1}))
+    varargin{1}=uint8(varargin{1});
 end
 
+input=typecast(varargin{1}(:)','uint8');
+
+output = typecast(org.apache.commons.codec.binary.Base64.decodeBase64(input), 'uint8')';
+

base64encode.m

@@ -1,33 +1,57 @@
-function output = base64encode(input)
-%BASE64ENCODE Encode a byte array using Base64 codec.
+function varargout = base64encode(varargin)
 %
-%    output = base64encode(input)
+% output = base64encode(input)
 %
-% The function takes a char, int8, or uint8 array INPUT and returns Base64
-% encoded string OUTPUT. JAVA must be running to use this function. Note
-% that encoding doesn't preserve input dimensions.
+% Encoding a binary vector or array using Base64
 %
-% See also base64decode
+% This function depends on JVM in MATLAB or, can optionally use the ZMat 
+% toolbox (https://github.com/fangq/zmat)
 %
 % Copyright (c) 2012, Kota Yamaguchi
 % URL: https://www.mathworks.com/matlabcentral/fileexchange/39526-byte-encoding-utilities
-% License : BSD, see LICENSE_*.txt
+%
+% Modified by: Qianqian Fang (q.fang <at> neu.edu)
+%
+% input:
+%      input: a base64-encoded string
+%
+% output:
+%      output: the decoded binary byte-stream as a uint8 vector
+%
+% examples:
+%      bytes=base64encode('Test JSONLab');
+%      orig=char(base64decode(bytes))
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+%
+% -- this function is part of JSONLab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
 %
 
 if(nargin==0)
     error('you must provide at least 1 input');
 end
+
 if(exist('zmat','file')==2 || exist('zmat','file')==3)
-    output=zmat(uint8(input),1,'base64');
+    [varargout{1:nargout}]=zmat(varargin{1}, 1,'base64',varargin{2:end});
     return;
 end
-if(exist('OCTAVE_VERSION','builtin'))
-    output = base64_encode(uint8(input));
+
+if(ischar(varargin{1}))
+    varargin{1}=uint8(varargin{1});
+end
+
+input=typecast(varargin{1}(:)','uint8');
+
+if(isoctavemesh)
+    varargout{1} = base64_encode(uint8(input));
     return;
 end
-error(javachk('jvm'));
-if ischar(input), input = uint8(input); end
 
-output = char(org.apache.commons.codec.binary.Base64.encodeBase64Chunked(input))';
-output = regexprep(output,'\r','');
+error(javachk('jvm'));
+if ischar(input)
+    input = uint8(input);
 end
+
+varargout{1}  = char(org.apache.commons.codec.binary.Base64.encodeBase64Chunked(input))';
+varargout{1}  = regexprep(varargout{1} ,'\r','');

fast_match_bracket.m

@@ -1,4 +1,48 @@
 function [endpos, maxlevel] = fast_match_bracket(key,pos,startpos,brackets)
+%
+% [endpos, maxlevel] = fast_match_bracket(key,pos,startpos,brackets)
+%
+% A fast function to find the position of a closing bracket token in a string
+%
+% authors:Qianqian Fang (q.fang <at> neu.edu)
+%
+% input:
+%      key: a preprocessed string containing only relevant opening/closing 
+%           bracket characters for accelerating the search.
+%      pos: a 1D integer vector with a length matching the length of key, 
+%           recording the corresponding position of each char. in the original string.
+%      startpos: the index in the original string as the start position to search; the
+%               startpos must be at least 1 greater than the opening bracket position
+%      brackets: (optional), a string of length 2, with the first character
+%               being the opening token and the 2nd being the closing token.
+%               if not given, brackets is set to '[]' to find matching square-brackets;
+%               for example, '{}' looks for a matching closing curly-bracket in
+%               the string key(pos(startpos,:end))
+%
+% output:
+%      endpos: if a matching bracket is found, return its position in the original 
+%              string
+%      maxlevel: return the depth of the enclosed brackets between the searched pair,
+%              includig the searching pair. For example, the matching closing-bracket 
+%              of the 1st square bracket (startpos=2) in  '[[[]],[]]' returns a 
+%              position of 9, with a maximum depth of 3; searching for the closing 
+%              bracket for the 2nd square bracket (startpos=3) returns a position of 
+%              5 and max-depth of 2.
+%
+% example:
+%      str='[[ [1,2], 1], 10, [5,10] ]';
+%      pos=find(str=='[' | str==']')
+%      key=str(pos)
+%      [p1,dep]=fast_match_bracket(key,1:length(key),3)
+%      [p2,dep]=fast_match_bracket(key,pos,2)
+%      [p3,dep]=fast_match_bracket(key,pos,3)
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+%
+% -- this function is part of jsonlab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
+%
+
 if(nargin<4)
     brackets='[]';
 end

gzipdecode.m

@@ -1,40 +1,69 @@
-function output = gzipdecode(input)
-%GZIPDECODE Decompress input bytes using GZIP.
+function varargout = gzipdecode(varargin)
 %
-%    output = gzipdecode(input)
+% output = gzipdecode(input)
+%    or
+% output = gzipdecode(input,info)
 %
-% The function takes a compressed byte array INPUT and returns inflated
-% bytes OUTPUT. The INPUT is a result of GZIPENCODE function. The OUTPUT
-% is always an 1-by-N uint8 array. JAVA must be enabled to use the function.
-%
-% See also gzipencode typecast
+% Decompressing a GZIP-compressed byte-stream to recover the original data
+% This function depends on JVM in MATLAB or, can optionally use the ZMat 
+% toolbox (https://github.com/fangq/zmat)
 %
 % Copyright (c) 2012, Kota Yamaguchi
 % URL: https://www.mathworks.com/matlabcentral/fileexchange/39526-byte-encoding-utilities
-% License : BSD, see LICENSE_*.txt
+%
+% Modified by: Qianqian Fang (q.fang <at> neu.edu)
+%
+% input:
+%      input: a string, int8/uint8 vector or numerical array to store the GZIP-compressed data
+%      info (optional): a struct produced by the zmat/lz4hcencode function during 
+%            compression; if not given, the inputs/outputs will be treated as a
+%            1-D vector
+%
+% output:
+%      output: the decompressed byte stream stored in a uint8 vector; if info is 
+%            given, output will restore the original data's type and dimensions
+%
+% examples:
+%      [bytes, info]=gzipencode(eye(10));
+%      orig=gzipdecode(bytes,info);
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+%
+% -- this function is part of JSONLab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
 %
 
 if(nargin==0)
     error('you must provide at least 1 input');
 end
 if(exist('zmat','file')==2 || exist('zmat','file')==3)
-    output=zmat(uint8(input),0,'gzip');
+    if(nargin>1)
+        [varargout{1:nargout}]=zmat(varargin{1},varargin{2:end});
+    else
+        [varargout{1:nargout}]=zmat(varargin{1},0,'gzip',varargin{2:end});
+    end
     return;
+elseif(isoctavemesh)
+    error('You must install the ZMat toolbox (https://github.com/fangq/zmat) to use this function in Octave');
 end
 error(javachk('jvm'));
-if ischar(input)
-  warning('gzipdecode:inputTypeMismatch', ...
-          'Input is char, but treated as uint8.');
-  input = uint8(input);
-end
-if ~isa(input, 'int8') && ~isa(input, 'uint8')
-    error('Input must be either int8 or uint8.');
+
+if(ischar(varargin{1}))
+    varargin{1}=uint8(varargin{1});
 end
 
+input=typecast(varargin{1}(:)','uint8');
+
 gzip = java.util.zip.GZIPInputStream(java.io.ByteArrayInputStream(input));
 buffer = java.io.ByteArrayOutputStream();
 org.apache.commons.io.IOUtils.copy(gzip, buffer);
 gzip.close();
-output = typecast(buffer.toByteArray(), 'uint8')';
 
-end
+if(nargout>0)
+    varargout{1} = typecast(buffer.toByteArray(), 'uint8')';
+    if(nargin>1 && isstruct(varargin{2}) && isfield(varargin{2},'type'))
+        inputinfo=varargin{2};
+	varargout{1}=typecast(varargout{1},inputinfo.type);
+	varargout{1}=reshape(varargout{1},inputinfo.size);
+    end
+end

gzipencode.m

@@ -1,38 +1,63 @@
-function output = gzipencode(input)
-%GZIPENCODE Compress input bytes with GZIP.
+function varargout = gzipencode(varargin)
 %
-%    output = gzipencode(input)
+% output = gzipencode(input)
+%    or
+% [output, info] = gzipencode(input)
 %
-% The function takes a char, int8, or uint8 array INPUT and returns
-% compressed bytes OUTPUT as a uint8 array. Note that the compression
-% doesn't preserve input dimensions. JAVA must be enabled to use the
-% function.
+% Compress a string or numerical array using the GZIP-compression
 %
-% See also gzipdecode typecast
+% This function depends on JVM in MATLAB or, can optionally use the ZMat 
+% toolbox (https://github.com/fangq/zmat)
 %
 % Copyright (c) 2012, Kota Yamaguchi
 % URL: https://www.mathworks.com/matlabcentral/fileexchange/39526-byte-encoding-utilities
-% License : BSD, see LICENSE_*.txt
 %
+% Modified by: Qianqian Fang (q.fang <at> neu.edu)
+%
+% input:
+%      input: the original data, can be a string, a numerical vector or array
+%
+% output:
+%      output: the decompressed byte stream stored in a uint8 vector; if info is 
+%            given, output will restore the original data's type and dimensions
+%
+% examples:
+%      [bytes, info]=gzipencode(eye(10));
+%      orig=gzipdecode(bytes,info);
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+%
+% -- this function is part of JSONLab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
+%
+
 
 if(nargin==0)
     error('you must provide at least 1 input');
 end
+
 if(exist('zmat','file')==2 || exist('zmat','file')==3)
-    output=zmat(uint8(input),1,'gzip');
+    [varargout{1:nargout}]=zmat(varargin{1},1,'gzip');
     return;
+elseif(isoctavemesh)
+    error('You must install the ZMat toolbox (https://github.com/fangq/zmat) to use this function in Octave');
 end
+
 error(javachk('jvm'));
-if ischar(input), input = uint8(input); end
-if ~isa(input, 'int8') && ~isa(input, 'uint8')
-    error('Input must be either char, int8 or uint8.');
+
+if(ischar(varargin{1}))
+    varargin{1}=uint8(varargin{1});
 end
 
+input=typecast(varargin{1}(:)','uint8');
+
 buffer = java.io.ByteArrayOutputStream();
 gzip = java.util.zip.GZIPOutputStream(buffer);
 gzip.write(input, 0, numel(input));
 gzip.close();
-output = typecast(buffer.toByteArray(), 'uint8')';
 
-end
+varargout{1} = typecast(buffer.toByteArray(), 'uint8')';
 
+if(nargout>1)
+    varargout{2}=struct('type',class(varargin{1}),'size',size(varargin{1}),'method','gzip','status',0);
+end