lib_c/c_cmode/fcmiof.h

//$Header$
//{f84eaac3-3de8-489b-afed-5d7f83e92748}
//-------------------------------------------------------------------------------------------------
//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 FCMIOF_H_INCLUDED
   #define FCMIOF_H_INCLUDED

   #ifdef MODULE_FCMIOF
      #define DECMOD_FCMIOF
   #else
      #define DECMOD_FCMIOF extern
   #endif


   //********************************************************************************
   // FCMIOF_stream_repchar():
   //--------------------------------------------------------------------------------
   // DESCRIPTION
   //   Emits a character to a stream a specified number of times.
   //
   // INPUTS
   //    s       
   //       The stream to which to output the characters.  NULL and otherwise
   //       invalid pointers are not allowed.
   //    n       
   //       The number of times to emit the character.  0 is a permitted value
   //       and results in no output.
   //
   // RETURN VALUE
   //   The return value from the final fprintf() function call, unless any
   //   fprintf() function call returns a negative value (an error code), in which
   //   case this function returns immediately with that error code.
   //********************************************************************************
   DECMOD_FCMIOF int FCMIOF_stream_repchar(FILE *s, char c, size_t n);


   //********************************************************************************
   // FCMIOF_repchar():
   //--------------------------------------------------------------------------------
   // DESCRIPTION
   //   Emits a character to stdout a specified number of times.
   //
   // INPUTS
   //    n       
   //       The number of times to emit the character.  0 is a permitted value
   //       and results in no output.
   //
   // RETURN VALUE
   //   The return value from the final printf() function call, unless any
   //   printf() function call returns a negative value (an error code), in which
   //   case this function returns immediately with that error code.
   //********************************************************************************
   DECMOD_FCMIOF int FCMIOF_repchar(char c, size_t n);


   //********************************************************************************
   // FCMIOF_stream_hline():
   //--------------------------------------------------------------------------------
   // DESCRIPTION
   //   Emits a horizontal line of the hyphens of the specified length to the
   //   specified stream.
   //
   // INPUTS
   //    s       
   //       The stream to which to output the characters.  NULL and otherwise
   //       invalid pointers are not allowed.
   //    line_len
   //       The number of characters to use for the line.  0 is an allowed value
   //       and results in 
   //
   // RETURN VALUE
   //   The return value from the final fprintf() function call, unless any
   //   fprintf() function call returns a negative value (an error code), in which
   //   case this function returns immediately with that error code.
   //********************************************************************************
   DECMOD_FCMIOF int FCMIOF_stream_hline(FILE *s, size_t line_len);


   //********************************************************************************
   // FCMIOF_hline():
   //--------------------------------------------------------------------------------
   // DESCRIPTION
   //   Emits a horizontal line of the hyphens of the specified length to stdout.
   //
   // INPUTS
   //    line_len
   //       The number of characters to use for the line.  0 is an allowed value
   //       and results in 
   //
   // RETURN VALUE
   //   The return value from the final printf() function call, unless any
   //   printf() function call returns a negative value (an error code), in which
   //   case this function returns immediately with that error code.
   //********************************************************************************
   DECMOD_FCMIOF int FCMIOF_hline(size_t line_len);


   //********************************************************************************
   // FCMIOF_stream_bannerheading():
   //--------------------------------------------------------------------------------
   // DESCRIPTION
   //   Prints a banner heading bracketed by asterisks to the specified stream.
   //   This function is useful for separating different sections of output.
   //
   // INPUTS
   //    f       
   //       The stream to which to output the characters.  NULL and otherwise
   //       invalid pointers are not allowed.
   //    s
   //       The text to use for the banner.  This string may be of 0 length, but
   //       the pointer "s" may not be NULL or otherwise invalid.
   //    line_len
   //       The number of characters to use for each line.  0 is an allowed value
   //       and results in lines with no output.
   //    n_extra_lines
   //       The number of lines of asterisks to use before and after the banner.
   //       0 is an allowed value and results in no lines of asterisks.
   //
   // RETURN VALUE
   //   The return value from the final printf() function call, unless any
   //   printf() function call returns a negative value (an error code), in which
   //   case this function returns immediately with that error code.
   //********************************************************************************
   DECMOD_FCMIOF int FCMIOF_stream_bannerheading(FILE *f,
                                                 char *s, 
                                                 size_t line_len,
                                                 size_t n_extra_lines);

   /****************************************************************************/
   /* FCMIOF_bannerheading():                                                  */
   /*--------------------------------------------------------------------------*/ 
   /* DESCRIPTION                                                              */
   /*   Prints a banner heading bracketed by astreisks to the standard output. */
   /*   This function is useful for separating different sections of output.   */
   /****************************************************************************/
   DECMOD_FCMIOF int FCMIOF_bannerheading(char *s, size_t line_len, size_t n_extra_lines);


   DECMOD_FCMIOF void FCMIOF_time_stream(FILE *s, time_t ltime);


   /* Two functions below return version control information for .C and
   ** .H files.
   */
   DECMOD_FCMIOF const char *FCMIOF_cvcinfo(void);
   DECMOD_FCMIOF const char *FCMIOF_hvcinfo(void);
   #define FCMIOF_H_VERSION ("$Header$")

