pdal::Utils

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

namespace pdal::Utils

Typedefs

using BacktraceEntries = std::deque<BacktraceEntry>

Functions

std::string toJSON(const MetadataNode &m)
void toJSON(const MetadataNode &m, std::ostream &o)
uintmax_t fileSize(const std::string &path)
std::ostream *createFile(const std::string &path, bool asBinary)

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

Parameters

  • path – Path to file to create.

  • asBinary – Whether the file should be written in binary mode.

Returns

Pointer to the created stream, or NULL.

bool isRemote(const std::string &path)

Open a file (potentially on a remote filesystem).

Parameters

  • path – Path (potentially remote) of file to open.

  • asBinary – Whether the file should be opened binary.

Returns

Pointer to stream opened for input.

std::string fetchRemote(const std::string &path)
std::istream *openFile(const std::string &path, bool asBinary)
void closeFile(std::ostream *out)

Close an output stream.

Parameters

out – Stream to close.

void closeFile(std::istream *in)

Close an input stream.

Parameters

out – Stream to close.

bool fileExists(const std::string &path)

Check to see if a file exists.

Parameters

path – Path to file.

Returns

Whether the file exists or not.

double computeHausdorff(PointViewPtr srcView, PointViewPtr candView)
std::pair<double, double> computeHausdorffPair(PointViewPtr viewA, PointViewPtr viewB)
std::string dllDir()
double computeChamfer(PointViewPtr srcView, PointViewPtr candView)
inline void printError(const std::string &s)
inline double toDouble(const Everything &e, Dimension::Type type)
template<typename INPUT>
inline Everything extractDim(INPUT &ext, Dimension::Type type)
template<typename OUTPUT>
inline void insertDim(OUTPUT &ins, Dimension::Type type, const Everything &e)
inline MetadataNode toMetadata(const BOX2D &bounds)
inline MetadataNode toMetadata(const BOX3D &bounds)
inline int openProgress(const std::string &filename)
inline void closeProgress(int fd)
inline void writeProgress(int fd, const std::string &type, const std::string &text)
std::vector< std::string > PDAL_DLL maybeGlob (const std::string &path)
template<>
inline StatusWithReason fromString(const std::string &s, Eigen::MatrixXd &matrix)
template<>
inline StatusWithReason fromString(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.

Parameters

  • cont – Container.

  • val – Value.

Returns

true if the value is in the container, false otherwise.

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

Determine if a map contains a key.

Parameters

  • c – Map.

  • v – Key value.

Returns

true if the value is in the container, false otherwise.

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

Generate a backtrace as a list of strings.

Returns

List of functions at the point of the call.

template<>
inline StatusWithReason fromString(const std::string &s, BOX2D &bounds)
template<>
inline StatusWithReason fromString(const std::string &s, BOX3D &bounds)
template<>
inline StatusWithReason fromString(const std::string &s, Bounds &bounds)
BacktraceEntries backtraceImpl()
template<class T> PDAL_DLL const T & 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.

Parameters

  • t – the input value.

  • min – the lower bound.

  • max – the upper bound.

Returns

the value to clamped to the given bounds.

PDAL_DLL void random_seed (unsigned int seed)

Set a seed for random number generation.

Parameters

seed – Seed value.

PDAL_DLL 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.

inline PDAL_DLL bool 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

inline double sround(double r)

Round double value to nearest integral value.

Parameters

r – Value to round

Returns

Rounded value

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

Convert a string to lowercase.

Returns

Converted string.

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

Convert a string to uppercase.

Returns

Converted string.

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

Compare strings in a case-insensitive manner.

Parameters

  • s – First string to compare.

  • s2 – Second string to compare.

Returns

Whether the strings are equal.

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

Determine if a string starts with a particular prefix.

Parameters

  • s – String to check for prefix.

  • prefix – Prefix to search for.

Returns

Whether the string begins with the prefix.

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

Determine if a string ends with a particular postfix.

Parameters

  • s – String to check for postfix.

  • postfix – Postfix to search for.

Returns

Whether the string ends with the postfix.

inline int cksum(char *buf, size_t size)

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

Parameters

  • buf – Pointer to buffer.

  • size – Size of buffer.

Returns

Generated checksum.

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

Fetch the value of an environment variable.

Parameters

  • name – Name of environment variable.

  • name – Value of the environment variable if it exists, empty otherwise.

Returns

0 on success, -1 on failure

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

Set the value of an environment variable.

Parameters

  • env – Name of environment variable.

  • val – Value of environment variable.

Returns

0 on success, -1 on failure

PDAL_DLL int unsetenv (const std::string &env)

Clear the value of an environment variable.

Parameters

env – Name of the environment variable to clear.

Returns

0 on success, -1 on failure

PDAL_DLL void eatwhitespace (std::istream &s)

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

Parameters

s – Stream to process.

PDAL_DLL void trimLeading (std::string &s)

Remove whitespace from the beginning of a string.

Parameters

s – String to be trimmed.

PDAL_DLL void trimTrailing (std::string &s)

Remove whitespace from the end of a string.

Parameters

s – String to be trimmed.

inline void trim(std::string &s)

Remove whitespace from the beginning and end of a string.

Parameters

s – String to be trimmed.

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

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

Parameters

  • s – Stream to insect.

  • x – Character to check for.

Returns

true if the character is at the current stream position, false otherwise.

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

Convert a buffer to a string using base64 encoding.

Parameters

  • buf – Pointer to buffer to encode.

  • size – Size of buffer.

Returns

Encoded buffer.

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

Convert a buffer to a string using base64 encoding.

Parameters

bytes – Pointer to buffer to encode.

Returns

Encoded buffer.

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

Decode a base64-encoded string into a buffer.

Parameters

input – String to decode.

Returns

Buffer containing decoded string.

PDAL_DLL 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.

Parameters

command – Command to run in subprocess. \mode Either ‘r’, ‘w’ or ‘r+’ to specify if the pipe should be opened as read-only, write-only or read-write.

Returns

Pointer to FILE for input/output from the subprocess.

PDAL_DLL int portable_pclose (FILE *fp)

Close file opened with portable_popen.

Parameters

fp – Pointer to file to close.

Returns

0 on success, -1 on failure.

PDAL_DLL 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,

PDAL_DLL 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.

Parameters

  • input – Input string to modify.

  • replaceWhat – Token to locate in input string.

  • replaceWithWhat – Replacement for found tokens.

Returns

Modified version of input string.

PDAL_DLL std::vector< std::string > 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.

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.

Returns

List of substrings generated from the input string.

PDAL_DLL std::vector< std::string > 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.

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.

Returns

List of substrings generated from the input string.

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

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

Parameters

s – Input string.

Returns

Valid JSON version of input string.

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

Demangle a C++ symbol into readable form.

Demangle strings using the compiler-provided demangle function.

Parameters

  • s – String to demangle.

  • s – [in] String to be demangled.

Returns

Demangled symbol.

Returns

Demangled string

PDAL_DLL int screenWidth ()

Return the screen width of an associated tty.

Returns

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

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

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

) or hex notation (\x10) as as necessary.

