ose_stackops.h File Reference

contains functions that manipulate the structure and contents of an OSE bundle and its elements More...

#include "ose.h"
#include "ose_util.h"
#include "ose_errno.h"

Include dependency graph for ose_stackops.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	OSE_START_BUNDLE(B)
#define	OSE_END_BUNDLE(B)

Functions
enum ose_errno	ose_getLastBundleElem (ose_bundle B, int32_t *n, int32_t *offsetn, int32_t *sizen)
enum ose_errno	ose_getLastTwoBundleElems (ose_bundle B, int32_t *n, int32_t *offsetnm1, int32_t *sizenm1, int32_t *offsetn, int32_t *sizen)
enum ose_errno	ose_getLastThreeBundleElems (ose_bundle B, int32_t *n, int32_t *offsetnm2, int32_t *sizenm2, int32_t *offsetnm1, int32_t *sizenm1, int32_t *offsetn, int32_t *sizen)
enum ose_errno	ose_getLastFourBundleElems (ose_bundle B, int32_t *n, int32_t *offsetnm3, int32_t *sizenm3, int32_t *offsetnm2, int32_t *sizenm2, int32_t *offsetnm1, int32_t *sizenm1, int32_t *offsetn, int32_t *sizen)
OSC to C
char *	ose_peekAddress (const ose_bundle B)
	Get the address of the last element.
char	ose_peekMessageArgTypeAtOffset (const ose_bundle B, const int32_t messageoffset)
	Get the type of the last item of the last element, where the offset of the last element is given.
char	ose_peekMessageArgType (const ose_bundle B)
	Get the type of the last item of the last element.
char	ose_peekType (const ose_bundle B)
	Get the type of the last element.
int32_t	ose_peekInt32 (ose_bundle B)
	Get the value of the last int stored in the last message.
float	ose_peekFloat (ose_bundle B)
	Get the value of the last float stored in the last message.
char *	ose_peekString (ose_bundle B)
	Get a pointer to the last string without removing it.
char *	ose_peekBlob (ose_bundle B)
	Get a pointer to the last blob without removing it.
char *	ose_peekSymbol (const ose_bundle B)
	Get a pointer to the last symbol stored in the last message.
double	ose_peekDouble (const ose_bundle B)
	Get the last double without removing it.
int8_t	ose_peekInt8 (const ose_bundle B)
	Get the last signed char without removing it.
uint8_t	ose_peekUInt8 (const ose_bundle B)
	Get the last uint8_t without removing it.
uint32_t	ose_peekUInt32 (const ose_bundle B)
	Get the last unsigned 32-bit int without removing it.
int16_t	ose_peekInt16 (const ose_bundle B)
	Peek at the int16 value of the last element.
uint16_t	ose_peekUInt16 (const ose_bundle B)
	Peek at the uint16 value of the last element.
int64_t	ose_peekInt64 (const ose_bundle B)
	Get the last 64-bit int without removing it.
uint64_t	ose_peekUInt64 (const ose_bundle B)
	Get the last unsigned int without removing it.
struct ose_timetag	ose_peekTimetag (const ose_bundle B)
	Get the last timetag without removing it.
const void *	ose_peekAlignedPtr (ose_bundle B)
	Get the last aligned pointer without removing it.
int32_t	ose_popInt32 (ose_bundle B)
	Get the last int and remove it from the bundle.
float	ose_popFloat (ose_bundle B)
	Get the last float and remove it from the bundle.
int32_t	ose_popString (ose_bundle B, char *buf)
	Get the last string and remove it from the bundle.
int32_t	ose_popBlob (ose_bundle B, char *buf)
	Get the last blob and remove it from the bundle.
int32_t	ose_popSymbol (ose_bundle B, char *buf)
	Get the last symbol and remove it from the bundle.
double	ose_popDouble (ose_bundle B)
	Get the last double and remove it from the bundle.
int8_t	ose_popInt8 (ose_bundle B)
	Get the last char and remove it from the bundle.
uint8_t	ose_popUInt8 (ose_bundle B)
	Get the last uint8_t and remove it from the bundle.
uint32_t	ose_popUInt32 (ose_bundle B)
	Get the last unsigned 32-bit int and remove it from the bundle.
int64_t	ose_popInt64 (ose_bundle B)
	Get the last 64-bit int and remove it from the bundle.
uint64_t	ose_popUInt64 (ose_bundle B)
	Get the last unsigned 64-bit int and remove it from the bundle.
struct ose_timetag	ose_popTimetag (ose_bundle B)
	Get the last timetag and remove it from the bundle.
Stack Operations
void	ose_drop (ose_bundle B)
	Drop the last element.
void	ose_2drop (ose_bundle B)
	Drop the last two elements.
void	ose_dup (ose_bundle B)
	Duplicate the last element.
void	ose_2dup (ose_bundle B)
	Duplicate the last two elements.
void	ose_nip_impl (ose_bundle B, int32_t onm1, int32_t snm1, int32_t on, int32_t sn)
void	ose_nip (ose_bundle B)
	Drop the second to last element.
void	ose_rot (ose_bundle B)
	Move the third to last element to the end.
void	ose_rrot (ose_bundle B)
	Move the last element to the third from the end.
void	ose_over (ose_bundle B)
	Copy the second from the last item over the last.
void	ose_2over (ose_bundle B)
	Copy the second to last pair of elements over the last pair.
void	ose_pick (ose_bundle B)
	Copy an element at an index to the end.
void	ose_roll (ose_bundle B)
	Move an element at an index to the end.
void	ose_pickBottom (ose_bundle B)
	Copy the first element to the end.
void	ose_rollBottom (ose_bundle B)
	Move the first element to the end.
int32_t	ose_pickMatch_impl (ose_bundle B)
	COPY the first element whose address matches the string at the end of the bundle to the end.
void	ose_pickMatch (ose_bundle B)
	COPY the first element whose address equals the string at the end to the end — ose_pickMatch_impl, and PUSH the flag it returns as an int.
int32_t	ose_pickPMatch_impl (ose_bundle B)
void	ose_pickPMatch (ose_bundle B)
	Copy the first element whose address pattern matches the string at the end to the end — ose_pickPMatch_impl, and push the flag it returns as an int.
int32_t	ose_rollMatch_impl (ose_bundle B)
	Move the first element whose address matches the string at the end of the bundle to the end.
void	ose_rollMatch (ose_bundle B)
	Move the first element whose address equals the string at the end to the end — ose_rollMatch_impl, and push the flag it returns as an int.
int32_t	ose_rollPMatch_impl (ose_bundle B)
void	ose_rollPMatch (ose_bundle B)
	Move the first element whose address pattern matches the string at the end to the end — ose_rollPMatch_impl, and push the flag it returns as an int.
void	ose_swap (ose_bundle B)
	Swap the last two elements.
void	ose_2swap (ose_bundle B)
	Swap elements the last two elements with the previous two.
void	ose_tuck (ose_bundle B)
	Copy the last element to the third from last position.
Grouping / Ungrouping
void	ose_bundleAll (ose_bundle B)
	Collect all bundle elements into a single bundle.
void	ose_bundleFromBottom (ose_bundle B)
	Collect elements at the start of the bundle together.
void	ose_bundleFromTop (ose_bundle B)
	Collect elements at the end of the bundle together.
void	ose_clear (ose_bundle B)
	Clear all elements.
void	ose_popAtOffset (ose_bundle B, int32_t o)
	Remove the element at a known offset, which must be the last one.
void	ose_pop (ose_bundle B)
	Pop the last item off the last element and push it onto the end of the bundle as a new element.
void	ose_popAll (ose_bundle B)
	Pop each item off the last element of the bundle.
void	ose_popAllDrop (ose_bundle B)
	Pop each item off the last element of the bundle, and drop the empty element.
void	ose_popAllBundle (ose_bundle B)
	Pop each item off the last element of the bundle, and bundle them together.
void	ose_popAllDropBundle (ose_bundle B)
	Pop each item off the last element of the bundle, drop the empty element, and bundle all new elements together.
void	ose_reverse (ose_bundle B)
	Reverse the items of the last element of the bundle.
void	ose_push (ose_bundle B)
	Push the last element of the bundle onto the element below it.
void	ose_decatenateElemFromEnd (ose_bundle B)
	Split an element in two.
void	ose_decatenateElemFromStart (ose_bundle B)
	Split an element in two.
void	ose_concatenateElems (ose_bundle B)
	Concatenate the last two elements.
void	ose_unpack (ose_bundle B)
	Unpack the last element.
void	ose_unpackDrop (ose_bundle B)
	Unpack the last element and drop it.
Queries
void	ose_countElems (ose_bundle B)
	Get the number of elements.
void	ose_countItems (ose_bundle B)
	Get the number of items in the last element.
void	ose_lengthItem (ose_bundle B)
	Get the length in bytes of the last item of the last element, excluding NULL-padding.
void	ose_lengthsItems (ose_bundle B)
	Get the lengths in bytes of all items of the last element as a list, excluding NULL-padding.
void	ose_sizeElem (ose_bundle B)
	Get the size of the last element in bytes, including NULL-padding, and excluding the size field.
void	ose_sizeItem (ose_bundle B)
	Get the size of the last item of the last element, including NULL-padding.
void	ose_sizesElems (ose_bundle B)
	Get the sizes of all elements as a list, including NULL-padding.
void	ose_sizesItems (ose_bundle B)
	Get the sizes of all items of the last element as a list, including NULL-padding.
void	ose_getAddresses (ose_bundle B)
	Get the address(es) of the last element of the bundle.
void	ose_setTimetag (ose_bundle B)
	Set the bundle's timetag.
void	ose_getTimetag (ose_bundle B)
	Get the bundle's timetag.
void	ose_getTypetags (ose_bundle B)
	Get the typetags of the last element.
void	ose_elemIsBundle (ose_bundle B)
	Determine whether the last element is a bundle.
void	ose_typeof0 (ose_bundle B)
	Get the type signature of the last element of the bundle with no recursion.
void	ose_typeof1 (ose_bundle B)
	Get the type signature of the last element of the bundle with one level of recursion.
void	ose_typeof2 (ose_bundle B)
	Get the type signature of the last element of the bundle with two levels of recursion.
Operations on Bundle Elements and Items
void	ose_setTypetagAtOffset_impl (ose_bundle B, char typetag, int32_t offset)
void	ose_setTypetag_impl (ose_bundle B, char typetag)
	Set the typetag of the last item of the last message.
void	ose_setTypetag (ose_bundle B)
	Set the typetag of the last item of the last message.
void	ose_blobToElemAtOffset (ose_bundle B, int32_t offset)
void	ose_disarmPointers (ose_bundle B)
	Convert a blob to a bundle element.
void	ose_rearmPointers (ose_bundle B)
	The inverse. Restores the TAG, which is not the same as restoring the meaning – an address is only valid in the process it came from.
void	ose_blobToElem (ose_bundle B)
void	ose_blobToType_impl (ose_bundle B, char typetag)
	Convert a blob to a different type.
void	ose_blobToType (ose_bundle B)
	Convert a blob to a different type.
void	ose_toType (ose_bundle B)
void	ose_toInt32 (ose_bundle B)
	Cast a value to a 32-bit integer.
void	ose_toFloat (ose_bundle B)
	Cast a value to a 32-bit float.
void	ose_toString (ose_bundle B)
	Cast a value to a string.
void	ose_toBlob (ose_bundle B)
	Cast a value to a blob.
