Loading...
Searching...
No Matches
Utilities_module
casa package (libcasa_casa)

More...

## Topics

| Utilities_module_internal_classes
| Internal Utilities_module classes and functions.

## Classes

class | casacore::AlignMemory
| More...
struct | casacore::BinarySearch_global_functions_binarysearch
| More...
class | casacore::BitVector
| More...
class | casacore::CASATask
| More...
struct | casacore::Compare_global_functions_ObjCompareFunc
| More...
class | casacore::BaseCompare
| abstract base class for comparing two objects More...
class | casacore::ObjCompare< T >
| compare two objects More...
class | casacore::CompareIntervalInt< T >
| Integer comparison class with intervals. More...
class | casacore::CompareIntervalReal< T >
| Real comparison class with intervals. More...
class | casacore::CompareNoCase
| Case-insensitive string comparison class. More...
class | casacore::CompareAlwaysTrue
| Comparison class that is always true. More...
class | casacore::CompositeNumber
| More...
struct | casacore::Copy_global_functions_throw
| More...
struct | casacore::Copy_global_functions_test
| Test routines . More...
struct | casacore::Copy_global_functions_copy
| Copy methods . More...
struct | casacore::CountedPtr_global_functions_dereference_error
| More...
class | casacore::CountedPtr< t >
| Referenced counted pointer for constant data. More...
class | casacore::COWPtr< T >
| More...
struct | casacore::DataType_global_functions_DataType
| More...
struct | casacore::DefaultValue_global_functions_defval
| More...
class | casacore::DynBuffer
| More...
struct | casacore::Fallible_global_functions_invalid_access
| More...
class | casacore::Fallible< T >
| Mark a value as valid or invalid. More...
struct | casacore::generic_global_functions_def
| More...
struct | casacore::LinearSearch_global_functions_linearsearch
| More...
class | casacore::MUString
| More...
struct | casacore::MUString_global_functions_output
| Global functions. More...
class | casacore::PtrHolder< T >
| More...
class | SPtrHolder< T >
| Hold and delete pointers not deleted by object destructors. More...
class | casacore::RecordTransformable
| More...
class | casacore::Regex
| More...
class | casacore::Sequence< t >
| More...
class | casacore::uIntSequence
| uInt sequence for general use More...
class | casacore::Sort
| Sort on one or more keys, ascending and/or descending. More...
class | casacore::SortError
| More...
class | casacore::SortInvDT
| Invalid data type used for this sort key. More...
class | casacore::SortInvIncr
| Invalid increment used for this sort key. More...
class | casacore::SortNoData
| No data array given to Sort constructor. More...
class | casacore::SortInvOpt
| Invalid sort option given to routine dosort. More...
class | casacore::StringDistance
| More...
class | casacore::ValType
| More...
struct | casacore::ValTypeId_global_functions_typeid
| More...

## 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
  - DataType enumerates the possible data types in the table system.
  - ValType describes the data types and their undefined values.
- 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_()

template<typename t>

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:

DebugAssert(ok(), AipsError); // include aips/Assert.h in your.cc file
DebugAssert
#define DebugAssert(expr, exception)
Definition Assert.h:148
casacore::AipsError
Definition Error.h:133

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]

template<class T>

uInt casacore::genSort | ( | T * | data,
|  | uInt | nr,
|  | Sort::Order | order = Sort::Ascending,
|  | int | options = 0 )

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]

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 )

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()

uInt casacore::precisionForValueErrorPairs | ( | const Vector< Double > & | pair1,
|  | const Vector< Double > & | pair2 )

Various precision-related functions

### Intended use:

Public interface

### Synopsis

Various functions for determining precision for printing.

Determine precision for two related value,error pairs (such as RA-Dec)