pdal::Utils

:cpp:namespace:`pdal::Utils` is a set of utility functions.

namespace pdal::Utils

Typedefs

using pdal::Utils::BacktraceEntries = typedef std::deque<BacktraceEntry>

Functions

template <>
template<>
bool fromString<Eigen::MatrixXd>(const std::string &s, Eigen::MatrixXd &matrix)
std::string PDAL_DLL pdal::Utils::toJSON(const MetadataNode & m)
void PDAL_DLL pdal::Utils::toJSON(const MetadataNode & m, std::ostream & o)
std::ostream PDAL_DLL * pdal::Utils::createFile(const std::string & path, bool asBinary)

Create a file (may be on a supported remote filesystem).

Return
Pointer to the created stream, or NULL.
Parameters
  • path: Path to file to create.
  • asBinary: Whether the file should be written in binary mode.

std::istream PDAL_DLL * pdal::Utils::openFile(const std::string & path, bool asBinary)

Open a file (potentially on a remote filesystem).

Return
Pointer to stream opened for input.
Parameters
  • path: Path (potentially remote) of file to open.
  • asBinary: Whether the file should be opened binary.

void PDAL_DLL pdal::Utils::closeFile(std::ostream * out)

Close an output stream.

Parameters
  • out: Stream to close.

void PDAL_DLL pdal::Utils::closeFile(std::istream * in)

Close an input stream.

Parameters
  • out: Stream to close.

bool PDAL_DLL pdal::Utils::fileExists(const std::string & path)

Check to see if a file exists.

Return
Whether the file exists or not.
Parameters
  • path: Path to file.

double PDAL_DLL pdal::Utils::computeHausdorff(PointViewPtr srcView, PointViewPtr candView)
void printError(const std::string &s)
double toDouble(const Everything &e, Dimension::Type type)
template <typename INPUT>
Everything extractDim(INPUT &ext, Dimension::Type type)
template <typename OUTPUT>
void insertDim(OUTPUT &ins, Dimension::Type type, const Everything &e)
MetadataNode toMetadata(const BOX2D &bounds)
MetadataNode toMetadata(const BOX3D &bounds)
int openProgress(const std::string &filename)
void closeProgress(int fd)
void writeProgress(int fd, const std::string &type, const std::string &text)
std::vector<std::string> PDAL_DLL pdal::Utils::maybeGlob(const std::string & path)
template <typename CONTAINER, typename VALUE>
bool contains(const CONTAINER &cont, const VALUE &val)

Determine if a container contains a value.

Return
true if the value is in the container, false otherwise.
Parameters
  • cont: Container.
  • val: Value.

template <typename KEY, typename VALUE>
bool contains(const std::map<KEY, VALUE> &c, const KEY &v)

Determine if a map contains a key.

Return
true if the value is in the container, false otherwise.
Parameters
  • c: Map.
  • v: Key value.

template <typename CONTAINER, typename VALUE>
void remove(CONTAINER &cont, const VALUE &val)

Remove all instances of a value from a container.

Parameters
  • cont: Container.
  • v: Value to remove.

template <typename CONTAINER, typename PREDICATE>
void remove_if(CONTAINER &cont, PREDICATE p)

Remove all instances matching a unary predicate from a container.

Parameters
  • cont: Container.
  • p: Predicate indicating whether a value should be removed.

PDAL_DLL std::vector< std::string > pdal::Utils::backtrace()

Generate a backtrace as a list of strings.

Return
List of functions at the point of the call.

Utils::BacktraceEntries backtraceImpl()
template <class T>
PDAL_DLL const T& pdal::Utils::clamp(const T & t, const T & minimum, const T & maximum)

Clamp value to given bounds.

Clamps the input value t to bounds specified by min and max. Used to ensure that row and column indices remain within valid bounds.

Return
the value to clamped to the given bounds.
Parameters
  • t: the input value.
  • min: the lower bound.
  • max: the upper bound.

void random_seed(unsigned int seed)

Set a seed for random number generation.

Parameters
  • seed: Seed value.

double random(double minimum, double maximum)

Generate a random value in the range [minimum, maximum].

Parameters
  • minimum: Lower value of range for random number generation.
  • maximum: Upper value of range for random number generation.

double uniform(const double &minimum, const double &maximum, uint32_t seed)

Generate values in a uniform distribution in the range [minimum, maximum] using the provided seed value.

Parameters
  • double: Lower value of range for random number generation.
  • double: Upper value of range for random number generation.
  • seed: Seed value for random number generation.

double normal(const double &mean, const double &sigma, uint32_t seed)

Generate values in a normal distribution in the range [minimum, maximum] using the provided seed value.

Parameters
  • double: Lower value of range for random number generation.
  • double: Upper value of range for random number generation.
  • seed: Seed value for random number generation.

