[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 195fae5: Completed Lists, types and blank libr
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master 195fae5: Completed Lists, types and blank library documentation |
|
Date: |
Fri, 28 Apr 2017 22:21:20 -0400 (EDT) |
branch: master
commit 195fae5be4f3f6a3e46ae261326da70b20705ea8
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>
Completed Lists, types and blank library documentation
The documentation of the existing functions to work with lists has been
completed. In the process the `gal_list_tosizet_t' was renamed to
`gal_list_dosizet_t': instead of "two-way" we are now calling it
"doubly-linked", ordered size_t list which is the conventional name for
this type of lists. Some small corrections were also made to the functions
(that has now been applied in the manual).
Thanks again to Guillaume Mahler (Similar to the previous commit) another
compiler warning about printing `uint64_t' has been corrected.
---
bin/mkcatalog/mkcatalog.c | 3 +-
bin/mkprof/oneprofile.c | 10 +-
doc/gnuastro.texi | 996 ++++++++++++++++++++++++++++++++++++----------
lib/blank.c | 24 +-
lib/gnuastro/blank.h | 6 +-
lib/gnuastro/list.h | 43 +-
lib/interpolate.c | 10 +-
lib/list.c | 112 +++---
8 files changed, 897 insertions(+), 307 deletions(-)
diff --git a/bin/mkcatalog/mkcatalog.c b/bin/mkcatalog/mkcatalog.c
index 1e074a0..1e2b57d 100644
--- a/bin/mkcatalog/mkcatalog.c
+++ b/bin/mkcatalog/mkcatalog.c
@@ -29,6 +29,7 @@ along with Gnuastro. If not, see
<http://www.gnu.org/licenses/>.
#include <float.h>
#include <string.h>
#include <stdlib.h>
+#include <inttypes.h>
#include <gnuastro/git.h>
#include <gnuastro/wcs.h>
@@ -769,7 +770,7 @@ mkcatalog_outputs_same_start(struct mkcatalogparams *p, int
o0c1,
asprintf(&str, "Random number generator name: %s", p->rngname);
gal_list_str_add(&comments, str, 0);
- asprintf(&str, "Random number generator seed: %lu", p->seed);
+ asprintf(&str, "Random number generator seed: %"PRIu64, p->seed);
gal_list_str_add(&comments, str, 0);
asprintf(&str, "Multiple of STD used for sigma-clipping: %.3f",
diff --git a/bin/mkprof/oneprofile.c b/bin/mkprof/oneprofile.c
index 5fdd9ff..295651f 100644
--- a/bin/mkprof/oneprofile.c
+++ b/bin/mkprof/oneprofile.c
@@ -239,7 +239,7 @@ makepixbypix(struct mkonthread *mkp)
double truncr=mkp->truncr, approx, hp=0.5f/mkp->p->oversample;
/* lQ: Largest. sQ: Smallest in queue */
- gal_list_tosizet_t *lQ=NULL, *sQ;
+ gal_list_dosizet_t *lQ=NULL, *sQ;
/* Find the nearest pixel to the profile center and add it to the
queue. */
@@ -258,7 +258,7 @@ makepixbypix(struct mkonthread *mkp)
/* Start the queue: */
byt[p]=1;
- gal_list_tosizet_add( &lQ, &sQ, p, r_circle(p, mkp) );
+ gal_list_dosizet_add( &lQ, &sQ, p, r_circle(p, mkp) );
/* If random points are necessary, then do it: */
if(mkp->func==PROFILE_SERSIC || mkp->func==PROFILE_MOFFAT
@@ -276,7 +276,7 @@ makepixbypix(struct mkonthread *mkp)
over sampled image. But all the profile parameters are in the
non-oversampled image. So we divide the distance by os
(p->oversample in double type) */
- gal_list_tosizet_pop_smallest(&lQ, &sQ, &p, &circ_r);
+ p=gal_list_dosizet_pop_smallest(&lQ, &sQ, &circ_r);
mkp->x=(p/is1-xc)/os;
mkp->y=(p%is1-yc)/os;
r_el(mkp);
@@ -312,7 +312,7 @@ makepixbypix(struct mkonthread *mkp)
if(byt[nind]==0)
{
byt[nind]=1;
- gal_list_tosizet_add( &lQ, &sQ, nind, r_circle(nind, mkp) );
+ gal_list_dosizet_add( &lQ, &sQ, nind, r_circle(nind, mkp) );
}
} );
@@ -323,7 +323,7 @@ makepixbypix(struct mkonthread *mkp)
/* All the pixels that required integration or random points are now
done, so we don't need an ordered array any more. */
- gal_list_tosizet_to_sizet(lQ, &Q);
+ gal_list_dosizet_to_sizet(lQ, &Q);
/* Order doesn't matter any more, add all the pixels you find. */
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 386b08d..a564cb3 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -528,16 +528,16 @@ Review of library fundamentals
Gnuastro library
* Configuration information:: General information about library config.
-* Library data types::
-* Library blank values::
-* Library data container::
+* Library data types:: Definitions and functions for types in
Gnuastro.
+* Library blank values:: Blank values and functions to deal with them.
+* Library data container:: General data container in Gnuastro.
* Linked lists:: Various types of linked lists.
-* Table input output::
-* Arithmetic on datasets::
-* Tessellation library::
+* Table input output:: Reading and writing table columns.
+* Arithmetic on datasets:: Arithmetic operations on a dataset.
+* Tessellation library:: Functions for working on tiles.
* Bounding box:: Finding the bounding box.
* FITS files:: Working with FITS data.
-* Text files::
+* Text files:: Functions to work on Text files.
* Git wrappers:: Wrappers for functions in libgit2.
* Polygons:: Working with the vertices of a polygon.
* Qsort functions:: Helper functions for Qsort.
@@ -553,12 +553,15 @@ Data container (@file{data.h})
Linked lists (@file{linkedlist.h})
-* List of strings::
-* List of int32_t::
-* List of size_t::
-* Ordered list of size_t::
-* Two way list of ordered size_t::
-* List of gal_data_t::
+* List of strings:: Simply linked list of strings.
+* List of int32_t:: Simply linked list of int32_ts.
+* List of size_t:: Simply linked list of size_ts.
+* List of float:: Simply linked list of floats.
+* List of double:: Simply linked list of doubles
+* List of void:: Simply linked list of void * pointers.
+* Ordered list of size_t:: Simply linked, ordered list of size_t.
+* Doubly linked ordered list of size_t:: Definition and functions.
+* List of gal_data_t:: Simply linked list Gnuastro's generic datatype.
FITS files (@file{fits.h})
@@ -16437,14 +16440,13 @@ place of @code{PREFIX}). Also copy the comments to
help readability later.
# SOURCE: the name of the `.c' source file without the `.c', for
# example, for `myprog.c', SOURCE would be `myprog'.
#
-# ARGUMENTS: any arguments to run the program with after
+# ARGUMENTS: [optional] any arguments to run the program with after
# compilation. If there are multiple arguments, put them in
-# double quotes, for example "img1.fits img2.fits". This is
-# optional.
+# double quotes, for example "img1.fits img2.fits".
#
-# OTHER-LIBRARIES: If your program depends on any libraries other
-# than Gnuastro's dependencies. For example if it needs libfirst
-# and libsecond, use "-lfirst -lsecond". This is optional.
+# OTHER-LIBRARIES: [optional] if your program depends on any
+# libraries other than Gnuastro's dependencies. For example
+# if it needs libfirst and libsecond, use "-lfirst -lsecond".
#
# When there are no arguments and no libraries other than Gnuastro's
# dependencies, you can simply run this command (when your source is
@@ -16548,16 +16550,16 @@ documentation will correspond to your installed
version.
@menu
* Configuration information:: General information about library config.
-* Library data types::
-* Library blank values::
-* Library data container::
+* Library data types:: Definitions and functions for types in
Gnuastro.
+* Library blank values:: Blank values and functions to deal with them.
+* Library data container:: General data container in Gnuastro.
* Linked lists:: Various types of linked lists.
-* Table input output::
-* Arithmetic on datasets::
-* Tessellation library::
+* Table input output:: Reading and writing table columns.
+* Arithmetic on datasets:: Arithmetic operations on a dataset.
+* Tessellation library:: Functions for working on tiles.
* Bounding box:: Finding the bounding box.
* FITS files:: Working with FITS data.
-* Text files::
+* Text files:: Functions to work on Text files.
* Git wrappers:: Wrappers for functions in libgit2.
* Polygons:: Working with the vertices of a polygon.
* Qsort functions:: Helper functions for Qsort.
@@ -16655,8 +16657,219 @@ header.
@node Library data types, Library blank values, Configuration information,
Gnuastro library
@subsection Library data types (@file{type.h})
-This header defines basic type identifiers and functions relating to the
-different types.
+Data in astronomy can have many types, numeric (numbers) and strings
+(names, identifiers). The former can also be divided into integers and
+floats, see @ref{Numeric data types} for a thorough discussion of the
+different numeric data types and which one is useful for different
+contexts.
+
+To deal with the very large diversity of types that are available (and used
+in different contexts), in Gnuastro each type is identified with global
+integer variable with a fixed name, this variable is then passed onto
+functions that can work on any type or is stored in Gnuastro's @ref{Generic
+data container} as one piece of meta-data.
+
+The actual values within these integer constants is irrelevant and you
+should never rely on them. When you need to check, explicitly use the named
+variable in the table below. If you want to check with more than one type,
+you can use C's @code{switch} statement.
+
+Since Gnuastro heavily deals with file input-output, the types it defines
+are fixed width types, these types are portable to all systems and are
+defined in the standard C header @file{stdint.h}. You don't need to include
+this header, it is included by any Gnuastro header that deals with the
+different types. However, the most commonly used types in a C (or C++)
+program (for example @code{int} or @code{long} are not defined by their
+exact width (storage), but by their minimum storage. So for example on some
+systems, @code{int} may be 2 bytes (16-bits, the minimum required by the
+standard) and on others it may be 4 bytes (32-bits, common in modern
+systems).
+
+With every type, a unique ``blank'' value (or place holder showing the
+absence of data) can be defined. Please see @ref{Library blank values} for
+constants that Gnuastro recognizes as a blank value for each type. See
address@hidden data types} for more explanation on the limits and particular
+aspects of each type.
+
address@hidden {Global integer} GAL_TYPE_INVALID
+This is just a place holder to specifically mark that no type has been set.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_BIT
+Identifier for a bit-stream. Currently no program in Gnuastro works
+directly on bits, but features will be added in the future.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_UINT8
+Identifier for an unsigned, 8-bit integer type: @code{uint8_t} (from
address@hidden), or an @code{unsigned char} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_INT8
+Identifier for a signed, 8-bit integer type: @code{int8_t} (from
address@hidden), or an @code{signed char} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_UINT16
+Identifier for an unsigned, 16-bit integer type: @code{uint16_t} (from
address@hidden), or an @code{unsigned short} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_INT16
+Identifier for a signed, 16-bit integer type: @code{int16_t} (from
address@hidden), or a @code{short} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_UINT32
+Identifier for an unsigned, 32-bit integer type: @code{uint32_t} (from
address@hidden), or an @code{unsigned int} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_INT32
+Identifier for a signed, 32-bit integer type: @code{int32_t} (from
address@hidden), or an @code{int} in most modern systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_UINT64
+Identifier for an unsigned, 64-bit integer type: @code{uint64_t} (from
address@hidden), or an @code{unsigned long} in most modern 64-bit systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_INT64
+Identifier for a signed, 64-bit integer type: @code{int64_t} (from
address@hidden), or an @code{long} in most modern 64-bit systems.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_SIZE_T
+Identifier for a @code{size_t} type. This is just an alias to
address@hidden, or @code{uint64} types for 32-bit, or 64-bit systems
+respectively.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_FLOAT32
+Identifier for a 32-bit single precision floating point type or
address@hidden in C.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_FLOAT64
+Identifier for a 64-bit double precision floating point type or
address@hidden in C.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_COMPLEX32
+Identifier for a complex number composed of two @code{float} types. Note
+that the complex type is not yet fully implemented in all Gnuastro's
+programs.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_COMPLEX64
+Identifier for a complex number composed of two @code{double} types. Note
+that the complex type is not yet fully implemented in all Gnuastro's
+programs.
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_STRING
+Identifier for a string of characters (@code{char *}).
address@hidden deffn
+
address@hidden {Global integer} GAL_TYPE_STRLL
+Identifier for a linked list of string of characters
+(@code{gal_list_str_t}, see @ref{List of strings}).
address@hidden deffn
+
address@hidden
+The functions below are defined to make working with the integer constants
+above easier. In the functions below, the constants above can be used for
+the @code{type} input argument.
+
address@hidden size_t gal_type_sizeof (uint8_t @code{type})
+Return the number of bytes occurpied by @code{type}. Internally, this
+function uses C's @code{sizeof} operator to measure the size of each type.
address@hidden deftypefun
+
address@hidden {char *} gal_type_to_string (uint8_t @code{type}, int
@code{long_name})
+Return a string that contains the name of the type. This can be used in
+messages to the users when your function/program accepts many types. It can
+return two types of string identifiers (short like @code{f32} or long like
address@hidden). The output string is statically allocated, so it should
+not be freed. The strings it will return for each type are the identifiers
+of the types in @ref{Numeric data types}.
address@hidden deftypefun
+
address@hidden uint8_t gal_type_from_string (char @code{*str})
+Return the Gnuastro integer constant that corresponds to the string
address@hidden This is effectively the inverse of the
address@hidden function and accepts both the short and long
+formats of each type.
address@hidden deftypefun
+
address@hidden void gal_type_min (uint8_t @code{type}, void @code{*in})
+Put the minimum possible value of @code{type} in the space pointed to by
address@hidden Since the value can have any type, this function doesn't return
+anything, it assumes the space for the given type is available to @code{in}
+and writes the value there. Here is one example
address@hidden
+int32_t min;
+gal_type_min(GAL_TYPE_INT32, &min);
address@hidden example
+
address@hidden
+Note: Do not use the minimum value for a blank value of a general
+(initially unknown) type, please use the constants/functions provided in
address@hidden blank values} for the definition and usage of blank values.
address@hidden deftypefun
+
address@hidden void gal_type_max (uint8_t @code{type}, void @code{*in})
+Put the maximum possible value of @code{type} in the space pointed to by
address@hidden Since the value can have any type, this function doesn't return
+anything, it assumes the space for the given type is available to @code{in}
+and writes the value there. Here is one example
address@hidden
+uint16_t max;
+gal_type_max(GAL_TYPE_INT16, &max);
address@hidden example
+
address@hidden
+Note: Do not use the maximum value for a blank value of a general
+(initially unknown) type, please use the constants/functions provided in
address@hidden blank values} for the definition and usage of blank values.
address@hidden deftypefun
+
address@hidden int gal_type_is_linked_list (uint8_t @code{type})
+Return 1 if the type is a linked list and zero otherwise.
address@hidden deftypefun
+
address@hidden int gal_type_out (int @code{first_type}, int @code{second_type})
+Return the larger of the two given types which can be used for the type of
+the output of an operation involving the two input types.
address@hidden deftypefun
+
address@hidden {char *} gal_type_bit_string (void @code{*in}, size_t
@code{size})
+Return the bit-string in the @code{size} bytes that @code{in} points
+to. The string is dynamically allocated and must be freed afterwards. You
+can use it to inspect the bits within one region of memory. Here is one
+short example:
+
address@hidden
+int32_t a=2017;
+char *bitstr=gal_type_bit_string(&a, 4);
+printf("%d: %s (%X)\n", a, bitstr, a);
+free(bitstr);
address@hidden example
+
address@hidden
+It will produce:
address@hidden
+2017: 11100001000001110000000000000000 (7E1)
address@hidden example
+
+As the example above shows, the bit-string is not the most efficient way to
+inspect bits. If you are familiar with hexademical notation, it is much
+more compact, see @url{https://en.wikipedia.org/wiki/Hexadecimal}. You can
+use @code{printf}'s @code{%x} or @code{%X} to print integers in hexadecimal
+format.
address@hidden deftypefun
+
@node Library blank values, Library data container, Library data types,
Gnuastro library
@subsection Library blank values (@file{blank.h})
@@ -16665,9 +16878,10 @@ pixel in an image), a place-holder is necessary for
the element if we don't
have a value to fill it with (for example the CCD cannot read those
pixels). We cannot simply shift all the other pixels to fill in the one we
have no value for. In other cases, it often occurs that the field of sky
-that you are studying is not a clean rectangle. You need a way to separate
-the pixels outside your scientific field from those inside it. Blank values
-are these place holders.
+that you are studying is not a clean rectangle to nicely fit into the
+boundaries of an image. You need a way to separate the pixels outside your
+scientific field from those inside it. Blank values act as these place
+holders in a dataset. They have no usable value but they have a position.
@cindex NaN
Every type needs a corresponding blank value (see @ref{Numeric data types}
@@ -16679,9 +16893,139 @@ the given type: for signed types (that allow
negatives), the minimum
possible value is used as blank and for unsigned types (that only accept
positives), the maximum possible value is used. To be generic and easy to
read/write we define a macro for these blank values and strongly encourage
-you tonly use these. Never make any assumption on the value of a type's
+you only use these, and never make any assumption on the value of a type's
blank value.
address@hidden NaN
+The IEEE NaN blank value type is defined to fail on any comparison, so if
+you are dealing with floating point types, you cannot use equality (a NaN
+will @emph{not} be equal to a NaN). If you know your dataset if floating
+point, you can use the @code{isnan} function in C's @file{math.h}
+header. For a description of numeric data types see @ref{Numeric data
+types}. For the constants identifying integers, please see @ref{Library
+data types}.
+
address@hidden {Global integer} GAL_BLANK_UINT8
+Blank value for an unsigned, 8-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_INT8
+Blank value for a signed, 8-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_UINT16
+Blank value for an unsigned, 16-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_INT16
+Blank value for a signed, 16-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_UINT32
+Blank value for an unsigned, 32-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_INT32
+Blank value for a signed, 32-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_UINT64
+Blank value for an unsigned, 64-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_INT64
+Blank value for a signed, 64-bit integer.
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_SIZE_T
+Blank value for @code{size_t} type (@code{uint32_t} or @code{uint64_t} in
+32-bit or 64-bit systems).
address@hidden deffn
+
address@hidden NaN
address@hidden {Global integer} GAL_BLANK_FLOAT32
+Blank value for a single precision, 32-bit floating point type (IEEE NaN
+value).
address@hidden deffn
+
address@hidden NaN
address@hidden {Global integer} GAL_BLANK_FLOAT64
+Blank value for a double precision, 64-bit floating point type (IEEE NaN
+value).
address@hidden deffn
+
address@hidden {Global integer} GAL_BLANK_STRING
+Blank value for string types (this is itsself a string, it isn't the
address@hidden pointer).
address@hidden deffn
+
address@hidden
+The functions below can be used to work with blank pixels.
+
address@hidden void gal_blank_write (void @code{*pointer}, uint8_t @code{type})
+Write the blank value for the given @code{type} into the space that
address@hidden points to. This can be used when the space is already
+allocated (for example one element in an array or a statically allocated
+variable).
address@hidden deftypefun
+
address@hidden {void *} gal_blank_alloc_write (uint8_t @code{type})
+Allocate the space required to keep the blank for the given data type
address@hidden, write the blank value into it and return the pointer to it.
address@hidden deftypefun
+
address@hidden void gal_blank_initialize (gal_data_t @code{*input})
+Initialize all the elements in the @code{input} dataset to the blank value
+that corresponds to its type. If @code{input} is a tile over a larger
+dataset, only the region that the tile covers will be set to blank.
address@hidden deftypefun
+
+
address@hidden int gal_blank_present (gal_data_t @code{*input}, int
@code{updateflag})
+Return 1 if the dataset has a blank value and zero if it doesn't. Before
+checking the dataset, this function will look at @code{input}'s flags. If
+the @code{GAL_DATA_FLAG_HASBLANK} or @code{GAL_DATA_FLAG_DONT_CHECK_ZERO}
+bits of @code{input->flag} are set to 1, this function will not do any
+check and will just use the information in the flags. This can greatly
+speed up processing when a dataset needs to be checked multiple times.
+
+If you want to re-check a dataset which has non-zero flags, then explicitly
+set the appropriate flag to zero before calling this function. When there
+are no other flags, you can just set @code{input->flags} to zero, otherwise
+you can use this expression:
+
address@hidden
+input->flags &= ~(GAL_DATA_FLAG_HASBLANK | GAL_DATA_FLAG_USE_ZERO);
address@hidden example
+
+When @code{updateflags} is zero, this function has no side-effects on the
+dataset: it will not toggle the flags. When the dataset's flags were not
+used and @code{updateflags} is non-zero, this function will set the flags
+appropriately to avoid having to re-check the dataset in future calls.
address@hidden deftypefun
+
+
address@hidden {gal_data_t *} gal_blank_flag (gal_data_t @code{*input})
+Create a dataset of the the same size as the input, but with an
address@hidden type that has a value of 1 for data that are blank and 0 for
+those that aren't.
address@hidden deftypefun
+
+
address@hidden void gal_blank_remove (gal_data_t @code{*input})
+Remove blank elements from a dataset, convert it to a 1D dataset, and
+adjust the size properly (the number of non-blank elements). In practice
+this function doesn't @code{realloc} the input array, it just shifts the
+blank elements to the end and adjusts the size elements of the
address@hidden, see @ref{Generic data container}.
address@hidden deftypefun
+
address@hidden {char *} gal_blank_as_string (uint8_t @code{type}, int
@code{width})
+Write the blank value for the given data type @code{type} into a string and
+return it. The space for the string is dynamically allocated so it must be
+freed after you are done with it.
address@hidden deftypefun
+
@node Library data container, Linked lists, Library blank values, Gnuastro
library
@subsection Data container (@file{data.h})
@@ -17259,12 +17603,15 @@ structure. All these structures and functions are
defined and declared in
@menu
-* List of strings::
-* List of int32_t::
-* List of size_t::
-* Ordered list of size_t::
-* Two way list of ordered size_t::
-* List of gal_data_t::
+* List of strings:: Simply linked list of strings.
+* List of int32_t:: Simply linked list of int32_ts.
+* List of size_t:: Simply linked list of size_ts.
+* List of float:: Simply linked list of floats.
+* List of double:: Simply linked list of doubles
+* List of void:: Simply linked list of void * pointers.
+* Ordered list of size_t:: Simply linked, ordered list of size_t.
+* Doubly linked ordered list of size_t:: Definition and functions.
+* List of gal_data_t:: Simply linked list Gnuastro's generic datatype.
@end menu
@node List of strings, List of int32_t, Linked lists, Linked lists
@@ -17297,7 +17644,7 @@ remain. Here is one short/simple example of
initializing and adding
elements to a string list:
@example
-gal_list_str_t *strlist=NULL;
+gal_list_str_t *strlist;
gal_list_str_add(&strlist, "bottom of list.");
gal_list_str_add(&strlist, "second last element of list.");
@end example
@@ -17324,7 +17671,7 @@ more user-friendly, format. For example the following
code snippet.
@example
size_t i;
-gal_list_str_t *tmp=NULL;
+gal_list_str_t *tmp;
for(tmp=list; tmp!=NULL; tmp=tmp->next)
printf("String %zu: %s\n", i, tmp->v);
@end example
@@ -17336,7 +17683,7 @@ calling this function becomes the bottom node after it.
@end deftypefun
@deftypefun void gal_list_str_free (gal_list_str_t @code{*list}, int
@code{freevalue})
-Free each node in @code{list}. If @code{freevalue} is not zero, also free
+Free every node in @code{list}. If @code{freevalue} is not zero, also free
the string within the nodes.
@end deftypefun
@@ -17349,25 +17696,28 @@ the string within the nodes.
Signed integers are the best types when you are dealing with a positive or
negative integers. The are generally useful in many contexts, for example
when you want to keep the order of a series of states (each state stored as
-a given number in an @code{enum} for example).
+a given number in an @code{enum} for example). On many modern systems,
address@hidden is just an alias for @code{int}, so you can use them
+interchably. To make sure, check the size of @code{int} on your system:
@deftp {Type (C @code{struct})} gal_list_i32_t
-A single node in a list containing a 32-bit signed integers (see
+A single node in a list containing a 32-bit signed integer (see
@ref{Numeric data types}).
@example
typedef struct gal_list_i32_t
@{
- int32_t *v;
+ int32_t v;
struct gal_list_i32_t *next;
@} gal_list_i32_t;
@end example
@end deftp
address@hidden void gal_list_i32_add (gal_list_i32_t @code{**list}, int32_t
@code{*value})
-Add a new node (containing @code{value}) to the list of integers
-(@code{list}) and update it. Here is one short example of initializing and
-adding elements to a string list:
address@hidden void gal_list_i32_add (gal_list_i32_t @code{**list}, int32_t
@code{value})
+Add a new node (containing @code{value}) to the top of the @code{list} of
address@hidden (@code{uint32_t} is equal to @code{int} on many modern
+systems), and update @code{list}. Here is one short example of initializing
+and adding elements to a string list:
@example
gal_list_i32_t *i32list=NULL;
@@ -17399,7 +17749,7 @@ context of your program.
@example
size_t i;
-gal_list_i32_t *tmp=NULL;
+gal_list_i32_t *tmp;
for(tmp=list; tmp!=NULL; tmp=tmp->next)
printf("String %zu: %s\n", i, tmp->v);
@end example
@@ -17410,13 +17760,26 @@ Reverse the order of the list such that the top node
in the list before
calling this function becomes the bottom node after it.
@end deftypefun
address@hidden {int32_t *} gal_list_i32_to_array (gal_list_i32_t @code{*list},
int @code{reverse}, size_t @code{*num})
+Dynamically allocate an array and fill it with the values in
address@hidden The function will return a pointer to the allocated array and
+put the number of elements in the array into the @code{num} pointer. If
address@hidden has a non-zero value, the array will be filled in the
+opposite order of elements in @code{list}. This function can be
+useful after you have finished reading an initially unknown number of
+values and want to put them in an array for easy random access.
address@hidden deftypefun
+
@deftypefun void gal_list_i32_free (gal_list_i32_t @code{*list})
-Free each node in @code{list}.
+Free every node in @code{list}.
@end deftypefun
address@hidden List of size_t, Ordered list of size_t, List of int32_t, Linked
lists
+
+
+
address@hidden List of size_t, List of float, List of int32_t, Linked lists
@subsubsection List of @code{size_t}
The @code{size_t} type is a unique type in C: as the name suggests it is
@@ -17434,26 +17797,28 @@ system's (virtual) memory and since its name has the
word ``size'' inside
it, it provides a good level of address@hidden you know that a
variable of this type is not used to store some generic state for
example.}. In Gnuastro, we do all counting and array indexing with this
-type, so this list is very handy.
+type, so this list is very handy. As discussed above, @code{size_t} maps to
+different types on different machines, so a portable way to print them with
address@hidden is to use C99's @code{%zu} format.
@deftp {Type (C @code{struct})} gal_list_sizet_t
-A single node in a list containing a @code{size_t} values: either
address@hidden or @code{uint64_t} depending on the host system, see
+A single node in a list containing a @code{size_t} value (which maps to
address@hidden or @code{uint64_t} on 32-bit and 64-bit systems), see
@ref{Numeric data types}.
@example
typedef struct gal_list_sizet_t
@{
- size_t *v;
+ size_t v;
struct gal_list_sizet_t *next;
@} gal_list_sizet_t;
@end example
@end deftp
address@hidden void gal_list_sizet_add (gal_list_sizet_t @code{**list}, size_t
@code{*value})
-Add a new node (containing @code{value}) to the list of @code{size_t}s
-(@code{list}) and update it. Here is one short example of initializing and
-adding elements to a string list:
address@hidden void gal_list_sizet_add (gal_list_sizet_t @code{**list}, size_t
@code{value})
+Add a new node (containing @code{value}) to the top of the @code{list} of
address@hidden and update @code{list}. Here is one short example of
+initializing and adding elements to a string list:
@example
gal_list_sizet_t *slist=NULL;
@@ -17485,7 +17850,7 @@ context of your program.
@example
size_t i;
-gal_list_sizet_t *tmp=NULL;
+gal_list_sizet_t *tmp;
for(tmp=list; tmp!=NULL; tmp=tmp->next)
printf("String %zu: %zu\n", i, tmp->v);
@end example
@@ -17496,62 +17861,331 @@ Reverse the order of the list such that the top node
in the list before
calling this function becomes the bottom node after it.
@end deftypefun
address@hidden {size_t *} gal_list_sizet_to_array (gal_list_sizet_t
@code{*list}, int @code{reverse}, size_t @code{*num})
+Dynamically allocate an array and fill it with the values in
address@hidden The function will return a pointer to the allocated array and
+put the number of elements in the array into the @code{num} pointer. If
address@hidden has a non-zero value, the array will be filled in the
+inverse of the order of elements in @code{list}. This function can be
+useful after you have finished reading an initially unknown number of
+values and want to put them in an array for easy random access.
address@hidden deftypefun
+
@deftypefun void gal_list_sizet_free (gal_list_sizet_t @code{*list})
-Free each node in @code{list}.
+Free every node in @code{list}.
@end deftypefun
address@hidden List of float, List of double, List of size_t, Linked lists
address@hidden List of @code{float}
+
+Single precision floating point numbers can accurately store real number
+until 7.2 decimals and only consume 4 bytes (32-bits) of memory, see
address@hidden data types}. Since astronomical data rarely reach that level
+of precision, single precision floating points are the type of choice to
+keep and read data. However, when processing the data, it is best to use
+double precision floating points (since errors propagate).
address@hidden {Type (C @code{struct})} gal_list_f32_t
+A single node in a list containing a 32-bit single precision @code{float}
+value: see @ref{Numeric data types}.
address@hidden
+typedef struct gal_list_f32_t
address@hidden
+ float v;
+ struct gal_list_f32_t *next;
address@hidden gal_list_f32_t;
address@hidden example
address@hidden deftp
address@hidden Ordered list of size_t, Two way list of ordered size_t, List of
size_t, Linked lists
address@hidden Ordered list of size_t
address@hidden void gal_list_f32_add (gal_list_f32_t @code{**list}, float
@code{value})
+Add a new node (containing @code{value}) to the top of the @code{list} of
address@hidden and update @code{list}. Here is one short example of
+initializing and adding elements to a string list:
address@hidden Structure gal_linkedlist_osll
address@hidden
+gal_list_f32_t *flist=NULL;
+gal_list_f32_add(&flist, 3.89);
+gal_list_f32_add(&flist, 1.23e-20);
address@hidden example
+
address@hidden deftypefun
+
address@hidden {float} gal_list_f32_pop (gal_list_f32_t @code{**list})
+Pop the top element of @code{list} and return the value. This function will
+also change @code{list} to point to the next node in the list. If
address@hidden, then this function will return @code{GAL_BLANK_FLOAT32}
+(NaN, see @ref{Library blank values}).
address@hidden deftypefun
+
address@hidden size_t gal_list_f32_number (gal_list_f32_t @code{*list})
+Return the number of nodes in @code{list}.
address@hidden deftypefun
+
address@hidden void gal_list_f32_print (gal_list_f32_t @code{*list})
+Print the values within each node of @code{*list} on the standard output in
+the same order that they are stored. Each floating point number is printed
+on one line. This function is mainly good for checking/debugging your
+program. For program outputs, its best to make your own implementation with
+a better, more user-friendly format. For example, in the following code
+snippet. You can also modify it to print all values in one line, and etc,
+depending on the context of your program.
+
address@hidden
+size_t i;
+gal_list_f32_t *tmp;
+for(tmp=list; tmp!=NULL; tmp=tmp->next)
+ printf("Node %zu: %f\n", i, tmp->v);
address@hidden example
address@hidden deftypefun
+
address@hidden void gal_list_f32_reverse (gal_list_f32_t @code{**list})
+Reverse the order of the list such that the top node in the list before
+calling this function becomes the bottom node after it.
address@hidden deftypefun
+
address@hidden {float *} gal_list_f32_to_array (gal_list_f32_t @code{*list},
int @code{reverse}, size_t @code{*num})
+Dynamically allocate an array and fill it with the values in
address@hidden The function will return a pointer to the allocated array and
+put the number of elements in the array into the @code{num} pointer. If
address@hidden has a non-zero value, the array will be filled in the
+inverse of the order of elements in @code{list}. This function can be
+useful after you have finished reading an initially unknown number of
+values and want to put them in an array for easy random access.
address@hidden deftypefun
+
address@hidden void gal_list_f32_free (gal_list_f32_t @code{*list})
+Free every node in @code{list}.
address@hidden deftypefun
+
+
+
+
address@hidden List of double, List of void, List of float, Linked lists
address@hidden List of @code{double}
+
+Double precision floating point numbers can accurately store real number
+until 15.9 decimals and consume 8 bytes (64-bits) of memory, see
address@hidden data types}. This level of precision makes them very good for
+serious processing in the middle of a program's execution: in many cases,
+the propagation of errors will still be insignificant compared to actual
+obervational errors in a data set. But since they consume 8 bytes and more
+CPU processing power, they are often not the best choice for storing and
+transferring of data.
+
address@hidden {Type (C @code{struct})} gal_list_f64_t
+A single node in a list containing a 64-bit double precision @code{double}
+value: see @ref{Numeric data types}.
address@hidden
+typedef struct gal_list_f64_t
address@hidden
+ double v;
+ struct gal_list_f64_t *next;
address@hidden gal_list_f64_t;
address@hidden example
address@hidden deftp
+
+
address@hidden void gal_list_f64_add (gal_list_f64_t @code{**list}, double
@code{value})
+Add a new node (containing @code{value}) to the top of the @code{list} of
address@hidden and update @code{list}. Here is one short example of
+initializing and adding elements to a string list:
+
address@hidden
+gal_list_f64_t *dlist=NULL;
+gal_list_f64_add(&dlist, 3.8129395763193);
+gal_list_f64_add(&dlist, 1.239378923931e-20);
address@hidden example
+
address@hidden deftypefun
+
address@hidden {double} gal_list_f64_pop (gal_list_f64_t @code{**list})
+Pop the top element of @code{list} and return the value. This function will
+also change @code{list} to point to the next node in the list. If
address@hidden, then this function will return @code{GAL_BLANK_FLOAT64}
+(NaN, see @ref{Library blank values}).
address@hidden deftypefun
+
address@hidden size_t gal_list_f64_number (gal_list_f64_t @code{*list})
+Return the number of nodes in @code{list}.
address@hidden deftypefun
+
address@hidden void gal_list_f64_print (gal_list_f64_t @code{*list})
+Print the values within each node of @code{*list} on the standard output in
+the same order that they are stored. Each floating point number is printed
+on one line. This function is mainly good for checking/debugging your
+program. For program outputs, its best to make your own implementation with
+a better, more user-friendly format. For example, in the following code
+snippet. You can also modify it to print all values in one line, and etc,
+depending on the context of your program.
+
address@hidden
+size_t i;
+gal_list_f64_t *tmp;
+for(tmp=list; tmp!=NULL; tmp=tmp->next)
+ printf("Node %zu: %f\n", i, tmp->v);
address@hidden example
address@hidden deftypefun
+
address@hidden void gal_list_f64_reverse (gal_list_f64_t @code{**list})
+Reverse the order of the list such that the top node in the list before
+calling this function becomes the bottom node after it.
address@hidden deftypefun
+
address@hidden {double *} gal_list_f64_to_array (gal_list_f64_t @code{*list},
int @code{reverse}, size_t @code{*num})
+Dynamically allocate an array and fill it with the values in
address@hidden The function will return a pointer to the allocated array and
+put the number of elements in the array into the @code{num} pointer. If
address@hidden has a non-zero value, the array will be filled in the
+inverse of the order of elements in @code{list}. This function can be
+useful after you have finished reading an initially unknown number of
+values and want to put them in an array for easy random access.
address@hidden deftypefun
+
address@hidden void gal_list_f64_free (gal_list_f64_t @code{*list})
+Free every node in @code{list}.
address@hidden deftypefun
+
+
+
+
address@hidden List of void, Ordered list of size_t, List of double, Linked
lists
address@hidden List of @code{void *}
+
+In C, @code{void *} is the most generic pointer. Usually pointers are
+associated with the type of content they point to. For example @code{int *}
+means a pointer to an integer. This ancillary information about the
+contents of the memory location is very useful for the compiler, catching
+bad errors and also documentation (it helps the reader see what the address
+in memory actually contains). However, @code{void *} is just a raw address
+(pointer), it contains no information on the contents it points to.
+
+These properties make the @code{void *} very useful when you want to treat
+the contents of an address in differnt ways. You can use the @code{void *}
+list defined in this section and its function on any kind of data: for
+example you can use it to keep a list of custom data structures that you
+have built for your own separate program. Each node in the list can keep
+anything and this gives you great versatily. But in using @code{void *},
+please beware that ``with great power comes great responsibilty''.
+
+
address@hidden {Type (C @code{struct})} gal_list_void_t
+A single node in a list containing a @code{void *} pointer.
address@hidden
+typedef struct gal_list_void_t
address@hidden
+ void *v;
+ struct gal_list_void_t *next;
address@hidden gal_list_void_t;
address@hidden example
address@hidden deftp
+
+
address@hidden void gal_list_void_add (gal_list_void_t @code{**list}, void
@code{*value})
+Add a new node (containing @code{value}) to the top of the @code{list} of
address@hidden *}s and update @code{list}. Here is one short example of
+initializing and adding elements to a string list:
+
address@hidden
+gal_list_void_t *vlist=NULL;
+gal_list_f64_add(&vlist, some_pointer);
+gal_list_f64_add(&vlist, another_pointer);
address@hidden example
+
address@hidden deftypefun
+
address@hidden {void *} gal_list_void_pop (gal_list_void_t @code{**list})
+Pop the top element of @code{list} and return the value. This function will
+also change @code{list} to point to the next node in the list. If
address@hidden, then this function will return @code{NULL}.
address@hidden deftypefun
+
address@hidden size_t gal_list_void_number (gal_list_void_t @code{*list})
+Return the number of nodes in @code{list}.
address@hidden deftypefun
+
address@hidden void gal_list_void_reverse (gal_list_void_t @code{**list})
+Reverse the order of the list such that the top node in the list before
+calling this function becomes the bottom node after it.
address@hidden deftypefun
+
address@hidden void gal_list_void_free (gal_list_void_t @code{*list})
+Free every node in @code{list}.
address@hidden deftypefun
+
+
address@hidden Ordered list of size_t, Doubly linked ordered list of size_t,
List of void, Linked lists
address@hidden Ordered list of @code{size_t}
+
+Positions/sizes in a dataset are conventionally in the @code{size_t} type
+(see @ref{List of size_t}) and it sometimes occurs that you want to parse
+and read the values in a specific order. For example you want to start from
+one pixel and add pixels to the list based on their distance to that
+pixel. So that ever time you pop an element from the list, you know it is
+the nearest that has not yet been studied. The @code{gal_list_osizet_t}
+type and its functions in this section are designed to facilitate such
+operations.
+
address@hidden {Type (C @code{struct})} gal_list_osizet_t
@cindex @code{size_t}
-Ordered @code{size_t} linked list (@code{osll}. Each node in this
-singly-linked list contains a @code{size_t} value and a floating point
-value. The floating point value is used as a reference to add new nodes in
-a sorted manner. At any moment, the first popped node in this list will
-have the smallest @code{tosort} value, and subsequent nodes will have
-larger to values.
+Each node in this singly-linked list contains a @code{size_t} value and a
+floating point value. The floating point value is used as a reference to
+add new nodes in a sorted manner. At any moment, the first popped node in
+this list will have the smallest @code{tosort} value, and subsequent nodes
+will have larger to values.
@end deftp
@example
-struct gal_linkedlist_osll
+typedef struct gal_list_osizet_t
@{
- size_t v;
- float s;
- struct gal_linkedlist_osll *next;
address@hidden;
+ size_t v; /* The actual value. */
+ float s; /* The parameter to sort by. */
+ struct gal_list_osizet_t *next;
address@hidden gal_list_osizet_t;
@end example
address@hidden void gal_linkedlist_add_to_osll (struct gal_linkedlist_osll
@code{**list}, size_t @code{value}, float @code{tosort})
-Allocate space for a new node in @code{list}, and store @code{value} into
-it. The new node will be added to the list based on the @code{tosort}
-value.
address@hidden void gal_list_osizet_add (gal_list_osizet_t @code{**list},
size_t @code{value}, float @code{tosort})
+Allocate space for a new node in @code{list}, and store @code{value} and
address@hidden into it. The new node will not necessarily be at the ``top''
+of the list. If @code{*list!=NULL}, then the @code{tosort} values of
+existing nodes is inspected and the given node is placed in the list such
+that the top element (which is popped with @code{gal_list_osizet_pop}) has
+the smallest @code{tosort} value.
@end deftypefun
address@hidden void gal_linkedlist_pop_from_osll (struct gal_linkedlist_osll
@code{**list}, size_t @code{*value}, float @code{*sortvalue})
-Pop a node from the top of @code{list}, put its value in @code{value} and
-its sort value in @code{sortvalue}. This function will also free the
-allocated space for the popped node and after this function, @code{list}
-will point to the next node (which has a larger @code{tosort} element).
address@hidden size_t gal_list_osizet_pop (gal_list_osizet_t @code{**list},
float @code{*sortvalue})
+Pop a node from the top of @code{list}, return the node's @code{value} and
+put its sort value in the space that @code{sortvalue} points to. This
+function will also free the allocated space for the popped node and after
+this function, @code{list} will point to the next node (which has a larger
address@hidden element).
@end deftypefun
address@hidden void gal_linkedlist_osll_into_sll (struct gal_linkedlist_osll
@code{*in}, struct gal_linkedlist_sll @code{**out})
-Convert the orderd @code{size_t} linked list into an ordinary @code{size_t}
-linked list (no longer sorted). This can be useful when all the elements
-have been added and you just need to pop-out elements.
address@hidden void gal_list_osizet_to_sizet_free (gal_list_osizet_t
@code{*in}, gal_list_sizet_t @code{**out})
+Convert the orderd list of @code{size_t}s into an ordinary @code{size_t}
+linked list. This can be useful when all the elements have been added and
+you just need to pop-out elements and don't care about the sorting values
+any more. After the conversion is done, this function will free the input
+list. Note that the @code{out} list doesn't have to be empty. If it already
+contains some nodes, the new nodes will be added ontop of them.
@end deftypefun
address@hidden Two way list of ordered size_t, List of gal_data_t, Ordered list
of size_t, Linked lists
address@hidden Two way list of ordered @code{size_t}
address@hidden Structure gal_linkedlist_tosll
address@hidden Doubly linked ordered list of size_t, List of gal_data_t,
Ordered list of size_t, Linked lists
address@hidden Doubly linked ordered list of @code{size_t}
+
+An ordered list of indexs is required in many contexts, one example was
+discussed at the beginning of @ref{Ordered list of size_t}. But the list
+that was introduced there only has one point of entry: you can always only
+parse the list from smallest to largest. In this section, the doubly-linked
address@hidden node is defined which will allow us to parse the
+values in ascending or descending order.
+
address@hidden {Type (C @code{struct})} gal_list_dosizet_t
@cindex @code{size_t}
-Two-way, ordered @code{size_t} linked list (@code{tosll}. Each node in this
+Doubly-linked, ordered @code{size_t} list node structure. Each node in this
Doubly-linked list contains a @code{size_t} value and a floating point
value. The floating point value is used as a reference to add new nodes in
a sorted manner. In the functions here, this linked list can be pointed to
@@ -17563,149 +18197,105 @@ by two pointers (largest and smallest) with the
following format:
|
smallest pointer
@end example
-At any moment, the two pointers will point the nodes containing the
+At any moment, the two pointers will point to the nodes containing the
``largest'' and ``smallest'' values and the rest of the nodes will be
sorted. This is useful when an unknown number of nodes are being added
continuously and during the operations it is important to have the nodes in
a sorted format.
address@hidden deftp
+
@example
-struct gal_linkedlist_tosll
+typedef struct gal_list_dosizet_t
@{
- size_t v;
- float s;
- struct gal_linkedlist_tosll *prev;
- struct gal_linkedlist_tosll *next;
address@hidden;
+ size_t v; /* The actual value. */
+ float s; /* The parameter to sort by. */
+ struct gal_list_dosizet_t *prev;
+ struct gal_list_dosizet_t *next;
address@hidden gal_list_dosizet_t;
@end example
address@hidden deftp
address@hidden void gal_linkedlist_print_tosll (struct gal_linkedlist_tosll
@code{*largest}, struct gal_linkedlist_tosll @code{*smallest})
-Print all the values within the linked list to the output terminal. This
-can be used for inspecting the status of the list during development.
address@hidden deftypefun
-
address@hidden void gal_linkedlist_add_to_tosll_end (struct
gal_linkedlist_tosll @code{**largest}, struct gal_linkedlist_tosll
@code{**smallest}, size_t @code{value}, float @code{tosort})
-Allocate space for a new node in @code{list}, and store @code{value} into
-it. The new node will be added to the list based on the @code{s} value as
-described in the description of @code{gal_linkedlist_tosll}. If this is the
-first node to be added to the list, both the @code{largest} and
address@hidden pointers can be @code{NULL}.
address@hidden void gal_list_dosizet_add (gal_list_dosizet_t @code{**largest},
gal_list_dosizet_t @code{**smallest}, size_t @code{value}, float @code{tosort})
+Allocate space for a new node in @code{list}, and store @code{value} and
address@hidden into it. If the list is empty, both @code{largest} and
address@hidden must be @code{NULL}.
@end deftypefun
address@hidden void gal_linkedlist_pop_from_tosll_start (struct
gal_linkedlist_tosll @code{**lartest}, struct gal_linkedlist_tosll
@code{**smallest}, size_t @code{*value}, float @code{*tosort})
-Pop the node with the smallest @code{s} of @code{list}, then put its value
-in @code{value} and its sort value in @code{sortvalue}. This function will
-also free the allocated space for the popped node and after this function,
address@hidden and @code{smallest} will be modified respectively. Note that
address@hidden size_t gal_list_dosizet_pop_smallest (gal_list_dosizet_t
@code{**largest}, gal_list_dosizet_t @code{**smallest}, float @code{tosort})
+Pop the value with the smallest reference from the doubly linked list and
+store the reference into the space pointed to by @code{tosort}. Note that
even though only the smallest pointer will be popped, when there was only
one node in the list, the @code{largest} pointer also has to change, so we
need both.
@end deftypefun
address@hidden void gal_linkedlist_smallest_tosll (struct gal_linkedlist_tosll
@code{*largest}, struct gal_linkedlist_tosll @code{**smallest})
-Given the @code{largest} pointer, set @code{smallest} as described in
address@hidden
address@hidden void gal_list_dosizet_print (gal_list_dosizet_t @code{*largest},
gal_list_dosizet_t @code{*smallest})
+Print the largest and smallest values sequentially until the list is
+parsed.
@end deftypefun
address@hidden void gal_linkedlist_tosll_into_sll (struct gal_linkedlist_tosll
@code{*in}, struct gal_linkedlist_sll @code{**out})
-Convert the two-way orderd @code{size_t} linked list into an ordinary
address@hidden linked list (no longer sorted). This can be useful when all
-the elements have been added and you just need to pop-out elements.
address@hidden deftypefun
address@hidden void gal_linkedlist_tosll_free (struct gal_linkedlist_tosll
@code{*largest})
-Free the space for all the nodes in @code{largest}. Note that any values
-within the nodes will also be discarded.
address@hidden void gal_list_dosizet_to_sizet (gal_list_dosizet_t @code{*in},
gal_list_sizet_t @code{**out})
+Convert the doubly linked, ordered @code{size_t} list into a singly-linked
+list of @code{size_t}.
@end deftypefun
address@hidden void gal_list_dosizet_free (gal_list_dosizet_t @code{*largest})
+Free the doubly linked, ordered @code{sizet_t} list.
address@hidden deftypefun
address@hidden List of gal_data_t, , Two way list of ordered size_t, Linked
lists
address@hidden List of gal_data_t, , Doubly linked ordered list of size_t,
Linked lists
@subsubsection List of @code{gal_data_t}
-Linked lists are a programming construct that allow several containers to
-be connected without a-priori knowledge of the number of elements, see
address@hidden://en.wikipedia.org/wiki/Linked_list, Wikipedia}, or @ref{Linked
-lists} for a more thorough discussion. The @code{next} element of
-Gnuastro's generic data container enables each dataset to be treated as a
-node in a simply linked list (see @ref{Generic data container}). This
-higher-level construct offers great versatility in combining multiple
-datasets and treating them as a larger whole.
-
-Tables are one example of the usage of linked lists: each column in a table
-in an independent dataset: with its own name, units, numeric data type (see
address@hidden data types}). The only constraint is on a table column dataset
-is its size: it is one-dimensional and must have the same number of
-elements as the other columns in the table. Another application is in
-Tessellating an input dataset into separate tiles or only studying
-particular regions, or tiles, of a larger dataset (see @ref{Tessellation
-library}). Each independent tile over the dataset can be connected to the
-others as a linked list and thus any number of tiles can be represented
-with one variable.
-
-The space keeping each @code{gal_data_t} node (column/tile in the examples
-above) in the linked list can be allocated once for many nodes as an array,
-when the total number is known a-priori (see @ref{Arrays of datasets}), or
-each dataset can be allocated separately: when the total number isn't
-finalized. In any case, through the @code{next} element, it is possible to
-connect them to define a linked list. The functions here are mainly useful
-in the latter case. There are two important things to keep in mind when
-defining and using simple linked lists:
-
address@hidden
-
address@hidden
-Before adding any nodes to a list, initialize it with a @code{NULL}
-pointer. The @code{NULL} pointer will mark the end/bottom of the list as
-more elements are added ontop of it.
-
address@hidden
-Simple linked lists are a last-in-first-out structure: so the last element
-you add to the top of the list is the first one that is popped out of, or
-read from, the list later. Hence when order matters, you can add the nodes
-to a list, then reverse the list with @code{gal_data_reverse_ll},
-otherwise, you should add them in reverse order from the beginning (which
-is only possible when the total number is known a-priori).
address@hidden itemize
-
-Here is one example of using these functions:
-
+Gnuastro's generic data container has a @code{next} element which enables
+it to be used as a singly-linked list (see @ref{Generic data
+container}). The ability to connect the different data containers offers
+great advantages. For example each column in a table in an independent
+dataset: with its own name, units, numeric data type (see @ref{Numeric data
+types}). Another application is in Tessellating an input dataset into
+separate tiles or only studying particular regions, or tiles, of a larger
+dataset (see @ref{Tessellation} and @ref{Tessellation library}). Each
+independent tile over the dataset can be connected to the others as a
+linked list and thus any number of tiles can be represented with one
+variable.
+
address@hidden void gal_list_data_add (gal_data_t @code{**list}, gal_data_t
@code{*newnode})
+Add an already allocated dataset (@code{newnode}) to top of @code{list}. In
+this example multiple images are linked together as a list:
@example
-gal_data_t *node, *newnode, *list=NULL;
-size_t minmapsize=-1; /* Largest unsigned number: data in RAM. */
-
-newnode=gal_fits_img_read("img1.fits", "1", minmapsize);
-gal_data_add_existing_to_ll(&list, newnode);
-
-newnode=gal_fits_img_read("img2.fits", "1", minmapsize);
-gal_data_add_existing_to_ll(&list, newnode);
-
-... /* Read any more images. */
-
-gal_data_reverse_ll(&list); /* Correct the order. */
-
-for(node=list; node!=NULL; node=node->next) /* Parse the list. */
- @{
- ... /* Do any further processing. */
- @}
-
-gal_data_free_ll(list); /* Clean up. */
-list=NULL; /* To be safe (if the function continues). */
+size_t minmapsize=-1;
+gal_data_t *tmp, *list=NULL;
+tmp = gal_fits_img_read("file1.fits", "1", minmapsize);
+gal_list_data_add( &list, tmp );
+tmp = gal_fits_img_read("file2.fits", "1", minmapsize);
+gal_list_data_add( &list, tmp );
@end example
address@hidden deftypefun
-These functions are declared in @file{gnuastro/data.h} which is also
-visible from the function names (see @ref{Gnuastro library}).
address@hidden void gal_list_data_add_alloc (gal_data_t @code{**list}, void
@code{*array}, uint8_t @code{type}, size_t @code{ndim}, size_t @code{*dsize},
struct wcsprm @code{*wcs}, int @code{clear}, size_t @code{minmapsize}, char
@code{*name}, char @code{*unit}, char @code{*comment})
+Allocate a new dataset (with @code{gal_data_alloc} in @ref{Dataset size and
+allocation}) and put it as the first element of @code{list}. Note that if
+this is the first node to be added to the list, @code{list} must be
address@hidden
address@hidden deftypefun
address@hidden void gal_data_add_existing_to_ll (gal_data_t @code{**list},
gal_data_t @code{*newnode})
-This function will add @code{newnode} to the top of the linked list pointed
-to by @code{*list}. Note that you need to give the pointer to the list,
-since this function will put @code{newnode} at the list's start/top (and
-thus change @code{*list}). Here is one example to read-in a series of
-images:
address@hidden {gal_data_t *} gal_list_data_pop (gal_data_t @code{**list})
+Pop the top node from @code{list} and return it.
@end deftypefun
address@hidden void gal_list_data_reverse (gal_data_t @code{**list})
+Reverse the order of the list such that the top node in the list before
+calling this function becomes the bottom node after it.
address@hidden deftypefun
address@hidden size_t gal_list_data_number (gal_data_t @code{*list})
+Return the number of nodes in @code{list}.
address@hidden deftypefun
address@hidden void gal_list_data_free (gal_data_t @code{*list})
+Free all the datasets in @code{list} along with all the allocated spaces in
+each.
address@hidden deftypefun
@node Table input output, Arithmetic on datasets, Linked lists, Gnuastro
library
diff --git a/lib/blank.c b/lib/blank.c
index 4e01f9d..c7bd893 100644
--- a/lib/blank.c
+++ b/lib/blank.c
@@ -79,18 +79,6 @@ gal_blank_write(void *ptr, uint8_t type)
-/* Initialize (set all the values in the array) with the blank value of the
- given type. */
-void
-gal_blank_initialize(gal_data_t *input)
-{
- GAL_TILE_PARSE_OPERATE({*i=b;}, input, NULL, 0, 0);
-}
-
-
-
-
-
/* Allocate some space for the given type and put the blank value into
it. */
void *
@@ -112,6 +100,18 @@ gal_blank_alloc_write(uint8_t type)
+/* Initialize (set all the values in the array) with the blank value of the
+ given type. */
+void
+gal_blank_initialize(gal_data_t *input)
+{
+ GAL_TILE_PARSE_OPERATE({*i=b;}, input, NULL, 0, 0);
+}
+
+
+
+
+
/* Return 1 if the dataset has a blank value and zero if it doesn't. Before
checking the dataset, this function will look at its flags. If the
`GAL_DATA_FLAG_HASBLANK' or `GAL_DATA_FLAG_DONT_CHECK_ZERO' bits of
diff --git a/lib/gnuastro/blank.h b/lib/gnuastro/blank.h
index db3c7f0..09129de 100644
--- a/lib/gnuastro/blank.h
+++ b/lib/gnuastro/blank.h
@@ -86,12 +86,12 @@ __BEGIN_C_DECLS /* From C++ preparations */
void
gal_blank_write(void *pointer, uint8_t type);
-void
-gal_blank_initialize(gal_data_t *input);
-
void *
gal_blank_alloc_write(uint8_t type);
+void
+gal_blank_initialize(gal_data_t *input);
+
char *
gal_blank_as_string(uint8_t type, int width);
diff --git a/lib/gnuastro/list.h b/lib/gnuastro/list.h
index 1c47cb2..c9a882a 100644
--- a/lib/gnuastro/list.h
+++ b/lib/gnuastro/list.h
@@ -106,7 +106,7 @@ void
gal_list_i32_reverse(gal_list_i32_t **list);
int32_t *
-gal_list_i32_to_array(gal_list_i32_t *list, int inverse, size_t *num);
+gal_list_i32_to_array(gal_list_i32_t *list, int reverse, size_t *num);
void
gal_list_i32_free(gal_list_i32_t *list);
@@ -140,7 +140,7 @@ void
gal_list_sizet_reverse(gal_list_sizet_t **list);
size_t *
-gal_list_sizet_to_array(gal_list_sizet_t *list, int inverse, size_t *num);
+gal_list_sizet_to_array(gal_list_sizet_t *list, int reverse, size_t *num);
void
gal_list_sizet_free(gal_list_sizet_t *list);
@@ -174,7 +174,7 @@ void
gal_list_f32_print(gal_list_f32_t *list);
float *
-gal_list_f32_to_array(gal_list_f32_t *list, int inverse, size_t *num);
+gal_list_f32_to_array(gal_list_f32_t *list, int reverse, size_t *num);
void
gal_list_f32_free(gal_list_f32_t *list);
@@ -208,7 +208,7 @@ void
gal_list_f64_reverse(gal_list_f64_t **list);
double *
-gal_list_f64_to_array(gal_list_f64_t *list, int inverse, size_t *num);
+gal_list_f64_to_array(gal_list_f64_t *list, int reverse, size_t *num);
void
gal_list_f64_free(gal_list_f64_t *list);
@@ -259,9 +259,8 @@ void
gal_list_osizet_add(gal_list_osizet_t **list,
size_t value, float tosort);
-void
-gal_list_osizet_pop(gal_list_osizet_t **list,
- size_t *value, float *sortvalue);
+size_t
+gal_list_osizet_pop(gal_list_osizet_t **list, float *sortvalue);
void
gal_list_osizet_to_sizet_free(gal_list_osizet_t *in,
@@ -272,36 +271,34 @@ gal_list_osizet_to_sizet_free(gal_list_osizet_t *in,
/****************************************************************
- *********** Two way ordered size_t **************
+ *********** Doubly linked, ordered size_t **************
****************************************************************/
-typedef struct gal_list_tosizet_t
+typedef struct gal_list_dosizet_t
{
size_t v; /* The actual value. */
float s; /* The parameter to sort by. */
- struct gal_list_tosizet_t *prev;
- struct gal_list_tosizet_t *next;
-} gal_list_tosizet_t;
+ struct gal_list_dosizet_t *prev;
+ struct gal_list_dosizet_t *next;
+} gal_list_dosizet_t;
void
-gal_list_tosizet_add(gal_list_tosizet_t **largest,
- gal_list_tosizet_t **smallest,
- size_t value, float tosort);
+gal_list_dosizet_add(gal_list_dosizet_t **largest,
+ gal_list_dosizet_t **smallest, size_t value, float
tosort);
-void
-gal_list_tosizet_print(gal_list_tosizet_t *largest,
- gal_list_tosizet_t *smallest);
+size_t
+gal_list_dosizet_pop_smallest(gal_list_dosizet_t **lartest,
+ gal_list_dosizet_t **smallest, float *tosort);
void
-gal_list_tosizet_pop_smallest(gal_list_tosizet_t **lartest,
- gal_list_tosizet_t **smallest,
- size_t *value, float *tosort);
+gal_list_dosizet_print(gal_list_dosizet_t *largest,
+ gal_list_dosizet_t *smallest);
void
-gal_list_tosizet_to_sizet(gal_list_tosizet_t *in,
+gal_list_dosizet_to_sizet(gal_list_dosizet_t *in,
gal_list_sizet_t **out);
void
-gal_list_tosizet_free(gal_list_tosizet_t *largest);
+gal_list_dosizet_free(gal_list_dosizet_t *largest);
diff --git a/lib/interpolate.c b/lib/interpolate.c
index 1565021..479e2a2 100644
--- a/lib/interpolate.c
+++ b/lib/interpolate.c
@@ -88,7 +88,7 @@ interpolate_close_neighbors_on_thread(void *in_prm)
float pdist;
uint8_t *b, *bf, *bb;
gal_list_void_t *tvll;
- gal_list_tosizet_t *lQ, *sQ;
+ gal_list_dosizet_t *lQ, *sQ;
size_t ngb_counter, dist, pind, *dinc;
size_t i, index, fullind, chstart=0, ndim=input->ndim;
gal_data_t *median, *tin, *tout, *tnear, *nearest=NULL;
@@ -184,11 +184,11 @@ interpolate_close_neighbors_on_thread(void *in_prm)
list structure. To start from the nearest and go out to the
farthest. */
lQ=sQ=NULL;
- gal_list_tosizet_add(&lQ, &sQ, index, 0.0f);
+ gal_list_dosizet_add(&lQ, &sQ, index, 0.0f);
while(sQ)
{
/* Pop-out (p) an index from the queue: */
- gal_list_tosizet_pop_smallest(&lQ, &sQ, &pind, &pdist);
+ pind=gal_list_dosizet_pop_smallest(&lQ, &sQ, &pdist);
/* If this isn't a blank value then add its values to the list of
neighbor values. Note that we didn't check whether the values
@@ -210,7 +210,7 @@ interpolate_close_neighbors_on_thread(void *in_prm)
list and break out. */
if(++ngb_counter>=prm->numneighbors)
{
- if(lQ) gal_list_tosizet_free(lQ);
+ if(lQ) gal_list_dosizet_free(lQ);
break;
}
}
@@ -232,7 +232,7 @@ interpolate_close_neighbors_on_thread(void *in_prm)
dist=gal_dimension_dist_manhattan(icoord, ncoord, ndim);
/* Add this neighbor to the list. */
- gal_list_tosizet_add(&lQ, &sQ, nind, dist);
+ gal_list_dosizet_add(&lQ, &sQ, nind, dist);
/* Flag this neighbor as checked. */
flag[nind] |= INTERPOLATE_FLAGS_CHECKED;
diff --git a/lib/list.c b/lib/list.c
index 9858500..638f8c4 100644
--- a/lib/list.c
+++ b/lib/list.c
@@ -260,7 +260,7 @@ gal_list_i32_reverse(gal_list_i32_t **list)
int32_t *
-gal_list_i32_to_array(gal_list_i32_t *list, int inverse, size_t *num)
+gal_list_i32_to_array(gal_list_i32_t *list, int reverse, size_t *num)
{
size_t i;
int32_t *out=NULL;
@@ -272,8 +272,8 @@ gal_list_i32_to_array(gal_list_i32_t *list, int inverse,
size_t *num)
{
out=gal_data_malloc_array(GAL_TYPE_SIZE_T, *num);
- i = inverse ? *num-1: 0;
- if(inverse)
+ i = reverse ? *num-1: 0;
+ if(reverse)
for(tmp=list;tmp!=NULL;tmp=tmp->next)
out[i--]=tmp->v;
else
@@ -411,7 +411,7 @@ gal_list_sizet_reverse(gal_list_sizet_t **list)
size_t *
-gal_list_sizet_to_array(gal_list_sizet_t *list, int inverse, size_t *num)
+gal_list_sizet_to_array(gal_list_sizet_t *list, int reverse, size_t *num)
{
size_t i, *out=NULL;
gal_list_sizet_t *tmp;
@@ -422,8 +422,8 @@ gal_list_sizet_to_array(gal_list_sizet_t *list, int
inverse, size_t *num)
{
out=gal_data_malloc_array(GAL_TYPE_SIZE_T, *num);
- i = inverse ? *num-1: 0;
- if(inverse)
+ i = reverse ? *num-1: 0;
+ if(reverse)
for(tmp=list;tmp!=NULL;tmp=tmp->next)
out[i--]=tmp->v;
else
@@ -562,7 +562,7 @@ gal_list_f32_print(gal_list_f32_t *list)
float *
-gal_list_f32_to_array(gal_list_f32_t *list, int inverse, size_t *num)
+gal_list_f32_to_array(gal_list_f32_t *list, int reverse, size_t *num)
{
size_t i;
float *out=NULL;
@@ -579,8 +579,8 @@ gal_list_f32_to_array(gal_list_f32_t *list, int inverse,
size_t *num)
out=gal_data_malloc_array(GAL_TYPE_FLOAT32, *num);
/* Fill in the array. */
- i = inverse ? *num-1: 0;
- if(inverse)
+ i = reverse ? *num-1: 0;
+ if(reverse)
for(tmp=list;tmp!=NULL;tmp=tmp->next)
out[i--]=tmp->v;
else
@@ -720,7 +720,7 @@ gal_list_f64_reverse(gal_list_f64_t **list)
double *
-gal_list_f64_to_array(gal_list_f64_t *list, int inverse, size_t *num)
+gal_list_f64_to_array(gal_list_f64_t *list, int reverse, size_t *num)
{
size_t i;
double *out=NULL;
@@ -737,8 +737,8 @@ gal_list_f64_to_array(gal_list_f64_t *list, int inverse,
size_t *num)
out=gal_data_malloc_array(GAL_TYPE_FLOAT64, *num);
/* Fill in the array. */
- i = inverse ? *num-1: 0;
- if(inverse)
+ i = reverse ? *num-1: 0;
+ if(reverse)
for(tmp=list;tmp!=NULL;tmp=tmp->next)
out[i--]=tmp->v;
else
@@ -943,24 +943,26 @@ gal_list_osizet_add(gal_list_osizet_t **list,
/* Note that the popped element is the smallest! */
-void
-gal_list_osizet_pop(gal_list_osizet_t **list,
- size_t *value, float *sortvalue)
+size_t
+gal_list_osizet_pop(gal_list_osizet_t **list, float *sortvalue)
{
+ size_t value;
gal_list_osizet_t *tmp=*list;
if(*list)
{
- *value=tmp->v;
+ value=tmp->v;
*sortvalue=tmp->s;
*list=tmp->next;
free(tmp);
}
else
{
- *value=GAL_BLANK_SIZE_T;
+ value=GAL_BLANK_SIZE_T;
*sortvalue=NAN;
}
+
+ return value;
}
@@ -1005,8 +1007,7 @@ gal_list_osizet_to_sizet_free(gal_list_osizet_t *in,
****************** Two way, Ordered SLL ********************
***************** size_t ********************
****************************************************************/
-
-/* The two way ordered SLL looks something like this:
+/* Doubly-linked ordered size_t list can be visualized like this:
largest pointer
|
@@ -1018,11 +1019,10 @@ gal_list_osizet_to_sizet_free(gal_list_osizet_t *in,
*/
/* Very similar to Ordered SLL, but now it is two way. */
void
-gal_list_tosizet_add(gal_list_tosizet_t **largest,
- gal_list_tosizet_t **smallest,
- size_t value, float tosort)
+gal_list_dosizet_add(gal_list_dosizet_t **largest,
+ gal_list_dosizet_t **smallest, size_t value, float tosort)
{
- gal_list_tosizet_t *newnode, *tmp=*largest;
+ gal_list_dosizet_t *newnode, *tmp=*largest;
errno=0;
newnode=malloc(sizeof *newnode);
@@ -1072,37 +1072,17 @@ gal_list_tosizet_add(gal_list_tosizet_t **largest,
-void
-gal_list_tosizet_print(gal_list_tosizet_t *largest,
- gal_list_tosizet_t *smallest)
-{
- size_t counter=1; /* We are not counting array elements :-D ! */
- while(largest!=NULL)
- {
- printf("\t%-5zu (%zu, %.4f) \n", counter++,
- largest->v, largest->s);
- largest=largest->next;
- printf("\t\t\t\t(%zu, %.4f)\n", smallest->v, smallest->s);
- smallest=smallest->prev;
- }
- printf("\n");
-}
-
-
-
-
-
/* Note that start has to be initialized. */
-void
-gal_list_tosizet_pop_smallest(gal_list_tosizet_t **largest,
- gal_list_tosizet_t **smallest,
- size_t *value, float *tosort)
+size_t
+gal_list_dosizet_pop_smallest(gal_list_dosizet_t **largest,
+ gal_list_dosizet_t **smallest, float *tosort)
{
- gal_list_tosizet_t *tmp=*smallest;
+ size_t value;
+ gal_list_dosizet_t *tmp=*smallest;
if(*smallest)
{
- *value=tmp->v;
+ value=tmp->v;
*tosort=tmp->s;
*smallest=tmp->prev;
@@ -1117,14 +1097,36 @@ gal_list_tosizet_pop_smallest(gal_list_tosizet_t
**largest,
/* If `smallest' is NULL, `largest' should also be NULL. */
if(*largest)
error(EXIT_FAILURE, 0, "`largest' and `smallest' pointers to "
- "`gal_list_tosizet_pop_smallest' must both be non-NULL or "
+ "`gal_list_dosizet_pop_smallest' must both be non-NULL or "
"both be NULL. However, in this call, `smallest' was NULL "
"while `largest' isn't NULL");
- *value=GAL_BLANK_SIZE_T;
+ value=GAL_BLANK_SIZE_T;
*tosort=NAN;
}
/*printf("Popped v: %zu, s: %f\n", *value, *tosort);*/
+
+ return value;
+}
+
+
+
+
+
+void
+gal_list_dosizet_print(gal_list_dosizet_t *largest,
+ gal_list_dosizet_t *smallest)
+{
+ size_t counter=1; /* We are not counting array elements :-D ! */
+ while(largest!=NULL)
+ {
+ printf("\t%-5zu (%zu, %.4f) \n", counter++,
+ largest->v, largest->s);
+ largest=largest->next;
+ printf("\t\t\t\t(%zu, %.4f)\n", smallest->v, smallest->s);
+ smallest=smallest->prev;
+ }
+ printf("\n");
}
@@ -1132,9 +1134,9 @@ gal_list_tosizet_pop_smallest(gal_list_tosizet_t
**largest,
void
-gal_list_tosizet_to_sizet(gal_list_tosizet_t *in, gal_list_sizet_t **out)
+gal_list_dosizet_to_sizet(gal_list_dosizet_t *in, gal_list_sizet_t **out)
{
- gal_list_tosizet_t *tmp;
+ gal_list_dosizet_t *tmp;
while(in!=NULL)
{
tmp=in->next;
@@ -1149,9 +1151,9 @@ gal_list_tosizet_to_sizet(gal_list_tosizet_t *in,
gal_list_sizet_t **out)
void
-gal_list_tosizet_free(gal_list_tosizet_t *largest)
+gal_list_dosizet_free(gal_list_dosizet_t *largest)
{
- gal_list_tosizet_t *tmp;
+ gal_list_dosizet_t *tmp;
while(largest!=NULL)
{
tmp=largest->next;
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gnuastro-commits] master 195fae5: Completed Lists, types and blank library documentation,
Mohammad Akhlaghi <=