BRL-CAD
hist.h
Go to the documentation of this file.
1 /* H I S T . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /** @defgroup data Data Management */
22 /** @defgroup hist Histogram Handling */
23 
24 /** @file hist.h
25  *
26  */
27 #ifndef BU_HIST_H
28 #define BU_HIST_H
29 
30 #include "common.h"
31 
32 #include <stddef.h> /* for size_t */
33 
34 #include "bu/defines.h"
35 #include "bu/magic.h"
36 
38 
39 /** @addtogroup hist */
40 /** @{ */
41 /** @file libbu/hist.c
42  *
43  * General purpose histogram handling routines.
44  *
45  * The subroutine bu_hist_range() is used to record items that may
46  * extend across multiple "bin"s.
47  *
48  */
49 
50 /**
51  * histogram support
52  */
53 struct bu_hist {
54  uint32_t magic; /**< magic # for id/check */
55  fastf_t hg_min; /**< minimum value */
56  fastf_t hg_max; /**< maximum value */
57  fastf_t hg_clumpsize; /**< (max-min+1)/nbins+1 */
58  size_t hg_nsamples; /**< total number of samples spread into histogram */
59  size_t hg_nbins; /**< # of bins in hg_bins[] */
60  long *hg_bins; /**< array of counters */
61 };
62 typedef struct bu_hist bu_hist_t;
63 #define BU_HIST_NULL ((struct bu_hist *)0)
64 
65 /**
66  * assert the integrity of a bu_hist struct.
67  */
68 #define BU_CK_HIST(_p) BU_CKMAG(_p, BU_HIST_MAGIC, "struct bu_hist")
69 
70 /**
71  * initialize a bu_hist struct without allocating any memory.
72  */
73 #define BU_HIST_INIT(_hp) { \
74  (_hp)->magic = BU_HIST_MAGIC; \
75  (_hp)->hg_min = (_hp)->hg_max = (_hp)->hg_clumpsize = 0.0; \
76  (_hp)->hg_nsamples = (_hp)->hg_nbins = 0; \
77  (_hp)->hg_bins = NULL; \
78  }
79 
80 /**
81  * macro suitable for declaration statement initialization of a
82  * bu_hist struct. does not allocate memory.
83  */
84 #define BU_HIST_INIT_ZERO {BU_HIST_MAGIC, 0.0, 0.0, 0.0, 0, 0, NULL}
85 
86 /**
87  * returns truthfully whether a bu_hist has been initialized via
88  * BU_HIST_INIT() or BU_HIST_INIT_ZERO.
89  */
90 #define BU_HIST_IS_INITIALIZED(_hp) (((struct bu_hist *)(_hp) != BU_HIST_NULL) && LIKELY((_hp)->magic == BU_HIST_MAGIC))
91 
92 #define BU_HIST_TALLY(_hp, _val) { \
93  if ((_val) <= (_hp)->hg_min) { \
94  (_hp)->hg_bins[0]++; \
95  } else if ((_val) >= (_hp)->hg_max) { \
96  (_hp)->hg_bins[(_hp)->hg_nbins]++; \
97  } else { \
98  (_hp)->hg_bins[(int)(((_val)-(_hp)->hg_min)/(_hp)->hg_clumpsize)]++; \
99  } \
100  (_hp)->hg_nsamples++; }
101 
102 #define BU_HIST_TALLY_MULTIPLE(_hp, _val, _count) { \
103  int __count = (_count); \
104  if ((_val) <= (_hp)->hg_min) { \
105  (_hp)->hg_bins[0] += __count; \
106  } else if ((_val) >= (_hp)->hg_max) { \
107  (_hp)->hg_bins[(_hp)->hg_nbins] += __count; \
108  } else { \
109  (_hp)->hg_bins[(int)(((_val)-(_hp)->hg_min)/(_hp)->hg_clumpsize)] += __count; \
110  } \
111  (_hp)->hg_nsamples += __count; }
112 
113 /* hist.c */
114 /* These are a set of data histogramming routines. */
115 
116 BU_EXPORT extern void bu_hist_free(struct bu_hist *histp);
117 
118 /**
119  * Initialize a bu_hist structure.
120  *
121  * It is expected that the structure is junk upon entry.
122  */
123 BU_EXPORT extern void bu_hist_init(struct bu_hist *histp, fastf_t min, fastf_t max, size_t nbins);
124 
125 BU_EXPORT extern void bu_hist_range(struct bu_hist *hp, fastf_t low, fastf_t high);
126 
127 /**
128  * Print a histogram.
129  */
130 BU_EXPORT extern void bu_hist_pr(const struct bu_hist *histp, const char *title);
131 
132 /** @} */
133 
135 
136 #endif /* BU_HIST_H */
137 
138 /*
139  * Local Variables:
140  * mode: C
141  * tab-width: 8
142  * indent-tabs-mode: t
143  * c-file-style: "stroustrup"
144  * End:
145  * ex: shiftwidth=4 tabstop=8
146  */
void bu_hist_pr(const struct bu_hist *histp, const char *title)
fastf_t hg_min
Definition: hist.h:55
Definition: hist.h:53
void bu_hist_init(struct bu_hist *histp, fastf_t min, fastf_t max, size_t nbins)
Definition: hist.c:51
size_t hg_nbins
Definition: hist.h:59
Header file for the BRL-CAD common definitions.
#define __BEGIN_DECLS
Definition: common.h:73
void bu_hist_range(struct bu_hist *hp, fastf_t low, fastf_t high)
fastf_t hg_clumpsize
Definition: hist.h:57
uint32_t magic
Definition: hist.h:54
size_t hg_nsamples
Definition: hist.h:58
fastf_t hg_max
Definition: hist.h:56
void bu_hist_free(struct bu_hist *histp)
Definition: hist.c:32
#define __END_DECLS
Definition: common.h:74
long * hg_bins
Definition: hist.h:60
double fastf_t
Definition: defines.h:300