# C API

    library(colorfast)

`{colorfast}` exports three C functions for use in other packages.

To use these functions:

- In your package `DESCRIPTION`
  - Add `LinkingTo: colorfast`
  - Add `Depends: colorfast (>= 1.0.1)`
- In your C code
  - Add `#include <colorfast.h>`
  - Call the functions below

    void col_to_rgb(const char *col, uint8_t ptr[4]);
    uint32_t col_to_int(const char *col);
    void int_to_col(uint32_t icol, char buf[10]);

## String color to vector of RGBA values

`void col_to_rgb(const char *col, uint8_t ptr[4])`

- `const char *col` is a pointer to a null-terminated C string containing either a hex color, or the name of a standard R color: E.g. `"#1287Af"`, `"hotpink"`
- `uint8_t ptr[4]` holds the values returned from the function i.e. RGBA color component values

The R call `col_to_rgb('red')`, can be called via the C api as:

    #include <stdint.h>
    #include <colorfast.h>

    void convert_col_to_rgb(const char *col) {
      uint8_t values[4];
      col_to_rgb(col, values);

      for (int i = 0; i < 4; ++i) {
        printf("%i ", values[i]);
      }
    }

## String color to packed integer color

`void col_to_int(const char *col)`

- `const char *col` is a pointer to a null-terminated C string containing either a hex color, or the name of a standard R color: E.g. `"#1287Af"`, `"hotpink"`

    #include <stdint.h>
    #include <colorfast.h>

    void convert_col_to_int(const char *col) {
      uint32_t value = col_to_int(col);

      printf("%i ", value);
    }

## Packed integer color to hexadecimal color

`void int_to_col(uint32_t icol, char buf[10])`

- `uint32_t icol` unsigned integer holding the 4 RGBA color values
- `char buf[10]` a character buffer into which the hex color will be written e.g. `#1154EE00`

    #include <stdint.h>
    #include <colorfast.h>

    void convert_int_to_col(uint32_t icol) {
      char buf[10];
      int_to_col(icol, buf);

      printf("%s\n", buf);
    }