R API

The Safe Runtime (R) is a portable runtime library for embedded applications.

The R library provides management for binary searching, buffering, error handling, events, events, files, hashing, lists, logging, memory, ssl, sockets, strings, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The library can be used in both C and C++ programs.

The R library uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.

The library includes a memory allocator and global memory allocation handler.

The library provides support for fiber coroutines to enable parallel programming without callbacks or complex threads. The network APIs use fibers to transparently block the fiber and resume other fibers automatically. This enables a straight-line "blocking" programming paradigm while enabling other fibers to run as required.

Extensions

RBuf	Dynamic Buffer Module.
REvent	Event Subsystem.
RFile	R File Module.
RHash	Hash table structure.
RList	List data structure.
RLog	Log Services.
RString	R String Module.
RWait	Wait object.
RbTree	Red/Black Tree.

Functions

PUBLIC void	assert(bool cond)
	Asser that a condition is true.
PUBLIC RName *	rAddFmtName(RHash hash, cchar name, int flags, cchar *fmt, ...)
	Add a name and formatted string value into the hash table.
PUBLIC RName *	rAddIntName(RHash hash, cchar name, int64 value)
	Add a name and integer value.
PUBLIC int	rAddItem(RList list, cvoid item)
	Add an item to a list.
PUBLIC RName *	rAddName(RHash table, cchar name, void *ptr, int flags)
	Add a name and value into the hash table.
PUBLIC RName *	rAddNameSubstring(RHash hash, cchar name, ssize nameSize, char *value, ssize valueSize)
	Add a name and value substring into the hash table.
PUBLIC int	rAddNullItem(RList *list)
	Add a null item to the list.
PUBLIC void	rAddNullToBuf(RBuf *buf)
	Add a null character to the buffer contents.
PUBLIC void	rAdjustBufEnd(RBuf *buf, ssize count)
	Adjust the buffer end position.
PUBLIC void	rAdjustBufStart(RBuf *buf, ssize count)
	Adjust the buffer start position.
PUBLIC void *	rAlloc(size_t size)
	Allocate a block of memory.
PUBLIC RBuf *	rAllocBuf(ssize initialSize)
	Create a new buffer.
PUBLIC REvent	rAllocEvent(RFiber fiber, REventProc proc, void data, Ticks delay)
	Allocate and schedule a new event to be run from the event loop.
PUBLIC void	rAllocException(int cause, size_t size)
	Signal a memory allocation exception.
PUBLIC RFiber *	rAllocFiber(RFiberProc fn, cvoid *data)
	Allocate a fiber coroutine object.
PUBLIC RHash *	rAllocHash(int size, int flags)
	Create a hash table.
PUBLIC RList *	rAllocList(int size, int flags)
	Allocate a list.
PUBLIC RLock *	rAllocLock(void)
	Allocate a lock object.
PUBLIC RSocket *	rAllocSocket(void)
	Allocate a socket object.
PUBLIC void *	rAllocType(RType type)
	Allocate an object of a given type.
PUBLIC RWait *	rAllocWait(int fd)
	Allocate a wait object for a file descriptor.
PUBLIC void	rAssert(cchar loc, cchar msg)
	Output an assert failed message.
PUBLIC int	rBackupFile(cchar *path, int count)
	Backup the given file.
PUBLIC void	rBackupLog(void)
	Backup a log.
PUBLIC cchar *	rBasename(cchar *path)
	Return the basename (filename) portion of a filename.
PUBLIC void	rBreakpoint(void)
	Trigger a breakpoint.
PUBLIC char *	rBufToString(RBuf *buf)
	Return a reference to the buffer contents.
PUBLIC char *	rBufToStringAndFree(RBuf *buf)
	Convert the buffer contents to a string.
PUBLIC void	rClearList(RList *list)
	Clears the list of all items.
PUBLIC RHash *	rCloneHash(RHash *master)
	Copy a hash table.
PUBLIC void	rCloseSocket(RSocket *sp)
	Close a socket.
PUBLIC void	rCompactBuf(RBuf *buf)
	Compact the buffer contents.
PUBLIC int	rConnectSocket(RSocket sp, cchar host, int port, Ticks deadline)
	Connect a client socket.
PUBLIC ssize	rCopyFile(cchar from, cchar to, int mode)
	Copy a file.
PUBLIC int	rCreateThread(cchar name, void proc, void *data)
	Create an O/S thread.
PUBLIC int	rDaemonize(void)
	For the current process and run as a daemon.
PUBLIC void	rDebug(cchar source, cchar fmt, ...)
	Emit a debug message to the log.
PUBLIC void	rDefaultLogHandler(cchar type, cchar source, cchar *msg)
	The default log handler.
PUBLIC bool	rEmitLog(cchar type, cchar source)
	Test if a log message should be emitted.
PUBLIC void	rError(cchar source, cchar fmt, ...)
	Emit an error message to the log.
PUBLIC void	rFlushBuf(RBuf *buf)
	Flush the buffer contents.
PUBLIC char *	rFormatLocalTime(cchar *format, Time time)
	Convert a time value to local time and format as a string.
PUBLIC RBuf *	rFormatLog(RBuf buf, cchar type, cchar source, cchar msg)
	Format a log message into a buffer.
PUBLIC char *	rFormatUniversalTime(cchar *format, Time time)
	Convert a time value to universal time and format as a string.
PUBLIC void	rFree(void *ptr)
	Free a block of memory allocated via rAlloc.
PUBLIC void	rFreeBuf(RBuf *buf)
	Free a buffer.
PUBLIC void	rFreeFiber(RFiber *fiber)
	Free a fiber coroutine.
PUBLIC void	rFreeHash(RHash *hash)
	Free a hash table.
PUBLIC void	rFreeList(RList *list)
	Free a list.
PUBLIC void	rFreeLock(RLock *mutex)
	Free a dynamically allocated lock object.
PUBLIC void	rFreeSocket(RSocket *sp)
	Free a socket object.
PUBLIC void	rFreeWait(RWait *wp)
	Free a wait object.
PUBLIC char *	rGetAppDir(void)
	Get the directory containing the application executable.
PUBLIC cchar *	rGetAppName(void)
	Get the application name defined via rSetAppName.
PUBLIC ssize	rGetBlockFromBuf(RBuf buf, char blk, ssize count)
	Get a block of data from the buffer.
PUBLIC cchar *	rGetBuf(RBuf *buf)
	Get the origin of the buffer content storage.
PUBLIC cchar *	rGetBufEnd(RBuf *buf)
	Get a reference to the end of the buffer contents.
PUBLIC ssize	rGetBufLength(RBuf *buf)
	Get the buffer content length.
PUBLIC ssize	rGetBufSize(RBuf *buf)
	Get the current size of the buffer content storage.
PUBLIC ssize	rGetBufSpace(RBuf *buf)
	Get the space available to store content.
PUBLIC cchar *	rGetBufStart(RBuf *buf)
	Get the start of the buffer contents.
PUBLIC int	rGetCharFromBuf(RBuf *buf)
	Get a character from the buffer.
PUBLIC RThread	rGetCurrentThread(void)
	Get the current Thread.
PUBLIC char *	rGetCwd(void)
	Get the current application working directory.
PUBLIC char *	rGetDate(cchar *format)
	Get a string representation of the current date/time.
PUBLIC Ticks	rGetElapsedTicks(Ticks mark)
	Get the elapsed time since a ticks mark.
PUBLIC cchar *	rGetError(int error)
	Return a string representation of an R error code.
PUBLIC RFiber *	rGetFiber(void)
	Get the current fiber object.
PUBLIC void *	rGetFiberStack(void)
	Get the base address of the fiber stack.
PUBLIC RList *	rGetFiles(cchar base, cchar pattern, int flags)
	Create a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC RList *	rGetFilesEx(RList results, cchar base, cchar *pattern, int flags)
	Get a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC int	rGetHashLength(RHash *hash)
	Return the count of symbols in a symbol entry.
uint64	rGetHiResTicks(void)
	Get the CPU tick count.
PUBLIC char *	rGetIsoDate(Time time)
	Get an ISO Date string representation of the given date/time.
PUBLIC void *	rGetItem(RList *list, int index)
	Get an list item.
PUBLIC int	rGetListLength(RList *list)
	Get the number of items in the list.
PUBLIC int	rGetLogFile(void)
	Get the log file file handle.
PUBLIC RLogHandler	rGetLogHandler(void)
	Return the currently configured log handler defined via rSetLogHandler
PUBLIC void *	rGetNextItem(RList list, int lastIndex)
	Get the next item in the list.
PUBLIC RName *	rGetNextName(RHash hash, RName next)
	Return the next symbol in a symbol entry.
PUBLIC int	rGetOsError(void)
	Return the native O/S error code.
PUBLIC Ticks	rGetRemainingTicks(Ticks mark, Ticks timeout)
	Return the time remaining until a timeout has elapsed.
PUBLIC cchar *	rGetServerName(void)
	Get the application server name string.
PUBLIC int	rGetSocketAddr(RSocket sp, char ipbuf, int ipbufLen, int *port)
	Get the locally bound socket IP address and port for the socket.
PUBLIC Socket	rGetSocketHandle(RSocket *sp)
	Get the socket file descriptor.
PUBLIC int	rGetState(void)
	Get the current R state.
PUBLIC char *	rGetTempFile(cchar dir, cchar prefix)
	Get a temp filename.
PUBLIC Ticks	rGetTicks(void)
	Get the system time.
PUBLIC Time	rGetTime(void)
	Get the time.
PUBLIC bool	rGetTimeouts(void)
	Return true if timeouts are enabled.
PUBLIC int	rGetWaitFd(void)
	Get the global wait descriptor.
PUBLIC void	rGlobalLock(void)
	Globally lock the application.
PUBLIC void	rGlobalUnlock(void)
	Unlock the global mutex.
PUBLIC void	rGracefulStop(void)
	Gracefully stop the app.
PUBLIC int	rGrowBuf(RBuf *buf, ssize count)
	Grow the buffer.
PUBLIC int	rGrowList(RList *list, int size)
	Grow the list to be at least the requested size in elements.
PUBLIC char *	rHashToJson(RHash *hash, int pretty)
	Convert a hash into JSON.
PUBLIC RBuf *	rHashToJsonBuf(RHash hash, RBuf buf, int pretty)
	Convert a hash into JSON in the given buffer.
PUBLIC char *	rHashToString(RHash hash, cchar join)
	Convert a hash of strings to a single string.
PUBLIC void	rInfo(cchar source, cchar fmt, ...)
	Emit an informational message to the log.
PUBLIC int	rInit(RFiberProc fn, cvoid *arg, ssize stackSize)
	Initialize the runtime.
PUBLIC int	rInitBuf(RBuf *buf, ssize size)
	Initialize the buffer and set the initial buffer size.
PUBLIC int	rInitFibers(ssize stackSize)
	Initialize the fiber coroutine module.
PUBLIC RLock *	rInitLock(RLock *mutex)
	Initialize a statically allocated lock object.
PUBLIC int	rInitLog(void)
	Initialize the logging subsystem.
PUBLIC int	rInitOs(void)
	Create and initialze the O/S dependent subsystem.
PUBLIC int	rInitWait(void)
	Initialize the I/O wait subsystem.
PUBLIC int	rInserCharToBuf(RBuf *buf, int c)
	Inser a character into the buffer.
PUBLIC int	rInsertItemAt(RList list, int index, cvoid item)
	Inser an item into a list at a specific position.
PUBLIC bool	rIsFileAbs(cchar *path)
	Determine if a file path is an absolute path.
PUBLIC bool	rIsLogSet(void)
	Test if the log has been configured.
PUBLIC bool	rIsMain(void)
	Test if a fiber is the main fiber.
PUBLIC bool	rIsSocketClosed(RSocket *sp)
	Test if the socket has been closed.
PUBLIC bool	rIsSocketConnected(RSocket *sp)
	Determine if the socket has connected to a remote pper.
PUBLIC bool	rIsSocketEof(RSocket *sp)
	Test if the other end of the socket has been closed.
PUBLIC bool	rIsSocketHandshaking(RSocket *sp)
	Determine if the socket is partway through a TLS handshake.
PUBLIC bool	rIsSocketSecure(RSocket *sp)
	Determine if the socket is secure.
PUBLIC char *	rJoinFile(cchar base, cchar other)
	Join file paths.
PUBLIC char *	rJoinFileBuf(char buf, ssize bufsize, cchar base, cchar *other)
	Join paths into a buffer.
PUBLIC char *	rListToString(RList list, cchar join)
	Convert a list of strings to a single string.
PUBLIC int	rListenSocket(RSocket sp, cchar host, int port, RSocketProc handler, void *arg)
	Listen on a server socket for incoming connections.
PUBLIC void	rLock(RLock *lock)
	Lock access.
PUBLIC void	rLog(char type, cchar source, cchar *fmt, ...)
	Write a message to the error log file.
PUBLIC void	rLogConfig(void)
	Print the product configuration at the start of the log file.
PUBLIC void	rLogv(cchar type, cchar source, cchar *fmt, va_list args)
	Write a message to the log file.
