lsst::utils Namespace Reference

Namespaces
	backtrace
	deprecated
	doImport
	get_caller_name
	inheritDoc
	python
	tests
	version
	wrappers

Classes
class	Backtrace
	Singleton, enables automatic backtraces on the following signals: More...
class	Cache
	Cache of most recently used values. More...
struct	key
struct	n
class	Symbol

Functions
std::string	demangleType (std::string const _typeName)
std::size_t	hashCombine (std::size_t seed) noexcept
	Combine hashes. More...
template<typename T , typename... Rest>
std::size_t	hashCombine (std::size_t seed, const T &value, Rest... rest) noexcept
	Combine hashes. More...
template<typename InputIterator >
std::size_t	hashIterable (std::size_t seed, InputIterator begin, InputIterator end) noexcept
	Combine hashes in an iterable. More...
double	nanojanskyToABMagnitude (double flux)
	Convert a flux in nanojansky to AB magnitude. More...
double	ABMagnitudeToNanojansky (double magnitude)
	Convert an AB magnitude to a flux in nanojansky. More...
std::string	getPackageDir (std::string const &packageName)
	return the root directory of a setup package More...
template<typename T >
constexpr void	assertValidHash ()
	Compile-time test of whether a specialization of std::hash conforms to the general spec. More...
template<typename T >
void	assertHashesEqual (T obj1, T obj2)
	Test that equal objects have equal hashes. More...
void	wrapDemangle (python::WrapperCollection &wrappers)
void	wrapPackaging (python::WrapperCollection &wrappers)
void	wrapBacktrace (python::WrapperCollection &wrappers)
	PYBIND11_MODULE (_utils, mod)

Variables
const double	referenceFlux = 1e23 * pow(10, (48.6 / -2.5)) * 1e9
	The Oke & Gunn (1983) AB magnitude reference flux, in nJy (often approximated as 3631.0). More...

Function Documentation

ABMagnitudeToNanojansky()

double lsst::utils::ABMagnitudeToNanojansky

(

double

magnitude

)

Convert an AB magnitude to a flux in nanojansky.

Definition at line 32 of file Magnitude.cc.

{ return pow(10, magnitude / -2.5) * referenceFlux; }

assertHashesEqual()

template<typename T >

void lsst::utils::assertHashesEqual	(	T	obj1,
		T	obj2
	)

Test that equal objects have equal hashes.

If objects of type T can be equal despite having different internal representations, you should include pairs of such objects.

Template Parameters

T	A hashable type.

Parameters

obj1,obj2

Two equal objects.

Definition at line 102 of file tests.h.

                                       {
    using Hash = std::hash<std::remove_cv_t<T>>;
 
    printIfHashEqual(obj1, obj2, Hash());
}

assertValidHash()

template<typename T >

constexpr void lsst::utils::assertValidHash ( )

constexpr

Compile-time test of whether a specialization of std::hash conforms to the general spec.

The function itself is a no-op.

Template Parameters

T	The properties of std::hash<T> will be tested.

Definition at line 72 of file tests.h.

                                 {
    using namespace std;
    using Hash = hash<remove_cv_t<T>>;
 
    static_assert(is_default_constructible<Hash>::value,
                  "std::hash specializations must be default-constructible");
    static_assert(is_copy_assignable<Hash>::value, "std::hash specializations must be copy-assignable");
    // Swappability hard to test before C++17
    static_assert(is_destructible<Hash>::value, "std::hash specializations must be destructible");
 
    static_assert(is_same<typename Hash::argument_type, remove_cv_t<T>>::value,
                  "std::hash must have an argument_type member until C++20");
    static_assert(is_same<typename Hash::result_type, size_t>::value,
                  "std::hash must have a result_type member until C++20");
    // Ability to call Hash(T) hard to test before C++17
    static_assert(is_same<result_of_t<Hash(T)>, size_t>::value,
                  "std::hash specializations must be callable and return a size_t");
}

demangleType()

std::string lsst::utils::demangleType

(

std::string const

_typeName

)

