<commit_before>\chapter{Programmer interface}
\label{ap:lang}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {C language}

The argument types given in this manual (PLFLT and PLINT) are typedefs for
the actual argument type.  A PLINT is actually a type {\tt long} and should
not be changed.  A PLFLT can be either a {\tt float} or {\tt double}; this
choice is made when the package is installed and on a Unix system (for
example) may result in a PLPLOT library named {\tt libplplotf.a} in single
precision and {\tt libplplotd.a} in double precision.

These and other constants used by PLPLOT are defined in the main header file
{\tt plplot.h}, which must be included by the user program.  This file also
contains all of the function prototypes, machine dependent defines, and
redefinition of the C-language bindings that conflict with the Fortran names
(more on this later).  {\tt plplot.h} obtains its values for PLFLT, PLINT,
and PLARGS (a macro for conditionally generating prototype argument lists)
from FLOAT (typedef), INT (typedef), and PROTO (macro), respectively.
The latter are defined in the file
{\tt chdr.h}.  The user is encouraged to use FLOAT, INT, and PROTO in
his/her own code, and modify {\tt chdr.h} according to taste.  It is not
actually necessary to declare variables as FLOAT and INT except when they
are pointers, as automatic conversion to the right type will otherwise occur
(if using a Standard C compiler; else K\&R style automatic promotion will
occur).  The only code in {\tt plplot.h} that directly depends on these
settings is as follows:
\begin{verbatim}
#include "chdr.h"

/* change from chdr.h conventions to plplot ones */

typedef FLOAT PLFLT;
typedef INT   PLINT;
#define PLARGS(a) PROTO(a)
\end{verbatim}

PLPLOT is capable of being compiled with Standard C (ANSI) mode on or off.
This is toggled via the macro PLSTDC, and set automatically if \_\_STDC\_\_
is defined.  If PLSTDC is defined, all functions are prototyped as allowed
under Standard C, and arguments passed exactly as specified in the
prototype.  If PLSTDC is not defined, however, function prototypes are
turned off and K\&R automatic argument promotion will occur, e.g.  {\tt
float $\rar$ double, int $\rar$ long}.  There is no middle ground!  A PLPLOT
library built with PLSTDC defined will not work (in general) with a program
built with PLSTDC undefined, and vice versa.  It is possible in principle to
build a library that will work under both Standard C and K\&R compilers
simultaneously (i.e.  by duplicating the K\&R promotion with the Standard C
prototype), but this seems to violate the spirit of the C standard and can
be confusing.  Eventually we will drop support for non-standard C compilers 
but for now have adopted this compromise.

In summary, PLPLOT will work using either a Standard or non-standard C
compiler, provided that you :
\begin{enumerate}
\item Include the PLPLOT main header file {\tt plplot.h}.
\item Make sure all pointer arguments are of the correct type
(the compiler should warn you if you forget, so don't worry, be happy).
\item Do not link a code compiled with PLSTDC defined to a PLPLOT library
compiled with PLSTDC undefined, or vice versa.
\item Use prototypes whenever possible to reduce type errors.
\end{enumerate}

Note that some Standard C compilers will give warnings when converting a
constant function argument to whatever is required by the prototype.  These
warnings can be ignored.

The one additional complicating factor concerns the use of stub routines to
interface with Fortran (see the following section for more explanation).  On
some systems, the Fortran \& C namespaces are set up to clobber each other.
More reasonable (from our viewpoint) is to agree on a standard map between
namespaces, such as the appending of an underscore to Fortran routine names
as is common on many Unix-like systems.  The only case where the shared
Fortran/C namespaces do any good is when passing a pointer to a like data
type, which represents only a small fraction of the cases that need to
be handled (which includes constant values passed on the stack, strings, and
two-dimensional arrays).

There are several ways to deal with this situation, but the least messy from
a user's perspective is to redefine those PLPLOT C function names which
conflict with the Fortran-interface stub routines.  The actual function
names are the same as those described in this document, but with a ``c\_''
prepended.  These macro definitions appear in the {\tt plplot.h} header file
and are otherwise harmless.  Therefore you can (and should) forget that most
of the names are being redefined to avoid the conflict and simply adhere to
the bindings as described in this manual.  Codes written under old versions
of PLPLOT (previous to 4.0) will require a recompile, however.

It is possible to compile the PLPLOT library so that the affected functions
retain their documented names, by specifying {\tt -DNOBRAINDEAD} on the
compile line.  Some reasons for doing this might be:  (a) you don't want to
include {\tt plplot.h} into your program for whatever reason, or (b) you are
debugging PLPLOT and wish to specify the documented names to the debugger.
In fact this procedure will work fine under SUNOS, with no Fortran/C
namespace collision.  But on other systems a special compiler switch may be
required to get it to work similarly, which is an extra burden on the user
and best avoided.

For more information on calling PLPLOT from C, please see the 14 example C
programs ({\tt x01c.c} through {\tt x14c.c}) distributed with PLPLOT.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Fortran language}

