![]() |
LibraryLink Utilities
3.0.1
Modern C++ wrapper over LibraryLink and WSTP
|
Wrapper class over WSTP with a stream-like interface.
WSStream resides in LLU namespace, whereas other WSTP-related classes can be found in LLU::WS namespace.
| EncodingIn | - default encoding to use when reading strings from WSTP |
| EncodingOut | - default encoding to use when writing strings to WSTP |
#include <WSStream.hpp>
Public Types | |
| using | StreamToken = WSStream &(*)(WSStream &) |
| Type of elements that can be sent via WSTP with no arguments, for example WS::Flush. More... | |
| using | BidirStreamToken = WSStream &(*)(WSStream &, WS::Direction) |
| Type of elements that can be either sent or received via WSTP with no arguments, for example WS::Rule. More... | |
| using | LoopbackData = std::pair< std::string, WSLINK > |
| Type of data stored on the stack to facilitate sending expressions of a priori unknown length. More... | |
Public Member Functions | |
| WSStream (WSLINK mlp) | |
| Constructs new WSStream. More... | |
| WSStream (WSLINK mlp, int argc) | |
Constructs new WSStream and checks whether there is a list of argc arguments on the LinkObject waiting to be read. More... | |
| WSStream (WSLINK mlp, const std::string &head, int argc) | |
Constructs new WSStream and checks whether there is a function with head head and argc arguments on the LinkObject waiting to be read. More... | |
| ~WSStream ()=default | |
| Default destructor. More... | |
| WSLINK & | get () noexcept |
| Returns a reference to underlying low-level WSTP handle. More... | |
| template<typename Iterator , typename = enable_if_input_iterator<Iterator>> | |
| void | sendRange (Iterator begin, Iterator end) |
| Sends any range as List. More... | |
| template<typename Iterator , typename = enable_if_input_iterator<Iterator>> | |
| void | sendRange (Iterator begin, Iterator end, const std::string &head) |
| Sends a range of elements as top-level expression with arbitrary head. More... | |
| WSStream & | operator<< (StreamToken f) |
| Sends a stream token via WSTP. More... | |
| WSStream & | operator<< (BidirStreamToken f) |
| Sends a bidirectional stream token via WSTP. More... | |
| WSStream & | operator<< (const WS::Symbol &s) |
| Sends a top-level symbol via WSTP. More... | |
| WSStream & | operator<< (const WS::Function &f) |
| Sends a top-level function via WSTP, function arguments should be sent immediately after. More... | |
| WSStream & | operator<< (const WS::Missing &f) |
| Sends a top-level expression of the form Missing["reason"]. More... | |
| WSStream & | operator<< (const WS::BeginExpr &expr) |
| Starts sending a new expression where the number of arguments is not known a priori. More... | |
| WSStream & | operator<< (const WS::DropExpr &expr) |
| Drops current expression that was initiated with BeginExpr. More... | |
| WSStream & | operator<< (const WS::EndExpr &expr) |
| Ends current expression that was initiated with BeginExpr, prepends the head from BeginExpr and sends everything to the "parent" link. More... | |
| WSStream & | operator<< (bool b) |
| Sends a boolean value via WSTP, it is translated to True or False in Mathematica. More... | |
| WSStream & | operator<< (mint i) |
| Sends a mint value. More... | |
| template<typename T > | |
| WSStream & | operator<< (const WS::ArrayData< T > &a) |
| Sends a WSTP array. More... | |
| template<typename T > | |
| WSStream & | operator<< (const WS::ListData< T > &l) |
| Sends a WSTP list. More... | |
| template<typename T , typename D > | |
| WSStream & | operator<< (const std::unique_ptr< T, D > &p) |
| Sends an object owned by unique pointer. More... | |
| template<typename T > | |
| WSStream & | operator<< (const std::vector< T > &l) |
| Sends a std::vector via WSTP, it is interpreted as a List in Mathematica. More... | |
| template<WS::Encoding E> | |
| WSStream & | operator<< (const WS::StringData< E > &s) |
| Sends a WSTP string. More... | |
| template<WS::Encoding E, typename T > | |
| WSStream & | operator<< (const WS::PutAs< E, T > &wrp) |
| Sends all strings within a given object using specified character encoding. More... | |
| template<typename T > | |
| WSStream & | operator<< (const std::basic_string< T > &s) |
| Sends std::basic_string. More... | |
| template<typename T , std::size_t N, typename = std::enable_if_t<WS::StringTypeQ<T>>> | |
| WSStream & | operator<< (const T(&s)[N]) |
| Sends a character array (or a string literal) More... | |
| WSStream & | operator<< (const char *s) |
| Sends a C-string. More... | |
| template<typename K , typename V > | |
| WSStream & | operator<< (const std::map< K, V > &map) |
| Sends a std::map via WSTP, it is translated to an Association in Mathematica. More... | |
| template<typename T , typename = std::enable_if_t<std::is_arithmetic_v<T>>> | |
| WSStream & | operator<< (T value) |
| Sends a scalar value (int, float, double, etc) if it is supported by WSTP If you need to send value of type not supported by WSTP (like unsigned int) you must either explicitly cast or provide your own overload. More... | |
| template<typename Container , typename = std::void_t< decltype(std::declval<Container>().begin(), std::declval<Container>().end(), std::declval<Container>().size())>> | |
| WSStream & | operator<< (const Container &c) |
| Sends any container (a class with begin(), end() and size()) as List. More... | |
| WSStream & | operator>> (BidirStreamToken f) |
| Receives a bidirectional stream token via WSTP. More... | |
| WSStream & | operator>> (const WS::Symbol &s) |
| Receives a symbol from WSTP. More... | |
| WSStream & | operator>> (WS::Symbol &s) |
| Receives a symbol from WSTP. More... | |
| WSStream & | operator>> (const WS::Function &f) |
| Receives a function from WSTP. More... | |
| WSStream & | operator>> (WS::Function &f) |
| Receives a function from WSTP. More... | |
| WSStream & | operator>> (bool &b) |
| Receives a True or False symbol from Mathematica and converts it to bool. More... | |
| WSStream & | operator>> (mint &i) |
| Receives a mint value. More... | |
| template<typename T > | |
| WSStream & | operator>> (WS::ArrayData< T > &a) |
| Receives a WSTP array. More... | |
| template<typename T > | |
| WSStream & | operator>> (WS::ListData< T > &l) |
| Receives a WSTP list. More... | |
| template<typename T > | |
| WSStream & | operator>> (std::vector< T > &l) |
| Receives a List from WSTP and assigns it to std::vector. More... | |
| template<WS::Encoding E = EncodingIn> | |
| WSStream & | operator>> (WS::StringData< E > &s) |
| Receives a WSTP string. More... | |
| template<typename T > | |
| WSStream & | operator>> (std::basic_string< T > &s) |
| Receives std::basic_string. More... | |
| template<WS::Encoding E, typename T > | |
| WSStream & | operator>> (WS::GetAs< E, T > wrp) |
| Receives a value of type T. More... | |
| template<typename K , typename V > | |
| WSStream & | operator>> (std::map< K, V > &map) |
| Receives a std::map via WSTP. More... | |
| template<typename T , typename = std::enable_if_t<std::is_arithmetic_v<T>>> | |
| WSStream & | operator>> (T &value) |
| Receives a scalar value (int, float, double, etc) if it is supported by WSTP If you need to receive value of type not supported by WSTP (like unsigned int) you must either explicitly cast or provide your own overload. More... | |
| using LLU::WSStream::BidirStreamToken = WSStream& (*)(WSStream&, WS::Direction) |
Type of elements that can be either sent or received via WSTP with no arguments, for example WS::Rule.
| using LLU::WSStream::LoopbackData = std::pair<std::string, WSLINK> |
Type of data stored on the stack to facilitate sending expressions of a priori unknown length.
| using LLU::WSStream::StreamToken = WSStream& (*)(WSStream&) |
Type of elements that can be sent via WSTP with no arguments, for example WS::Flush.
|
explicit |
Constructs new WSStream.
| [in] | mlp | - low-level object of type WSLINK received from LibraryLink |
| LLU::WSStream::WSStream | ( | WSLINK | mlp, |
| int | argc | ||
| ) |
Constructs new WSStream and checks whether there is a list of argc arguments on the LinkObject waiting to be read.
| [in] | mlp | - low-level object of type WSLINK received from LibraryLink |
| [in] | argc | - expected number of arguments |
| LLU::WSStream::WSStream | ( | WSLINK | mlp, |
| const std::string & | head, | ||
| int | argc | ||
| ) |
Constructs new WSStream and checks whether there is a function with head head and argc arguments on the LinkObject waiting to be read.
| [in] | mlp | - low-level object of type WSLINK received from LibraryLink\ |
| [in] | head | - expected head of expression on the Link |
| [in] | argc | - expected number of arguments |
| see | WSStream::testHead(const std::string&, int); |
head
|
default |
Default destructor.
|
inlinenoexcept |
Returns a reference to underlying low-level WSTP handle.
| WSStream& LLU::WSStream::operator<< | ( | BidirStreamToken | f | ) |
Sends a bidirectional stream token via WSTP.
| [in] | f | - an element that can be either sent or received via WSTP with no arguments, for example WS::Rule |
| WSStream& LLU::WSStream::operator<< | ( | bool | b | ) |
Sends a boolean value via WSTP, it is translated to True or False in Mathematica.
| [in] | b | - a boolean value |
| ErrorName::WSPutSymbolError |
| WSStream& LLU::WSStream::operator<< | ( | const char * | s | ) |
|
inline |
Sends any container (a class with begin(), end() and size()) as List.
| Container | - type that is a collection of some elements |
| [in] | c | - container to be sent |
| ErrorName::WSPutContainerError |
| WSStream& LLU::WSStream::operator<< | ( | const std::basic_string< T > & | s | ) |
Sends std::basic_string.
| T | - string character type supported in any of WSPut*String |
| [in] | s | - std::basic_string<T> to be sent |
| ErrorName::WSPutStringError |
| WSStream& LLU::WSStream::operator<< | ( | const std::map< K, V > & | map | ) |
Sends a std::map via WSTP, it is translated to an Association in Mathematica.
| K | - map key type, must be supported in WSStream |
| V | - map value type, must be supported in WSStream |
| [in] | map | - map to be sent as Association |
| ErrorName::WSPutFunctionError | plus whatever can be thrown sending keys and values |
| WSStream& LLU::WSStream::operator<< | ( | const std::unique_ptr< T, D > & | p | ) |
Sends an object owned by unique pointer.
| T | - list element type |
| D | - destructor type, not really relevant |
| [in] | p | - pointer to the object to be sent |
| WSStream& LLU::WSStream::operator<< | ( | const std::vector< T > & | l | ) |
Sends a std::vector via WSTP, it is interpreted as a List in Mathematica.
| T | - vector element type (types supported in WSPut*List will be handled more efficiently) |
| [in] | l | - std::vector to be sent |
| ErrorName::WSPutListError |
| WSStream& LLU::WSStream::operator<< | ( | const T(&) | s[N] | ) |
Sends a character array (or a string literal)
| T | - character type supported in any of WSPut*String |
| N | - length of character array |
| [in] | s | - character array to be sent as String |
| ErrorName::WSPutStringError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::ArrayData< T > & | a | ) |
Sends a WSTP array.
| T | - array element type |
| [in] | a | - ArrayData to be sent |
| ErrorName::WSPutArrayError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::BeginExpr & | expr | ) |
Starts sending a new expression where the number of arguments is not known a priori.
| [in] | expr | - object of class BeginExpr that stores expression head as string |
| WSStream& LLU::WSStream::operator<< | ( | const WS::DropExpr & | expr | ) |
Drops current expression that was initiated with BeginExpr.
| [in] | expr | - object of class DropExpr |
| WSStream& LLU::WSStream::operator<< | ( | const WS::EndExpr & | expr | ) |
Ends current expression that was initiated with BeginExpr, prepends the head from BeginExpr and sends everything to the "parent" link.
| [in] | expr | - object of class EndExpr |
| WSStream& LLU::WSStream::operator<< | ( | const WS::Function & | f | ) |
Sends a top-level function via WSTP, function arguments should be sent immediately after.
| [in] | f | - a function |
| ErrorName::WSPutFunctionError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::ListData< T > & | l | ) |
Sends a WSTP list.
| T | - list element type |
| [in] | l | - ListData to be sent |
| ErrorName::WSPutListError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::Missing & | f | ) |
Sends a top-level expression of the form Missing["reason"].
| [in] | f | - WS::Missing object with a reason |
| ErrorName::WSPutFunctionError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::PutAs< E, T > & | wrp | ) |
Sends all strings within a given object using specified character encoding.
Normally, when you send a string WSStream chooses the appropriate WSTP function based on the EncodingOut template parameter. Sometimes you may want to locally override the output encoding and you can do this by wrapping the object with WS::PutAs<desired encoding, wrapped type> (you can use WS::putAs function to construct WS::PutAs object without having to explicitly specify the second template parameter).
| [in] | wrp | - object to be sent |
| WSStream& LLU::WSStream::operator<< | ( | const WS::StringData< E > & | s | ) |
Sends a WSTP string.
| E | - encoding of the string (it determines which function from WSPut*String family to use) |
| [in] | s | - WS::StringData to be sent |
| ErrorName::WSPutStringError |
| WSStream& LLU::WSStream::operator<< | ( | const WS::Symbol & | s | ) |
Sends a top-level symbol via WSTP.
| [in] | s | - a symbol |
| ErrorName::WSPutSymbolError |
| WSStream& LLU::WSStream::operator<< | ( | mint | i | ) |
| WSStream& LLU::WSStream::operator<< | ( | StreamToken | f | ) |
Sends a stream token via WSTP.
| [in] | f | - a stream token, i.e. an element that can be sent via WSTP with no arguments, for example WS::Flush |
| WSStream& LLU::WSStream::operator<< | ( | T | value | ) |
Sends a scalar value (int, float, double, etc) if it is supported by WSTP If you need to send value of type not supported by WSTP (like unsigned int) you must either explicitly cast or provide your own overload.
| T | - scalar type |
| [in] | value | - numeric value to be sent |
| ErrorName::WSPutScalarError |
| WSStream& LLU::WSStream::operator>> | ( | BidirStreamToken | f | ) |
Receives a bidirectional stream token via WSTP.
| [in] | f | - an element that can be either sent or received via WSTP with no arguments, for example WS::Rule |
| WSStream& LLU::WSStream::operator>> | ( | bool & | b | ) |
Receives a True or False symbol from Mathematica and converts it to bool.
| [out] | b | - argument to which the boolean received from WSTP will be assigned |
| WSStream& LLU::WSStream::operator>> | ( | const WS::Function & | f | ) |
Receives a function from WSTP.
Parameter f must have head and argument count specified and they need to match the head and argument count that was read from WSTP
| [in] | f | - a function with head and argument count specified |
| WSStream& LLU::WSStream::operator>> | ( | const WS::Symbol & | s | ) |
Receives a symbol from WSTP.
Parameter s must have head specified and it has to match the head that was read from WSTP
| [in] | s | - a symbol |
| WSStream& LLU::WSStream::operator>> | ( | mint & | i | ) |
Receives a mint value.
| [in] | i | - argument to which a mint value will be assigned |
| WSStream& LLU::WSStream::operator>> | ( | std::basic_string< T > & | s | ) |
Receives std::basic_string.
| T | - string character type supported in any of WSGet*String |
| [out] | s | - argument to which the std::basic_string<T> received from WSTP will be assigned |
| ErrorName::WSGetStringError |
| WSStream& LLU::WSStream::operator>> | ( | std::map< K, V > & | map | ) |
Receives a std::map via WSTP.
| K | - map key type, must be supported in WSStream |
| V | - map value type, must be supported in WSStream |
| [out] | map | - argument to which the std::map received from WSTP will be assigned |
| ErrorName::WSGetFunctionError | plus whatever can be thrown receiving keys and values |
| WSStream& LLU::WSStream::operator>> | ( | std::vector< T > & | l | ) |
Receives a List from WSTP and assigns it to std::vector.
| T | - vector element type (types supported in WSGet*List will be handled more efficiently) |
| [out] | l | - argument to which the List received from WSTP will be assigned |
| ErrorName::WSGetListError |
| WSStream& LLU::WSStream::operator>> | ( | T & | value | ) |
Receives a scalar value (int, float, double, etc) if it is supported by WSTP If you need to receive value of type not supported by WSTP (like unsigned int) you must either explicitly cast or provide your own overload.
| T | - scalar type |
| [out] | value | - argument to which the value received from WSTP will be assigned |
| ErrorName::WSGetScalarError |
| WSStream& LLU::WSStream::operator>> | ( | WS::ArrayData< T > & | a | ) |
Receives a WSTP array.
| T | - array element type |
| [out] | a | - argument to which the WS::ArrayData received from WSTP will be assigned |
| ErrorName::WSGetArrayError |
| WSStream& LLU::WSStream::operator>> | ( | WS::Function & | f | ) |
Receives a function from WSTP.
If the parameter f has head or argument count set, than it has to match the head or argument count that was read from WSTP
| [in,out] | f | - a function which may have head or argument count specified |
| WSStream& LLU::WSStream::operator>> | ( | WS::ListData< T > & | l | ) |
Receives a WSTP list.
| T | - list element type |
| [out] | l | - argument to which the WS::ListData received from WSTP will be assigned |
| ErrorName::WSGetListError |
| WSStream& LLU::WSStream::operator>> | ( | WS::StringData< E > & | s | ) |
Receives a WSTP string.
| T | - string character type |
| [out] | s | - argument to which the WS::StringData received from WSTP will be assigned |
| ErrorName::WSGetStringError |
| WSStream& LLU::WSStream::operator>> | ( | WS::Symbol & | s | ) |
Receives a symbol from WSTP.
If the parameter s has head specified, then it has to match the head that was read from WSTP, otherwise the head read from WSTP will be assigned to s
| [in,out] | s | - a symbol |
| void LLU::WSStream::sendRange | ( | Iterator | begin, |
| Iterator | end | ||
| ) |
Sends any range as List.
| InputIterator | - type that is an iterator |
| [in] | begin | - iterator to the first element of the range |
| [in] | end | - iterator past the last element of the range |
| void LLU::WSStream::sendRange | ( | Iterator | begin, |
| Iterator | end, | ||
| const std::string & | head | ||
| ) |
Sends a range of elements as top-level expression with arbitrary head.
| InputIterator | - type that is an iterator |
| [in] | begin | - iterator to the first element of the range |
| [in] | end | - iterator past the last element of the range |
| [in] | head | - head of the top-level expression |