diff --git a/README.txt b/README.txt
index be20d7104942e1819f49f53e7eea6f09b50d903a..83616b81a6e3df9b18f85ce0917a1c43b2fb5727 100644
--- a/README.txt
+++ b/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
-------------------------------------------------------------------------------