void	ose_appendByte (ose_bundle B)
void	ose_toSymbol (ose_bundle B)
void	ose_toDouble (ose_bundle B)
void	ose_toInt8 (ose_bundle B)
void	ose_toUInt8 (ose_bundle B)
void	ose_toInt16 (ose_bundle B)
void	ose_toUInt16 (ose_bundle B)
void	ose_toUInt32 (ose_bundle B)
void	ose_toInt64 (ose_bundle B)
void	ose_toUInt64 (ose_bundle B)
void	ose_toTimetag (ose_bundle B)
void	ose_toTrue (ose_bundle B)
void	ose_toFalse (ose_bundle B)
void	ose_toNil (ose_bundle B)
void	ose_toInfinitum (ose_bundle B)
void	ose_concatenateBlobs (ose_bundle B)
	Concatenate two blobs.
void	ose_concatenateStrings (ose_bundle B)
	Concatenate two strings.
void	ose_swapStringToAddress (ose_bundle B)
	Exchange the last string of a message with the address.
void	ose_moveStringToAddress (ose_bundle B)
	Move the last string of a message to the address.
void	ose_decatenateBlobFromEnd_impl (ose_bundle B, int32_t n)
void	ose_decatenateBlobFromEnd (ose_bundle B)
void	ose_decatenateBlobFromStart_impl (ose_bundle B, int32_t n)
void	ose_decatenateBlobFromStart (ose_bundle B)
void	ose_decatenateStringFromEnd_impl (ose_bundle B, int32_t n)
void	ose_decatenateStringFromEnd (ose_bundle B)
void	ose_decatenateStringFromStart_impl (ose_bundle B, int32_t n)
void	ose_decatenateStringFromStart (ose_bundle B)
void	ose_elemToBlob (ose_bundle B)
	Convert the last element into a blob.
void	ose_itemToBlob (ose_bundle B)
	Convert the last item of the last element into a blob.
void	ose_joinStrings (ose_bundle B)
	Join two strings with a separator (string) between them.
void	ose_splitStringFromEnd (ose_bundle B)
void	ose_splitStringFromStart (ose_bundle B)
void	ose_swap4Bytes (ose_bundle B)
void	ose_swap8Bytes (ose_bundle B)
void	ose_swapNBytes (ose_bundle B)
void	ose_trimStringEnd (ose_bundle B)
void	ose_trimStringStart (ose_bundle B)
Matching, Selecting, Routing, and Assignment
void	ose_match (ose_bundle B)
	Compare two strings.
void	ose_pmatch (ose_bundle B)
	Compare two strings using pattern matching.
void	ose_replace (ose_bundle B)
void	ose_assign (ose_bundle B)
void	ose_lookup (ose_bundle B)
void	ose_plookup (ose_bundle B)
void	ose_route1 (ose_bundle B)
	Route messages in a bundle with patterns that match an address.
void	ose_routeWithDelegation (ose_bundle B)
	Route all messages in a bundle with patterns that match one or more addresses.
void	ose_select1 (ose_bundle B)
	Select messages in a bundle with patterns that match an address.
void	ose_selectWithDelegation (ose_bundle B)
	Route all messages in a bundle with patterns that match one or more addresses.
void	ose_gather (ose_bundle B)
	Gather messages from a bundle that match one or more strings.
void	ose_nth (ose_bundle B)
	Copy the nth item of an element.
Element and Item Creation
void	ose_makeBlob (ose_bundle B)
	Create an empty blob of a given size.
void	ose_pushBundle (ose_bundle B)
	Create an empty bundle.
Arithmetic
void	ose_add (ose_bundle B)
	Add the number in the last message to the number in the previous message.
void	ose_sub (ose_bundle B)
	Subtract the number in the second to last message from the number in the last message.
void	ose_mul (ose_bundle B)
	Multiply the number in the last message by the number in the previous message.
void	ose_div (ose_bundle B)
	Divide the number in the second to last message by the number in the last message.
void	ose_mod (ose_bundle B)
	Take the number in the last message modulo the number in the second to last message.
void	ose_pow (ose_bundle B)
	Raise the number in the last message to the power of the number in the second to last message.
void	ose_neg (ose_bundle B)
	Flip the sign of the number in the last message of the bundle.
void	ose_eql (ose_bundle B)
	Compare the numbers in the last two messages for equality.
void	ose_neq (ose_bundle B)
	Compare the numbers in the last two messages for non equality.
void	ose_lte (ose_bundle B)
	Test whether the number in the last message is less than or equal to the number in the second to last message.
void	ose_gt (ose_bundle B)
void	ose_gte (ose_bundle B)
void	ose_min (ose_bundle B)
void	ose_max (ose_bundle B)
void	ose_abs (ose_bundle B)
void	ose_not (ose_bundle B)
void	ose_lt (ose_bundle B)
	Test whether the number in the last message is less than to the number in the second to last message.
void	ose_and (ose_bundle B)
	Test whether the numbers in the last two messages are both non-zero.
void	ose_or (ose_bundle B)
	Test whether at least one of the numbers in the last two messages is non-zero.

C to OSC
#define	OSE_MAXLINE   4096
	Append a message containing a pointer.
void	ose_pushInt32 (ose_bundle B, int32_t v)
	Append a message containing a 32-bit signed int.
void	ose_pushFloat (ose_bundle B, float v)
	Append a message containing a float.
void	ose_pushString (ose_bundle B, const char *const v)
	Append a message containing a string.
void	ose_pushStringBelowAtOffset (ose_bundle B, const int32_t offset, const char *const s, const int32_t slen)
void	ose_pushStringBelow (ose_bundle B, const char *const s, const int32_t slen)
void	ose_pushBlob (ose_bundle B, int32_t size, const char *const blob)
	Append a message containing a blob.
void	ose_pushSymbol (ose_bundle B, const char *const v)
	Append a message containing a symbol.
void	ose_pushDouble (ose_bundle B, double v)
	Append a message containing a double.
void	ose_pushInt8 (ose_bundle B, int8_t v)
	Append a message containing a signed char.
void	ose_pushUInt8 (ose_bundle B, uint8_t v)
	Append a message containing an uint8_t.
void	ose_pushUInt32 (ose_bundle B, uint32_t v)
	Append a message containing an unsigned 32-bit int.
void	ose_pushInt64 (ose_bundle B, int64_t v)
	Append a message containing a signed 64-bit int.
void	ose_pushUInt64 (ose_bundle B, uint64_t v)
	Append a message containing an unsigned 64-bit int.
void	ose_pushTimetag (ose_bundle B, uint32_t sec, uint32_t fsec)
	Append a message containing a timetag.
void	ose_pushTrue (ose_bundle B)
	Append message containing true to B.
void	ose_pushFalse (ose_bundle B)
	Append message containing false to B.
void	ose_pushNil (ose_bundle B)
	Append message containing NIL to B.
void	ose_pushInfinitum (ose_bundle B)
	Append a message containing an infinitum.
void	ose_pushAlignedPtr (ose_bundle B, const void *v)
void	ose_pushLines (ose_bundle B, const char *const src)
	Push each line of src as a string.
void	ose_pushMessage (ose_bundle B, const char *const address, int32_t addresslen, int32_t n,...)
	Append a message.

Detailed Description

contains functions that manipulate the structure and contents of an OSE bundle and its elements

An OSE bundle is simply an OSC bundle that has been organized in a particular way, as described in ose_context.h. The functions in this file assume that the ose_bundle that is passed as their first argument was created using the function ose_newBundleFromCBytes.

The satisfaction of the preconditions stated in the documentation is the responsibility of the caller, and result in undefined behavior if they are not met.

• Elements vs Items
• Notation

Macro Definition Documentation

OSE_END_BUNDLE

#define OSE_END_BUNDLE

(

B

)

Value:

    int32_t ose_stackops_reserved_nbs___ = ose_readSize(B); \
    ose_writeInt32(B, ose_stackops_reserved_o___,           \
                   OSE_BUNDLE_HEADER_LEN +                  \
                   (ose_stackops_reserved_nbs___ -          \
                    ose_stackops_reserved_bs___));          \
}

OSE_MAXLINE

#define OSE_MAXLINE   4096

Append a message containing a pointer.

How long a line of .ose source may be.

OSE_START_BUNDLE

#define OSE_START_BUNDLE

(

B

)

Value:

    {                               \
    ose_pushBundle(B);                                      \
    int32_t ose_stackops_reserved_o___ =                    \
        ose_getLastBundleElemOffset(B);                     \
    int32_t ose_stackops_reserved_bs___ = ose_readSize(B);

Function Documentation

ose_2drop()

void ose_2drop

(

ose_bundle

B

)

Drop the last two elements.

Precondition

B must contain at least two elements.

\( \fn{2DROP}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots } } \), where \(\ela{K-1}{}\) and \(\elb{K}{}\) have been removed.

ose_2dup()

void ose_2dup

(

ose_bundle

B

)

Duplicate the last two elements.

Precondition

B must contain at least two elements.

\( \fn{2DUP}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots, \ela{K-1}{}, \elb{K}{}, \ela{K+1}{}, \elb{K+2}{} } } \)

ose_2over()

void ose_2over

(

ose_bundle

B

)

Copy the second to last pair of elements over the last pair.

Precondition

B must contain at least four elements.

\( \fn{2OVER}{ \BB\elems{ \ldots, \ela{K-3}{}, \elb{K-2}{}, \elc{K-1}{}, \eld{K}{} } }{ \BBtick\elems{ \ldots, \ela{K-3}{}, \elb{K-2}{}, \elc{K-1}{}, \eld{K}{}, \ela{K+1}{}, \elb{K+2}{} } } \)

ose_2swap()

void ose_2swap

(

ose_bundle

B

)

Swap elements the last two elements with the previous two.

Precondition

B must contain at least four elements.

\( \fn{2SWAP}{ \BB\elems{ \ldots, \ela{K-3}{}, \elb{K-2}{}, \elc{K-1}{}, \eld{K}{} } }{ \BBtick\elems{ \ldots, \elc{K-3}{}, \eld{K-2}{}, \ela{K-1}{}, \elb{K}{} } } \)

ose_abs()

void ose_abs

(

ose_bundle

B

)

\(\fnunop{ABS}{abs}\)

ose_add()

void ose_add

(

ose_bundle

B

)

Add the number in the last message to the number in the previous message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{ADD}{+}\)

ose_and()

void ose_and

(

ose_bundle

B

)

Test whether the numbers in the last two messages are both non-zero.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{AND}{\land}\)

ose_blobToType()

void ose_blobToType

(

ose_bundle

B

)

Convert a blob to a different type.

This function converts a blob to a different type by removing its size and changing its typetag.

Precondition

B must not be empty.

The last element must be a message.

The last item must be a blob.

See also

ose_setTypetag

\( \fn{BLOBTOTYPE}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttb} }, \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \itb{}{\type{\tti}}\values{\ttvar} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttvar} } } } \)

ose_blobToType_impl()

void ose_blobToType_impl	(	ose_bundle	B,
		char	typetag
	)

Convert a blob to a different type.

This function converts a blob to a different type by removing its size and changing its typetag.

Precondition

B must not be empty.

The last element must be a message.

The last item must be a blob.

See also

ose_setTypetag_impl

\( \fn{BLOBTOTYPE\_IMPL}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttb} } }, \ttvar }{ \BBtick\elems{ \ldots, \elat{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttvar} } } } \)

ose_bundleAll()

void ose_bundleAll

(

ose_bundle

B

)

Collect all bundle elements into a single bundle.

