libfx - C Software Development Kit¶

// target: valid macro's name

#define FX_ERROR_H
#define FX_YES 1
#define FX_NO 0
#define FX_COE 0x1234567A

// target: invalid macro's name

#define fx_error_h              // not upper case
#define FX_ERROR_h              // not upper case completly
#define _FX_ERROR_H             // _ prefix are reserved names
#define __FX_ERROR_H            // __ prefix are reserved names

// target: valid identity names

unsigned int year;
unsigned char month;
unsigned char day_in_month;
unsigned char day_in_week;
const double pi = 3.14;

struct date {};
void now_date(struct date *d);

// target: invalid identity names

unsigned int _year;             // _ prefix are reserved names
unsigned int __year;            // __ prefix are reserved names

unsigned int Year;              // contain upper case
struct Date {};
void Now_date(struct Date *d);
const double PI = 3.14;

// target: wrong identity names - too long

const double gravity_constant = 9.8;    // g is enough
                                        // any one work with physical
                                        // theory know what is g
                                        // if not, they should
                                        // research to know

struct input_output_type {};            // io_type is engouh
                                        // any one know what is io

// too long name: interator, i is engough
for (size_t interator = 0; interator < 8; ++interator) {}

// target: wrong identity names - too short

double s(double x) {                    // too short to understand
        return x * x;
}

double a[8] = {1, 2, 3, 4, 5, 6, 7, 8};
double b[8];

for (size_t i = 0; i < 8; ++i)          // we will look for s() to see
        b[i] = s(a[i]);                 // what is it doing because
                                        // we can not know from it
                                        // name, it is wasted time

// target: comment for header files

/*
        fx_array: array's interface - an abstract data type.

        fx_array_t store information about array.
        fx_array_init() initialize an array
        fx_array_free() release resources which uses by array
        fx_array_set() set a value into array at specific index
        fx_array_get() get a value from array at specific index
*/

typedef struct {} fx_array_t;

void fx_array_init(fx_array_t *a);
void fx_array_free(fx_array_t *a);
void fx_array_set(fx_array_t *a, size_t index, void *item);
void *fx_array_get(fx_array_t *a, size_t index);

// target: comment on one line in right side

const unsigned double g = 9.8;          // gravity constant
const unsigned double l = 299792458;    // speed of light

// target: comment for functions

struct qe2_result {
        bool has_roots;
        double x1;
        double x2;
};

void solve_qe2(double a, double b, double c, struct qe2_result *r);
/*
        Solve quadratic equation 2: y = a*x^2 + b*x + c.

        If a is zero, undefined behiviors.  If equation has root,
        r->has_roots is set to true and x1, x2 is set to corresponding
        values. If not, r->has_roots is set to false and x1, x2 is not
        change.
*/

Open and close curly brackets in same line if it is fits in one line.

Open curly brackets in same line and close curly brackets in next
line if it is not fits on one line.

// target:: open and close curly brackets on one line

enum week_day {mon, tue, wed, thus, fri, sat, sun};

unsigned char odd_numbers[] = {1, 3, 5, 7, 9};

// target: open and close curly brackets on multi line

struct qe2_result {
        bool has_roots;
        double x1;
        double x2;
};

void solve_qe2(double a, double b, double c, struct qe2_result *r) {

}

for (unsigned int i = 0; i < 10; ++i) {

}

Maximum characters per line is 78.

Indentation is 8 spaces.

// target: finite loop

int array[8] = {1, 2, 3, 4, 5, 6, 7, 8};
for (size_t i = 0; i < 8; ++i) {

}

// target: infinite loop

for (;;) {

}

// target: do some things first then check loop condition


for (bool still_loop = true;;) {        // verify loop condition here

                                        // do some things to change
                                        // loop condition here

        if (!still_loop)                // check loop condition here

                break;
}

// target: change loop condition in other statements


for (bool still_loop = true; still_loop;) {     // verify loop
                                                // condition here

                                                // change loop
                                                // condition here
}

// target: show interface, hide implementation and use interface

// in <yourlib/fx_array.h>
// show interface: data type and functions
typedef struct {} fx_array_t;
void fx_array_init(fx_array_t *a, size_t cap);
void fx_array_free(fx_array_t *a);
void fx_array_set(fx_array_t *a, size_t index, void *item);
void *fx_array_get(fx_array_t *a, size_t index);

// in <yourlib/fx_array.c>
// hide implementation, also define it
void fx_array_init(fx_array_t *a, size_t cap) {}
void fx_array_free(fx_array_t *a) {}
void fx_array_set(fx_array_t *a, size_t index, void *item) {}
void *fx_array_get(fx_array_t *a, size_t index) {}

// in <somewhere/main.c>
// use interface
#include <yourlib/fx_array.h>

fx_array_t v;
int data = 64;
int *item;

fx_array_init(&a, 128);
fx_array_set(&a, 0, &data);
item = (int *) fx_array_get(&a, 0);

// target: wrong access to private data type