PDAL_DLL bool pdal::Utils::compare_approx(double v1, double v2, double tolerance)

Determine if two values are within a particular range of each other.

Parameters
  • v1: First value to compare.
  • v2: Second value to compare.
  • tolerance: Maximum difference between v1 and v2

double sround(double r)

Round double value to nearest integral value.

Return
Rounded value
Parameters
  • r: Value to round

std::string tolower(const std::string &s)

Convert a string to lowercase.

Return
Converted string.

std::string toupper(const std::string &s)

Convert a string to uppercase.

Return
Converted string.

bool iequals(const std::string &s, const std::string &s2)

Compare strings in a case-insensitive manner.

Return
Whether the strings are equal.
Parameters
  • s: First string to compare.
  • s2: Second string to compare.

bool startsWith(const std::string &s, const std::string &prefix)

Determine if a string starts with a particular prefix.

Return
Whether the string begins with the prefix.
Parameters
  • s: String to check for prefix.
  • prefix: Prefix to search for.

bool endsWith(const std::string &s, const std::string &postfix)

Determine if a string ends with a particular postfix.

Return
Whether the string ends with the postfix.
Parameters
  • s: String to check for postfix.
  • postfix: Postfix to search for.

int cksum(char *buf, size_t size)

Generate a checksum that is the integer sum of the values of the bytes in a buffer.

Return
Generated checksum.
Parameters
  • buf: Pointer to buffer.
  • size: Size of buffer.

int getenv(std::string const &name, std::string &val)

Fetch the value of an environment variable.

Return
0 on success, -1 on failure
Parameters
  • name: Name of environment varaible.
  • name: Value of the environemnt variable if it exists, empty otherwise.

int setenv(const std::string &env, const std::string &val)

Set the value of an environment variable.

Return
0 on success, -1 on failure
Parameters
  • env: Name of environment variable.
  • val: Value of environment variable.

int unsetenv(const std::string &env)

Clear the value of an environment variable.

Return
0 on success, -1 on failure
Parameters
  • env: Name of the environment variable to clear.

void eatwhitespace(std::istream &s)

Skip stream input until a non-space character is found.

Parameters
  • s: Stream to process.

void trimLeading(std::string &s)

Remove whitspace from the beginning of a string.

Parameters
  • s: String to be trimmed.

void trimTrailing(std::string &s)

Remove whitspace from the end of a string.

Parameters
  • s: String to be trimmed.

void trim(std::string &s)

Remove whitespace from the beginning and end of a string.

Parameters
  • s: String to be trimmed.

bool eatcharacter(std::istream &s, char x)

If specified character is at the current stream position, advance the stream position by 1.

Return
true if the character is at the current stream position, false otherwise.
Parameters
  • s: Stream to insect.
  • x: Character to check for.

std::string base64_encode(const unsigned char *buf, size_t size)

Convert a buffer to a string using base64 encoding.

Return
Encoded buffer.
Parameters
  • buf: Pointer to buffer to encode.
  • size: Size of buffer.

std::string base64_encode(std::vector<uint8_t> const &bytes)

Convert a buffer to a string using base64 encoding.

Return
Encoded buffer.
Parameters
  • bytes: Pointer to buffer to encode.

std::vector<uint8_t> base64_decode(std::string const &input)

Decode a base64-encoded string into a buffer.

Return
Buffer containing decoded string.
Parameters
  • input: String to decode.

FILE *portable_popen(const std::string &command, const std::string &mode)

Start a process to run a command and open a pipe to which input can be written and from which output can be read.

Return
Pointer to FILE for input/output from the subprocess.
Parameters
  • command: Command to run in subprocess. Either ‘r’, ‘w’ or ‘r+’ to specify if the pipe should be opened as read-only, write-only or read-write.

int portable_pclose(FILE *fp)

Close file opened with portable_popen.

Return
0 on success, -1 on failure.
Parameters
  • fp: Pointer to file to close.

int run_shell_command(const std::string &cmd, std::string &output)

Create a subprocess and set the standard output of the command into the provided output string.

Parameters
  • cmd: Command to run.
  • output: String to which output from the command should be written,

std::string replaceAll(std::string input, const std::string &replaceWhat, const std::string &replaceWithWhat)

Replace all instances of one string found in the input with another value.

Return
Modified version of input string.
Parameters
  • input: Input string to modify.
  • replaceWhat: Token to locate in input string.
  • replaceWithWhat: Replacement for found tokens.

StringList wordWrap(std::string const &inputString, size_t lineLength, size_t firstLength = 0)

Break a string into a list of strings to not exceed a specified length.

Whitespace is condensed to a single space and each string is free of whitespace at the beginning and end when possible. Optionally, a line length for the first line can be different from subsequent lines.