\( \fn{BUNDLEALL}{ \BB\elems{ \ldots, \ela{K}{} } }{ \BBtick\elems{ \elb{1}{\type{\ttbndl}}\items{ \ldots, \ela{K}{} } } } \)

ose_bundleFromBottom()

void ose_bundleFromBottom

(

ose_bundle

B

)

Collect elements at the start of the bundle together.

The last element, a message containing an int, will be removed, and the value of the int will be used to count elements starting from the beginning of the bundle.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([0, K-1]\) (inclusive), where \(K\) is the total number of elements in the bundle at the time the function is called.

Note

The collection operation is performed after removing the message containing the number of elements to collect, i.e. the message containing that value cannot be included.

A value of 0 will produce an empty bundle at the start of B.

\( \left\{ \begin{array}{lr} \fn{BUNDLEFROMBOTTOM}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \elb{K}{\type{\ttbndl}}\items{}, \ldots } }, & v = 0 \\ \fn{BUNDLEFROMBOTTOM}{ \BB\elems{ \elb{1}{}, \ldots, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \elc{1}{\type{\ttbndl}}\items{ \elb{1}{} } \ldots } }, & v = 1 \\ \fn{BUNDLEFROMBOTTOM}{ \BB\elems{ \elb{1}{}, \ldots, \elc{v}{}, \ldots, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \eld{1}{\type{\ttbndl}}\items{ \elb{1}{}, \ldots, \elc{v}{} } \ldots } }, & v > 1 \end{array} \right. \)

ose_bundleFromTop()

void ose_bundleFromTop

(

ose_bundle

B

)

Collect elements at the end of the bundle together.

The last element, a message containing an int, will be removed, and the value of the int will be used to count elements starting from the end of the bundle.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([0, K-1]\) (inclusive), where \(K\) is the total number of elements in the bundle at the time the function is called.

Note

The collection operation is performed after removing the message containing the number of elements to collect, i.e. the message containing that value cannot be included.

A value of 0 will produce an empty bundle at the end of B.

\( \left\{ \begin{array}{lr} \fn{BUNDLEFROMTOP}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{K}{ \ldots, \elb{K}{\type{\ttbndl}}\items{} } }, & v = 0 \\ \fn{BUNDLEFROMTOP}{ \BB\elems{ \ldots, \elb{K-1}{}, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \elc{K-1}{\type{\ttbndl}}\items{ \itb{}{} } } }, & v = 1 \\ \fn{BUNDLEFROMTOP}{ \BB\elems{ \ldots, \elb{K-v}{}, \ldots, \elc{K-1}{}, \ela{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \eld{K-v}{\type{\ttbndl}}\items{ \elb{1}{}, \ldots, \elc{v}{} } } }, & v > 1 \end{array} \right. \)

ose_clear()

void ose_clear

(

ose_bundle

B

)

Clear all elements.

\( \fn{CLEAR}{ \BB\elems{\ldots} }{ \BBtick\elems{} } \)

ose_concatenateBlobs()

void ose_concatenateBlobs

(

ose_bundle

B

)

Concatenate two blobs.

Precondition

B must not be empty.

The last element must be a message.

The last two items of the message must be blobs.

Note

This function does not include any NULL padding between the blobs.

\( \fn{CONCATENATEBLOBS}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg(\ldots, \type{\ttb}_{L-1}, \type{\ttb}_{L})}}\items{ \ldots, \ita{L-1}{\type{\ttb}}, \itb{L}{\type{\ttb}} } } }{ \BBtick\elems{ \ldots, \itat{K}{\type{\ttmsg}}\items{ \ldots, \ita{}{}\itb{L-1}{\type{\ttb}} } } } \)

ose_concatenateElems()

void ose_concatenateElems

(

ose_bundle

B

)

Concatenate the last two elements.

This function behaves identically to ose_push, unless the two elements are both bundles, in which case the elements of the last are pushed onto the second to last.

See also

ose_push

\( \fnname{CONCATENATEELEMS}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttvar}}\items{ \ita{1}{}, \ldots, \itb{L}{} }, \elb{K}{\type{\ttvar}}\items{ \itc{1}{}, \ldots, \itd{M}{} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{}\items{ \ita{1}{}, \ldots, \itb{L}{}, \ldots, \itc{L+1}{}, \ldots, \itd{L+M}{} } } }, \text{ for } \ttvar = \ttbndl \text{ and} \\ \fnmapping{ \BB }{ \fnname{PUSH}\fninput{\BB} } \text{ otherwise.} \end{array} \right. \)

ose_concatenateStrings()

void ose_concatenateStrings

(

ose_bundle

B

)

Concatenate two strings.

Precondition

B must not be empty.

The last element must be a message.

The last two items of the message must be strings.

Note

This function does not include any NULL padding between the strings.

\( \fn{CONCATENATESTRINGS}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg(\ldots, \type{\tts}_{L-1}, \type{\tts}_{L})}}\items{ \ldots, \ita{L-1}{\type{\tts}}, \itb{L}{\type{\tts}} } } }{ \BBtick\elems{ \ldots, \itat{K}{\type{\ttmsg}}\items{ \ldots, \ita{}{}\itb{L-1}{\type{\tts}} } } } \)

ose_countElems()

void ose_countElems

(

ose_bundle

B

)

Get the number of elements.

Creates a new message containing the number of elements in B as an int.

See also

ose_countItems

\( \fn{COUNTELEMS}{ \BB\elems{\ldots, \ela{K}{}} }{ \BBtick\elems{ \ldots, \ela{K}{}, \elb{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{K} } } } \)

ose_countItems()

void ose_countItems

(

ose_bundle

B

)

Get the number of items in the last element.

Creates a new message containing the number of items in the last element of B as an int.

Precondition

B must not be empty.

See also

ose_countElems

\( \fn{COUNTITEMS}{ \BB\elems{ \ldots, \ela{K}{}\items{ \ldots, \ita{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{ \ldots, \ita{L}{} }, \elb{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \itb{}{\type{\tti}}\values{L} } } } \)

Note

TWO CASES. The formula above is the one where the topmost element is a MESSAGE, and the count is of its items. When the topmost element is a BUNDLE the count is of its ELEMENTS, which is the formula below – "how many things are in the top one", whichever kind of container it is.

The bundle case was undocumented until 2026-08-23 and is the reason a reader of the implementation alone concluded that this function conflates items with elements. It does not; see ose_countElems, which counts the elements of the bundle itself.

\( \fn{COUNTITEMS}{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\elems{ \ldots, \elb{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{\type{\ttbndl}}\elems{ \ldots, \elb{L}{} }, \elc{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{L} } } } \)

See also

ose_countElems

ose_decatenateElemFromEnd()

void ose_decatenateElemFromEnd

(

ose_bundle

B

)

Split an element in two.

The last element of the bundle, a message containing an int \(v\), will be removed. The second to last element will have \(v\) items removed counting from the end, which will be contained in a new element of the same type.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([1,K]\) (inclusive), where \(K\) is the number of items in the second to last element.

See also

ose_decatenateElemFromStart

\( \fn{DECATENATEELEMFROMEND}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttvar}}\items{ \ldots, \ita{L-v}{}, \ldots, \itb{L}{} }, \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \itc{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttvar}}\items{\ldots}, \elc{K}{\type{\ttvar}}\items{ \ita{1}{}, \ldots, \itb{v}{} } } } \)

ose_decatenateElemFromStart()

void ose_decatenateElemFromStart

(

ose_bundle

B

)

Split an element in two.

The last element of the bundle, a message containing an int \(v\), will be removed. The second to last element will have \(v\) items removed counting from the start, which will be contained in a new element of the same type.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([1,K]\) (inclusive), where \(K\) is the number of items in the second to last element.

See also

ose_decatenateElemFromEnd

\( \fn{DECATENATEELEMFROMSTART}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttvar}}\items{ \ita{1}{}, \ldots, \itb{v}{}, \ldots } \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \itc{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttvar}}\items{ \ita{1}{}, \ldots, \itb{v}{} }, \elc{K}{\type{\ttvar}}\items{\ldots} } } \)

ose_disarmPointers()

void ose_disarmPointers

(

ose_bundle

B

)

Convert a blob to a bundle element.

This function removes the last element of the bundle, which must be a message, converts the last item of that message to a bundle element, and pushes it onto the end of the bundle.

Precondition

B must not be empty.

The last element must be a message.

The last item must be a blob.

The blob size and blob contents together must form a valid bundle element—no alteration to the contents to the blob or its size are made.

Retag every bound function in the top element so it cannot be called here, or so it can again.

A 'p' and a 'P' are byte for byte identical; the tag is the whole difference between a function this process may call and an address it may only look at. Recursive, because a machine is a bundle of bundles.

Disarming is what lets a machine from another process be RECEIVED at all: the input walk refuses 'p' and accepts 'P'. See OSETT_WILDPTR in ose.h.

Precondition

B must not be empty.

ose_div()

void ose_div

(

ose_bundle

B

)

Divide the number in the second to last message by the number in the last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{DIV}{/}\)

ose_drop()

void ose_drop

(

ose_bundle

B

)

Drop the last element.

Precondition

B must not be empty.

\( \fn{DROP}{ \BB\elems{ \ldots, \ela{K}{} } }{ \BBtick\elems{ \ldots } } \), where \(\ela{K}{}\) has been removed.

ose_dup()

void ose_dup

(

ose_bundle

B

)

Duplicate the last element.

Precondition

B must not be empty.

\( \fn{DUP}{ \BB\elems{ \ldots, \ela{K}{} } }{ \BBtick\elems{ \ldots, \ela{K}{}, \ela{K+1}{} } } \)

ose_elemIsBundle()

void ose_elemIsBundle

(

ose_bundle

B

)

Determine whether the last element is a bundle.

Creates a new message with a single integer with a value of 1 if the last element is a bundle, and a 0 otherwise.

Precondition

B must not be empty.

\( \fn{ELEMISBUNDLE}{ \BB\elems{ \ldots, \ela{K}{\type{\ttvar}} } }{ \BBtick\elems{ \ldots, \ela{K}{\type{\ttvar}}, \elb{K+1}{\type{\tti}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } } \), where \(v=1\) if \(\ttvar=\type{\ttbndl}\), or \(0\) otherwise.

ose_elemToBlob()

void ose_elemToBlob

(

ose_bundle

B

)

Convert the last element into a blob.

Precondition

B must not be empty.

\( \fn{ELEMTOBLOB}{ \BB\elems{ \ldots, \ela{K}{} } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttmsg}}\items{ \ita{}{\type{\ttb}}\values{\ela{}{}} } } } \)

ose_eql()

void ose_eql

(

ose_bundle

B

)

Compare the numbers in the last two messages for equality.

Precondition

B must contain at least two elements.

The last two elements must be messages.

Note

This is a test for equality of all bits from the typetag string through the payload, so, for example, two equivalent values of different types, say the int 10 and the float 10.0 are not considered equal.

\(\fnbinop{EQL}{=}\)

ose_gather()

void ose_gather

(

ose_bundle

B

)

Gather messages from a bundle that match one or more strings.

The last element must be a message containing one or more strings, and the second to last element must be a bundle. These two elements are removed, and each message in the bundle that matches a string in the message is placed in a new bundle. All messages that were unmatched are placed in a second bundle.

Precondition

B must contain at least two elements.

The last element must be a message containing one or more strings.

The second to last element must be a bundle.

See also

ose_route1

ose_routeWithDelegation

ose_select1

ose_selectWithDelegation

ose_getAddresses()

void ose_getAddresses

(

ose_bundle

B

)

