From 81f8fd63a82915fc274c7cac10854cadf2f640f9 Mon Sep 17 00:00:00 2001 From: Daniel Santos Date: Sun, 20 Mar 2022 13:36:29 +0000 Subject: README.md update * add library information to README.md * fixed some README.md mistakes * update doc/ Signed-off-by: Daniel Santos --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-------- doc | 2 +- 2 files changed, 84 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0df7a21..98b669d 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,85 @@ # Numericx Readme -A command-line interface (CLI) program that converts a number (or text) from one numerical system into another different numerical system. +A program that converts a number (or text) from one numerical system into another different numerical system. -## Compiling +## C library -This program create an executable (or many) that will convert a number from one numerical system into another one. +### Create libraries -For example, you may want to convert a hexadecimal number into a ternary number. You may use this program. +You may use `make libs` to create a static and a shared numericx library. To install a shared library into your system use `sudo make prefix=/usr install-lib`. + +### Functions + +See [Numericx documentation website](https://dacs-git.codeberg.page/numericx/), for the list of functions and function arguments of the Numericx library. +Look at `Files > File List` in the documentation menubar website. + +There are basically two main functions: the `numericx_translate()` and the `numericx_free()`. Remember to free your numericx result with `numericx_free(var);`! + +### Code example + +Look at the `cli.c` file for an example of how to call Numericx in your C program. + +Here is a code snippet: + +``` +(...) + +/* 'result' variable has to be NULL */ +char* result = NULL; + +/* + * 'from', 'to' and 'number' are strings (malloced or literals, not arrays). + * the rest of the variables, except 'result', are booleans + * + * Do the translation + */ +int status = numericx_translate( + from_numericals, from_units_on_the_end, from_first_number_void, from_infinite_base, + to_numericals, to_units_on_the_end, to_first_number_void, to_infinite_base, + number, &result); + +/* Test for translation failure */ +switch( status ) +{ + case EINVAL: + fprintf(stderr, "error: numericx: %s. Resulting string argument value has to be NULL.\n", + strerror(EINVAL)); + break; + case EDOM: + fprintf(stderr, "error: numericx: %s. Valid numerals are: \"%s\".\n", + strerror(EDOM), from); + break; + case ERANGE: + fprintf(stderr, "error: numericx: Unrepresentable void number.\n"); + break; +} + +/* General error message with free and exit() */ +if( !(status == true) ) +{ + fprintf(stderr, "error: numericx: Incapable of translating.\n"); + numericx_free(result); + + exit(EXIT_FAILURE); +} + +/* Print translated number ('result') in case of success */ +printf("%s\n", result); + +/* Free translated number, when no longer needed */ +numericx_free(result); + +(...) +``` + + +## CLI + +### Compiling + +With this program, you can create an executable (or many) that will convert a number from one numerical system into another one. This is good if, for example, you want to use numerical system translation with your bash terminal. + +For example, you may want to convert a hexadecimal number into a ternary number. Here is what you would do. You first need to define the proprieties of the numerical systems. These proprieties are defined in the compilation process (as compilation flags). @@ -26,17 +99,17 @@ if you want the units place of this numerical system to be on the right side, us Now, to create the executable to translate a number for these two numerical system, join all of this together and compile using this: ``` -$ cc -DFROM_NUMERICALS=\"0123456789abcdef\" -DFROM_FIRST_NUMBER_VOID -DFROM_INFINITE_BASE -DFROM_UNITS_ON_THE_END -DTO_NUMERICALS=\"123\" -DTO_UNITS_ON_THE_END numericx.c -o hex-to-ternary +$ cc -DFROM_NUMERICALS=\"0123456789abcdef\" -DFROM_FIRST_NUMBER_VOID -DFROM_INFINITE_BASE -DFROM_UNITS_ON_THE_END -DTO_NUMERICALS=\"123\" -DTO_UNITS_ON_THE_END numericx.c cli.c -o hex-to-ternary ``` This creates the `hex-to-ternary` executable with can be used to convert numbers from hexadecimal to ternary! -## Pre-defined executable compilation +### Pre-defined executable compilation There are many pre-defined compilation of executables on the Makefile. Take a look at the Makefile to know them. Or you can run `make` to get all of the pre-defined executables. `make clean` to delete them. -## Compilation flags meanings +### Compilation flags meanings There are two categories for the compilation flags: the `FROM` category and the `TO` category. @@ -48,21 +121,19 @@ Below, are the meanings of the `FROM` flags. The `TO` flags are the same as the |Flag|Meaning| |---|---| -|`FROM_NUMERALS`|Define the numerical system numerals of the 'from'| +|`FROM_NUMERICALS`|Define the numerical system numerals of the 'from'| |`FROM_UNITS_ON_THE_END`|Defines the units case to be on the end (on the right) for the 'from'| |`FROM_FIRST_NUMBER_VOID`|Defines the first number as a "not counting" for the 'from'| |`FROM_INFINITE_BASE`|Defines the first number to be infinite, for the 'from' (for example, if the first numeral is 0, then 0 == 00 == 000 == 0000 ... . Or if the first numeral is 1, then 1 == 11 == 111 ...)| -Remember: you use put a `-D` before these flags names as an compiler argument. For example, `-DFROM_NUMERALS=...`. +Remember: you use put a `-D` before these flags names as an compiler argument. For example, `-DFROM_NUMERICALS=...`. -## Documentation - -See [numericx documentation page](https://dacs-git.codeberg.page/numericx/). Look at `Files > File List` in the documentation menubar website. ## License MIT + ## Author Daniel A. C. Santos diff --git a/doc b/doc index c653752..f5ca804 160000 --- a/doc +++ b/doc @@ -1 +1 @@ -Subproject commit c653752b636a734879c064cb198244a84796a318 +Subproject commit f5ca8047d9b8c93d6a00b047d7eec869f0fdf6c5 -- cgit 1.4.1-2-gfad0