typedef struct {                // define private type
        size_t cap;
        void **slots;
} fx_array_t;

int item = 8;
fx_array_t a;                   // define a instance
a.slots[0] = (void *) &item;    // do not do this

fx_array_set(&a, 0, &item);     // let interface do that

// target: work with public data type

// define interface: public data types and function
struct qe2_input {
        double a;
        double b;
        double c
};

struct qe2_output {
        bool has_roots;
        double x1;
        double x2;
};

void solve_qe2(struct qe2_input &in, struct qe2_output &out) {}

// use interface
struct qe2_input in;
struct qe2_output out;

in.a = 3;                       // set members freely
in.b = 4;
in.c = 5;
solve_qe2(&in, &out);

if (out.has_roots) {            // get members freely
        out.x1;
        out.x2;
}

/*
        That this, public data types occurs when you need to pass
        input arguments or get output data
*/

#include <fx_error/error.h>

#define FX_ERROR_DCL(error_id)
#define FX_ERROR_DEF(error_id)

typedef struct {} fx_error_t;
extern FX_ERROR_STATE_ATTR const fx_error_t *fx_error_state;

void fx_error_raise(const fx_error_t *e);
bool fx_error_catch(const fx_error_t *e);
bool fx_error_check(void);
void fx_error_clear(void);
const char *fx_error_id(const fx_error_t *e);

// target: declare, define errors

// in <yourlib/error.h>
#include <fx_error/error.h>     // use fx_error APIs

FX_ERROR_DCL(YOURLIB_E001);     // declare errors which may be occurs
FX_ERROR_DCL(YOURLIB_E002);     // in your library
FX_ERROR_DCL(YOURLIB_E003);

// in <yourlib/error.c>         // define errors
FX_ERROR_DEF(YOURLIB_E001);
FX_ERROR_DEF(YOURLIB_E002);
FX_ERROR_DEF(YOURLIB_E003);

// in <yourlib/api.h> or <yourlib/api.c>
// you can use YOURLIB_E001 with fx_error APIs

// target: raise, check, handle error

# include <yourlib/error.h>     // use your defined errors

// in <yourlib/do_work.h>
void do_work(void);             // describe why YOURLIB_E001 will
                                // occurs to help other people who
                                // uses your APIs check errors

// in <yourlib/do_work.c>
void do_work(void) {
        if (...) {                              // error condition
                fx_error_raise(YOURLIB_E001);   // raise error
                return;                         // stop function
        }
}

// in <somewhere/do_other_work.c>
#include <yourlib/do_work.h>            // use your APIs

void do_other_work(void) {
        do_work();                      // call your API
        if (fx_error_check()) {         // check error
                                        // handle error
        }
}

// target: check, handle multi error cases

// in <yourlib/do_work.h>
void do_work(void);     // describe why YOURLIB_E001, YOURLIB_E002
                        // and YOURLIB_E003 will be occurs

// in <yourlib/do_work.c>
void do_work(void) {
        if (...) {                              // error condition 1
                fx_error_raise(YOURLIB_E001);   // raise error
                return;                         // stop function
        }
        if (...) {                              // the same above
                fx_error_raise(YOURLIB_E002);
                return;
        }
        if (...) {                              // the same above
                fx_error_raise(YOURLIB_E003);
                return;
        }
}

// in <somewhere/do_other_work.c>
#include <yourlib/do_work.h>            // use your APIs

void do_other_work(void) {
        do_work();                              // call API
        if (fx_error_catch(YOURLIB_E001)) {     // check and handle
                                                // for YOURLIB_E001
        }
        if (fx_error_catch(YOURLIB_E002)) {     // check and handle
                                                // for YOURLIB_E002
        }
        if (fx_error_catch(YOURLIB_E003)) {     // check and handle
                                                // for YOURLIB_E003
        }
}

#include <fx_error/error.h>
// in libfx_error

#define FX_ERROR_DCL(error_id)
// declare error identity in header file

#define FX_ERROR_DEF(error_id)
// define error identity in source file

#define FX_ERROR_ASSERT(expression)
// verify at debug mode

void fx_error_raise(const fx_error_t *e);
// set fx_error_state to e

int fx_error_catch(const fx_error_t *e);
// check specific error has occurs

int fx_error_check(void);
// check error has occurs or not

void fx_error_clear(void);
// set fx_error_state to FX_ENONE

const char *fx_error_id(const fx_error_t *e);
// get short string which describe error

// target: declare, define errors

// in <yourlib/error.h>
#include <fx_error/error.h>     // use fx_error APIs

FX_ERROR_DCL(YOURLIB_E001);     // declare errors which may be occurs
FX_ERROR_DCL(YOURLIB_E002);     // in your library
FX_ERROR_DCL(YOURLIB_E003);

// in <yourlib/error.c>         // define errors
FX_ERROR_DEF(YOURLIB_E001);
FX_ERROR_DEF(YOURLIB_E002);
FX_ERROR_DEF(YOURLIB_E003);