Get the address(es) of the last element of the bundle.

Creates a list of one or more strings containing the addresses of the last element of the bundle. If the last element is a message, the result will be its address. If the last element is a bundle, the result will be a list of the addresses of each element.

Precondition

B must not be empty.

\( \fnname{getaddresses}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}} } }{ \BBtick\elems{ \ldots, \ela{K}{}, \elb{K+1}{\type{\ttmsg}}\items{ \ita{}{\tts}\values{\fnaddress{\ela{}{}}} } } }, \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} }, \elb{K+1}{\type{\ttmsg}}\items{ \itc{1}{\type{\tts}}\values{\fnaddress{\ita{}{}}}, \ldots, \itd{L}{\type{\tts}}\values{\fnaddress{\itb{}{}}}, } } } \end{array} \right. \)

ose_getTimetag()

void ose_getTimetag

(

ose_bundle

B

)

Get the bundle's timetag.

This function creates a new message at the end of B containing an 8-byte blob with the contents of the timetag field of B. The timetag field is not modified.

ose_getTypetags()

void ose_getTypetags

(

ose_bundle

B

)

Get the typetags of the last element.

Todo:

Implement.

ose_gt()

void ose_gt

(

ose_bundle

B

)

\(\fnbinop{GT}{>}\)

Added 2026-08-18 with ose_gte. The library had lt and lte and no counterparts, so every "greater than" had to be written by swapping the arguments – which reads backwards at the call site, and is the sort of thing that hides an off-by-one.

ose_gte()

void ose_gte

(

ose_bundle

B

)

\(\fnbinop{GTE}{>=}\)

ose_itemToBlob()

void ose_itemToBlob

(

ose_bundle

B

)

Convert the last item of the last element into a blob.

Precondition

B must not be empty.

The last element must be a message.

The message must not be empty.

\( \fn{ITEMTOBLOB}{ \BB\elems{ \ldots, \ela{K}{}\items{ \ldots, \ita{L}{} } } }{ \BBtick\elems{ \ldots, \elat{K}{}\items{ \ldots, \itat{L}{\type{\ttb}}\values{ita{}{}} } } } \)

ose_joinStrings()

void ose_joinStrings

(

ose_bundle

B

)

Join two strings with a separator (string) between them.

Takes three messages, each with a single string, and combines them into a single string. The separator is the string in the last message.

Precondition

B must contain at least three elements.

The last three elements must be messages.

The last three messages must each contain exactly one string.

This function is equivalent to

ose_swap(B);
ose_push(B);
ose_push(B);
ose_concatenateStrings(B);
ose_concatenateStrings(B);

\( \fn{JOINSTRINGS}{ \BB\elems{ \ldots, \ela{K-2}{\type{\ttmsg(\tts)}}\items{ \ita{}{\type{\tts}}\values{\valv{}{}} }, \elb{K-1}{\type{\ttmsg(\tts)}}\items{ \itb{}{\type{\tts}}\values{\valw{}{}} }, \elc{K}{\type{\ttmsg(\tts)}}\items{ \itc{}{\type{\tts}}\values{\valx{}{}} }, } }{ \BBtick\elems{ \ldots, \elat{K-2}{\type{\ttmsg(\tts)}}\items{ \itat{a}{\type{\tts}}\values{ \valv{}{}\valx{}{}\valw{}{} } } } } \)

ose_lengthItem()

void ose_lengthItem

(

ose_bundle

B

)

Get the length in bytes of the last item of the last element, excluding NULL-padding.

Creates a new message containing the number of bytes in the last item of the last element of B, excluding NULL-padding.

Precondition

B must not be empty.

See also

ose_lengthsItems

ose_sizeItem

ose_lengthsItems()

void ose_lengthsItems

(

ose_bundle

B

)

Get the lengths in bytes of all items of the last element as a list, excluding NULL-padding.

Creates a new message containing a list of the numbers of bytes of all items of the last element of B, excluding NULL-padding.

Precondition

B must not be empty.

See also

ose_lengthItem

ose_sizesItems

Todo:

Implement.

\( \fn{LENGTHSITEMS}{ \BB\elems{ \ldots, \ela{K}{}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{ \ita{1}{}, \ldots, \itb{L}{} }, \elb{K+1}{\type{\ttmsg(\allints{1}{L})}}\items{ \itc{1}{\type{\tti}}\values{\fnlength{\ita{}{}}}, \ldots, \itc{L}{\type{\tti}}\values{\fnlength{\itb{}{}}} } } } \)

ose_lt()

void ose_lt

(

ose_bundle

B

)

Test whether the number in the last message is less than to the number in the second to last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{LT}{<}\)

ose_lte()

void ose_lte

(

ose_bundle

B

)

Test whether the number in the last message is less than or equal to the number in the second to last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{LTE}{\le}\)

ose_makeBlob()

void ose_makeBlob

(

ose_bundle

B

)

Create an empty blob of a given size.

The last element, a message containing the size of the blob to be created, will be removed, and a new message containing a single blob of that size will be created.

Precondition

B must not be empty.

The last element must be a message.

The last element must contain a single non-negative integer.

\( \fn{MAKEBLOB}{ \BB\elems{ \ldots, \ela{K}{} } }{ \BBtick\elems{ \ldots, \ela{K}{}, \elb{K+1}{\type{\ttmsg}}\items{ \ita{}{\type{\ttb}} } } } \)

ose_match()

void ose_match

(

ose_bundle

B

)

Compare two strings.

Does a simple string comparison on the strings contained in the last two messages. It leaves the last two messages in place and creates a new message with a single non-zero int if the strings are identical, or 0 otherwise.

Precondition

B must contain at least two elements.

The last two elements must be messages.

the last two messages must each contain exactly one string.

\( \fn{MATCH}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg(\type{\tts})}}\items{ \ita{}{\type{\tts}}\values{\valv{}{}} }, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valw{}{}} } } }{ \BBtick\elems{ \ldots, \ela{K-1}{\type{\ttmsg(\type{\tts})}}\items{ \ita{}{\type{\tts}}\values{\valv{}{}} }, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valw{}{}} }, \elc{K+1}{\type{\ttmsg}}\items{ \itc{}{\type{\tti}}\values{\valv{}{} \match \valw{}{}} } } } \)

ose_max()

void ose_max

(

ose_bundle

B

)

\(\fnbinop{MAX}{max}\)

ose_min()

void ose_min

(

ose_bundle

B

)

\(\fnbinop{MIN}{min}\)

ose_mod()

void ose_mod

(

ose_bundle

B

)

Take the number in the last message modulo the number in the second to last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{MOD}{\bmod}\)

ose_moveStringToAddress()

void ose_moveStringToAddress

(

ose_bundle

B

)

Move the last string of a message to the address.

Precondition

B must not be empty.

The last element must be a message.

The last item of the message must be a string.

\( \fn{MOVESTRINGTOADDRESS}{ \BB\elems{ \ldots, \ela{K}{\ttmsg(\ldots, \type{\tts}_L)}\items{ \alpha=a\mid \ldots, \itb{L}{\type{\tts}} } } }{ \BBtick\elems{ \ldots, \ela{K}{\ttmsg(\ldots, \type{\tts}_L)}\items{ \alpha=b\mid \ldots } } } \)

ose_mul()

void ose_mul

(

ose_bundle

B

)

Multiply the number in the last message by the number in the previous message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{MUL}{}\)

ose_neg()

void ose_neg

(

ose_bundle

B

)

Flip the sign of the number in the last message of the bundle.

Precondition

B must contain at least one element.

The last element must be a message.

The last element must contain exactly one numerical value.

\( \fn{NEG}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg(\type{\ttvar})}}\items{ \ita{}{\type{\ttvar}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttmsg(\type{\ttvar})}}\items{ \itb{}{\type{\ttvar}}\values{-\valv{}{}} } } }, \ttvar=\type{\tti\ttf} \)

ose_neq()

void ose_neq

(

ose_bundle

B

)

Compare the numbers in the last two messages for non equality.

Precondition

B must contain at least two elements.

The last two elements must be messages.

Note

This is a test for equality of all bits from the typetag string through the payload, so, for example, two equivalent values of different types, say the int 10 and the float 10.0 are not considered equal.

\(\fnbinop{NEQ}{\neq}\)

ose_nip()

void ose_nip

(

ose_bundle

B

)

Drop the second to last element.

Precondition

B must contain at least two elements.

\( \fn{NIP}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots, \elb{K-1}{} } } \), where \(A\) has been removed.

ose_not()

void ose_not

(

ose_bundle

B

)

\(\fnunop{NOT}{!}\)

The library had and and or and no negation. A boolean algebra missing negation is a real hole and cannot be worked around cleanly.

ose_nth()

void ose_nth

(

ose_bundle

B

)

Copy the nth item of an element.

The last element must be a message with one or more integers representing the positions of the items in the second to last element to copy to the end of the bundle. The last element will be removed. Indexes are 0-based counting from the beginning of the element.

Precondition

B must contain at least two elements.

The last element must be a message.

The last element (message) must contain at least one item.

All items of the last element (message) must be integers.

All integer values in the last element (message) must be in the range \([0,K-1]\), where \(K\) is the number of items in the second to last element.

\( \fn{NTH}{ \BB\elems{ \ldots, \ela{K-1}{\ttvar}\items{ \ldots, \ita{\valv{}{}}{}, \ldots, \itb{\valw{}{}}{}, \ldots }, \elb{K}{\type{\ttmsg(\allints{1}{M})}}\items{ \itc{1}{\type{\tti}}\values{\valv{}{}}, \ldots, \itd{M}{\type{\tti}}\values{\valw{}{}}, } } }{ \BBtick\elems{ \ldots, \elc{K-1}{\ttvar}\items{ \ita{1}{}, \ldots, \itb{M}{} } } } \)

ose_or()

void ose_or

(

ose_bundle

B

)

Test whether at least one of the numbers in the last two messages is non-zero.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{OR}{\lor}\)

ose_over()

void ose_over

(

ose_bundle

B

)

Copy the second from the last item over the last.

@ B must contain at least two elements.

\( \fn{OVER}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots, \ela{K-1}{}, \elb{K}{}, \ela{K+1}{} } } \)

ose_peekAddress()

char * ose_peekAddress

(

const ose_bundle

B

)

Get the address of the last element.

Returns

a pointer to the address

Precondition

B must not be empty.

Note

If the last element of B is a bundle, this function returns a pointer to the bundle ID, "#bundle".

\( \fn{PEEKADDRESS}{ \BB\elems{ \ldots, \ela{K}{} } }{ \left[\BBtick, \fnaddress{\ela{}{}}\right] } \)

ose_peekAlignedPtr()

const void * ose_peekAlignedPtr

(

ose_bundle

B

)

Get the last aligned pointer without removing it.

Precondition

B must not be empty.

The last element must be a message.

The last item of the last message must be a valid aligned pointer, written using ose_pushAlignedPtr, or ose_writeAlignedPtr.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKALIGNEDPTR}{\ttb}\)

ose_peekBlob()

char * ose_peekBlob

(

ose_bundle

B

)

Get a pointer to the last blob without removing it.

Returns

a pointer to the location in the bundle where the blob is

Precondition

B must not be empty.

The last element must be a message.

The last item of the last message must be a valid OSC blob.

Note

The blob should not be modified unless you know what you are doing.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKBLOB}{\ttb}\)

ose_peekDouble()

double ose_peekDouble

(

const ose_bundle

B

)

Get the last double without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKDOUBLE}{\ttd}\)

ose_peekFloat()