PUBLIC int	rLookAtLastCharInBuf(RBuf *buf)
	Peek at the last character in the buffer.
PUBLIC int	rLookAtNextCharInBuf(RBuf *buf)
	Peek at the next character in the buffer.
PUBLIC bool	rLookupEvent(REvent id)
	Lookup an event ID.
PUBLIC int	rLookupItem(RList list, cvoid item)
	Find an item and return its index.
PUBLIC void *	rLookupName(RHash hash, cchar name)
	Lookup a symbol in the hash table.
PUBLIC RName *	rLookupNameEntry(RHash hash, cchar name)
	Lookup a symbol in the hash table and return the hash entry.
PUBLIC int	rLookupStringItem(RList list, cchar str)
	Find a string item and return its index.
PUBLIC bool	rMatchFile(cchar path, cchar pattern)
	Matach a file against a glob pattern.
PUBLIC void *	rMemdup(cvoid *ptr, size_t size)
	Duplicate a block of memory.
PUBLIC void	rMetrics(cchar message, cchar namespace, cchar dimensions, cchar values, ...)
	Emit an EMF metrics message suitable for AWS CloudWatch Metrics.
PUBLIC Time	rParseIsoDate(cchar *when)
	Parse an ISO date string.
PUBLIC void *	rPopItem(RList *list)
	Pop an item.
PUBLIC void	rPushItem(RList list, void item)
	Push an item onto the list.
PUBLIC ssize	rPutBlockToBuf(RBuf buf, cchar ptr, ssize size)
	Put a block to the buffer.
PUBLIC int	rPutCharToBuf(RBuf *buf, int c)
	Put a character to the buffer.
PUBLIC ssize	rPutIntToBuf(RBuf *buf, int64 i)
	Put an integer to the buffer.
PUBLIC ssize	rPutStringToBuf(RBuf buf, cchar str)
	Put a string to the buffer.
PUBLIC ssize	rPutSubToBuf(RBuf buf, cchar str, ssize count)
	Put a substring to the buffer.
PUBLIC ssize	rPutToBuf(RBuf buf, cchar fmt, ...)
	Put a formatted string to the buffer.
PUBLIC char *	rReadFile(cchar path, ssize lenp)
	Read data from a file.
PUBLIC ssize	rReadSocket(RSocket sp, char buf, ssize bufsize, Ticks deadline)
	Read from a socket.
PUBLIC ssize	rReadSocketSync(RSocket sp, char buf, ssize bufsize)
	Read from a socket.
PUBLIC int	rRemoveItem(RList list, cvoid item)
	Remove an item from the list.
PUBLIC int	rRemoveItemAt(RList *list, int index)
	Remove an item from the list.
PUBLIC int	rRemoveName(RHash hash, cchar name)
	Remove a symbol entry from the hash table.
PUBLIC int	rRemoveStringItem(RList list, cchar str)
	Remove a string item from the list.
PUBLIC int	rReserveBufSpace(RBuf *buf, ssize need)
	Grow the buffer so that there is at least the needed minimum space available.
PUBLIC void	rResetBufIfEmpty(RBuf *buf)
	Reset the buffer.
PUBLIC void	rResetSocket(RSocket *sp)
	Reset a socket.
PUBLIC void *	rResumeFiber(RFiber fiber, void result)
	Resume a fiber.
PUBLIC Ticks	rRunEvents(void)
	Run due events.
PUBLIC int	rServiceEvents(void)
	Service events.
PUBLIC int	rSetAppName(cchar name, cchar title, cchar *version)
	Set the application name, title and version.
PUBLIC void	rSetDefaultSocketCa(cchar *ca)
	Set the default CA root certificate bundle.
PUBLIC void	rSetError(int error)
	Set the error code.
PUBLIC void	rSetFiberStack(ssize size)
	Set the default fiber stack size.
PUBLIC void *	rSetItem(RList list, int index, cvoid item)
	Set a list item.
PUBLIC int	rSetLog(cchar spec, cchar format, bool force)
	Initialize logging.
PUBLIC void	rSetLogFilter(cchar types, cchar sources, bool force)
	Define a filter for log messages.
PUBLIC RLogHandler	rSetLogHandler(RLogHandler handler)
	Define a log handler routine that will be invoked to process log messages.
PUBLIC void	rSetMemHandler(RMemProc handler)
	Define a global memory exhaustion handler.
PUBLIC void	rSetOsError(int error)
	Set the O/S error code.
PUBLIC void	rSetSocketBlocking(RSocket *sp, bool on)
	Set a socket into blocking I/O mode.
PUBLIC void	rSetSocketCerts(RSocket sp, cchar key, cchar cert, cchar ca, cchar *revoke)
	Configure the socket TLS certificates.
PUBLIC void	rSetSocketCiphers(RSocket sp, cchar ciphers)
	Set the ciphers to use for communications.
PUBLIC void	rSetSocketVerify(RSocket *sp, int verifyPeer, int verifyIssuer)
	Set the socket TLS verification parameters.
PUBLIC void	rSetSocketWaitMask(RSocket *sp, int64 mask, Ticks deadline)
	Update the wait mask for a socket.
PUBLIC void	rSetState(int state)
	Set the R state.
PUBLIC void	rSetTimeouts(bool on)
	Control timeouts.
PUBLIC void	rSetWaitHandler(RWait wp, RWaitProc handler, cvoid arg, int64 mask)
	Define a wait handler function on a wait object.
PUBLIC void	rSetWaitMask(RWait *wp, int64 mask, Ticks deadline)
	Update the wait mask for a wait handler.
PUBLIC void	rSignal(cchar name, cvoid arg)
	Signal watches of a named event.
PUBLIC void	rSleep(Ticks ticks)
	Sleep a fiber for the requested number of milliseconds.
PUBLIC void *	rSort(void base, ssize num, ssize width, RSortProc compare, void ctx)
	Quicksort.
PUBLIC RList *	rSortList(RList list, RSortProc compare, void ctx)
	Sor a list.
PUBLIC int	rSpawnFiber(RFiberProc fn, void *arg)
	Spawn a fiber coroutine.
PUBLIC void *	rSpawnThread(RThreadProc fn, void *arg)
	Spawn an O/S thread.
PUBLIC REvent	rStartEvent(REventProc proc, void *data, Ticks delay)
	Start a callback event.
PUBLIC void	rStartFiber(RFiber fiber, void data)
	Start a fiber coroutine.
PUBLIC void	rStop(void)
	Immediately stop the app.
PUBLIC int	rStopEvent(REvent id)
	Stop an event.
PUBLIC void	rTermBuf(RBuf *buf)
	Terminate a buffer.
PUBLIC void	rTermFibers(void)
	Terminate the fiber coroutine module.
PUBLIC void	rTermLock(RLock *mutex)
	Terminate a statically allocated lock object.
PUBLIC void	rTermLog(void)
	Terminate logging.
PUBLIC void	rTermOs(void)
	Stop the O/S dependent subsystem.
PUBLIC void	rTermWait(void)
	Terminate the I/O wait subsystem.
PUBLIC bool	rTryLock(RLock *lock)
	Attempt to lock access.
PUBLIC void	rUnlock(RLock *lock)
	Unlock a mutex.
PUBLIC int	rWait(Ticks timeout)
	Wait for an I/O event.
PUBLIC void *	rWaitForIO(RWait *wp, int mask, Ticks deadline)
	Wait for an IO event on a wait object.
PUBLIC int	rWalkDir(cchar dir, cchar pattern, RWalkDirProc callback, void *arg, int flags)
	Walk a directory tree and invoke a callback for each path that matches a given pattern.
PUBLIC void	rWatch(cchar name, RWatchProc proc, void data)
	Watch for a named event to happen.
PUBLIC void	rWatchOff(cchar name, RWatchProc proc, void data)
	Stop watching for a named event to happen.
PUBLIC ssize	rWriteFile(cchar path, cchar buf, ssize len, int mode)
	Write data to a file.
PUBLIC int	rWritePid(void)
	Write the current process pid to /var/run.
PUBLIC ssize	rWriteSocket(RSocket sp, cvoid buf, ssize bufsize, Ticks deadline)
	Write to a socket.
PUBLIC ssize	rWriteSocketSync(RSocket sp, cvoid buf, ssize len)
	Write to a socket.
PUBLIC void *	rYieldFiber(void *value)
	Yield a fiber back to the main fiber.
PUBLIC RbTree *	rbAlloc(int flags, RbFree free, RbCompare compare)
	Allocate a red/black tree.
PUBLIC RbNode *	rbFirst(RbTree *rbt)
	Return the lexically first node.
PUBLIC void	rbFree(RbTree *rbt)
	Free a red/black tree.
PUBLIC RbNode *	rbInsert(RbTree rbt, void data)
	Insert a new data item in the tree.
PUBLIC RbNode *	rbLookup(RbTree rbt, void data, void *ctx)
	Lookup a data item.
PUBLIC RbNode *	rbLookupFirst(RbTree rbt, void data, void *ctx)
	Return the lexically first matching node.
PUBLIC RbNode *	rbLookupNext(RbTree rbt, RbNode node, void data, void ctx)
	Return the next matching node after the given node.
PUBLIC RbNode *	rbNext(RbTree rbt, RbNode node)
	Return the next node in sequence.
PUBLIC void *	rbRemove(RbTree rbt, RbNode node, int keep)
	Remove a data item from the tree.
PUBLIC char *	scamel(cchar *str)
	Create a camel case version of the string.
PUBLIC int	scaselesscmp(cchar s1, cchar s2)
	Compare strings ignoring case.
PUBLIC bool	scaselessmatch(cchar s1, cchar s2)
	Compare strings ignoring case.
PUBLIC char *	schr(cchar *str, int c)
	Find a character in a string.
PUBLIC char *	sclone(cchar *str)
	Clone a string.
PUBLIC int	scmp(cchar s1, cchar s2)
	Compare strings.
PUBLIC char *	scontains(cchar str, cchar pattern)
	Find a pattern in a string.
PUBLIC ssize	scopy(char dest, ssize destMax, cchar src)
	Copy a string.
PUBLIC cchar *	sends(cchar str, cchar suffix)
	Test if the string ends with a given pattern.
PUBLIC char *	sfmt(cchar *fmt, ...)
	Format a string.
PUBLIC char *	sfmtbuf(char buf, ssize maxSize, cchar fmt, ...)
	Format a string into a static buffer.
PUBLIC char *	sfmtbufv(char buf, ssize maxSize, cchar fmt, va_list args)
	Format a string into a statically allocated buffer.
PUBLIC char *	sfmtv(cchar *fmt, va_list args)
	Format a string.
PUBLIC uint	shash(cchar *str, ssize len)
	Compute a hash code for a string.
PUBLIC uint	shashlower(cchar *str, ssize len)
	Compute a caseless hash code for a string.
PUBLIC char *	sitos(int64 value)
	Convert an integer to a string.
PUBLIC char *	sitosbuf(char *buf, ssize size, int64 value, int radix)
	Convert an integer to a string buffer.
PUBLIC char *	sitosradix(int64 value, int radix)
	Convert an integer to a string.
PUBLIC char *	sjoin(cchar *str, ...)
	Catenate strings.
PUBLIC cchar *	sjoinArgs(int argc, cchar *argv, cchar sep)
	Join an array of strings.
PUBLIC char *	sjoinfmt(cchar str, cchar fmt, ...)
	Join a formatted string to an existing string.
PUBLIC char *	sjoinv(cchar *str, va_list args)
	Catenate strings.
PUBLIC ssize	slen(cchar *str)
	Return the length of a string.
PUBLIC char *	slower(char *str)
	Convert a string to lower case.
PUBLIC bool	smatch(cchar s1, cchar s2)
	Compare strings.
PUBLIC int	sncaselesscmp(cchar s1, cchar s2, ssize len)
	Compare strings ignoring case.
PUBLIC char *	sncaselesscontains(cchar str, cchar pattern, ssize limit)
	Find a pattern in a string with a limit using a caseless comparison.
PUBLIC char *	snclone(cchar *str, ssize len)
	Clone a substring.
PUBLIC int	sncmp(cchar s1, cchar s2, ssize len)
	Compare strings.
PUBLIC char *	sncontains(cchar str, cchar pattern, ssize limit)
	Find a pattern in a string with a limit.
PUBLIC ssize	sncopy(char dest, ssize destMax, cchar src, ssize len)
	Copy characters from a string.
PUBLIC char *	spbrk(cchar str, cchar set)
	Locate the a character from a set in a string.
PUBLIC char *	sptok(char str, cchar pattern, char **last)
	Tokenize a string.
PUBLIC char *	srchr(cchar *str, int c)
	Find a character in a string by searching backwards.
PUBLIC char *	ssplit(char str, cchar delim, char **last)
	Split a string at a delimiter.
PUBLIC ssize	sspn(cchar str, cchar set)
	Find the end of a spanning prefix.
PUBLIC bool	sstarts(cchar str, cchar prefix)
	Test if the string starts with a given pattern.
PUBLIC char *	ssub(cchar *str, ssize offset, ssize length)
	Create a substring.
PUBLIC char *	stemplate(cchar str, void tokens)
	Replace template tokens in a string with values from a lookup table.
