Couchbase Lite C
Couchbase Lite C API
Data Structures | Macros | Typedefs | Functions
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. More...
 
#define FLSTR(STR)   ((FLSlice){("" STR), sizeof(("" STR))-1})
 Macro version of FLStr, for use in initializing compile-time constants. More...
 

Typedefs

typedef FLSlice FLHeapSlice
 A heap-allocated, reference-counted slice. More...
 
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. More...
 
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. More...
 
static FLSlice FLStr (const char *FL_NULLABLE str)
 Returns a slice pointing to the contents of a C string. More...
 
FLEECE_PUBLIC bool FLSlice_Equal (FLSlice a, FLSlice b) FLPURE
 Equality test of two slices. More...
 
FLEECE_PUBLIC int FLSlice_Compare (FLSlice, FLSlice) FLPURE
 Lexicographic comparison of two slices; basically like memcmp(), but taking into account differences in length. More...
 
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. More...
 
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. More...
 
FLEECE_PUBLIC FLSliceResult FLSliceResult_New (size_t)
 Allocates an FLSliceResult of the given size, without initializing the buffer. More...
 
FLEECE_PUBLIC FLSliceResult FLSlice_Copy (FLSlice)
 Allocates an FLSliceResult, copying the given slice. More...
 
static FLSliceResult FLSliceResult_CreateWith (const void *FL_NULLABLE bytes, size_t size)
 Allocates an FLSliceResult, copying size bytes starting at buf. More...
 
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. More...
 
static void FLSliceResult_Release (FLSliceResult s)
 Decrements the ref-count of a FLSliceResult, freeing its memory if it reached zero. More...
 
static FLSlice FLSliceResult_AsSlice (FLSliceResult sr)
 Type-casts a FLSliceResult to FLSlice, since C doesn't know it's a subclass. More...
 
FLEECE_PUBLIC void FL_WipeMemory (void *dst, size_t size)
 Writes zeroes to size bytes of memory starting at dst. More...
 

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

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

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
sThe FLSlice to copy.
bufferWhere to copy the bytes. At least capacity bytes must be available.
capacityThe 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.