float ose_peekFloat

(

ose_bundle

B

)

Get the value of the last float stored in the last message.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKFLOAT}{\ttf}\)

ose_peekInt16()

int16_t ose_peekInt16

(

const ose_bundle

B

)

Peek at the int16 value of the last element.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

The 16-bit widths had every part of their support except this: the typetags, the /,/u and /,/U conversions that produce them, ose_readInt16() to read one at an offset, and printing. What was missing was the stack accessor every other width has, so a value of a type the build advertises in its ABI record could be made and printed and never read back.

Read as 32 bits and narrowed, which is what ose_readInt16() does and is not an accident: OSC pads every payload item to four bytes, so a 16-bit value occupies a four-byte slot and the swap is over the whole slot.

ose_peekInt32()

int32_t ose_peekInt32

(

ose_bundle

B

)

Get the value of the last int stored in the last message.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKINT32}{\tti}\)

ose_peekInt64()

int64_t ose_peekInt64

(

const ose_bundle

B

)

Get the last 64-bit int without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKINT64}{\tth}\)

ose_peekInt8()

int8_t ose_peekInt8

(

const ose_bundle

B

)

Get the last signed char without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKINT8}{\ttc}\)

ose_peekMessageArgType()

char ose_peekMessageArgType

(

const ose_bundle

B

)

Get the type of the last item of the last element.

Returns

the typetag of the last item of the last element

Return values

OSETT_NOTYPETAG

if the message has no data/payload

Precondition

B must not be empty.

The last element should be a message.

Warning

This function does no typechecking to ensure that the last element is actually a message.

\( \fn{PEEKMESSAGEARGTYPE}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\type{\ttvar}} } } }{ \left[\BB, \ttvar\right] } \)

ose_peekMessageArgTypeAtOffset()

char ose_peekMessageArgTypeAtOffset	(	const ose_bundle	B,
		const int32_t	messageoffset
	)

Get the type of the last item of the last element, where the offset of the last element is given.

Returns

the typetag of the last item of the last element

Return values

OSETT_NOTYPETAG

if the message has no data/payload

Precondition

B must not be empty.

The last element should be a message.

Warning

This function does no typechecking to ensure that the last element is actually a message.

ose_peekString()

char * ose_peekString

(

ose_bundle

B

)

Get a pointer to the last string without removing it.

Returns

a pointer to the location in the bundle where the string is

Precondition

B must not be empty.

The last element must be a message.

The last item of the last message must be a NULL-terminated string.

Note

The string should not be modified unless you know what you are doing.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKSTRING}{\tts}\)

ose_peekSymbol()

char * ose_peekSymbol

(

const ose_bundle

B

)

Get a pointer to the last symbol stored in the last message.

Returns

a pointer to the location in the bundle where the symbol is

Precondition

B must not be empty

the last element must be a message

the last item of the last message must be a NULL-terminated string

Note

The string should not be modified unless you know what you are doing.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKSYMBOL}{\ttS}\)

ose_peekTimetag()

struct ose_timetag ose_peekTimetag

(

const ose_bundle

B

)

Get the last timetag without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKTIMETAG}{\tttt}\)

ose_peekType()

char ose_peekType

(

const ose_bundle

B

)

Get the type of the last element.

Returns

the type of the last element

Return values

OSETT_BUNDLE
OSETT_MESSAGE

Precondition

B must not be empty.

Warning

It is undefined behavior to call this function on an empty bundle.

\( \fn{PEEKTYPE}{ \BB\elems{ \ldots, \ita{K}{\type{\ttvar}} } }{ \left[\BB, \ttvar\right] } \)

ose_peekUInt16()

uint16_t ose_peekUInt16

(

const ose_bundle

B

)

Peek at the uint16 value of the last element.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

ose_peekUInt32()

uint32_t ose_peekUInt32

(

const ose_bundle

B

)

Get the last unsigned 32-bit int without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKUINT32}{\ttk}\)

ose_peekUInt64()

uint64_t ose_peekUInt64

(

const ose_bundle

B

)

Get the last unsigned int without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKUINT64}{\ttH}\)

ose_peekUInt8()

uint8_t ose_peekUInt8

(

const ose_bundle

B

)

Get the last uint8_t without removing it.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpeektypedvalue{PEEKUINT8}{\ttC}\)

ose_pick()

void ose_pick

(

ose_bundle

B

)

Copy an element at an index to the end.

The last element, a message containing an int, will be removed, and the value of the int will be used to index an element of B. Indexes are 0-based, counting from the end, with 0 being the last element after the removal of the message. The element that corresponds to the index will be copied to the end.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([0, K-2]\) (inclusive), where \(K\) is the total number of elements in the bundle at the time the function is called.

Note

When the index is 0, the operation is equivalent to ose_dup, and when it is 1, it is equivalent to ose_over.

See also

ose_pickBottom

ose_pickMatch

\( \fn{PICK}{ \BB\elems{ \ldots, \ela{K-1-v}{}, \ldots, \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{ \valv{}{} } } } }{ \BBtick\elems{ \ldots, \ela{K-1-v}{}, \ldots, \elat{K}{} } } \), where \(\elb{}{}\) has been removed and \(\ela{}{}\) copied to the end.

ose_pickBottom()

void ose_pickBottom

(

ose_bundle

B

)

Copy the first element to the end.

Precondition

B must not be empty.

See also

ose_pick

ose_pickMatch

\( \fn{PICKBOTTOM}{ \BB\elems{ \ela{1}{}, \ldots } }{ \BBtick\elems{ \ela{1}{}, \ldots, \ela{K}{} } } \)

ose_pickMatch()

void ose_pickMatch

(

ose_bundle

B

)

COPY the first element whose address equals the string at the end to the end — ose_pickMatch_impl, and PUSH the flag it returns as an int.

ose_pushInt32(B, ose_pickMatch_impl(B)). The bundle therefore ends up one element larger than it started even on success, and a caller that wanted only the copy must drop the flag. Addresses are compared with strcmp.

See also

ose_pickMatch_impl

ose_pickMatch_impl()

int32_t ose_pickMatch_impl

(

ose_bundle

B

)

COPY the first element whose address matches the string at the end of the bundle to the end.

The last element of B must be a message containing one string. Elements are compared from the beginning of the bundle and the FIRST match wins, halting the search. The matched element is copied to the end; the original stays where it was. ose_rollMatch is the same search with the element MOVED instead.

ose_pickMatch_impl compares addresses with strcmp – no pattern matching. ose_pickPMatch_impl uses OSC pattern matching, via ose_match_pattern(), and matches only when the address is consumed entirely (OSE_MATCH_ADDRESS_COMPLETE).

Which side is the pattern: the stored element's address is the pattern and the string at the end of the bundle is matched against it – the OSC dispatch direction, and the argument order ose_match_pattern() takes. So a bundle holding /a* answers to a lookup of /ab, not the other way round.

The search string is dropped only on a match. If nothing matches it is still there when the function returns, under the flag.

Precondition

B must contain at least one element.

The last element must be a message containing one string.

Returns

(the _impl forms) 1 if an element was copied, 0 if none matched.

The void forms push that flag – see the note on the roll family below, which is the same arrangement.

Warning

The two families disagree about a full bundle. If the bundle declines to grow, ose_rollMatch_impl returns 0 and these return 1: the copy did not happen and the caller is told it did. ose_pickMatch_found_impl returns void, so there is nothing for ose_pickMatch_impl to propagate. It is not covered by a test: the unit fixture cannot present a bundle that is already at capacity.

See also

ose_rollMatch

ose_pick

\( \fn{PICKMATCH}{ \BB\elems{ \ldots, \ela{J}{}, \ldots, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \ela{J}{}, \ldots, \ela{K}{}, \elc{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \itc{}{\type{\tti}}\values{1} } } } \), where \(\ela{J}{}\) is the first element for which \(\fnaddress{\ela{J}{}} \match \valv{}{}\), \(\elb{K}{}\) has been removed, and a COPY of \(\ela{J}{}\) has been appended — the original stays where it was. If no element matches, \(\elb{K}{}\) REMAINS and the flag is 0.

The void form is the one shown; ose_pickMatch_impl does the same without the trailing flag, returning it instead.

ose_pickPMatch()

void ose_pickPMatch

(

ose_bundle

B

)

Copy the first element whose address pattern matches the string at the end to the end — ose_pickPMatch_impl, and push the flag it returns as an int.

ose_pushInt32(B, ose_pickPMatch_impl(B)). The bundle therefore ends up one element larger than it started even on success, and a caller that wanted only the copy must drop the flag. The stored address is the pattern; the string at the end is matched against it.

See also

ose_pickPMatch_impl

ose_pickPMatch_impl()

int32_t ose_pickPMatch_impl

(

ose_bundle

B

)

\(\fn{PICKPMATCH}{\ldots}{\ldots}\) — PICKMATCH above, with \(\fnaddress{\ela{J}{}} \pmatch \valv{}{}\) in place of \(\match\): the stored element's address is the PATTERN and \(\valv{}{}\) is matched against it, which is the direction ose_match_pattern() takes its arguments and the direction OSC dispatch runs. A match counts only when the address is consumed entirely.

ose_plookup()

void ose_plookup

(

ose_bundle

B

)

Todo:

Implement.

ose_pmatch()

void ose_pmatch

(

ose_bundle

B

)

Compare two strings using pattern matching.

Performs a string comparison using pattern matching on the strings contained in the last two messages. The string in the last message is called the address, and the string in the second to last message is called the pattern. Only the pattern may contain wildcards.

Two new messages are created at the end of B, each of which contains a single integer. The first will be non-zero if the pattern was matched in its entirety, and 0 otherwise, and the second will be non-zero if the address was matched in its entirety and zero otherwise.

The address is left untouched by the operation, but the pattern is modified: the portion that matched is removed, and the portion that is unmatched remains (which may be an empty string).

Precondition

B must contain at least two elements.

The last two elements must be messages.

the last two messages must each contain exactly one string.

\( \fn{PMATCH}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg(\type{\tts})}}\items{ \ita{}{\type{\tts}}\values{\valv{}{}} }, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valw{}{}} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttmsg(\type{\tts})}}\items{ \itat{}{\type{\tts}}\values{\valvt{}{}} }, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valw{}{}} }, \elc{K+1}{\type{\ttmsg}}\items{ \itc{}{\type{\tti}} }, \eld{K+2}{\type{\ttmsg}}\items{ \itd{}{\type{\tti}} } } } \), where \(\valvt{}{}\) may have been modified with any matching portion stripped, \(\itc{}{}\) is non-zero if \(\valvt{}{}\) was fully matched and zero otherwise, and \(\itd{}{}\) is non-zero if \(\valw{}{}\) was fully matched and zero otherwise.

ose_pop()

void ose_pop

(

ose_bundle

B

)

Pop the last item off the last element and push it onto the end of the bundle as a new element.

Precondition

B must not be empty.

Note

The last element of the bundle may be empty, in which case the element will be dropped.

See also

ose_popAll

ose_popAllDrop

ose_popAllBundle

ose_popAllDropBundle

\( \fnname{POP}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{}\items{} } }{ \BBtick\elems{ \ldots } }, \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ldots, \ita{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{\ldots}, \ita{K+1}{} } }, \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{\ldots}, \elb{K+1}{\type{\ttmsg}}\items{ \ita{}{} } } } \end{array} \right. \)

ose_popAll()

void ose_popAll

(

ose_bundle

B

)

Pop each item off the last element of the bundle.

