3.2.3. Proximie::PxUtility reference

namespace PxUtility

The PxUtility namespace, as the name suggests, contains utility classes and helpers for various tasks and systems used by the Proximie SDK and SDK applications. These utility elements are chiefly stand-alone components agnostic to the details of the Proximie systems and implementation: e.g. logging, REST/HTTP support, serialization etc.

Typedefs

using JsonSerializerError = ErrorCodeException<JsonSerializerErrorCategory>

Exception class for JsonSerializer errors

using NetworkPort_t = std::uint16_t

The type of a network port numbers

template<bool B, class T = void>
using disable_if_t = typename disable_if<B, T>::type

Implements a disable_if_t as the inverse of enable_if_t.

Enums

enum class HttpResponseClassErrorCode

Custom error class for dealing with HTTP responses as error_code values.

Boost/Beast does not have error_code support for HTTP response status codes. Further, std error_codes require code zero (only) to indicate success and non-zero for error conditions. This error code encapsulates the response status class only, allowing allowing a single ‘successful’ class (namely 200s). The caller can check this code to determine if it needs to inspect the full response for more detail (chiefly when non-successful).

Values:

enumerator Successful

Success (200 status, not an error)

enumerator Informational

Information (100 status)

enumerator Redirection

Redirection (300 status)

enumerator ClientError

Client error (400 error)

enumerator ServerError

Server error (500 error)

enumerator Unknown

Unknown.

enum class JsonSerializerErrorCode

Error codes for JsonSerializer serialization errors.

Values:

enumerator Successful

Success, not an error.

enumerator InvalidType

Type of a value did not match the requirement.

enumerator KeyMissing

Key was missing in the JSON object.

enumerator ReadOnlyValueMismatch

A read-only value is different from expected.

enumerator InternalError

Internal error.

Functions

template<>
inline PxMedia::FrameRate lerp(const PxMedia::FrameRate &lerpFrom, const PxMedia::FrameRate &lerpTo, double prop)

Specialisation of lerp for FrameRate.

template<>
inline PxMedia::VideoCapabilities::VideoResolution lerp(const PxMedia::VideoCapabilities::VideoResolution &lerpFrom, const PxMedia::VideoCapabilities::VideoResolution &lerpTo, double prop)

Specialisation of lerp for VideoCapabilities VideoResolution.

template<class T, class Compare>
constexpr const T &clamp(const T &value, const T &low, const T &high, Compare comp)

Clamp a value of type T using a compare function.

template<class T>
constexpr const T &clamp(const T &value, const T &low, const T &high)

Clamp a value of type T.

error_code errorCodeFromGFileError(const GError &error)

Make an error code from a GLib GFileError.

error_code errorCodeFromGFileError(GFileError error)

Make an error code from a GLib GFileError.

inline error_code make_error_code(const HttpResponseClassErrorCode code)

Provides support to make an error_code for the HttpResponseClassErrorCode type.

inline error_condition make_error_condition(const HttpResponseClassErrorCode code)

Provides support to make an error_condition for the HttpResponseClassErrorCode type.

error_code errorCodeFromHttpResponseStatus(boost::beast::http::status status)

Helper to convert a Boost Beast HTTP status to a HttpResponseClassErrorCode.

Parameters:

status – [in] A Boost Beast HTTP status value

Returns:

An error_code which will be a HttpResponseClassErrorCode

constexpr uint32_t makeWord32(uint16_t high, uint16_t low)

Create a 32-bit word from two 16-bit values

constexpr uint16_t highWord32(uint32_t dword)

Obtain the high 16-bits of a 32-bit word

constexpr uint16_t lowWord32(uint32_t dword)

Obtain the low 16-bits of a 32-bit word

template<typename T>
constexpr std::underlying_type<T>::type to_underlying(T value) noexcept

A version of std::to_underlying that works with C++11

template<typename NARROWED, typename SOURCE>
boost::optional<NARROWED> narrowInt(SOURCE value)

Recast an integer type to a narrower type, with range checking.

Returns an optional value, which is empty if the cast failed

template<typename T>
std::enable_if_t<std::is_floating_point<T>::value, T> lerpf(T lerpFrom, T lerpTo, double proportion, T step = 0)

Linearly interpolate between two floating point values.

