Objects in EMBOSS are defined (Appendix C, C Coding Standards) and documented (Appendix D, Code Documentation Standards) in a standard way.

A typical definition, for the public AJAX string object, is shown below and includes the standard documentation:

/* @data AjPStr ***************************************************************
**
** Ajax string object.
**
** Holds a null terminated character string with additional data.
** The length is known and held internally.
** The reserved memory size is known and held internally.
** The reference count is known and held internally.
** New pointers can refer to the same string without needing
** to duplicate the character data.
**
** If a string has multiple references it cannot be changed. Any
** instance to be changed is first copied to a new string. This
** means that any function which can change the character data must
** pass a pointer to the string so that the string can be moved.
**
** A default null string is provided. New strings are by default
** implemented as pointers to this with increased reference counters.
**
** AjPStr is implemented as a pointer to a C data structure.
**
** @alias AjPPStr
** @alias AjSStr
** @alias AjOStr
** @iterator AjIStr
**
** @attr Res [ajuint] Reserved bytes (usable for expanding in place)
** @attr Len [ajuint] Length of current string, excluding NULL at end
** @attr Ptr [char*] The string, as a NULL-terminated C string.
** @attr Use [ajuint] Use count: 1 for single reference, more if several
**                   pointers share the same string.
**                   Must drop to 0 before deleting. Modifying means making
**                   a new string if not 1.
** @attr Padding [ajint] Padding to alignment boundary
** @@
******************************************************************************/

typedef struct AjSStr 
{
    ajuint  Res;
    ajuint  Len;
    char   *Ptr;
    ajuint  Use;
    ajint   Padding;
}   AjOStr;
#define AjPStr AjOStr*
typedef AjPStr* AjPPStr;

You can see that the declaration defines:

The object pointer (AjPStr) is the datatype you'll commonly use and for this reason an AjPStr is often referred to as a "string object", rather than the more cumbersome "string object pointer". Of course an AjPStr points to a string object in memory.

The datatype naming conventions are supposed to make the names intuitive:

Many other basic datatypes are available. For example the basic file object AjPFile is defined in the AJAX file ajfile.h whereas the input (AjPSeq) and output (AjPSeqout) sequence objects are in ajseqdata.h and ajseqwrite.h respectively. Different naming conventions apply for public NUCLEUS objects and for private objects including those listed in the application code (see Appendix C, C Coding Standards).

You should never access the elements of an object directly, that is what the library functions are for. Objects should always be accessed by calling the appropriate AJAX or NUCLEUS functions. These are fully described by structured comments in the source files in a similar way to the objects themselves (see Appendix D, Code Documentation Standards). Functions are organised by the datatype they act upon and, for easier navigation, into sections of related functionality. This documentation is available online and via SRS (see Section 1.3, “Developer Documentation”).

The function sections are supposed to help you to quickly find the functions you need. Functions in the same section tend to have similar names and return types, and similar number, order and type of parameters. As functions in the same section are all used in a similar way then programming with the libraries is reasonably intuitive.

Most of the sections are unique to a given library file however there are some common sections. For example, many of the library files have an "element retrieval" section for functions which return a data element of an object and an "element set" section for functions that set the value of a data element directly. Most of the complex biological datatypes have "input" and "output" sections for reading or writing the data to file in a formatted way. This includes input (AjPSeq) and output (AjPSeqout) sequence objects, application reports (AjPReport) and sequence alignments (AjPAlign). The common sections are described in more detail in Appendix D, Code Documentation Standards.

The main thing to be aware of when using objects with functions is that object pointers (for example an AjPStr) are always used: a data structure proper is never passed to or returned from a function for reasons of efficiency. Furthermore, for consistency, all functions in EMBOSS should obey the following rules:

Consider, for example, two functions in the AJAX string library ajstr.c: ajStrMatchS and ajStrAssignS. ajStrMatchS compares two strings and returns ajTrue if they are the same whereas ajStrAssignS copies one string value into another.

You can deduce that ajStrMatchS merely reads two string values and therefore object pointers will be passed. In contrast, ajStrAssignS must change the value of the destination string, possibly allocating a new string (as a failsafe in case a NULL pointer is passed to it) or reallocating a new bigger string in cases where a destination string is passed but is too small to hold the new value. In either case the string value will be changed and possibly the pointer too, therefore the address of the object pointer for the destination string is required.

The prototypes show that this is indeed the case:

AjBool ajStrMatchS(const AjPStr str, const AjPStr str2);
AjBool ajStrAssignS(AjPStr* Pstr, const AjPStr str);

The two strings (str and str2) passed to ajStrMatchS are only read from, therefore the parameters are object pointers (AjPStr). The source string (str) of ajStrAssignS is also read-only, whereas the destination string (Pstr) is modified and therefore the address must be passed (AjPStr* Pstr).