Parameters

s – String to modify.

Returns

Copy of input string with non-printing characters converted to printable notation.

PDAL_DLL double normalizeLongitude (double longitude)

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

Parameters

longitude – Longitude to normalize.

Returns

Normalized longitude.

PDAL_DLL 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.

Parameters

  • buf – Point to buffer to dump.

  • count – Size of buffer.

Returns

Buffer converted to hex string.

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

Count the number of characters in a string that meet a 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.

Returns

Then number of characters matching the predicate.

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

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

Parameters

  • s – String in which to start counting characters.

  • p – Position in input string at which to start counting.

Returns

Then number of space-y characters matching the predicate.

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

Split a string into substrings based on a predicate.

Characters matching the predicate are discarded.

Parameters

  • s – String to split.

  • p – Unary predicate that returns true to indicate that a character is a split location.

Returns

Substrings.

template<typename PREDICATE> PDAL_DLL std::vector< std::string > 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().

Parameters

  • s – String to split.

  • p – Predicate returns true if a char in a string is a split location.

Returns

Vector of substrings.

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

Split a string into substrings based a splitting character.

The splitting characters are discarded.

Parameters

  • s – String to split.

  • p – Character indicating split positions.

Returns

Substrings.

inline PDAL_DLL std::vector< std::string > 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().