As discussed in the preceding section, PLPLOT's integer representation is a
PLINT and its floating point representation is a PLFLT.  To the
Fortran user, this most commonly translates to a type {\tt integer} and
type {\tt real}, respectively.  This is somewhat system dependent (and up to
the installer of the package) so you should check the release notes to be
sure, or just try it and see what happens.

Because the PLPLOT kernel is written in C, standard C syntax is used in the
description of each PLPLOT function.  Thus to understand this manual it is
helpful to know a little about C, but fortunately the translation is very
easy and can be summarized here.  As an example, the routine {\tt plline}
call from C would look like:
%
\begin{verbatim}
    plline(n,x,y);}
\end{verbatim}
%
while from Fortran would look like:
%
\begin{verbatim}
	call plline(n,x,y)
\end{verbatim}
%
typically with {\tt n} declared as type {\tt integer} and {\tt x}, {\tt y}
declared as type {\tt real} (arrays in this case).  Each C language type
used in the text translates roughly as follows:
\begin{tabbing}
01234567\=
	890123456789012345678901\=\kill
%
	\>PLFLT			\>real\\
	\>PLINT			\>integer\\
	\>char *		\>character\\
	\>PLFLT *		\>real or real array\\
	\>PLFLT **		\>real array\\
	\>{\tt"}string{\tt"}	\>{\tt'}string{\tt'}\\
	\>array[0]		\>array(1)\\
\end{tabbing}
In C there are two ways to pass a variable --- by value (the default) or by
reference (pointer), whereas only the latter is used by Fortran.
Therefore when you see references in the text to {\em either} an ordinary
argument or a pointer argument (e.g.  {\tt *data}), you simply use an
ordinary Fortran variable or array name.

The PLPLOT library comes with a set of Fortran interface routines that
allow the exact same call syntax (usually) regardless of whether calling
from C or Fortran.  These ``stub'' routines handle transforming the data
from the normal Fortran representation to that typically used in C.  This
includes:<commit_msg>Added note about >8 chars in Fortran names.<commit_after>\chapter{Programmer interface}
\label{ap:lang}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {C language}

The argument types given in this manual (PLFLT and PLINT) are typedefs for
the actual argument type.  A PLINT is actually a type {\tt long} and should
not be changed.  A PLFLT can be either a {\tt float} or {\tt double}; this
choice is made when the package is installed and on a Unix system (for
example) may result in a PLPLOT library named {\tt libplplotf.a} in single
precision and {\tt libplplotd.a} in double precision.

These and other constants used by PLPLOT are defined in the main header file
{\tt plplot.h}, which must be included by the user program.  This file also
contains all of the function prototypes, machine dependent defines, and
redefinition of the C-language bindings that conflict with the Fortran names
(more on this later).  {\tt plplot.h} obtains its values for PLFLT, PLINT,
and PLARGS (a macro for conditionally generating prototype argument lists)
from FLOAT (typedef), INT (typedef), and PROTO (macro), respectively.
The latter are defined in the file
{\tt chdr.h}.  The user is encouraged to use FLOAT, INT, and PROTO in
his/her own code, and modify {\tt chdr.h} according to taste.  It is not
actually necessary to declare variables as FLOAT and INT except when they
are pointers, as automatic conversion to the right type will otherwise occur
(if using a Standard C compiler; else K\&R style automatic promotion will
occur).  The only code in {\tt plplot.h} that directly depends on these
settings is as follows:
\begin{verbatim}
#include "chdr.h"

/* change from chdr.h conventions to plplot ones */

typedef FLOAT PLFLT;
typedef INT   PLINT;
#define PLARGS(a) PROTO(a)
\end{verbatim}

PLPLOT is capable of being compiled with Standard C (ANSI) mode on or off.
This is toggled via the macro PLSTDC, and set automatically if \_\_STDC\_\_
is defined.  If PLSTDC is defined, all functions are prototyped as allowed
under Standard C, and arguments passed exactly as specified in the
prototype.  If PLSTDC is not defined, however, function prototypes are
turned off and K\&R automatic argument promotion will occur, e.g.  {\tt
float $\rar$ double, int $\rar$ long}.  There is no middle ground!  A PLPLOT
library built with PLSTDC defined will not work (in general) with a program
built with PLSTDC undefined, and vice versa.  It is possible in principle to
build a library that will work under both Standard C and K\&R compilers
simultaneously (i.e.  by duplicating the K\&R promotion with the Standard C
prototype), but this seems to violate the spirit of the C standard and can
be confusing.  Eventually we will drop support for non-standard C compilers 
but for now have adopted this compromise.

