Provides basic helpers for reading and writing UTF-8 encoded strings. More...

Namespaces
namespace	containers

Classes
class	Allocator

class	BasicInlineDeque

class	BasicInlineDeque< ValueType, SizeType, containers::internal::kGenericSized >

class	BasicInlineDequeStorage

class	BasicInlineDequeStorage< ValueType, SizeType, kCapacity, false >

class	BasicInlineDequeStorage< ValueType, SizeType, kCapacity, true >

class	BasicInlineQueue

class	BasicInlineQueue< ValueType, SizeType, containers::internal::kGenericSized >

class	BasicInlineVarLenEntryQueue

class	BasicInlineVarLenEntryQueue< T, containers::internal::kGenericSized >

class	ByteBuffer
	ByteBuffers declare a buffer along with a ByteBuilder. More...

class	ByteBuilder

struct	ConstexprTag

class	Deallocator
	Abstract interface for releasing memory. More...

class	InlineBasicString
	`pw::InlineBasicString` is a fixed-capacity version of `std::basic_string`. In brief: More...

class	InlineBasicString< T, string_impl::kGeneric >

class	IntrusiveForwardList

class	IntrusiveMap

class	IntrusiveMultiMap

class	IntrusiveMultiSet

class	IntrusiveSet

class	JsonArray

class	JsonBuffer

class	JsonBuilder

class	JsonObject

class	JsonValue

class	LinkerSymbol

struct	NaturallyAligned

class	NestedJsonArray

class	NestedJsonObject

class	NoDestructor

class	PackedPtr

class	RuntimeInitGlobal

class	ScopeGuard

class	SharedPtr

class	Status

class	StatusWithSize

class	StringBuffer

class	StringBuilder

class	ThreadAttrs

class	ThreadContext

class	ThreadContext< kExternallyAllocatedThreadStack >

class	ThreadContextFor

class	ThreadStack

class	UniquePtr

class	Vector

class	Vector< T, vector_impl::kGeneric >

struct	VectorStorage

struct	VectorStorage< T, kMaxSize, false >

struct	VectorStorage< T, kMaxSize, true >

class	WeakPtr

Typedefs
template<typename T >
using	AlignedAtomic = std::atomic< NaturallyAligned< T > >

template<typename T , size_t kCapacity = containers::internal::kGenericSized>
using	InlineDeque = BasicInlineDeque< T, uint16_t, kCapacity >

template<typename T , size_t kCapacity = containers::internal::kGenericSized>
using	InlineQueue = BasicInlineQueue< T, uint16_t, kCapacity >

template<size_t kMaxSizeBytes = containers::internal::kGenericSized>
using	InlineVarLenEntryQueue = BasicInlineVarLenEntryQueue< std::byte, kMaxSizeBytes >
	Variable-length entry queue that uses `std::byte` for the byte type.

template<typename T >
using	IntrusiveList = containers::future::IntrusiveList< T >

template<typename FunctionType >
using	Function = fit::function_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE >

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize>
using	InlineFunction = fit::inline_function< FunctionType, inline_target_size >

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
using	DynamicFunction = fit::function_impl< inline_target_size, false, FunctionType, Allocator >

using	Closure = Function< void()>
	`void`-returning `pw::Function` that takes no arguments.

template<typename FunctionType >
using	Callback = fit::callback_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE >

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize>
using	InlineCallback = fit::inline_callback< FunctionType, inline_target_size >
	Version of `pw::Callback` that exclusively uses inline storage.

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
using	DynamicCallback = fit::callback_impl< inline_target_size, false, FunctionType, Allocator >
	Version of `pw::Callback` that supports dynamic allocation.

template<size_t kCapacity = string_impl::kGeneric>
using	InlineString = InlineBasicString< char, kCapacity >
	`pw::InlineString` is an alias of `pw::InlineBasicString<char>` and is equivalent to `std::string`.

