Slices

Data Structures
struct	FLSlice
	A simple reference to a block of memory. More...
struct	FLSliceResult
	A heap-allocated block of memory returned from an API call. More...

Macros
#define	kFLSliceNull   ((FLSlice){NULL, 0})
	A convenient constant denoting a null slice.
#define	FLSTR(STR)   ((FLSlice){("" STR), sizeof(("" STR))-1})
	Macro version of FLStr, for use in initializing compile-time constants.

Typedefs
typedef FLSlice	FLHeapSlice
	A heap-allocated, reference-counted slice.
typedef FLSlice	FLString
typedef FLSliceResult	FLStringResult

Functions
static FLPURE int	FLMemCmp (const void *FL_NULLABLE a, const void *FL_NULLABLE b, size_t size)
	Exactly like memcmp, but safely handles the case where a or b is NULL and size is 0 (by returning 0), instead of producing "undefined behavior" as per the C spec.
static void	FLMemCpy (void *FL_NULLABLE dst, const void *FL_NULLABLE src, size_t size)
	Exactly like memcmp, but safely handles the case where dst or src is NULL and size is 0 (as a no-op), instead of producing "undefined behavior" as per the C spec.
static FLSlice	FLStr (const char *FL_NULLABLE str)
	Returns a slice pointing to the contents of a C string.
FLEECE_PUBLIC bool	FLSlice_Equal (FLSlice a, FLSlice b) FLPURE
	Equality test of two slices.
FLEECE_PUBLIC int	FLSlice_Compare (FLSlice, FLSlice) FLPURE
	Lexicographic comparison of two slices; basically like memcmp(), but taking into account differences in length.
FLEECE_PUBLIC uint32_t	FLSlice_Hash (FLSlice s) FLPURE
	Computes a 32-bit hash of a slice's data, suitable for use in hash tables.
FLEECE_PUBLIC bool	FLSlice_ToCString (FLSlice s, char *buffer, size_t capacity)
	Copies a slice to a buffer, adding a trailing zero byte to make it a valid C string.
FLEECE_PUBLIC FLSliceResult	FLSliceResult_New (size_t)
	Allocates an FLSliceResult of the given size, without initializing the buffer.
FLEECE_PUBLIC FLSliceResult	FLSlice_Copy (FLSlice)
	Allocates an FLSliceResult, copying the given slice.
static FLSliceResult	FLSliceResult_CreateWith (const void *FL_NULLABLE bytes, size_t size)
	Allocates an FLSliceResult, copying size bytes starting at buf.
FLEECE_PUBLIC void	_FLBuf_Retain (const void *FL_NULLABLE)
FLEECE_PUBLIC void	_FLBuf_Release (const void *FL_NULLABLE)
static FLSliceResult	FLSliceResult_Retain (FLSliceResult s)
	Increments the ref-count of a FLSliceResult.
static void	FLSliceResult_Release (FLSliceResult s)
	Decrements the ref-count of a FLSliceResult, freeing its memory if it reached zero.
static FLSlice	FLSliceResult_AsSlice (FLSliceResult sr)
	Type-casts a FLSliceResult to FLSlice, since C doesn't know it's a subclass.
FLEECE_PUBLIC void	FL_WipeMemory (void *dst, size_t size)
	Writes zeroes to size bytes of memory starting at dst.

Detailed Description

Macro Definition Documentation

FLSTR

#define FLSTR

(

STR

)

((FLSlice){("" STR), sizeof(("" STR))-1})

Macro version of FLStr, for use in initializing compile-time constants.

STR must be a C string literal. Has zero runtime overhead.

kFLSliceNull

#define kFLSliceNull   ((FLSlice){NULL, 0})

A convenient constant denoting a null slice.

Typedef Documentation

FLHeapSlice

typedef FLSlice FLHeapSlice

A heap-allocated, reference-counted slice.

This type is really just a hint in an API that the data can be retained instead of copied, by assigning it to an alloc_slice. You can just treat it like FLSlice.

FLString