Definition at line 113 of file Demangle.cc.

                                                  {
#if 1
    typedef multi_index_container<
        Symbol,
        indexed_by<
            ordered_unique<tag<n>,
                member<Symbol, int, &Symbol::n> >,
            ordered_unique<tag<key>,
                member<Symbol, std::string, &Symbol::key> >
        >
    > SymbolTable;
    typedef SymbolTable::index<n>::type::iterator nIterator;
    typedef SymbolTable::index<key>::type::iterator keyIterator;
    Symbol::reset();
 
    // Here's my symbol table and its indices
    SymbolTable st;
 
    SymbolTable::index<n>::type &nIndex = st.get<n>();
    SymbolTable::index<key>::type &keyIndex = st.get<key>();
    //
    // Start mangling
    //
    std::string typeName("");
    const char *ptr = _typeName.c_str();
 
    if (*ptr == 'r' || *ptr == 'V' || *ptr == 'K') {
        ptr++;                          // (restrict/volatile/const)
    }
 
    if (*ptr == 'P') ptr++;             // We passed "this" which is (type *)
 
    std::string currentSymbol = "";     // Current symbol
    std::stack<char> typeStack;         // Did we last see an N or an I?
 
    int lastTokenWasType = 0;           // When > 0, the last token was a type such as int or float
    while (*ptr != '\0') {
        lastTokenWasType--;
        switch (*ptr) {
          case 'E':
            ptr++;
            currentSymbol = "";
 
            if (typeStack.empty()) {
                typeStack.push('\a');   // at least don't crash
            }
 
            if (typeStack.top() == 'I') {
                typeName += '>';
            } else if (typeStack.top() == 'L') {
                ;
            } else if (typeStack.top() == 'N') {
                ;
            }
            typeStack.pop();
 
            if (!typeStack.empty() && typeStack.top() == 'I') {
                if (*ptr != 'E' && typeName[typeName.size() - 1] != '<') {
                    typeName += ',';
                }
            }
 
            break;
          case 'I':
            typeStack.push(*ptr++);
            currentSymbol = "";
 
            typeName += '<';
            break;
          case 'L':
            typeStack.push(*ptr++);
            currentSymbol = "";
            {
                std::string type;
                if (interpret_typeletter(*ptr, type)) {
                    typeName += "(" + type + ')';
                } else {
                    typeName += 'c';
                }
                ptr++;
            }
            if (*ptr == 'n') {
                typeName += '-'; ptr++;
            }
            while (*ptr != '\0' && *ptr != 'E') {
                typeName += *ptr++;
            }
            break;
          case 'N':
            typeStack.push(*ptr++);
            currentSymbol = "";
            break;
          case 'S':
            ++ptr;
            switch (*ptr) {
              case 't': typeName += "::std::"; break;
              case 'a': typeName += "::std::allocator"; break;
              case 'b': typeName += "::std::basic_string"; break;
              case 's': typeName += "::std::basic_string<char,::std::char_traits<char>,::std::allocator<char>>"; break;
              case 'i': typeName += "::std::basic_istream<char,  std::char_traits<char> >"; break;
              case 'o': typeName += "::std::basic_ostream<char,std::char_traits<char>>"; break;
              case 'd': typeName += "::std::basic_iostream<char,std::char_traits<char>>"; break;
              default:
                {
                    int subst = 0;      // number of substitution
 
                    if (*ptr == '_') {
                        ;                   // S_ => 0
                    } else if (isdigit(*ptr) || isupper(*ptr)) {
                        while (isdigit(*ptr) || isupper(*ptr)) {
                            if (isdigit(*ptr)) {
                                subst = 36*subst + (*ptr - '0');
                            } else {
                                subst = 36*subst + 10 + (*ptr - 'A');
                            }
                            ptr++;
                        }
                        subst++;            // S_ == 0; S1_ == 1
                        assert (*ptr == '_');
                        ptr++;
                    }
 
                    nIterator sym = nIndex.find(subst);
                    if (sym == nIndex.end()) { // not found
                        typeName += (boost::format("[S%d]") % subst).str();
                    } else {
                        typeName += sym->key;
                    }
 
                }
                break;
            }
            currentSymbol = "";
            break;
          case '0': case '1': case '2': case '3': case '4':
          case '5': case '6': case '7': case '8': case '9':
            {
                const int len = atoi(ptr++);
                while (isdigit(*ptr)) ptr++;
 
                std::string name = "";
                for (int i = 0; *ptr != '\0' && i < len; i++) {
                    name += *ptr++;
                }
 
                if (currentSymbol != "") {
                    currentSymbol += "::";
                    typeName += "::";
                }
 
                currentSymbol += name;
                typeName += name;
 
                if (keyIndex.find(currentSymbol) == keyIndex.end()) {
                    st.insert(currentSymbol);
                }
            }
            break;
          default:
            {
                std::string type;
                if (interpret_typeletter(*ptr, type)) {
                    if (lastTokenWasType > 0) {
                        typeName += ",";
                    }
                    typeName += type;
                    lastTokenWasType = 2; // it'll be decremented on every char in the name
                } else {
                    typeName += *ptr;
                }
                ptr++;
            }
        }
    }
 
    static volatile bool dumpSymbolTable = false; // can be set from gdb
    if (dumpSymbolTable) {
        // The test on the iterator is paranoid, but they _could_
        // have deleted elements.  In this case, they didn't.
        for (unsigned int i = 0; i < st.size(); i++) {
            nIterator el = nIndex.find(2);
            if (el != nIndex.end()) {          // did we find it?
                el->print();
            }
        }
    }
 
    return typeName;
#else
    return _typeName;
#endif
}

getPackageDir()

std::string lsst::utils::getPackageDir

(

std::string const &

packageName

)

return the root directory of a setup package

Parameters

[in]

packageName

name of package (e.g. "utils")

Exceptions

lsst::pex::exceptions::NotFoundError

if desired version can't be found

