<commit_before>#ifndef CSOUND_H
#define CSOUND_H
/*! \mainpage
 *
 * Csound is a unit generator-based, user-programmable,
 * user-extensible computer music system.  It was originally written
 * by <NAME> at the Massachusetts Institute of Technology in
 * 1984 as the first C language version of this type of
 * software. Since then Csound has received numerous contributions
 * from researchers, programmers, and musicians from around the world.
 *
 * \section section_api_outline Outline of the API
 *
 * \subsection section_api_apilist The Csound Application Programming Interfaces
 *
 * The Csound Application Programming Interface (API) reference is contained
 * herein.
 * The Csound API actually consists of several APIs:
 *
 * - The basic Csound C API. Include csound.h and link with libcsound.a.
 *   This also includes the Cscore API (see below).
 * - The basic Csound C++ API. Include csound.hpp and link with libcsound.a.
 * - The interfaces API, includes a number of auxiliary C++ classes, which
 *   add functionality and support the wrapping of the Csound API by various
 *   languages (e.g. Python, Java, Lua).
 *
 * \b Purposes
 *
 * The purposes of the Csound API are as follows:
 *
 * \li Declare a stable public application programming interface (API)
 *     for Csound in csound.h. This is the only header file that needs
 *     to be \#included by users of the Csound API.
 *
 * \li Hide the internal implementation details of Csound from users of
 *     the API, so that development of Csound can proceed without affecting
 *     code that uses the API.
 *
 * \b Users
 *
 * Users of the Csound API fall into two main categories: hosts, and plugins.
 *
 * \li Hosts are applications that use Csound as a software synthesis engine.
 *     Hosts can link with the Csound API either statically or dynamically.
 *
 * \li Plugins are shared libraries loaded by Csound at run time to implement
 *     external opcodes and/or drivers for audio or MIDI input and output.
 *     Plugin opcodes need only include the csdl.h header which brings all
 *     necessary functions and data structures.
 *
 * \section section_api_c_example An Example Using the Csound API
 *
 * The Csound command--line program is itself built using the Csound API.
 * Its code reads as follows:
 *
 * \code
 * #include "csound.h"
 *
 * int main(int argc, char **argv)
 * {
 *   // Create Csound.
 *   void *csound = csoundCreate(0);
 *   // One complete compile/perform cycle.
 *   int result = csoundCompile(csound, argc, argv);
 *   if(!result) {
 *     while(csoundPerformKsmps(csound) == 0){}
 *     csoundCleanup(csound);
 *   }
 *   // Destroy Csound.
 *   csoundDestroy(csound);
 *   return result;
 * }
 * \endcode
 *
 *
 * Everything that can be done using C as in the above examples can also be done
 * in a similar manner in Python or any of the other Csound API languages.
 *
 * \file csound.h
 *
 * \brief Declares the public Csound application programming interface (API).
 * \author <NAME>, <NAME>, <NAME>, <NAME>,
 *         <NAME>, <NAME>, <NAME> and <NAME>.
 *
 * Hosts using the Csound API must \#include <csound.h>, and link with the
 * Csound API library. Plugin libraries should \#include <csdl.h> to get
 * access to the API function pointers in the CSOUND structure, and do not
 * need to link with the Csound API library.
 * Only one of csound.h and csdl.h may be included by a compilation unit.
 *
 * Hosts must first create an instance of Csound using the \c csoundCreate
 * API function. When hosts are finished using Csound, they must destroy the
 * instance of csound using the \c csoundDestroy API function.
 * Most of the other Csound API functions take the Csound instance as their
 * first argument.
 * Hosts can only call the standalone API functions declared in csound.h.<commit_msg>Updated csound.h API example documentation.<commit_after>#ifndef CSOUND_H
#define CSOUND_H
/*! \mainpage
 *
 * Csound is a unit generator-based, user-programmable,
 * user-extensible computer music system.  It was originally written
 * by <NAME> at the Massachusetts Institute of Technology in
 * 1984 as the first C language version of this type of
 * software. Since then Csound has received numerous contributions
 * from researchers, programmers, and musicians from around the world.
 *
 * \section section_api_outline Outline of the API
 *
 * \subsection section_api_apilist The Csound Application Programming Interfaces
 *
 * The Csound Application Programming Interface (API) reference is contained
 * herein.
 * The Csound API actually consists of several APIs:
 *
 * - The basic Csound C API. Include csound.h and link with libcsound.a.
 *   This also includes the Cscore API (see below).
 * - The basic Csound C++ API. Include csound.hpp and link with libcsound.a.
 * - The interfaces API, includes a number of auxiliary C++ classes, which
 *   add functionality and support the wrapping of the Csound API by various
 *   languages (e.g. Python, Java, Lua).
 *
 * \b Purposes
 *
 * The purposes of the Csound API are as follows:
 *
 * \li Declare a stable public application programming interface (API)
 *     for Csound in csound.h. This is the only header file that needs
 *     to be \#included by users of the Csound API.
 *
 * \li Hide the internal implementation details of Csound from users of
 *     the API, so that development of Csound can proceed without affecting
 *     code that uses the API.
 *
 * \b Users
 *
 * Users of the Csound API fall into two main categories: hosts, and plugins.
 *
 * \li Hosts are applications that use Csound as a software synthesis engine.
 *     Hosts can link with the Csound API either statically or dynamically.
 *
 * \li Plugins are shared libraries loaded by Csound at run time to implement
 *     external opcodes and/or drivers for audio or MIDI input and output.
 *     Plugin opcodes need only include the csdl.h header which brings all
 *     necessary functions and data structures. Plugins can be written in C++
 *     using either `include/plugin.h` (using the Csound allocator, for opcodes
 *     that do not involve standard C++ library collections) or
 *     `include/OpcodeBase.hpp` (using the standard ++ allocator, for opcodes
 *     that do use standard C++ library collections).
 *
 * \section section_api_c_example Examples Using the Csound API
 *
 * The Csound command--line program is itself built using the Csound API.
 * Its code reads (in outline) as follows:
 *
 * \code
 * #include "csound.h"
 *
 * int main(int argc, char **argv)
 * {
 *   void *csound = csoundCreate(0);
 *   int result = csoundCompile(csound, argc, argv);
 *   if(!result) {
 *     while(csoundPerformKsmps(csound) == 0){}
 *     csoundCleanup(csound);
 *   }
 *   csoundDestroy(csound);
 *   return result;
 * }
 * \endcode
 *
 * The Csound API defines two modes of operation for hosts. In the first mode,
 * a regular Csound score is performed and then performance automatically
 * ends. This could be called "score mode." In the second mode, Csound
 * continues to perform indefinitely until performance is explicitly ended by
 * calling csoundStop. This could be called "live mode." Which mode is used is
 * determined by when csoundStart is called. In more detail:
 *
 * \subsection s1 Score Mode
 *
 * \li The <CsOptions> section of the CSD file is processed.
 *
 * \li csoundStart must be called after csoundCompileCsd or csoundReadScore.
 *
 * \li The score is pre-processed, and events are dispatched as regular score
 *     events. "f", "s", and "e" events are permitted in the score.
 *
 * \code
 * #include "csound.h"
 *
 * const char *csd_text = "blah blah blah";
 *
 * int main(int argc, char **argv)
 * {
 *   void *csound = csoundCreate(0);
 *   int result = csoundCompileCsdText(csound, csd_text);
 *   result = csoundStart(csound);
 *   while (1) {
 *      result = csoundPerformKsmps(csound);
 *      if (result != 0) {
 *         break;
 *      }
 *   }
 *   result = csoundCleanup(csound);
 *   csoundReset(csound);
 *   csoundDestroy(csound);
 *   return result;
 * }
 * \endcode
 *
 * \subsection s2 Live Mode
 *
 * \li The <CsOptions> section of the CSD file not processed; options must
 *     be set by calling csoundSetOption.
 *
 * \li csoundStart must be called before csoundCompileCsd or csoundReadScore.
 *
 * \li The score is not pre-processed, and events are dispatched as real-time
 *     events. "f", "s", and "e" events are not permitted.
 *
 * \code
 * #include "csound.h"
 *
 * const char *orc_text = "blah blah blah";
 * const char *sco_text = "blah blah blah";
 *
 * int main(int argc, char **argv)
 * {
 *   void *csound = csoundCreate(0);
 *   int result = csoundSetOption(csound, "-d");
 *   result = csoundSetOption(csound, "-odac");
 *   result = csoundStart(csound);
 *   result = csoundCompileOrc(csound, orc_text);
 *   result = csoundReadScore(csound, sco_text);
 *   while (1) {
 *      result = csoundPerformKsmps(csound);
 *      if (result != 0) {
 *         break;
 *      }
 *   }
 *   result = csoundCleanup(csound);
 *   csoundReset(csound);
 *   csoundDestroy(csound);
 *   return result;
 * }
 * \endcode

 *
 * Everything that can be done using C as in the above examples can also be done
 * in a similar manner in Python or any of the other Csound API languages.
 *
 * \file csound.h
 *
 * \brief Declares the public Csound application programming interface (API).
 * \author <NAME>, <NAME>, <NAME>, <NAME>,
 *         <NAME>, <NAME>, <NAME> and <NAME>.
 *
 * Hosts using the Csound API must \#include <csound.h>, and link with the
 * Csound API library. Plugin libraries should \#include <csdl.h> to get
 * access to the API function pointers in the CSOUND structure, and do not
 * need to link with the Csound API library.
 * Only one of csound.h and csdl.h may be included by a compilation unit.
 *
 * Hosts must first create an instance of Csound using the \c csoundCreate
 * API function. When hosts are finished using Csound, they must destroy the
 * instance of csound using the \c csoundDestroy API function.
 * Most of the other Csound API functions take the Csound instance as their
 * first argument.
 * Hosts can only call the standalone API functions declared in csound.h.
{'fraction_non_alphanumeric': 0.08463949843260188, 'fraction_numerical': 0.001959247648902821, 'mean_word_length': 3.342407486176095, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, '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': '3550698', 'n_tokens_mistral': 2988, 'n_tokens_neox': 2897, 'n_words': 1316}