typedef FLSlice FLString

FLStringResult

typedef FLSliceResult FLStringResult

Function Documentation

_FLBuf_Release()

FLEECE_PUBLIC void _FLBuf_Release

(

const void *

FL_NULLABLE

)

_FLBuf_Retain()

FLEECE_PUBLIC void _FLBuf_Retain

(

const void *

FL_NULLABLE

)

FL_WipeMemory()

FLEECE_PUBLIC void FL_WipeMemory	(	void *	dst,
		size_t	size )

Writes zeroes to size bytes of memory starting at dst.

Unlike a call to memset, these writes cannot be optimized away by the compiler. This is useful for securely removing traces of passwords or encryption keys.

FLMemCmp()

static FLPURE int FLMemCmp ( const void *FL_NULLABLE a, const void *FL_NULLABLE b, size_t size )

inlinestatic

Exactly like memcmp, but safely handles the case where a or b is NULL and size is 0 (by returning 0), instead of producing "undefined behavior" as per the C spec.

FLMemCpy()

static void FLMemCpy ( void *FL_NULLABLE dst, const void *FL_NULLABLE src, size_t size )

inlinestatic

Exactly like memcmp, but safely handles the case where dst or src is NULL and size is 0 (as a no-op), instead of producing "undefined behavior" as per the C spec.

FLSlice_Compare()

FLEECE_PUBLIC int FLSlice_Compare	(	FLSlice	,
		FLSlice	)

Lexicographic comparison of two slices; basically like memcmp(), but taking into account differences in length.

FLSlice_Copy()

FLEECE_PUBLIC FLSliceResult FLSlice_Copy

(

FLSlice

)

Allocates an FLSliceResult, copying the given slice.

FLSlice_Equal()

FLEECE_PUBLIC bool FLSlice_Equal	(	FLSlice	a,
		FLSlice	b )

Equality test of two slices.

FLSlice_Hash()

FLEECE_PUBLIC uint32_t FLSlice_Hash

(

FLSlice

s

)

Computes a 32-bit hash of a slice's data, suitable for use in hash tables.

FLSlice_ToCString()

FLEECE_PUBLIC bool FLSlice_ToCString	(	FLSlice	s,
		char *	buffer,
		size_t	capacity )

Copies a slice to a buffer, adding a trailing zero byte to make it a valid C string.

If there is not enough capacity the slice will be truncated, but the trailing zero byte is always written.

Parameters

s	The FLSlice to copy.
buffer	Where to copy the bytes. At least capacity bytes must be available.
capacity	The maximum number of bytes to copy (including the trailing 0.)

Returns

True if the entire slice was copied, false if it was truncated.

FLSliceResult_AsSlice()

static FLSlice FLSliceResult_AsSlice ( FLSliceResult sr )

inlinestatic

Type-casts a FLSliceResult to FLSlice, since C doesn't know it's a subclass.

FLSliceResult_CreateWith()

static FLSliceResult FLSliceResult_CreateWith ( const void *FL_NULLABLE bytes, size_t size )

inlinestatic

Allocates an FLSliceResult, copying size bytes starting at buf.

FLSliceResult_New()

FLEECE_PUBLIC FLSliceResult FLSliceResult_New

(

size_t

)

Allocates an FLSliceResult of the given size, without initializing the buffer.

FLSliceResult_Release()

static void FLSliceResult_Release ( FLSliceResult s )

inlinestatic

Decrements the ref-count of a FLSliceResult, freeing its memory if it reached zero.

FLSliceResult_Retain()

static FLSliceResult FLSliceResult_Retain ( FLSliceResult s )

inlinestatic

Increments the ref-count of a FLSliceResult.

FLStr()

static FLSlice FLStr ( const char *FL_NULLABLE str )

inlinestatic

Returns a slice pointing to the contents of a C string.

It's OK to pass NULL; this returns an empty slice.

Note

If the string is a literal, it's more efficient to use FLSTR instead.

Performance is O(n) with the length of the string, since it has to call strlen.