// in <yourlib/api.h> or <yourlib/api.c>
// you can use YOURLIB_E001 with fx_error APIs

// target: raise, check, handle error

# include <yourlib/error.h>     // use your defined errors

// in <yourlib/do_work.h>
void do_work(void);             // describe why YOURLIB_E001 will
                                // occurs to help other people who
                                // uses your APIs check errors

// in <yourlib/do_work.c>
void do_work(void) {
        if (...) {                              // error condition
                fx_error_raise(YOURLIB_E001);   // raise error
                return;                         // stop function
        }
}

// in <somewhere/do_other_work.c>
#include <yourlib/do_work.h>            // use your APIs

void do_other_work(void) {
        do_work();                      // call your API
        if (fx_error_check()) {         // check error
                                        // handle error
        }
}

// target: raise error then abort process

// in <yourlib/do_work_abort.h>
void do_work_abort();           // describe why YOURLIB_E001 will
                                // be occurs and process will be
                                // terminate also

// in <yourlib/do_work_abort.c>
void do_work_abort(int arg) {
        if (...)                                // error condition
                fx_error_abort(YOURLIB_E001);   // raise error then
                                                // abort
}

// in <somewhere/do_other_work.c>
#include <yourlib/do_work.h>    // use your APIs

void do_other_work(void) {
        do_work_abort();        // call API
                                // if error occurs, error state will
                                // be set then terminate process with
                                // SIGABRT
}

// target: check, handle multi error cases

// in <yourlib/do_work.h>
void do_work(void);     // describe why YOURLIB_E001, YOURLIB_E002
                        // and YOURLIB_E003 will be occurs

// in <yourlib/do_work.c>
void do_work(void) {
        if (...) {                              // error condition 1
                fx_error_raise(YOURLIB_E001);   // raise error
                return;                         // stop function
        }
        if (...) {                              // the same above
                fx_error_raise(YOURLIB_E002);
                return;
        }
        if (...) {                              // the same above
                fx_error_raise(YOURLIB_E003);
                return;
        }
}

// in <somewhere/do_other_work.c>
#include <yourlib/do_work.h>            // use your APIs

void do_other_work(void) {
        do_work();                              // call API
        if (fx_error_catch(YOURLIB_E001)) {     // check and handle
                                                // for YOURLIB_E001
        }
        if (fx_error_catch(YOURLIB_E002)) {     // check and handle
                                                // for YOURLIB_E002
        }
        if (fx_error_catch(YOURLIB_E003)) {     // check and handle
                                                // for YOURLIB_E003
        }
}

#include <fx_error/kernel.h>

const struct fx_error *fx_error_from_kernel(int code);
// return fx_error_t * from kernel error code

void fx_error_kraise(int code);
// raise fx_error from kernel error code

// pre-defined errors corespond with kernel error codes
// for example: EPERM corespond with FX_EPERM

#include <fx_error/error.h>

FX_ERROR_DCL(FX_EINDEX);        // invalid index accessing
FX_ERROR_DCL(FX_EKEY);          // invalid key accessing
FX_ERROR_DCL(FX_EFULL);         // full storage

#include <fx_test/test.h>

void fx_test_init(fx_test_t *t, enum fx_test_mode mode);
// initialize testing

void fx_test_free(fx_test_t *t);
// release resources which uses by testing

void fx_test_run(fx_test_t *t, const fx_test_unit_set_t *s);
// run unit tests in parallel

void fx_test_join(fx_test_t *t, fx_test_result_t *r);
// wait for all of unit tests finished

void fx_test_result_dump(FILE *out, fx_test_result_t *r);
// print testing's result

#include <fx_test/queue.h>
// in libfx_test

void fx_test_queue_init(fx_test_queue_t *q, size_t cap);
// initialize queue

void fx_test_queue_free(fx_test_queue_t *q);
// release resources which uses by queue

void fx_test_queue_push(fx_test_queue_t *q, void *item);
// add item into back of queue

void *fx_test_queue_front(fx_test_queue_t *q);
// get item in front of queue

void fx_test_queue_pop(fx_test_queue_t *q);
// remove an item in front of queue

void fx_test_queue_clear(fx_test_queue_t *q);
// make queue is empty

bool fx_test_queue_empty(fx_test_queue_t *q);
// check queue is empty or not

bool fx_test_queue_full(fx_test_queue_t *q);
// check queue is full or not

// target: initialize, push, front, pop and free queue

#include <fx_test/queue.h>              // use queue APIs

fx_test_queue_t q;                      // initialize
fx_test_queue_init(&q, 128);

int one = 1;
int two = 2;
int three = 3;
fx_test_queue_push(&q, &one);           // push items to front
fx_test_queue_push(&q, &two);
fx_test_queue_push(&q, &three);

int *item;
item = fx_test_queue_front(&q);         // get front item
fx_test_queue_pop(&q);                  // remove front item

fx_test_free(&q);                       // release resources