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:
parent
a6b6c803a0
commit
81f8fd63a8
95
README.md
95
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
|
||||
|
|
2
doc
2
doc
|
@ -1 +1 @@
|
|||
Subproject commit c653752b636a734879c064cb198244a84796a318
|
||||
Subproject commit f5ca8047d9b8c93d6a00b047d7eec869f0fdf6c5
|
Loading…
Reference in New Issue