template<size_t kCapacity = string_impl::kGeneric>
using	InlineByteString = InlineBasicString< std::byte, kCapacity >
	`pw::InlineByteString` is an alias of `pw::InlineBasicString<std::byte>`. `InlineByteString` may be used as a simple, efficient byte container.

using	DefaultThreadContext = ThreadContext< thread::backend::kDefaultStackSizeBytes >
	Alias for ThreadContext with the backend's default stack size.

using	ThreadPriority = thread::internal::Priority< thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority >

using	Thread = ::pw::thread::Thread

Functions
constexpr size_t	countl_zero (size_t x) noexcept

constexpr size_t	bit_width (size_t x) noexcept

constexpr size_t	bit_ceil (size_t x) noexcept

class pw::Deallocator	DoGetInfo (InfoType info_type, const void *ptr) override

template<>
StatusWithSize	ToString (const async2::ReadyType &, span< char > buffer)

template<>
StatusWithSize	ToString (const async2::PendingType &, span< char > buffer)

template<typename T >
StatusWithSize	ToString (const async2::Poll< T > &poll, span< char > buffer)

template<>
StatusWithSize	ToString (const async2::Poll<> &poll, span< char > buffer)

bool	IsAlignedAs (const void *ptr, size_t alignment)
	Returns whether the given pointer meets the given alignment requirement.

template<typename T >
bool	IsAlignedAs (const void *ptr)

constexpr size_t	AlignDown (uintptr_t value, size_t alignment)
	Returns the value rounded down to the nearest multiple of alignment.

template<typename T >
constexpr T *	AlignDown (T *value, size_t alignment)
	Returns the value rounded down to the nearest multiple of alignment.

constexpr size_t	AlignUp (uintptr_t value, size_t alignment)
	Returns the value rounded up to the nearest multiple of alignment.

template<typename T >
constexpr T *	AlignUp (T *value, size_t alignment)
	Returns the value rounded up to the nearest multiple of alignment.

constexpr size_t	Padding (size_t length, size_t alignment)
	Returns the number of padding bytes required to align the provided length.

ByteSpan	GetAlignedSubspan (ByteSpan bytes, size_t alignment)

