update README

git-svn-id: http://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab@411 786e58fb-9377-0410-9ff7-e4ac0ac0635c

README.txt

@@ -3,7 +3,7 @@
 =           An open-source MATLAB/Octave JSON encoder and decoder             =
 ===============================================================================
 
-*Copyright (c) 2011,2012  Qianqian Fang <fangq at nmr.mgh.harvard.edu>
+*Copyright (c) 2011-2013  Qianqian Fang <fangq at nmr.mgh.harvard.edu>
 *License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt
 *Version: 0.9.8 (Optimus - alpha)
 
@@ -36,11 +36,12 @@ format allows to wrap complex binary data in a flexible and extensible
 structure, making it possible to process complex and large dataset 
 without accuracy loss due to text conversions.
 
-We envision that both JSON and its binary version will serve as the
-mainstream data-exchange formats for scientific research in the future, 
-and fulfill part of the roles achieved by other general-purpose 
-file specifications, such as
-[http://www.hdfgroup.org/HDF5/whatishdf5.html HDF5].
+We envision that both JSON and its binary version will serve as part of 
+the mainstream data-exchange formats for scientific research in the future. 
+It will provide the flexibility and generality achieved by other popular 
+general-purpose file specifications, such as
+[http://www.hdfgroup.org/HDF5/whatishdf5.html HDF5], with significantly 
+reduced complexity and enhanced performance.
 
 JSONlab is a free and open-source implementation of a JSON/UBJSON encoder 
 and a decoder in the native MATLAB language. It can be used to convert a MATLAB 
@@ -71,8 +72,8 @@ III.Using JSONlab
 
 JSONlab provides two functions, loadjson.m -- a MATLAB->JSON decoder, 
 and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and 
-two equivallents -- loadubjson and saveubjson for the binary JSON. T
-he detailed help info for the four functions can be found below:
+two equivallent functions -- loadubjson and saveubjson for the binary 
+JSON. The detailed help info for the four functions can be found below:
 
 === loadjson.m ===
 <pre>
@@ -92,7 +93,7 @@ he detailed help info for the four functions can be found below:
           http://www.mathworks.com/matlabcentral/fileexchange/20565
              date: 2008/07/03
  
-  $Id: loadjson.m 371 2012-06-20 12:43:06Z fangq $
+  $Id: loadjson.m 394 2012-12-18 17:58:11Z fangq $
  
   input:
        fname: input file name, if fname contains "{}" or "[]", fname
@@ -120,7 +121,7 @@ he detailed help info for the four functions can be found below:
   author: Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
              created on 2011/09/09
  
-  $Id: savejson.m 371 2012-06-20 12:43:06Z fangq $
+  $Id: savejson.m 394 2012-12-18 17:58:11Z fangq $
  
   input:
        rootname: name of the root-object, if set to '', will use variable name
@@ -180,6 +181,97 @@ he detailed help info for the four functions can be found below:
        savejson('',a,'ArrayIndent',0,'FloatFormat','\t%.5g')
 </pre>
 
+=== loadubjson.m ===
+
+<pre>
+  data=loadubjson(fname,opt)
+     or
+  data=loadubjson(fname,'param1',value1,'param2',value2,...)
+ 
+  parse a JSON (JavaScript Object Notation) file or string
+ 
+  authors:Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
+             date: 2013/08/01
+ 
+  $Id: loadubjson.m 410 2013-08-24 03:33:18Z fangq $
+ 
+  input:
+       fname: input file name, if fname contains "{}" or "[]", fname
+              will be interpreted as a UBJSON string
+       opt: a struct to store parsing options, opt can be replaced by 
+            a list of ('param',value) pairs. The param string is equivallent
+            to a field in opt.
+ 
+  output:
+       dat: a cell array, where {...} blocks are converted into cell arrays,
+            and [...] are converted to arrays
+</pre>
+
+=== saveubjson.m ===
+
+<pre>
+  json=saveubjson(rootname,obj,filename)
+     or
+  json=saveubjson(rootname,obj,opt)
+  json=saveubjson(rootname,obj,'param1',value1,'param2',value2,...)
+ 
+  convert a MATLAB object (cell, struct or array) into a Universal 
+  Binary JSON (UBJSON) binary string
+ 
+  author: Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
+             created on 2013/08/17
+ 
+  $Id: saveubjson.m 410 2013-08-24 03:33:18Z fangq $
+ 
+  input:
+       rootname: name of the root-object, if set to '', will use variable name
+       obj: a MATLAB object (array, cell, cell array, struct, struct array)
+       filename: a string for the file name to save the output JSON data
+       opt: a struct for additional options, use [] if all use default
+         opt can have the following fields (first in [.|.] is the default)
+ 
+         opt.FileName [''|string]: a file name to save the output JSON data
+         opt.ArrayToStruct[0|1]: when set to 0, saveubjson outputs 1D/2D
+                          array in JSON array format; if sets to 1, an
+                          array will be shown as a struct with fields
+                          "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
+                          sparse arrays, the non-zero elements will be
+                          saved to _ArrayData_ field in triplet-format i.e.
+                          (ix,iy,val) and "_ArrayIsSparse_" will be added
+                          with a value of 1; for a complex array, the 
+                          _ArrayData_ array will include two columns 
+                          (4 for sparse) to record the real and imaginary 
+                          parts, and also "_ArrayIsComplex_":1 is added. 
+         opt.ParseLogical [1|0]: if this is set to 1, logical array elem
+                          will use true/false rather than 1/0.
+         opt.NoRowBracket [1|0]: if this is set to 1, arrays with a single
+                          numerical element will be shown without a square
+                          bracket, unless it is the root object; if 0, square
+                          brackets are forced for any numerical arrays.
+         opt.ForceRootName [0|1]: when set to 1 and rootname is empty, saveubjson
+                          will use the name of the passed obj variable as the 
+                          root object name; if obj is an expression and 
+                          does not have a name, 'root' will be used; if this 
+                          is set to 0 and rootname is empty, the root level 
+                          will be merged down to the lower level.
+         opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
+                          for example, if opt.JSON='foo', the JSON data is
+                          wrapped inside a function call as 'foo(...);'
+         opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
+                          back to the string form
+         opt can be replaced by a list of ('param',value) pairs. The param 
+         string is equivallent to a field in opt.
+  output:
+       json: a string in the JSON format (see http://json.org)
+ 
+  examples:
+       a=struct('node',[1  9  10; 2 1 1.2], 'elem',[9 1;1 2;2 3],...
+            'face',[9 01 2; 1 2 3; NaN,Inf,-Inf], 'author','FangQ');
+       saveubjson('mesh',a)
+       saveubjson('',a,'ArrayIndent',0,'FloatFormat','\t%.5g')
+</pre>
+
+
 === examples ===
 
 Under the "examples" folder, you can find several scripts to demonstrate the
@@ -209,8 +301,9 @@ in MATLAB to get consistant results
 # Can not handle classes.
 # saveubjson has not yet supported arbitrary data ([H] in the UBJSON specification)
 # saveubjson now converts a logical array into a uint8 ([U]) array for now
-# an unofficial N-D array count format is used in saveubjson, we are communicating \
-with the UBJSON spec maintainer to investigate the possibility to make this upstream
+# an unofficial N-D array count syntax is implemented in saveubjson. We are \
+actively communicating with the UBJSON spec maintainer to investigate the \
+possibility of making it upstream
 
 -------------------------------------------------------------------------------