template<typename T>
std::enable_if_t<std::is_integral<T>::value, T> lerpi(T lerpFrom, T lerpTo, double proportion, T step = 0)

Linearly interpolate between two integer values.

Optionally specify a step value to round the result to

template<typename T>
T lerp(const T &lerpFrom, const T &lerpTo, double proportion)

Basic lerp, which assumes integer values. Non-integer types need to have a specialised form provided.

template<>
inline double lerp<double>(const double &lerpFrom, const double &lerpTo, double proportion)

Lerp specialized for floating point values.

inline json_object wrapJsonValue(json_value &&value, string_view key)

Helper to wrap a JSON value within an enclosing object The original value is itself moved into returned object value

inline error_code make_error_code(const JsonSerializerErrorCode code)

Provides support to make an error_code for the JsonSerializerErrorCode type.

inline error_condition make_error_condition(const JsonSerializerErrorCode code)

Provides support to make an error_condition for the JsonSerializerErrorCode type.

template<typename T>
std::weak_ptr<T> weakFromShared(const std::shared_ptr<T> &shared)

Helper to create a weak pointer from a shared pointer.

template<typename T>
std::weak_ptr<T> weakFromShared(const shared_not_null<T> &shared)

Helper to create a weak pointer from a non-null shared pointer.

template<typename T>
std::weak_ptr<T> weakFromShared(T *shared)

Helper to create a weak pointer from a raw pointer, where the target type must support shared_from_this.

template<typename T, typename ...Args>
inline shared_not_null<T> make_shared_not_null(Args&&... args)

Convenience equivalent to std::make_shared for shared_not_null.

shared_not_null<boost::asio::ssl::context> makeSslContext(string_view certPath)

Helper function to create a SSL context from a certificate path.

The SSL context will use the given path with:

  • A context “method” of TLS version 1.2 (client)

  • ”peer” verify mode.

See boost::asio::ssl::context for more details.

shared_not_null<boost::asio::ssl::context> makeDefaultSslContext()

Helper function to create a default SSL context.

The SSL context will use default verification paths for the system and:

  • A context “method” of TLS version 1.2 (client)

  • ”peer” verify mode.

See boost::asio::ssl::context for more details.

template<typename MAP>
std::vector<typename MAP::key_type> mapKeys(const MAP &map)

Obtain the keys from a map into a vector of the map’s key type.

template<typename MAP>
std::vector<typename MAP::mapped_type> mapValues(const MAP &map)

Obtain the values from a map into a vector of the map’s value type.

template<typename T, typename MAP>
std::vector<T> mapTransformedValues(const MAP &map, std::function<T(const typename MAP::mapped_type&)> transform)

Obtain values from a map with a provided value transformation.

template<typename MAP, std::enable_if_t<std::is_constructible<bool, typename MAP::mapped_type>::value, bool> = true>
std::vector<typename MAP::mapped_type> mapValuesTruthy(const MAP &map)

Obtain the values from the map, where the value type is convertible to boolean and is true, into a vector of the map’s value type

template<typename KO, typename VO, typename KI, typename VI>
std::map<KO, VO> transformMap(const std::map<KI, VI> &map, const std::function<std::pair<KO, VO>(const std::pair<KI, VI>&)> &mapper, const std::function<bool(const std::pair<KI, VI>&)> &filter = nullptr)

Map one map type to another with a transform function.

template<typename FROM, typename TO>
std::vector<TO> mapVector(const std::vector<FROM> &from, const std::function<TO(const FROM&)> &mapFn)

Map a vector of one type to another type using a mapping function.

std::string escapeString(string_view str)

Given a string, return a new string which escapes all non-printable and non-ASCII characters with C-style escape sequences.

Variables

constexpr NetworkPort_t DEFAULT_HTTP_PORT = 80

Default HTTP port

constexpr NetworkPort_t DEFAULT_SSL_PORT = 443

Default TLS/SSL port

constexpr NetworkPort_t DEFAULT_UDP_PORT = 5004

Default UDP port

class CallbackFuture
#include <PxUtility/CallbackFuture.h>

A utility class to associate a future with the value passed to a callback.

Public Static Functions

template<typename T>
static inline CallbackFutureResult<T> makeCallbackFuture()

Creates a future and callback pair for a given type. When the callback is called, the future will be set.

