shared_source/c_datd/gmp_rats.h

//$Header$
//-------------------------------------------------------------------------------------------------
//This file is part of "David T. Ashley's Shared Source Code", a set of shared components
//integrated into many of David T. Ashley's projects.
//-------------------------------------------------------------------------------------------------
//This source code and any program in which it is compiled/used is provided under the MIT License,
//reproduced below.
//-------------------------------------------------------------------------------------------------
//Permission is hereby granted, free of charge, to any person obtaining a copy of
//this software and associated documentation files(the "Software"), to deal in the
//Software without restriction, including without limitation the rights to use,
//copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the
//Software, and to permit persons to whom the Software is furnished to do so,
//subject to the following conditions :
//
//The above copyright notice and this permission notice shall be included in all
//copies or substantial portions of the Software.
//
//THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
//AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
//SOFTWARE.
//-------------------------------------------------------------------------------------------------
#ifndef GMP_RATS_H_INCLUDED
   #define GMP_RATS_H_INCLUDED

   #ifdef MODULE_GMP_RATS
      #define DECMOD_GMP_RATS
   #else
      #define DECMOD_GMP_RATS extern
   #endif

   //The data structure of a rational number.  Generally,
   //it isn't necessary to keep error flags for the rational
   //number--instead, we can just use the NAN flags of integers,
   //with the convention that if either of the integers
   //has any of the NAN flags set, then the rational number
   //is NAN.  This will be good enough.  So let's agree
   //by convention that a rational number is either
   //valid or NAN--no other possibilities, and nothing more
   //specific.
   //
   //Generally, none of the algorithms in this module make
   //assumptions about whether the inputs are normalized,
   //although they may make assurances about whether the
   //outputs are normalized.  Anything except a denominator
   //of zero is considered acceptable for inputs.
   //
   //For the record, "normalized" according to my definition is:
   //   a)Zero has the unique representation 0/1.
   //   b)Numerator and denominator are coprime.
   //   c)Positive rational numbers have positive
   //     components.
   //   d)Negative rational numbers have numerator
   //     negative and denominator positive.
   typedef struct 
      {
      GMP_INTS_mpz_struct num;
         //The numerator.
      GMP_INTS_mpz_struct den;
         //The denominator.
      } GMP_RATS_mpq_struct;

   /******************************************************************/
   /***  STATUS FUNCTIONS  *******************************************/
   /******************************************************************/
   //Functions in this category provide information about rational
   //numbers.
   //
   //Returns TRUE if the rational number is NAN, which means
   //either integer component with flags set or a denominator
   //of zero.
   DECMOD_GMP_RATS
   int GMP_RATS_mpq_is_nan(const GMP_RATS_mpq_struct *rn);

   /******************************************************************/
   /***  INITIALIZATION, CLEARING, AND SETTING FUNCTIONS  ************/
   /******************************************************************/
   //Allocates an space for integers, initializes a rational number
   //to 0/1.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_init(GMP_RATS_mpq_struct *arg);
   //Destroys a rational number.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_clear(GMP_RATS_mpq_struct *arg);
   //Sets a rational number to the two integer components
   //specified.  It is not required that these components
   //be normalized.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_set_si(GMP_RATS_mpq_struct *arg,
                            int num,
                            int den);
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_copy(      GMP_RATS_mpq_struct *dst,
                          const GMP_RATS_mpq_struct *src);

   //Swaps two rational numbers.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_swap( GMP_RATS_mpq_struct *a,
                           GMP_RATS_mpq_struct *b);

   //Swaps numerator and denominator.  Simple swap, no normalization.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_swap_components(GMP_RATS_mpq_struct *arg);

   //Sets a rational number to be a slash-separated integer.  The 
   //two components (before and after the slash) may be integers
   //in scientific notation, integers with commas, etc.  The
   //*failure flag is set TRUE if the number could not be parsed.
   //The rational number involved must already have been initialized,
   //so space is allocated.  The number is not normalized in any
   //way--the integer components of the rational number are
   //exactly the slash-separated components.  It is possible to
   //use this function to simply parse to see if one can form
   //a rational number, but this is an expensive process because
   //of the allocation and then destruction involved.  It seems
   //possible in the future that one would introduce a function
   //which won't take the scientifc notation, and so the word 
   //"complex" is included below.  Any subsequent function which
   //won't accept the scientific notation should be called "simple"
   //instead.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_set_complex_slash_sepd_rat_num(const char *s,
                                                    int *failure,
                                                    GMP_RATS_mpq_struct *rn);

   //Attempts to parse and set a rational number expressed in
   //pure scientific notation.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_set_sci_not_rat_num(const char *s,
                                         int *failure,
                                         GMP_RATS_mpq_struct *rn);

   //Attempts to parse and set a rational number which might be in
   //any accepted format.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_set_all_format_rat_num(const char *s,
                                            int *failure,
                                            GMP_RATS_mpq_struct *rn);

   /******************************************************************/
   /***  NORMALIZATION FUNCTIONS  ************************************/
   /******************************************************************/
   //Normalizes only the signs.  Non-negative number expressed as +/+,
   //negative numbers expressed only as -/+.
   DECMOD_GMP_RATS
   void
   GMP_RATS_mpq_normalize_sign(GMP_RATS_mpq_struct *rn);

   
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_normalize(GMP_RATS_mpq_struct *rn);

   /******************************************************************/
   /***  ARITHMETIC FUNCTIONS  ***************************************/
   /******************************************************************/
   //Adds two rational numbers to produce normalized result.
   //Args may be same as result.  Any NAN inputs result in NAN
   //output:  NAN flagged using 1/0 as return value.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_add(      GMP_RATS_mpq_struct *result,
                         const GMP_RATS_mpq_struct *arg1,
                         const GMP_RATS_mpq_struct *arg2);
   //Subtract, follows the same rules as add.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_sub(      GMP_RATS_mpq_struct *result,
                         const GMP_RATS_mpq_struct *arg1,
                         const GMP_RATS_mpq_struct *arg2);
   //Multiply.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_mul(      GMP_RATS_mpq_struct *result,
                         const GMP_RATS_mpq_struct *arg1,
                         const GMP_RATS_mpq_struct *arg2);
   //Divide.
   DECMOD_GMP_RATS
   void GMP_RATS_mpq_div(      GMP_RATS_mpq_struct *result,
                         const GMP_RATS_mpq_struct *arg1,
                         const GMP_RATS_mpq_struct *arg2);

   /******************************************************************/
   /***  COMPARISON FUNCTIONS  ***************************************/
   /******************************************************************/
   //Compares two rational numbers.  The return value is neg if
   //arg1 < arg2, 0 if arg1 == arg2, and 1 if arg1 > arg2.  The
   //rational numbers passed are not required to be normalized,
   //either with respect to sign of components or with respect 
   //to coprimality.  There are some errors which may occur, either
   //because a denominator is zero or because intermediate results
   //overflow as the comparison is made.  For that reason, the
   //"failure" pointer is allowed.  If it is NULL, no failure information
   //is returned and any failure condition results in a return value
   //of zero and the failure can't be detected by the caller.
   //If the pointer is not NULL, the failure boolean will be
   //filled in so the caller can detect it.
   int GMP_RATS_mpq_cmp(const  GMP_RATS_mpq_struct *arg1,
                        const  GMP_RATS_mpq_struct *arg2,
                        int   *failure);

   /******************************************************************/
   /***  VERSION CONTROL REPORTING FUNCTIONS  ************************/
   /******************************************************************/
   DECMOD_GMP_RATS const char *GMP_RATS_cvcinfo(void);
   DECMOD_GMP_RATS const char *GMP_RATS_hvcinfo(void);
   #define GMP_RATS_H_VERSION ("$Header$")
