(recode.info)Outer level

---

Next: Request level Prev: Library Up: Library

---

Enter node , (file) or (file)node

Outer level functions
=====================

   The outer level functions mainly prepare the whole recoding library
for use, or do actions which are unrelated to specific recodings.  Here
is an example of a program which does not really make anything useful.

     #include <stdbool.h>
     #include <recode.h>
     
     const char *program_name;
     
     int
     main (int argc, char *const *argv)
     {
       program_name = argv[0];
       RECODE_OUTER outer = recode_new_outer (true);
     
       recode_delete_outer (outer);
       exit (0);
     }

   The header file `<recode.h>' declares an opaque `RECODE_OUTER'
structure, which the programmer should use for allocating a variable in
his program (let's assume the programmer is a male, here, no prejudice
intended).  This `outer' variable is given as a first argument to all
outer level functions.

   The `<recode.h>' header file uses the Boolean type setup by the
system header file `<stdbool.h>'.  But this header file is still fairly
new in C standards, and likely does not exist everywhere.  If you
system does not offer this system header file yet, the proper
compilation of the `<recode.h>' file could be guaranteed through the
replacement of the inclusion line by:

     typedef enum {false = 0, true = 1} bool;

   People wanting wider portability, or Autoconf lovers, might arrange
their `configure.in' for being able to write something more general,
like:

     #if STDC_HEADERS
     # include <stdlib.h>
     #endif
     
     /* Some systems do not define EXIT_*, even with STDC_HEADERS.  */
     #ifndef EXIT_SUCCESS
     # define EXIT_SUCCESS 0
     #endif
     #ifndef EXIT_FAILURE
     # define EXIT_FAILURE 1
     #endif
     /* The following test is to work around the gross typo in systems like Sony
        NEWS-OS Release 4.0C, whereby EXIT_FAILURE is defined to 0, not 1.  */
     #if !EXIT_FAILURE
     # undef EXIT_FAILURE
     # define EXIT_FAILURE 1
     #endif
     
     #if HAVE_STDBOOL_H
     # include <stdbool.h>
     #else
     typedef enum {false = 0, true = 1} bool;
     #endif
     
     #include <recode.h>
     
     const char *program_name;
     
     int
     main (int argc, char *const *argv)
     {
       program_name = argv[0];
       RECODE_OUTER outer = recode_new_outer (true);
     
       recode_term_outer (outer);
       exit (EXIT_SUCCESS);
     }

but we will not insist on such details in the examples to come.

   * Initialisation functions

          RECODE_OUTER recode_new_outer (AUTO_ABORT);
          bool recode_delete_outer (OUTER);

     The recoding library absolutely needs to be initialised before
     being used, and `recode_new_outer' has to be called once, first.
     Besides the OUTER it is meant to initialise, the function accepts
     a Boolean argument whether or not the library should automatically
     issue diagnostics on standard and abort the whole program on
     errors.  When AUTO_ABORT is `true', the library later conveniently
     issues diagnostics itself, and aborts the calling program on
     errors.  This is merely a convenience, because if this parameter
     was `false', the calling program should always take care of
     checking the return value of all other calls to the recoding
     library functions, and when any error is detected, issue a
     diagnostic and abort processing itself.

     Regardless of the setting of AUTO_ABORT, all recoding library
     functions return a success status.  Most functions are geared for
     returning `false' for an error, and `true' if everything went fine.
     Functions returning structures or strings return `NULL' instead of
     the result, when the result cannot be produced.  If AUTO_ABORT is
     selected, functions either return `true', or do not return at all.

     As in the example above, `recode_new_outer' is called only once in
     most cases.  Calling `recode_new_outer' implies some overhead, so
     calling it more than once should preferably be avoided.

     The termination function `recode_delete_outer' reclaims the memory
     allocated by `recode_new_outer' for a given OUTER variable.
     Calling `recode_delete_outer' prior to program termination is more
     aesthetic then useful, as all memory resources are automatically
     reclaimed when the program ends.  You may spare this terminating
     call if you prefer.

   * The `program_name' declaration

     As we just explained, the user may set the `recode' library so
     that, in case of problems error, it issues the diagnostic itself
     and aborts the whole processing.  This capability may be quite
     convenient.  When this feature is used, the aborting routine
     includes the name of the running program in the diagnostic.  On
     the other hand, when this feature is not used, the library merely
     return error codes, giving the library user fuller control over
     all this.  This behaviour is more like what usual libraries do:
     they return codes and never abort.  However, I would rather not
     force library users to necessarily check all return codes
     themselves, by leaving no other choice.  In most simple
     applications, letting the library diagnose and abort is much
     easier, and quite welcome.  This is precisely because both
     possibilities exist that the `program_name' variable is needed: it
     may be used by the library _when_ the user sets it to diagnose
     itself.