Return
List of substrings generated from the input string.
Parameters
  • inputString: String to split into substrings.
  • lineLength: Maximum length of substrings.
  • firstLength: When non-zero, the maximum length of the first substring. When zero, the first firstLength is assigned the value provided in lineLength.

StringList wordWrap2(std::string const &inputString, size_t lineLength, size_t firstLength = 0)

Break a string into a list of strings to not exceed a specified length.

The concatanation of the returned substrings will yield the original string. The algorithm attempts to break the original string such that each substring begins with a word.

Return
List of substrings generated from the input string.
Parameters
  • inputString: String to split into substrings.
  • lineLength: Maximum length of substrings.
  • firstLength: When non-zero, the maximum length of the first substring. When zero, the first firstLength is assigned the value provided in lineLength.

std::string escapeJSON(const std::string &s)

Add escape characters or otherwise transform an input string so as to be a valid JSON string.

Return
Valid JSON version of input string.
Parameters
  • s: Input string.

std::string demangle(const std::string &s)

Demangle a C++ symbol into readable form.

Demangle strings using the compiler-provided demangle function.

Return
Demangled symbol.
Return
Demangled string
Parameters
  • s: String to demangle.
Parameters
  • s: String to be demangled.

int screenWidth()

Return the screen width of an associated tty.

Return
The tty screen width or 80 if on Windows or it can’t be determined.

std::string escapeNonprinting(const std::string &s)

Escape non-printing characters by using standard notation (i.e.

) or hex notation () as as necessary.

Return
Copy of input string with non-printing characters converted to printable notation.
Parameters
  • s: String to modify.

double normalizeLongitude(double longitude)

Normalize longitude so that it’s between (-180, 180].

Return
Normalized longitude.
Parameters
  • longitude: Longitude to normalize.

std::string hexDump(const char *buf, size_t count)

Convert an input buffer to a hexadecimal string representation similar to the output of the UNIX command ‘od’.

This is mostly used as an occasional debugging aid.

Return
Buffer converted to hex string.
Parameters
  • buf: Point to buffer to dump.
  • count: Size of buffer.

template <typename PREDICATE>
PDAL_DLL std::string::size_type pdal::Utils::extract(const std::string & s, std::string::size_type p, PREDICATE pred)

Count the number of characters in a string that meet a predicate.

Return
Then number of characters matching the predicate.
Parameters
  • s: String in which to start counting characters.
  • p: Position in input string at which to start counting.
  • pred: Unary predicate that tests a character.

PDAL_DLL std::string::size_type pdal::Utils::extractSpaces(const std::string & s, std::string::size_type p)

Count the number of characters spaces in a string at a position.

Return
Then number of space-y characters matching the predicate.
Parameters
  • s: String in which to start counting characters.
  • p: Position in input string at which to start counting.

template <typename PREDICATE>
PDAL_DLL std::vector<std::string> pdal::Utils::split(const std::string & s, PREDICATE p)

Split a string into substrings based on a predicate.

Characters matching the predicate are discarded.

Return
Substrings.
Parameters
  • s: String to split.
  • p: Unary predicate that returns true to indicate that a character is a split location.

template <typename PREDICATE>
PDAL_DLL std::vector<std::string> pdal::Utils::split2(const std::string & s, PREDICATE p)

Split a string into substrings.

Characters matching the predicate are discarded, as are empty strings otherwise produced by split().

Return
Vector of substrings.
Parameters
  • s: String to split.
  • p: Predicate returns true if a char in a string is a split location.

PDAL_DLL std::vector<std::string> pdal::Utils::split(const std::string & s, char tChar)

Split a string into substrings based a splitting character.

The splitting characters are discarded.

Return
Substrings.
Parameters
  • s: String to split.
  • p: Character indicating split positions.

PDAL_DLL std::vector<std::string> pdal::Utils::split2(const std::string & s, char tChar)

Split a string into substrings based a splitting character.

The splitting characters are discarded as are empty strings otherwise produced by split().

Return
Substrings.
Parameters
  • s: String to split.
  • p: Character indicating split positions.

std::vector<std::string> simpleWordexp(const std::string &s)

Perform shell-style word expansion (break a string into arguments).

This only does simple handling of quoted values and backslashes and doesn’t support fancier shell behavior. Use the real wordexp() if you need all that. The behavior of escaped values in a string was surprising to me, so try the shell first if you think you’ve found a problem.

Return
List of arguments.
Parameters
  • s: Input string to parse.

template <typename T>
std::string typeidName()

Return a string representation of a type specified by the template argument.

Return
String representation of the type.

RedirectStream redirect(std::ostream &out, std::ostream &dst)

Redirect a stream to some other stream, by default a null stream.