The SDK ensures that the future is set on an internal thread, so the future can be waited on from application code and callbacks without causing deadlocks.

template<typename T>
struct CallbackFutureResult
#include <PxUtility/CallbackFuture.h>

Contains the future and associated callback that will use it.

Public Members

std::future<T> future

The future that will be set by the callback.

std::function<void(const T&)> callback

The callback to provide to the caller that will set the future.

class Color
#include <PxUtility/Color.h>

Utility class to represent color values.

Public Functions

Color() = default

Default construction as opaque black.

inline Color(float red, float green, float blue, float alpha = 1)

Construct from red/green/blue and default to opaque alpha.

inline float red() const

Get the red value.

inline Color &red(float set)

Set the red value.

inline float green() const

Get the green value.

inline Color &green(float set)

Set the green value.

inline float blue() const

Get the blue value.

inline Color &blue(float set)

Set the blue value.

inline float alpha() const

Get the alpha value.

inline Color &alpha(float set)

Set the alpha value.

inline Color &opaque()

Set alpha to opaque.

inline uint32_t toARGB32() const

Convert to ARGB 32 bit value.

Public Static Functions

static inline Color grey(float value, float alpha = 1)

Create a grey value with equal red, green, blue.

static inline Color black(float alpha = 1)

Standard black color.

static inline Color white(float alpha = 1)

Standard white color.

static Color fromARGB32(uint32_t color)

Create from an ARGB 32 bit value.

template<typename ENUM, typename STRING = string_view>
class EnumMapper
#include <PxUtility/EnumMapper.h>

Helper class to map enum values to strings and vice versa

Public Types

using EnumStringPair = std::pair<ENUM, STRING>

An enum/string pair.

Public Functions

inline EnumMapper(const std::initializer_list<EnumStringPair> &mapping)

Create with the enum/string mapping values.

inline bool toString(ENUM enumValue, STRING &stringValue) const

Get the string value for an enum Returns true if the enum has been mapped to a string

inline const STRING &toString(ENUM enumValue) const

Get the string value for an enum, assuming the enum is valid and there will be a string mapping. If this is not true, throws an exception.

inline boost::optional<ENUM> toEnum(const STRING &stringValue) const

Get the enum value for a string If the string was not found, the return optional value is empty

inline const std::map<ENUM, STRING> &enumToStringMap() const

Access the underlying enum-to-string map.

inline const std::map<STRING, ENUM> &stringToEnumMap() const

Access the underlying string-to-enum map.

class IErrorCodeException : public std::exception
#include <PxUtility/ErrorCodeException.h>

Base interface for error_code-based errors.

This abstract interface class provides functions common to all error_code-based exceptions. This allows code to catch all error_code-based exceptions and examine the error code.

Subclassed by Proximie::PxUtility::ErrorCodeException< CAT, ENUM >

Public Functions

virtual error_code errorCode() const noexcept = 0

Return an error_code corrsponding to the exception’s code

template<typename CAT, typename ENUM = typename CAT::ErrorCodeEnum>
class ErrorCodeException : public Proximie::PxUtility::IErrorCodeException
#include <PxUtility/ErrorCodeException.h>

Exception class for error_code-based errors.

ErrorCodeException exceptions use Boost error_category to describe the error, with a supporting error code enum for the error code.

Public Types

using Category = CAT

Alias for the error category, which much be an error_category

using ErrorCodeEnum = ENUM

Alias for the error code enumeration used by the category

Public Functions

inline explicit ErrorCodeException(ErrorCodeEnum errcode)

Create exception from a error code enum

inline ErrorCodeEnum code() const

The error code enum that the exception corresponds to

inline const char *what() const noexcept override

The error message text, which matches the error category message.

inline virtual error_code errorCode() const noexcept override

Return an error_code corrsponding to the exception’s code

class GLibFileErrorCategory : public boost::system::error_category
#include <PxUtility/GLibFileErrorCode.h>

Error category for GLib GFileError error codes.

Error category

Implements the error_category interface

const char *name() const noexcept override

Returns the error category name as a string

std::string message(int code) const override

Returns the message for the provided error code

Public Static Functions

static const GLibFileErrorCategory &category()

Returns the category instance for the GLibFileErrorCategory

static const char *messageFromErrorCode(GFileError code)