#endif

//End of fcmiof.h.
1	dashley	71	//$Header$
2	dashley	244	//{f84eaac3-3de8-489b-afed-5d7f83e92748}
3	dashley	71	//-------------------------------------------------------------------------------------------------
4			//This file is part of "David T. Ashley's Shared Source Code", a set of shared components
5			//integrated into many of David T. Ashley's projects.
6			//-------------------------------------------------------------------------------------------------
7			//This source code and any program in which it is compiled/used is provided under the MIT License,
8			//reproduced below.
9			//-------------------------------------------------------------------------------------------------
10			//Permission is hereby granted, free of charge, to any person obtaining a copy of
11			//this software and associated documentation files(the "Software"), to deal in the
12			//Software without restriction, including without limitation the rights to use,
13			//copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the
14			//Software, and to permit persons to whom the Software is furnished to do so,
15			//subject to the following conditions :
16			//
17			//The above copyright notice and this permission notice shall be included in all
18			//copies or substantial portions of the Software.
19			//
20			//THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21			//IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22			//FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
23			//AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24			//LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25			//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26			//SOFTWARE.
27			//-------------------------------------------------------------------------------------------------
28			#ifndef FCMIOF_H_INCLUDED
29			#define FCMIOF_H_INCLUDED
30
31			#ifdef MODULE_FCMIOF
32			#define DECMOD_FCMIOF
33			#else
34			#define DECMOD_FCMIOF extern
35			#endif
36
37
38	dashley	244	//********************************************************************************
39			// FCMIOF_stream_repchar():
40			//--------------------------------------------------------------------------------
41			// DESCRIPTION
42			// Emits a character to a stream a specified number of times.
43			//
44			// INPUTS
45			// s
46			// The stream to which to output the characters. NULL and otherwise
47			// invalid pointers are not allowed.
48			// n
49			// The number of times to emit the character. 0 is a permitted value
50			// and results in no output.
51			//
52			// RETURN VALUE
53			// The return value from the final fprintf() function call, unless any
54			// fprintf() function call returns a negative value (an error code), in which
55			// case this function returns immediately with that error code.
56			//********************************************************************************
57			DECMOD_FCMIOF int FCMIOF_stream_repchar(FILE *s, char c, size_t n);
58	dashley	71
59
60	dashley	244	//********************************************************************************
61			// FCMIOF_repchar():
62			//--------------------------------------------------------------------------------
63			// DESCRIPTION
64			// Emits a character to stdout a specified number of times.
65			//
66			// INPUTS
67			// n
68			// The number of times to emit the character. 0 is a permitted value
69			// and results in no output.
70			//
71			// RETURN VALUE
72			// The return value from the final printf() function call, unless any
73			// printf() function call returns a negative value (an error code), in which
74			// case this function returns immediately with that error code.
75			//********************************************************************************
76			DECMOD_FCMIOF int FCMIOF_repchar(char c, size_t n);
77	dashley	71
78
79	dashley	244	//********************************************************************************
80			// FCMIOF_stream_hline():
81			//--------------------------------------------------------------------------------
82			// DESCRIPTION
83			// Emits a horizontal line of the hyphens of the specified length to the
84			// specified stream.
85			//
86			// INPUTS
87			// s
88			// The stream to which to output the characters. NULL and otherwise
89			// invalid pointers are not allowed.
90			// line_len
91			// The number of characters to use for the line. 0 is an allowed value
92			// and results in
93			//
94			// RETURN VALUE
95			// The return value from the final fprintf() function call, unless any
96			// fprintf() function call returns a negative value (an error code), in which
97			// case this function returns immediately with that error code.
98			//********************************************************************************
99			DECMOD_FCMIOF int FCMIOF_stream_hline(FILE *s, size_t line_len);
100	dashley	71
101
102	dashley	244	//********************************************************************************
103			// FCMIOF_hline():
104			//--------------------------------------------------------------------------------
105			// DESCRIPTION
106			// Emits a horizontal line of the hyphens of the specified length to stdout.
107			//
108			// INPUTS
109			// line_len
110			// The number of characters to use for the line. 0 is an allowed value
111			// and results in
112			//
113			// RETURN VALUE
114			// The return value from the final printf() function call, unless any
115			// printf() function call returns a negative value (an error code), in which
116			// case this function returns immediately with that error code.
117			//********************************************************************************
118			DECMOD_FCMIOF int FCMIOF_hline(size_t line_len);
119	dashley	71
120
121	dashley	244	//********************************************************************************
122			// FCMIOF_stream_bannerheading():
123			//--------------------------------------------------------------------------------
124			// DESCRIPTION
125			// Prints a banner heading bracketed by asterisks to the specified stream.
126			// This function is useful for separating different sections of output.
127			//
128			// INPUTS
129			// f
130			// The stream to which to output the characters. NULL and otherwise
131			// invalid pointers are not allowed.
132			// s
133			// The text to use for the banner. This string may be of 0 length, but
134			// the pointer "s" may not be NULL or otherwise invalid.
135			// line_len
136			// The number of characters to use for each line. 0 is an allowed value
137			// and results in lines with no output.
138			// n_extra_lines
139			// The number of lines of asterisks to use before and after the banner.
140			// 0 is an allowed value and results in no lines of asterisks.
141			//
142			// RETURN VALUE
143			// The return value from the final printf() function call, unless any
144			// printf() function call returns a negative value (an error code), in which
145			// case this function returns immediately with that error code.
146			//********************************************************************************
147			DECMOD_FCMIOF int FCMIOF_stream_bannerheading(FILE *f,
148			char *s,
149			size_t line_len,
150			size_t n_extra_lines);
151
152	dashley	71	/****************************************************************************/
153			/* FCMIOF_bannerheading(): */
154			/--------------------------------------------------------------------------/
155			/* DESCRIPTION */
156			/* Prints a banner heading bracketed by astreisks to the standard output. */
157			/* This function is useful for separating different sections of output. */
158			/****************************************************************************/
159	dashley	244	DECMOD_FCMIOF int FCMIOF_bannerheading(char *s, size_t line_len, size_t n_extra_lines);
160	dashley	71
161
162			DECMOD_FCMIOF void FCMIOF_time_stream(FILE *s, time_t ltime);
163
164
165			/* Two functions below return version control information for .C and
166			** .H files.
167			*/
168			DECMOD_FCMIOF const char *FCMIOF_cvcinfo(void);
169			DECMOD_FCMIOF const char *FCMIOF_hvcinfo(void);
170			#define FCMIOF_H_VERSION ("$Header$")
171
172			#endif
173
174			//End of fcmiof.h.