PUBLIC char *	stitle(cchar *str)
	Create a Title Case version of the string.
PUBLIC double	stof(cchar *str)
	Convert a string to a double.
PUBLIC int64	stoi(cchar *str)
	Convert a string to an integer.
PUBLIC int64	stoiradix(cchar str, int radix, int err)
	Convert a string to an integer.
PUBLIC char *	stok(char str, cchar delim, char **last)
	Tokenize a string.
PUBLIC struct RList *	stolist(cchar *src)
	String to list.
PUBLIC char *	strim(char str, cchar set, int where)
	Trim a string.
PUBLIC char *	supper(char *str)
	Convert a string to upper case.
PUBLIC void	szero(char *str)
	Erase the contents of a string.

Typedefs

REventProc	Callback function for events.
RFiber	Fiber state.
RFiberContext	Fiber coroutine stack context.
RFiberProc	Fiber entry point function.
RHashProc	Hashing function to use for the table.
RListCompareProc	List comparison procedure for soring.
RLock	Multithreading lock control structure.
RLogHandler	Log handler callback type.
RMemProc	Memory exhaustion callback procedure.
RName	Per item structure.
RSortProc	Quicksort callback function.
RThreadProc	Thread entry point function.
RWaitProc	Callback function for IO wait events.
RWalkDirProc	Callback function for rWalkDir
RWatchProc	Callback function for watched events.
RbCompare	Callback to compare a data nodes.
RbFree	Callback to free a nodes associated data.
Socket	Argument for sockets.
size_t	Unsigned integral type.
time_t	Unsigned time type.

Defines

#define	ITERATE_INDEX node = rbLookupFirst(rbt, key, ctx); node; node = rbLookupNext(rbt, node, key, ctx)
	Traverse an index over matching nodes.
#define	ME_R_LOGGING 1
	Default for logging is "on".
#define	R_DEFAULT_DATE "%a %b %d %T %Y %Z"
	Default date format used in rFormatLocalTime/rFormatUniversalTime when no format supplied E.g.
#define	R_DYNAMIC_NAME 0x8
	Dynamic name provided, hash will free.
#define	R_DYNAMIC_VALUE 0x1
	Dynamic (allocated) value provided, hash will free.
#define	R_EVENT_ASYNC 1
	Windows async select.
#define	R_EVENT_EPOLL 2
	epoll_wait.
#define	R_EVENT_KQUEUE 3
	BSD kqueue.
#define	R_EVENT_SELECT 4
	traditional select().
#define	R_HASH_CASELESS 0x40
	Ignore case in comparisons.
#define	R_IO 0x6
	Wait mask for readable or writeable events.
#define	R_MEM_FAIL 0x4
	Memory allocation failed - immediate exit.
#define	R_MEM_LIMIT 0x2
	Memory use exceeds memory limit - invoking policy.
#define	R_MEM_TOO_BIG 0x8
	Memory allocation request is too big - immediate exit.
#define	R_MEM_WARNING 0x1
	Memory use exceeds warnHeap level limit.
#define	R_MODIFIED 0x200
	Wait mask for modify events.
#define	R_READABLE 0x2
	Wait mask for readable events.
#define	R_SOCKET_CLOSED 0x1
	RSocket has been closed.
#define	R_SOCKET_EOF 0x2
	Seen end of file.
#define	R_SOCKET_LISTENER 0x4
	RSocket is server listener.
#define	R_SOCKET_SERVER 0x8
	Socket is on the server-side.
#define	R_STATIC_NAME 0x10
	Static name provided no need to clone or free.
#define	R_STATIC_VALUE 0x2
	Static value provided, no need to clone or free.
#define	R_TEMPORAL_NAME 0x20
	Temporal name provided, hash will clone and free.
#define	R_TEMPORAL_VALUE 0x4
	Temporal value provided, hash will clone and free.
#define	R_TRIM_BOTH 0x3
	Flag for strim to trim from both the start and the end of the string.
#define	R_TRIM_END 0x2
	Flag for strim to trim from the end of the string.
#define	R_TRIM_START 0x1
	Flag for strim to trim from the start of the string.
#define	R_WALK_DEPTH_FIRST 0x1
	Flag for rGetFiles to do a depth-first traversal.
#define	R_WALK_DIRS 0x4
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_FILES 0x8
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_HIDDEN 0x2
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_MISSING 0x20
	Allow walking missing paths.
#define	R_WALK_RELATIVE 0x10
	Return paths relative to the original path.
#define	R_WRITABLE 0x4
	Wait mask for writable events.
#define	RB_DUP 0x1
	Flags for rbAlloc to permit duplicate keys.
#define	ITERATE_INDEX node = rbLookupFirst(rbt, key, ctx); node; node = rbLookupNext(rbt, node, key, ctx)
	Traverse an index over matching nodes.

RBuf

Dynamic Buffer Module.

Description:: RBuf is a flexible, dynamic growable buffer structure. It has start and end pointers to the data buffer which act as read/write pointers. Routines are provided to get and put data into and out of the buffer and automatically advance the appropriate start/end pointer. By definition, the buffer is empty when the start pointer == the end pointer. Buffers can be created with a fixed size or can grow dynamically as more data is added to the buffer.

For performance, the specification of RBuf is deliberately exposed. All members of RBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.

See Also:: rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

API Stability:: Internal.

Fields:

char *	buf	Actual buffer for data.
ssize	buflen	Current size of buffer.
char *	end	Pointer one past the last data chr.
char *	endbuf	Pointer one past the end of buffer.
char *	start	Pointer to next data char.

PUBLIC void void rAddNullToBuf (RBuf *buf)

Add a null character to the buffer contents.

Description:: Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling rGetBufStart and using the returned pointer as a "C" string pointer.

Parameters:

buf	Buffer created via rAllocBuf.

API Stability:: Evolving.

See Also:: RBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rAdjustBufEnd (RBuf *buf, ssize count)

Adjust the buffer end position.

Description:: Adjust the buffer end position by the specified amount. This is typically used to advance the end position as content is appended to the buffer. Adjusting the start or end position will change the value returned by rGetBufLength. If using the rPutBlock or rPutChar routines, adjusting the end position is done automatically.

Parameters:

buf	Buffer created via rAllocBuf.
count	Positive or negative count of bytes to adjust the end position.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rAdjustBufStart (RBuf *buf, ssize count)

Adjust the buffer start position.

Description:: Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by rGetBufLength. If using the rGetBlock or rGetChar routines, adjusting the start position is done automatically.

Parameters:

buf	Buffer created via rAllocBuf.
count	Positive or negative count of bytes to adjust the start position.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC RBuf * RBuf * rAllocBuf (ssize initialSize)

Create a new buffer.

Description:: Create a new buffer.

Parameters:

initialSize

Initial size of the buffer.

Returns:: A new buffer.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC char * char * rBufToString (RBuf *buf)

Return a reference to the buffer contents.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: A pointer into the buffer data. Caller must not free.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC char * char * rBufToStringAndFree (RBuf *buf)

Convert the buffer contents to a string.

The string is allocated and the buffer is freed

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: Allocated string.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rCompactBuf (RBuf *buf)

Compact the buffer contents.

Description:: Compact the buffer contents by copying the contents down to start the the buffer origin.

Parameters:

buf	Buffer created via rAllocBuf.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rFlushBuf (RBuf *buf)

Flush the buffer contents.

Description:: Discard the buffer contents and reset the start end content pointers.

Parameters:

buf	Buffer created via rAllocBuf.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rFreeBuf (RBuf *buf)

Free a buffer.

Parameters:

buf	Buffere created via rAllocBuf

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rGetBlockFromBuf (RBuf *buf, char *blk, ssize count)

Get a block of data from the buffer.

Description:: Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.

Parameters:

buf	Buffer created via rAllocBuf.
blk	Destination block for the read data.
count	Count of bytes to read from the buffer.

Returns:: The count of bytes read into the block or -1 if the buffer is empty.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC cchar * cchar * rGetBuf (RBuf *buf)

Get the origin of the buffer content storage.

Description:: Get a pointer to the start of the buffer content storage. This is always and allocated block.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: A pointer to the buffer content storage.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC cchar * cchar * rGetBufEnd (RBuf *buf)

Get a reference to the end of the buffer contents.

Description:: Get a pointer to the location immediately after the end of the buffer contents.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: Pointer to the end of the buffer data contents. Points to the location one after the last data byte.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rGetBufLength (RBuf *buf)

Get the buffer content length.

Description:: Get the length of the buffer contents. This is not the same as the buffer size which may be larger.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: The length of the content stored in the buffer in bytes.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rGetBufSize (RBuf *buf)

Get the current size of the buffer content storage.

Description:: This returns the size of the memory block allocated for storing the buffer contents.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: The size of the buffer content storage.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rGetBufSpace (RBuf *buf)

Get the space available to store content.

Description:: Get the number of bytes available to store content in the buffer.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: The number of bytes available.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC cchar * cchar * rGetBufStart (RBuf *buf)

Get the start of the buffer contents.

Description:: Get a pointer to the start of the buffer contents. Use rGetBufLength to determine the length of the content. Use rGetBufEnd to get a pointer to the location after the end of the content.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: Pointer to the start of the buffer data contents.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rGetCharFromBuf (RBuf *buf)

Get a character from the buffer.

Description:: Get the next byte from the buffer start and advance the start position.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: The character or -1 if the buffer is empty.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rGrowBuf (RBuf *buf, ssize count)

Grow the buffer.

Description:: Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via rAllocBuf or rInitBuf

Parameters:

buf	Buffer created via rAllocBuf.
count	Count of bytes by which to grow the buffer content size.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rInitBuf (RBuf *buf, ssize size)

Initialize the buffer and set the initial buffer size.

Description:: This initializes a buffer that is already allocated and is useful for static buffer declarations. This call sets the initial buffer content size. Setting a non-zero size will immediately grow the buffer to be this size.

Parameters:

buf	Buffer created via rAllocBuf.
size	Size to make the buffer.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rInserCharToBuf (RBuf *buf, int c)

Inser a character into the buffer.

Description:: Inser a character into to the buffer prior to the current buffer start point.

Parameters:

buf	Buffer created via rAllocBuf.
c	Character to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rLookAtLastCharInBuf (RBuf *buf)

Peek at the last character in the buffer.

Description:: Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rLookAtNextCharInBuf (RBuf *buf)

Peek at the next character in the buffer.

Description:: Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.

Parameters:

buf	Buffer created via rAllocBuf.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rPutBlockToBuf (RBuf *buf, cchar *ptr, ssize size)

Put a block to the buffer.

Description:: Append a block of data to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
ptr	Block to append.
size	Size of block to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rPutCharToBuf (RBuf *buf, int c)

Put a character to the buffer.

Description:: Append a character to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
c	Character to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rPutIntToBuf (RBuf *buf, int64 i)

Put an integer to the buffer.

Description:: Append a integer to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
i	Integer to append to the buffer.

Returns:: Number of characters added to the buffer, otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rPutStringToBuf (RBuf *buf, cchar *str)

Put a string to the buffer.

Description:: Append a null terminated string to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
str	String to append.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rPutSubToBuf (RBuf *buf, cchar *str, ssize count)

Put a substring to the buffer.

Description:: Append a null terminated substring to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
str	String to append.
count	Put at most count characters to the buffer.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rResetBufIfEmpty

PUBLIC ssize ssize rPutToBuf (RBuf *buf, cchar *fmt, ...)

Put a formatted string to the buffer.

Description:: Format a string and append to the buffer at the end position and increment the end pointer.

Parameters:

buf	Buffer created via rAllocBuf.
fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC int int rReserveBufSpace (RBuf *buf, ssize need)

Grow the buffer so that there is at least the needed minimum space available.

Description:: Grow the storage allocated for content for the buffer if required to ensure the minimum specified by "need" is available.

Parameters:

buf	Buffer created via rAllocBuf.
need	Required free space in bytes.

Returns:: Zero if successful and otherwise a negative error code.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

PUBLIC void void rResetBufIfEmpty (RBuf *buf)

Reset the buffer.

Description:: If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.

Parameters:

buf	Buffer created via rAllocBuf.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf

PUBLIC void void rTermBuf (RBuf *buf)

Terminate a buffer.

Description:: This frees memory allocated by the buffer. This call should be used for buffers initialized via rInitBuf

Parameters:

buf	Buffer created via rAllocBuf.

API Stability:: Evolving.

See Also:: RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

REvent

Event Subsystem.

Description:: R provides a simple based eventing mechanism. Events are described by REvent objects which are created and queued via rStartEvent. Events are scheduled once unless restarted via rRestartEvent.

API Stability:: Internal.

Fields:

PUBLIC bool bool rLookupEvent (REvent id)

Lookup an event ID.

Parameters:

id	Event id allocated by rStartEvent.

Returns:: True if the event exists.

API Stability:: Evolving.

PUBLIC Ticks Ticks rRunEvents (void )

Run due events.

Returns:: Time delay till the next event.

API Stability:: Evolving.

PUBLIC int int rServiceEvents (void )

Service events.