Helper to translate an error code into a message string

class HttpFetch
#include <PxUtility/HttpFetch.h>

A helper class to make simple HTTP requests.

Make a request

static void fetch(const FetchRequest &request, const HandlerFunction &handler)

Make a fetch request asynchronously, calling the handler when complete.

static std::future<FetchResult> fetch(const FetchRequest &request)

Make a fetch request and return a future with the result.

Public Types

using HttpVerb = boost::beast::http::verb

HTTP verb is the underlying Boost/Beast type

using HttpStatus = boost::beast::http::status

HTTP status is the underlying Boost/Beast type

using UrlView = boost::url::url_view_base

Some kind of URL view

using HandlerType = void(FetchResult result)

Define the function signature for request result handlers

using HandlerFunction = std::function<HandlerType>

Define the function type for request result handlers

struct FetchRequest
#include <PxUtility/HttpFetch.h>

The full request structure.

Fields

shared_not_null<PxCore::ProximieContext> pxContext

Proximie context.

RequestParams params

Parameters to use in the request.

RequestFields fields

Fields to use in the request.

Construction

inline explicit FetchRequest(const shared_not_null<PxCore::ProximieContext> &context)

Create a new request, with the required Proximie context

struct FetchResponse
#include <PxUtility/HttpFetch.h>

The response from a fetch request.

Fields

HttpStatus httpStatus = HttpStatus::unknown

HTTP status

std::string valueText

The result value as plain text

boost::optional<json_value> valueJson

If available, the result value parsed from JSON

Construction

FetchResponse() = default

Create an empty response

inline FetchResponse(HttpStatus status, std::string value)

Create a response with a status and result value

struct FetchResult
#include <PxUtility/HttpFetch.h>

The fetch result is the final error code with the fetch response.

Public Members

error_code error

Error, if any

std::shared_ptr<FetchResponse> response

Response, which may be null in the case of extreme fetch errors

class RequestFields
#include <PxUtility/HttpFetch.h>

Request fields, which are typically common/reused across requests.

Construction

RequestFields() = default

Default empty constructor.

inline explicit RequestFields(std::shared_ptr<IAccessTokenProvider> tokenProvider)

Commonly created with a token provider.

Parameter values

Note: setter methods are chainable

inline RequestFields &tokenProvider(std::shared_ptr<IAccessTokenProvider> set)

Set the access token provider.

inline std::shared_ptr<IAccessTokenProvider> tokenProvider() const

Get the access token provider.

inline RequestFields &userAgent(string_view set)

Set the user agent - if empty, the context’s default will be used.

inline const std::string &userAgent() const

Get the user agent.

class RequestParams
#include <PxUtility/HttpFetch.h>

Request parameters define the specifics of a request.

Helpers

static RequestParams fromUrl(HttpVerb verb, const UrlView &url, string_view body = {})

Create request params from a source URL string

Parameter values

Note: setter methods are chainable

inline RequestParams &verb(HttpVerb set)

Set the verb/method.

inline HttpVerb verb() const

Get the verb/method.

inline RequestParams &host(string_view set)

Set the host.

inline const std::string &host() const

Get the host.

inline RequestParams &port(PxUtility::NetworkPort_t set)

Set the port.

inline PxUtility::NetworkPort_t port() const

Get the port.

inline PxUtility::NetworkPort_t portOrDefault(PxUtility::NetworkPort_t def) const

Get port, or a given default if not set.

inline RequestParams &target(string_view set)

Set the target/path.

inline const std::string &target() const

Get the target/path.

inline RequestParams &body(string_view set)

Set the body.

inline const std::string &body() const

Get the body.

class HttpResponseClassErrorCategory : public boost::system::error_category
#include <PxUtility/HttpResponseClassErrorCode.h>

Error category for HttpResponseClassErrorCode.

Error category

Implements the error_category interface

const char *name() const noexcept override

Returns the error category name as a string

std::string message(int code) const override

Returns the message for the provided error code

Public Static Functions

static const HttpResponseClassErrorCategory &category()

Returns the category instance for the HttpResponseClassErrorCategory

class IAccessTokenProvider
#include <PxUtility/IAccessTokenProvider.h>

An interface to provide fresh access tokens on demand.

