# Triceps &Cpp; API Reference

## &Cpp; API Introduction

Fundamentally, the &Cpp; and Perl APIs are shaped similarly. So I won't be making a version of all the examples in &Cpp;. Please read the Perl-based documentation first to understand the spirit and usage of Triceps. The &Cpp;-based documentation is more of the reference type and concentrates on the low-level specifics and differences from Perl necessitated by this specifics.

In many cases just reading the descriptions of the methods in the

    .h

files should be enough to understand the details and be able to use the API. However in some cases the class hierarchies differ, with the Perl API covering the complexities exposed in the &Cpp; API.

Writing directly in &Cpp; is significantly harder than in Perl, so I highly recommend sticking with the Perl API unless you have a good reason to do otherwise. Even when the performance is important, it's usually enough to write a few critical elements in &Cpp; and then bind them together in Perl. (If you wonder about Java, and why I didn't use it instead, the answer is that Java successfully combines the drawbacks of both and adds some of its own).

The &Cpp; Triceps API is much more sensitive to the errors. The Perl API checks all the arguments for consistency, it's principle is that the interpreter must never crash. The &Cpp; API is geared towards the efficiency of execution. It checks for errors when constructing the major elements but then does almost no checks at run time. The expectation is that the caller knows what he is doing. If the caller sends bad data, mislays the pointers etc., the program will crash. The idea here is that most likely the &Cpp; API will be used from another layer: either an interpreted one (like Perl) or a compiled one (like a possible future custom language). Either way that layer is responsible for detecting the user errors at either interpretation or compile time. By the time the data gets to the &Cpp; code, it's already checked and there is no need to check it again. Of course, if you write the programs manually in &Cpp;, that checking is upon you.

The more high-level features are currently available only in Perl. For example, there are no joins in the &Cpp; API. If you want to do the joins in &Cpp;, you have to code your own. This will change over time, as these features will solidify and move to a &Cpp; implementation to become more efficient and available through all the APIs. But it's much easier to experiment with the initial implementations in Perl.

The &Cpp; code is located in the

    cpp/

subdirectory, and all the further descriptions refer to the subdirectories under it.
C++

## The const-ness in &Cpp;

I've been using the

    const

keyword for two purposes:

- To let the compiler optimize a little better the methods that do not change the state of the objects.
- To mark the fragments of the read-only object internal state returned by the methods. This is much more efficient than making copies of them.

So if you get a

    const vector<> &

returned from a method, this is a gentle reminder that you should not be modifying this vector. Of course, nothing can stop a determined programmer from doing a type cast and modifying it anyway, but be aware that such inconsistent modifications will likely cause the program to crash in the future. And if the vector contains references to other objects, these objects usually should not be modified either, even they might not be marked with const.

However all this

    const

stuff is not all rainbows and unicorns but also produces a sizable amount of suffering. One consequence is that you can not use the normal iterators on the

    const

vectors, you have to use the const_iterators. Another is that once in a while you get something like a

    (const RowType *)

from one method and need to pass it as an argument to another method that takes a

    (RowType *)

. In this case make sure that you know what you are doing and then proceed boldly with using a

    const_cast

. There is just no way to get all the const-ness self-consistent without ripping it out altogether.
const
const_iterator