Description:: This call blocks and continually services events on the event loop until the app is instructed to exit via $rStop. An app should call rServiceEvents from the main program.

Returns:: The current R state.

API Stability:: Evolving.

PUBLIC void void rSetWaitMask (RWait *wp, int64 mask, Ticks deadline)

Update the wait mask for a wait handler.

Parameters:

wp	RWait object.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until.

API Stability:: Evolving.

PUBLIC void void rSignal (cchar *name, cvoid *arg)

Signal watches of a named event.

Parameters:

name	Named event.
arg	Data argument to pass to the watch function.

API Stability:: Evolving.

PUBLIC REvent REvent rStartEvent (REventProc proc, void *data, Ticks delay)

Start a callback event.

Description:: This schedules an event to run once. The event can be rescheduled in the callback by invoking rRestartEvent.

Parameters:

proc	Callback procedure function. Signature is: void (fn)(void data, int id).
data	Data reference to pass to the callback.
delay	Delay in milliseconds in which to run the callback.

Returns:: A positive integer event ID.

API Stability:: Evolving.

PUBLIC int int rStopEvent (REvent id)

Stop an event.

Parameters:

id	Event id allocated by rStartEvent.

Returns:: Integer handle index. Otherwise return -1 on allocation errors.

API Stability:: Evolving.

PUBLIC int int rWait (Ticks timeout)

Wait for an I/O event.

Description:: This is typically called by $rServiceEvents to wait for I/O events.

Parameters:

timeout

Maximum time in milliseconds to wait for an I/O event.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC void * void * rWaitForIO (RWait *wp, int mask, Ticks deadline)

Wait for an IO event on a wait object.

Description:: Wait for an IO event by yielding the current coroutine fiber until the IO event arrives. When the IO event occurs, the wait handler will be invoked on the fiber.

Parameters:

wp	RWait object.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until.

API Stability:: Evolving.

PUBLIC void void rWatch (cchar *name, RWatchProc proc, void *data)

Watch for a named event to happen.

Parameters:

name	Named event.
proc	Function to call.
data	Data argument to pass to the function.

API Stability:: Evolving.

PUBLIC void void rWatchOff (cchar *name, RWatchProc proc, void *data)

Stop watching for a named event to happen.

This will remove the watch for a previous rWatch call with exactly the same proc and data arguments

Parameters:

name	Named event.
proc	Function provided to a previous rWatch call.
data	Data argument supplied to a previous rWatch call.

API Stability:: Evolving.

RFile

R File Module.

See Also:

API Stability:: Internal.

Fields:

PUBLIC int int rBackupFile (cchar *path, int count)

Backup the given file.

Description:: This creates backup copies of the file using the form: filename-d.ext.

Parameters:

path	Filename to backup.
count	Number of backup copies to keep.

API Stability:: Evolving.

See Also:: RFile

PUBLIC cchar * cchar * rBasename (cchar *path)

Return the basename (filename) portion of a filename.

Parameters:

path	Filename to examine.

Returns:: A pointer to the basename portion of the supplied filename path. This call does not allocate a new string.

API Stability:: Evolving.

See Also:: RFile

PUBLIC ssize ssize rCopyFile (cchar *from, cchar *to, int mode)

Copy a file.

Description:: Copy a file to a destination path.

Parameters:

from	Source file name.
to	Destination file name.
mode	Posix file mode on created file.

Returns:: Number of bytes copied or negative error code.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rGetAppDir (void )

Get the directory containing the application executable.

Returns:: An allocated string containing the application directory. Caller must free.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rGetCwd (void )

Get the current application working directory.

Returns:: An allocated string containing the working directory. Caller must free.

API Stability:: Evolving.

See Also:: RFile

PUBLIC RList * RList * rGetFiles (cchar *base, cchar *pattern, int flags)

Create a list of files in a directory or subdirectories that match the given wildcard pattern.

This call returns a list of filenames

Description:: Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

If the pattern is absolute.

Parameters:

base	Base directory from which to interpret the pattern. If the patternDirectory to list.
pattern	Wild card patterns to match.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

Returns:: A list (RList) of filenames.

API Stability:: Evolving.

See Also:: RFile

PUBLIC RList * RList * rGetFilesEx (RList *results, cchar *base, cchar *pattern, int flags)

Get a list of files in a directory or subdirectories that match the given wildcard pattern.

This call adds the files to the supplied results list

Description:: Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

Parameters:

results	Instance of RList. See rAllocList
base	Base directory from which to interpret the pattern. If the patternDirectory to list.
pattern	Wild card patterns to match.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

Returns:: A list (RList) of filenames.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rGetTempFile (cchar *dir, cchar *prefix)

Get a temp filename.

Description:: Create a temp file name in the given directory with the specified prefix.

Parameters:

dir	Directory to contain the temporary file. If null, use system default temp directory (/tmp).
prefix	Optional filename prefix.

Returns:: An allocated string containing the file name. Caller must free.

API Stability:: Evolving.

See Also:: RFile

PUBLIC bool bool rIsFileAbs (cchar *path)

Determine if a file path is an absolute path.

Parameters:

path	Filename path to test.

Returns:: True if the path is an absolute path.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rJoinFile (cchar *base, cchar *other)

Join file paths.

Description:: Join a path to a base path. If the other path is absolute, it will be returned.

Parameters:

base	Directory filename to use as the base.
other	Other filename path to join to the base filename.

Returns:: Allocated string containing the resolved filename. Caller must free.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rJoinFileBuf (char *buf, ssize bufsize, cchar *base, cchar *other)

Join paths into a buffer.

Description:: Join a path to a base path. If path is absolute, it will be returned.

Parameters:

buf	Destination path buffer.
bufsize	Size of buf.
base	Directory filename to use as the base.
other	Other filename path to join to the base filename.

Returns:: Allocated string containing the resolved filename.

API Stability:: Evolving.

See Also:: RFile

PUBLIC bool bool rMatchFile (cchar *path, cchar *pattern)

Matach a file against a glob pattern.

Description:: This tests a filename against a file pattern. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories,and a trailing "/" matches directories only.

If the pattern is absolute.

Parameters:

path	Filename to test.
pattern	Wild card patterns to match.

Returns:: True if the path matches the pattern.

API Stability:: Evolving.

See Also:: RFile

PUBLIC char * char * rReadFile (cchar *path, ssize *lenp)

Read data from a file.

Description:: Reads data from a file.

Parameters:

path	Filename to read.
lenp	Pointer to receive the length of the file read.

Returns:: The contents of the file in an allocated string.

API Stability:: Evolving.

See Also:: RFile

PUBLIC int int rWalkDir (cchar *dir, cchar *pattern, RWalkDirProc callback, void *arg, int flags)

Walk a directory tree and invoke a callback for each path that matches a given pattern.

Description:: The pattern may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

Parameters:

dir	Base directory from which to interpret the pattern.
pattern	Wild card patterns to match.
callback	Callback function of the signature RWalkDirProc
arg	Argument to callback function.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

API Stability:: Evolving.

See Also:: RFile

PUBLIC ssize ssize rWriteFile (cchar *path, cchar *buf, ssize len, int mode)

Write data to a file.

Description:: Write data from a file. The file will be created if required.

Parameters:

path	Filename to write.
buf	Buffer of data to write to the file.
len	Length of the buffer.
mode	Create file mode.

Returns:: The length of bytes written to the file. Should equal len.

API Stability:: Evolving.

See Also:: RFile

RHash

Hash table structure.

Description:: The hash structure supports growable hash tables collision resistant hashes.

See Also:: RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

API Stability:: Evolving.

Fields:

int *	buckets	Hash collision bucket table.
uint	flags	Hash control flags.
RHashProc	fn	Hash function.
int	free	Free list of names.
uint	length	Number of names in the hash.
struct RName *	names	Hash items.
uint	numBuckets	Number of buckets in the first-level hash.
uint	size	Size of allocated names.

PUBLIC RName * RName * rAddFmtName (RHash *hash, cchar *name, int flags, cchar *fmt, ...)

Add a name and formatted string value into the hash table.

Description:: Associate an arbitrary value with a string name and inser into the hash table.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
flags	Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used.
fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Added RName reference.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RName * RName * rAddIntName (RHash *hash, cchar *name, int64 value)

Add a name and integer value.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
value	A 64 bit integer value.

Returns:: Added RName reference.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RName * RName * rAddName (RHash *table, cchar *name, void *ptr, int flags)

Add a name and value into the hash table.

Description:: Associate an arbitrary value with a string name and inser into the hash table.

Parameters:

table	Hash table returned via rAllocHash.
name	String name to associate with the data.
ptr	Arbitrary pointer to associate with the name in the table.
flags	Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used.

Returns:: Added RName reference.

API Stability:: Evolving.

See Also:: RHash, RName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RName * RName * rAddNameSubstring (RHash *hash, cchar *name, ssize nameSize, char *value, ssize valueSize)

Add a name and value substring into the hash table.

Description:: Associate an arbitrary value with a string name and inser into the hash table. The flags used are: R_DYNAMIC_NAME | R_DYNAMIC_VALUE.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
nameSize	Size of the name string.
value	Value string to store.
valueSize	Length of string value.

Returns:: Added RName reference.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RHash * RHash * rAllocHash (int size, int flags)

Create a hash table.

Description:: Creates a hash table that can store arbitrary objects associated with string names.

Parameters:

size

Estimated number of names in the hash table. Set to 0 or -1 to get a default (small) hash table.

flags

Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. Set to R_HASH_CASELESS for case insensitive matching for names. The default flags is: R_STATIC_NAME | R_STATIC_VALUE.

Returns:: Returns a pointer to the allocated hash table.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RHash * RHash * rCloneHash (RHash *master)

Copy a hash table.

Parameters:

master

Original hash table.

Returns:: Returns a pointer to the new allocated hash table.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC void void rFreeHash (RHash *hash)

Free a hash table.

Parameters:

hash	Hash table to free.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC int int rGetHashLength (RHash *hash)

Return the count of symbols in a symbol entry.

Description:: Returns the number of symbols currently existing in a symbol table.

Parameters:

hash	Symbol table returned via rAllocHash.

Returns:: Integer count of the number of entries.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC RName * RName * rGetNextName (RHash *hash, RName *next)

Return the next symbol in a symbol entry.

Description:: Continues walking the contents of a symbol table by returning the next entry in the symbol table. A previous call to rGetFirstSymbol or rGetNextSymbol is required to supply the value of the last argument.

Parameters:

hash	Hash table hash returned via rAllocHash.
next	Index of next name.

Returns:: Pointer to the first entry in the symbol table.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC char * char * rHashToString (RHash *hash, cchar *join)

Convert a hash of strings to a single string.

Parameters:

hash	Hash pointer returned from rCreateHash.
join	String to use as the element join string.

Returns:: String consisting of the joined hash values.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName

PUBLIC void * void * rLookupName (RHash *hash, cchar *name)

Lookup a symbol in the hash table.

Description:: Lookup a name and return the value associated with that name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:: Value associated with the name when the entry was insered via rInserSymbol.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupNameEntry, rRemoveName

PUBLIC RName * RName * rLookupNameEntry (RHash *hash, cchar *name)

Lookup a symbol in the hash table and return the hash entry.

Description:: Lookup a name and return the hash table descriptor associated with that name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:: RName for the entry.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rRemoveName

PUBLIC int int rRemoveName (RHash *hash, cchar *name)

Remove a symbol entry from the hash table.

Description:: Removes a symbol entry from the symbol table. The entry is looked up via the supplied name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:: Returns zero if successful, otherwise a negative RT error code is returned.

API Stability:: Evolving.

See Also:: RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry

RList

List data structure.

Description:: The RList is a dynamic, growable list suitable for storing simple primitive data types or pointers to arbitrary objects.

See Also:: RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

API Stability:: Internal.

Fields:

uint	capacity	Current list capacity.
uint	flags	Items should be freed when list is freed.
void **	items	List item data.
uint	length	Current length of the list contents.

PUBLIC int int rAddItem (RList *list, cvoid *item)

Add an item to a list.

Description:: Add the specified item to the list. The list must have been previously created via rAllocList. The list will grow as required to store the item.

Parameters:

list	List pointer returned from rAllocList
item	Pointer to item to store.

Returns:: Returns a positive list index for the insered item. If the item cannot be insered due to a memory allocation failure, -1 is returned.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rAddNullItem (RList *list)

Add a null item to the list.

Description:: Add a null item to the list. This item does not count in the length returned by rGetListLength and will not be visible when iterating using rGetNextItem

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC RList * RList * rAllocList (int size, int flags)

Allocate a list.

Description:: Creates an empty list. RList's can store generic pointers. They automatically grow as required when items are added to the list.

Parameters:

size	Initial capacity of the list. Set to < 0 to get a growable list with a default initial size. Set to 0 to to create the list but without any initial list storage. Then call rSetListLimits to define the initial list size.
flags	Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. Default is R_STATIC_VALUE.

Returns:: Returns a pointer to the list.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void void rClearList (RList *list)

Clears the list of all items.

Description:: Resets the list length to zero and clears all items.

Parameters:

list	List pointer returned from rAllocList.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void void rFreeList (RList *list)

Free a list.