This simple interface is used by the SDK where HTTP requests need to be made using access tokens. The mechanism of obtaining and refreshing an access token is an application implementation decision, so the caller needs to provide an IAccessTokenProvider-derived object which implements the interface.

The concrete provider should arrange to have a fresh, valid token available to respond to ad hoc requests. Typically this involves obtaining an initial access token (e.g. via some authentication flow), and to note when the token expires in order to pre-emptively refresh it.

See Authentication & authorisation for more details on authentication and access tokens.

Public Functions

virtual const char *accessToken() const = 0

Obtain a fresh, valid access token string on demand.

class JsonSerializer
#include <PxUtility/JsonSerializer.h>

A serializer that allows data interchange between typed C++ structs and JSON objects using Boost’s JSON support.

Implementing serializable objects

Providing the C++ value struct (or class) implement a suitable serialization function, class JsonSerializer can be used serialize from a Boost JSON value into the C++ value, or create a JSON value from a C++ value.

The C++ serializable values are objects that implement a serialize function: 

void serialize(JsonSerializer& serializer);

This function is called for serialization to and from the object. The implementation simply calls JsonSerializer::serialize (or variants) for each of it’s own members. This includes serializing members which are themselves C++ objects that implement serialize, allowing object hierarchies to be easily serialized.

Serializing between C++ and JSON objects

Creation of a JSON object from a serializable source object should always succeed except for exceptional (throwing) errors (e.g. memory allocation). The philosophy here is that an object should always be able to reliably create a JSON representation of itself.

However, we assume that any JSON values that we are attempting to serialize into a C++ object can fail, the assumption being the source of the JSON is not within application control and so may not match the required format/structure.

For this reason, there are variants for reading from JSON values (see the full JsonSerializer documentation below for details). Briefly, readObject... function variants should be used where it’s considered an error if the serialization fails, and they return an error-code or throw in case of failure. The check... function variants are used when the JSON object type is not known or guaranteed, and so it’s not an error if serialization fails.

Member serialization

JsonSerializer::serialize (and variants) are bidirectional, and will serialize into or read from the C++ object depending on the serializer’s purpose. This allows C++ objects to implement a single serialization function, ensuring consistent read & write behaviour.

JsonSerializer::serialize returns the JsonSerializer object itself, allowing the serialization calls to be chained rather than making a call per member.

void serialize(JsonSerializer& serializer) {
    serializer
        .serialize("foo", fooMember)
        .serialize("bar", barMember);
}

JsonSerializer::serialize supports a variety of types, including JSON “plain old data” types (numbers, strings, Booleans, …) as well as any C++ object that itself supports a serialize member function as described above.

enum class WhenKeyMissing

How to handle a missing key when reading JSON into a C++ object.

Values:

enumerator UseDefault

When missing, use a default-constructed value.

enumerator Throw

Missing keys are an error.

template<typename ENUM>
using validateEnum = bool(int64_t value, ENUM &set)

A function used with JsonSerializer::serializeEnum to validate an integer value is a valid enum value.

Template Parameters:

ENUM – The type of the enum being serialized

template<typename T>
inline JsonSerializer &serialize(string_view key, T &value, WhenKeyMissing missing = WhenKeyMissing::Throw)

Serialize a C++ value with the given key to the serializer.

Template Parameters:

T – The type of the member being serialized

Parameters:

  • key – [in] The key that will be used in the JSON object

  • value – [inout] The member value to be serialized

  • missing – [in] How to handle a missing key when reading from JSON

Returns:

The JsonSerializer object, allowing chained calls

template<typename T>
inline JsonSerializer &serialize(string_view key, boost::optional<T> &value)

Serialization for optional values.

JsonSerializer supports optional values. When serializing into the C++ object, if the JSON key is absent then the target value will be reset. When serializing from the C++ object, if the value is absent, no JSON value is written.

Template Parameters:

T – The type of the member being serialized

Parameters:

  • key – [in] The key that will be used in the JSON object

  • value – [inout] The member value to be serialized

Returns:

The JsonSerializer object, allowing chained calls

template<typename ENUM>
JsonSerializer &serializeEnum(string_view key, ENUM &value, validateEnum<ENUM> isValid, WhenKeyMissing missing = WhenKeyMissing::Throw)

Support serialization of enum values.

When serializing enum values as integers in JSON, this variant adds a validation function to confirm an incoming value is a valid enum value.