constexpr ByteBuilder::iterator	operator+ (int n, ByteBuilder::iterator it)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator== (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator!= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator< (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator<= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator> (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<typename T , size_t kLhsSize, size_t kRhsSize>
bool	operator>= (const Vector< T, kLhsSize > &lhs, const Vector< T, kRhsSize > &rhs)

template<auto method, typename T >
auto	bind_member (T *instance)

template<typename Function >
	ScopeGuard (Function()) -> ScopeGuard< Function(*)()>

template<typename T , typename A , typename B >
constexpr std::optional< T >	CheckedAdd (A a, B b)

template<typename T , typename Inc >
constexpr bool	CheckedIncrement (T &base, Inc inc)

template<typename T , typename A , typename B >
constexpr std::optional< T >	CheckedSub (A a, B b)

template<typename T , typename Dec >
constexpr bool	CheckedDecrement (T &base, Dec dec)

template<typename T , typename A , typename B >
constexpr std::optional< T >	CheckedMul (A a, B b)

template<typename T >
constexpr T	IntegerDivisionRoundNearest (T dividend, T divisor)

template<class ResultT , size_t kSourceExtentBytes>
internal::SpanFromBytes< ResultT, kSourceExtentBytes >	span_cast (span< std::byte, kSourceExtentBytes > bytes)

template<class ResultT , size_t kSourceExtentBytes>
internal::SpanFromBytes< const ResultT, kSourceExtentBytes >	span_cast (span< const std::byte, kSourceExtentBytes > bytes)

constexpr Status	OkStatus ()

constexpr bool	operator== (const Status &lhs, const Status &rhs)

constexpr bool	operator!= (const Status &lhs, const Status &rhs)

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator== (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator!= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator< (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator<= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator> (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity, size_t kRhsCapacity>
constexpr bool	operator>= (const InlineBasicString< T, kLhsCapacity > &lhs, const InlineBasicString< T, kRhsCapacity > &rhs) noexcept

template<typename T , size_t kLhsCapacity>
constexpr bool	operator== (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator== (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<typename T , size_t kLhsCapacity>
constexpr bool	operator!= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator!= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<typename T , size_t kLhsCapacity>
constexpr bool	operator< (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator< (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<typename T , size_t kLhsCapacity>
constexpr bool	operator<= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator<= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<typename T , size_t kLhsCapacity>
constexpr bool	operator> (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator> (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<typename T , size_t kLhsCapacity>
constexpr bool	operator>= (const InlineBasicString< T, kLhsCapacity > &lhs, const T *rhs)

template<typename T , size_t kRhsCapacity>
constexpr bool	operator>= (const T *lhs, const InlineBasicString< T, kRhsCapacity > &rhs)

template<size_t kBufferSize = 0u, typename... Args>
auto	MakeString (Args &&... args)

system::AsyncCore &	System ()

void	SystemStart (channel::ByteReaderWriter &io_channel)

void	InfiniteLoop ()

Variables
constexpr size_t	kExternallyAllocatedThreadStack

constexpr ConstexprTag	kConstexpr {}

Detailed Description

Provides basic helpers for reading and writing UTF-8 encoded strings.

Typedef Documentation

◆ InlineDeque

template<typename T , size_t kCapacity = containers::internal::kGenericSized>

using pw::InlineDeque = typedef BasicInlineDeque<T, uint16_t, kCapacity>

The InlineDeque class is similar to the STL's double ended queue (std::deque), except it is backed by a fixed-size buffer. InlineDeque's must be declared with an explicit maximum size (e.g. InlineDeque<int, 10>>) but deques can be used and referred to without the max size template parameter (e.g. InlineDeque<int>).

To allow referring to a pw::InlineDeque without an explicit maximum size, all InlineDeque classes inherit from the BasicInlineDequeStorage class, which in turn inherits from InlineDeque<T>, which stores the maximum size in a variable. This allows InlineDeques to be used without having to know their maximum size at compile time. It also keeps code size small since function implementations are shared for all maximum sizes.

◆ InlineQueue

template<typename T , size_t kCapacity = containers::internal::kGenericSized>

using pw::InlineQueue = typedef BasicInlineQueue<T, uint16_t, kCapacity>

The InlineQueue class is similar to std::queue<T, std::deque>, except it is backed by a fixed-size buffer. InlineQueue's must be declared with an explicit maximum size (e.g. InlineQueue<int, 10>>) but deques can be used and referred to without the max size template parameter (e.g. InlineQueue<int>).

pw::InlineQueue is wrapper around pw::InlineDeque with a simplified API and push_overwrite() & emplace_overwrite() helpers.

◆ IntrusiveList

template<typename T >

using pw::IntrusiveList = typedef containers::future::IntrusiveList<T>

A doubly-linked intrusive list.

IntrusiveList<T> is a handle to access and manipulate the list, and IntrusiveList<T>::Item is the type from which the base class items must derive.

As a doubly-linked list, operations such as removal are O(1) in time, and the list may be iterated in either direction. However, the overhead needed is 2*sizeof(T*).

This class is modeled on std::list, with the following differences:

Since items are not allocated by this class, the following methods have no analogue:
- std::list<T>::get_allocator
- std::list<T>::emplace
- std::list<T>::emplace_front
- std::list<T>::emplace_back
- std::list<T>::resize
Methods corresponding to the following take initializer lists of pointer to items rather than the items themselves:
- std::list<T>::(constructor)
- std::list<T>::assign
- std::list<T>::insert
There are no overloads corresponding to the following methods that take r-value references.:
- std::list<T>::insert
- std::list<T>::push_back
- std::list<T>::push_front
- std::list<T>::splice
Since modifying the list modifies the items themselves, methods corresponding to those below only take iterators and not const_iterators:
- std::list<T>::insert
- std::list<T>::erase
- std::list<T>::splice
An additional overload of erase is provided that takes a direct reference to an item.
C++23 methods are not (yet) supported.

Template Parameters

T	Type of intrusive items stored in the list.

◆ Thread

using pw::Thread = typedef ::pw::thread::Thread

pw::thread::Thread will be renamed to pw::Thread. New code should refer to pw::Thread.

◆ ThreadPriority

using pw::ThreadPriority = typedef thread::internal::Priority<thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority>

Represents a thread's priority. Schedulers favor higher priority tasks when determining which thread to run. Scheduling policies differ, but a common default policy for real-time operating systems is preemptive scheduling, where the highest priority ready thread is always selected to run. If there are multiple tasks with the same priority, RTOSes may use round-robin scheduling, where each ready thread at a given priority is given equal opportunity to run.

Priorities may be compared with ==, !=, <, etc. Comparisons occur in terms of the native priorities they represent, but are translated such that logically lower priorities always compare as less than higher priorities, even if the underlying RTOS uses lower numbers for higher priorities.

Function Documentation

◆ CheckedAdd()

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedAdd	(	A	a,
		B	b
	)

constexpr

Adds two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the first addend, `a`.
B	The type of the second addend, `b`.

Parameters

[in]	a	The first addend.
[in]	b	The second addend.

Returns: The sum (a + b) if addition was successful, or nullopt if the addition would overflow.

Note: The template argument must be provided, e.g. pw::CheckedAdd<uint32_t>(...).

◆ CheckedDecrement()

template<typename T , typename Dec >

constexpr bool pw::CheckedDecrement	(	T &	base,
		Dec	dec
	)

constexpr

Decrements a variable by some amount.

Template Parameters

T	The type of the variable to be decremented.
Dec	The type of the variable to subtract.

Parameters

[in]	base	The variable to be decremented.
[in]	inc	The number to subtract from `base`.

Returns: True if the subtraction was successful and base was decremented (base -= inc); False if the subtraction would overflow and base is unmodified.

◆ CheckedIncrement()

template<typename T , typename Inc >

constexpr bool pw::CheckedIncrement	(	T &	base,
		Inc	inc
	)

constexpr

Increments a variable by some amount.

Template Parameters

T	The type of the variable to be incremented.
Inc	The type of the variable to add.

Parameters

[in]	base	The variable to be incremented.
[in]	inc	The number to add to `base`.

Returns: True if the addition was successful and base was incremented (base += inc); False if the addition would overflow and base is unmodified.

◆ CheckedMul()

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedMul	(	A	a,
		B	b
	)

constexpr

Multiplies two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the first factor, `a`.
B	The type of the second factor, `b`.

Parameters

[in]	a	The first factor.
[in]	b	The second factor.

Returns: The product (a * b) if multiplication was successful, or nullopt if the multiplication would overflow.

Note: The template argument must be provided, e.g. pw::CheckedMul<uint32_t>(...).

◆ CheckedSub()

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedSub	(	A	a,
		B	b
	)

constexpr

Subtracts two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the minuend, `a`.
B	The type of the subtrahend, `b`.

Parameters

[in]	a	The minuend (the number from which `b` is subtracted).
[in]	b	The subtrahend (the number subtracted from `a`).

Returns: The difference (a - b) if subtraction was successful, or nullopt if the subtraction would overflow.

Note: The template argument must be provided, e.g. pw::CheckedSub<uint32_t>(...).

◆ GetAlignedSubspan()

ByteSpan pw::GetAlignedSubspan	(	ByteSpan	bytes,
		size_t	alignment
	)

Returns the largest aligned subspan of a given byte span.

The subspan will start and end on alignment boundaries.

Returns: A ByteSpan within bytes aligned to alignment, or an empty ByteSpan if alignment was not possible.

◆ InfiniteLoop()

void pw::InfiniteLoop ( )

inline

Loops infinitely. Call as pw_InfiniteLoop() in C.

Infinite loops without side effects are undefined behavior. Use pw::InfiniteLoop in place of an empty while (true) {} or for (;;) {}.

◆ IntegerDivisionRoundNearest()

template<typename T >

constexpr T pw::IntegerDivisionRoundNearest	(	T	dividend,
		T	divisor
	)

constexpr

Performs integer division and rounds to the nearest integer. Gives the same result as std::round(static_cast<double>(dividend) / static_cast<double>(divisor)), but requires no floating point operations and is constexpr.

embed:rst:leading-asterisk
 
*  .. warning::
* 
*     ``signed`` or ``unsigned`` ``int``, ``long``, or ``long long`` operands
*     overflow if:
* 
*     - the quotient is positive and ``dividend + divisor/2`` overflows, or
*     - the quotient is negative and ``dividend - divisor/2`` overflows.
* 
*     To avoid overflow, do not use this function with very large
*     operands, or cast ``int`` or ``long`` to a larger type first. Overflow
*     cannot occur with types smaller than ``int`` because C++ implicitly
*     converts them to ``int``.
*

◆ IsAlignedAs()

template<typename T >

bool pw::IsAlignedAs ( const void * ptr )

Returns whether the given pointer meets the alignment requirement for the given type.

◆ OkStatus()

constexpr Status pw::OkStatus ( )

constexpr

Returns an

embed:rst:inline :c:enumerator:`OK`

status. Equivalent to Status() or Status(PW_STATUS_OK). This function is used instead of a Status::Ok() function, which would be too similar to Status::ok().

◆ span_cast()

template<class ResultT , size_t kSourceExtentBytes>

internal::SpanFromBytes< const ResultT, kSourceExtentBytes > pw::span_cast ( span< const std::byte, kSourceExtentBytes > bytes )

Casts a pw::span<const std::byte> (ConstByteSpan) to a span of a different const type.

This function is only safe to use if the underlying data is actually of the specified type. You cannot safely use this function to reinterpret e.g. a raw byte array from malloc() as a span of integers.

This function is essentially the inverse of pw::as_bytes.

If kSourceExtentBytes is dynamic_extent, the returned span also has a dynamic extent. Otherwise, the returned span has a static extent of kSourceExtentBytes / sizeof(ResultT).

Template Parameters

ResultT	The type of the returned span. Must be one byte to avoid misuse and violation of the strict aliasing rule. This restriction might be lifted in the future.
kSourceExtentBytes	The extent of the source byte span. This is normally inferred and need not be explicitly provided.

◆ System()

system::AsyncCore & pw::System ( )

inline

Returns a reference to the global pw_system instance. pw::System() provides several features for applications: a memory allocator, an async dispatcher, and a RPC server.

◆ SystemStart()

void pw::SystemStart ( channel::ByteReaderWriter & io_channel )

Starts running pw_system:async with the provided IO channel. This function never returns.

Variable Documentation

◆ kConstexpr

constexpr ConstexprTag pw::kConstexpr {}

inlineconstexpr

Value used to select a constexpr constructor tagged with pw::ConstexprTag.

◆ kExternallyAllocatedThreadStack

constexpr size_t pw::kExternallyAllocatedThreadStack

inlineconstexpr

Initial value:

=

std::numeric_limits<size_t>::max()

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ InlineDeque

◆ InlineQueue

◆ IntrusiveList

◆ Thread

◆ ThreadPriority

Function Documentation

◆ CheckedAdd()

◆ CheckedDecrement()

◆ CheckedIncrement()

◆ CheckedMul()

◆ CheckedSub()

◆ GetAlignedSubspan()

◆ InfiniteLoop()

◆ IntegerDivisionRoundNearest()

◆ IsAlignedAs()

◆ OkStatus()

◆ span_cast()

◆ System()

◆ SystemStart()

Variable Documentation

◆ kConstexpr

◆ kExternallyAllocatedThreadStack