#endif

//End of gmp_rats.h.
1	dashley	71	//$Header$
2			//-------------------------------------------------------------------------------------------------
3			//This file is part of "David T. Ashley's Shared Source Code", a set of shared components
4			//integrated into many of David T. Ashley's projects.
5			//-------------------------------------------------------------------------------------------------
6			//This source code and any program in which it is compiled/used is provided under the MIT License,
7			//reproduced below.
8			//-------------------------------------------------------------------------------------------------
9			//Permission is hereby granted, free of charge, to any person obtaining a copy of
10			//this software and associated documentation files(the "Software"), to deal in the
11			//Software without restriction, including without limitation the rights to use,
12			//copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the
13			//Software, and to permit persons to whom the Software is furnished to do so,
14			//subject to the following conditions :
15			//
16			//The above copyright notice and this permission notice shall be included in all
17			//copies or substantial portions of the Software.
18			//
19			//THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20			//IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21			//FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
22			//AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23			//LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24			//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25			//SOFTWARE.
26			//-------------------------------------------------------------------------------------------------
27			#ifndef GMP_RATS_H_INCLUDED
28			#define GMP_RATS_H_INCLUDED
29
30			#ifdef MODULE_GMP_RATS
31			#define DECMOD_GMP_RATS
32			#else
33			#define DECMOD_GMP_RATS extern
34			#endif
35
36			//The data structure of a rational number. Generally,
37			//it isn't necessary to keep error flags for the rational
38			//number--instead, we can just use the NAN flags of integers,
39			//with the convention that if either of the integers
40			//has any of the NAN flags set, then the rational number
41			//is NAN. This will be good enough. So let's agree
42			//by convention that a rational number is either
43			//valid or NAN--no other possibilities, and nothing more
44			//specific.
45			//
46			//Generally, none of the algorithms in this module make
47			//assumptions about whether the inputs are normalized,
48			//although they may make assurances about whether the
49			//outputs are normalized. Anything except a denominator
50			//of zero is considered acceptable for inputs.
51			//
52			//For the record, "normalized" according to my definition is:
53			// a)Zero has the unique representation 0/1.
54			// b)Numerator and denominator are coprime.
55			// c)Positive rational numbers have positive
56			// components.
57			// d)Negative rational numbers have numerator
58			// negative and denominator positive.
59			typedef struct
60			{
61			GMP_INTS_mpz_struct num;
62			//The numerator.
63			GMP_INTS_mpz_struct den;
64			//The denominator.
65			} GMP_RATS_mpq_struct;
66
67			/******************************************************************/
68			/* STATUS FUNCTIONS *****************************************/
69			/******************************************************************/
70			//Functions in this category provide information about rational
71			//numbers.
72			//
73			//Returns TRUE if the rational number is NAN, which means
74			//either integer component with flags set or a denominator
75			//of zero.
76			DECMOD_GMP_RATS
77			int GMP_RATS_mpq_is_nan(const GMP_RATS_mpq_struct *rn);
78
79			/******************************************************************/
80			/* INITIALIZATION, CLEARING, AND SETTING FUNCTIONS **********/
81			/******************************************************************/
82			//Allocates an space for integers, initializes a rational number
83			//to 0/1.
84			DECMOD_GMP_RATS
85			void GMP_RATS_mpq_init(GMP_RATS_mpq_struct *arg);
86			//Destroys a rational number.
87			DECMOD_GMP_RATS
88			void GMP_RATS_mpq_clear(GMP_RATS_mpq_struct *arg);
89			//Sets a rational number to the two integer components
90			//specified. It is not required that these components
91			//be normalized.
92			DECMOD_GMP_RATS
93			void GMP_RATS_mpq_set_si(GMP_RATS_mpq_struct *arg,
94			int num,
95			int den);
96			DECMOD_GMP_RATS
97			void GMP_RATS_mpq_copy( GMP_RATS_mpq_struct *dst,
98			const GMP_RATS_mpq_struct *src);
99
100			//Swaps two rational numbers.
101			DECMOD_GMP_RATS
102			void GMP_RATS_mpq_swap( GMP_RATS_mpq_struct *a,
103			GMP_RATS_mpq_struct *b);
104
105			//Swaps numerator and denominator. Simple swap, no normalization.
106			DECMOD_GMP_RATS
107			void GMP_RATS_mpq_swap_components(GMP_RATS_mpq_struct *arg);
108
109			//Sets a rational number to be a slash-separated integer. The
110			//two components (before and after the slash) may be integers
111			//in scientific notation, integers with commas, etc. The
112			//*failure flag is set TRUE if the number could not be parsed.
113			//The rational number involved must already have been initialized,
114			//so space is allocated. The number is not normalized in any
115			//way--the integer components of the rational number are
116			//exactly the slash-separated components. It is possible to
117			//use this function to simply parse to see if one can form
118			//a rational number, but this is an expensive process because
119			//of the allocation and then destruction involved. It seems
120			//possible in the future that one would introduce a function
121			//which won't take the scientifc notation, and so the word
122			//"complex" is included below. Any subsequent function which
123			//won't accept the scientific notation should be called "simple"
124			//instead.
125			DECMOD_GMP_RATS
126			void GMP_RATS_mpq_set_complex_slash_sepd_rat_num(const char *s,
127			int *failure,
128			GMP_RATS_mpq_struct *rn);
129
130			//Attempts to parse and set a rational number expressed in
131			//pure scientific notation.
132			DECMOD_GMP_RATS
133			void GMP_RATS_mpq_set_sci_not_rat_num(const char *s,
134			int *failure,
135			GMP_RATS_mpq_struct *rn);
136
137			//Attempts to parse and set a rational number which might be in
138			//any accepted format.
139			DECMOD_GMP_RATS
140			void GMP_RATS_mpq_set_all_format_rat_num(const char *s,
141			int *failure,
142			GMP_RATS_mpq_struct *rn);
143
144			/******************************************************************/
145			/* NORMALIZATION FUNCTIONS **********************************/
146			/******************************************************************/
147			//Normalizes only the signs. Non-negative number expressed as +/+,
148			//negative numbers expressed only as -/+.
149			DECMOD_GMP_RATS
150			void
151			GMP_RATS_mpq_normalize_sign(GMP_RATS_mpq_struct *rn);
152
153
154			DECMOD_GMP_RATS
155			void GMP_RATS_mpq_normalize(GMP_RATS_mpq_struct *rn);
156
157			/******************************************************************/
158			/* ARITHMETIC FUNCTIONS *************************************/
159			/******************************************************************/
160			//Adds two rational numbers to produce normalized result.
161			//Args may be same as result. Any NAN inputs result in NAN
162			//output: NAN flagged using 1/0 as return value.
163			DECMOD_GMP_RATS
164			void GMP_RATS_mpq_add( GMP_RATS_mpq_struct *result,
165			const GMP_RATS_mpq_struct *arg1,
166			const GMP_RATS_mpq_struct *arg2);
167			//Subtract, follows the same rules as add.
168			DECMOD_GMP_RATS
169			void GMP_RATS_mpq_sub( GMP_RATS_mpq_struct *result,
170			const GMP_RATS_mpq_struct *arg1,
171			const GMP_RATS_mpq_struct *arg2);
172			//Multiply.
173			DECMOD_GMP_RATS
174			void GMP_RATS_mpq_mul( GMP_RATS_mpq_struct *result,
175			const GMP_RATS_mpq_struct *arg1,
176			const GMP_RATS_mpq_struct *arg2);
177			//Divide.
178			DECMOD_GMP_RATS
179			void GMP_RATS_mpq_div( GMP_RATS_mpq_struct *result,
180			const GMP_RATS_mpq_struct *arg1,
181			const GMP_RATS_mpq_struct *arg2);
182
183			/******************************************************************/
184			/* COMPARISON FUNCTIONS *************************************/
185			/******************************************************************/
186			//Compares two rational numbers. The return value is neg if
187			//arg1 < arg2, 0 if arg1 == arg2, and 1 if arg1 > arg2. The
188			//rational numbers passed are not required to be normalized,
189			//either with respect to sign of components or with respect
190			//to coprimality. There are some errors which may occur, either
191			//because a denominator is zero or because intermediate results
192			//overflow as the comparison is made. For that reason, the
193			//"failure" pointer is allowed. If it is NULL, no failure information
194			//is returned and any failure condition results in a return value
195			//of zero and the failure can't be detected by the caller.
196			//If the pointer is not NULL, the failure boolean will be
197			//filled in so the caller can detect it.
198			int GMP_RATS_mpq_cmp(const GMP_RATS_mpq_struct *arg1,
199			const GMP_RATS_mpq_struct *arg2,
200			int *failure);
201
202			/******************************************************************/
203			/* VERSION CONTROL REPORTING FUNCTIONS **********************/
204			/******************************************************************/
205			DECMOD_GMP_RATS const char *GMP_RATS_cvcinfo(void);
206			DECMOD_GMP_RATS const char *GMP_RATS_hvcinfo(void);
207			#define GMP_RATS_H_VERSION ("$Header$")
208			#endif
209
210			//End of gmp_rats.h.