After all items have been popped off the element, the empty element, a message with no data, or an empty bundle, is left as the final element of the bundle.

Precondition

B must not be empty.

Note

The last element of the bundle may be empty, in which case this function is a no-op.

See also

ose_pop

ose_popAllDrop

ose_popAllBundle

ose_popAllDropBundle

\( \fnname{POPALL}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{}\items{} } }{ \BB } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \itb{K}{}, \ldots, \ita{K+L}{}, \elat{K+L+1}{}\items{} } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttmsg}}\items{ \itb{}{} }, \ldots, \elc{K+L}{\type{\ttmsg}}\items{ \ita{}{} }, \elat{K+L+1}{}\items{} } } \end{array} \right. \)

ose_popAllBundle()

void ose_popAllBundle

(

ose_bundle

B

)

Pop each item off the last element of the bundle, and bundle them together.

Like ose_popAll, but all elements created from the items of the last element are bundled together.

Precondition

B must not be empty.

Note

The last element of the bundle may be empty, in which case it is simply bundled.

See also

ose_pop

ose_popAll

ose_popAllDrop

ose_popAllDropBundle

\( \fnname{POPALLDROP}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{}\items{} } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{ \ela{}{}\items{} } } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{ \itb{1}{}, \ldots, \ita{L}{}, \ela{L+1}{}\items{} } } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{ \elc{1}{\type{\ttmsg}}\items{ \itb{}{} }, \ldots, \eld{L}{\type{\ttmsg}}\items{ \ita{}{} }, \ela{L+1}{}\items{} } } } \end{array} \right. \)

ose_popAllDrop()

void ose_popAllDrop

(

ose_bundle

B

)

Pop each item off the last element of the bundle, and drop the empty element.

Unlike ose_popAll, the empty element is not left at the end of the bundle.

Precondition

B must not be empty.

Note

The last element of the bundle may be empty, in which case it is simply dropped.

See also

ose_pop

ose_popAll

ose_popAllBundle

ose_popAllDropBundle

\( \fnname{POPALLDROP}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{}\items{} } }{ \BBtick\elems{ \ldots } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \itb{K}{}, \ldots, \ita{K+L}{} } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttmsg}}\items{ \itb{}{} }, \ldots, \elc{K+L}{\type{\ttmsg}}\items{ \ita{}{} } } } \end{array} \right. \)

ose_popAllDropBundle()

void ose_popAllDropBundle

(

ose_bundle

B

)

Pop each item off the last element of the bundle, drop the empty element, and bundle all new elements together.

The combined behavior of ose_popAllDrop and ose_popAllBundle.

Precondition

B must not be empty.

Note

The last element of the bundle may be empty, in which case it is dropped and an empty bundle is created in its place.

See also

ose_pop

ose_popAll

ose_popAllBundle

ose_popAllDrop

\( \fnname{POPALLDROPBUNDLE}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{}\items{} } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{} } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{ \itb{1}{}, \ldots, \ita{L}{} } } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttbndl}}\items{ \elc{1}{\type{\ttmsg}}\items{ \itb{}{} }, \ldots, \eld{L}{\type{\ttmsg}}\items{ \ita{}{} } } } } \end{array} \right. \)

ose_popAtOffset()

void ose_popAtOffset	(	ose_bundle	B,
		int32_t	o
	)

Remove the element at a known offset, which must be the last one.

ose_pop() with the walk omitted. ose_pop() locates the last element by walking the bundle from its header; a caller that already holds that offset passes it here instead.

Precondition

B must contain at least one element.

o must be the offset of the last element of B.

Note

This does not remove an element from the middle of a bundle. An interior offset is a violation of the precondition above. To remove an interior element, build a new bundle without it.

ose_popBlob()

int32_t ose_popBlob	(	ose_bundle	B,
		char *	buf
	)

Get the last blob and remove it from the bundle.

Parameters

B	the bundle
buf	a pointer to an array large enough to store a copy of the blob payload, i.e. not including the 4 byte size

Returns

the size of the blob (not including the 4 byte size, or any padding)

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPBLOB}{\ttb}\)

ose_popDouble()

double ose_popDouble

(

ose_bundle

B

)

Get the last double and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPDOUBLE}{\ttd}\)

ose_popFloat()

float ose_popFloat

(

ose_bundle

B

)

Get the last float and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPFLOAT}{\ttf}\)

ose_popInt32()

int32_t ose_popInt32

(

ose_bundle

B

)

Get the last int and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPINT32}{\tti}\)

ose_popInt64()

int64_t ose_popInt64

(

ose_bundle

B

)

Get the last 64-bit int and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPINT64}{\tth}\)

ose_popInt8()

int8_t ose_popInt8

(

ose_bundle

B

)

Get the last char and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPINT8}{\ttc}\)

ose_popString()

int32_t ose_popString	(	ose_bundle	B,
		char *	buf
	)

Get the last string and remove it from the bundle.

Parameters

B	the bundle
buf	a pointer to an array large enough to store a copy of the string

Returns

the length of the string not including the NULL byte

Precondition

B must not be empty.

The last element must be a message.

The last item of the last message must be a NULL-terminated string.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPSTRING}{\tts}\)

ose_popSymbol()

int32_t ose_popSymbol	(	ose_bundle	B,
		char *	buf
	)

Get the last symbol and remove it from the bundle.

Parameters

B	the bundle
buf	a pointer to an array large enough to store a copy of the symbol

Returns

the length of the symbol not including the NULL byte

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPSYMBOL}{\ttS}\)

ose_popTimetag()

struct ose_timetag ose_popTimetag

(

ose_bundle

B

)

Get the last timetag and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPTIMETAG}{\tttt}\)

ose_popUInt32()

uint32_t ose_popUInt32

(

ose_bundle

B

)

Get the last unsigned 32-bit int and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPUINT32}{\ttk}\)

ose_popUInt64()

uint64_t ose_popUInt64

(

ose_bundle

B

)

Get the last unsigned 64-bit int and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPUINT64}{\ttH}\)

ose_popUInt8()

uint8_t ose_popUInt8

(

ose_bundle

B

)

Get the last uint8_t and remove it from the bundle.

Precondition

B must not be empty.

The last element must be a message.

Warning

This function does no type or bounds checking.

\(\fnpoptypedvalue{POPUINT8}{\ttC}\)

ose_pow()

void ose_pow

(

ose_bundle

B

)

Raise the number in the last message to the power of the number in the second to last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{POW}{^}\), where \(^\) is exponentiation and not C's XOR — which is what this computed on every integer width until 2026-09-14. An integer result that does not fit, and a negative integer exponent, raise OSE_ERR_RANGE rather than answering something plausible.

ose_push()

void ose_push

(

ose_bundle

B

)

Push the last element of the bundle onto the element below it.

The behavior of this function depends on the types and number of elements at the end of the bundle as follows:

• the bundle is empty: an empty bundle is created
• there is only one element: it is pushed into a bundle
• both elements are messages: append the payload of the last to the one below it.
• the second to last element is a bundle: the last element is pushed into it.
• the second to last element is a message, and the last element is a bundle: the last element becomes a blob appended to the message.

\( \fnname{PUSH}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{} }{ \BBtick\elems{ \ela{}{\type{\ttbndl}} } } \\ \fnmapping{ \BB\elems{\ela{}{}} }{ \BBtick\elems{ \elb{}{\type{\ttbndl}}\items{\ela{}{}} } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } \elb{K}{\type{\ttmsg}}\items{ \itc{1}{}, \ldots, \itd{M}{} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{}, \itc{L+1}{}, \ldots, \itd{L+M}{} } } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttbndl}}\items{ \ldots, \ita{L}{} }, \elb{K}{} } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttbndl}}\items{ \ldots, \ita{L}{}, \elb{L+1}{} } } } \\ \fnmapping{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{} }, \elb{K}{\type{\ttbndl}} } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{}, \itb{L+1}{\type{\ttb}} } } } \end{array} \right. \)

ose_pushBlob()

void ose_pushBlob	(	ose_bundle	B,
		int32_t	blobsize,
		const char *const	blob
	)

Append a message containing a blob.

Precondition

B must have room for blobsize bytes plus the message overhead.

Postcondition

On violation, sets errno to OSE_ERR_RANGE and pushes nothing. blobsize is host-supplied at several call sites – it is how bytes arrive from a socket or an audio buffer – and before this was checked a blob larger than the remaining space was written past the end of the bundle's memory. ose_incSize refused to grow and set errno, and this function did not look before copying.

\(\fnpushtype{PUSHBLOB}{\ttb}\)

ose_pushBundle()

void ose_pushBundle

(

ose_bundle

B

)

Create an empty bundle.

\( \fn{PUSHBUNDLE}{ \BB\elems{\ldots, \ela{K}{}} }{ \BBtick\elems{ \ldots, \ela{K}{}, \elb{K+1}{\type{\ttbndl}}\items{} } } \)

ose_pushDouble()

void ose_pushDouble	(	ose_bundle	B,
		double	f
	)

Append a message containing a double.

\(\fnpushtype{PUSHDOUBLE}{\ttd}\)

ose_pushFalse()

void ose_pushFalse

(

ose_bundle

B

)

Append message containing false to B.

\(\fnpushunittype{PUSHFALSE}{F}\)

ose_pushFloat()

void ose_pushFloat	(	ose_bundle	B,
		float	f
	)

Append a message containing a float.

\(\fnpushtype{PUSHFLOAT}{\ttf}\)

ose_pushInfinitum()

void ose_pushInfinitum

(

ose_bundle

B

)

Append a message containing an infinitum.

\(\fnpushunittype{PUSHINFINITUM}{I}\)

ose_pushInt32()

void ose_pushInt32	(	ose_bundle	B,
		int32_t	i
	)

Append a message containing a 32-bit signed int.

\(\fnpushtype{PUSHINT32}{\tti}\)

ose_pushInt64()

void ose_pushInt64	(	ose_bundle	B,
		int64_t	i
	)

Append a message containing a signed 64-bit int.

\(\fnpushtype{PUSHINT64}{\tth}\)

ose_pushInt8()

void ose_pushInt8	(	ose_bundle	B,
		int8_t	i
	)

Append a message containing a signed char.

\(\fnpushtype{PUSHINT8}{\ttc}\)

ose_pushLines()

void ose_pushLines	(	ose_bundle	bundle,
		const char *const	src
	)

Push each line of src as a string.

A line ends at \n, a trailing \r goes with it, and empty lines are skipped rather than pushed. Lines longer than OSE_MAXLINE are skipped.

Does not push a bundle first: where the lines go is the caller's decision. A loader reading a file wraps them; a host feeding its own input register does not.

Here rather than in a loader because it is not about loading – it is what every caller that has .ose source in memory needs, and there were two copies of these rules before there was one.

\(\fnpushtype{PUSHALIGNEDPTR}{\ttb}\)

ose_pushMessage()

void ose_pushMessage	(	ose_bundle	B,
		const char *const	address,
		int32_t	addresslen,
		int32_t	n,
			...
	)

Append a message.

Parameters

B	the bundle
address	the address of the message
addresslen	the address length not including NULL padding
n	the number of arguments
...	n arguments (typetag, data)

See also

ose_writeMessage

ose_pushNil()

void ose_pushNil

(

ose_bundle

B

)

Append message containing NIL to B.

\(\fnpushunittype{PUSHNIL}{N}\)

ose_pushString()

void ose_pushString	(	ose_bundle	B,
		const char *const	s
	)

Append a message containing a string.

\(\fnpushtype{PUSHSTRING}{\tts}\)

