Browse Source

Fixed documentation. Updated README.md.

master
frnmst/Franco Masotti 6 years ago
parent
commit
a02392908b
  1. 36
      README.md
  2. BIN
      refman.pdf
  3. 6
      src/Makefile
  4. 8
      src/doxy.conf
  5. BIN
      src/refman.pdf
  6. 83
      src/salibc.c
  7. 8
      src/salibc.h
  8. 4
      src/salibc_test.c

36
README.md

@ -6,33 +6,47 @@ Simple Array C Library
The methods accessible to the user (the non `static` ones) are the ones
described in `salibc.h`.
To generate the ducumentation, you need to install `doxygen`, `texlive-core`
and `texlive-latexextra` (these are the names under Parabola GNU/Linux-libre
distro).
The first thing to do i to move to the `src` directory:
```
$ cd src
```
To generate the documentation, you need to install the following packages:
```
doxygen
texlive-core
texlive-latexextra
```
You can then execute the following:
These are the names under Parabola GNU/Linux-libre distro.
You can then execute the following if you are only interested in the HTML form:
```
$ cd src && make doxygen && cd latex && make
$ make doxygen
```
This will generate both LaTeX (`src/latex/refman.pdf`) and HTML
(`src/html/index.html`) documentation.
Or, if you want a pdf file (`../refman.pdf`):
```
$ make doxygenlatex
```
If you are only interested in the HTML form you don't need to install the
LaTeX packages.
You can also remove the whole documentation like this:
```
$ make cleandoxygen
```
The doxygen configuration file has been generated with the following:
```
$ doxygen -g doxy.conf
```
and then edited with the options I thought were useful.
where `doxy.conf` was edited with the options I thought were useful.
##Test
You can test the library with the following:
```
$ cd src && make
$ make
```
This will generate an executable file called `salibc.out`.

BIN
refman.pdf

Binary file not shown.

6
src/Makefile

@ -64,5 +64,11 @@ salibc: salibc.o salibc_test.o
doxygen:
@doxygen doxy.conf
doxygenlatex: doxygen
@cd latex; make pdf; mv refman.pdf ../../.; cd ..
cleandoxygen:
@rm -rf html latex ../refman.pdf
# to protect files with the following names, the .PHONY rule is used
.PHONY: default all clean indent $(EXECUTABLES)

8
src/doxy.conf

@ -66,7 +66,7 @@ PROJECT_NUMBER =
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF =
PROJECT_BRIEF = Simple C Array Library
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55
@ -438,7 +438,7 @@ LOOKUP_CACHE_SIZE = 0
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
@ -2000,7 +2000,7 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
@ -2040,7 +2040,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
PREDEFINED = DOXYGEN
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The

BIN
src/refman.pdf

Binary file not shown.

83
src/salibc.c