Parameters:

list	List pointer returned from rAllocList

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void * void * rGetItem (RList *list, int index)

Get an list item.

Description:: Get an list item specified by its index.

Parameters:

list	List pointer returned from rAllocList.
index	Item index into the list. Indexes have a range from zero to the lenghth of the list - 1.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rGetListLength (RList *list)

Get the number of items in the list.

Description:: Returns the number of items in the list. This will always be less than or equal to the list capacity.

Parameters:

list	List pointer returned from rAllocList.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void * void * rGetNextItem (RList *list, int *lastIndex)

Get the next item in the list.

Description:: Returns the value of the next item in the list.

Parameters:

list	List pointer returned from rAllocList.
lastIndex	Pointer to an integer that will hold the last index retrieved.

Returns:: Next item in list or null for an empty list or after the last item.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rInsertItemAt (RList *list, int index, cvoid *item)

Inser an item into a list at a specific position.

Description:: Insert the item into the list before the specified position. The list will grow as required to store the item.

Parameters:

list	List pointer returned from rAllocList
index	Location at which to store the item. The previous item at this index is moved to make room.
item	Pointer to item to store.

Returns:: The position index (positive integer) if successful. If the item cannot be insered due to a memory allocation failure, -1 is returned.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC char * char * rListToString (RList *list, cchar *join)

Convert a list of strings to a single string.

This uses the specified join string between the elements

Parameters:

list	List pointer returned from rAllocList.
join	String to use as the element join string. May be null.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rLookupItem (RList *list, cvoid *item)

Find an item and return its index.

Description:: Search for an item in the list and return its index.

Parameters:

list	List pointer returned from rAllocList.
item	Pointer to value stored in the list.

Returns:: Positive list index if found, otherwise a negative RT error code.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rLookupStringItem (RList *list, cchar *str)

Find a string item and return its index.

Description:: Search for the first matching string in the list and return its index.

Parameters:

list	List pointer returned from rAllocList.
str	Pointer to string to look for.

Returns:: Positive list index if found, otherwise a negative RT error code.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void * void * rPopItem (RList *list)

Pop an item.

Description:: Treat the list as a stack and pop the last pushed item.

Parameters:

list	List pointer returned from rAllocList.

Returns:: The last pushed item. If the list is empty, returns NULL.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC void void rPushItem (RList *list, void *item)

Push an item onto the list.

Description:: Treat the list as a stack and push the last pushed item.

Parameters:

list	List pointer returned from rAllocList.
item	Item to push onto the list.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rRemoveItem (RList *list, cvoid *item)

Remove an item from the list.

Description:: Search for a specified item and then remove it from the list.

Parameters:

list	List pointer returned from rAllocList.
item	Item pointer to remove.

Returns:: The positive index of the removed item, otherwise a negative RT error code.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rRemoveItemAt (RList *list, int index)

Remove an item from the list.

Description:: Removes the element specified by index, from the list. The list index is provided by rInsertItem.

Returns:: The positive index of the removed item, otherwise a negative RT error code.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveStringItem, rSetItem, rSortList

PUBLIC int int rRemoveStringItem (RList *list, cchar *str)

Remove a string item from the list.

Description:: Search for the first matching string and then remove it from the list.

Parameters:

list	List pointer returned from rAllocList.
str	String value to remove.

Returns:: The positive index of the removed item, otherwise a negative RT error code.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rSetItem, rSortList

PUBLIC void * void * rSetItem (RList *list, int index, cvoid *item)

Set a list item.

Description:: Update the list item stored at the specified index.

Parameters:

list	List pointer returned from rAllocList.
index	Location to update.
item	Pointer to item to store.

Returns:: The old item previously at that location index.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSortList

PUBLIC void * void * rSort (void *base, ssize num, ssize width, RSortProc compare, void *ctx)

Quicksort.

Description:: This is a quicksor with a context argument.

Parameters:

base	Base of array to sor.
num	Number of array elements.
width	Width of array elements.
compare	Comparison function.
ctx	Context argument to provide to comparison function.

Returns:: The base array for chaining.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

PUBLIC RList * RList * rSortList (RList *list, RSortProc compare, void *ctx)

Sor a list.

Description:: Sor a list using the sor ordering dictated by the supplied compare function.

Parameters:

list	List pointer returned from rAllocList.
compare	Comparison function. If null, then a default string comparison is used.
ctx	Context to provide to comparison function.

Returns:: The sorted list.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem

RLog

Log Services.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

API Stability:: Internal.

Fields:

PUBLIC void void assert (bool cond)

Asser that a condition is true.

Parameters:

cond	Boolean result of a conditional test.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rAssert (cchar *loc, cchar *msg)

Output an assert failed message.

Description:: This will emit an assert failed message to the standard error output. It may bypass the logging system.

Parameters:

loc	Source code location string. Use R_LOC to define a file name and line number string suitable for this parameter.
msg	Simple string message to output.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rBackupLog (void )

Backup a log.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC int int rDaemonize (void )

For the current process and run as a daemon.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rDebug (cchar *source, cchar *fmt, ...)

Emit a debug message to the log.

Parameters:

source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
...	Variable arg list from va_list.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rDefaultLogHandler (cchar *type, cchar *source, cchar *msg)

The default log handler.

Parameters:

type	Log message type.
source	Source of the message.
msg	Log message.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC bool bool rEmitLog (cchar *type, cchar *source)

Test if a log message should be emitted.

Description:: This call enables routines to test if messages should be logd for a given type/source pair.

Parameters:

type	Log message type string. If null, check "all".
source	Log message source. If null, chek "all".

Returns:: True if the message should be logd.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rError (cchar *source, cchar *fmt, ...)

Emit an error message to the log.

Parameters:

source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
...	Variable arg list from va_list.

API Stability:: Evolving.

See Also:: RLogHandler, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC RBuf * RBuf * rFormatLog (RBuf *buf, cchar *type, cchar *source, cchar *msg)

Format a log message into a buffer.

Description:: This formats the log message according to the current log format string.

Parameters:

buf	RBuf instance.
type	Log message type string.
source	Log message source.
msg	Message to log.

Returns:: The buffer suitable for chaining calls.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC int int rGetLogFile (void )

Get the log file file handle.

Description:: Returns the file handle used for logging.

Returns:: An file handle.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogHandler, rLog, rSetLog

PUBLIC RLogHandler RLogHandler rGetLogHandler (void )

Return the currently configured log handler defined via rSetLogHandler

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rLog, rSetLog

PUBLIC void void rInfo (cchar *source, cchar *fmt, ...)

Emit an informational message to the log.

Parameters:

source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
...	Variable arg list from va_list.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC int int rInitLog (void )

Initialize the logging subsystem.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC bool bool rIsLogSet (void )

Test if the log has been configured.

Returns:: True if the log has been defined.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rLog (cchar *source, cchar *fmt, ...)

Emit a log message to the log.

Parameters:

source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
...	Variable arg list from va_list.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rSetLog

PUBLIC void void rLog (char *type, cchar *source, cchar *fmt, ...)

Write a message to the error log file.

Description:: Send a message to the error log file. The purpose of the error log is to record essential configuration and error conditions. Per-request log typically is sent to a separate log.

By default, error log messages are sent to the standard output. Applications may redirect output by installing a log handler using rSetLogHandler.

Log messages should be a single text line to facilitate machine processing of log files.

Log typically is enabled in both debug and release builds and may be controlled via the build define ME_R_LOGGING which is typically set via the MakeMe setting "logging: true".

Parameters:

type	Message type.
source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

Remarks:: RLog is highly useful as a debugging aid.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rSetLog

PUBLIC void void rLogConfig (void )

Print the product configuration at the start of the log file.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rLogv (cchar *type, cchar *source, cchar *fmt, va_list args)

Write a message to the log file.

Description:: Send a message to the logging subsystem. The purpose of the log is to record essential configuration and error conditions. Per-request log typically is sent to a separate log.

By default, error messages are sent to the standard output. Applications may redirect output by installing a log handler using rSetLogHandler.

Log messages should be a single text line to facilitate machine processing of log files.

Log typically is enabled in both debug and release builds and may be controlled via the build define ME_R_LOGGING which is typically set via the MakeMe setting "logging: true".

Parameters:

type	Message type.
source	Module emitting the log message.
fmt	Printf style format string. Variable number of arguments to.
args	Variable arg list from va_list.

Remarks:: RLog is highly useful as a debugging aid.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rMetrics (cchar *message, cchar *namespace, cchar *dimensions, cchar *values, ...)

Emit an EMF metrics message suitable for AWS CloudWatch Metrics.

Parameters:

message	Prefix message string.
namespace	Metric namespace.
dimensions	Metric dimensions.
values	Format string of values.
...	Arguments for values format string.

API Stability:: Prototype.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rSetError (int error)

Set the error code.

Description:: Set errno or equivalent.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC int int rSetLog (cchar *spec, cchar *format, bool force)

Initialize logging.

Parameters:

spec	The spec is of the form: "destination:filter". The destination may be a filename, "stdout", "stderr" or "none". The log filter portion is of the form: "types:sources" and is passed to rSetLogFilter.
format	The log pattern to use to format the message. The format can use Letter tokens that are expanded at runtime. The tokens supported are: 'A' for the application name, 'D' for the local datetime, 'H' for the system hostname, 'P' for the process ID , 'S' for the message source, and 'T' for the log message type.
force	Set to true to overwrite a previous definition.

Returns:: Zero if successful, otherwise a negative R error code.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog

PUBLIC void void rSetLogFilter (cchar *types, cchar *sources, bool force)

Define a filter for log messages.

Parameters:

types	Comma separated list of types to emit. Can prefix a type with "!" to subtract from the list. Defaults to "error, info".
sources	Comma separated list of sources to emit. Can prefix a type with "!" to subtract from the list. Defaults to "all".
force	Set to true to overwrite a previous definition.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC RLogHandler RLogHandler rSetLogHandler (RLogHandler handler)

Define a log handler routine that will be invoked to process log messages.

Parameters:

handler

Log handler callback function.

Returns:: The previous log handler function.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rSetTimeouts (bool on)

Control timeouts.

Parameters:

on	Set to false to disable timeouts for debugging.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC void void rTermLog (void )

Terminate logging.

API Stability:: Evolving.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

PUBLIC int int rWritePid (void )

Write the current process pid to /var/run.

Returns:: Zero on success, otherwise a negative status code.

See Also:: RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

RString

R String Module.

Description:: The RT provides a suite of r ascii string manipulation routines to help prevent buffer overflows and other potential security traps.

See Also:: scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

API Stability:: Internal.

Fields:

PUBLIC char * char * scamel (cchar *str)

Create a camel case version of the string.