ose_pushSymbol()

void ose_pushSymbol	(	ose_bundle	B,
		const char *const	s
	)

Append a message containing a symbol.

\(\fnpushtype{PUSHSYMBOL}{\ttS}\)

ose_pushTimetag()

void ose_pushTimetag	(	ose_bundle	B,
		uint32_t	sec,
		uint32_t	fsec
	)

Append a message containing a timetag.

\( \fn{PUSHTIMETAG}{ \BB\elems{\ldots}, sec, fsec }{ \BBtick\elems{ \ldots, \ela{K}{\type{\ttmsg(\type{\tttt})}}\items{ \ita{}{\type{\tttt}}\values{ sec^\prime, fsec^\prime } } } } \)

ose_pushTrue()

void ose_pushTrue

(

ose_bundle

B

)

Append message containing true to B.

\(\fnpushunittype{PUSHTRUE}{\ttT}\)

ose_pushUInt32()

void ose_pushUInt32	(	ose_bundle	B,
		uint32_t	i
	)

Append a message containing an unsigned 32-bit int.

\(\fnpushtype{PUSHUINT32}{\ttk}\)

ose_pushUInt64()

void ose_pushUInt64	(	ose_bundle	B,
		uint64_t	i
	)

Append a message containing an unsigned 64-bit int.

\(\fnpushtype{PUSHUINT64}{\ttH}\)

ose_pushUInt8()

void ose_pushUInt8	(	ose_bundle	B,
		uint8_t	i
	)

Append a message containing an uint8_t.

\(\fnpushtype{PUSHUINT8}{\ttC}\)

ose_rearmPointers()

void ose_rearmPointers

(

ose_bundle

B

)

The inverse. Restores the TAG, which is not the same as restoring the meaning – an address is only valid in the process it came from.

Precondition

B must not be empty.

ose_reverse()

void ose_reverse

(

ose_bundle

B

)

Reverse the items of the last element of the bundle.

Precondition

B must not be empty.

\( \fn{REVERSE}{ \BB\elems{ \ela{0}{}, \ldots, \elb{K}{} } }{ \BBtick\elems{ \elb{0}{}, \ldots, \ela{K}{} } } \)

ose_roll()

void ose_roll

(

ose_bundle

B

)

Move an element at an index to the end.

The last element, a message containing an int, will be removed, and the value of the int will be used to index an element of B. Indexes are 0-based, counting from the end, with 0 being the last element after the removal of the message. The element that corresponds to the index will be moved to the end.

Precondition

B must contain at least two elements.

The last element must be a message containing an int.

The int must be in the range \([0, K-2]\) (inclusive), where \(K\) is the total number of elements in the bundle at the time the function is called.

Note

When the index is 0, this is a no-op (excepting that the message containing the index is dropped), when it is 1, it is equivalent to ose_swap, and when it is 2, it is equivalent to ose_rot.

See also

ose_rollBottom

ose_rollMatch

\( \fn{ROLL}{ \BB\elems{ \ldots, \ela{K-1-v}{}, \ldots, \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \ita{}{\type{\tti}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \ela{K-1}{} } } \), where \(\elb{}{}\) has been removed, and \(\ela{}{}\) has been moved to the end.

ose_rollBottom()

void ose_rollBottom

(

ose_bundle

B

)

Move the first element to the end.

Precondition

B must not be empty.

Note

If B contains only one element, this is a no-op, with two elements, it is equivalent to ose_swap, and with three elements, it is equivalent to ose_rot.

See also

ose_roll

ose_rollMatch

\( \fn{ROLLBOTTOM}{ \BB\elems{ \ela{1}{}, \ldots } }{ \BBtick\elems{ \ldots, \ela{K}{} } } \)

ose_rollMatch()

void ose_rollMatch

(

ose_bundle

B

)

Move the first element whose address equals the string at the end to the end — ose_rollMatch_impl, and push the flag it returns as an int.

ose_pushInt32(B, ose_rollMatch_impl(B)). The bundle therefore ends up one element larger than it started even on success, and a caller that wanted only the move must drop the flag. Addresses are compared with strcmp.

See also

ose_rollMatch_impl

ose_rollMatch_impl()

int32_t ose_rollMatch_impl

(

ose_bundle

B

)

Move the first element whose address matches the string at the end of the bundle to the end.

These move rather than copy – the matched element is gone from where it was – which is the whole difference between this family and the pick family above.

The last element of B must be a message containing one string. It is dropped only on a match: ose_rollMatch_found_impl() is where the drop happens, and it is reached only once something has matched. The two no-match cases in ut_ose_stackops.c find the string still in place.

Addresses are compared from the beginning of the bundle and the first match wins. For the pattern variant the stored element's address is the pattern and the string at the end is matched against it – see the note on the pick family above.

ose_rollMatch_impl compares with strcmp – no pattern matching. ose_rollPMatch_impl uses OSC pattern matching, and matches only when the pattern consumes the address entirely.

Precondition

B must contain at least one element.

The last element must be a message containing one string.

Returns

(the _impl forms) 1 if an element was moved, 0 if none matched or the bundle declined to grow. The pick family answers 1 in that last case; see the

Warning

above.

The void forms push that flag. ose_rollMatch() is ose_pushInt32(B, ose_rollMatch_impl(B)), so the bundle ends up one element larger than it started even on a successful roll, and a caller that wanted the element moved and nothing else must drop it. The same is true of ose_pickMatch() and ose_pickPMatch() above.

See also

ose_pickMatch

ose_roll

\( \fn{ROLLMATCH}{ \BB\elems{ \ldots, \ela{J}{}, \ldots, \elb{K}{\type{\ttmsg(\type{\tts})}}\items{ \itb{}{\type{\tts}}\values{\valv{}{}} } } }{ \BBtick\elems{ \ldots, \ldots, \ela{K-1}{}, \elc{K}{\type{\ttmsg(\type{\tti})}}\items{ \itc{}{\type{\tti}}\values{1} } } } \), where \(\ela{J}{}\) is the first element for which \(\fnaddress{\ela{J}{}} \match \valv{}{}\), \(\elb{K}{}\) has been removed, and \(\ela{J}{}\) has been MOVED to the end — it is gone from where it was, which is the whole difference from PICKMATCH. If no element matches, \(\elb{K}{}\) REMAINS and the flag is 0.

ose_rollPMatch()

void ose_rollPMatch

(

ose_bundle

B

)

Move the first element whose address pattern matches the string at the end to the end — ose_rollPMatch_impl, and push the flag it returns as an int.

ose_pushInt32(B, ose_rollPMatch_impl(B)). The bundle therefore ends up one element larger than it started even on success, and a caller that wanted only the move must drop the flag. The stored address is the pattern; the string at the end is matched against it.

See also

ose_rollPMatch_impl

ose_rollPMatch_impl()

int32_t ose_rollPMatch_impl

(

ose_bundle

B

)

\(\fn{ROLLPMATCH}{\ldots}{\ldots}\) — ROLLMATCH above, with \(\fnaddress{\ela{J}{}} \pmatch \valv{}{}\) in place of \(\match\). See PICKPMATCH for which side is the pattern.

ose_rot()

void ose_rot

(

ose_bundle

B

)

Move the third to last element to the end.

Precondition

B must contain at least three elements.

\( \fn{ROT}{ \BB\elems{ \ldots, \ela{K-2}{}, \elb{K-1}{}, \elc{K}{} } }{ \BBtick\elems{ \ldots, \elb{K-2}{}, \elc{K-1}{}, \ela{K}{} } } \)

ose_route1()

void ose_route1

(

ose_bundle

B

)

Route messages in a bundle with patterns that match an address.

The last element is a message that contains a string called the address. The second to last element is a bundle that contains elements whose addresses are patterns. The message is dropped, and all patterns that match the address, fully or partially, are copied into a newly created bundle. The portions of the patterns that matched are stripped.

Precondition

B must contain at least two elements.

The last element must be a message containing a single string.

The second to last element must be a bundle.

See also

ose_routeWithDelegation

ose_select1

ose_selectWithDelegation

ose_gather

\( \fn{ROUTE1}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttbndl}}\items{ \ita{i}{\type{\ttmsg}} }, \elb{K}{\type{\ttmsg(\type{\tts}_i)}} } }{ \BBtick\elems{ \ldots, \ela{K-1}{\type{\ttbndl}}, \elc{K}{\type{\ttbndl}}\items{ \itat{i}{} \pmatchin \ela{}{} } } } \), where the patterns of \(\itat{i}{}\) have been stripped of their matching part.

ose_routeWithDelegation()

void ose_routeWithDelegation

(

ose_bundle

B

)

Route all messages in a bundle with patterns that match one or more addresses.

The last element is a message containing one or more strings called addresses. The second to last element is a bundle that contains elements whose addresses are patterns. Both elements are dropped, and a new bundle created. The new bundle will consist of one bundle for each address containing all elements from the original bundle that matched that address, with the part of their patterns that matched removed, and a final bundle, the delegation bundle, that contains all elements from the original bundle that did not match any of the addresses.

Precondition

B must contain at least two elements.

The last element must be a message containing one or more strings.

The second to last element must be a bundle.

See also

ose_route1

ose_select1

ose_selectWithDelegation

ose_gather

\( \fn{ROUTEWITHDELEGATION}{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{i}{\type{\ttmsg}} }, \elb{K+1}{\type{\ttmsg(\allstrings{1}{L})}}\items{ \itb{1}{\type{\tts}}, \ldots, \itb{L}{\type{\tts}} } } }{ \BBtick\elems{ \ldots, \elc{K}{\type{\ttbndl}}\items{ \itat{i}{} \pmatchin \itb{L}{} }, \ldots, \eld{K+L}{\type{\ttbndl}}\items{ \itat{i}{} \pmatchin \itb{1}{} }, \ele{K+L+1}{\type{\ttbndl}}\items{ \itat{i}{} \pmatchnotin \elb{}{} } } } \), where the patterns of \(\itat{i}{}\) have been stripped of their matching part.

ose_rrot()

void ose_rrot

(

ose_bundle

B

)

Move the last element to the third from the end.

Precondition

B must contain at least three elements.

\( \fn{RROT}{ \BB\elems{ \ldots, \ela{K-2}{}, \elb{K-1}{}, \elc{K}{} } }{ \BBtick\elems{ \ldots, \elc{K-2}{}, \ela{K-1}{}, \elb{K}{} } } \)

ose_select1()

void ose_select1

(

ose_bundle

B

)

Select messages in a bundle with patterns that match an address.

The last element is a message that contains a string called the address. The second to last element is a bundle that contains elements whose addresses are patterns. The message is dropped, and all patterns that match the address, fully or partially, are copied into a newly created bundle, unmodified.

Precondition

B must contain at least two elements.

The last element must be a message containing a single string.

The second to last element must be a bundle.

See also

ose_route1

ose_routeWithDelegation

ose_selectWithDelegation

ose_gather

\( \fn{SELECT1}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttbndl}}\items{ \ita{i}{\type{\ttmsg}} }, \elb{K}{\type{\ttmsg(\type{\tts}_i)}} } }{ \BBtick\elems{ \ldots, \ela{K-1}{\type{\ttbndl}}, \elc{K}{\type{\ttbndl}}\items{ \ita{i}{} \pmatchin \ela{}{} } } } \)

ose_selectWithDelegation()

void ose_selectWithDelegation

(

ose_bundle

B

)

Route all messages in a bundle with patterns that match one or more addresses.

