00001 //# Conversion.h: A class with general conversion definitions 00002 //# Copyright (C) 1996,1999,2001,2002,2003 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_CONVERSION_H 00029 #define CASA_CONVERSION_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/string.h> // needed for memcpy 00034 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 // <summary> 00039 // A class with general conversion definitions 00040 // </summary> 00041 00042 // <use visibility=export> 00043 00044 // <reviewed reviewer="Friso Olnon" date="1996/11/06" tests="tConversion" demos=""> 00045 // </reviewed> 00046 00047 // <synopsis> 00048 // This class contains the general definitions for the Conversion classes. 00049 // <ul> 00050 // <li> 00051 // It defines the signature for the functions converting from input 00052 // to output format (e.g. from local to canonical format). There is 00053 // a version where the number of values is given and a version where 00054 // the number of bytes is given. The latter is there to be able to use 00055 // memcpy as a conversion function (which will often be the case). 00056 // Note that the signatures only differ in return value. 00057 // <li> 00058 // It defines functions to convert Bools to bits and vice-versa. 00059 // These are used elsewhere to store Bools as space efficient as possible. 00060 // Note that these functions are machine independent (they work on little 00061 // and big endian machines). 00062 // <li> 00063 // It defines a private version of memcpy for compilers having a 00064 // different signature for memcpy (e.g. ObjectCenter and DEC-Alpha). 00065 // </ul> 00066 // Static functions in the classes 00067 // <linkto class=CanonicalConversion>CanonicalConversion</linkto>, 00068 // <linkto class=VAXConversion>VAXConversion</linkto>, and 00069 // <linkto class=IBMConversion>IBMConversion</linkto> convert data 00070 // from/to canonical, VAX, and IBM/360 format, resp.. 00071 // <br>Classes derived from 00072 // <linkto class=DataConversion>DataConversion</linkto> 00073 // provide the same functionality in a polymorphic way. 00074 // </synopsis> 00075 00076 // <motivation> 00077 // This provides a common place for definitions used elsewhere. 00078 // It also provides a uniform interface to memcpy. 00079 // </motivation> 00080 00081 //# <todo asof="$DATE$"> 00082 //# </todo> 00083 00084 00085 class Conversion 00086 { 00087 public: 00088 // Define the signature of a function converting <src>nvalues</src> 00089 // values from internal to external format or vice-versa. 00090 // These functions are used in the <linkto class=TypeIO>IO framework 00091 // </linkto>, but are also used in the table system. 00092 // Examples of such conversions are: 00093 // <br>- local <-> canonical (when storing in canonical format) 00094 // <br>- local <-> local (when storing in local format) 00095 // <br>- binary <-> ASCII 00096 // <br>It returns the number of bytes in <em>external</em> format. 00097 // (For example the ToLocal/FromLocal functions in class 00098 // <linkto class=CanonicalConversion>CanonicalConversion</linkto> 00099 // return the number of bytes in canonical format). 00100 typedef size_t ValueFunction (void* to, const void* from, 00101 size_t nvalues); 00102 00103 // Define the signature of a function converting from one 00104 // format to another providing the number of bytes. 00105 // It returns the <src>to</src> pointer (similar to memcpy). 00106 // (For example the byteTo/FromLocalXXX functions in class 00107 // <linkto class=CanonicalConversion>CanonicalConversion</linkto>. 00108 typedef void* ByteFunction (void* to, const void* from, 00109 size_t nbytes); 00110 00111 // Convert a stream of Bools to output format (as bits). 00112 // The variable <src>startBit</src> (0-relative) indicates 00113 // where to start in the <src>to</src> buffer. 00114 // <group> 00115 static size_t boolToBit (void* to, const void* from, 00116 size_t nvalues); 00117 static void boolToBit (void* to, const void* from, 00118 size_t startBit, 00119 size_t nvalues); 00120 // </group> 00121 00122 // Convert a stream of Bools to output format (as bits). 00123 // The variable <src>startBit</src> (0-relative) indicates 00124 // where to start in the <src>from</src> buffer. 00125 // <group> 00126 static size_t bitToBool (void* to, const void* from, 00127 size_t nvalues); 00128 static void bitToBool (void* to, const void* from, 00129 size_t startBit, 00130 size_t nvalues); 00131 // </group> 00132 00133 // Copy a value using memcpy. 00134 // It differs from memcpy in the return value. 00135 // <note> This version has the <src>ValueFunction</src> signature, 00136 // but it expects as input the number of bytes. 00137 // </note> 00138 static size_t valueCopy (void* to, const void* from, 00139 size_t nbytes); 00140 00141 // Get a pointer to the memcpy function. 00142 static ByteFunction* getmemcpy(); 00143 00144 private: 00145 // Copy bits to Bool in an unoptimized way needed when 'to' is not 00146 // aligned properly. 00147 static size_t bitToBool_ (void* to, const void* from, 00148 size_t nvalues); 00149 }; 00150 00151 00152 inline Conversion::ByteFunction* Conversion::getmemcpy() 00153 { 00154 return memcpy; 00155 } 00156 00157 00158 00159 } //# NAMESPACE CASACORE - END 00160 00161 #endif