@ -1,4 +1,4 @@
/**
/*
* @file salibc.c
* @author Franco Masotti
* @date 28 Apr 2016
@ -92,16 +92,17 @@ element_null (void *element)
return (element == NULL);
}
#if defined (MEMORY_OVERLAP_CHECK) || DOXYGEN
/**
* If this flag is defined memory_overlaps function will work normally,
* @brief If this flag is defined memory_overlaps function will work normally,
* otherwise it will only return false. By default this flag is deactivated.
*/
#ifdef MEMORY_OVERLAP_CHECK
#define MEMORY_OVERLAP_CHECK
/**
* Since memory is not always allocated consecutively, the following controls
* may fail because the only check memory addresses and not if that memory
* belongs to something else.
* @note Since memory is not always allocated consecutively, the following
* controls may fail because only memory addresses are checked and the
* system does not know if the memory in between belongs to something else.
*/
static bool
memory_overlaps (void *chunk1, void *chunk2, size_t fullsize)
@ -138,7 +139,8 @@ memory_overlaps (void *chunk1, void *chunk2, size_t fullsize)
*/
/**
* Delete the non-ADT part of the array (as well as some fields of the ADT).
* @note The non-ADT part of the array is deleted (as well as some fields of
* the ADT).
*/
static void
realarray_delete (Array a)
@ -146,7 +148,6 @@ realarray_delete (Array a)
if (array_null (a))
return;
/* Free the real array. */
free (array_pointer (a));
a->ptr = NULL;
a->nmemb = 0;
@ -177,7 +178,7 @@ array_indexpointer (Array a, int index)
}
/**
* It is assumed that element has the same size of a->ptr.
* @note It is assumed that element has the same size of a->ptr.
*/
static bool
array_memcopy (Array a, int index, void *element)
@ -186,10 +187,11 @@ array_memcopy (Array a, int index, void *element)
return false;
/**
* Even though the array_indexoutofbounds function is called inside the
* @note Even though the array_indexoutofbounds function is called inside the
* array_indexpointer function, this returns NULL, so memcpy would be done
* on a dest of NULL.
* on a dest of NULL. That's why we need to call that function here as well
*/
/** @code */
if (!element_null (element)
&& !memory_overlaps (a, element, array_fullsize (a))
&& !array_indexoutofbounds (a, index))
@ -197,6 +199,7 @@ array_memcopy (Array a, int index, void *element)
memcpy (array_indexpointer (a, index), element, array_size (a));
return true;
}
/** @endcode */
else
return false;
}
@ -229,7 +232,7 @@ array_length (Array a)
}
/**
* This function should not return an out of bound value.
* @note This function should not return an out of bound value.
*/
size_t
array_fullsize (Array a)
@ -248,7 +251,8 @@ array_pointer (Array a)
}
/**
* memcmp works well in checking equality even for floating point numbers.
* @note memcmp works well in checking equality even for floating point
* numbers.
*/
bool
array_equal (Array a1, Array a2)
@ -266,7 +270,7 @@ array_equal (Array a1, Array a2)
}
/**
* Array constructor.
* @note This function is also known as the array constructor.
*/
Array
array_new (int nmemb, size_t size)
@ -286,9 +290,6 @@ array_new (int nmemb, size_t size)
array_delete (&new_array);
}
/**
* This may be NULL.
*/
return new_array;
}
@ -297,13 +298,7 @@ array_delete (Array * a_ref)
{
if (!element_null (a_ref) && !array_null (*a_ref))
{
/**
* Free the real array.
*/
realarray_delete (*a_ref);
/**
* Free the ADT.
*/
(*a_ref)->size = 0;
free (*a_ref);
*a_ref = NULL;
@ -332,7 +327,7 @@ array_set (Array a, void *element)
}
/**
* This is an interface to array_indexpointer.
* @note This function is an interface to array_indexpointer.
*/
char *
array_get (Array a, int index)
@ -350,18 +345,22 @@ array_copy (Array a1)
return NULL;
/**
* Allocate a new array with the same ADT characteristics.
* @note Allocate a new array with the same ADT characteristics.
*/
/** @code */
a2 = array_new (array_length (a1), array_size (a1));
if (array_null (a2))
return NULL;
/** @endcode */
/**
* Copy the real array using the previously defined functions.
* @note Copy the real array using the previously defined functions.
*/
/** @code */
for (i = 0; i < array_length (a1); i++)
if (!array_memcopy (a2, i, array_indexpointer (a1, i)))
return NULL;
/** @endcode */
return a2;
}
@ -375,30 +374,31 @@ array_resize (Array a, int new_length)
if (array_null (a))
return NULL;
/**
/** @code */
/*
* Invalid new length.
*/
if (new_length < 0)
return false;
/**
* new_length is set to 0 -> leave ADT, but delete internal array.
/*
* new_length is set to zero, so leave the ADT, but delete internal array.
*/
else if (new_length == 0)
{
realarray_delete (a);
return true;
}
/**
* Same size -> do nothing.
/*
* Same size as before, then do nothing.
*/
else if (array_length (a) == new_length)
return true;
/**
/*
* Array's length != new_length, so realloc can now be used directly.
*/
else
{
/**
/*
* Safe realloc (to avoid losing the stored array if realloc fails).
*/
tmp =
@ -409,7 +409,7 @@ array_resize (Array a, int new_length)
a->ptr = tmp;
else
return false;
/**
/*
* memset to 0 new part of the array.
* To do this we must go to the first byte of the new array and put 0
* until we get to (memdiff * a->size) bytes.
@ -419,17 +419,18 @@ array_resize (Array a, int new_length)
memset (array_pointer (a) + array_fullsize (a) + array_size (a), 0,
((size_t) memdiff) * array_size (a));
/**
/*
* Set the new array length.
*/
a->nmemb = new_length;
}
return true;
/** @endcode */
}
/**
* This function alters the input.
* @note This function alters the input.
*/
bool
array_append (Array a, void *element)
@ -449,12 +450,14 @@ array_trim (Array a)
int initial_length = array_length (a);
char *element, *element_copy;
element = array_indexpointer (a, initial_length - 1);
/**
* Copy *element int *element_copy.
* @note Copy *element int *element_copy.
*/
/** @code */
element = array_indexpointer (a, initial_length - 1);
element_copy = malloc (array_size (a));
memcpy (element_copy, element, array_size (a));
/** @endcode */
if (!element_null (element_copy) && array_resize (a, initial_length - 1))
return element_copy;
@ -469,11 +472,13 @@ array_merge (Array a1, Array a2)
int i, j, total_length = array_length (a1) + array_length (a2);
/**
* Safety controls.
* @note Safety controls.
*/
/** @code */
if ((array_null (a1) && array_null (a2)) || (array_size (a1) !=
array_size (a2)))
return NULL;
/** @endcode */
new_array = array_new (total_length, array_size (a1));
if (array_null (new_array))

8
src/salibc.h

@ -28,6 +28,10 @@
*/
#ifndef SALIBC
/**
* @brief Include the main header.
*/
#define SALIBC
/**
@ -48,6 +52,10 @@
/**
* @brief Array Abstract Data Type.
*
* @struct Array
*
* @typedef struct Array *Array
*/
typedef struct Array
{

4
src/salibc_test.c

@ -33,10 +33,10 @@
* @brief if this flag is defined then the main function in this file is
* included.
*/
#ifdef SALIBC_TEST
#if defined (SALIBC_TEST) || DOXYGEN
/**
* @brief Use:
* @note Use:
* const MYVARIABLE = value
* instead of:
* value