Chapter 17. The Common API for PLplot
Prev | Part IV. Reference | Next

## Chapter 17. The Common API for PLplot

The purpose of this chapter is to document the common API for every PLplot function that should be available across all PLplot language bindings. Therefore, this chapter excludes obsolete/deprecated API functions which are listed in Chapter 21, Obsolete/Deprecated API for PLplot and also excludes API specialized for each language binding that is documented in Chapter 18, The Specialized C/C++ API for PLplot and subsequent chapters.

The common API constitutes the most important part of the PLplot API that programmers need to know.

For the C case, these common API routines have prototypes defined in `plplot.h` using PLplot C types for arguments. The names for these types have been chosen to be self-documenting. So `PLINT` refers to the PLplot integer type, and `PLFLT` refers to the PLplot floating-point type. If the name has a `_VECTOR` or `_MATRIX` suffix the type corresponds to the one-dimensional or two-dimensional array argument type native to the language being supported by PLplot. If the name does not have either of those two suffixes or if it has a suffix of `_SCALAR`, then it refers to a scalar quantity. Finally, note that most of our common API arguments are input only and are guaranteed not to be changed by the PLplot routine. However, in some cases the argument is used for output quantities which are changed by the PLplot routine, and in this case we include `_NC` (standing for "non-constant") in the argument type name.

We document our common API below for the C case, but it should be fairly straightforward to infer the corresponding API for any of our supported languages from these results because of the self-documenting names we use for the PLplot C types for arguments. Of course, the best way to learn how to use our common API for the language of your choice is to look at our standard set of examples. For additional language documentation you should consult the various chapters in Part III, “ Supported computer languages ” as well.

What follows is a list of all common API functions of the latest PLplot version. The following information is provided for each function:

1. The function name and a brief description.

2. The function as it would be called from C.

3. A complete description of the function.

4. A description of each argument that the function takes.

5. The redacted argument form of the function as well as any language specific variations that might occur on the general calling scheme described in the following paragraph.

6. A list of PLplot examples that demonstrate how to use the function.

The general calling scheme for the other languages supported by PLplot is as follows, using the function `plline` as an example.

- C: `plline( n, x, y );`

- Ada/standard: `Draw_Curve( x, y );`

- Ada/traditional: `plline( x, y );`

- C++: `pls->line(n, x, y );`

- D: `plline( x, y );`

- Fortran: `plline( x, y )`

- Java: `pls.line( x, y );`

- Lua: `pl.line( x, y )`

- OCaml: `plline x y;`

- Octave: `plline( x', y' );`

- Python: `plline( x, y )`

- Tcl/Tk: `$w cmd plline x y`

Note that in all our supported languages other than C and C++, the argument ``n`` (which specifies the length of the input vectors ``x`` and ``y``) is not used in the argument list since that information is already available from the vector (and matrix in the general case) arguments themselves. This is what we refer to above as the “redacted argument form” of the function.

Prev | Up | Next
Chapter 16. Bibliography | Home | `pl_setcontlabelformat`: Set format of numerical label for contours