README.md update

* add library information to README.md
 * fixed some README.md mistakes
 * update doc/

Signed-off-by: Daniel Santos <dacs.git@brilhante.top>
This commit is contained in:
Daniel Santos 2022-03-20 13:36:29 +00:00
parent a6b6c803a0
commit 81f8fd63a8
2 changed files with 84 additions and 13 deletions

View File

@ -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

2
doc

@ -1 +1 @@
Subproject commit c653752b636a734879c064cb198244a84796a318
Subproject commit f5ca8047d9b8c93d6a00b047d7eec869f0fdf6c5