Description:: Copy a string into a newly allocated block and make the first character lower case.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int int scaselesscmp (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is a r replacement for strcasecmp. It can handle NULL args

Description:: Compare two strings ignoring case differences. This call operates similarly to strcmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:: Evolving.

See Also:: RString, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC bool bool scaselessmatch (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean

Description:: Compare two strings ignoring case differences.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * schr (cchar *str, int c)

Find a character in a string.

Description:: This is a r replacement for strchr. It can handle NULL args.

Parameters:

str	String to examine.
c	Character to search for.

Returns:: If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sclone (cchar *str)

Clone a string.

Description:: Copy a string into a newly allocated block.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int int scmp (cchar *s1, cchar *s2)

Compare strings.

Description:: Compare two strings. This is a r replacement for strcmp. It can handle null args.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * scontains (cchar *str, cchar *pattern)

Find a pattern in a string.

Description:: Locate the first occurrence of pattern in a string.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC ssize ssize scopy (char *dest, ssize destMax, cchar *src)

Copy a string.

Description:: R replacement for strcpy. Copy a string and ensure the destination buffer is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is always terminated with a null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.

Returns:: The number of characters in the target string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC cchar * cchar * sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:

str	String to examine.
suffix	Pattern to search for.

Returns:: Returns a pointer to the start of the pattern if found. Otherwise returns NULL.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sfmt (cchar *fmt, ...)

Format a string.

This is a secure verion of printf that can handle null args

Description:: Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sfmtbuf (char *buf, ssize maxSize, cchar *fmt, ...)

Format a string into a static buffer.

Description:: This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The buffer.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sfmtbufv (char *buf, ssize maxSize, cchar *fmt, va_list args)

Format a string into a statically allocated buffer.

Description:: This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: The buffer;.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sfmtv (cchar *fmt, va_list args)

Format a string.

This is a secure verion of printf that can handle null args

Description:: Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC uint uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC uint uint shashlower (cchar *str, ssize len)

Compute a caseless hash code for a string.

Description:: This computes a hash code for the string after convering it to lower case.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sitos (int64 value)

Convert an integer to a string.

Description:: This call convers the supplied 64 bit integer to a string using base 10.

Parameters:

value

Integer value to conver.

Returns:: An allocated string with the convered number.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sitosbuf (char *buf, ssize size, int64 value, int radix)

Convert an integer to a string buffer.

Description:: This call convers the supplied 64 bit integer into a string formatted into the supplied buffer according to the specified radix.

Parameters:

buf	Pointer to the buffer that will hold the string.
size	Size of the buffer.
value	Integer value to conver.
radix	The base radix to use when encoding the number.

Returns:: Returns a reference to the string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sitosradix (int64 value, int radix)

Convert an integer to a string.

Description:: This call convers the supplied 64 bit integer to a string according to the specified radix.

Parameters:

value	Integer value to conver.
radix	The base radix to use when encoding the number.

Returns:: An allocated string with the convered number.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sjoin (cchar *str, ...)

Catenate strings.

Description:: This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.

Parameters:

str	First string to catentate.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:: Returns an allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC cchar * cchar * sjoinArgs (int argc, cchar **argv, cchar *sep)

Join an array of strings.

Parameters:

argc	number of strings to join.
argv	Array of strings.
sep	Separator string to use. If NULL, then no separator is used.

Returns:: A single joined string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sjoinfmt (cchar *str, cchar *fmt, ...)

Join a formatted string to an existing string.

Description:: This uses the format and args to create a string that is joined to the first string.

Parameters:

str	First string to catentate.
fmt	First string to catentate.
...	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sjoinv (cchar *str, va_list args)

Catenate strings.

Description:: This catenates strings together.

Parameters:

str	First string to catentate.
args	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC ssize ssize slen (cchar *str)

Return the length of a string.

Description:: R replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum. It will return zero for NULL args.

Parameters:

str	String to measure.

Returns:: The length of the string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * slower (char *str)

Convert a string to lower case.

Description:: Convert a string to its lower case equivalent.

Parameters:

str	String to conver.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC bool bool smatch (cchar *s1, cchar *s2)

Compare strings.

Description:: Compare two strings. This is similar to scmp but it returns a boolean.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int int sncaselesscmp (cchar *s1, cchar *s2, ssize len)

Compare strings ignoring case.

Description:: Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sncaselesscontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit using a caseless comparison.

Description:: Locate the first occurrence of pattern in a string, but do not search more than the given character limit. Use a caseless comparison.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * snclone (cchar *str, ssize len)

Clone a substring.

Description:: Copy a substring into a newly allocated block.

Parameters:

str	Pointer to the block to duplicate.
len	Number of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int int sncmp (cchar *s1, cchar *s2, ssize len)

Compare strings.

Description:: Compare two strings for a given string length. This call operates similarly to strncmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sncontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit.

Description:: Locate the first occurrence of pattern in a string, but do not search more than the given character limit.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC ssize ssize sncopy (char *dest, ssize destMax, cchar *src, ssize len)

Copy characters from a string.

Description:: R replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.
len	Maximum count of characters to copy.

Returns:: Returns a reference to the destination if successful or NULL if the string won't fit.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * spbrk (cchar *str, cchar *set)

Locate the a character from a set in a string.

Description:: This locates in the string the first occurence of any character from a given set of characters.

Parameters:

str	String to examine.
set	Set of characters to scan for.

Returns:: Returns a reference to the first character from the given set. Returns NULL if none found.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * sptok (char *str, cchar *pattern, char **last)

Tokenize a string.

Description:: Split a string into tokens using a string pattern as delimiters.

Parameters:

str	String to tokenize.
pattern	String pattern to use for token delimiters.
last	Last token pointer.

Returns:: Returns a pointer to the next token.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * srchr (cchar *str, int c)

Find a character in a string by searching backwards.

Description:: This locates in the string the last occurence of a character.

Parameters:

str	String to examine.
c	Character to scan for.

Returns:: Returns a reference in the string to the requested character. Returns NULL if none found.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * ssplit (char *str, cchar *delim, char **last)

Split a string at a delimiter.

Description:: Split a string and return pars. The string is modified. This routiner never returns null. If there are leading delimiters, the empty string will be returned and *last will be set to the portion after the delimiters. If str is null, a managed reference to the empty string will be returned. If there are no characters after the delimiter, then *last will be set to the empty string.

Parameters:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Reference to the portion after the delimiters. Will return an empty string if is not trailing portion.

Returns:: Returns a pointer to the first par before the delimiters. If the string begins with delimiters, the empty string will be returned.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC ssize ssize sspn (cchar *str, cchar *set)

Find the end of a spanning prefix.

Description:: This scans the given string for characters from the set and returns an index to the first character not in the set.

Parameters:

str	String to examine.
set	Set of characters to span.

Returns:: Returns an index to the first character after the spanning set. If not found, returns the index of the first null.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC bool bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:

str	String to examine.
prefix	Pattern to search for.

Returns:: Returns true if the pattern was found. Otherwise returns zero.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * ssub (cchar *str, ssize offset, ssize length)

Create a substring.

Parameters:

str	String to examine.
offset	Staring offset within str for the beginning of the substring.
length	Length of the substring in characters.

Returns:: Returns a newly allocated substring.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, stemplate, stitle, stok, strim, supper

PUBLIC char * char * stemplate (cchar *str, void *tokens)

Replace template tokens in a string with values from a lookup table.

Tokens are ${variable} references

Parameters:

str	String to expand.
tokens	Hash table of token values to use.

Returns:: An expanded string. May return the original string if no "$" references are present.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stitle, stok, strim, supper

PUBLIC char * char * stitle (cchar *str)

Create a Title Case version of the string.

Description:: Copy a string into a newly allocated block and make the first character upper case.

Parameters:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stok, strim, supper

PUBLIC double double stof (cchar *str)

Convert a string to a double.

Description:: This call convers the supplied string to a double.

Parameters:

str	Pointer to the string to parse.

Returns:: The double equivalent value of the string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int64 int64 stoi (cchar *str)

Convert a string to an integer.

Description:: This call convers the supplied string to an integer using base 10.

Parameters:

str	Pointer to the string to parse.

Returns:: The integer equivalent value of the string.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC int64 int64 stoiradix (cchar *str, int radix, int *err)

Convert a string to an integer.

Description:: This call convers the supplied string to an integer using the specified radix (base).

Parameters:

str	Pointer to the string to parse.
radix	Base to use when parsing the string.
err	Return error code. Set to 0 if successful.

Returns:: The integer equivalent value of the string.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * stok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:: Split a string into tokens using a character set as delimiters.

Parameters:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Last token pointer.

Returns:: Returns a pointer to the next token inside the original string. Caller must not free the result.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, strim, supper

PUBLIC struct RList * struct RList * stolist (cchar *src)

String to list.

This parses the string of space separated arguments. Single and double quotes are supported

Parameters:

src	Source string to parse.

Returns:: List of arguments.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

PUBLIC char * char * strim (char *str, cchar *set, int where)

Trim a string.

Description:: Trim leading and trailing characters off a string. The original string is not modified and the return value is a newly allocated string.

Parameters:

str	String to trim.
set	String of characters to remove.
where	Flags to indicate trim from the start, end or both. Use R_TRIM_START, R_TRIM_END, R_TRIM_BOTH.

Returns:: Returns a newly allocated trimmed string. May not equal str.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, supper

PUBLIC char * char * supper (char *str)

Convert a string to upper case.

Description:: Convert a string to its upper case equivalent.

Parameters:

str	String to conver.

Returns:: Returns a pointer to the convered string. Will always equal str.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim

PUBLIC void void szero (char *str)

Erase the contents of a string.

Parameters:

str	String to erase.

API Stability:: Evolving.

See Also:: RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

RWait

Wait object.

Description:: The RWait service provides a flexible IO waiting mechansim.

API Stability:: Evolving.

Fields:

cvoid *	arg	Argument to pass to the handler.
Ticks	deadline	System deadline time to wait until.
int	fd	File descriptor to wait upon.
RFiber *	fiber	Current fiber for rWaitForIO.
RWaitProc	handler	Handler function to invoke as the entrypoint in the fiber coroute.
int	mask	Current event mask.

PUBLIC RWait * RWait * rAllocWait (int fd)

Allocate a wait object for a file descriptor.

Returns:: A RWait object.

API Stability:: Evolving.

PUBLIC void void rFreeWait (RWait *wp)

Free a wait object.

API Stability:: Evolving.

PUBLIC int int rInitWait (void )

Initialize the I/O wait subsystem.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC void void rSetWaitHandler (RWait *wp, RWaitProc handler, cvoid *arg, int64 mask)

Define a wait handler function on a wait object.

Description:: This will run the designated handler on a coroutine fiber in response to matching I/O events.

Parameters:

wp	RWait object.
handler	Function handler to invoke as the entrypoint in the new coroutine fiber.
arg	Parameter argument to pass to the handler.
mask	Set to R_READABLE or R_WRITABLE or both.

API Stability:: Evolving.

PUBLIC void void rTermWait (void )

Terminate the I/O wait subsystem.

API Stability:: Evolving.

RbTree

Red/Black Tree.

Description:: Self-balancing binary search tree.

API Stability:: Evolving.

Fields:

PUBLIC RbTree * RbTree * rbAlloc (int flags, RbFree free, RbCompare compare)

Allocate a red/black tree.

Parameters:

flags	Set to RB_DUP if you wish to store duplicate nodes.
free	Callback to free a node's item data.
compare	Callback to compare two nodes.

Returns:: An RbTree instance.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbFirst (RbTree *rbt)

Return the lexically first node.

Parameters:

rbt	RbTree allocated via rbAlloc.

Returns:: The first node.

API Stability:: Evolving.

PUBLIC void void rbFree (RbTree *rbt)

Free a red/black tree.

Parameters:

rbt	RbTree to free. Allocated via rbAlloc.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbInsert (RbTree *rbt, void *data)

Insert a new data item in the tree.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data to store in the tree. The data should contain the lookup key value for the data. The comparison callback will be passed the data and it should be able to extract the key from the data.

Returns:: The inserted node.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbLookup (RbTree *rbt, void *data, void *ctx)

Lookup a data item.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:: The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbLookupFirst (RbTree *rbt, void *data, void *ctx)

Return the lexically first matching node.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:: The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbLookupNext (RbTree *rbt, RbNode *node, void *data, void *ctx)

Return the next matching node after the given node.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Starting node for the search.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:: The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:: Evolving.

PUBLIC RbNode * RbNode * rbNext (RbTree *rbt, RbNode *node)

Return the next node in sequence.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Starting node.

Returns:: The next node in the tree.

API Stability:: Evolving.

PUBLIC void * void * rbRemove (RbTree *rbt, RbNode *node, int keep)

Remove a data item from the tree.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Node to remove. The node is identified by calling rbLookup.
keep	If true, the data item will not be freed. Otherwise the free callback will be invoked on the data item.

API Stability:: Evolving.

Functions

PUBLIC void * void * rAlloc (size_t size)

Allocate a block of memory.

Description:: This is the lowest level of memory allocation routine. Memory is freed via rFree.

Parameters:

size	Size of the memory block to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler will be invoked.

Remarks:: Do not mix calls to rAlloc and malloc.

API Stability:: Evolving.

PUBLIC REvent REvent rAllocEvent (RFiber *fiber, REventProc proc, void *data, Ticks delay)

Allocate and schedule a new event to be run from the event loop.

Description:: Allocate an event to run a callback via the event loop. The safe runtime (R) is not thread-safe in general. A few APIs are thread-safe to enable data interchange between R and foreign threads.

This API is thread-safe and may be called by foreign threads. This routine is the only safe way to invoke R services from a foreign-thread.

Parameters:

fiber	Fiber object.
proc	Function to invoke when the event is run.
data	Data to associate with the event and stored in event->data.
delay	Time in milliseconds used by continuous events between firing of the event.

Returns:: The event object. If called from a foreign thread, note that the event may have already run n return.

API Stability:: Internal.

PUBLIC void void rAllocException (int cause, size_t size)

Signal a memory allocation exception.

Description:: R uses a global memory allocaction error handler. If doing direct malloc() allocations that fail, call this routine to signal the memory failure and run the allocation handler.

Parameters:

cause	Set to R_MEM_WARNING, R_MEM_LIMIT, R_MEM_FAIL or R_MEM_TO_BIG.
size	Size in bytes of the failing allocation.

API Stability:: Evolving.

PUBLIC RFiber * RFiber * rAllocFiber (RFiberProc fn, cvoid *data)

Allocate a fiber coroutine object.

Description:: This allocates a new fiber coroutine. Use rStartFiber to launch.

Parameters:

fn	Fiber entry point.
data	Entry point argument.

Returns:: A fiber object.

API Stability:: Internal.

PUBLIC RLock * RLock * rAllocLock (void )

Allocate a lock object.

Description:: This call creates a lock object that can be used in rLock rTryLock and rUnlock calls.

API Stability:: Evolving.

PUBLIC RSocket * RSocket * rAllocSocket (void )

Allocate a socket object.

Returns:: A socket object instance.

API Stability:: Evolving.

PUBLIC void * void * rAllocType (RType type)

Allocate an object of a given type.

Description:: Allocates a zeroed block of memory large enough to hold an instance of the specified type.

Parameters:

type	RType of the object to allocate.

Returns:: Returns a pointer to the allocated block. If memory is not available the memory allocation handler will be invoked.

API Stability:: Evolving.

PUBLIC void void rBreakpoint (void )

Trigger a breakpoint.

Description:: This routine is invoked for asserion errors from rAssert and errors from rError. It is useful in debuggers as breakpoint location for detecting errors.

API Stability:: Evolving.

PUBLIC void void rCloseSocket (RSocket *sp)

Close a socket.

Description:: Close a socket.

Parameters:

sp	Socket object returned from rAllocSocket.

API Stability:: Evolving.

PUBLIC int int rConnectSocket (RSocket *sp, cchar *host, int port, Ticks deadline)

Connect a client socket.

Description:: Open a client connection. May be called from a fiber or from main.

: If using TLS, this must only be called from a fiber.

Parameters:

sp	Socket object returned via rAllocSocket.
host	Host or IP address to connect to.
port	TCP/IP port number to connect to.
deadline	Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC int int rCreateThread (cchar *name, void *proc, void *data)

Create an O/S thread.

Parameters:

name	Descriptive name for the thread.
proc	Thread main function to invoke.
data	Argument to proc.

API Stability:: Evolving.

PUBLIC char * char * rFormatLocalTime (cchar *format, Time time)

Convert a time value to local time and format as a string.

Description:: R replacement for ctime.

Parameters:

format	Time format string. See rFormatUniversalTime for time formats.
time	Time to format. Use rGetTime to retrieve the current time.

Returns:: The formatting time string. Caller msut free.

API Stability:: Evolving.

PUBLIC char * char * rFormatUniversalTime (cchar *format, Time time)

Convert a time value to universal time and format as a string.

Description:: Format a time string. This uses strftime if available and so the supported formats vary from platform to platform. Strftime should supports some of these these formats described below.

Parameters:

format

Time format string
A ... full weekday name (Monday)
a ... abbreviated weekday name (Mon)
B ... full month name (January)
b ... abbreviated month name (Jan)
C ... century. Year / 100. (0-N)
c ... standard date and time representation
D ... date (m/d/y)
d ... day-of-month (01-31)
e ... day-of-month with a leading space if only one digit ( 1-31)
F ... same as Y-m-d
H ... hour (24 hour clock) (00-23)
h ... same as b
I ... hour (12 hour clock) (01-12)
j ... day-of-year (001-366)
k ... hour (24 hour clock) (0-23)
l ... the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
M ... minute (00-59)
m ... month (01-12)
n ... a newline
P ... lower case am / pm
p ... AM / PM
R ... same as H:M
r ... same as H:M:S p
S ... second (00-59)
s ... seconds since epoch
T ... time (H:M:S)
t ... a tab.
U ... week-of-year, first day sunday (00-53)
u ... the weekday (Monday as the first day of the week) as a decimal number (1-7).
v ... is equivalent to `e-b-Y'.
W ... week-of-year, first day monday (00-53)
w ... weekday (0-6, sunday is 0)
X ... standard time representation
x ... standard date representation
Y ... year with century
y ... year without century (00-99)
Z ... timezone name
z ... offset from UTC (-hhmm or +hhmm)
%+ ... national representation of the date and time (the format is similar to that produced by date(1)).
%% ... percent sign

Some platforms may also support the following format extensions:
E* ... POSIX locale extensions. Where "*" is one of the characters: c, C, x, X, y, Y.
G ... a year as a decimal number with century. This year is the one that contains the greater par of the week (Monday as the first day of the week).
g ... the same year as in `G', but as a decimal number without century (00-99).
O* ... POSIX locale extensions. Where "*" is one of the characters: d, e, H, I, m, M, S, u, U, V, w, W, y. Additionly OB implemented to represent alternative months names (used standalone, without day mentioned).
V ... the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.

Useful formats:
RFC822: "%a, %d %b %Y %H:%M:%S %Z "Fri, 07 Jan 2003 12:12:21 PDT" \n "T F "12:12:21 2007-01-03"
"%v "07-Jul-2003" \n RFC3399: "FTTZ" "1985-04-12T23:20:50.52Z" which is April 12 1985, 23:20.50 and 52 msec

time

Time to format. Use rGetTime to retrieve the current time.

Returns:: The formatting time string. Caller must free.

API Stability:: Evolving.

PUBLIC void void rFree (void *ptr)

Free a block of memory allocated via rAlloc.

Description:: This releases a block of memory allocated via rAllocMem.

Parameters:

ptr	Pointer to the block. If ptr is null, the call is skipped.

Remarks:: The rFree routine is a macro over rFreeMem. Do not mix calls to rFreeMem and free.

API Stability:: Evolving.

PUBLIC void void rFreeFiber (RFiber *fiber)

Free a fiber coroutine.

Description:: The fiber must have already completed before invoking this routine. This routine is typically only called internally by the fiber module.

Parameters:

fiber

Fiber to free.

API Stability:: Internal.

PUBLIC void void rFreeLock (RLock *mutex)

Free a dynamically allocated lock object.

Parameters:

mutex

Reference to an RLock structure to initialize.

API Stability:: Evolving.

PUBLIC void void rFreeSocket (RSocket *sp)

Free a socket object.

API Stability:: Evolving.

PUBLIC cchar * cchar * rGetAppName (void )

Get the application name defined via rSetAppName.

Returns:: The one-word lower case application name defined via rSetAppName.

API Stability:: Evolving.

PUBLIC RThread RThread rGetCurrentThread (void )

Get the current Thread.

Returns:: The currently executing thread.

API Stability:: Evolving.

PUBLIC char * char * rGetDate (cchar *format)

Get a string representation of the current date/time.

Description:: Get the current date/time as a string according to the given format.

Parameters:

format

Date formatting string. See strftime for acceptable date format specifiers. If null, then this routine uses the R_DEFAULT_DATE format.

Returns:: A date string. Caller must free.

API Stability:: Evolving.

PUBLIC Ticks Ticks rGetElapsedTicks (Ticks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with rGetTicks()

Parameters:

mark	Staring time stamp.

Returns:: The time elapsed since the mark was taken.

API Stability:: Evolving.

PUBLIC cchar * cchar * rGetError (int error)

Return a string representation of an R error code.

Parameters:

error

An R error code. These codes are always negative for errors and zero for R_OK.

Returns:: A static string error representation.

API Stability:: Evolving.

PUBLIC RFiber * RFiber * rGetFiber (void )

Get the current fiber object.

Returns:: Fiber Fiber object.

API Stability:: Evolving.

PUBLIC void * void * rGetFiberStack (void )

Get the base address of the fiber stack.

Returns:: A pointer to the base of the fiber stack.

API Stability:: Evolving.

uint64 rGetHiResTicks (void )

Get the CPU tick count.

Description:: Get the current CPU tick count. This is a system dependant high resolution timer. On some systems, this returns time in nanosecond resolution.

Returns:: The CPU time in ticks. Will return the system time if CPU ticks are not available.

API Stability:: Internal.

PUBLIC char * char * rGetIsoDate (Time time)

Get an ISO Date string representation of the given date/time.

Description:: Get the date/time as an ISO string.

Parameters:

time	Given time to convert.

Returns:: A date string. Caller must free.

API Stability:: Evolving.

PUBLIC int int rGetOsError (void )

Return the native O/S error code.

Description:: Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.

Returns:: The O/S error code.

API Stability:: Evolving.

PUBLIC Ticks Ticks rGetRemainingTicks (Ticks mark, Ticks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:

mark	Staring time stamp.
timeout	Time in milliseconds.

Returns:: Time in milliseconds until the timeout elapses.

API Stability:: Evolving.

PUBLIC cchar * cchar * rGetServerName (void )

Get the application server name string.

Returns:: A string containing the application server name string.

API Stability:: Evolving.

PUBLIC int int rGetSocketAddr (RSocket *sp, char *ipbuf, int ipbufLen, int *port)

Get the locally bound socket IP address and port for the socket.

Description:: Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from rAllocSocket.
ipbuf	Buffer to receive the IP address.
ipbufLen	Size of the ipbuf.
port	Address of an integer to receive the port unumber.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC Socket Socket rGetSocketHandle (RSocket *sp)

Get the socket file descriptor.

Description:: Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: The Socket file descriptor used by the O/S for the socket.

API Stability:: Evolving.

PUBLIC int int rGetState (void )

Get the current R state.

Returns:: Returns R_RUNNING, R_STOPPING or R_STOPPED.

API Stability:: Evolving.

PUBLIC Ticks Ticks rGetTicks (void )

Get the system time.

Description:: Get the system time in milliseconds. This is a monotonically increasing time counter. It does not represent wall-clock time.

Returns:: The system time in milliseconds.

API Stability:: Evolving.

PUBLIC Time Time rGetTime (void )

Get the time.

Description:: Get the date/time in milliseconds since Jan 1 1970.

Returns:: The time in milliseconds since Jan 1 1970.

API Stability:: Evolving.

PUBLIC bool bool rGetTimeouts (void )

Return true if timeouts are enabled.

Returns:: True if timeouts are enabled.

API Stability:: Evolving.

PUBLIC int int rGetWaitFd (void )

Get the global wait descriptor.

Returns:: The wait file descriptor used by epoll and kqueue.

API Stability:: Evolving.

PUBLIC void void rGlobalLock (void )

Globally lock the application.

Description:: This call asserts the application global lock so that other threads calling rGlobalLock will block until the current thread calls rGlobalUnlock. WARNING: Use this API very sparingly.

API Stability:: Evolving.

PUBLIC void void rGlobalUnlock (void )

Unlock the global mutex.

Description:: This call unlocks the global mutex previously locked via rGlobalLock.

API Stability:: Evolving.

PUBLIC void void rGracefulStop (void )

Gracefully stop the app.

Description:: Queued events will be serviced.

API Stability:: Evolving.

PUBLIC int int rGrowList (RList *list, int size)

Grow the list to be at least the requested size in elements.

Parameters:

list	List pointer returned from rAllocList.
size	Required minimum size for the list.

API Stability:: Evolving.

PUBLIC char * char * rHashToJson (RHash *hash, int pretty)

Convert a hash into JSON.

Parameters:

hash	Hash table to use for the result.
pretty	Set to true to have a prettier JSON representation.

Returns:: A JSON string. Caller must free.

API Stability:: Evolving.

PUBLIC RBuf * RBuf * rHashToJsonBuf (RHash *hash, RBuf *buf, int pretty)

Convert a hash into JSON in the given buffer.

Parameters:

hash	Hash table to use for the result.
buf	RBuf instance to store the json text.
pretty	Set to true to have a prettier JSON representation.

Returns:: The given buffer.

API Stability:: Evolving.

PUBLIC int int rInit (RFiberProc fn, cvoid *arg, ssize stackSize)

Initialize the runtime.

Description:: This routine should be called at startup from main().

Parameters:

fn	Fiber function to start.
arg	Argument to the fiber function.
stackSize	Size of the fiber coroutine stacks.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC int int rInitFibers (ssize stackSize)

Initialize the fiber coroutine module.

Parameters:

stackSize

Default size of fiber stacks in bytes.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC RLock * RLock * rInitLock (RLock *mutex)

Initialize a statically allocated lock object.

Description:: This call initialized a lock object without allocation. The object can then be used used in rLock rTryLock and rUnlock calls.

Parameters:

mutex

Reference to an RLock structure to initialize.

Returns:: A reference to the supplied mutex. Returns null on errors.

API Stability:: Evolving.

PUBLIC int int rInitOs (void )

Create and initialze the O/S dependent subsystem.

Description:: Called internally by the RT. Should not be called by users.

API Stability:: Internal.

PUBLIC bool bool rIsMain (void )

Test if a fiber is the main fiber.

Returns:: True if the fiber is the main fiber.

API Stability:: Evolving.

PUBLIC bool bool rIsSocketClosed (RSocket *sp)

Test if the socket has been closed.

Description:: Determine if rCloseSocket has been called.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: True if the socket is at end-of-file.

API Stability:: Evolving.

PUBLIC bool bool rIsSocketConnected (RSocket *sp)

Determine if the socket has connected to a remote pper.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: True if the socket is connected.

API Stability:: Evolving.

PUBLIC bool bool rIsSocketEof (RSocket *sp)

Test if the other end of the socket has been closed.

Description:: Determine if the other end of the socket has been closed and the socket is at end-of-file.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: True if the socket is at end-of-file.

API Stability:: Evolving.

PUBLIC bool bool rIsSocketHandshaking (RSocket *sp)

Determine if the socket is partway through a TLS handshake.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: True if the socket is handshaking.

API Stability:: Evolving.

PUBLIC bool bool rIsSocketSecure (RSocket *sp)

Determine if the socket is secure.

Description:: Determine if the socket is using SSL to provide enhanced security.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:: True if the socket is using SSL, otherwise zero.

API Stability:: Evolving.

PUBLIC int int rListenSocket (RSocket *sp, cchar *host, int port, RSocketProc handler, void *arg)

Listen on a server socket for incoming connections.

Description:: Open a server socket and listen for client connections. If host is null, then this will listen on both IPv6 and IPv4.

Parameters:

sp	Socket object returned via rAllocSocket.
host	Host name or IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
port	TCP/IP port number to connect to.
handler	Function callback to invoke for incoming connections. The function is invoked on a new fiber coroutine.
arg	Argument to handler.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC void void rLock (RLock *lock)

Lock access.

Description:: This call asserts a lock on the given lock mutex so that other threads calling rLock will block until the current thread calls rUnlock.

Parameters:

lock

object.

API Stability:: Evolving.

PUBLIC void * void * rMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:: Copy a block of memory into a newly allocated block.

Parameters:

ptr	Pointer to the block to duplicate.
size	Size of the block to copy.

Returns:: Returns an allocated block.

API Stability:: Evolving.

PUBLIC Time Time rParseIsoDate (cchar *when)

Parse an ISO date string.

Returns:: The time in milliseconds since Jan 1, 1970.

API Stability:: Evolving.

PUBLIC ssize ssize rReadSocket (RSocket *sp, char *buf, ssize bufsize, Ticks deadline)

Read from a socket.

Description:: Read data from a socket. The read will return with whatever bytes are available. If none is available, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.

: Must be called from a fiber.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Pointer to a buffer to hold the read data.
bufsize	Size of the buffer.
deadline	Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline.

Returns:: A count of bytes actually read. Return a negative R error code on errors.

Returns:: Return -1 for EOF and errors. On success, return the number of bytes read. Use rIsSocketEof to distinguision between EOF and errors.

API Stability:: Evolving.

PUBLIC ssize ssize rReadSocketSync (RSocket *sp, char *buf, ssize bufsize)

Read from a socket.

Description:: Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block until there is some data available or the socket is disconnected. Use rSetSocketBlocking to change the socket blocking mode. It is preferable to use rReadSocket which can wait without blocking via fiber coroutines.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Pointer to a buffer to hold the read data.
bufsize	Size of the buffer.

Returns:: A count of bytes actually read. Return a negative R error code on errors.

Returns:: Return -1 for EOF and errors. On success, return the number of bytes read. Use rIsSocketEof to distinguision between EOF and errors.

API Stability:: Evolving.

PUBLIC void void rResetSocket (RSocket *sp)

Reset a socket.

Description:: Reset a socket by closing the underlying socket file descriptor. The Socket instance can be reused by rConnectSocket.

Parameters:

sp	Socket object returned from rAllocSocket.

API Stability:: Evolving.

PUBLIC void * void * rResumeFiber (RFiber *fiber, void *result)

Resume a fiber.

Description:: Resume a fiber. Generally only called from the main fiber. If called from a non-main fiber the target fiber is resumed via an event to the main fiber.

Parameters:

fiber	Fiber object.
result	Result to pass to the fiber and will be the value returned from rYieldFiber.

API Stability:: Evolving.

PUBLIC int int rSetAppName (cchar *name, cchar *title, cchar *version)

Set the application name, title and version.

Parameters:

name	One word, lower case name for the app.
title	Pascal case multi-word descriptive name.
version	Version of the app. Major-Minor-Patch. E.g. 1.2.3.

Returns:: Zero if successful. Otherwise a negative RT error code.

API Stability:: Evolving.

PUBLIC void void rSetDefaultSocketCa (cchar *ca)

Set the default CA root certificate bundle.

Parameters:

ca	File containing the root certificates.

API Stability:: Evolving.

PUBLIC void void rSetFiberStack (ssize size)

Set the default fiber stack size.

Parameters:

size	Size of fiber stack in bytes.

API Stability:: Internal.

PUBLIC void void rSetMemHandler (RMemProc handler)

Define a global memory exhaustion handler.

Description:: The memory handler will be invoked for memory allocation errors.

Parameters:

handler

Callback function invoked with the signature: void fn(int cause, size_t size).

API Stability:: Evolving.

PUBLIC void void rSetOsError (int error)

Set the O/S error code.

Description:: Set errno or equivalent.

API Stability:: Evolving.

PUBLIC void void rSetSocketBlocking (RSocket *sp, bool on)

Set a socket into blocking I/O mode.

from a socket

Description:: Sockets are opened in non-blocking mode by default.

Parameters:

sp	Socket object returned from rAllocSocket.
on	Set to true to enable blocking mode.

API Stability:: Evolving.

PUBLIC void void rSetSocketCerts (RSocket *sp, cchar *key, cchar *cert, cchar *ca, cchar *revoke)

Configure the socket TLS certificates.

Description:: This call is a wrapper over rSetTLSCerts.

Parameters:

sp	Socket object returned from rAllocSocket.
key	Private key for the certificate.
cert	Certificate to use for TLS.
ca	Certificate authority to use when verifying peer connections.
revoke	List of revoked certificates.

API Stability:: Evolving.

PUBLIC void void rSetSocketCiphers (RSocket *sp, cchar *ciphers)

Set the ciphers to use for communications.

Parameters:

sp	Socket object returned from rAllocSocket.
ciphers	String of suitable ciphers.

API Stability:: Evolving.

PUBLIC void void rSetSocketVerify (RSocket *sp, int verifyPeer, int verifyIssuer)

Set the socket TLS verification parameters.

Description:: This call is a wrapper over rSetTlsCerts.

Parameters:

sp	Socket object returned from rAllocSocket.
verifyPeer	Set to true to verify peer certificates.
verifyIssuer	Set to true to verify the issuer of the peer certificate.

API Stability:: Evolving.

PUBLIC void void rSetSocketWaitMask (RSocket *sp, int64 mask, Ticks deadline)

Update the wait mask for a socket.

Parameters:

sp	Socket object returned from rAllocSocket.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until.

API Stability:: Evolving.

PUBLIC void void rSetState (int state)

Set the R state.

Parameters:

state

Set to R_RUNNING, R_STOPPING or R_STOPPED.

API Stability:: Evolving.

PUBLIC void void rSleep (Ticks ticks)

Sleep a fiber for the requested number of milliseconds.

: Must be called from a fiber.

Description:: Pause a fiber for the requested duration and then resume via the main fiber. Other fibers continue to run.

Parameters:

ticks

Time period in milliseconds to sleep.

API Stability:: Evolving.

PUBLIC int int rSpawnFiber (RFiberProc fn, void *arg)

Spawn a fiber coroutine.

Description:: This allocates a new fiber and resumes it.

Parameters:

fn	Fiber entry point.
arg	Entry point argument.

Returns:: Zero if successful.

API Stability:: Evolving.

PUBLIC void * void * rSpawnThread (RThreadProc fn, void *arg)

Spawn an O/S thread.

Description:: This creates a new thread and runs the given function.

Parameters:

fn	Thread main function entry point.
arg	Argument provided to the thread.

Returns:: Value returned from fn().

API Stability:: Evolving.

PUBLIC void void rStartFiber (RFiber *fiber, void *data)

Start a fiber coroutine.

Description:: This creates an event so that the main fiber can start the fiber. This routine is typically only called internally by the fiber module.

Parameters:

fiber	The fiber object.
data	Value to pass to the fiber entry point.

API Stability:: Internal.

PUBLIC void void rStop (void )

Immediately stop the app.

Description:: Queued events will not be serviced.

API Stability:: Evolving.

PUBLIC void void rTermFibers (void )

Terminate the fiber coroutine module.

API Stability:: Evolving.

PUBLIC void void rTermLock (RLock *mutex)

Terminate a statically allocated lock object.

Parameters:

mutex

Reference to an RLock structure to initialize.

API Stability:: Evolving.

PUBLIC void void rTermOs (void )

Stop the O/S dependent subsystem.

API Stability:: Internal.

PUBLIC bool bool rTryLock (RLock *lock)

Attempt to lock access.

Description:: This call attempts to assert a lock on the given lock mutex so that other threads calling rLock or rTryLock will block until the current thread calls rUnlock.

Returns:: Returns zero if the successful in locking the mutex. Returns a negative error code if unsuccessful.

API Stability:: Evolving.

PUBLIC void void rUnlock (RLock *lock)

Unlock a mutex.

Description:: This call unlocks a mutex previously locked via rLock or rTryLock.

Parameters:

lock

object.

API Stability:: Evolving.

PUBLIC ssize ssize rWriteSocket (RSocket *sp, cvoid *buf, ssize bufsize, Ticks deadline)

Write to a socket.

Description:: Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. If no data can be written, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.

: Must be called from a fiber.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Reference to a block to write to the socket.
bufsize	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors.
deadline	System time in ticks to wait until.

Returns:: A count of bytes actually written. Return a negative error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and rGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:: Evolving.

PUBLIC ssize ssize rWriteSocketSync (RSocket *sp, cvoid *buf, ssize len)

Write to a socket.

Description:: Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. It is preferable to use rWriteSocket which can wait without blocking via fiber coroutines.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Reference to a block to write to the socket.
len	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors.

Returns:: A count of bytes actually written. Return a negative error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and rGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:: Evolving.

PUBLIC void * void * rYieldFiber (void *value)

Yield a fiber back to the main fiber.

Description:: Pause a fiber until resumed by the main fiber. the target fiber is resumed via an event to the main fiber. This routine is thread safe when invoked from a non-main thread.

Parameters:

value

Value to provide as a result to the main fiber that called rResumeFiber.

API Stability:: Evolving.

Typedefs

typedef libucontext_ucontext_t RFiberContext.

Fiber coroutine stack context.

API Stability:: Evolving.

typedef void(* RFiberProc) (void *data).

Fiber entry point function.

Parameters:

data	Custom function argument.

API Stability:: Evolving.

typedef uint(* RHashProc) (cvoid *name, ssize len).

Hashing function to use for the table.

Parameters:

name	Name to hash.
len	Length of the name to hash.

Returns:: An integer hash index.

API Stability:: Internal.

typedef void(* RMemProc) (int cause, size_t size).

Memory exhaustion callback procedure.

Parameters:

cause	The cause of the memory failure.
size	The size of the failing block allocation.

typedef void *(* RThreadProc) (void *data).

Thread entry point function.

Parameters:

data	Custom function argument.

Returns:: Value to pass back from rSpawnThread.

API Stability:: Evolving.

typedef long size_t.

Unsigned integral type.

Equivalent in size to void*

typedef int Socket.

Argument for sockets.

typedef unsigned long time_t.

Unsigned time type.

Time in seconds since Jan 1, 1970

typedef void(* REventProc) (void *data).

Callback function for events.

Parameters:

data	Opaque data argument.

API Stability:: Evolving.

typedef void(* RWatchProc) (cvoid *data, cvoid *arg).

Callback function for watched events.

Parameters:

data	Opaque data argument supplied via rWatchEvent.
arg	Watched event arg.

API Stability:: Evolving.

typedef int(* RWalkDirProc) (void *arg, cchar *path, int flags).

Callback function for rWalkDir

Parameters:

arg	Argument supplied to rWalkDir.
path	Current filename path to walk.
flags	Flags supplied to rWalkDir.

API Stability:: Evolving.

See Also:: RFile

typedef int(* RListCompareProc) (cvoid *arg1, cvoid *arg2).

List comparison procedure for soring.

Description:: Callback function signature used by rSortList

Parameters:

arg1	First list item to compare.
arg2	Second list item to compare.

Returns:: Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.

API Stability:: Evolving.

See Also:: RList, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

typedef int(* RSortProc) (cvoid *p1, cvoid *p2, void *ctx).

Quicksort callback function.

Description:: This is a quicksor callback with a context argument.

Parameters:

p1	Pointer to first element.
p2	Pointer to second element.
ctx	Context argument to provide to comparison function.

Returns:: -1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.

API Stability:: Evolving.

See Also:: RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList

typedef void(* RLogHandler) (cchar *type, cchar *source, cchar *msg).

Log handler callback type.

Description:: Callback prototype for the log handler. Used by rSetLogHandler to define a message logging handler to process log and error messages. See rLog for more details.

Parameters:

type	The message type: 'code', 'error', 'info', 'log'.
source	The message source.
msg	Log message.

API Stability:: Evolving.

See Also:: rError, rGetLogFile, rGetLogHandler, rLog, rSetLog

typedef void(* RWaitProc) (cvoid *data, int mask).

Callback function for IO wait events.

Parameters:

data	Opaque data argument.
mask	IO event selection mask.

API Stability:: Evolving.

typedef int(* RbCompare) (cvoid *n1, cvoid *n2, cvoid *ctx).

Callback to compare a data nodes.

Description:: The comparison function may perform a simple "strcmp" style comparison function or it may perform a modified comparison using the supplied context information. For example: a comparison could perform a "startsWith" style comparison. The context argument can control the type of comparison that is performed.

Parameters:

n1	Reference to first item.
n2	Reference to item to compare.
ctx	Context provided to rbLookup.

Returns:: Return -1 if n1 is lexically less than n2. Zero if equal and 1 if n1 is greater than n2.

API Stability:: Evolving.

typedef void(* RbFree) (void *data).

Callback to free a nodes associated data.

Parameters:

data	Reference to the associated data for a node.

API Stability:: Evolving.

RFiber

Fiber state.

API Stability:: Evolving.

Fields:

RLock

Multithreading lock control structure.

Description:: RLock is used for multithread locking in multithreaded applications.

Fields:

API Stability:: Evolving.

RName

Per item structure.

Fields:

uint	custom	Custom data bits.
uint	flags	Name was allocated.
char *	name	Hash name.
int	next	Next name in hash chain or next free if on free list.
void *	value	Pointer to data.