Template Parameters:

ENUM – The type of the enum being serialized

Parameters:

  • key – [in] The key that will be used in the JSON object

  • value – [inout] The member value to be serialized

  • isValid – [in] A validation function for the enum type

  • missing – [in] How to handle a missing key when reading from JSON

Returns:

The JsonSerializer object, allowing chained calls

template<typename ENUM>
JsonSerializer &serializeEnum(string_view key, boost::optional<ENUM> &value, validateEnum<ENUM> isValid)

Support serialization of optional enum values.

This variation accepts enum values that are optional. If the value is absent when writing to JSON, no key is written. If the incoming JSON does not have the key, the enum value is reset.

JsonSerializer &serializeAsReadOnly(string_view key, const std::string &value)

Serialize a read-only string value.

A common use case is that a payload string value is read-only:

  • When writing to JSON, write the value as normal

  • When reading from JSON, the value must equal the value in the C++ object.

Parameters:

  • key – [in] The key that will be used in the JSON object

  • value – [inout] The member value to be serialized

Returns:

The JsonSerializer object, allowing chained calls

JsonSerializer &serializeAsFixed(string_view key, string_view value)

Serialize a constant string value.

A common use case is that a payload string value is fixed for the type. This is similar to JsonSerializer::serializeAsReadOnly except that the C++ object does not need to include the value as a data member and can just provide the value required as a constant.

  • When writing to JSON, write the constant value

  • When reading from JSON, the value must equal constant value

Parameters:

  • key – [in] The key that will be used in the JSON object

  • value – [in] The constant value to be written or expected to be read

Returns:

The JsonSerializer object, allowing chained calls

Serialize JSON into C++ object

template<typename T>
static inline void readObjectFromJsonOrThrow(T &target, const json_object &source)

Read from a source JSON object into a typed target object. In case of error, this function will throw an exception.

Template Parameters:

T – The type of the C++ object being serialized into

Parameters:

  • target – [out] The target C++ object to be serialized into

  • source – [in] The source JSON object to be read from

template<typename T>
static inline outcome::result<void> readObjectFromJson(T &target, const json_object &source)

Read from a source JSON object into a typed target object.

Template Parameters:

T – The type of the C++ object being serialized into

Parameters:

  • target – [out] The target C++ object to be serialized into

  • source – [in] The source JSON object to be read from

Returns:

outcome::result<void> with the error in case of failure

template<typename T>
static inline outcome::result<std::shared_ptr<T>> readSharedPtrFromJson(const json_object &source)

Read from a source JSON object and return a typed shared pointer of the resulting object.

Template Parameters:

T – The type of the C++ object being serialized into

Parameters:

source – [in] The source JSON object to be read from

Returns:

outcome::result<std::shared_ptr<T>> with the error in case of failure

template<typename T>
static inline bool checkReadObjectFromJson(T &target, const json_object &source)

Check if a source JSON object was serialized into a typed target object.

Template Parameters:

T – The type of the C++ object being serialized into

Parameters:

  • target – [out] The target C++ object to be serialized into

  • source – [in] The source JSON object to be read from

Returns:

true if successful, false in case of failure

Serialize C++ object into JSON

template<typename T>
static inline void makeJsonFromObject(json_object &target, const T &source)

Generate a JSON object representation of a typed source object.

This function throws in case of failure, as types should always be able to reliably serialize themselves except for exceptional reasons. The target JSON object remains unchanged in case of serialization failure.

Template Parameters:

T – The type of the C++ object being serialized from

Parameters:

  • target – [out] The target JSON value to be set

  • source – [in] The source C++ object to be serialized from

JSON/string conversion

template<typename T>
static inline std::string jsonStringFromObject(const T &source)

Read a source object typed T and convert to a JSON string representation.

This function throws in case of failure, as types should always be able to reliably serialize themselves except for exceptional reasons.

Template Parameters:

T – The type of the C++ object being serialized from

Parameters:

source – [in] The source C++ object to convert

Returns:

The object, converted to JSON and serialized into a string

static inline std::string stringFromJsonObject(const json_object &object)

Helper function to convert a JSON object into a plain string.

Parameters:

object – [in] The source JSON object to read

Returns:

The stringified form of the JSON object as a std::string.