Definition at line 33 of file packaging.cc.

                                                      {
    std::string envVar = packageName;      // package's environment variable
 
    transform(envVar.begin(), envVar.end(), envVar.begin(), (int (*)(int)) toupper);
    envVar += "_DIR";
 
    char const *dir = getenv(envVar.c_str());
    if (!dir) {
        throw LSST_EXCEPT(lsst::pex::exceptions::NotFoundError, "Package " + packageName + " not found");
    }
 
    return dir;
}

hashCombine() [1/2]

std::size_t lsst::utils::hashCombine ( std::size_t  seed )

inlinenoexcept

Combine hashes.

A specialization of hashCombine for a trivial argument list.

Definition at line 35 of file hashCombine.h.

{ return seed; }

hashCombine() [2/2]

template<typename T , typename... Rest>

std::size_t lsst::utils::hashCombine ( std::size_t  seed, const T &  value, Rest...  rest  )

noexcept

Combine hashes.

This is provided as a convenience for those who need to hash a composite. C++11 includes std::hash, but neglects to include a facility for combining hashes.

Template Parameters

T,Rest

the types to hash. All types must have a valid (in particular, non-throwing) specialization of std::hash.

Parameters

seed	An arbitrary starting value.
value,rest	The objects to hash.

Returns

A combined hash for all the arguments after seed.

Exception Safety

Shall not throw exceptions.

To use it:

// Arbitrary seed; can change to get different hashes of same argument list
std::size_t seed = 0;
result = hashCombine(seed, obj1, obj2, obj3);

Definition at line 63 of file hashCombine.h.

                                                                             {
    std::hash<T> hasher;
    seed ^= hasher(value) + 0x9e3779b9 + (seed << 6) + (seed >> 2);
    return hashCombine(seed, rest...);
}

hashIterable()

template<typename InputIterator >

std::size_t lsst::utils::hashIterable ( std::size_t  seed, InputIterator  begin, InputIterator  end  )

noexcept

Combine hashes in an iterable.

This is provided as a convenience for those who need to hash a container.

Template Parameters

InputIterator

an iterator to the objects to be hashed. The pointed-to type must have a valid (in particular, non-throwing) specialization of std::hash.

Parameters

seed	An arbitrary starting value.
begin,end	The range to hash.

Returns

A combined hash for all the elements in [begin, end).

Exception Safety

Shall not throw exceptions.

To use it:

// Arbitrary seed; can change to get different hashes of same argument list
std::size_t seed = 0;
result = hashIterable(seed, container.begin(), container.end());

Definition at line 93 of file hashCombine.h.

                                                                                        {
    std::size_t result = 0;
    for (; begin != end; ++begin) {
        result = hashCombine(result, *begin);
    }
    return result;
}

nanojanskyToABMagnitude()

double lsst::utils::nanojanskyToABMagnitude

(

double

flux

)

Convert a flux in nanojansky to AB magnitude.

Definition at line 30 of file Magnitude.cc.

{ return -2.5 * log10(flux / referenceFlux); }

PYBIND11_MODULE()

lsst::utils::PYBIND11_MODULE	(	_utils	,
		mod
	)

Definition at line 33 of file _utils.cc.

                             {
    python::WrapperCollection wrappers(mod, "_utils");
    {
        auto backtraceWrappers = wrappers.makeSubmodule("backtrace");
        wrapBacktrace(backtraceWrappers);
        wrappers.collectSubmodule(std::move(backtraceWrappers));
    }
    wrapPackaging(wrappers);
    wrapDemangle(wrappers);
    wrappers.finish();
}

wrapBacktrace()

void lsst::utils::wrapBacktrace

(

python::WrapperCollection &

wrappers

)

Definition at line 32 of file _Backtrace.cc.

                                                       {
    wrappers.wrap(
        [](auto & mod) {
            Backtrace &backtrace = Backtrace::get();
            // Trick to tell the compiler backtrace is used and should not be
            // optimized away, as well as convenient way to check if backtrace
            // is enabled.
            mod.def("isEnabled", [&backtrace]() -> bool { return backtrace.isEnabled(); });
        }
    );
}

wrapDemangle()

void lsst::utils::wrapDemangle

(

python::WrapperCollection &

wrappers

)

Definition at line 32 of file _Demangle.cc.

                                                      {
    wrappers.wrap(
        [](auto & mod) {
            mod.def("demangleType", demangleType);
        }
    );
}

wrapPackaging()

void lsst::utils::wrapPackaging

(

python::WrapperCollection &

wrappers

)

Definition at line 30 of file _packaging.cc.

                                                       {
    wrappers.wrap(
        [](auto & mod) {
            mod.def("getPackageDir", getPackageDir);
        }
    );
}

Variable Documentation

referenceFlux

const double lsst::utils::referenceFlux = 1e23 * pow(10, (48.6 / -2.5)) * 1e9

The Oke & Gunn (1983) AB magnitude reference flux, in nJy (often approximated as 3631.0).

Definition at line 46 of file Magnitude.h.