Topics | |
| Utilities_module_internal_classes | |
| Internal Utilities_module classes and functions. | |
Functions | |
| template<typename t> | |
| void | casacore::assert_ (bool expr, const char *msg, const char *file, int line) |
| | |
| template<class T> | |
| uInt | casacore::genSort (T *data, uInt nr, Sort::Order order=Sort::Ascending, int options=0) |
| Global in-place sort functions The following global functions are easier to use than the static GenSort member functions. | |
| template<class T, class INX = uInt> | |
| uInt | casacore::genSort (Vector< INX > &indexVector, const T *data, INX nr, Sort::Order order=Sort::Ascending, int options=0) |
| Global indirect sort functions The following global functions easier to use than the static GenSortIndirect member functions. | |
| uInt | casacore::precisionForValueErrorPairs (const Vector< Double > &pair1, const Vector< Double > &pair2) |
| | |
Detailed Description
Classes and global functions for general use
See below for an overview of the classes in this module.
Review Status
- Reviewed By:
- Friso Olnon
- Date Reviewed:
- 1995/03/20
Synopsis
This module is a bag of unrelated mini-modules, classes and global functions. The following functional groups can be recognized:
-
Object utilities:
- ObjCompare objects with each other. A signature for comparison functions is defined (required for comparison functions used in the Sort class), and one such function is provided.
- objcopy/objmove/objset copies objects from one place to another.
- Mark objects as valid or invalid.
- Notices provide basic support for shared access of data by various objects.
- Sort objects on one or more keys, in ascending or descending order. Fast sorting is provided for certain types of objects.
- Binary Search templated functions for sorted containers (ascending or descending order) are available.
- Linear Search templated functions for unsorted containers are available.
-
Logical utilities:
- Assertion lets you throw an error when a condition in not fullfilled.
- Bit vectors are an efficient method to keep True/False information on a set of items or conditions.
-
Pointer utilities
- Counted pointers provide support for reference counting.
- Datatype utilities
-
Other utilities
- Dynamic buffers are used to store data in dynamically allocated buffers.
- Regular expressions are supported by the class Regex built on top of std::regex.
- Sequences of any datatype can be derived from the base class Sequence. One example is uIntSequence, provided for general use.
- Strings. for the C++ preprocessor
Tip: You may want to look at the individual header files to see whether you might not prefer to include only the header files you really need; it may be more efficient to do so;
Function Documentation
◆ assert_()
| void casacore::assert_ | ( | bool | expr, |
| const char * | msg, | ||
| const char * | file, | ||
| int | line ) |
Utility function for Assert macros.
Intended use:
Public interface
Review Status
- Reviewed By:
- Friso Olnon
- Date Reviewed:
- 1995/03/13
Prerequisite
- module Exceptions
Etymology
Templated function assert_ is the basis for the macros DebugAssertExit, DebugAssert, AlwaysAssertExit, and AlwaysAssert which form the "public interface" to the Assertion mechanism.
Synopsis
The present Assertion mechanism uses the exception handling mechanism to throw the errors when an Assertion fails. It can be used in two ways:
- DebugAssertExit(expr)
- AlwaysAssertExit(expr)
- cause the program to abort if expr evaluates to false. This form is intended for the end users because presumabily at their level there is no way to recover from errors.
- DebugAssert(expr, exception)
- AlwaysAssert(expr, exception)
- throw the specified exception if the expr is false. This form is designed to be used by library elements because it actually raises an exception which can be later caught in the regular way.
Tip: DebugAssertExit and DebugAssert are only invoked in debug mode (i;e; when AIPS_DEBUG is defined); otherwise they preprocess to null statements; AlwaysAssertExit and AlwaysAssert are always invoked;
Example
The implementation of the Array classes contains many examples of the Assertion mechanism. The following application of the Assertion mechanism is taken from the archive of the aips2.nosp@m.-wor.nosp@m.kers@.nosp@m.nrao.nosp@m..edu mail group (Brian Glendenning, 1994/03/23):
I thought I'd readvertise a technique I use that helps me find problems in the classes I write. I have found this to be an EXTREMELY useful way of discovering bugs automatically (so the users of your class don't have to manually).
In your class, write an ok() member function that returns a Bool. Allow for inheritance and make it a virtual function (in fact, the derived class's ok() would probably call the ok() from its parent, as well as doing specific stuff for the derived class).
Then in every member function, place a call to ok() in an Assertion. Like this:
The second argument is the exception you want to throw. AipsError will always do, although you can throw a more particular one if you want to. This Assertion will not be in production code – i.e. if AIPS_DEBUG is not defined, the above line will be a null statement. I place these lines at the entry to all member functions (except I place them at the end of a constructor!). (I normally don't put an Assertion in an inline function).
In the ok() function you should Assert a class's invariants. This is more or less the same as Asserting that an object's private and protected data are consistent. For example, one of the simple tests I do in the array classes is Assert that the number of elements (which I cache) is indeed equal to the product of its shape (I do ~15 tests in the ok() for the new Array<T> class).
this templated function is called from Assert macros
◆ genSort() [1/2]
|
inline |
Global in-place sort functions The following global functions are easier to use than the static GenSort member functions.
They do an in-place sort of data, thus the data themselves are moved ending up in the requested order.
The default sorting method is QuickSort, which is the fastest. However, there are pathological cases where it can be slow. HeapSort is about twice a slow, but its speed is guaranteed. InsSort (insertion sort) can be very, very slow, but it is the only stable sort method (i.e. equal values are kept in their original order). However, (see (name=genSortIndirect)) indirect sorting methods
are available to make QuickSort and HeapSort stable.
All sort methods have an option to skip duplicate values. This is the only case where the returned number of values can be less than the original number of values.
Definition at line 312 of file GenSort.h.
References casacore::Sort::Ascending, order(), and casacore::GenSort< T >::sort().
◆ genSort() [2/2]
|
inline |
Global indirect sort functions The following global functions easier to use than the static GenSortIndirect member functions.
They do an indirect sort of data, thus the data themselves are not moved. Rather an index vector is returned giving the sorted data indices.
The sorting method used is merge sort, which is always stable. It is the fastest, especially if it can use multiple threads.
Unlike the (see (name=genSortInPlace)) in-place sorting methods, all indirect sorting methods are stable (i.e. equal values are left in their original order).
All sort methods have an option to skip duplicate values. This is the only case where the returned number of values can be less than the original number of values.
Definition at line 358 of file GenSort.h.
References casacore::Sort::Ascending, order(), and casacore::GenSortIndirect< T, INX >::sort().
◆ precisionForValueErrorPairs()
Generated by
1.15.0