C API

= C API =

The C API has two parts: the writer API and reader API.

== writer API ==

The first function called when writing pointless files is pointless_create_begin()

{{{ void pointless_create_begin(pointless_create_t* c); }}}

The last function called is one of

{{{ // cancel writing void pointless_create_end(pointless_create_t* c);

// write to file int pointless_create_output_and_end_f(pointless_create_t* c, const char* fname, const char** error);

// write to in-memory buffer int pointless_create_output_and_end_b(pointless_create_t* c, void** buf, size_t* buflen, const char** error); }}}

They return 0 on failure, 1 on success.

In between, values are created, and the root value is set.

{{{ // inline-values uint32_t pointless_create_i32(pointless_create_t* c, int32_t v); uint32_t pointless_create_u32(pointless_create_t* c, uint32_t v); uint32_t pointless_create_float(pointless_create_t* c, float v); uint32_t pointless_create_null(pointless_create_t* c);

uint32_t pointless_create_boolean_true(pointless_create_t* c); uint32_t pointless_create_boolean_false(pointless_create_t* c); uint32_t pointless_create_empty_slot(pointless_create_t* c);

// vectors, buffer owned by library uint32_t pointless_create_vector_value(pointless_create_t* c); uint32_t pointless_create_vector_i8(pointless_create_t* c); uint32_t pointless_create_vector_u8(pointless_create_t* c); uint32_t pointless_create_vector_i16(pointless_create_t* c); uint32_t pointless_create_vector_u16(pointless_create_t* c); uint32_t pointless_create_vector_i32(pointless_create_t* c); uint32_t pointless_create_vector_u32(pointless_create_t* c); uint32_t pointless_create_vector_float(pointless_create_t* c);

uint32_t pointless_create_vector_value_append(pointless_create_t* c, uint32_t vector, uint32_t v); uint32_t pointless_create_vector_i8_append(pointless_create_t* c, uint32_t vector, int8_t v); uint32_t pointless_create_vector_u8_append(pointless_create_t* c, uint32_t vector, uint8_t v); uint32_t pointless_create_vector_i16_append(pointless_create_t* c, uint32_t vector, int16_t v); uint32_t pointless_create_vector_u16_append(pointless_create_t* c, uint32_t vector, uint16_t v); uint32_t pointless_create_vector_i32_append(pointless_create_t* c, uint32_t vector, int32_t v); uint32_t pointless_create_vector_u32_append(pointless_create_t* c, uint32_t vector, uint32_t v); uint32_t pointless_create_vector_float_append(pointless_create_t* c, uint32_t vector, float v);

void pointless_create_vector_value_set(pointless_create_t* c, uint32_t vector, uint32_t i, uint32_t v);

uint32_t pointless_create_vector_u32_transfer(pointless_create_t* c, uint32_t vector, uint32_t* v, uint32_t n); uint32_t pointless_create_vector_value_transfer(pointless_create_t* c, uint32_t vector, uint32_t* v, uint32_t n);

// vectors, buffer owned by caller uint32_t pointless_create_vector_i8_owner(pointless_create_t* c, int8_t* items, uint32_t n_items); uint32_t pointless_create_vector_u8_owner(pointless_create_t* c, uint8_t* items, uint32_t n_items); uint32_t pointless_create_vector_i16_owner(pointless_create_t* c, int16_t* items, uint32_t n_items); uint32_t pointless_create_vector_u16_owner(pointless_create_t* c, uint16_t* items, uint32_t n_items); uint32_t pointless_create_vector_i32_owner(pointless_create_t* c, int32_t* items, uint32_t n_items); uint32_t pointless_create_vector_u32_owner(pointless_create_t* c, uint32_t* items, uint32_t n_items); uint32_t pointless_create_vector_float_owner(pointless_create_t* c, float* items, uint32_t n_items);

// sets uint32_t pointless_create_set(pointless_create_t* c); uint32_t pointless_create_set_add(pointless_create_t* c, uint32_t s, uint32_t k);

// maps uint32_t pointless_create_map(pointless_create_t* c); uint32_t pointless_create_map_add(pointless_create_t* c, uint32_t m, uint32_t k, uint32_t v); }}}

Each create-value function returns a handle, which is used by the set-root function, and create-value functions for values which can store other values. create-value functions return POINTLESS_CREATE_VALUE_FAIL on failure.

== reader API ==

The reader API is less straight-forward. The top-level functions are

{{{ // open pointless file int pointless_open_f(pointless_t* p, const char* fname, const char** error);

// open from in-memory buffer, will be free()'d by the library on close. int pointless_open_m(pointless_t* p, void* buf, size_t buflen, const char** error);

// close void pointless_close(pointless_t* p); }}}

The start traversing the data structure, the root must be known

{{{ pointless_value_t* pointless_root(pointless_t* p); }}}

The type is available through the type field. There are many functions to traverse containers, and fetch inline-values.

=== Inline values ===

{{{ int32_t pointless_value_get_i32(uint32_t t, pointless_value_data_t* v); uint32_t pointless_value_get_u32(uint32_t t, pointless_value_data_t* v); float pointless_value_get_float(uint32_t t, pointless_value_data_t* v); uint32_t pointless_value_get_bool(uint32_t t, pointless_value_data_t* v); }}}

=== Unicode values ===

{{{ uint32_t pointless_reader_unicode_len(pointless_t* p, pointless_value_t* v); uint32_t* pointless_reader_unicode_value_ucs4(pointless_t* p, pointless_value_t* v);

// note: caller must free() the returned buffers const char* pointless_reader_unicode_value_utf7_alloc(pointless_t* p, pointless_value_t* v, const char** error); const char* pointless_reader_unicode_value_utf8_alloc(pointless_t* p, pointless_value_t* v, const char** error); uint16_t* pointless_reader_unicode_value_ucs2_alloc(pointless_t* p, pointless_value_t* v, const char** error); }}}

=== Vectors ===

Each of these corresponds to a different vector type.

{{{ uint32_t pointless_reader_vector_n_items(pointless_t* p, pointless_value_t* v); pointless_value_t* pointless_reader_vector_value(pointless_t* p, pointless_value_t* v); int8_t* pointless_reader_vector_i8(pointless_t* p, pointless_value_t* v); uint8_t* pointless_reader_vector_u8(pointless_t* p, pointless_value_t* v); int16_t* pointless_reader_vector_i16(pointless_t* p, pointless_value_t* v); uint16_t* pointless_reader_vector_u16(pointless_t* p, pointless_value_t* v); int32_t* pointless_reader_vector_i32(pointless_t* p, pointless_value_t* v); uint32_t* pointless_reader_vector_u32(pointless_t* p, pointless_value_t* v); float* pointless_reader_vector_float(pointless_t* p, pointless_value_t* v); }}}

=== Bit vectors ===

{{{ uint32_t pointless_reader_bitvector_n_bits(pointless_t* p, pointless_value_t* v); uint32_t pointless_reader_bitvector_is_set(pointless_t* p, pointless_value_t* v, uint32_t bit); }}}

=== Sets/Maps ===

TBD