Return
Context for stream restoration (see restore()).
Parameters
  • out: Stream to redirect.
  • dst: Destination stream.

RedirectStream redirect(std::ostream &out)

Redirect a stream to a null stream.

Return
Context for stream restoration (see restore()).
Parameters
  • out: Stream to redirect.

RedirectStream redirect(std::ostream &out, const std::string &file)

Redirect a stream to some file.

Return
Context for stream restoration (see restore()).
Parameters
  • out: Stream to redirect.
  • file: Name of file where stream should be redirected.

void restore(std::ostream &out, RedirectStream &redir)

Restore a stream redirected with redirect().

Parameters

template <typename T_OUT>
bool inRange(double in)

Determine whether a double value may be safely converted to the given output type without over/underflow.

If the output type is integral the input will be rounded before being tested.

Return
Whether value can be safely converted to template type.
Parameters
  • in: Value to range test.

template <typename T_IN, typename T_OUT>
bool inRange(T_IN in)

Determine whether a value may be safely converted to the given output type without over/underflow.

If the output type is integral and different from the input time, the value will be rounded before being tested.

Return
Whether value can be safely converted to template type.
Parameters
  • in: Value to range test.

template <typename T_IN, typename T_OUT>
bool numericCast(T_IN in, T_OUT &out)

Convert a numeric value from one type to another.

Floating point values are rounded to the nearest integer before a conversion is attempted.

Return
true if the conversion was successful, false if the datatypes/input value don’t allow conversion.
Parameters
  • in: Value to convert.
  • out: Converted value.

template <>
bool numericCast(double in, float &out)

Convert a numeric value from double to float.

Specialization to handle NaN.

Return
true if the conversion was successful, false if the datatypes/input value don’t allow conversion.
Parameters
  • in: Value to convert.
  • out: Converted value.

template <typename T>
std::string toString(const T &from)

Convert a value to its string representation by writing to a stringstream.

Return
String representation.
Parameters
  • from: Value to convert.

std::string toString(bool from)

Convert a bool to a string.

std::string toString(double from, size_t precision = 10)

Convert a double to string with a precision of 10 decimal places.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(float from)

Convert a float to string with a precision of 10 decimal places.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(long long from)

Convert a long long int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(unsigned long from)

Convert an unsigned long long int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(long from)

Convert a long int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(unsigned int from)

Convert an unsigned int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(int from)

Convert an int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(unsigned short from)

Convert an unsigned short to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(short from)

Convert a short int to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(char from)

Convert a char (treated as numeric) to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(unsigned char from)

Convert an unsigned char (treated as numeric) to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

std::string toString(signed char from)

Convert a signed char (treated as numeric) to string.

Return
String representation of numeric value.
Parameters
  • from: Value to convert.

template <typename T>
bool fromString(const std::string &from, T *&to)
template <typename T>
bool fromString(const std::string &from, T &to)

Convert a string to a value by reading from a string stream.

Return
true if the conversion was successful, false otherwise.
Parameters
  • from: String to convert.
  • to: Converted value.

template <>
bool fromString(const std::string &from, std::string &to)
template <>
template<>
bool fromString<char>(const std::string &s, char &to)

Convert a numeric string to a char numeric value.

s String to convert.

Return
true if the conversion was successful, false otherwise.
Parameters
  • to: Converted numeric value.

template <>
template<>
bool fromString<unsigned char>(const std::string &s, unsigned char &to)

Convert a numeric string to an unsigned char numeric value.

s String to convert.

Return
true if the conversion was successful, false otherwise.
Parameters
  • to: Converted numeric value.

template <>
template<>
bool fromString<signed char>(const std::string &s, signed char &to)

Convert a numeric string to a signed char numeric value.

s String to convert.

Return
true if the conversion was successful, false otherwise.
Parameters
  • to: Converted numeric value.

template <>
template<>
bool fromString<double>(const std::string &s, double &d)

Specialization conversion from string to double to handle Nan.

Return
true if the conversion was successful, false otherwise.
Parameters
  • s: String to be converted.
  • d: Converted value.

template <typename E>
std::underlying_type<E>::type toNative(E e)

Return the argument cast to its underlying type.

Typically used on an enum.

Return
Converted variable.
Parameters
  • e: Variable for which to find the underlying type.

Variables

const std::string dynamicLibExtension = ".so"
const char dirSeparator = '/'
const char pathListSeparator = ':'
struct BacktraceEntry
#include <BacktraceImpl.hpp>

Public Functions

BacktraceEntry()

Public Members

std::string libname
void *addr
std::string symname
int offset
struct RedirectStream
#include <Utils.hpp>

Public Functions

RedirectStream()

Public Members

std::ofstream *m_out
std::streambuf *m_buf
std::unique_ptr<NullOStream> m_null