static outcome::result<void> parseJsonObjectString(json_object &target, string_view json)

Helper function to parse a string into a target JSON object.

Convenience function since object serialization expects JSON objects rather than general values.

Parameters:

  • target – [out] The target JSON value to be set

  • json – [in] A JSON string value to parse

Returns:

outcome::result<void>

Public Types

using LogSeverity = PxCore::PxLogger::LogSeverity

Alias for PxLogger.

class JsonSerializerErrorCategory : public boost::system::error_category
#include <PxUtility/JsonSerializerErrorCode.h>

Error category for JsonSerializerErrorCode.

Error category

Implements the error_category interface

const char *name() const noexcept override

Returns the error category name as a string

std::string message(int code) const override

Returns the message for the provided error code

Public Types

using ErrorCodeEnum = JsonSerializerErrorCode

Alias for the enum type used

Public Static Functions

static const JsonSerializerErrorCategory &category()

Returns the category instance for the JsonSerializerErrorCategory

static const char *messageFromErrorCode(ErrorCodeEnum code)

Helper to translate an error code into a message string

template<typename T>
class Point
#include <PxUtility/Point.h>

General purpose point/position class.

Public Types

using PointValueType = T

Type of the point values.

Public Functions

constexpr Point() = default

Default constructor creates zero point.

inline constexpr Point(T x, T y)

May construct with x and y values.

inline Point &reset()

Reset the point to zero.

inline T x() const

Get the x coordinate.

inline Point &x(T set)

Set the x coordinate.

inline T y() const

Get the y coordinate.

inline Point &y(T set)

Set the y coordinate.

inline bool isZero() const

Test for zero-point.

template<typename T>
class SharedPtrFactory
#include <PxUtility/ptr-utils.h>

Helper to make a shared pointer for a type.

This is useful for creating shared pointers for types that are have private constructors to enforce factory creation.

Public Static Functions

template<typename ...ARGS>
static inline shared_not_null<T> create(ARGS&&... args)

Create a non-null shared pointer for the factory type.

template<typename T>
class Rectangle
#include <PxUtility/Rectangle.h>

General purpose rectangle class.

Public Functions

Rectangle() = default

Default constructor creates an “empty” rectangle (all zero values)

inline Rectangle &reset()

Reset the rectangle to an “empty” state (all zero values)

inline T left() const

Get the left side of the rectangle.

inline Rectangle &left(T set)

Set the left side of the rectangle.

inline T top() const

Get the top side of the rectangle.

inline Rectangle &top(T set)

Set the top side of the rectangle.

inline T right() const

Get the right side of the rectangle.

inline Rectangle &right(T set)

Set the right side of the rectangle.

inline T bottom() const

Get the bottom side of the rectangle.

inline Rectangle &bottom(T set)

Set the bottom side of the rectangle.

inline bool empty() const

Test for “empty” (all zero values) rectangle.

template<typename U>
bool convertTo(Rectangle<U> &out) const

Convert a rectangle of one underlying integer type to another.

Returns true if converted, false if the original values are out of range for the new type

inline std::string toString() const

Convert to a string representation.

template<typename T>
class Size
#include <PxUtility/Size.h>

General purpose size class.

Public Types

using SizeType = T

Type of the size width and height.

Public Functions

constexpr Size() = default

Default constructor creates an “empty” size value (all zero values)

inline constexpr Size(T width, T height)

May construct with a width and height.

inline Size &reset()

Reset the size to “empty” (all zero values)

inline T width() const

Get the width of the size value.

inline Size &width(T set)

Set the width of the size value.

inline T height() const

Get the height of the size value.

inline Size &height(T set)

Set the height of the size value.

inline Size &operator+=(const Size &other)

Add another size to this one.

inline Size &operator-=(const Size &other)

Subtract another size from this one.

inline Size &flip()

Flip/swap the width and height.

inline bool empty() const

Test for “empty” (all zero values)

template<typename U>
inline bool convertTo(Size<U> &out) const

Convert a size of one underlying integer type to another.

Returns true if converted, false if the original values are out of range for the new type

inline std::string toString() const

Get string representation of the size.

template<bool B, class T = void>
struct disable_if
template<class T>
struct disable_if<false, T>
#include <PxUtility/traits-utility.h>

Implements a disable_if as the inverse of enable_if.