The last element is a message containing one or more strings called addresses. The second to last element is a bundle that contains elements whose addresses are patterns. Both elements are dropped, and a new bundle created. The new bundle will consist of one bundle for each address containing all elements from the original bundle that matched that address, unmodified, and a final bundle, the delegation bundle, that contains all elements from the original bundle that did not match any of the addresses.

Precondition

B must contain at least two elements.

The last element must be a message containing one or more strings.

The second to last element must be a bundle.

See also

ose_select1

ose_route1

ose_routeWithDelegation

ose_gather

\( \fn{SELECTWITHDELEGATION}{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{i}{\type{\ttmsg}} }, \elb{K+1}{\type{\ttmsg(\allstrings{1}{L})}}\items{ \itb{1}{\type{\tts}}, \ldots, \itb{L}{\type{\tts}} } } }{ \BBtick\elems{ \ldots, \elc{K}{\type{\ttbndl}}\items{ \ita{i}{} \pmatchin \itb{L}{} }, \ldots, \eld{K+L}{\type{\ttbndl}}\items{ \ita{i}{} \pmatchin \itb{1}{} }, \ele{K+L+1}{\type{\ttbndl}}\items{ \ita{i}{} \pmatchnotin \elb{}{} } } } \)

ose_setTimetag()

void ose_setTimetag

(

ose_bundle

B

)

Set the bundle's timetag.

This function moves the contents of an 8-byte blob into the timetag field of the bundle B. The message containing the blob is dropped.

Precondition

B must not be empty.

The last element must be a message.

The last item of the last message be a blob containing an OSC timetag (ose_timetag).

\( \fn{SETTIMETAG}{ \BB\elems{ \timetag\mid \ldots, \ela{K}{\type{\ttmsg(\type{\ttb})}}\items{ \ita{}{\type{\ttb}}\values{\valv{}{}} } } }{ \BBtick\elems{ \timetag = \valv{}{}\mid, \ldots } } \), where \(\timetag\) is the timetag field of the bundle, and \(\ela{}{}\) has been removed.

ose_setTypetag()

void ose_setTypetag

(

ose_bundle

B

)

Set the typetag of the last item of the last message.

This function simply chages the typetag, it does not make any change to the content of the data itself. This can be thought of as a reinterpretation of the bytes as a different type.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

See also

ose_setTypetag_impl

Similar functionality can be accomplished using ose_blobToType, however there is an important difference. A blob consists of a size field followed by that number of bytes, and when converting to another type using ose_blobToType, the size of the blob is removed, while ose_setTypetag leaves the entire blob including its size intact and simply changes the typetag.

\( \fn{SETTYPETAG}{ \BB\elems{ \ldots, \ela{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttvar} }, \elb{K}{\type{\ttmsg(\type{\tti})}}\items{ \itb{}{\type{\tti}}\values{\upsilon} } } }{ \BBtick\elems{ \ldots, \elat{K-1}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\upsilon} } } } \)

ose_setTypetag_impl()

void ose_setTypetag_impl	(	ose_bundle	B,
		char	typetag
	)

Set the typetag of the last item of the last message.

This function changes the typetag of a message's item without modifying the contents of the data at all.

This function simply chages the typetag, it does not make any change to the content of the data itself. This can be thought of as a reinterpretation of the bytes as a different type.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

See also

ose_setTypetag

Similar functionality can be accomplished using ose_blobToType, however there is an important difference. A blob consists of a size field followed by that number of bytes, and when converting to another type using ose_blobToType, the size of the blob is removed, while ose_setTypetag leaves the entire blob including its size intact and simply changes the typetag.

\( \fn{SETTYPETAG\_IMPL}{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\ttvar} } }, \upsilon }{ \BBtick\elems{ \ldots, \elat{K}{\type{\ttmsg}}\items{ \ldots, \ita{L}{\upsilon} } } } \)

ose_sizeElem()

void ose_sizeElem

(

ose_bundle

B

)

Get the size of the last element in bytes, including NULL-padding, and excluding the size field.

Creates a new message containing the result as a single int.

Precondition

B must not be empty.

See also

ose_sizeItem

ose_lengthElem

\( \fn{SIZEELEM}{ \BB\elems{\ldots, \ela{K}{}} }{ \BBtick\elems{ \ldots, \ela{K}{}, \elb{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \itb{}{\type{\tti}}\values{\fnsize{ela{}{}}} } } } \)

ose_sizeItem()

void ose_sizeItem

(

ose_bundle

B

)

Get the size of the last item of the last element, including NULL-padding.

Creates a new message containing the number of bytes in the last item of the last element of B, including NULL-padding.

Precondition

B must not be empty.

See also

ose_lengthItem

ose_sizesItems

\( \fn{SIZEITEM}{ \BB\elems{ \ldots, \ela{K}{}\items{ \ldots, \ita{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{ \ldots, \ita{L}{} }, \elb{K+1}{\type{\ttmsg(\type{\tti})}}\items{ \itb{}{\type{\tti}}\values{\fnsize{\ita{}{}}} } } } \)

ose_sizesElems()

void ose_sizesElems

(

ose_bundle

B

)

Get the sizes of all elements as a list, including NULL-padding.

Creates a new message containing a list of the numbers of bytes of all items of the last element of B, including NULL-padding.

Precondition

B must not be empty.

Note

The size of a blob does not include the size field.

See also

ose_sizeElem

Todo:

Implement.

\( \fn{SIZESELEMS}{ \BB\elems{ \ela{1}{}, \ldots, \elb{K}{} } }{ \BBtick\elems{ \ela{1}{}, \ldots, \elb{K}{}, \elc{K+1}{\type{\ttmsg(\allints{1}{K})}}\items{ \ita{1}{\type{\tti}}\values{\fnsize{\ela{}{}}}, \ldots, \itb{K}{\type{\tti}}\values{\fnsize{\elb{}{}}} } } } \)

ose_sizesItems()

void ose_sizesItems

(

ose_bundle

B

)

Get the sizes of all items of the last element as a list, including NULL-padding.

Creates a new message containing a list of the numbers of bytes of all items of the last element of B, excluding NULL-padding.

Precondition

B must not be empty.

See also

ose_sizeItem

ose_lengthsItems

Todo:

Implement.

\( \fn{SIZESITEMS}{ \BB\elems{ \ldots, \ela{K}{}\items{ \ita{1}{}, \ldots, \itb{L}{} }, } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{ \ita{1}{}, \ldots, \itb{L}{} }, \elb{K+1}{\type{\ttmsg(\allints{1}{L})}}\items{ \itc{1}{\type{\tti}}\values{\fnsize{\ita{}{}}}, \ldots, \itd{L}{\type{\tti}}\values{\fnsize{\itb{}{}}}, } } } \)

ose_sub()

void ose_sub

(

ose_bundle

B

)

Subtract the number in the second to last message from the number in the last message.

Precondition

B must contain at least two elements.

The last two elements must be messages.

The last two elements must each contain exactly one numerical value.

The items that the last two elements contain must be of the same type as each other.

\(\fnbinop{SUB}{-}\)

ose_swap()

void ose_swap

(

ose_bundle

B

)

Swap the last two elements.

Precondition

B must contain at least two elements.

\( \fn{SWAP}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots, \elb{K-1}{}, \ela{K}{} } } \)

ose_swapStringToAddress()

void ose_swapStringToAddress

(

ose_bundle

B

)

Exchange the last string of a message with the address.

Precondition

B must not be empty.

The last element must be a message.

The last item of the message must be a string.

\( \fn{SWAPSTRINGTOADDRESS}{ \BB\elems{ \ldots, \ela{K}{\ttmsg(\ldots, \type{\tts}_L)}\items{ \alpha=a\mid \ldots, \itb{L}{\type{\tts}} } } }{ \BBtick\elems{ \ldots, \ela{K}{\ttmsg(\ldots, \type{\tts}_L)}\items{ \alpha=b\mid \ldots, \ita{L}{\type{\tts}} } } } \)

ose_toBlob()

void ose_toBlob

(

ose_bundle

B

)

Cast a value to a blob.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

\(\fntotype{TOBLOB}{\ttb}\)

ose_toFloat()

void ose_toFloat

(

ose_bundle

B

)

Cast a value to a 32-bit float.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

Note

One of the primary uses of this function is to convert a string representation of a number found as part of an OSC address into an integer. For that reason, strings may begin with a leading slash: "/123" will be converted to the int 123.

\(\fntotype{TOFLOAT}{\ttf}\)

ose_toInt32()

void ose_toInt32

(

ose_bundle

B

)

Cast a value to a 32-bit integer.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

Note

One of the primary uses of this function is to convert a string representation of a number found as part of an OSC address into an integer. For that reason, strings may begin with a leading slash: "/123" will be converted to the int 123.

\(\fntotype{TOINT32}{\tti}\)

ose_toString()

void ose_toString

(

ose_bundle

B

)

Cast a value to a string.

Precondition

B must not be empty.

The last element must be a message.

The last element must not be empty.

\(\fntotype{TOSTRING}{\tts}\)

ose_toType()

void ose_toType

(

ose_bundle

B

)

Todo:

Implement.

ose_tuck()

void ose_tuck

(

ose_bundle

B

)

Copy the last element to the third from last position.

Precondition

B must contain at least two elements.

\( \fn{TUCK}{ \BB\elems{ \ldots, \ela{K-1}{}, \elb{K}{} } }{ \BBtick\elems{ \ldots, \elb{K-1}{}, \ela{K}{}, \elb{K+1}{} } } \)

ose_typeof0()

void ose_typeof0

(

ose_bundle

B

)

Get the type signature of the last element of the bundle with no recursion.

See also

ose_typeof1

ose_typeof2

ose_typeof1()

void ose_typeof1

(

ose_bundle

B

)

Get the type signature of the last element of the bundle with one level of recursion.

See also

ose_typeof0

ose_typeof2

ose_typeof2()

void ose_typeof2

(

ose_bundle

B

)

Get the type signature of the last element of the bundle with two levels of recursion.

See also

ose_typeof0

ose_typeof1

ose_unpack()

void ose_unpack

(

ose_bundle

B

)

Unpack the last element.

Each item of the last element is "unpacked" to the top level of B. This is a similar operation to the ose_popAll functions, but the resulting order of new elements is the opposite.

Precondition

B must not be empty.

See also

ose_unpackDrop

\( \fnname{UNPACK}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{}, \ita{K+1}{}, \ldots, \itb{K+L}{} } }, \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \ela{K}{}\items{}, \elb{K+1}{\type{\ttmsg}}\items{ \ita{}{} }, \ldots, \elc{K+L}{}\items{ \itb{}{} } } } \end{array} \right. \)

ose_unpackDrop()

void ose_unpackDrop

(

ose_bundle

B

)

Unpack the last element and drop it.

Each item of the last element is "unpacked" to the top level of B. This is a similar operation to the ose_popAll functions, but the resulting order of new elements is the opposite. Unlike ose_unpack, ose_unpackDrop drops the empty element.

Precondition

B must not be empty.

See also

ose_unpack

\( \fnname{UNPACKDROP}\left\{ \begin{array}{lr} \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttbndl}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \ita{K}{}, \ldots, \itb{K+L-1}{} } }, \\ \fnmapping{ \BB\elems{ \ldots, \ela{K}{\type{\ttmsg}}\items{ \ita{1}{}, \ldots, \itb{L}{} } } }{ \BBtick\elems{ \ldots, \elb{K}{\type{\ttmsg}}\items{ \ita{}{} }, \ldots, \elc{K+L-1}{}\items{ \itb{}{} } } } \end{array} \right. \)