pdal::Utils

pdal::Utils is a set of utility functions.

namespace Utils

Typedefs

using BacktraceEntries = std::deque<BacktraceEntry>
using StringStreamClassicLocale = ClassicLocaleStream<std::stringstream>

Common used streams with classic locale.

using IStringStreamClassicLocale = ClassicLocaleStream<std::istringstream>
using OStringStreamClassicLocale = ClassicLocaleStream<std::ostringstream>

Functions

std::string toJSON(const MetadataNode &m)
void toJSON(const MetadataNode &m, std::ostream &o)
std::string tempFilename(const std::string &path)
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> 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.

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

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.

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

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

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

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

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 whitespace from the beginning of a string.

Parameters:

s – String to be trimmed.

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.

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.

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.

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.

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.

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.

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.

Parameters:
  • input – Input string to modify.

  • replaceWhat – Token to locate in input string.

  • replaceWithWhat – Replacement for found tokens.

Returns:

Modified version of input string.

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.

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.

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.

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

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.

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.

double normalizeLongitude(double longitude)

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

Parameters:

longitude – Longitude to normalize.

Returns:

Normalized longitude.

template<typename PREDICATE>
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 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>
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>
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 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 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.

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, std::enable_if_t<!std::is_integral<T>::value>* = nullptr>
StatusWithReason fromString(const std::string &from, T &to)

Convert a string to a non-integral value by reading from a string stream.

Convert a string to an integral 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::expr::AssignStatement &stmt)
template<>
inline StatusWithReason fromString(const std::string &from, pdal::expr::ConditionalExpression &expr)
template<>
StatusWithReason fromString(const std::string &from, SrsOrderSpec &srsOrder)
template<>
std::string toString(const SrsOrderSpec &srsOrder)
template<size_t LEN>
inline StatusWithReason fromString(const std::string &from, StringHeaderVal<LEN> &h)
template<>
inline StatusWithReason fromString(const std::string &from, pdal::i3s::Obb &obb)

Variables

const char dynamicLibExtension[] = ".so"
const char dirSeparator = '/'
const char pathListSeparator = ':'
class TempFile

Public Functions

inline TempFile(const std::string path)
inline virtual ~TempFile()
inline const std::string &filename()
class ArbiterOutStream : public std::ofstream

Public Functions

inline ArbiterOutStream(const std::string &localPath, const std::string &remotePath, std::ios::openmode mode)
inline virtual ~ArbiterOutStream()

Public Members

std::string m_remotePath
TempFile m_localFile
class ArbiterInStream : public std::ifstream

Public Functions

inline ArbiterInStream(const std::string &localPath, const std::string &remotePath, std::ios::openmode mode)

Public Members

TempFile m_localFile
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

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

Public Static Functions

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

Public Functions

inline StatusWithReason()
inline StatusWithReason(bool ok)
StatusWithReason(int code) = delete
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
template<typename T>
struct ClassicLocaleStream : public T
#include <Utils.hpp>

Wrapper around a stream to be sure that uses classic locale.

Use it instead of a std::*stream on any stream that reads or writes numbers. It prevents problems due to locale global changes done in the application that uses PDAL.

Public Functions

template<typename ...Args>
inline ClassicLocaleStream(Args&&... args)