`pdal::Utils`¶

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

namespace Utils¶

Typedefs

using BacktraceEntries = std::deque<BacktraceEntry>¶

Functions

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.

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

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.

std::string PDAL_DLL pdal::Utils::fetchRemote(const std::string & path)

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

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<> bool fromString<SrsBounds>(const std::string &s, SrsBounds &srsBounds)¶

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

[in] 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

out: Stream to be restored.
redir: RedirectStream returned from corresponding redirect() call.

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