package flare.data.converters {
	import flare.data.DataSchema;
	import flare.data.DataSet;

	import flash.utils.IDataInput;
	import flash.utils.IDataOutput;

	/**
	 * Interface for data converters that map between an external data file
	 * format and ActionScript objects (e.g., Arrays and Objects).
	 */
	public interface IDataConverter
	{
		/**
		 * Converts data from an external format into ActionScript objects.
		 * @param input the loaded input data
		 * @param schema a data schema describing the structure of the data.
		 *  Schemas are optional in many but not all cases.
		 * @return a DataSet instance containing converted data objects.
		 */
		function read(input:IDataInput, schema:DataSchema=null):DataSet;
		
		/**
		 * Converts data from ActionScript objects into an external format.
		 * @param data the data set to write.
		 * @param output an object to which to write the output. If this value
		 *  is null, a new <code>ByteArray</code> will be created.
		 * @return the converted data. If the <code>output</code> parameter is
		 *  non-null, it is returned. Otherwise the return value will be a
		 *  newly created <code>ByteArray</code>
		 */
		function write(data:DataSet, output:IDataOutput=null):IDataOutput;
		
	} // end of interface IDataConverter
}