In summary, PLPLOT will work using either a Standard or non-standard C
compiler, provided that you :
\begin{enumerate}
\item Include the PLPLOT main header file {\tt plplot.h}.
\item Make sure all pointer arguments are of the correct type
(the compiler should warn you if you forget, so don't worry, be happy).
\item Do not link a code compiled with PLSTDC defined to a PLPLOT library
compiled with PLSTDC undefined, or vice versa.
\item Use prototypes whenever possible to reduce type errors.
\end{enumerate}

Note that some Standard C compilers will give warnings when converting a
constant function argument to whatever is required by the prototype.  These
warnings can be ignored.

The one additional complicating factor concerns the use of stub routines to
interface with Fortran (see the following section for more explanation).  On
some systems, the Fortran \& C namespaces are set up to clobber each other.
More reasonable (from our viewpoint) is to agree on a standard map between
namespaces, such as the appending of an underscore to Fortran routine names
as is common on many Unix-like systems.  The only case where the shared
Fortran/C namespaces do any good is when passing a pointer to a like data
type, which represents only a small fraction of the cases that need to
be handled (which includes constant values passed on the stack, strings, and
two-dimensional arrays).

There are several ways to deal with this situation, but the least messy from
a user's perspective is to redefine those PLPLOT C function names which
conflict with the Fortran-interface stub routines.  The actual function
names are the same as those described in this document, but with a ``c\_''
prepended.  These macro definitions appear in the {\tt plplot.h} header file
and are otherwise harmless.  Therefore you can (and should) forget that most
of the names are being redefined to avoid the conflict and simply adhere to
the bindings as described in this manual.  Codes written under old versions
of PLPLOT (previous to 4.0) will require a recompile, however.

It is possible to compile the PLPLOT library so that the affected functions
retain their documented names, by specifying {\tt -DNOBRAINDEAD} on the
compile line.  Some reasons for doing this might be:  (a) you don't want to
include {\tt plplot.h} into your program for whatever reason, or (b) you are
debugging PLPLOT and wish to specify the documented names to the debugger.
In fact this procedure will work fine under SUNOS, with no Fortran/C
namespace collision.  But on other systems a special compiler switch may be
required to get it to work similarly, which is an extra burden on the user
and best avoided.

For more information on calling PLPLOT from C, please see the 14 example C
programs ({\tt x01c.c} through {\tt x14c.c}) distributed with PLPLOT.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Fortran language}

As discussed in the preceding section, PLPLOT's integer representation is a
PLINT and its floating point representation is a PLFLT.  To the
Fortran user, this most commonly translates to a type {\tt integer} and
type {\tt real}, respectively.  This is somewhat system dependent (and up to
the installer of the package) so you should check the release notes to be
sure, or just try it and see what happens.

Because the PLPLOT kernel is written in C, standard C syntax is used in the
description of each PLPLOT function.  Thus to understand this manual it is
helpful to know a little about C, but fortunately the translation is very
easy and can be summarized here.  As an example, the routine {\tt plline}
call from C would look like:
%
\begin{verbatim}
    plline(n,x,y);}
\end{verbatim}
%
while from Fortran would look like:
%
\begin{verbatim}
	call plline(n,x,y)
\end{verbatim}
%
typically with {\tt n} declared as type {\tt integer} and {\tt x}, {\tt y}
declared as type {\tt real} (arrays in this case).  Each C language type
used in the text translates roughly as follows:
\begin{tabbing}
01234567\=
	890123456789012345678901\=\kill
%
	\>PLFLT			\>real\\
	\>PLINT			\>integer\\
	\>char *		\>character\\
	\>PLFLT *		\>real or real array\\
	\>PLFLT **		\>real array\\
	\>{\tt"}string{\tt"}	\>{\tt'}string{\tt'}\\
	\>array[0]		\>array(1)\\
\end{tabbing}
In C there are two ways to pass a variable --- by value (the default) or by
reference (pointer), whereas only the latter is used by Fortran.
Therefore when you see references in the text to {\em either} an ordinary
argument or a pointer argument (e.g.  {\tt *data}), you simply use an
ordinary Fortran variable or array name.

The PLPLOT library comes with a set of Fortran interface routines that
allow the exact same call syntax (usually) regardless of whether calling
from C or Fortran.  In some cases, this means the subroutine name {\em
exceeds 8 characters in length}.  Nearly every Fortran compiler on sale
today allows subroutine names longer than 8 characters, so this should not
be a problem (although if it ever is, in principle a truncated name could
be defined for that platform).

These ``stub'' routines handle transforming the data
from the normal Fortran representation to that typically used in C.  This
includes:
{'fraction_non_alphanumeric': 0.07819243462807819, 'fraction_numerical': 0.005521706016755522, 'mean_word_length': 4.300033636057854, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 32, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2037818', 'n_tokens_mistral': 4390, 'n_tokens_neox': 4156, 'n_words': 2443}