Parameters

  • s – String to split.

  • p – Character indicating split positions.

Returns

Substrings.

PDAL_DLL 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.

Parameters

s – Input string to parse.

Returns

List of arguments.

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

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

Returns

String representation of the type.

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

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

Parameters

  • out – Stream to redirect.

  • dst – Destination stream.

Returns

Context for stream restoration (see restore()).

inline RedirectStream redirect(std::ostream &out)

Redirect a stream to a null stream.

Parameters

out – Stream to redirect.

Returns

Context for stream restoration (see restore()).

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

Redirect a stream to some file.

Parameters

  • out – Stream to redirect.

  • file – Name of file where stream should be redirected.

Returns

Context for stream restoration (see restore()).

inline 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.

Parameters

in – Value to range test.

Returns

Whether value can be safely converted to template type.

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.

Parameters

in – Value to range test.

Returns

Whether value can be safely converted to template type.

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.

Parameters

  • in – Value to convert.

  • out – Converted value.

Returns

true if the conversion was successful, false if the datatypes/input value don’t allow conversion.

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

Convert a numeric value from double to float.

Specialization to handle NaN.

Parameters

  • in – Value to convert.

  • out – Converted value.

Returns

true if the conversion was successful, false if the datatypes/input value don’t allow conversion.

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

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

Parameters

from – Value to convert.

Returns

String representation.

inline std::string toString(bool from)

Convert a bool to a string.

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

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

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(float from)

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

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(long long from)

Convert a long long int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(unsigned long from)

Convert an unsigned long long int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(long from)

Convert a long int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(unsigned int from)

Convert an unsigned int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(int from)

Convert an int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(unsigned short from)

Convert an unsigned short to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(short from)

Convert a short int to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(char from)

Convert a char (treated as numeric) to string.

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(unsigned char from)

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

Parameters

from – Value to convert.

Returns

String representation of numeric value.

inline std::string toString(signed char from)

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

Parameters

from – Value to convert.

Returns

String representation of numeric value.

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

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

Parameters

  • from – String to convert.

  • to – Converted value.

Returns

true if the conversion was successful, false otherwise.

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

Convert a numeric string to a char numeric value.

\parm s String to convert.

Parameters

to – Converted numeric value.

Returns

true if the conversion was successful, false otherwise.

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

Convert a numeric string to an unsigned char numeric value.

\parm s String to convert.

Parameters

to – Converted numeric value.

Returns

true if the conversion was successful, false otherwise.

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

Convert a numeric string to a signed char numeric value.

\parm s String to convert.

Parameters

to – Converted numeric value.

Returns

true if the conversion was successful, false otherwise.

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

Specialization conversion from string to double to handle Nan.

Parameters

  • s – String to be converted.

  • d – Converted value.

Returns

true if the conversion was successful, false otherwise.

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

Return the argument cast to its underlying type.

Typically used on an enum.

Parameters

e – Variable for which to find the underlying type.

Returns

Converted variable.

template<>
inline StatusWithReason fromString(const std::string &from, pdal::i3s::Obb &obb)
template<>
inline StatusWithReason fromString(const std::string &from, pdal::expr::AssignStatement &stmt)
template<>
inline StatusWithReason fromString(const std::string &from, pdal::expr::ConditionalExpression &expr)

Variables

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

Public Functions

inline BacktraceEntry()

Public Members

std::string libname
void *addr
std::string symname
int offset
class Random
#include <Random.hpp>

Public Functions

PDAL_DLL Random()
PDAL_DLL Random(int32_t seed)
PDAL_DLL Random(const std::vector<int32_t> seed)
PDAL_DLL Random(const std::string &seed)
PDAL_DLL std::mt19937 & generator ()

Public Static Functions

static PDAL_DLL unsigned int quick ()
class StatusWithReason
#include <Utils.hpp>

Public Functions

inline StatusWithReason()
inline StatusWithReason(bool ok)
StatusWithReason(int code)
inline StatusWithReason(int code, const std::string &what)
inline int code() const
inline operator bool() const
inline std::string what() const
struct RedirectStream
#include <Utils.hpp>

Public Functions

inline RedirectStream()

Public Members

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